diff --git a/.changeset/old-dolls-smell.md b/.changeset/old-dolls-smell.md new file mode 100644 index 00000000000..a845151cc84 --- /dev/null +++ b/.changeset/old-dolls-smell.md @@ -0,0 +1,2 @@ +--- +--- diff --git a/.typedoc/custom-theme.mjs b/.typedoc/custom-theme.mjs index 20b8ab3715d..6310f6a3d0a 100644 --- a/.typedoc/custom-theme.mjs +++ b/.typedoc/custom-theme.mjs @@ -218,9 +218,69 @@ class ClerkMarkdownThemeContext extends MarkdownThemeContext { const customizedModel = model; customizedModel.typeParameters = undefined; - const output = superPartials.memberWithGroups(customizedModel, options); + // Extract the Accessors group (if any) and prevent default rendering for it + const originalGroups = customizedModel.groups; + const accessorsGroup = originalGroups?.find(g => g.title === 'Accessors'); + const groupsWithoutAccessors = originalGroups?.filter(g => g.title !== 'Accessors'); + + customizedModel.groups = groupsWithoutAccessors; + const nonAccessorOutput = superPartials.memberWithGroups(customizedModel, options); + customizedModel.groups = originalGroups; + + /** @type {string[]} */ + const md = [nonAccessorOutput]; + + if (accessorsGroup && accessorsGroup.children && accessorsGroup.children.length > 0) { + md.push('\n\n## Accessors\n'); + // Table header + // This needs to be 'Property' instead of 'Accessor' so that clerk.com renders it correctly + md.push('| Property | Type | Description |'); + md.push('| --- | --- | --- |'); + + for (const child of accessorsGroup.children) { + /** @type {import('typedoc').DeclarationReflection} */ + // @ts-ignore - child is a DeclarationReflection for accessor members + const decl = child; + // Name and anchor id + const name = decl.name; + const id = name.toLowerCase().replace(/[^a-z0-9]/g, ''); + + // Resolve the accessor type from the getter signature + /** @type {any} */ + const getterSig = /** @type {any} */ (decl).getSignature; + /** @type {any} */ + const setterSig = /** @type {any} */ (decl).setSignature; + let typeStr = ''; + if (getterSig?.type) { + typeStr = this.partials.someType(getterSig.type); + } else if (setterSig?.parameters?.[0]?.type) { + typeStr = this.partials.someType(setterSig.parameters[0].type); + } else if (decl.type) { + typeStr = this.partials.someType(decl.type); + } - return output; + // Prefer comment on the getter signature; fallback to declaration comment + const summary = getterSig?.comment?.summary ?? decl.comment?.summary ?? setterSig?.comment?.summary; + const description = Array.isArray(summary) + ? summary.reduce((acc, curr) => acc + (curr.text || ''), '') + : ''; + + md.push(`| \`${escapeChars(name)}\` | ${typeStr} | ${description} |`); + } + } + + return md.join('\n'); + }, + /** + * Suppress default per-accessor member rendering; table is rendered in memberWithGroups instead. + * @param {import('typedoc').DeclarationReflection} model + * @param {{ headingLevel: number, nested?: boolean }} options + */ + member: (model, options) => { + if (model.kind === ReflectionKind.Accessor) { + return ''; + } + return superPartials.member(model, options); }, /** * This hides the "Type parameters" section and the declaration title from the output @@ -412,6 +472,17 @@ ${tabs} * Hide "Extends" and "Extended by" sections */ hierarchy: () => '', + /** + * @param {import('typedoc').DeclarationReflection} model + */ + accessor: model => { + // Fallback single-row rendering if used directly elsewhere + const name = model.name; + const typeStr = model.getSignature?.type ? this.partials.someType(model.getSignature.type) : ''; + const summary = model.getSignature?.comment?.summary ?? model.comment?.summary; + const description = Array.isArray(summary) ? summary.reduce((acc, curr) => acc + (curr.text || ''), '') : ''; + return '| ' + '`' + escapeChars(name) + '`' + ' | ' + typeStr + ' | ' + description + ' |'; + }, }; } } diff --git a/package.json b/package.json index 926374fe642..990834941ba 100644 --- a/package.json +++ b/package.json @@ -53,7 +53,8 @@ "test:integration:vue": "E2E_APP_ID=vue.vite pnpm test:integration:base --grep @vue", "test:typedoc": "pnpm typedoc:generate && cd ./.typedoc && vitest run", "turbo:clean": "turbo daemon clean", - "typedoc:generate": "pnpm build:declarations && typedoc --tsconfig tsconfig.typedoc.json && rm -rf .typedoc/docs && mv .typedoc/temp-docs .typedoc/docs", + "typedoc:generate": "pnpm build:declarations && pnpm typedoc:generate:skip-build", + "typedoc:generate:skip-build": "typedoc --tsconfig tsconfig.typedoc.json && rm -rf .typedoc/docs && mv .typedoc/temp-docs .typedoc/docs", "version-packages": "changeset version && pnpm install --lockfile-only --engine-strict=false", "version-packages:canary": "./scripts/canary.mjs", "version-packages:snapshot": "./scripts/snapshot.mjs",