react-props-parser 0.0.1

package/dist/program.d.ts

@@ -0,0 +1,21 @@
+import ts from 'typescript';
+/**
+ * Returns a ts.Program that has `filePath` up to date and ready to read,
+ * reusing a shared per-project ts.LanguageService rather than building a
+ * new ts.Program from scratch on every call. See the module comment above
+ * for why that distinction matters.
+ *
+ * Uses the *consuming project's* real tsconfig.json when one can be found
+ * (walking up from the file's directory), rather than a fixed set of
+ * compiler options.
+ *
+ * This matters beyond just matching the project's strictness settings:
+ * without the real `baseUrl`/`paths`, any import that relies on a path
+ * alias — including a cross-file `extends` base interface reached that
+ * way — fails to resolve, silently degrading to whatever TS falls back
+ * to rather than the actual project structure. Falls back to a fixed
+ * set of reasonable defaults when no tsconfig.json is found (e.g. a
+ * standalone fixture file with no project root), so parsing a bare
+ * .tsx file in isolation still works.
+ */
+export declare function createProgramForFile(filePath: string): ts.Program;

package/dist/program.js

@@ -0,0 +1,172 @@
+import ts from 'typescript';
+import path from 'node:path';
+const FALLBACK_OPTIONS = {
+    target: ts.ScriptTarget.ES2020,
+    module: ts.ModuleKind.ESNext,
+    jsx: ts.JsxEmit.ReactJSX,
+    esModuleInterop: true,
+    skipLibCheck: true,
+    strict: true,
+};
+// Every file parsed with the same effective compiler options (i.e. every
+// file under the same resolved tsconfig, or every file that falls back to
+// FALLBACK_OPTIONS) shares one long-lived ts.LanguageService instead of
+// getting its own throwaway ts.Program. A LanguageService reparses only
+// the files whose version actually changed since the last getProgram()
+// call — it re-checks the rest (React's own types, lib.dom.d.ts, sibling
+// component files already seen) from its cached ASTs. Building a fresh
+// ts.Program per file, as this used to do, redid that shared work (often
+// hundreds of files' worth of parsing/binding) on every single call —
+// the dominant cost behind slow Storybook startup with many components.
+//
+// Keyed by resolved tsconfig path (or FALLBACK_KEY when none is found),
+// since that's exactly the granularity at which compiler options — and
+// therefore which files can safely share one Program — are the same.
+const FALLBACK_KEY = '\0fallback';
+const projectCache = new Map();
+// Memoizes the two filesystem walks resolveCompilerOptions used to redo
+// on every call: ts.findConfigFile (per directory) and reading/parsing
+// the tsconfig it finds (per resolved config path). Many files share a
+// directory or a tsconfig, so this turns O(files) I/O into O(directories)
+// + O(tsconfigs).
+const configPathByDir = new Map();
+const optionsByConfigPath = new Map();
+const registry = ts.createDocumentRegistry();
+/**
+ * Returns a ts.Program that has `filePath` up to date and ready to read,
+ * reusing a shared per-project ts.LanguageService rather than building a
+ * new ts.Program from scratch on every call. See the module comment above
+ * for why that distinction matters.
+ *
+ * Uses the *consuming project's* real tsconfig.json when one can be found
+ * (walking up from the file's directory), rather than a fixed set of
+ * compiler options.
+ *
+ * This matters beyond just matching the project's strictness settings:
+ * without the real `baseUrl`/`paths`, any import that relies on a path
+ * alias — including a cross-file `extends` base interface reached that
+ * way — fails to resolve, silently degrading to whatever TS falls back
+ * to rather than the actual project structure. Falls back to a fixed
+ * set of reasonable defaults when no tsconfig.json is found (e.g. a
+ * standalone fixture file with no project root), so parsing a bare
+ * .tsx file in isolation still works.
+ */
+export function createProgramForFile(filePath) {
+    const { key, options, projectDir } = resolveProjectForFile(filePath);
+    const entry = getOrCreateProject(key, options, projectDir);
+    entry.rootFiles.add(filePath);
+    // Always bump the requested file's own version so its content is
+    // re-read from disk on every call (needed for correctness across
+    // repeated parse() calls / watch-mode edits) — sibling files already
+    // in rootFiles keep their cached version, which is what lets the
+    // LanguageService skip re-parsing them.
+    entry.versions.set(filePath, (entry.versions.get(filePath) ?? 0) + 1);
+    const program = entry.service.getProgram();
+    if (!program) {
+        throw new Error(`Could not build a TypeScript program for: ${filePath}`);
+    }
+    return program;
+}
+function resolveProjectForFile(filePath) {
+    const configPath = resolveConfigPathForDir(path.dirname(filePath));
+    if (!configPath) {
+        return { key: FALLBACK_KEY, options: FALLBACK_OPTIONS, projectDir: process.cwd() };
+    }
+    let options = optionsByConfigPath.get(configPath);
+    if (!options) {
+        options = readCompilerOptions(configPath);
+        optionsByConfigPath.set(configPath, options);
+    }
+    return { key: configPath, options, projectDir: path.dirname(configPath) };
+}
+function resolveConfigPathForDir(dir) {
+    if (configPathByDir.has(dir))
+        return configPathByDir.get(dir) ?? null;
+    const foundPath = ts.findConfigFile(dir, ts.sys.fileExists);
+    const resolved = foundPath ? resolveSolutionStyleReferences(foundPath) : null;
+    configPathByDir.set(dir, resolved);
+    return resolved;
+}
+function readCompilerOptions(configPath) {
+    const configFile = ts.readConfigFile(configPath, ts.sys.readFile);
+    if (configFile.error)
+        return FALLBACK_OPTIONS;
+    const parsed = ts.parseJsonConfigFileContent(configFile.config, ts.sys, path.dirname(configPath));
+    // A project's tsconfig may not set jsx at all if it doesn't compile
+    // .tsx directly (e.g. relies on a bundler for that) — without it, TS
+    // can't parse JSX syntax at all, so every component file would fail
+    // outright. Fill it in rather than let real project configs break.
+    return {
+        ...parsed.options,
+        jsx: parsed.options.jsx ?? ts.JsxEmit.ReactJSX,
+    };
+}
+function getOrCreateProject(key, options, projectDir) {
+    const cached = projectCache.get(key);
+    if (cached)
+        return cached;
+    const rootFiles = new Set();
+    const versions = new Map();
+    const host = {
+        getScriptFileNames: () => [...rootFiles],
+        getScriptVersion: (fileName) => String(versions.get(fileName) ?? 0),
+        getScriptSnapshot: (fileName) => {
+            if (!ts.sys.fileExists(fileName))
+                return undefined;
+            const text = ts.sys.readFile(fileName);
+            return text !== undefined ? ts.ScriptSnapshot.fromString(text) : undefined;
+        },
+        getCurrentDirectory: () => projectDir,
+        getCompilationSettings: () => options,
+        getDefaultLibFileName: (opts) => ts.getDefaultLibFilePath(opts),
+        fileExists: ts.sys.fileExists,
+        readFile: ts.sys.readFile,
+        readDirectory: ts.sys.readDirectory,
+        directoryExists: ts.sys.directoryExists,
+        getDirectories: ts.sys.getDirectories,
+        realpath: ts.sys.realpath,
+    };
+    const entry = {
+        service: ts.createLanguageService(host, registry),
+        rootFiles,
+        versions,
+    };
+    projectCache.set(key, entry);
+    return entry;
+}
+/**
+ * A "solution-style" root tsconfig.json — `{ "files": [], "references":
+ * [...] }`, common in real projects split into build/test/etc. sub-
+ * projects — declares no compilerOptions of its own; the actual settings
+ * (target, paths, jsx, ...) live in one of the referenced configs. Taking
+ * such a root at face value silently produces near-empty options: no
+ * `paths`, meaning any path-aliased import — including a cross-file
+ * `extends` base interface reached that way — fails to resolve.
+ *
+ * Follows the first `references` entry (recursively, depth-bounded)
+ * until landing on a config that either declares its own compilerOptions
+ * (which may itself `extends` a base config — parseJsonConfigFileContent
+ * follows that chain natively) or has no further references to follow.
+ */
+function resolveSolutionStyleReferences(configPath, depth = 0) {
+    if (depth > 5)
+        return configPath;
+    const raw = ts.readConfigFile(configPath, ts.sys.readFile);
+    if (raw.error || !raw.config)
+        return configPath;
+    const hasOwnOptions = raw.config.compilerOptions && Object.keys(raw.config.compilerOptions).length > 0;
+    const references = raw.config.references;
+    if (hasOwnOptions || !Array.isArray(references) || references.length === 0) {
+        return configPath;
+    }
+    const firstRef = references[0];
+    if (!firstRef?.path)
+        return configPath;
+    const refTarget = path.resolve(path.dirname(configPath), firstRef.path);
+    const nextConfigPath = ts.sys.fileExists(refTarget)
+        ? refTarget
+        : path.join(refTarget, 'tsconfig.json');
+    if (!ts.sys.fileExists(nextConfigPath))
+        return configPath;
+    return resolveSolutionStyleReferences(nextConfigPath, depth + 1);
+}

package/dist/resolvePropsType.d.ts

@@ -0,0 +1,52 @@
+import ts from 'typescript';
+import { type ResolvedParseOptions } from './options.js';
+export interface ResolvedPropsType {
+    type: ts.Type;
+    /** Node to resolve individual prop symbols' types/locations against. */
+    contextNode: ts.Node;
+    displayName: string;
+    /**
+     * Symbol to read the top-level jsdoc description from — the *local*
+     * type reference's own symbol, not necessarily `type.symbol`/
+     * `type.aliasSymbol`. Those reflect whatever the resolved type's
+     * own definition is, which for something like `Partial<FullUserFields>`
+     * is TypeScript's *built-in* `Partial` alias — picking up its doc
+     * comment ("Make all properties in T optional") would be wrong. This
+     * is resolved from the actual identifier as written at the reference
+     * site (or the declaration site, for the bare-fallback case), which
+     * correctly follows to an imported type's own symbol without also
+     * picking up an unrelated wrapper utility type's docs.
+     */
+    docSymbol: ts.Symbol | undefined;
+}
+/**
+ * Finds the props type for a component in a source file, resolving it
+ * via the checker rather than by name-matching declarations in the same
+ * file. This matters because in a typical real codebase the props type
+ * is declared in a sibling `types.ts` and imported — using the checker
+ * to resolve whatever type node the component's signature actually
+ * points at follows that import for free, the same way it follows an
+ * `extends` base interface across files. Checked several ways, since
+ * "the props type" shows up in different places depending on how the
+ * component is written:
+ *  - a parameter's own type annotation, `(props: XProps) => ...` or
+ *    `({ a, b }: XProps) => ...` (destructured — the annotation is on
+ *    the parameter, not affected by the binding pattern)
+ *  - the variable's own type annotation, `const X: React.FC<XProps> = ({ a }) => ...`
+ *  - any call expression with type arguments assigned to a variable —
+ *    `forwardRef<Ref, XProps>((props, ref) => ...)`,
+ *    `SomeWrapper<XProps>(Component, ...)`, `memo<XProps>(...)`, etc.
+ *    Generalized rather than hardcoded to forwardRef/memo by name, since
+ *    real component libraries wrap components in their own HOCs using
+ *    the same shape (a type argument that *is* the props type).
+ *  - a `memo(...)`/any other wrapper with no type arguments of its own —
+ *    handled for free by walking the whole tree rather than only the
+ *    top level of a function declaration or variable initializer, so
+ *    the inner function/arrow expression's own parameter annotation is
+ *    still found.
+ *
+ * Falls back to "first exported `Props`-or-`*Props`-named declaration
+ * in this file" when no component signature can be resolved at all
+ * (e.g. a bare type-only fixture with no component function).
+ */
+export declare function resolvePropsType(sourceFile: ts.SourceFile, checker: ts.TypeChecker, options?: ResolvedParseOptions): ResolvedPropsType | undefined;

package/dist/resolvePropsType.js

@@ -0,0 +1,206 @@
+import ts from 'typescript';
+import { DEFAULT_PARSE_OPTIONS } from './options.js';
+import { truncateTypeName } from './utils/truncateTypeName.js';
+/**
+ * Finds the props type for a component in a source file, resolving it
+ * via the checker rather than by name-matching declarations in the same
+ * file. This matters because in a typical real codebase the props type
+ * is declared in a sibling `types.ts` and imported — using the checker
+ * to resolve whatever type node the component's signature actually
+ * points at follows that import for free, the same way it follows an
+ * `extends` base interface across files. Checked several ways, since
+ * "the props type" shows up in different places depending on how the
+ * component is written:
+ *  - a parameter's own type annotation, `(props: XProps) => ...` or
+ *    `({ a, b }: XProps) => ...` (destructured — the annotation is on
+ *    the parameter, not affected by the binding pattern)
+ *  - the variable's own type annotation, `const X: React.FC<XProps> = ({ a }) => ...`
+ *  - any call expression with type arguments assigned to a variable —
+ *    `forwardRef<Ref, XProps>((props, ref) => ...)`,
+ *    `SomeWrapper<XProps>(Component, ...)`, `memo<XProps>(...)`, etc.
+ *    Generalized rather than hardcoded to forwardRef/memo by name, since
+ *    real component libraries wrap components in their own HOCs using
+ *    the same shape (a type argument that *is* the props type).
+ *  - a `memo(...)`/any other wrapper with no type arguments of its own —
+ *    handled for free by walking the whole tree rather than only the
+ *    top level of a function declaration or variable initializer, so
+ *    the inner function/arrow expression's own parameter annotation is
+ *    still found.
+ *
+ * Falls back to "first exported `Props`-or-`*Props`-named declaration
+ * in this file" when no component signature can be resolved at all
+ * (e.g. a bare type-only fixture with no component function).
+ */
+export function resolvePropsType(sourceFile, checker, options = DEFAULT_PARSE_OPTIONS) {
+    const fromSignature = findPropsTypeFromComponentSignature(sourceFile, checker, options);
+    if (fromSignature)
+        return fromSignature;
+    let fallback;
+    ts.forEachChild(sourceFile, (node) => {
+        if (fallback)
+            return;
+        if (ts.isInterfaceDeclaration(node) && isPropsName(node.name.text))
+            fallback = node;
+        if (ts.isTypeAliasDeclaration(node) && isPropsName(node.name.text))
+            fallback = node;
+    });
+    if (!fallback)
+        return undefined;
+    return {
+        type: checker.getTypeAtLocation(fallback),
+        contextNode: fallback,
+        displayName: fallback.name.text,
+        docSymbol: checker.getSymbolAtLocation(fallback.name),
+    };
+}
+function findPropsTypeFromComponentSignature(sourceFile, checker, options) {
+    let found;
+    const resolveFromTypeNode = (typeNode, contextNode) => {
+        if (found)
+            return;
+        const type = checker.getTypeFromTypeNode(typeNode);
+        // Not a plausible props type (e.g. a primitive parameter on some
+        // unrelated helper function encountered while walking the tree) —
+        // skip rather than confidently claim it.
+        if (!(type.getFlags() & ts.TypeFlags.Object) && !type.isUnion() && !type.isIntersection()) {
+            return;
+        }
+        // A props type is a plain data shape — it never has call/construct
+        // signatures. A parameter typed `React.ComponentType<XProps>` (or
+        // `FC<...>`, `ElementType<...>`, a class reference, etc.) is *itself*
+        // union-shaped and object-flagged, so it would otherwise pass the
+        // check above and get misidentified as the props type — this is
+        // exactly what a HOC factory's first parameter looks like
+        // (`withExtraProps(WrappedComponent: React.ComponentType<Props>)`),
+        // and matching it hands back React's own static properties
+        // (`contextTypes`, `defaultProps`, ...) instead of the real props.
+        const branches = type.isUnion() ? type.types : [type];
+        if (branches.every((t) => t.getCallSignatures().length > 0 || t.getConstructSignatures().length > 0)) {
+            return;
+        }
+        // Resolve documentation from the identifier actually written at
+        // this reference site (e.g. "XProps" in `props: XProps`), not from
+        // the resolved type's own symbol — see ResolvedPropsType.docSymbol.
+        const docSymbol = ts.isTypeReferenceNode(typeNode)
+            ? checker.getSymbolAtLocation(ts.isQualifiedName(typeNode.typeName) ? typeNode.typeName.right : typeNode.typeName)
+            : (type.aliasSymbol ?? type.symbol);
+        found = {
+            type,
+            contextNode,
+            displayName: typeDisplayName(typeNode, type, checker, options),
+            docSymbol,
+        };
+    };
+    const checkParams = (params) => {
+        if (found || params.length === 0)
+            return;
+        const paramType = params[0].type;
+        if (paramType)
+            resolveFromTypeNode(paramType, params[0]);
+    };
+    // `const X: React.FC<XProps> = (...) => ...` — the props type is a
+    // type argument on the *variable's* annotation, not the parameter.
+    //
+    // Requires the variable to be exported: without the old React.FC-
+    // name-only filter, matching *any* generic type reference here would
+    // false-positive on unrelated code (`const cache: Map<string, X> = ...`).
+    // An unexported local isn't a plausible component to document anyway.
+    const checkVariableTypeAnnotation = (decl) => {
+        if (found || !decl.type || !ts.isTypeReferenceNode(decl.type) || !isExported(decl))
+            return;
+        const propsArg = decl.type.typeArguments?.[0];
+        if (propsArg)
+            resolveFromTypeNode(propsArg, decl);
+    };
+    // Any `SomeWrapper<..., XProps, ...>(...)` call assigned to a
+    // variable — forwardRef, memo, or a project's own HOC. Not hardcoded
+    // to a specific wrapper name: tries each type argument in order and
+    // takes the first that resolves to a plausible object/union/
+    // intersection type, since which position holds the props type
+    // varies by wrapper (forwardRef's is typically the 2nd, a simple
+    // custom wrapper's is often the 1st). Same export requirement as
+    // above, for the same reason (avoid matching e.g. a local
+    // `useMemo<Y>(...)` call).
+    const checkWrapperCall = (decl) => {
+        if (found || !decl.initializer || !ts.isCallExpression(decl.initializer) || !isExported(decl)) {
+            return;
+        }
+        const typeArgs = decl.initializer.typeArguments;
+        if (!typeArgs || typeArgs.length === 0)
+            return;
+        // Prefer a type argument whose own name looks like a props type
+        // (the near-universal `*Props` convention) over just taking the
+        // first object-like one — forwardRef<HTMLButtonElement, XProps>
+        // would otherwise match the ref type first, since it's an object
+        // type too.
+        const byName = typeArgs.find((arg) => ts.isTypeReferenceNode(arg) && /Props$/.test(rightmostName(arg.typeName)));
+        if (byName) {
+            resolveFromTypeNode(byName, decl);
+            if (found)
+                return;
+        }
+        for (const typeArg of typeArgs) {
+            resolveFromTypeNode(typeArg, decl);
+            if (found)
+                return;
+        }
+    };
+    const visit = (node) => {
+        if (found)
+            return;
+        if (ts.isFunctionDeclaration(node)) {
+            checkParams(node.parameters);
+        }
+        // Checked regardless of where this function/arrow expression sits
+        // in the tree (top-level initializer, wrapped in memo(...), the
+        // second argument to forwardRef(...), etc.) — forEachChild below
+        // reaches it either way, so no wrapper needs special-casing here.
+        if (ts.isArrowFunction(node) || ts.isFunctionExpression(node)) {
+            checkParams(node.parameters);
+        }
+        if (ts.isVariableStatement(node)) {
+            for (const decl of node.declarationList.declarations) {
+                checkVariableTypeAnnotation(decl);
+                checkWrapperCall(decl);
+            }
+        }
+        ts.forEachChild(node, visit);
+    };
+    visit(sourceFile);
+    return found;
+}
+function typeDisplayName(typeNode, type, checker, options) {
+    if (ts.isTypeReferenceNode(typeNode)) {
+        return rightmostName(typeNode.typeName);
+    }
+    // A component's real parameter annotation is often an intersection
+    // like `XProps & InternalProps & WrapperProps` — internal/wrapper
+    // additions mixed in alongside the type a human actually thinks of
+    // as "the props type". Prefer the first `*Props`-named constituent
+    // over the full (long, implementation-detail-laden) intersection
+    // string as the display name; the full prop set from every
+    // constituent is still returned regardless, this only affects the
+    // one-line name shown for the component.
+    if (ts.isIntersectionTypeNode(typeNode)) {
+        const namedProps = typeNode.types.find((t) => ts.isTypeReferenceNode(t) && /Props$/.test(rightmostName(t.typeName)));
+        if (namedProps && ts.isTypeReferenceNode(namedProps)) {
+            return rightmostName(namedProps.typeName);
+        }
+    }
+    // Union/inline object literal/anything else — no single clean
+    // reference name on the node itself; fall back to whatever symbol
+    // the checker resolved, or the stringified type as a last resort.
+    return (type.symbol?.name ??
+        type.aliasSymbol?.name ??
+        truncateTypeName(checker.typeToString(type), options.maxTypeNameLength));
+}
+function isExported(decl) {
+    const statement = decl.parent.parent;
+    return !!(ts.getCombinedModifierFlags(statement) & ts.ModifierFlags.Export);
+}
+function rightmostName(name) {
+    return ts.isQualifiedName(name) ? name.right.text : name.text;
+}
+function isPropsName(name) {
+    return name === 'Props' || name.endsWith('Props');
+}

package/dist/types.d.ts

@@ -0,0 +1,86 @@
+export interface PropDescriptor {
+    name: string;
+    required: boolean;
+    type: {
+        /** Raw TS type text, e.g. "string", "'a' | 'b'" */
+        name: string;
+        /**
+         * Present only when this prop's type is a union of object shapes
+         * (e.g. `{type:'a',foo} | {type:'b',bar}`) — one entry per branch,
+         * each with its own resolved props. This is what lets a rich
+         * ArgsTable render per-variant fields instead of one opaque
+         * stringified union.
+         */
+        elements?: UnionBranch[];
+        /**
+         * Present when this prop's type resolves to a plain object shape
+         * (a named interface/type-alias reference, or an inline object
+         * type) — its own fields, one level deep, each with jsdoc intact.
+         * `name` stays the original reference (e.g. "AvatarUser") so the
+         * type identity is still visible; this is the expanded shape
+         * alongside it, not a replacement for it.
+         */
+        properties?: Record<string, PropDescriptor>;
+        /**
+         * Present when this prop's type is itself a function (a named
+         * function type alias, an `interface` call signature, or an inline
+         * `(...) => ...` type) — one entry per parameter of its call
+         * signature. Each parameter's own type is expanded the same way a
+         * regular object prop's would be (via `properties`), but only when
+         * it resolves to a type declared in the user's own project —
+         * expanding a built-in like `MouseEvent` would just surface
+         * TypeScript's own lib.dom.d.ts internals, which isn't what anyone
+         * wants to see in a props table.
+         */
+        parameters?: ParameterDescriptor[];
+        /**
+         * Present alongside `parameters` — the call signature's return type,
+         * expanded via `properties` under the same user-defined-only rule.
+         */
+        returnType?: FunctionTypePart;
+    };
+    description?: string;
+    /** From an `@default` jsdoc tag, e.g. `@default 3` -> "3" */
+    defaultValue?: {
+        value: string;
+    };
+}
+export interface ParameterDescriptor {
+    name: string;
+    required: boolean;
+    type: FunctionTypePart;
+}
+interface FunctionTypePart {
+    name: string;
+    /** Same rule as `PropDescriptor.type.properties` — only expanded for user-defined types, never for a built-in like `MouseEvent`. */
+    properties?: Record<string, PropDescriptor>;
+}
+export interface UnionBranch {
+    /** The literal discriminant prop shared across all branches, if one exists (e.g. `type: 'a'`). */
+    discriminant?: {
+        name: string;
+        value: string;
+    };
+    props: Record<string, PropDescriptor>;
+}
+export interface Documentation {
+    /** Name of the exported component/props type */
+    displayName: string;
+    description?: string;
+    /**
+     * Flattened prop set. When the top-level Props type is itself a
+     * union of object shapes, this is only the properties common to
+     * every branch (often empty) — variant-specific props, including
+     * their jsdoc, live in `elements` instead. This is the exact gap
+     * plain react-docgen has for a top-level union Props type: it
+     * reports the flattened set and drops per-variant jsdoc entirely.
+     */
+    props: Record<string, PropDescriptor>;
+    /**
+     * Present only when the top-level Props type is a union of object
+     * shapes (e.g. `type Props = AProps | BProps | ...`) — one entry
+     * per branch, each with its own resolved props and jsdoc intact.
+     */
+    elements?: UnionBranch[];
+}
+export {};

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/utils/jsdoc.d.ts

@@ -0,0 +1,4 @@
+import ts from 'typescript';
+export declare function getSymbolDescription(symbol: ts.Symbol, checker: ts.TypeChecker): string | undefined;
+/** Reads an `@default <value>` jsdoc tag off a symbol, e.g. `@default 3` -> "3". */
+export declare function getDefaultValueTag(symbol: ts.Symbol, checker: ts.TypeChecker): string | undefined;

package/dist/utils/jsdoc.js

@@ -0,0 +1,14 @@
+import ts from 'typescript';
+export function getSymbolDescription(symbol, checker) {
+    const parts = symbol.getDocumentationComment(checker);
+    const text = ts.displayPartsToString(parts).trim();
+    return text.length > 0 ? text : undefined;
+}
+/** Reads an `@default <value>` jsdoc tag off a symbol, e.g. `@default 3` -> "3". */
+export function getDefaultValueTag(symbol, checker) {
+    const tag = symbol.getJsDocTags(checker).find((t) => t.name === 'default');
+    if (!tag)
+        return undefined;
+    const text = tag.text ? ts.displayPartsToString(tag.text).trim() : '';
+    return text.length > 0 ? text : undefined;
+}

package/dist/utils/truncateTypeName.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Caps a rendered type-name string (`checker.typeToString(...)` output)
+ * at `maxLength` characters, replacing the overflow with a single `…`.
+ *
+ * `checker.typeToString` has no length limit of its own — a utility-type
+ * chain like `JssSupportedProperty<Pick<RheaTextProps, "content" |
+ * "ariaLabel" | "semanticTag" | ...>>` can run to hundreds of characters,
+ * which overflows fixed-width UI (e.g. Storybook's ArgsTable) instead of
+ * wrapping. Truncating here, once, at the source keeps every consumer of
+ * `Documentation` simple — no repeated CSS `text-overflow` workarounds
+ * downstream, and the same cap applies whether the value ends up in a
+ * table cell, a tooltip, or a JSON dump.
+ *
+ * `maxLength` of `Infinity` (or any falsy/`<= 0` value skipped by the
+ * caller) disables truncation entirely.
+ */
+export declare function truncateTypeName(name: string, maxLength: number): string;

package/dist/utils/truncateTypeName.js

@@ -0,0 +1,23 @@
+/**
+ * Caps a rendered type-name string (`checker.typeToString(...)` output)
+ * at `maxLength` characters, replacing the overflow with a single `…`.
+ *
+ * `checker.typeToString` has no length limit of its own — a utility-type
+ * chain like `JssSupportedProperty<Pick<RheaTextProps, "content" |
+ * "ariaLabel" | "semanticTag" | ...>>` can run to hundreds of characters,
+ * which overflows fixed-width UI (e.g. Storybook's ArgsTable) instead of
+ * wrapping. Truncating here, once, at the source keeps every consumer of
+ * `Documentation` simple — no repeated CSS `text-overflow` workarounds
+ * downstream, and the same cap applies whether the value ends up in a
+ * table cell, a tooltip, or a JSON dump.
+ *
+ * `maxLength` of `Infinity` (or any falsy/`<= 0` value skipped by the
+ * caller) disables truncation entirely.
+ */
+export function truncateTypeName(name, maxLength) {
+    if (maxLength === Infinity || name.length <= maxLength)
+        return name;
+    if (maxLength <= 1)
+        return '…';
+    return `${name.slice(0, maxLength - 1)}…`;
+}