[ChronosSF]

No description provided.

[ChronosSF]

Cross-platform topic map: report

This is the analysis behind the proposed full topic map for the platform switcher (343 entries), pushed to this branch in fe5fbb8.

Proposed src/data/platform-topic-map.json for the DocsSubHeader platform switcher. It is built from IgniteUI/igniteui-documentation at origin/vnext 697e3b5 (2026-10-23, PR #903 "update-chip-topic"). origin/vnext was 8e30265 when the work started; #903 moved the Angular Chip topic from chip to the shared inputs/chip. Every output was regenerated at 697e3b5.

Entries	343
Identical slug on every platform in the entry	163
Divergent (at least one slug differs)	180
Slugs mapped per site	Angular 314 / React 337 / Web Components 341 / Blazor 316
Needs review (not in the map)	8
Title look-alikes checked and rejected	15
Validator	0 errors; 1 jp broken link (Angular inputs/chip); 4 deliberate coverage overrides
Seed (4 entries + NOTE)	Kept verbatim; all four confirmed correct

1. Method

1.1 Real slug sets

A page's slug is its Astro content-collection id. Every step that decides which pages exist was re-implemented and run over sources extracted from git objects (git cat-file, no checkout). None of the repo's scripts were run.

xplat (React, Web Components, Blazor) — docs/xplat/scripts/generate.mjs:

• processDir emits every .md/.mdx file under src/content/{lang}/components/ to the same relative path. It skips any _shared folder.
• A file is skipped if the TOC excludes it, as decided by collectExcludedSlugs / collectIncludedSlugs with emitsFor() from src/lib/platform-groups.ts:
  • include wins, then exclude; group aliases (Web, NonWeb, Xaml) are expanded.
  • An excluded parent excludes its whole subtree.
  • A slug reachable through any non-excluded path is kept.
  • A file with no TOC node is emitted on every platform.
• expandSharedFiles turns each grids/_shared/*.mdx into grids/{grid,hierarchical-grid,tree-grid,pivot-grid}/<name>.mdx. It is filtered by sharedComponents and by TOC exclusion, and it overwrites a regular file at the same path.

Angular — the build runs sync:generated-from-xplat, then generate:

1. Start from the committed .mdx files under docs/angular/src/content/{lang}/components/.
2. sync-generated.mjs copies the xplat output generated for Angular (--platform=Angular) over them, except anything under grids/ or changelog/. So every xplat page the xplat TOC does not exclude for Angular becomes an Angular page with the same slug.
3. generate-grids.mjs then writes grids_templates/*.mdx × the 4 GRID_CONFIGS to {grid,treegrid,hierarchicalgrid,pivotgrid}/<name>.mdx. It only writes a page when the result still starts with frontmatter after ComponentBlock filtering.

Content collection — src/content-helper.ts, both content.config.ts files, and the Astro 7.3 glob loader:

• Pattern **/*.{md,mdx}, minus **/_* and the root README/CHANGELOG/LICENSE files.
• Angular also excludes **/*.md.
• Entries without a title are dropped.
• The id is github-slugger applied to each path segment, with a trailing /index removed. So themes/index.mdx → themes, and themes/sass/index.mdx → themes/sass.
• No file overrides this with a slug: frontmatter field.

Cross-check:

• The computed React/WC/Blazor sets (en and jp) and the computed en Angular sync set match the local docs/xplat/generated/* file-for-file.
• The local jp Angular tree is older (2026-10-01) and lacks 2 files: inputs/checkbox, layouts/card.
• Angular grid page counts match the local tree: 47 / 45 / 42 / 19.

1.2 Pairing

1. Identical slugs. 339 slugs exist on two or more en sites.
   • In 322 of them, every copy comes from one source file, so they are the same topic by construction.
   • In 17, Angular has its own file with the same slug. Each was checked on title, H1, H2s, ApiLink types and samples, and all 17 are the same topic: ai/* ×5, grid-lite/* ×8, themes/elevations|palettes|typography, and general-cli-overview.
   • For general-cli-overview a better Angular page exists (section 3.4).
2. Grid features, by rule.
   • Angular grids_templates/X and xplat grids/_shared/X are the same feature template. So {grid|treegrid|hierarchicalgrid|pivotgrid}/X ↔ grids/{grid|tree-grid|hierarchical-grid|pivot-grid}/X.
   • The H1s were checked with platform and grid names stripped. 25 differ only in wording ("Clipboard Interactions" vs "Clipboard Overview", "Export to Excel and PDF Service" vs "Exporting").
   • One rename: display-density → size. Both are titled "Grid Size" and use the same displayDensity sample.
3. Curated divergent relations (candidates.mjs).
   • Each has an evidence line from ev.mjs and was confirmed by reading the pages.
   • Signals used: frontmatter, H1/H2, ApiLink, sample paths, TOC names and position, cross-links, docConfig/docComponents tokens, and the 145 rules in web.config.
   • The web.config rules confirm the Angular themes reorganisation and the framework-and-features → data-analysis / ssr-rendering / right-to-left-support moves.
4. Assembly (pairs.mjs).
   • There is one entry per xplat topic.
   • A curated or grid relation sets the Angular slug; otherwise the identical Angular slug is used.
   • When both exist, the relation wins because it points to Angular's sidebar page (4 cases, section 3.4).

2. Slug counts

Site	en pages	en without TOC entry	jp pages	jp without TOC entry
Angular	420	36	424 (423 distinct ids, see 7.8)	40
React	338	34	321	17
Web Components	344	34	327	17
Blazor	322	34	305	17

Pages that exist only because of generation (en):

• Angular: only 158 of the 420 pages are committed files.
  • 122 come from the xplat sync: charts, maps, gauges, excel/spreadsheet, inputs/*, layouts/*, and others.
  • 140 come from the grid templates: grid/ 47 (including 5 committed), treegrid/ 45, hierarchicalgrid/ 42, pivotgrid/ 19.
• xplat: every page is generated. 116 React pages and 120 WC/Blazor pages are _shared expansions with no 1:1 source file.
• Per-site lists, with origin and TOC flag: data/slugs-{en,jp}-{Platform}.tsv.

jp vs en:

• React/WC/Blazor jp lack the 17 changelog/* pages; nothing else differs.
• Angular jp lacks inputs/chip.
• Angular jp has extra pages: its own chip and card (both in the jp TOC; en uses layouts/card), plus the untocced button-group and charts/features/chart-legends.

3. Relation families

Family	Entries	Examples
identical	163	charts/types/area-chart, geo-map-*, inputs/badge, layouts/card, ai/skills, grid-lite/overview, themes/palettes
grid-feature	120	grid/sorting ↔ grids/grid/sorting; grid/master-detail ↔ grids/grid/master-detail; treegrid/load-on-demand ↔ grids/tree-grid/load-on-demand (WC only)
component-section	28	banner ↔ notifications/banner; calendar ↔ scheduling/calendar; list ↔ grids/list; icon ↔ layouts/icon
general	8	general/getting-started ↔ general-getting-started; general/update-guide ↔ update-guide (React only)
component-renamed	7	navdrawer ↔ menus/navigation-drawer; texthighlight ↔ inputs/highlight; input-group ↔ inputs/input
grid-overview	6	grid/grid ↔ grids/data-grid; grids-and-lists ↔ grids/grids-header; treegrid/tree-grid ↔ grids/tree-grid/overview
grid-renamed	4	{grid,treegrid,hierarchicalgrid}/display-density ↔ grids/*/size; pivotgrid/pivot-grid-custom ↔ grids/pivot-grid/remote-operations (WC)
combo	4	combo ↔ inputs/combo/overview; simple-combo ↔ inputs/combo/single-selection
themes	2	themes (index) ↔ themes/overview; themes/misc/tailwind-classes ↔ themes/tailwind
changelog (xplat↔xplat)	1	general-changelog-dv ↔ general-changelog-dv-react / -wc / -blazor

3.1 Identical slugs (163)

They split by platforms covered: 113 entries cover A R W B, 21 cover A R W, and 29 cover R W B only.

• Same source synced to Angular:
  • charts (46), geo-map-*, maps/map-api, gauges, dashboard tile, zoomslider, excel library, spreadsheet (no Blazor)
  • inputs/{badge,button,button-group,checkbox,chip,switch,color-picker,qr-code,color-editor}
  • layouts/{accordion,avatar,card,carousel,breadcrumbs,virtual-scroll}
  • menus/toolbar, interactivity/accessibility-compliance, themes/accessibility
• Angular's own file, same slug and subject: ai/*, grid-lite/*, themes/{elevations,palettes,typography}.
• xplat only:
  • inputs/text-area, layouts/dock-manager-{embedding-frames,updating-panes}, themes/configuration, themes/styles, grids/grid/icons
  • the untocced grids/*/theming-grid pages and changelog/* ×17

3.2 Non-obvious relations

• CLI getting started. xplat general-cli-overview ↔ Angular general/cli/getting-started-with-cli: identical H2 list (Install / Create / Add Template / Run / AI-MCP / Commands) and the same description. By TOC position the match would be general/cli-overview, but that is a two-tool overview.
• Pivot remote operations. pivotgrid/pivot-grid-custom ↔ WC grids/pivot-grid/remote-operations. Same title ("Pivot Grid Custom Remote"), same H1 ("Remote Operations"), same noop sample.
• Grids landing page. grids-and-lists ↔ grids/grids-header: both titled "The Fastest X Grid", with the same section list.
• Grid overviews.
  • grid/grid ↔ grids/data-grid; web has no grids/grid/overview.
  • The other grids pair with .../overview.
  • pivotgrid/pivot-grid-features ↔ grids/pivot-grid/features (React and Blazor only).
• Directive vs component. mask ↔ inputs/mask-input, date-time-editor ↔ inputs/date-time-input, texthighlight ↔ inputs/highlight. input-group ↔ inputs/input (both have label, prefix/suffix and hint/helper).
• Moved to another section.
  • list and tree → grids/
  • icon → layouts/
  • chat → interactivity/
  • dialog, toast, snackbar, banner → notifications/
  • calendar and the date pickers → scheduling/
• Per-platform changelogs:
  • Angular general-changelog-dv (Angular-only xplat source; the Angular TOC calls it "Data Visualization Changelog")
  • general-changelog-dv-react, -wc, -blazor

3.3 Grid rule coverage

• 147 Angular grid-variant pages were checked; 123 have an xplat page and are mapped.
• The 24 without one:
  • {grid,treegrid,hierarchicalgrid,pivotgrid}/theming (see 4.1)
  • treegrid/groupby, treegrid/remote-data-operations, hierarchicalgrid/{keyboard-navigation,paging}, pivotgrid/export-excel
  • 15 untocced template pages (7.3)
• Tree-grid column-moving, excel-style-filtering, keyboard-navigation and live-data exist only on WC and Blazor, and load-on-demand only on WC. Their entries carry only those keys.

3.4 Identical slugs deliberately not used (the validator's 4 coverage warnings)

xplat slug	Angular slug used	Angular duplicate left unmapped
layouts/icon	icon	layouts/icon (untocced sync)
inputs/icon-button	icon-button	inputs/icon-button (untocced sync)
themes/tailwind	themes/misc/tailwind-classes	themes/tailwind (untocced sync)
general-cli-overview	general/cli/getting-started-with-cli	general-cli-overview (committed older copy)

4. Needs review (8, not in the map)

#	Candidate	For	Against
4.1	A grid/theming ↔ RWB grids/grid/theming-grid (also the treegrid and hierarchicalgrid pairs)	Same subject; same feature name	The xplat pages are untocced and absent from _shared. They are short dark-sample "Available Theming Properties" pages, while Angular has a full grid-theme() guide. Title 0.29, H2 0.09. The xplat grid "Theming" TOC link is NonWeb-only.
4.2	A general/cli-overview ↔ RWB general-cli-overview	Same TOC position (the CLI parent of the step-by-step guide)	Content matches general/cli/getting-started-with-cli instead (mapped); H2 overlap 0.11
4.3	A label-input ↔ RWB inputs/input	It is Angular's plain input	input-group is the closer match (prefix/suffix, hint), and an xplat slug can be in only one entry
4.4	A themes/roundness (+ themes/spacing, display-density) ↔ RWB themes/configuration	The xplat page has Roundness / Elevation / Size / Spacing sections	One merged xplat page vs 4 Angular pages; elevations already pair by identical slug
4.5	A themes/sass/component-themes ↔ RWB themes/styles	Both cover restyling a component	Sass functions and scoping vs CSS parts and variables; H2 overlap 0
4.6	A icon-service ↔ RWB grids/grid/icons	Both cover replacing internal icons with setIconRef; API overlap 0.50	General registry service vs a grid-specific page
4.7	A general/ssr-rendering ↔ R nextjs-usage	Both are SSR integration guides	Different frameworks; no section overlap
4.8	RW general-licensing ↔ B general-nuget-feed	Blazor has no licensing page; the NuGet feed is its licensed-package route	The licensing page is a licence FAQ (agreements, tokens, CI); the feed page only adds a source

Rejected look-alikes (different subjects; REJECTED in candidates.mjs):

• general/cli/component-templates ≠ inputs/combo/templates
• themes/sass/configuration ≠ themes/configuration
• general/how-to/how-to-customize-theme ≠ themes/configuration
• general/cli/getting-started-with-angular-schematics ≠ general-cli-overview
• themes/sass/{palettes,typography,elevations} ≠ themes/* (the Angular themes/* pages are the counterparts)
• display-density ≠ grids/grid/size
• exporter-excel ≠ grids/grid/export-excel
• for-of ≠ layouts/virtual-scroll
• icon-service ≠ layouts/icon
• combo-remote ≠ inputs/combo/overview
• pie-chart / sparkline (legacy, untocced) ≠ charts/types/*

5. No counterpart (confident)

Angular (106 unmapped):

• Angular-specific guides:
  • general/wpf-to-angular-guide/* (9), angular-reactive-form-validation, general/angular-grid-overview-guide
  • general/code-splitting-…, general/data-analysis, general/how-to/* (4)
  • Angular Schematics pages, CLI auth-template and component-templates
• Directives and services: overlay ×4, transaction ×3, exporters (CSV/Excel/PDF), drag-drop, for-of, toggle, layout, icon-service, material-icons-extended.
• Components with no xplat page: action-strip, autocomplete, month-picker, time-picker, paginator, tabbar, drop-down-virtual, drop-down-hierarchical-selection, combo-remote, query-builder-model.
• Theming: themes/sass/* (14), themes/misc/{angular-material,bootstrap}-theming, printing-styles, themes/roundness, themes/spacing, display-density.
• Grids: */theming, treegrid/{groupby,remote-data-operations}, hierarchicalgrid/{keyboard-navigation,paging}, pivotgrid/export-excel.
• Other: interactivity/right-to-left-support, plus the untocced pages in 7.2–7.4.

Other sites:

• React: nextjs-usage.
• WC: inputs/file-input, layouts/dock-manager-{customization,electron}. Angular dock-manager is a single page already paired with layouts/dock-manager.
• Blazor: getting-started variants (-blazor-client, -web-app, -maui, -oss), general-installing-blazor, general-nuget-feed.

6. jp gaps

• Broken on jp: Angular inputs/chip. jp R/W/B have inputs/chip, but jp Angular has not taken feat(chip): update chip xplat topic #903 and still has its own chip. Switching from the jp xplat Chip page to Angular leads to a missing page. This fixes itself when jp Angular syncs; until then jp Angular chip goes to getting started.
• 51 harmless misses: the 17 changelog/* entries have no jp pages, and no jp page is in them.
• Lost but not broken:
  • jp Angular card (its sidebar page) is unmapped. The layouts/card entry still resolves on jp, because jp Angular has the synced layouts/card (untocced).
  • jp Angular button-group and charts/features/chart-legends are untocced extras.

7. Suspected problems

1. xplat TOC: Blazor how-to pages are built nowhere.
   • The second "How to" node (toc.json ~line 230) excludes Blazor, React and WC, so it is Angular-only, but its children are Blazor-only.
   • As a result blazor-excel-library-temporarily-stop-automatic-calculation-of-formulas-to-speed-up-processing and blazor-webassembly-how-to-read-and-write-excel-files-to-reduce-server-load are emitted on no site.
   • customize-marker-display-in-blazor-charts excludes all four web platforms.
   • The parent's exclude was probably meant to be [Angular, React, WebComponents].
2. The sync publishes untocced Angular duplicates.
   • layouts/icon, inputs/icon-button and themes/tailwind duplicate Angular's own pages; inputs/color-editor is also untocced.
   • Synced pages that are in the R/W/B TOC but not in the Angular TOC (possible omissions): charts/features/chart-titles, excel-library-working-with-grids, geo-map-binding-data-overview, geo-map-display-imagery-types, geo-map-resources-esri, geo-map-type-series.
   • The Angular content .gitignore misses the synced themes/accessibility.mdx and themes/tailwind.mdx.
3. Angular grid templates emit 18 unlinked pages. Template frontmatter that is not wrapped in a ComponentBlock is written for every grid variant.
   • The pages: pivotgrid/* ×13, hierarchicalgrid/{cascading-combos,multi-row-layout,search}, treegrid/{cascading-combos,multi-row-layout}.
   • Their content is boilerplate, e.g. the title "Batch Editing and Transactions in Angular Pivot Grid Grid".
   • 3 of them pair with equally untocced xplat pivot pages (excel-style-filtering, row-editing, validation). They are kept in the map because both sides come from the same template and grid; remove them if the pages are removed.
4. Committed Angular orphans: general-cli-overview, pie-chart, sparkline, general-whats-new-dv, general-breaking-changes-dv, multi-column-combobox, style-guide, slider/slider-ticks. Also, the committed geo-map-binding-data-overview.mdx is overwritten by the sync on every build.
5. xplat pages without TOC entries.
   • changelog/igniteui-* ×17 are built on React, WC and Blazor, including other platforms' package changelogs (e.g. changelog/igniteui-react on Blazor). Nothing links to them, and jp has no copies.
   • Also untocced: grids/*/{batch-editing,validation}, grids/grid/selection-based-aggregates, */theming-grid, hierarchical-grid/clipboard-interactions, pivot-grid/{clipboard-interactions,excel-style-filtering,row-editing,row-selection,validation}, inputs/color-editor.
   • The map pairs 7 Angular TOC pages with these hidden xplat pages: {grid,treegrid,hierarchicalgrid}/{batch-editing,validation} and grid/selection-based-aggregates. Drop those 7 entries if xplat hides the pages on purpose.
6. web.config redirects whose targets are not pages:
   • combo-cascading
   • button-group (now inputs/button-group)
   • hierarchicalgrid/clipboard-interactions
   • hierarchicalgrid/live-data
   • pivotGrid/state-persistence — the id is lowercase, so this works only through case-insensitive matching.
7. Slugs are collection ids, not TOC hrefs. Ids are lowercased and drop /index (Angular themes/index.mdx → themes). The validator rejects uppercase.
8. jp Angular duplicate id: themes.mdx and themes/index.mdx both resolve to themes, so Astro drops one of them.

8. Files

The proposed map is src/data/platform-topic-map.json in fe5fbb8. Its validator (validate.mjs) and the extraction scripts are not in this PR.

---

🤖 Generated with Claude Code