From 9b9ca084fc52881a1d8c4126f291df63deae873b Mon Sep 17 00:00:00 2001 From: Alexis Aguilar <98043211+alexisintech@users.noreply.github.com> Date: Mon, 11 May 2026 17:19:56 -0700 Subject: [PATCH 1/3] fix(repo): Add standalonePage tag for JSDoc comments --- .typedoc/custom-router.mjs | 9 ++-- .typedoc/custom-theme.mjs | 17 ++++---- .typedoc/extract-methods.mjs | 5 ++- .typedoc/standalone-page-tag.mjs | 25 +++++++++++ .../hooks/createBillingPaginatedHook.tsx | 42 +++++++++---------- packages/shared/src/react/types.ts | 1 + typedoc.config.mjs | 10 ++++- 7 files changed, 70 insertions(+), 39 deletions(-) create mode 100644 .typedoc/standalone-page-tag.mjs diff --git a/.typedoc/custom-router.mjs b/.typedoc/custom-router.mjs index c7aabc36813..0fca4b91220 100644 --- a/.typedoc/custom-router.mjs +++ b/.typedoc/custom-router.mjs @@ -2,6 +2,7 @@ import { ReflectionKind } from 'typedoc'; import { MemberRouter } from 'typedoc-plugin-markdown'; +import { isInlineModifierWithoutStandalonePage } from './standalone-page-tag.mjs'; import { REFERENCE_OBJECT_PAGE_SYMBOLS } from './reference-objects.mjs'; /** @type {Set} */ @@ -58,15 +59,11 @@ class ClerkRouter extends MemberRouter { } /** - * `@inline` marks types that should be expanded at use sites, not documented as their own page. + * `@inline` marks types that should be expanded at use sites, not documented as their own page unless `@standalonePage` is also set (see `standalone-page-tag.mjs`). * TypeDoc still assigns `fullUrls` for exported aliases, so we also strip links in the theme's `referenceType` partial (`custom-theme.mjs`). */ const model = page.model; - if ( - model && - 'comment' in model && - /** @type {{ comment?: import('typedoc').Comment | undefined }} */ (model).comment?.hasModifier('@inline') - ) { + if (model && isInlineModifierWithoutStandalonePage(/** @type {import('typedoc').Reflection} */ (model))) { return false; } diff --git a/.typedoc/custom-theme.mjs b/.typedoc/custom-theme.mjs index 82f0dbf83ac..07a0fc2c5e0 100644 --- a/.typedoc/custom-theme.mjs +++ b/.typedoc/custom-theme.mjs @@ -11,6 +11,7 @@ import { removeLineBreaks } from '../node_modules/typedoc-plugin-markdown/dist/l import { TypeDeclarationVisibility } from '../node_modules/typedoc-plugin-markdown/dist/options/maps.js'; import { applyTodoStrippingToComment } from './comment-utils.mjs'; +import { isInlineModifierWithoutStandalonePage } from './standalone-page-tag.mjs'; import { REFERENCE_OBJECTS_LIST } from './reference-objects.mjs'; export { REFERENCE_OBJECTS_LIST }; @@ -789,7 +790,7 @@ function renderMergedIntersectionDeclaration(ctx, model, opts, mergedChildren, s } if (model.comment) { md.push( - superPartials.comment(model.comment, { + ctx.partials.comment(model.comment, { headingLevel, showSummary: true, showTags: false, @@ -808,7 +809,7 @@ function renderMergedIntersectionDeclaration(ctx, model, opts, mergedChildren, s if (model.comment) { md.push( - superPartials.comment(model.comment, { + ctx.partials.comment(model.comment, { headingLevel, showSummary: false, showTags: true, @@ -1047,9 +1048,9 @@ class ClerkMarkdownThemeContext extends MarkdownThemeContext { ); }, /** - * Stock `comments.comment` prints every {@link Comment.modifierTags} as **`TitleCase`** before the summary. - * `@inline` / `@inlineType` are router/type hints only; `@experimental` is SDK-only guidance — none of these - * must appear in property tables or prose. + * Stock `comments.comment` prints every {@link Comment.modifierTags} as **`TitleCase`** before the summary + * (it does not consult `notRenderedTags`; that option only filters block tags). `@inline` / `@inlineType` are + * router/type hints; `@experimental` is SDK-only guidance — none of these must appear in property tables or prose. * * @param {import('typedoc').Comment} model * @param {Parameters[1]} [options] @@ -1059,7 +1060,7 @@ class ClerkMarkdownThemeContext extends MarkdownThemeContext { return superPartials.comment.call(this, model, options); } const modelToRender = applyTodoStrippingToComment(model) ?? model; - const hidden = new Set(['@inline', '@inlineType', '@experimental']); + const hidden = new Set(['@inline', '@inlineType', '@experimental', '@standalonePage']); const modTags = Array.from(modelToRender.modifierTags ?? []); if (modTags.some(/** @param {string} t */ t => hidden.has(t))) { const clone = Object.assign(Object.create(Object.getPrototypeOf(modelToRender)), modelToRender, { @@ -1076,12 +1077,12 @@ class ClerkMarkdownThemeContext extends MarkdownThemeContext { */ declarationTitle: () => '', /** - * TypeDoc's default links every {@link ReferenceType} to a URL. Types marked `@inline` are expanded at use sites and (via the router) have no standalone page — linking produces broken relative `.mdx` paths in extracted method docs. Render the **aliased type** (RHS) so literals and unions show as `'phone_code'`, not `PhoneCodeStrategy`. + * TypeDoc's default links every {@link ReferenceType} to a URL. Types marked `@inline` are expanded at use sites and (via the router) have no standalone page — linking produces broken relative `.mdx` paths in extracted method docs. Render the **aliased type** (RHS) so literals and unions show as `'phone_code'`, not `PhoneCodeStrategy`, unless `@standalonePage` is set (`standalone-page-tag.mjs`). * * @param {import('typedoc').ReferenceType} model */ referenceType: model => { - if (model.reflection?.comment?.hasModifier('@inline')) { + if (isInlineModifierWithoutStandalonePage(model.reflection)) { const decl = /** @type {import('typedoc').DeclarationReflection} */ (model.reflection); // Generic instantiation, e.g. `Fn` — let `someType` apply type arguments. if (model.typeArguments?.length) { diff --git a/.typedoc/extract-methods.mjs b/.typedoc/extract-methods.mjs index dfb8efcb710..96440f8dffb 100644 --- a/.typedoc/extract-methods.mjs +++ b/.typedoc/extract-methods.mjs @@ -32,6 +32,7 @@ import { applyRelativeLinkReplacements, stripReferenceObjectPropertiesSection, } from './custom-plugin.mjs'; +import { isInlineModifierWithoutStandalonePage } from './standalone-page-tag.mjs'; import { prepareMarkdownRenderer } from './prepare-markdown-renderer.mjs'; import { applyTodoStrippingToComment } from './comment-utils.mjs'; import { REFERENCE_OBJECTS_LIST, REFERENCE_OBJECT_CONFIG } from './reference-objects.mjs'; @@ -1048,7 +1049,7 @@ function unwrapOptionalParamType(t) { /** * When TypeDoc renders a parameter type as a markdown link to another generated `.mdx` file, that type has a dedicated page — omit nested `param?.prop` rows so readers follow the type link instead. - * `@inline` aliases are expanded by the theme and do not link to a standalone page. + * `@inline` aliases are expanded by the theme and do not link to a standalone page unless `@standalonePage` is set (`standalone-page-tag.mjs`). * * @param {import('typedoc').SomeType | undefined} t * @param {import('typedoc-plugin-markdown').MarkdownThemeContext} ctx @@ -1060,7 +1061,7 @@ function parameterTypeLinksToStandaloneMdxPage(t, ctx) { } if (bare.type === 'reference') { const ref = /** @type {import('typedoc').ReferenceType} */ (bare); - if (ref.reflection?.comment?.hasModifier('@inline')) { + if (isInlineModifierWithoutStandalonePage(ref.reflection)) { return false; } } diff --git a/.typedoc/standalone-page-tag.mjs b/.typedoc/standalone-page-tag.mjs new file mode 100644 index 00000000000..fc6ba0441dd --- /dev/null +++ b/.typedoc/standalone-page-tag.mjs @@ -0,0 +1,25 @@ +// @ts-check + +/** + * Modifier tag: keep a dedicated `.mdx` page even when `@inline` is present (TypeDoc + our router + * otherwise drop inline-marked declarations; the theme also expands references instead of linking). + */ +export const STANDALONE_PAGE_MODIFIER_TAG = '@standalonePage'; + +/** + * @param {import('typedoc').Reflection | undefined} reflection + * @returns {boolean} True when `@inline` should suppress a standalone page / force in-place expansion. + */ +export function isInlineModifierWithoutStandalonePage(reflection) { + const comment = + reflection && 'comment' in reflection + ? /** @type {{ comment?: import('typedoc').Comment | undefined }} */ (reflection).comment + : undefined; + if (!comment?.hasModifier('@inline')) { + return false; + } + if (comment.hasModifier(STANDALONE_PAGE_MODIFIER_TAG)) { + return false; + } + return true; +} diff --git a/packages/shared/src/react/hooks/createBillingPaginatedHook.tsx b/packages/shared/src/react/hooks/createBillingPaginatedHook.tsx index d41bdc57d78..e6ecc3137e6 100644 --- a/packages/shared/src/react/hooks/createBillingPaginatedHook.tsx +++ b/packages/shared/src/react/hooks/createBillingPaginatedHook.tsx @@ -25,28 +25,28 @@ type BillingHookConfig { +export interface HookParams extends PaginatedHookConfig< + PagesOrInfiniteOptions & { + /** + * If `true`, a request will be triggered when the hook is mounted. + * + * @default true + */ + enabled?: boolean; + /** + * On `cache` mode, no request will be triggered when the hook is mounted and the data will be fetched from the cache. + * + * @default undefined + * + * @hidden + * + * @experimental + */ + __experimental_mode?: 'cache'; + } +> { /** * Specifies whether to fetch for the current user or Organization. * diff --git a/packages/shared/src/react/types.ts b/packages/shared/src/react/types.ts index aea1557422e..e4a0a3a7d16 100644 --- a/packages/shared/src/react/types.ts +++ b/packages/shared/src/react/types.ts @@ -85,6 +85,7 @@ export type PaginatedResourcesWithDefault = { /** * @inline + * @standalonePage */ export type PaginatedHookConfig = T & { /** diff --git a/typedoc.config.mjs b/typedoc.config.mjs index 56db774f8a2..c206e1c92e4 100644 --- a/typedoc.config.mjs +++ b/typedoc.config.mjs @@ -91,6 +91,8 @@ const config = { /** Parsed for router/theme; must not appear as a doc section (otherwise renders as **Inline**). */ '@inline', '@inlineType', + /** Opts into a dedicated reference page despite `@inline` (see `.typedoc/standalone-page-tag.mjs`). */ + '@standalonePage', ], packageOptions: { includeVersion: false, @@ -114,11 +116,15 @@ const config = { /** Type-only / router hints; not user-facing prose (see `notRenderedTags`). */ '@inline', '@inlineType', + /** With `@inline`, still emit a standalone `.mdx` page (see `.typedoc/standalone-page-tag.mjs`). */ + '@standalonePage', ], /** - * Stops TypeDoc from generating standalone pages for inline types. + * Keep `@inline` / `@inlineType` / `@standalonePage` in the model so the custom router and theme can read them. */ - excludeTags: OptionDefaults.excludeTags.filter(tag => tag !== '@inline' && tag !== '@inlineType'), + excludeTags: OptionDefaults.excludeTags.filter( + tag => tag !== '@inline' && tag !== '@inlineType' && tag !== '@standalonePage', + ), exclude: ['src/**/*.test.ts', 'src/**/*.test.tsx'], readme: 'none', disableGit: true, From 30393f112268a8bdf05d502979be4cd15b238059 Mon Sep 17 00:00:00 2001 From: Alexis Aguilar <98043211+alexisintech@users.noreply.github.com> Date: Mon, 11 May 2026 17:27:28 -0700 Subject: [PATCH 2/3] Apply suggestion from @alexisintech --- .typedoc/standalone-page-tag.mjs | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/.typedoc/standalone-page-tag.mjs b/.typedoc/standalone-page-tag.mjs index fc6ba0441dd..20cf25c55e4 100644 --- a/.typedoc/standalone-page-tag.mjs +++ b/.typedoc/standalone-page-tag.mjs @@ -1,8 +1,7 @@ // @ts-check /** - * Modifier tag: keep a dedicated `.mdx` page even when `@inline` is present (TypeDoc + our router - * otherwise drop inline-marked declarations; the theme also expands references instead of linking). + * Modifier tag: keep a dedicated `.mdx` page even when `@inline` is present (TypeDoc + our router otherwise drop inline-marked declarations; the theme also expands references instead of linking). */ export const STANDALONE_PAGE_MODIFIER_TAG = '@standalonePage'; From 9e29238e449bdc4ea376e1f6bc01463be5e35f97 Mon Sep 17 00:00:00 2001 From: Alexis Aguilar <98043211+alexisintech@users.noreply.github.com> Date: Tue, 12 May 2026 13:10:51 -0700 Subject: [PATCH 3/3] add standalone-page-tag.mjs to turbo.json --- turbo.json | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/turbo.json b/turbo.json index d19e070127a..faf549e53ff 100644 --- a/turbo.json +++ b/turbo.json @@ -345,7 +345,8 @@ ".typedoc/reference-objects.mjs", ".typedoc/comment-utils.mjs", ".typedoc/extract-methods.mjs", - ".typedoc/extract-returns-and-params.mjs" + ".typedoc/extract-returns-and-params.mjs", + ".typedoc/standalone-page-tag.mjs" ], "outputs": [".typedoc/**"], "outputLogs": "new-only"