Skip to content

feat(ApiLink): default member label to member name, cased per platform #110

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
dobromirts wants to merge 1 commit into
base: master
Choose a base branch
from
Open

feat(ApiLink): default member label to member name, cased per platform #110

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 12 additions & 2 deletions src/components/mdx/ApiLink/ApiLink.astro
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -63,6 +63,16 @@ const ctx = Astro.locals.platformContext as PlatformContext;
const { prefix, apiPackages } = ctx;
const label = Astro.props.label;

const upperFirst = (value: string) => value ? value.charAt(0).toUpperCase() + value.slice(1) : value;
const lowerFirst = (value: string) => value ? value.charAt(0).toLowerCase() + value.slice(1) : value;
Comment thread
dobromirts marked this conversation as resolved.

/**
* Auto-label for a member when no explicit `label` is provided. Blazor member
* names are PascalCase; WebComponents, React, and Angular use camelCase.
*/
const formatMemberName = (member: string) =>
ctx.name === 'Blazor' ? upperFirst(member) : lowerFirst(member);

function getIndexedDisplayName(resolvedName: string, displayBaseName: string, type: string, classSuffix?: string) {
if (resolvedName === type) return type;
if (classSuffix && resolvedName === `${type}${classSuffix}`) return type;
Expand Down Expand Up @@ -109,7 +119,7 @@ if (Astro.props.kind === 'sass') {
const baseType = effectivePrefixed ? `${prefix}${type}` : type;

url = '';
displayLabel = label ?? (member ? `${baseType}.${member}` : baseType);
displayLabel = label ?? (member ? formatMemberName(member) : baseType);
renderCode = true;

const indexed = resolveApiLinkFromIndex({
Expand All @@ -128,7 +138,7 @@ if (Astro.props.kind === 'sass') {
url = indexed.url;
renderLink = true;
const indexedDisplay = getIndexedDisplayName(indexed.symbolName, baseType, type, pkgConfig.classSuffix);
displayLabel = label ?? (indexed.memberName ? `${indexedDisplay}.${indexed.memberName}` : indexedDisplay);
displayLabel = label ?? (indexed.memberName ? formatMemberName(indexed.memberName) : indexedDisplay);
} else if (indexed.status === 'ambiguous') {
const symbol = member ? `${type}.${member}` : type;
throw new Error(`[ApiLink] Ambiguous API symbol "${symbol}" matched registry candidate "${indexed.candidate}". Add pkg= or kind= to disambiguate.`);
Expand Down
6 changes: 4 additions & 2 deletions src/components/mdx/ApiLink/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,7 +38,7 @@ the index is unavailable, `ApiLink` renders code text and does not guess a URL.
|------|------|---------|-------------|
| `type` | `string` | *(required)* | Short symbol name without platform prefix, e.g. `"Grid"` instead of `"IgrGrid"`. |
| `member` | `string` | — | Optional member name. Resolved through the generated member map when available. |
| `label` | `string` | auto | Override the display text. |
| `label` | `string` | auto | Override the display text. When omitted and `member` is set, the label defaults to just the member name (not `Type.member`), cased per platform: camelCase for WebComponents/React/Angular, PascalCase for Blazor. When omitted with no `member`, it defaults to the resolved symbol name. |
| `pkg` | `string` | — | Ambiguity override only. Use when the same symbol exists in multiple packages and the combined index cannot choose safely. |
| `kind` | `'class' \| 'interface' \| 'enum' \| 'type' \| 'variable' \| 'function'` | auto | Optional narrowing. Usually unnecessary when the index is available. |
| `prefixed` | `boolean` | `true` | Candidate-name override for symbols that are never platform-prefixed. Avoid for new docs when the index can resolve the symbol. |
Expand All @@ -53,7 +53,9 @@ Platform names use `PlatformContext.name`: `Angular`, `React`,
{/* Let the generated index find package, kind, and exact symbol name. */}
<ApiLink type="Grid" />

{/* Member anchors are resolved from the generated member map. */}
{/* Member anchors are resolved from the generated member map. With no
`label`, the display text defaults to the member name, cased per platform:
`rowSelection` for WebComponents/React/Angular, `RowSelection` for Blazor. */}
<ApiLink type="Grid" member="rowSelection" />

{/* Use pkg only when the symbol name is ambiguous across packages. */}
Expand Down