react-props-parser 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tural Hajiyev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,158 @@
+# react-props-parser
+
+It's a typescript-aware props parser for React projects, built on the Typescript compiler API.
+
+## Motivation
+
+Storybook works fine with React and Typescript, but once the types get complex, ArgTable can't parse them fully. A few issues I ran into were:
+
+- jsdoc for props not showing up in Storybook at all
+- some types described as a union instead of the interface name
+- an interface name shown, but no way to see the actual structure of the type
+- with union types, jsdocs disappearing entirely (the value itself comes through, but if a prop is optional, consumers have no way of seeing that)
+
+It becomes a bigger issue when consumers need to see the props and end up having to open a code editor and go find the type definition in the library themselves.
+
+While digging into this, I realized Storybook actually uses two different parsers under the hood — `react-docgen` and `react-docgen-typescript`.
+
+They work fine up to a point, but often you hit a wall, need to start overriding argTypes by hand, and end up with two sources of truth (the type files and Storybook itself).
+
+To fix this, I decided to use Claude Code and try writing my own parser to see if it could be solved properly.
+
+That's how this journey started.
+
+## Comparison with react-docgen and react-docgen-typescript
+
+| Feature | react-docgen | react-docgen-typescript | react-props-parser |
+| ----- | ----- | ----- | ----- |
+| Primitive properties | renders type | renders type | renders type |
+| Named interface | renders only name of interface (unable to see the structure) | renders only name of interface (unable to see the structure) | renders name of interface, clickable to see the structure of the interface |
+| Array of named interface | same limitation as previous one | same limitation as previous one | works the same as previous one |
+| Anonymous interface | renders structure of interface as text | renders structure of interface as text | renders clickable Props interface, click to see the structure |
+| Array of anonymous interfaces | same limitation as previous one | same limitation as previous one | works the same as previous one |
+| Union primitives | renders 'union' keyword | renders name of each type | renders name of each type |
+| Union interfaces | renders 'union' keyword | renders name of interfaces | renders clickable names of interfaces, click to see the type of each |
+| Nested interfaces | shows only name of interface | shows only name of interface | clickable name of interface, click to see the structure |
+| Utility functions (Pick, Omit, Partial, Required) | renders name of utility function ('Pick', 'Omit', etc.) | renders the definition, e.g. `Pick<FirstAction, "type">` | renders clickable definition, click to see the structure |
+| Function with interface call signature | renders only name of the interface | renders only name of the interface | renders name of the interface with popup to show arguments and return type | 
+| Named function type | renders string with arguments and return type | renders string with arguments and return type | renders name of interface, with popup to show function arguments and return type | 
+| Anonymous function | renders string with arguments and return type | renders string with arguments and return type | renders clickable string to show detailed type | 
+| Anonymous function with interface argument | renders string with name of interface | renders string with name of interface | renders clickable string with popup to show structure of interface | 
+| forwardRef | same output with above mentioned details | same output with above mentioned details | same output with above mentioned details |
+| HOC | unable to render props | unable to render props | renders all props of the main component |
+| HOC with extra props | renders only extra props | renders only extra props | renders all props of the main component and extra props |
+
+Here is the visual version of comparison of these 3 tools (from left to right: react-docgen, react-docgen-typescript, react-props-parser):
+
+Basic Component:
+
+![Comparison-1](./comparison-1.png)
+
+With HOC:
+
+![Comparison-2](./comparison-2.png)
+
+## Quick start
+
+Most people use this through the Vite or webpack integration below to get
+Storybook's Controls panel working properly — jump to whichever builder you
+use. If you just want the parsed props as JSON, call `parse()` directly:
+
+## Using it with Storybook + Vite
+
+```bash
+npm install --save-dev react-props-parser
+```
+
+In `.storybook/main.ts`:
+
+```ts
+import type { StorybookConfig } from '@storybook/react-vite';
+import { viteLoader } from 'react-props-parser/vite';
+
+const config: StorybookConfig = {
+  framework: '@storybook/react-vite',
+  addons: [
+    '@storybook/addon-essentials',
+    // Registers a Storybook argTypesEnhancer that hides Controls fields
+    // from non-active union branches and fills in branch-specific
+    // descriptions — runs automatically for every story.
+    'react-props-parser/vite/preset',
+  ],
+  typescript: {
+    // Turn off Storybook's built-in docgen — react-props-parser supplies
+    // __docgenInfo itself via the plugin below.
+    reactDocgen: false,
+  },
+  async viteFinal(viteConfig) {
+    viteConfig.plugins ??= [];
+    // Pass options to viteLoader() to configure parsing, e.g. raise
+    // (or Infinity to disable) the 50-char default cap on rendered
+    // type-name strings like `Pick<Foo, "a" | "b" | ...>`.
+    viteConfig.plugins.push(viteLoader({ maxTypeNameLength: 80 }));
+    return viteConfig;
+  },
+};
+
+export default config;
+```
+
+## Using it with Storybook + webpack
+
+```bash
+npm install --save-dev react-props-parser
+```
+
+In `.storybook/main.ts`:
+
+```ts
+import type { StorybookConfig } from '@storybook/react-webpack5';
+
+const config: StorybookConfig = {
+  framework: '@storybook/react-webpack5',
+  addons: [
+    '@storybook/addon-essentials',
+    // Same preset used by the Vite setup — it's builder-agnostic.
+    'react-props-parser/vite/preset',
+  ],
+  typescript: {
+    reactDocgen: false,
+  },
+  webpackFinal: async (webpackConfig) => {
+    webpackConfig.module ??= { rules: [] };
+    webpackConfig.module.rules ??= [];
+    webpackConfig.module.rules.push({
+      test: /\.tsx$/,
+      exclude: /node_modules/,
+      enforce: 'pre',
+      // `options` here is react-props-parser's own ParseOptions, forwarded
+      // to every parse() call — same fields as the Vite loader above.
+      use: [{ loader: 'react-props-parser/webpack', options: { maxTypeNameLength: 80 } }],
+    });
+    return webpackConfig;
+  },
+};
+
+export default config;
+```
+
+Either way, once wired in, every exported component in a `.tsx` file gets a
+`Component.__docgenInfo` static property attached at build time — the same
+convention `react-docgen-typescript`-based tooling already reads — so
+Storybook's addon-docs and Controls panel pick it up with no other changes.
+
+## Configuration
+
+Both `viteLoader(options)` and the webpack loader's rule `options` take the
+same `ParseOptions` object accepted by `parse()` directly:
+
+| Option              | Default | What it does                                                                                     |
+| -------------------- | ------- | -------------------------------------------------------------------------------------------------- |
+| `maxTypeNameLength`  | `50`    | Caps a rendered type-name string (a prop's type, a union branch, a fallback displayName) at N characters, truncating with `…`. Set to `Infinity` to disable. |
+| `maxDepth`           | `2`     | How many levels of nested object props get expanded into `type.properties`.                         |
+
+```ts
+import { parse } from 'react-props-parser';
+
+const doc = parse('./Button.tsx', { maxTypeNameLength: 80 });
+```

package/dist/extractProperties.d.ts

@@ -0,0 +1,23 @@
+import ts from 'typescript';
+import type { PropDescriptor } from './types.js';
+import { type ResolvedParseOptions } from './options.js';
+/**
+ * Given an already-resolved ts.Type, walks `checker.getPropertiesOfType`,
+ * converting each property symbol into a PropDescriptor.
+ * `checker.getPropertiesOfType` already flattens `extends`/intersection
+ * chains, so no separate extends/intersection handler is needed. Takes
+ * a raw ts.Type (rather than a declaration node) so it works equally
+ * for the top-level Props type, each branch of a union.ts split, and a
+ * recursive nested-object expansion below.
+ *
+ * A prop whose type is itself a plain object shape (a named interface
+ * reference like `user: AvatarUser`, or an inline object type) gets
+ * expanded into `type.properties`, recursively, up to `maxDepth`
+ * levels (default 2) — deep enough that an interface-inside-an-
+ * interface actually shows its own nested shape, but bounded so a
+ * self-referential or very deep type can't blow up the output. `seen`
+ * additionally guards against infinite recursion on a type that
+ * refers back to one already being expanded in the current chain
+ * (e.g. `interface TreeNode { children: TreeNode[] }`).
+ */
+export declare function extractPropertiesFromType(type: ts.Type, contextNode: ts.Node, checker: ts.TypeChecker, depth?: number, options?: ResolvedParseOptions, seen?: ReadonlySet<ts.Type>): Record<string, PropDescriptor>;

package/dist/extractProperties.js

@@ -0,0 +1,213 @@
+import ts from 'typescript';
+import { getSymbolDescription, getDefaultValueTag } from './utils/jsdoc.js';
+import { resolveUnionBranches } from './handlers/union.js';
+import { truncateTypeName } from './utils/truncateTypeName.js';
+import { DEFAULT_PARSE_OPTIONS } from './options.js';
+/** Summary label shown in place of an inline/unnamed object type's own printed shape — see the comment at its use site below. */
+const ANONYMOUS_OBJECT_LABEL = 'Props';
+/**
+ * Given an already-resolved ts.Type, walks `checker.getPropertiesOfType`,
+ * converting each property symbol into a PropDescriptor.
+ * `checker.getPropertiesOfType` already flattens `extends`/intersection
+ * chains, so no separate extends/intersection handler is needed. Takes
+ * a raw ts.Type (rather than a declaration node) so it works equally
+ * for the top-level Props type, each branch of a union.ts split, and a
+ * recursive nested-object expansion below.
+ *
+ * A prop whose type is itself a plain object shape (a named interface
+ * reference like `user: AvatarUser`, or an inline object type) gets
+ * expanded into `type.properties`, recursively, up to `maxDepth`
+ * levels (default 2) — deep enough that an interface-inside-an-
+ * interface actually shows its own nested shape, but bounded so a
+ * self-referential or very deep type can't blow up the output. `seen`
+ * additionally guards against infinite recursion on a type that
+ * refers back to one already being expanded in the current chain
+ * (e.g. `interface TreeNode { children: TreeNode[] }`).
+ */
+export function extractPropertiesFromType(type, contextNode, checker, depth = 0, options = DEFAULT_PARSE_OPTIONS, seen = new Set()) {
+    const { maxDepth } = options;
+    const props = {};
+    for (const symbol of checker.getPropertiesOfType(type)) {
+        // Read optionality off the checker-resolved symbol flag, not the
+        // original AST declaration's `?` token. For a plain interface prop
+        // those agree, but a mapped utility type (Partial<T>, Required<T>,
+        // Pick<T, K>, ...) changes optionality on the *resolved* type
+        // without touching the original declaration node — checking
+        // questionToken there would silently report Partial<T>'s props as
+        // required and Required<T>'s props as still optional.
+        const required = !(symbol.flags & ts.SymbolFlags.Optional);
+        let propType = checker.getTypeOfSymbolAtLocation(symbol, contextNode);
+        // Optional props (`foo?: T`) resolve via the checker as `T | undefined`.
+        // `required` already conveys optionality, so strip the implicit
+        // undefined member to match react-docgen-typescript's convention and
+        // avoid redundant noise in the ArgsTable.
+        if (!required) {
+            propType = checker.getNonNullableType(propType);
+        }
+        const defaultValue = getDefaultValueTag(symbol, checker);
+        const elements = resolveUnionBranches(propType, contextNode, checker, options);
+        // For an array prop (`tags: Tag[]`), the interesting shape to expand
+        // is the *element* type, not the array itself — `checker.
+        // getPropertiesOfType` on an array type would just walk Array.prototype
+        // (length, push, map, ...), which is exactly the noise consumers
+        // don't want surfaced. Array<T>/ReadonlyArray<T> are always generic
+        // type references, so their element type is their sole type argument.
+        const arrayElementType = checker.isArrayType(propType)
+            ? checker.getTypeArguments(propType)[0]
+            : undefined;
+        const expandableType = arrayElementType ?? propType;
+        // A union already gets its own per-branch breakdown via `elements`
+        // above; `properties` is for the simpler case of a single nested
+        // object shape, e.g. `user: AvatarUser` or `tags: Tag[]`. type.name
+        // stays the raw reference ("AvatarUser", "Tag[]") so the type
+        // identity is still visible — this is the expanded shape alongside
+        // it, not a replacement. For `tags: Tag[]` this is Tag's own
+        // properties, not a property named after an array index.
+        const properties = !elements &&
+            expandableType &&
+            depth < maxDepth &&
+            !seen.has(expandableType) &&
+            isExpandableObjectType(expandableType, checker)
+            ? extractPropertiesFromType(expandableType, contextNode, checker, depth + 1, options, new Set(seen).add(expandableType))
+            : undefined;
+        // A function-shaped prop (named function type alias, `interface`
+        // call signature, or inline `(...) => ...`) — not expanded via
+        // `properties` above (isExpandableObjectType excludes call
+        // signatures), but its parameters and return type are still worth
+        // breaking down, same idea one level in.
+        const signature = !elements && !properties && expandableType && expandableType.getCallSignatures().length > 0
+            ? extractFunctionSignature(expandableType, contextNode, checker, depth, options, seen)
+            : undefined;
+        // An inline, unnamed object type (`controls: { visible: boolean; ... }`,
+        // as opposed to a named interface/type-alias reference like `user:
+        // AvatarUser`) has no real identity to show as a summary — TS's own
+        // printed form is just the whole shape crammed onto one line, which
+        // truncateTypeName then cuts off mid-field ("{ visible: boolean;
+        // label: string; disabl…"). There's nothing useful about that as a
+        // *name*, and it duplicates `properties` below anyway, so swap it
+        // for a short, generic placeholder instead of truncating it — the
+        // real shape is still one click away via `properties`. Keeps the
+        // `[]` suffix for an anonymous-object array element so the summary
+        // doesn't silently drop that it's a list.
+        const isAnonymousObject = !!properties && isAnonymousObjectType(expandableType);
+        const typeName = isAnonymousObject
+            ? arrayElementType
+                ? `${ANONYMOUS_OBJECT_LABEL}[]`
+                : ANONYMOUS_OBJECT_LABEL
+            : truncateTypeName(checker.typeToString(propType), options.maxTypeNameLength);
+        props[symbol.name] = {
+            name: symbol.name,
+            required,
+            type: {
+                name: typeName,
+                ...(elements ? { elements } : {}),
+                ...(properties ? { properties } : {}),
+                ...(signature?.parameters ? { parameters: signature.parameters } : {}),
+                ...(signature?.returnType ? { returnType: signature.returnType } : {}),
+            },
+            description: getSymbolDescription(symbol, checker),
+            ...(defaultValue !== undefined ? { defaultValue: { value: defaultValue } } : {}),
+        };
+    }
+    return props;
+}
+/**
+ * Breaks a function-shaped type's (first) call signature down into its
+ * parameters and return type, expanding either the same way a regular
+ * object prop is — but only when that type is declared in the user's
+ * own project. `checker.getPropertiesOfType` on a param or return type
+ * of `MouseEvent` would happily walk lib.dom.d.ts's ~30 fields; nobody
+ * asking about their own `onSelect: (event: SelectionEvent) => Result`
+ * wants that, but they very much do want `SelectionEvent`'s/`Result`'s
+ * own shape expanded since those are theirs.
+ *
+ * Only the first signature is used — overloaded function types are rare
+ * for a props position, and picking one deterministically beats trying
+ * to merge/pick among several.
+ */
+function extractFunctionSignature(type, contextNode, checker, depth, options, seen) {
+    const signature = type.getCallSignatures()[0];
+    if (!signature)
+        return undefined;
+    const expandPart = (partType) => {
+        const { maxDepth } = options;
+        const properties = depth < maxDepth &&
+            !seen.has(partType) &&
+            isExpandableObjectType(partType, checker) &&
+            isUserDefinedType(partType)
+            ? extractPropertiesFromType(partType, contextNode, checker, depth + 1, options, new Set(seen).add(partType))
+            : undefined;
+        return {
+            name: truncateTypeName(checker.typeToString(partType), options.maxTypeNameLength),
+            ...(properties ? { properties } : {}),
+        };
+    };
+    const parameters = signature.parameters.length === 0
+        ? undefined
+        : signature.parameters.map((paramSymbol) => {
+            const paramType = checker.getTypeOfSymbolAtLocation(paramSymbol, contextNode);
+            const declaration = paramSymbol.valueDeclaration;
+            const required = !declaration?.questionToken && !declaration?.initializer;
+            return { name: paramSymbol.name, required, type: expandPart(paramType) };
+        });
+    // Always reported, even for `void`/`undefined`/`any`/`unknown` — the
+    // signature isn't complete without it, and a caller reading a
+    // function-shaped prop's full type wants to see "=> void" rather than
+    // have the return silently vanish. `expandPart` naturally adds no
+    // `properties` for these anyway, since none of them are an
+    // expandable object shape.
+    const returnType = expandPart(checker.getReturnTypeOfSignature(signature));
+    return { parameters, returnType };
+}
+/**
+ * True when every declaration of this type's symbol lives outside
+ * TypeScript's own bundled lib files (lib.dom.d.ts, lib.es5.d.ts, ...) —
+ * that's how a built-in like `MouseEvent` or `Event` is told apart from
+ * an interface the user actually wrote, regardless of what it's named.
+ * A type with no declarations (an anonymous literal) counts as
+ * user-defined — there's nothing built-in about it.
+ */
+function isUserDefinedType(type) {
+    const symbol = type.symbol ?? type.aliasSymbol;
+    const declarations = symbol?.getDeclarations();
+    if (!declarations || declarations.length === 0)
+        return true;
+    return declarations.every((decl) => !isBuiltinLibFile(decl.getSourceFile().fileName));
+}
+function isBuiltinLibFile(fileName) {
+    return /[/\\]typescript[/\\]lib[/\\]lib\.[^/\\]+\.d\.ts$/.test(fileName);
+}
+/**
+ * True for a plain object shape worth expanding — a named interface/
+ * type-alias reference or an inline object literal type with at least
+ * one property, and not a function, array, or other built-in with its
+ * own (usually large, uninteresting) property set.
+ */
+function isExpandableObjectType(type, checker) {
+    if (!(type.getFlags() & ts.TypeFlags.Object))
+        return false;
+    if (type.getCallSignatures().length > 0)
+        return false;
+    const symbolName = type.symbol?.name;
+    if (symbolName === 'Array' || symbolName === 'ReadonlyArray' || symbolName === 'Date') {
+        return false;
+    }
+    return checker.getPropertiesOfType(type).length > 0;
+}
+/**
+ * True for an object type with no name to show. A genuinely inline
+ * `{ ... }` written directly at the property position still gets a
+ * symbol from the checker — it's just the synthetic one every type
+ * literal gets, named `ts.InternalSymbolName.Type` ("__type"), not a
+ * real declared name — so checking for *a* symbol isn't enough; this
+ * checks for a *named* one. `aliasSymbol` is checked separately since
+ * `type Foo = { ... }` carries the same symbol-less underlying type but
+ * has a real name one level up, via the alias rather than the type
+ * itself — both it and a named interface reference print their own
+ * name via `checker.typeToString` and should keep it.
+ */
+function isAnonymousObjectType(type) {
+    const symbol = type.getSymbol();
+    const hasRealSymbolName = !!symbol && symbol.name !== ts.InternalSymbolName.Type;
+    return !hasRealSymbolName && !type.aliasSymbol;
+}

package/dist/handlers/union.d.ts

@@ -0,0 +1,15 @@
+import ts from 'typescript';
+import type { UnionBranch } from '../types.js';
+import { type ResolvedParseOptions } from '../options.js';
+/**
+ * Detects a "union of objects" prop type (e.g.
+ * `{ type: 'a'; foo: string } | { type: 'b'; bar: number }`) and, if
+ * one is found, splits it into per-branch prop sets — this is the
+ * actual differentiator vs. react-docgen-typescript, which only
+ * stringifies the whole union and stops there.
+ *
+ * Returns undefined for anything that isn't a union of object types
+ * (primitive unions like `'a' | 'b'`, single object types, etc.) —
+ * in that case the caller just keeps the flattened `type.name` string.
+ */
+export declare function resolveUnionBranches(type: ts.Type, contextNode: ts.Node, checker: ts.TypeChecker, options?: ResolvedParseOptions): UnionBranch[] | undefined;

package/dist/handlers/union.js

@@ -0,0 +1,71 @@
+import ts from 'typescript';
+// Circular import: extractProperties.ts imports resolveUnionBranches
+// from this file. Safe in ESM since neither side calls the other at
+// module-evaluation time — only inside function bodies, by which
+// point both modules have finished initializing.
+import { extractPropertiesFromType } from '../extractProperties.js';
+import { DEFAULT_PARSE_OPTIONS } from '../options.js';
+import { truncateTypeName } from '../utils/truncateTypeName.js';
+/**
+ * Detects a "union of objects" prop type (e.g.
+ * `{ type: 'a'; foo: string } | { type: 'b'; bar: number }`) and, if
+ * one is found, splits it into per-branch prop sets — this is the
+ * actual differentiator vs. react-docgen-typescript, which only
+ * stringifies the whole union and stops there.
+ *
+ * Returns undefined for anything that isn't a union of object types
+ * (primitive unions like `'a' | 'b'`, single object types, etc.) —
+ * in that case the caller just keeps the flattened `type.name` string.
+ */
+export function resolveUnionBranches(type, contextNode, checker, options = DEFAULT_PARSE_OPTIONS) {
+    if (!type.isUnion())
+        return undefined;
+    const branches = type.types;
+    const isObjectUnion = branches.every((t) => !t.isLiteral() && !!(t.getFlags() & ts.TypeFlags.Object));
+    if (!isObjectUnion)
+        return undefined;
+    const discriminantName = findDiscriminant(branches, checker);
+    return branches.map((branchType) => {
+        const branchProps = extractPropertiesFromType(branchType, contextNode, checker, 0, options);
+        const discriminant = discriminantName
+            ? {
+                name: discriminantName,
+                value: truncateTypeName(literalPropValue(branchType, discriminantName, checker), options.maxTypeNameLength),
+            }
+            : undefined;
+        return {
+            ...(discriminant ? { discriminant } : {}),
+            props: branchProps,
+        };
+    });
+}
+/**
+ * A discriminant is a property present in every branch whose value is
+ * a distinct literal (string/number/boolean) in each one — the common
+ * `type: 'a'` / `type: 'b'` pattern. Picks the first property that
+ * qualifies across all branches; returns undefined if none does.
+ */
+function findDiscriminant(branches, checker) {
+    if (branches.length === 0)
+        return undefined;
+    const firstBranchProps = checker.getPropertiesOfType(branches[0]).map((s) => s.name);
+    for (const propName of firstBranchProps) {
+        const valuesAreAllLiteral = branches.every((branch) => {
+            const symbol = checker.getPropertyOfType(branch, propName);
+            if (!symbol)
+                return false;
+            const propType = checker.getTypeOfSymbolAtLocation(symbol, symbol.valueDeclaration ?? branch.symbol.valueDeclaration);
+            return propType.isLiteral();
+        });
+        if (valuesAreAllLiteral)
+            return propName;
+    }
+    return undefined;
+}
+function literalPropValue(branch, propName, checker) {
+    const symbol = checker.getPropertyOfType(branch, propName);
+    if (!symbol)
+        return '';
+    const propType = checker.getTypeOfSymbolAtLocation(symbol, symbol.valueDeclaration ?? branch.symbol.valueDeclaration);
+    return checker.typeToString(propType);
+}

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+import { type ParseOptions } from './options.js';
+import type { Documentation } from './types.js';
+export type { Documentation, PropDescriptor, UnionBranch } from './types.js';
+export type { ParseOptions } from './options.js';
+/**
+ * Entry point: TS/TSX file path in, Documentation JSON out.
+ *
+ * `options` lets consumers tune output shape/size — e.g.
+ * `{ maxTypeNameLength: 80 }` to raise (or `Infinity` to disable) the
+ * default 50-character cap on rendered type-name strings, or
+ * `maxDepth` to change how many levels of nested object props get
+ * expanded. See {@link ParseOptions}.
+ */
+export declare function parse(filePath: string, options?: ParseOptions): Documentation;

package/dist/index.js

@@ -0,0 +1,93 @@
+import ts from 'typescript';
+import { createProgramForFile } from './program.js';
+import { resolvePropsType } from './resolvePropsType.js';
+import { extractPropertiesFromType } from './extractProperties.js';
+import { resolveUnionBranches } from './handlers/union.js';
+import { truncateTypeName } from './utils/truncateTypeName.js';
+import { resolveOptions } from './options.js';
+/**
+ * Entry point: TS/TSX file path in, Documentation JSON out.
+ *
+ * `options` lets consumers tune output shape/size — e.g.
+ * `{ maxTypeNameLength: 80 }` to raise (or `Infinity` to disable) the
+ * default 50-character cap on rendered type-name strings, or
+ * `maxDepth` to change how many levels of nested object props get
+ * expanded. See {@link ParseOptions}.
+ */
+export function parse(filePath, options) {
+    const resolvedOptions = resolveOptions(options);
+    const program = createProgramForFile(filePath);
+    const sourceFile = program.getSourceFile(filePath);
+    if (!sourceFile) {
+        throw new Error(`Could not load source file: ${filePath}`);
+    }
+    const checker = program.getTypeChecker();
+    const resolved = resolvePropsType(sourceFile, checker, resolvedOptions);
+    if (!resolved) {
+        throw new Error(`No "Props" interface or type alias found in: ${filePath}`);
+    }
+    const { type: topLevelType, contextNode, displayName, docSymbol } = resolved;
+    // When the top-level Props type is itself a union of object shapes
+    // (`export type InputProps = AProps | BProps | ...`), the flat
+    // `props` above is only the *intersection* of all branches — usually
+    // just the discriminant, with every variant-specific field (and its
+    // jsdoc) missing entirely. That's the exact gap plain react-docgen
+    // has, and it's what leaves Storybook's Controls panel showing only
+    // one row. `elements` carries the full per-branch breakdown; when
+    // present, it's also used to build a *union* (not intersection) flat
+    // `props` map below, so every field from every branch shows up in
+    // Controls, each keeping its own description where unambiguous.
+    const elements = resolveUnionBranches(topLevelType, contextNode, checker, resolvedOptions);
+    const props = elements
+        ? mergePropsAcrossBranches(elements, resolvedOptions)
+        : extractPropertiesFromType(topLevelType, contextNode, checker, 0, resolvedOptions);
+    const description = docSymbol
+        ? ts.displayPartsToString(docSymbol.getDocumentationComment(checker)).trim() || undefined
+        : undefined;
+    return {
+        displayName,
+        description,
+        props,
+        ...(elements ? { elements } : {}),
+    };
+}
+/**
+ * Builds the flat `props` map for a top-level union Props type as the
+ * *union* of every branch's own props (not the intersection TypeScript
+ * gives you natively) — this is what Storybook's Controls panel and
+ * other react-docgen-typescript-shaped consumers read, so it needs to
+ * carry every field, not just the shared discriminant.
+ *
+ * A field present in only one branch keeps that branch's description
+ * as-is (no ambiguity). A field present in multiple branches keeps its
+ * description only if every branch that has it agrees — otherwise it's
+ * dropped rather than concatenated into nonsense, same rule as before.
+ * `required` is true only if the field is present and required in
+ * every branch; a field that's optional or absent in even one branch
+ * isn't safe to treat as always-required.
+ */
+function mergePropsAcrossBranches(elements, options) {
+    const allNames = new Set();
+    for (const branch of elements) {
+        for (const name of Object.keys(branch.props))
+            allNames.add(name);
+    }
+    const result = {};
+    for (const name of allNames) {
+        const inBranches = elements
+            .map((branch) => branch.props[name])
+            .filter((p) => p !== undefined);
+        const descriptions = new Set(inBranches.map((p) => p.description));
+        const defaults = new Set(inBranches.map((p) => JSON.stringify(p.defaultValue)));
+        const typeNames = [...new Set(inBranches.map((p) => p.type.name))];
+        const required = inBranches.length === elements.length && inBranches.every((p) => p.required);
+        result[name] = {
+            name,
+            required,
+            type: { name: truncateTypeName(typeNames.join(' | '), options.maxTypeNameLength) },
+            description: descriptions.size === 1 ? [...descriptions][0] : undefined,
+            defaultValue: defaults.size === 1 ? inBranches[0]?.defaultValue : undefined,
+        };
+    }
+    return result;
+}

package/dist/options.d.ts

@@ -0,0 +1,24 @@
+/** Consumer-facing configuration for {@link parse}. */
+export interface ParseOptions {
+    /**
+     * Maximum characters allowed in a rendered type-name string (a prop's
+     * `type.name`, a union branch's merged type text, or the component
+     * displayName's stringified-type fallback) before it's truncated with
+     * a trailing `…`. Long utility-type chains like
+     * `JssSupportedProperty<Pick<RheaTextProps, "content" | "ariaLabel" |
+     * ...>>` otherwise render at full length and overflow fixed-width UI.
+     *
+     * Pass `Infinity` to disable truncation entirely.
+     *
+     * @default 50
+     */
+    maxTypeNameLength?: number;
+    /** How many levels of nested object props get expanded into `type.properties`. @default 2 */
+    maxDepth?: number;
+}
+export interface ResolvedParseOptions {
+    maxTypeNameLength: number;
+    maxDepth: number;
+}
+export declare const DEFAULT_PARSE_OPTIONS: ResolvedParseOptions;
+export declare function resolveOptions(options?: ParseOptions): ResolvedParseOptions;

package/dist/options.js

@@ -0,0 +1,10 @@
+export const DEFAULT_PARSE_OPTIONS = {
+    maxTypeNameLength: 50,
+    maxDepth: 2,
+};
+export function resolveOptions(options) {
+    return {
+        maxTypeNameLength: options?.maxTypeNameLength ?? DEFAULT_PARSE_OPTIONS.maxTypeNameLength,
+        maxDepth: options?.maxDepth ?? DEFAULT_PARSE_OPTIONS.maxDepth,
+    };
+}