Add local ApiLink registry snapshots

.gitattributes

@@ -0,0 +1,2 @@
+*.md  text eol=lf
+*.mdx text eol=lf

.github/CONTRIBUTING.md

@@ -8,9 +8,11 @@
  ### 7. [Sample / Code View Configuration](#code-view-configuration)
  ### 8. [PlatformBlock usage](#platform-block)
  ### 9. [ApiLink usage](#api-link)
- ### 10. [Creating shared help topics](#creating-shared-help-topics)
- ### 11. [Updating of Data Visualization related topics](#updating-of-data-visualization-related-topics)
- ### 12. [Adding of images](#adding-of-images-in-the-topic)
+ ### 10. [Checking MDX API Links](#checking-api-links)
+ ### 11. [ApiLink registry workflow](#api-link-registry-workflow)
+ ### 12. [Creating shared help topics](#creating-shared-help-topics)
+ ### 13. [Updating of Data Visualization related topics](#updating-of-data-visualization-related-topics)
+ ### 14. [Adding of images](#adding-of-images-in-the-topic)
 
 # <a name='#repository-overview'>Repository overview</a>
 
@@ -251,7 +253,7 @@ Usage:
 | `height` | no | `400` | Height of the sample widget in pixels (numeric JSX expression, e.g. `{600}`). |
 | `alt` | no | `""` | Accessible label for the iframe. Use the `{Platform}` token so it resolves per-platform. |
 | `lob` | no | `false` | Use `lobDemosBaseUrl` as the base URL (for LOB / grid-dynamic demos). |
-| `dv` | no | `false` | Force `dvDemosBaseUrl` for samples whose path does not start with a recognised DV prefix. |
+| `dv` | no | `false` | Force `dvDemosBaseUrl` for samples whose path does not start with a recognized DV prefix. |
 | `crm` | no | `false` | Use `crmDemoBaseUrl` (for CRM demo samples). |
 | `iframeOnly` | no | `false` | Render only the iframe — hides the navbar, code tabs, and live-edit footer. |
 | `fullscreenBtn` | no | `false` | When used together with `iframeOnly={true}`, adds an "Open in full screen" button below the iframe. |
@@ -312,30 +314,131 @@ import ApiLink from 'igniteui-astro-components/components/mdx/ApiLink.astro';
 Basic syntax:
 
 ```mdx
-<ApiLink pkg="grids" type="Grid" />
-<ApiLink pkg="grids" type="Column" member="sortable" />
+<ApiLink type="Grid" />
+<ApiLink type="Column" member="sortable" />
 <ApiLink pkg="gauges" type="BulletGraph" label="Bullet Graph" />
 ```
 
 Key attributes:
 
 | Attribute | Required | Notes |
 |---|---|---|
-| `pkg` | yes | Package key: `"grids"`, `"core"`, `"charts"`, `"gauges"`, `"excel"`, etc. |
+| `pkg` | no | Package key such as `"core"`, `"grids"`, `"charts"`, `"inputs"`, `"excel"`, or `"geo-core"`. Add it only when the registry has multiple valid matches and the package must be explicit. |
 | `type` | yes | Short type name **without** platform prefix — e.g. `"Grid"`, not `"IgrGrid"`. |
-| `kind` | for non-classes | TypeDoc kind: omit for classes. Use `"enum"`, `"interface"`, or `"typeAlias"` otherwise. |
+| `kind` | for non-classes | API kind. Omit for classes. Use `"enum"`, `"interface"`, `"type"`, `"function"`, or `"variable"` when the registry symbol is not a class. |
 | `member` | no | Property or method name for anchor links. |
 | `prefixed` | no | Default `true` (adds `Igr`/`Igx`/`Igc`/`Igb`). Set `{false}` for excel types and when `type` already contains `{ComponentName}`. |
-| `exclude` | no | Comma-separated platforms to show as inline code instead of a link (e.g. `exclude="Blazor"`). Use when the type does not exist on those platforms. |
+| `suffix` | no | Default `true` for component-style symbols. Set `{false}` for utility classes, strategy classes, and excel types that do not have an Angular `Component` suffix. |
 | `label` | no | Override the display text. |
 
+`ApiLink` resolves through the generated API symbol registry. Keep links minimal when the registry can resolve a single target:
+
+```mdx
+<ApiLink type="Calendar" />
+<ApiLink type="Grid" member="filter" />
+```
+
+Add `pkg` only when the same symbol exists in more than one package:
+
+```mdx
+<ApiLink pkg="core" type="Calendar" />
+<ApiLink pkg="inputs" type="CheckboxChangeEventArgs" />
+<ApiLink pkg="geo-core" type="NumberFormatSpecifier" />
+```
+
+Add `kind` only when the intended symbol is not a class, or when the same name exists as multiple API kinds:
+
+```mdx
+<ApiLink kind="enum" type="TransactionType" />
+```
+
+If one `ApiLink` cannot be correct for all platforms, split the content with `PlatformBlock` instead of forcing one set of props to mean different targets.
+
+Member lookup is case-insensitive, but after a member is found the registry is the source of truth for the rendered member name and anchor.
+
 Also declare the types in the frontmatter so the auto-generated API reference grid works:
 
 ```yaml
 mentionedTypes: ["Grid", "Column"]
 ```
 
-For a complete reference see [AI-AGENT-API-LINKS.md](../docs/xplat/AI-AGENT-API-LINKS.md).
+For a complete editing reference see [AI-AGENT-API-LINKS.md](../docs/xplat/AI-AGENT-API-LINKS.md). For the registry and checker flow, see [API-LINK-WORKFLOW.md](../API-LINK-WORKFLOW.md).
+
+# <a name='#checking-api-links'>Checking MDX API Links</a>
+
+Use the root `check-mdx-links` scripts to validate `ApiLink` references:
+
+| Scope | Command |
+|---|---|
+| All MDX sources | `npm run check-mdx-links` |
+| Angular docs | `npm run check-mdx-links:angular` |
+| React xplat docs | `npm run check-mdx-links:react` |
+| Web Components xplat docs | `npm run check-mdx-links:wc` |
+| Blazor xplat docs | `npm run check-mdx-links:blazor` |
+| Markdown reports | `npm run check-mdx-links:report:<platform>` |
+| Resolve-only broken-link reports | `npm run check-mdx-links:broken:<platform>` |
+
+These scripts also check for ambiguous `ApiLink` references. If a symbol exists in more than one registry package and the link does not specify enough information to choose safely, the script prints an **Ambiguous ApiLinks** section, writes a `reports/api-link-ambiguity-report*.md` file, and exits with a failure.
+
+Fix ambiguous links by adding a specific `pkg` or `kind` prop. If the correct target differs by platform, wrap platform-specific links in `PlatformBlock`.
+
+Angular checks run the same generated-content sync used by Angular builds before scanning `docs/angular/src/content`. React, Web Components, and Blazor checks generate the selected platform output first, then scan raw xplat MDX files filtered through each language `toc.json` platform exclusions. This keeps report paths pointed at raw xplat source files while avoiding topics excluded from that platform.
+
+Reports are written under `reports/`:
+
+| Report | Meaning |
+|---|---|
+| `api-link-ambiguity-report*.md` | Registry duplicate keys and currently referenced ambiguous `ApiLink`s. |
+| `mdx-broken-links*.md` | Resolve-only broken or unresolved `ApiLink`s. |
+| `mdx-link-report*.md` | Full URL check output when the non-broken report scripts are used. |
+
+Referenced ambiguities should be fixed before merging. Registry duplicate keys can remain in the report when no current MDX link references them.
+
+# <a name='#api-link-registry-workflow'>ApiLink registry workflow</a>
+
+The API registry flow is:
+
+```mermaid
+flowchart TD
+    A[api-docs] --> B[Generate API docs]
+    B --> C[Generate API registry JSON]
+    C --> D[Sync into igniteui-documentation]
+    D --> E[ApiLink resolves type/member from registry]
+    E --> F{Resolved?}
+
+    F -->|Yes| G[Render API link]
+    G --> H[Link checker crawls URL]
+    H --> I[Reported if unreachable / soft 404]
+
+    F -->|No| J[Render highlighted text only]
+    J --> K[Reported as unresolved]
+```
+
+The checker also detects duplicate registry matches:
+
+```mermaid
+flowchart TD
+    A[MDX ApiLink] --> B[Resolve candidate names]
+    B --> C[Apply platform prefix/suffix rules]
+    C --> D[Apply pkg and kind filters]
+    D --> E[Match type in registry]
+    E --> F[Match member case-insensitively]
+    F --> G{How many registry symbols match?}
+
+    G -->|0| H[Unresolved ApiLink]
+    G -->|1| I[Resolved ApiLink]
+    G -->|2 or more| J[Ambiguous ApiLink]
+
+    H --> K[Write broken report]
+    I --> L[Use canonical registry symbol and member]
+    J --> M[Write ambiguity report and fail when enabled]
+```
+
+Registry snapshots live under `src/data/api-link-index/<platform>/staging-latest.json`. The runtime `ApiLink` component and the checker both use these registries to choose the final URL.
+
+Only referenced ambiguities are blocking. Duplicate registry keys listed in the report are informational until an MDX file references them without enough props to choose the intended symbol.
+
+For the full workflow, package mappings, generated-content behavior, and practical fix loop, see [API-LINK-WORKFLOW.md](../API-LINK-WORKFLOW.md).
 
 # <a name='#creating-shared-help-topics'>Creating shared help topics</a>
 
@@ -369,4 +472,4 @@ Usage:
 - Use the `@xplat-images` alias which resolves to `docs/xplat/public/images/`.
 - Always provide a meaningful `alt` attribute.
 - Use `{Platform}` in the `alt` text when the image is platform-generic (e.g. `alt="{Platform} Grid Overview"`).
-- Responsive sizing and lazy loading are handled automatically by Astro — no extra classes or `data-srcset` attributes are needed.
+- Responsive sizing and lazy loading are handled automatically by Astro — no extra classes or `data-srcset` attributes are needed.

API-LINK-WORKFLOW.md

@@ -0,0 +1,191 @@
+# ApiLink Registry Workflow
+
+This document explains the current `ApiLink` flow from API documentation generation to MDX validation. The short version: the API registry is the source of truth for symbol URLs, member casing, package selection, and ambiguity detection.
+
+## End-to-End Flow
+
+```mermaid
+flowchart TD
+    A[api-docs] --> B[Generate API docs]
+    B --> C[Generate API registry JSON]
+    C --> D[Sync into igniteui-documentation]
+    D --> E[ApiLink resolves type/member from registry]
+    E --> F{Resolved?}
+
+    F -->|Yes| G[Render API link]
+    G --> H[Link checker crawls URL]
+    H --> I[Reported if unreachable / soft 404]
+
+    F -->|No| J[Render highlighted text only]
+    J --> K[Reported as unresolved]
+```
+
+The checker adds one more branch for duplicate registry matches:
+
+```mermaid
+flowchart TD
+    A[MDX ApiLink] --> B[Resolve candidate names]
+    B --> C[Apply platform prefix/suffix rules]
+    C --> D[Apply pkg and kind filters]
+    D --> E[Match type in registry]
+    E --> F[Match member case-insensitively]
+    F --> G{How many registry symbols match?}
+
+    G -->|0| H[Unresolved ApiLink]
+    G -->|1| I[Resolved ApiLink]
+    G -->|2 or more| J[Ambiguous ApiLink]
+
+    H --> K[Write broken report]
+    I --> L[Use canonical registry symbol and member]
+    J --> M[Write ambiguity report and fail when enabled]
+```
+
+## Source Repositories
+
+`api-docs` owns the API documentation generation. It produces the API docs and the registry JSON snapshots.
+
+`igniteui-documentation` stores registry snapshots under:
+
+```text
+src/data/api-link-index/
+  angular/staging-latest.json
+  react/staging-latest.json
+  webcomponents/staging-latest.json
+  blazor/staging-latest.json
+  manifest.json
+```
+
+`igniteui-astro-components` owns the runtime `ApiLink` component and registry lookup code used by MDX rendering.
+
+## Registry Contract
+
+Each registry entry describes a symbol:
+
+| Field | Meaning |
+|---|---|
+| `p` | Package id, such as `igniteui-react-inputs` or `IgniteUI.Blazor`. |
+| `k` | API kind, such as `class`, `interface`, `enum`, or `type`. |
+| `u` | URL path for the symbol. |
+| `m` | Member map for anchors. |
+
+The registry can contain duplicate symbol keys when more than one package or kind has the same public name. This is expected. It becomes a docs problem only when an MDX `ApiLink` references the duplicate name without enough props to choose one symbol.
+
+## ApiLink Resolution Rules
+
+Resolution is platform-aware:
+
+- Angular tries Angular naming conventions first, such as `Calendar` -> `IgxCalendarComponent`.
+- React, Web Components, and Blazor apply their platform prefixes and package mappings.
+- Member matching is case-insensitive, but the resolved member name and anchor come from the registry.
+- `pkg` filters the candidate symbols by package id.
+- `kind` filters the candidate symbols by API kind.
+
+The registry is the source of truth after a symbol is found. For example, if MDX uses a member with different casing, the rendered link uses the canonical registry member and anchor.
+
+## When to Add Props
+
+Keep links minimal when the registry resolves one symbol:
+
+```mdx
+<ApiLink type="Calendar" />
+<ApiLink type="Grid" member="filter" />
+```
+
+Add `pkg` when the same symbol exists in more than one package and the package changes the target:
+
+```mdx
+<ApiLink pkg="core" type="Calendar" />
+<ApiLink pkg="inputs" type="CheckboxChangeEventArgs" />
+<ApiLink pkg="geo-core" type="NumberFormatSpecifier" />
+```
+
+Add `kind` when the same symbol name exists as a non-class type, or when the intended symbol is not a class:
+
+```mdx
+<ApiLink kind="enum" type="TransactionType" />
+```
+
+Use `PlatformBlock` when the correct package or symbol differs by platform:
+
+```mdx
+<PlatformBlock for="React">
+<ApiLink pkg="inputs" type="CheckboxChangeEventArgs" />
+</PlatformBlock>
+
+<PlatformBlock for="Blazor">
+<ApiLink pkg="core" type="CheckboxChangeEventArgs" />
+</PlatformBlock>
+```
+
+## Checker Commands
+
+The root `check-mdx-links` scripts include ambiguity reporting:
+
+| Command | What it checks |
+|---|---|
+| `npm run check-mdx-links:angular` | Angular content after xplat Angular sync. |
+| `npm run check-mdx-links:react` | Raw xplat content for React, filtered by TOC exclusions. |
+| `npm run check-mdx-links:wc` | Raw xplat content for Web Components, filtered by TOC exclusions. |
+| `npm run check-mdx-links:blazor` | Raw xplat content for Blazor, filtered by TOC exclusions. |
+| `npm run check-mdx-links:broken:<platform>` | Resolve-only report for broken, unresolved, and ambiguous `ApiLink`s. |
+| `npm run check-mdx-links:report:<platform>` | Markdown report for URL checks plus ambiguity report. |
+
+The package scripts pass these flags to `scripts/check-mdx-links.mjs`:
+
+```text
+--list-ambiguities
+--ambiguity-md=reports/api-link-ambiguity-report-<platform>.md
+--fail-on-ambiguity
+```
+
+Use `--no-sync` only for a quick local resolver check when generated content is already current.
+
+## Platform Generation Before Checking
+
+Angular:
+
+```text
+npm run sync:generated-from-xplat --prefix docs/angular
+npm run sync:generated-from-xplat:jp --prefix docs/angular
+scan docs/angular/src/content
+```
+
+React, Web Components, and Blazor:
+
+```text
+npm run generate:<platform> --prefix docs/xplat
+npm run generate:<platform>:jp --prefix docs/xplat
+scan docs/xplat/src/content with toc.json exclusions
+```
+
+This keeps reported file paths on the raw xplat MDX files while still respecting platform-specific excluded topics.
+
+## Reports
+
+Ambiguity reports are written to:
+
+```text
+reports/api-link-ambiguity-report.md
+reports/api-link-ambiguity-report-angular.md
+reports/api-link-ambiguity-report-react.md
+reports/api-link-ambiguity-report-wc.md
+reports/api-link-ambiguity-report-blazor.md
+```
+
+The report has two useful sections:
+
+- Referenced ambiguous `ApiLink`s: current MDX links that must be fixed.
+- All registry duplicate symbol keys: duplicate registry names that may or may not be referenced.
+
+Only referenced ambiguities are blockers. Duplicate registry keys are informational until MDX links to them without enough props.
+
+## Practical Fix Loop
+
+1. Run the platform check.
+2. Open the ambiguity report.
+3. For each referenced ambiguity, compare the candidate packages and kinds.
+4. Add the smallest correct disambiguation: usually `pkg`, sometimes `kind`.
+5. Use `PlatformBlock` only when one MDX line cannot be correct for all platforms.
+6. Re-run the same check until `Ambiguous ApiLinks` says `None`.
+
+For Angular `Calendar`, no `pkg` is needed in normal Angular docs because `Calendar` resolves through Angular naming conventions to `IgxCalendarComponent` before considering the duplicate raw `Calendar` registry key.