Merge pull request #256 from IgniteUI/vkombov/configure-apilink-index-resolution

Add local ApiLink registry snapshots

Author: viktorkombov

.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.

.github/skills/docfx-sync/SKILL.md

@@ -71,27 +71,24 @@ These look like:
 |---|---|
 | `.../classes/igx{foo}component.html` | `<ApiLink type="Foo" />` |
 | `.../classes/igx{foo}component.html#{member}` | `<ApiLink type="Foo" member="member" />` |
-| `.../classes/igx{foo}directive.html` | `<ApiLink type="FooDirective" suffix={false} />` |
-| `.../interfaces/i{foo}.html` | `<ApiLink kind="interface" type="IFoo" suffix={false} prefixed={false} />` |
+| `.../classes/igx{foo}directive.html` | `<ApiLink type="FooDirective" />` |
+| `.../interfaces/i{foo}.html` | `<ApiLink kind="interface" type="IFoo" />` |
 | `.../enums/igx{foo}.html` | `<ApiLink kind="enum" type="Foo" />` |
-| `.../enums/{foo}.html` (no igx) | `<ApiLink kind="enum" type="Foo" prefixed={false} />` |
-| `.../functions/{foo}.html` | `<ApiLink kind="function" type="foo" prefixed={false} />` |
+| `.../enums/{foo}.html` (no igx) | `<ApiLink kind="enum" type="Foo" />` |
+| `.../functions/{foo}.html` | `<ApiLink kind="function" type="foo" />` |
 
 **Prop reference:**
 
 | Prop | Default | When to override |
 |---|---|---|
 | `type` | required | Short name, no `Igx` prefix — `"Grid"` not `"IgxGrid"` |
 | `kind` | `"class"` | Set `"interface"`, `"enum"`, `"type"`, `"function"`, `"variable"` as appropriate |
-| `suffix` | `true` | `false` for directives, utilities, interfaces (anything that isn't a `Component`) |
-| `prefixed` | `true` | `false` for interfaces (`IFoo`), enums/functions with no `Igx` prefix |
 | `member` | none | Property or method name from the URL anchor |
 | `label` | derived | Only when display text differs from the type name (e.g. `label="igx-grid"` for selector display) |
 | `pkg` | `"core"` | Angular docs **rarely** need this — use `pkg="charts"` for chart types, etc. |
 
-**Important — `suffix={false}` traps:**
-- `InputGroup`, `Checkbox`, `DropDown`, `Overlay`, `List`, `Avatar`, `Icon`, `Badge`, `Button`, `Card` — these commonly appear **without** `Component` suffix in prose. Restore the `suffix={false}` if master had it.
-- `Combo` in overlay note context → `suffix={false}` (the note refers to `IgxCombo` selector, not `IgxComboComponent`)
+The generated ApiLink registry resolves prefix/suffix differences. Do not add
+`prefixed={false}` or `suffix={false}` for new links.
 
 ---
 
@@ -134,7 +131,7 @@ JP content is at `docs/angular/src/content/jp/`. Apply the same fixes as EN. The
 
 1. **Do not add `pkg=` to angular-specific files** unless the type is from a sub-package (charts, gauges, maps, etc.). Angular docs default to `pkg="core"` which resolves to `igniteui-angular`.
 
-2. **Do not remove `suffix={false}` or `prefixed={false}`** from existing ApiLink components — these were added deliberately and are often required for the link to resolve correctly.
+2. **Do not add legacy prefix/suffix override props**. The registry should resolve the actual API symbol name.
 
 3. **Do not use `.md` extensions** in links — the remark plugin does not handle them and produces dead links at build time.