react-props-parser 0.0.1

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "react-props-parser",
+  "version": "0.0.1",
+  "description": "TypeScript-aware React props parser: expands discriminated unions, unions of objects, and nested object props into structured data (via the TypeScript compiler API) instead of stringifying types like react-docgen-typescript does. Ships with a Vite plugin and a webpack loader for wiring the parsed docgen info into Storybook.",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "keywords": [
+    "react",
+    "docgen",
+    "react-docgen",
+    "typescript",
+    "storybook",
+    "props",
+    "documentation",
+    "vite-plugin",
+    "webpack-loader"
+  ],
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./vite": "./src/vite/index.js",
+    "./vite/preset": "./src/vite/preset.js",
+    "./webpack": "./src/webpack/index.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "src/vite",
+    "src/webpack",
+    "LICENSE"
+  ],
+  "license": "MIT",
+  "author": "Tural Hajiyev",
+  "homepage": "https://github.com/turalowski/react-props-parser#readme",
+  "bugs": "https://github.com/turalowski/react-props-parser/issues",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/turalowski/react-props-parser.git"
+  },
+  "workspaces": [
+    "examples"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepublishOnly": "npm run build",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "typescript": "^5.6.0"
+  },
+  "devDependencies": {
+    "vitest": "^2.1.0",
+    "@types/node": "^22.0.0",
+    "@types/react": "^18.3.0",
+    "react": "^18.3.0"
+  },
+  "allowScripts": {
+    "esbuild@0.21.5": true,
+    "fsevents@2.3.3": true,
+    "esbuild@0.28.2": true
+  }
+}

package/src/vite/argTypes.js

@@ -0,0 +1,32 @@
+/**
+ * Given a component's __docgenInfo (as produced by react-props-parser + our
+ * vite plugin) and the discriminant value a particular story uses
+ * (e.g. 'text'), returns a Storybook `argTypes` override that hides
+ * every field belonging to *other* branches.
+ *
+ * Storybook's Controls panel merges `meta.argTypes` (built from the
+ * full, unioned `docgenInfo.props`) with each story's own `argTypes`.
+ * A field can be hidden per-story via `table: { disable: true }` —
+ * this computes exactly that set from `elements`, so a "Text" story
+ * only shows text-branch fields and a "CheckboxGroup" story only
+ * shows checkbox-group fields, without hand-listing them per story.
+ */
+export function argTypesForVariant(docgenInfo, discriminantValue) {
+  const elements = docgenInfo?.elements;
+  if (!elements) return {};
+
+  const wanted = JSON.stringify(discriminantValue);
+  const branch = elements.find((e) => e.discriminant?.value === wanted);
+  if (!branch) return {};
+
+  const allowedNames = new Set(Object.keys(branch.props));
+  const overrides = {};
+
+  for (const name of Object.keys(docgenInfo.props)) {
+    if (!allowedNames.has(name)) {
+      overrides[name] = { table: { disable: true } };
+    }
+  }
+
+  return overrides;
+}

package/src/vite/argTypesEnhancer.js

@@ -0,0 +1,172 @@
+/**
+ * Storybook argTypesEnhancer + preview annotation in one file: this
+ * whole module gets bundled into the preview iframe (registered via
+ * previewAnnotations in preset.js), so `argTypesEnhancers` needs to be
+ * exported at the top level exactly like it would be from a project's
+ * own .storybook/preview.ts.
+ *
+ * Runs automatically for every story — no per-story wiring needed.
+ * Reads the rendering component's own __docgenInfo (attached by our
+ * vite plugin) and the story's args to figure out which union branch
+ * is active, then:
+ *  - hides every field that belongs to a different branch
+ *  - restores each visible field's branch-specific jsdoc description.
+ *    core's merged top-level `props` deliberately drops a field's
+ *    description when branches disagree on it (e.g. the discriminant
+ *    field itself, like `type`, usually has a different doc comment
+ *    per branch) rather than show the wrong text. Once we know which
+ *    branch is actually active, there's no ambiguity left, so we can
+ *    fill the correct one back in here.
+ */
+function rdrpArgTypesEnhancer(context) {
+  const docgenInfo = context.component?.__docgenInfo;
+  const elements = docgenInfo?.elements;
+  if (!elements || elements.length === 0) return context.argTypes;
+
+  const discriminantName = elements.find((e) => e.discriminant)?.discriminant?.name;
+  if (!discriminantName) return context.argTypes;
+
+  const currentValue = context.args?.[discriminantName] ?? context.initialArgs?.[discriminantName];
+  if (currentValue === undefined) return context.argTypes;
+
+  const branch = elements.find((e) => e.discriminant?.value === JSON.stringify(currentValue));
+  if (!branch) return context.argTypes;
+
+  const allowedNames = new Set(Object.keys(branch.props));
+  const argTypes = { ...context.argTypes };
+
+  for (const name of Object.keys(argTypes)) {
+    if (!allowedNames.has(name)) {
+      argTypes[name] = { ...argTypes[name], table: { ...argTypes[name]?.table, disable: true } };
+      continue;
+    }
+
+    const branchDescription = branch.props[name]?.description;
+    if (branchDescription && !argTypes[name]?.description) {
+      argTypes[name] = { ...argTypes[name], description: branchDescription };
+    }
+  }
+
+  return argTypes;
+}
+
+/**
+ * For a prop whose type resolved to a nested object shape (core's
+ * `type.properties`, e.g. `user: AvatarUser`, or `tags: Tag[]`) or a
+ * union of object shapes (`type.elements`, e.g. `action: LinkAction |
+ * ButtonAction`), Storybook's default Controls table would otherwise
+ * just show the bare reference name(s) as the Type column with no way
+ * to see the actual fields.
+ *
+ * Storybook's Type column supports a summary/detail pair —
+ * `table.type.summary` is the visible, clickable text; `table.type.
+ * detail` opens in a popover on click. This keeps summary as the
+ * original type name(s) (e.g. "AvatarUser", "Tag[]", or "LinkAction |
+ * ButtonAction") — clickable, recognizable — and puts the full
+ * expanded shape in detail, rendered recursively so an
+ * interface-inside-an-interface (core expands up to 2 levels) shows
+ * its own nested shape too, not just the outer one.
+ *
+ * Also disables Storybook's default interactive "object" control for
+ * every array-typed prop (`control: false`). react-docgen-typescript-
+ * shaped type names it can't otherwise classify (any named reference,
+ * including plain arrays like `Tag[]` or `string[]`) fall back to that
+ * generic control, which edits the *runtime* value via react-inspector
+ * — clicking its "show non-enumerable properties" toggle on an array
+ * value walks Array.prototype, surfacing push/pop/map/... as if they
+ * were editable fields. There's no safe/useful live-edit UI for an
+ * array here anyway, so this table.type.detail popover (read-only,
+ * static, no prototype involved) replaces it as the way to inspect the
+ * shape instead.
+ */
+function rdrpNestedShapeEnhancer(context) {
+  const props = context.component?.__docgenInfo?.props;
+  if (!props) return context.argTypes;
+
+  const argTypes = { ...context.argTypes };
+
+  for (const [name, prop] of Object.entries(props)) {
+    if (!argTypes[name]) continue;
+
+    const isArray = isArrayTypeName(prop.type?.name);
+    const detail = expandedShapeFor(prop);
+
+    argTypes[name] = {
+      ...argTypes[name],
+      ...(isArray ? { control: false } : {}),
+      ...(detail
+        ? { table: { ...argTypes[name].table, type: { summary: prop.type.name, detail } } }
+        : {}),
+    };
+  }
+
+  return argTypes;
+}
+
+/** True for a TS-printed array type name — "Tag[]", "string[]", "readonly Tag[]" — covering every form checker.typeToString produces for an array type. */
+function isArrayTypeName(name) {
+  return typeof name === 'string' && /\[\]$/.test(name);
+}
+
+/**
+ * Renders the expanded shape for one PropDescriptor — its `type.
+ * properties` (wrapped in `Array<...>` when the prop's own type name is
+ * an array, e.g. `tags: Tag[]` renders as `Array<{ ... }>`, not a bare
+ * `{ ... }` that reads as if `tags` held a single Tag) or its `type.
+ * elements` (each union branch's shape, joined with ` | `). Returns
+ * undefined when there's no structure to expand, e.g. a plain
+ * `string[]` — a regular array has nothing more useful to show than
+ * its type name, which is already the clickable-free (non-object-
+ * control) Type column text.
+ */
+function expandedShapeFor(prop, indent = 0) {
+  if (prop.type?.properties) {
+    const shape = renderShape(prop.type.properties, indent);
+    return isArrayTypeName(prop.type.name) ? `Array<${shape}>` : shape;
+  }
+  if (prop.type?.elements) {
+    return prop.type.elements.map((branch) => renderShape(branch.props, indent)).join(' | ');
+  }
+  if (prop.type?.parameters || prop.type?.returnType) {
+    return renderFunctionSignature(prop.type.parameters, prop.type.returnType, indent);
+  }
+  return undefined;
+}
+
+/**
+ * Renders a function-shaped prop's (core's `type.parameters`/`type.
+ * returnType`) full call signature as `(param: Type, ...) => Return` —
+ * each part's own type is expanded inline via `renderShape` when core
+ * resolved it to a nested object shape (a user-defined interface, never
+ * a built-in like `MouseEvent`), the same way a plain object prop's
+ * nested fields are. A `void`/`undefined`/`any`/`unknown` return (core
+ * omits `returnType` for those) falls back to the generic `...`, same
+ * as before this had a real return type to show.
+ */
+function renderFunctionSignature(parameters, returnType, indent) {
+  const params = (parameters ?? [])
+    .map((p) => {
+      const valueType = p.type?.properties ? renderShape(p.type.properties, indent) : p.type?.name ?? 'unknown';
+      return `${p.name}${p.required ? '' : '?'}: ${valueType}`;
+    })
+    .join(', ');
+
+  const returns = returnType?.properties ? renderShape(returnType.properties, indent) : returnType?.name ?? '...';
+
+  return `(${params}) => ${returns}`;
+}
+
+/** Recursively renders a props map as a pretty-printed object shape, expanding nested properties/elements at any depth core resolved. */
+function renderShape(properties, indent = 0) {
+  const pad = '  '.repeat(indent + 1);
+  const closePad = '  '.repeat(indent);
+
+  const fields = Object.values(properties).map((p) => {
+    const valueType = expandedShapeFor(p, indent + 1) ?? p.type?.name ?? 'unknown';
+    return `${pad}${p.name}${p.required ? '' : '?'}: ${valueType}`;
+  });
+
+  return `{\n${fields.join(';\n')};\n${closePad}}`;
+}
+
+export const argTypesEnhancers = [rdrpArgTypesEnhancer, rdrpNestedShapeEnhancer];

package/src/vite/index.js

@@ -0,0 +1,101 @@
+import { parse } from 'react-props-parser';
+
+export { argTypesForVariant } from './argTypes.js';
+
+/**
+ * Minimal Vite plugin: for each .tsx file, runs it through react-props-parser's
+ * parse() and appends `ComponentName.__docgenInfo = {...}` to the
+ * transformed module — the same static-property convention Storybook's
+ * addon-docs / ArgsTable already reads from
+ * @joshwooding/vite-plugin-react-docgen-typescript, so no Storybook-side
+ * changes are needed to see the result.
+ *
+ * Dummy-sandbox scope: finds component names via a simple regex
+ * (`export function X` / `export const X =` / `export { X as Y }`)
+ * rather than a real AST walk — good enough to prove the wiring end to
+ * end, but see findComponentNames' own comment for a real limitation
+ * this has on files with multiple differently-scoped exports.
+ *
+ * @param {import('react-props-parser').ParseOptions} [options] Forwarded
+ * as-is to every `parse()` call — e.g. `viteLoader({ maxTypeNameLength: 80 })`.
+ */
+export function viteLoader(options) {
+  return {
+    name: 'rdrp-docgen',
+    enforce: 'pre',
+    transform(code, id) {
+      if (!id.endsWith('.tsx') || id.includes('node_modules') || id.includes('.stories.')) {
+        return null;
+      }
+
+      // Only inject when we found real exported component identifiers
+      // in the source. Never fall back to documentation.displayName as
+      // an injection target — parse() will happily resolve a "props
+      // type" for a hook or utility function too (anything with an
+      // object-shaped parameter), and its displayName in that case can
+      // be an arbitrary type string like "Partial<ConfigProps> |
+      // undefined" — not a valid JS identifier. Splicing that into
+      // generated code produces a syntax error that breaks the whole
+      // build, not just a skipped file, so this check is load-bearing,
+      // not an optimization.
+      const componentNames = findComponentNames(code);
+      if (componentNames.length === 0) return null;
+
+      let documentation;
+      try {
+        documentation = parse(id, options);
+      } catch {
+        // No Props type in this file (e.g. not a component file) — skip silently.
+        return null;
+      }
+
+      // Attaches to *every* plausible exported binding, not just one —
+      // a file commonly exports several differently-scoped versions of
+      // "the" component (an internal base, a public wrapper, a
+      // Storybook-specific unwrapped alias via `export { X as Y }`),
+      // and this module has no reliable way to know which one a given
+      // consumer will actually import. Missing the right one means
+      // Storybook shows names/types with zero descriptions (the props
+      // come from wherever *is* documented, but the rendered component
+      // itself carries no __docgenInfo at all) — worse than attaching
+      // the same (single, best-guess) props to every candidate.
+      // Known imprecision: every export gets identical props even
+      // when their real prop types differ (e.g. an internal-only
+      // export vs. its public-facing wrapper) — a real per-export fix
+      // needs core to resolve props per named export, not just once
+      // per file.
+      const injections = componentNames
+        .map((name) => {
+          const docgenInfo = { ...documentation, displayName: name };
+          return `try { ${name}.__docgenInfo = ${JSON.stringify(docgenInfo)}; } catch (e) {}`;
+        })
+        .join('\n');
+
+      return { code: `${code}\n${injections}\n`, map: null };
+    },
+  };
+}
+
+function findComponentNames(code) {
+  const names = new Set();
+
+  for (const m of code.matchAll(/export function ([A-Z][A-Za-z0-9]*)\s*\(/g)) {
+    names.add(m[1]);
+  }
+  for (const m of code.matchAll(/export const ([A-Z][A-Za-z0-9]*)\s*[:=]/g)) {
+    names.add(m[1]);
+  }
+  // `export { X, Z as W }` — a plain re-export list. The *local* name
+  // (before `as`, if present) is what needs __docgenInfo attached,
+  // since that's the actual declared binding in this module's scope;
+  // whatever alias another file imports it as doesn't change the
+  // object identity.
+  for (const m of code.matchAll(/export\s*\{([^}]+)\}/g)) {
+    for (const part of m[1].split(',')) {
+      const localName = part.trim().split(/\s+as\s+/)[0].trim();
+      if (/^[A-Z][A-Za-z0-9]*$/.test(localName)) names.add(localName);
+    }
+  }
+
+  return [...names];
+}

package/src/vite/preset.js

@@ -0,0 +1,12 @@
+// Storybook preset entry point, referenced from `addons` in
+// .storybook/main.ts. Registers our argTypesEnhancer into
+// `previewAnnotations` — the same mechanism a project's own
+// .storybook/preview.ts uses — so it's actually bundled into the
+// preview iframe and runs for every story automatically.
+import { fileURLToPath } from 'node:url';
+
+const enhancerPath = fileURLToPath(new URL('./argTypesEnhancer.js', import.meta.url));
+
+export function previewAnnotations(entry = []) {
+  return [...entry, enhancerPath];
+}

package/src/webpack/index.js

@@ -0,0 +1,104 @@
+import { parse } from 'react-props-parser';
+
+/**
+ * Webpack loader equivalent of the vite loader (src/vite/index.js): same
+ * job (parse the file via react-props-parser, inject __docgenInfo onto the
+ * component so Storybook's addon-docs/Controls can read it), but
+ * wired in via webpackFinal's module.rules instead of a Vite
+ * transform hook, since Storybook's webpack5 builder doesn't go
+ * through Vite at all.
+ *
+ * `enforce: 'pre'` (set by the consumer's webpackFinal, see README)
+ * runs this before the framework's own babel/ts transform, so it
+ * receives raw .tsx source and can safely append plain JS at the end
+ * — the appended assignment statement is valid syntax standing alone
+ * in a TS/TSX file, so the next loader in the chain parses the whole
+ * thing, injected line included, without needing to know about us.
+ *
+ * findComponentNames below is intentionally duplicated from
+ * src/vite/index.js rather than shared — same small regex-based
+ * heuristic, kept next to each builder integration so neither depends
+ * on the other's internals.
+ *
+ * Loader options (e.g. `{ maxTypeNameLength: 80 }`) are set on the
+ * rule itself — `use: [{ loader: 'react-props-parser/webpack', options: {...} }]`
+ * — and read here via the standard webpack 5 `this.getOptions()`, then
+ * forwarded as-is to `parse()`. No schema validation: this loader
+ * takes exactly react-props-parser's own `ParseOptions` shape, so a
+ * typo here just surfaces the same way a bad `parse()` call would.
+ */
+export default function webpackLoader(source) {
+  const filePath = this.resourcePath;
+  const options = this.getOptions?.();
+
+  if (!filePath.endsWith('.tsx') || filePath.includes('node_modules') || filePath.includes('.stories.')) {
+    return source;
+  }
+
+  // Only inject when we found real exported component identifiers in
+  // the source. Never fall back to documentation.displayName as an
+  // injection target — parse() will happily resolve a "props type"
+  // for a hook or utility function too (anything with an object-
+  // shaped parameter), and its displayName in that case can be an
+  // arbitrary type string like "Partial<ConfigProps> | undefined" —
+  // not a valid JS identifier. Splicing that into generated code
+  // produces a syntax error that breaks the whole build, not just a
+  // skipped file, so this check is load-bearing, not an optimization.
+  const componentNames = findComponentNames(source);
+  if (componentNames.length === 0) return source;
+
+  let documentation;
+  try {
+    documentation = parse(filePath, options);
+  } catch {
+    // No Props type in this file (e.g. not a component file) — skip silently.
+    return source;
+  }
+
+  // Attaches to *every* plausible exported binding, not just one — a
+  // file commonly exports several differently-scoped versions of "the"
+  // component (an internal base, a public wrapper, a Storybook-
+  // specific unwrapped alias via `export { X as Y }`), and this module
+  // has no reliable way to know which one a given consumer will
+  // actually import. Missing the right one means Storybook shows
+  // names/types with zero descriptions (the props come from wherever
+  // *is* documented, but the rendered component itself carries no
+  // __docgenInfo at all) — worse than attaching the same (single,
+  // best-guess) props to every candidate.
+  // Known imprecision: every export gets identical props even when
+  // their real prop types differ (e.g. an internal-only export vs. its
+  // public-facing wrapper) — a real per-export fix needs core to
+  // resolve props per named export, not just once per file.
+  const injections = componentNames
+    .map((name) => {
+      const docgenInfo = { ...documentation, displayName: name };
+      return `try { ${name}.__docgenInfo = ${JSON.stringify(docgenInfo)}; } catch (e) {}`;
+    })
+    .join('\n');
+
+  return `${source}\n${injections}\n`;
+}
+
+function findComponentNames(code) {
+  const names = new Set();
+
+  for (const m of code.matchAll(/export function ([A-Z][A-Za-z0-9]*)\s*\(/g)) {
+    names.add(m[1]);
+  }
+  for (const m of code.matchAll(/export const ([A-Z][A-Za-z0-9]*)\s*[:=]/g)) {
+    names.add(m[1]);
+  }
+  // `export { X, Z as W }` — a plain re-export list. The *local* name
+  // (before `as`, if present) is what needs __docgenInfo attached,
+  // since that's the actual declared binding in this module's scope;
+  // whatever alias another file imports it as doesn't change the
+  // object identity.
+  for (const m of code.matchAll(/export\s*\{([^}]+)\}/g)) {
+    for (const part of m[1].split(',')) {
+      const localName = part.trim().split(/\s+as\s+/)[0].trim();
+      if (/^[A-Z][A-Za-z0-9]*$/.test(localName)) names.add(localName);
+    }
+  }
+
+  return [...names];
+}