@jfrader/storybook-docs 0.6.0 → 0.8.0

package/dist/build/snippet-bindings.d.ts

@@ -0,0 +1,3 @@
+import ts from 'typescript';
+export declare function snippetProgram(file: ts.SourceFile): ts.Program;
+export declare function unresolvedSnippetBindings(source: string, localTags?: Set<string>): string[];

package/dist/index.js

@@ -5,7 +5,7 @@ import { createRoot } from "react-dom/client";
 import { site as site3, themeCss, theme as theme2 } from "virtual:storybook-docs/site";
 
 // src/app.tsx
-import { Children, useEffect as useEffect8, useRef as useRef5, useState as useState9 } from "react";
+import { useEffect as useEffect8, useRef as useRef5, useState as useState9 } from "react";
 import { catalog as catalog3, groups as groups2 } from "virtual:storybook-docs/catalog";
 import { pages, site as site2, theme } from "virtual:storybook-docs/site";
 
@@ -263,6 +263,11 @@ import { useCallback as useCallback2, useEffect as useEffect4, useId, useRef as
 import { Component as Component2, createElement as createElement2, useEffect as useEffect2, useRef, useState as useState2 } from "react";
 
 // src/sections.ts
+function frameSource(meta, story) {
+  const unchanged = Object.entries(story.args ?? {}).every(([key, value]) => Object.hasOwn(meta.args ?? {}, key) && Object.is(value, meta.args?.[key]));
+  return story.parameters?.docs?.source?.code ?? (unchanged ? meta.parameters?.docs?.source?.code : void 0);
+}
+var STORY_EXCERPT = "// Excerpt from the story";
 function mergeAnnotations(...values) {
   const merged = {};
   const isRecord = (value) => value !== null && typeof value === "object" && Object.getPrototypeOf(value) === Object.prototype;
@@ -375,13 +380,20 @@ function usageSnippet(componentName, args) {
   return `${opening}>${children}</${componentName}>`;
 }
 function buildUsageSnippet({ componentName, from, args, source, renderSource, jsxName, component }) {
-  if (!source?.trim() && renderSource?.trim()) return renderSource;
   const rootName = componentName.split(".")[0];
   const identity = component;
   const tag = jsxName ?? (typeof identity?.displayName === "string" && identity.displayName.startsWith(`${rootName}.`) ? identity.displayName : componentName);
   const compound = component != null && Object.entries(component).some(([name, part]) => /^[A-Z]/.test(name) && (typeof part === "function" || part !== null && typeof part === "object" && "$$typeof" in part));
-  const example = source?.trim() || (compound && !tag.includes(".") ? null : usageSnippet(tag, args));
+  const generated = () => compound && !tag.includes(".") ? null : usageSnippet(tag, args);
+  const extracted = renderSource?.trim();
+  const excerpt = extracted?.startsWith(STORY_EXCERPT);
+  const example = source?.trim() || (excerpt ? generated() || extracted : extracted || generated());
   if (!example) return null;
+  if (!source?.trim() && example === extracted) {
+    const rootTag = example.replace(/^\s*\/\/[^\n]*(?:\n|$)/gm, "").trim().match(/^<([A-Za-z_$][\w$]*(?:\.[\w$]+)*)[\s/>]/)?.[1]?.split(".")[0];
+    if (excerpt || rootTag !== rootName || !from.trim()) return example;
+  }
+  if (!from.trim()) return example;
   const imports = [...example.matchAll(/import\s*\{([^}]+)\}\s*from\s*(['"])(.*?)\2/g)];
   const imported = imports.some((match) => match[3] === from && match[1].split(",").some((name) => name.trim() === rootName));
   return imported ? example : `import { ${rootName} } from '${from}';
@@ -1038,7 +1050,7 @@ function ControlledStoryFrame({ module, story, componentName, componentDefaults,
   const storyLayout = requestedLayout === "centered" || requestedLayout === "fullscreen" ? requestedLayout : "padded";
   const docsOverride = definition.parameters?.docs;
   const docsMeta = meta.parameters?.docs;
-  const authoredCode = docsOverride?.source?.code ?? docsMeta?.source?.code;
+  const authoredCode = frameSource(meta, definition);
   const authoredStory = docsOverride?.description?.story ?? docsMeta?.description?.story;
   const storyName = definition.name ?? story;
   const skipped = ["loaders", "beforeEach"].filter((key) => meta[key] || definition[key]);
@@ -1297,7 +1309,7 @@ function ComponentPage({ entry }) {
         " props"
       ] })
     ] }),
-    /* @__PURE__ */ jsx8("p", { className: "lede", children: description ?? `${entry.name} \u2014 every story in ${entry.storybookTitle} is rendered below, in sections.` }),
+    description ? /* @__PURE__ */ jsx8("p", { className: "lede", children: description }) : null,
     error ? /* @__PURE__ */ jsxs5("div", { className: "story-failed", children: [
       "Could not load the story module: ",
       error
@@ -1322,9 +1334,7 @@ function ComponentPage({ entry }) {
       ] }, section.title))
     ] }) : null,
     /* @__PURE__ */ jsx8("h2", { children: "Props" }),
-    /* @__PURE__ */ jsx8(PropsTable, { components: props, argTypes, defaultArgs }),
-    /* @__PURE__ */ jsx8("h2", { children: "Notes" }),
-    /* @__PURE__ */ jsx8("p", { children: "Everything above is generated from this component\u2019s story module and source files. Editorial judgement \u2014 when to reach for it, when not to \u2014 is written next to the code and rendered as guidance above." })
+    /* @__PURE__ */ jsx8(PropsTable, { components: props, argTypes, defaultArgs })
   ] });
 }
 
@@ -1847,21 +1857,14 @@ function SearchBox() {
 import { releases as releases2 } from "virtual:storybook-docs/releases";
 import { jsx as jsx16, jsxs as jsxs13 } from "react/jsx-runtime";
 var routeHref = (path) => `#${hrefFor(path)}`;
-var NAV_GROUP_WINDOW = 12;
-function NavGroup({ id, title, active, activeIndex = -1, children }) {
-  const [open, setOpen] = useState9(false);
-  const [showAll, setShowAll] = useState9(false);
-  const expanded = active || open;
-  const links = Children.toArray(children);
-  const capped = active && links.length > NAV_GROUP_WINDOW;
-  const start2 = Math.min(Math.max(activeIndex - NAV_GROUP_WINDOW / 2, 0), Math.max(0, links.length - NAV_GROUP_WINDOW));
-  const visibleLinks = capped && !showAll ? links.slice(start2, start2 + NAV_GROUP_WINDOW) : links;
+function NavGroup({ id, title, active, children }) {
+  const [open, setOpen] = useState9(active);
   return /* @__PURE__ */ jsxs13("div", { role: "group", "aria-labelledby": id, children: [
-    /* @__PURE__ */ jsx16("button", { type: "button", className: "grp", id, "aria-expanded": expanded, "aria-controls": `${id}-links`, disabled: active, onClick: () => setOpen(!open), children: title }),
-    /* @__PURE__ */ jsxs13("div", { id: `${id}-links`, hidden: !expanded, children: [
-      /* @__PURE__ */ jsx16("div", { id: `${id}-window`, children: visibleLinks }),
-      capped ? /* @__PURE__ */ jsx16("button", { type: "button", className: "nav-more", "aria-expanded": showAll, "aria-controls": `${id}-window`, onClick: () => setShowAll(!showAll), children: showAll ? "Show less" : `Show all ${links.length}` }) : null
-    ] })
+    /* @__PURE__ */ jsxs13("button", { type: "button", className: "grp", id, "aria-expanded": open, "aria-controls": `${id}-links`, onClick: () => setOpen(!open), children: [
+      /* @__PURE__ */ jsx16("span", { children: title }),
+      /* @__PURE__ */ jsx16("svg", { className: "grp-chevron", width: "14", height: "14", viewBox: "0 0 16 16", fill: "none", stroke: "currentColor", strokeWidth: "1.5", "aria-hidden": "true", children: /* @__PURE__ */ jsx16("path", { d: "m6 4 4 4-4 4" }) })
+    ] }),
+    /* @__PURE__ */ jsx16("div", { id: `${id}-links`, hidden: !open, children })
   ] });
 }
 function parseRoute(hash) {
@@ -1989,7 +1992,7 @@ function DocsApp() {
           ]
         }
       ) : null,
-      foundations.length > 0 ? /* @__PURE__ */ jsx16(NavGroup, { id: "nav-grp-foundations", title: "Foundations", active: foundations.some((item) => route.kind === item.kind), children: foundations.map((item) => /* @__PURE__ */ jsx16(
+      foundations.length > 0 ? /* @__PURE__ */ jsx16(NavGroup, { id: "nav-grp-foundations", title: "Design tokens", active: foundations.some((item) => route.kind === item.kind), children: foundations.map((item) => /* @__PURE__ */ jsx16(
         "a",
         {
           href: item.href,
@@ -2001,8 +2004,8 @@ function DocsApp() {
       )) }, `foundations-${activeSlug ?? route.kind}`) : null,
       groups2.map((group, index) => {
         const entries = catalog3.filter((entry) => entry.group === group);
-        const activeIndex = entries.findIndex((entry) => entry.slug === activeSlug);
-        return /* @__PURE__ */ jsx16(NavGroup, { id: `nav-grp-${index}`, title: group, active: activeIndex !== -1, activeIndex, children: entries.map((entry) => /* @__PURE__ */ jsx16(
+        const active = entries.some((entry) => entry.slug === activeSlug);
+        return /* @__PURE__ */ jsx16(NavGroup, { id: `nav-grp-${index}`, title: group, active, children: entries.map((entry) => /* @__PURE__ */ jsx16(
           "a",
           {
             href: routeHref(`/components/${entry.slug}`),

package/dist/sections.d.ts

@@ -13,6 +13,18 @@ export type DocsParameters = {
         language?: string;
     };
 };
+export declare function frameSource(meta: {
+    args?: Record<string, unknown>;
+    parameters?: {
+        docs?: DocsParameters;
+    };
+}, story: {
+    args?: Record<string, unknown>;
+    parameters?: {
+        docs?: DocsParameters;
+    };
+}): string | undefined;
+export declare const STORY_EXCERPT = "// Excerpt from the story";
 export declare function mergeAnnotations(...values: Array<Record<string, unknown> | undefined>): Record<string, unknown>;
 export interface StorySection {
     title: string;

package/dist/styles.css

@@ -202,8 +202,7 @@ body {
   background: var(--sd-surface);
   padding: 14px 12px 12px;
 }
-.nav a,
-.nav-more {
+.nav a {
   display: flex;
   align-items: center;
   box-sizing: border-box;
@@ -214,16 +213,7 @@ body {
   font-size: 13.5px;
   text-decoration: none;
 }
-.nav-more {
-  width: 100%;
-  background: none;
-  border: 0;
-  font-family: inherit;
-  cursor: pointer;
-  text-align: left;
-}
-.nav a:hover,
-.nav-more:hover {
+.nav a:hover {
   background: var(--sd-surface-hover);
   color: var(--sd-text);
 }
@@ -234,23 +224,46 @@ body {
 }
 .grp {
   margin: 3px 0 2px;
-  padding: 0 10px;
+  padding: 8px 10px;
   font-size: 10.5px;
   letter-spacing: 0.09em;
   text-transform: uppercase;
   color: var(--sd-text-muted);
   font-weight: 700;
-  display: block;
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 8px;
   width: 100%;
   text-align: left;
   font-family: inherit;
   background: none;
   border: 0;
+  border-radius: 8px;
   cursor: pointer;
-  min-height: 28px;
+  min-height: 36px;
+}
+.grp[aria-expanded="true"] {
+  background: var(--sd-surface-raised);
+  color: var(--sd-text);
+}
+.grp:hover {
+  background: var(--sd-surface-hover);
+  color: var(--sd-text);
+}
+.grp-chevron {
+  flex-shrink: 0;
+  transition: transform 150ms ease;
+}
+.grp[aria-expanded="true"] .grp-chevron {
+  transform: rotate(90deg);
+}
+@media (prefers-reduced-motion: reduce) {
+  .grp-chevron {
+    transition: none;
+  }
 }
-.grp:focus-visible,
-.nav-more:focus-visible {
+.grp:focus-visible {
   outline: 2px solid var(--sd-focus-ring);
   outline-offset: 2px;
 }

package/dist/vite-plugin.js

@@ -609,58 +609,110 @@ export const cleanup = () => {};
 `;
 
 // src/build/story-sources.ts
+import ts3 from "typescript";
+
+// src/sections.ts
+var STORY_EXCERPT = "// Excerpt from the story";
+
+// src/build/snippet-bindings.ts
 import ts2 from "typescript";
+var options = { target: ts2.ScriptTarget.Latest, jsx: ts2.JsxEmit.Preserve, noLib: true };
+var UNRESOLVED_NAME_DIAGNOSTICS = /* @__PURE__ */ new Set([2304, 2552, 2580, 2581, 2582, 2591, 2592, 18004]);
+function snippetProgram(file) {
+  const host = ts2.createCompilerHost(options);
+  host.getSourceFile = (name) => name === file.fileName ? file : void 0;
+  return ts2.createProgram([file.fileName], options, host);
+}
+var globals;
+function globalNames() {
+  if (!globals) {
+    const host = ts2.createCompilerHost({ target: ts2.ScriptTarget.Latest });
+    const lib = host.getDefaultLibFileName({ target: ts2.ScriptTarget.Latest });
+    const libraries = ts2.createProgram([lib], { target: ts2.ScriptTarget.Latest });
+    const file = libraries.getSourceFile(lib);
+    globals = new Set(libraries.getTypeChecker().getSymbolsInScope(file, ts2.SymbolFlags.Value).map((symbol) => symbol.name));
+  }
+  return globals;
+}
+function unresolvedSnippetBindings(source, localTags = /* @__PURE__ */ new Set()) {
+  const file = ts2.createSourceFile("snippet.tsx", `declare const args: any;
+${source}`, ts2.ScriptTarget.Latest, true, ts2.ScriptKind.TSX);
+  const program = snippetProgram(file);
+  const expression = file.statements.find(ts2.isExpressionStatement)?.expression;
+  const rootTag = expression && (ts2.isJsxElement(expression) ? expression.openingElement.tagName : ts2.isJsxSelfClosingElement(expression) ? expression.tagName : void 0);
+  const publicRoot = rootTag?.getText(file).split(".")[0];
+  const identifiers = /* @__PURE__ */ new Map();
+  const visit = (node) => {
+    if (ts2.isIdentifier(node)) identifiers.set(node.getStart(file), node);
+    ts2.forEachChild(node, visit);
+  };
+  visit(file);
+  const unresolved = /* @__PURE__ */ new Set();
+  for (const diagnostic of program.getSemanticDiagnostics(file)) {
+    if (!UNRESOLVED_NAME_DIAGNOSTICS.has(diagnostic.code) || diagnostic.start === void 0) continue;
+    const node = identifiers.get(diagnostic.start);
+    if (!node) continue;
+    let tag = node;
+    while (ts2.isPropertyAccessExpression(tag.parent) && tag.parent.expression === tag) tag = tag.parent;
+    const jsxTag = (ts2.isJsxOpeningElement(tag.parent) || ts2.isJsxClosingElement(tag.parent) || ts2.isJsxSelfClosingElement(tag.parent)) && tag.parent.tagName === tag;
+    if (!(jsxTag && node.text === publicRoot && !localTags.has(node.text)) && !globalNames().has(node.text)) unresolved.add(node.text);
+  }
+  return [...unresolved].sort();
+}
+
+// src/build/story-sources.ts
 function unwrap(node) {
-  while (ts2.isParenthesizedExpression(node) || ts2.isAsExpression(node) || ts2.isSatisfiesExpression(node) || ts2.isTypeAssertionExpression(node)) node = node.expression;
+  while (ts3.isParenthesizedExpression(node) || ts3.isAsExpression(node) || ts3.isSatisfiesExpression(node) || ts3.isTypeAssertionExpression(node)) node = node.expression;
   return node;
 }
 var MAX_HELPER_DEPTH = 3;
 function extractStorySourceDetails(source) {
-  const file = ts2.createSourceFile("stories.tsx", source, ts2.ScriptTarget.Latest, true, ts2.ScriptKind.TSX);
+  const file = ts3.createSourceFile("stories.tsx", source, ts3.ScriptTarget.Latest, true, ts3.ScriptKind.TSX);
+  const checker = snippetProgram(file).getTypeChecker();
   const declarations = /* @__PURE__ */ new Map();
   const exports = /* @__PURE__ */ new Map();
   for (const statement of file.statements) {
-    const exported = ts2.canHaveModifiers(statement) && ts2.getModifiers(statement)?.some((modifier) => modifier.kind === ts2.SyntaxKind.ExportKeyword);
-    if (ts2.isVariableStatement(statement)) {
+    const exported = ts3.canHaveModifiers(statement) && ts3.getModifiers(statement)?.some((modifier) => modifier.kind === ts3.SyntaxKind.ExportKeyword);
+    if (ts3.isVariableStatement(statement)) {
       for (const declaration of statement.declarationList.declarations) {
-        if (!ts2.isIdentifier(declaration.name) || !declaration.initializer) continue;
+        if (!ts3.isIdentifier(declaration.name) || !declaration.initializer) continue;
         declarations.set(declaration.name.text, declaration.initializer);
         if (exported) exports.set(declaration.name.text, declaration.name.text);
       }
-    } else if (ts2.isFunctionDeclaration(statement) && statement.name) {
+    } else if (ts3.isFunctionDeclaration(statement) && statement.name) {
       declarations.set(statement.name.text, statement);
       if (exported) exports.set(statement.name.text, statement.name.text);
-    } else if (ts2.isExportDeclaration(statement) && !statement.moduleSpecifier && statement.exportClause && ts2.isNamedExports(statement.exportClause)) {
+    } else if (ts3.isExportDeclaration(statement) && !statement.moduleSpecifier && statement.exportClause && ts3.isNamedExports(statement.exportClause)) {
       for (const element of statement.exportClause.elements) {
         exports.set(element.name.text, (element.propertyName ?? element.name).text);
       }
     }
   }
   const renderFor = (node, seen = /* @__PURE__ */ new Set()) => {
-    if (ts2.isFunctionDeclaration(node)) return node;
+    if (ts3.isFunctionDeclaration(node)) return node;
     node = unwrap(node);
-    if (ts2.isIdentifier(node)) {
+    if (ts3.isIdentifier(node)) {
       if (seen.has(node.text)) return;
       seen.add(node.text);
       const declaration = declarations.get(node.text);
       return declaration ? renderFor(declaration, seen) : void 0;
     }
-    if (ts2.isPropertyAccessExpression(node) && node.name.text === "render" || ts2.isElementAccessExpression(node) && ts2.isStringLiteral(node.argumentExpression) && node.argumentExpression.text === "render") return renderFor(node.expression, seen);
-    if (ts2.isArrowFunction(node) || ts2.isFunctionExpression(node)) return node;
-    if (!ts2.isObjectLiteralExpression(node)) return;
+    if (ts3.isPropertyAccessExpression(node) && node.name.text === "render" || ts3.isElementAccessExpression(node) && ts3.isStringLiteral(node.argumentExpression) && node.argumentExpression.text === "render") return renderFor(node.expression, seen);
+    if (ts3.isArrowFunction(node) || ts3.isFunctionExpression(node)) return node;
+    if (!ts3.isObjectLiteralExpression(node)) return;
     for (const property of [...node.properties].reverse()) {
-      if (ts2.isSpreadAssignment(property)) {
+      if (ts3.isSpreadAssignment(property)) {
         const render = renderFor(property.expression, new Set(seen));
         if (render !== void 0) return render;
-      } else if (property.name && (ts2.isIdentifier(property.name) || ts2.isStringLiteral(property.name)) && property.name.text === "render") {
-        if (ts2.isMethodDeclaration(property)) return property;
-        if (ts2.isPropertyAssignment(property)) return renderFor(property.initializer, seen) ?? null;
-        if (ts2.isShorthandPropertyAssignment(property)) return renderFor(property.name, seen) ?? null;
+      } else if (property.name && (ts3.isIdentifier(property.name) || ts3.isStringLiteral(property.name)) && property.name.text === "render") {
+        if (ts3.isMethodDeclaration(property)) return property;
+        if (ts3.isPropertyAssignment(property)) return renderFor(property.initializer, seen) ?? null;
+        if (ts3.isShorthandPropertyAssignment(property)) return renderFor(property.name, seen) ?? null;
         return null;
       }
     }
   };
-  const hasJsx = (node) => ts2.isJsxElement(node) || ts2.isJsxSelfClosingElement(node) || ts2.isJsxFragment(node) || (ts2.forEachChild(node, hasJsx) ?? false);
+  const hasJsx = (node) => ts3.isJsxElement(node) || ts3.isJsxSelfClosingElement(node) || ts3.isJsxFragment(node) || (ts3.forEachChild(node, hasJsx) ?? false);
   const returnsCache = /* @__PURE__ */ new Map();
   const returnCounts = /* @__PURE__ */ new Map();
   const returnedJsx = (render) => {
@@ -669,17 +721,17 @@ function extractStorySourceDetails(source) {
     const expressions = [];
     if (!render.body) return expressions;
     let returnCount = 0;
-    if (ts2.isBlock(render.body)) {
+    if (ts3.isBlock(render.body)) {
       const visit = (node) => {
-        if (ts2.isFunctionLike(node)) return;
-        if (ts2.isReturnStatement(node)) {
+        if (ts3.isFunctionLike(node)) return;
+        if (ts3.isReturnStatement(node)) {
           returnCount += 1;
           if (node.expression && hasJsx(node.expression)) expressions.push(unwrap(node.expression));
           return;
         }
-        ts2.forEachChild(node, visit);
+        ts3.forEachChild(node, visit);
       };
-      ts2.forEachChild(render.body, visit);
+      ts3.forEachChild(render.body, visit);
     } else {
       returnCount = 1;
       if (hasJsx(render.body)) expressions.push(unwrap(render.body));
@@ -693,16 +745,16 @@ function extractStorySourceDetails(source) {
     seen.add(name);
     const declaration = declarations.get(name);
     if (!declaration) return;
-    if (ts2.isFunctionDeclaration(declaration)) return declaration;
+    if (ts3.isFunctionDeclaration(declaration)) return declaration;
     const expression = unwrap(declaration);
-    if (ts2.isIdentifier(expression)) return helperFor(expression.text, seen);
-    if (ts2.isArrowFunction(expression) || ts2.isFunctionExpression(expression)) return expression;
+    if (ts3.isIdentifier(expression)) return helperFor(expression.text, seen);
+    if (ts3.isArrowFunction(expression) || ts3.isFunctionExpression(expression)) return expression;
   };
-  const bindingContains = (binding, name) => ts2.isIdentifier(binding) ? binding.text === name : binding.elements.some((element) => ts2.isBindingElement(element) && bindingContains(element.name, name));
+  const bindingContains = (binding, name) => ts3.isIdentifier(binding) ? binding.text === name : binding.elements.some((element) => ts3.isBindingElement(element) && bindingContains(element.name, name));
   const isShadowed = (expression, name) => {
     for (let node = expression.parent; node; node = node.parent) {
-      if (ts2.isFunctionLike(node) && node.parameters.some((parameter) => bindingContains(parameter.name, name))) return true;
-      if (ts2.isBlock(node) && node.statements.some((statement) => ts2.isVariableStatement(statement) && statement.declarationList.declarations.some((declaration) => bindingContains(declaration.name, name)) || ts2.isFunctionDeclaration(statement) && statement.name?.text === name)) return true;
+      if (ts3.isFunctionLike(node) && node.parameters.some((parameter) => bindingContains(parameter.name, name))) return true;
+      if (ts3.isBlock(node) && node.statements.some((statement) => ts3.isVariableStatement(statement) && statement.declarationList.declarations.some((declaration) => bindingContains(declaration.name, name)) || ts3.isFunctionDeclaration(statement) && statement.name?.text === name)) return true;
     }
     return false;
   };
@@ -712,24 +764,24 @@ function extractStorySourceDetails(source) {
     if (cached !== void 0) return cached;
     const bindings = /* @__PURE__ */ new Map();
     for (const [name, declaration] of declarations) {
-      bindings.set(name, ts2.isFunctionDeclaration(declaration) ? void 0 : declaration);
+      bindings.set(name, ts3.isFunctionDeclaration(declaration) ? void 0 : declaration);
     }
     const bind = (scope2, name, initializer) => {
-      if (ts2.isIdentifier(name)) scope2.set(name.text, initializer);
+      if (ts3.isIdentifier(name)) scope2.set(name.text, initializer);
       else for (const element of name.elements) {
-        if (ts2.isBindingElement(element)) bind(scope2, element.name, element.initializer);
+        if (ts3.isBindingElement(element)) bind(scope2, element.name, element.initializer);
       }
     };
     const addScope = (node, parent) => {
       const scope2 = new Map(parent);
-      if (ts2.isFunctionLike(node)) {
+      if (ts3.isFunctionLike(node)) {
         for (const parameter of node.parameters) bind(scope2, parameter.name, parameter.initializer);
       }
-      if (ts2.isBlock(node)) {
+      if (ts3.isBlock(node)) {
         for (const statement of node.statements) {
-          if (ts2.isVariableStatement(statement)) {
+          if (ts3.isVariableStatement(statement)) {
             for (const declaration of statement.declarationList.declarations) bind(scope2, declaration.name, declaration.initializer);
-          } else if (ts2.isFunctionDeclaration(statement) && statement.name) scope2.set(statement.name.text, void 0);
+          } else if (ts3.isFunctionDeclaration(statement) && statement.name) scope2.set(statement.name.text, void 0);
         }
       }
       return scope2;
@@ -740,55 +792,84 @@ function extractStorySourceDetails(source) {
     for (const node of ancestors.reverse()) scope = addScope(node, scope);
     const knownCollection = (expression, bindings2, seen = /* @__PURE__ */ new Set()) => {
       expression = unwrap(expression);
-      if (ts2.isArrayLiteralExpression(expression)) {
-        return expression.elements.every((element) => !ts2.isSpreadElement(element) || knownCollection(element.expression, bindings2, new Set(seen)));
+      if (ts3.isArrayLiteralExpression(expression)) {
+        return expression.elements.every((element) => !ts3.isSpreadElement(element) || knownCollection(element.expression, bindings2, new Set(seen)));
       }
-      if (ts2.isIdentifier(expression)) {
+      if (ts3.isIdentifier(expression)) {
         if (seen.has(expression.text)) return false;
         seen.add(expression.text);
         const initializer = bindings2.get(expression.text);
         return Boolean(initializer && knownCollection(initializer, bindings2, seen));
       }
-      if (ts2.isCallExpression(expression) && ts2.isPropertyAccessExpression(expression.expression) && ["slice", "filter", "toSorted", "toReversed"].includes(expression.expression.name.text)) {
+      if (ts3.isCallExpression(expression) && ts3.isPropertyAccessExpression(expression.expression) && ["slice", "filter", "toSorted", "toReversed"].includes(expression.expression.name.text)) {
         return knownCollection(expression.expression.expression, bindings2, seen);
       }
       return false;
     };
     const visit = (node, bindings2) => {
-      if (ts2.isFunctionLike(node) || ts2.isBlock(node)) bindings2 = addScope(node, bindings2);
-      if (ts2.isCallExpression(node)) {
+      if (ts3.isFunctionLike(node) || ts3.isBlock(node)) bindings2 = addScope(node, bindings2);
+      if (ts3.isCallExpression(node)) {
         const target = node.expression;
-        const map = ts2.isPropertyAccessExpression(target) && target.name.text === "map" || ts2.isElementAccessExpression(target) && ts2.isStringLiteral(target.argumentExpression) && target.argumentExpression.text === "map";
+        const map = ts3.isPropertyAccessExpression(target) && target.name.text === "map" || ts3.isElementAccessExpression(target) && ts3.isStringLiteral(target.argumentExpression) && target.argumentExpression.text === "map";
         if (map && !knownCollection(target.expression, bindings2)) return true;
       }
-      return ts2.forEachChild(node, (child) => visit(child, bindings2)) ?? false;
+      return ts3.forEachChild(node, (child) => visit(child, bindings2)) ?? false;
     };
     const unknown = visit(jsx, scope);
     mapCache.set(jsx, unknown);
     return unknown;
   };
-  const inlineRoot = (expression, detail, trail = []) => {
-    const tag = ts2.isJsxElement(expression) ? expression.openingElement.tagName : ts2.isJsxSelfClosingElement(expression) ? expression.tagName : void 0;
-    const name = tag && ts2.isIdentifier(tag) && /^[A-Z]/.test(tag.text) ? tag.text : void 0;
+  const textWithBindings = (expression, bindings) => {
+    const edits = [];
+    const visit = (node) => {
+      if (ts3.isIdentifier(node)) {
+        const symbol = checker.getSymbolAtLocation(node);
+        const text2 = symbol && bindings.get(symbol);
+        const parent = node.parent;
+        const tag = (ts3.isJsxOpeningElement(parent) || ts3.isJsxClosingElement(parent) || ts3.isJsxSelfClosingElement(parent)) && parent.tagName === node;
+        if (text2 && !tag) edits.push({
+          start: node.getStart(file) - expression.getStart(file),
+          end: node.end - expression.getStart(file),
+          text: ts3.isShorthandPropertyAssignment(parent) ? `${node.text}: ${text2}` : text2
+        });
+      }
+      ts3.forEachChild(node, visit);
+    };
+    visit(expression);
+    let text = expression.getText(file);
+    for (const edit of edits.reverse()) text = text.slice(0, edit.start) + edit.text + text.slice(edit.end);
+    return text;
+  };
+  const inlineRoot = (expression, detail, trail = [], bindings = /* @__PURE__ */ new Map()) => {
+    const tag = ts3.isJsxElement(expression) ? expression.openingElement.tagName : ts3.isJsxSelfClosingElement(expression) ? expression.tagName : void 0;
+    const name = tag && ts3.isIdentifier(tag) && /^[A-Z]/.test(tag.text) ? tag.text : void 0;
     const helper = name && helperFor(name);
-    if (!name || !declarations.has(name)) return expression.getText(file);
+    if (!name || !declarations.has(name)) return textWithBindings(expression, bindings);
     if (!helper) {
       const reason2 = "local definition is not a direct function";
       detail.remaining.push({ name, reason: reason2 });
       return `// ${name} not expanded: ${reason2}.
-${expression.getText(file)}`;
+${textWithBindings(expression, bindings)}`;
     }
     const returned = returnedJsx(helper);
     const jsx = returned[0];
-    const reason = isShadowed(expression, name) ? "file helper is shadowed in this scope" : trail.includes(name) ? "recursive helper cycle" : trail.length >= MAX_HELPER_DEPTH ? `helper depth limit (${MAX_HELPER_DEPTH})` : returnCounts.get(helper) !== 1 || returned.length !== 1 || !jsx || !(ts2.isJsxElement(jsx) || ts2.isJsxSelfClosingElement(jsx) || ts2.isJsxFragment(jsx)) ? "no single literal JSX return" : hasUnknownMap(helper, jsx) ? "maps over a collection without a local array definition" : void 0;
+    const reason = isShadowed(expression, name) ? "file helper is shadowed in this scope" : trail.includes(name) ? "recursive helper cycle" : trail.length >= MAX_HELPER_DEPTH ? `helper depth limit (${MAX_HELPER_DEPTH})` : returnCounts.get(helper) !== 1 || returned.length !== 1 || !jsx || !(ts3.isJsxElement(jsx) || ts3.isJsxSelfClosingElement(jsx) || ts3.isJsxFragment(jsx)) ? "no single literal JSX return" : hasUnknownMap(helper, jsx) ? "maps over a collection without a local array definition" : void 0;
     if (reason) {
       detail.remaining.push({ name, reason });
       return `// ${name} not expanded: ${reason}.
-${expression.getText(file)}`;
+${textWithBindings(expression, bindings)}`;
     }
     detail.inlined.push(name);
+    const attributes = ts3.isJsxElement(expression) ? expression.openingElement.attributes : ts3.isJsxSelfClosingElement(expression) ? expression.attributes : void 0;
+    const parameter = helper.parameters[0]?.name;
+    const rootAttributes = ts3.isJsxElement(jsx) ? jsx.openingElement.attributes : ts3.isJsxSelfClosingElement(jsx) ? jsx.attributes : void 0;
+    const spread = attributes?.properties.length === 1 ? attributes.properties[0] : void 0;
+    if (parameter && ts3.isIdentifier(parameter) && spread && ts3.isJsxSpreadAttribute(spread) && textWithBindings(spread.expression, bindings) === "args" && rootAttributes?.properties.some((prop) => ts3.isJsxSpreadAttribute(prop) && ts3.isIdentifier(prop.expression) && prop.expression.text === parameter.text)) {
+      const symbol = checker.getSymbolAtLocation(parameter);
+      if (symbol) bindings = new Map(bindings).set(symbol, "args");
+    }
     return `// JSX from ${name}, as authored.
-${inlineRoot(jsx, detail, [...trail, name])}`;
+${inlineRoot(jsx, detail, [...trail, name], bindings)}`;
   };
   const sources = {};
   const helpers = {};
@@ -799,8 +880,16 @@ ${inlineRoot(jsx, detail, [...trail, name])}`;
     const expressions = returnedJsx(render);
     if (expressions.length) {
       const detail = { inlined: [], remaining: [] };
-      const jsx = expressions.map((expression) => inlineRoot(expression, detail)).join("\n\n");
-      sources[name] = expressions.length > 1 ? `// JSX return branches as authored in the story.
+      const bindings = /* @__PURE__ */ new Map();
+      const parameter = render.parameters[0]?.name;
+      if (parameter && ts3.isIdentifier(parameter)) {
+        const symbol = checker.getSymbolAtLocation(parameter);
+        if (symbol) bindings.set(symbol, "args");
+      }
+      const jsx = expressions.map((expression) => inlineRoot(expression, detail, [], bindings)).join("\n\n");
+      const unresolved = unresolvedSnippetBindings(jsx, new Set(declarations.keys()));
+      const incomplete = detail.remaining.length || unresolved.length || expressions.length > 1;
+      sources[name] = incomplete ? `${STORY_EXCERPT}${unresolved.length ? `; unresolved bindings: ${unresolved.join(", ")}` : "; multiple return branches"}.
 ${jsx}` : jsx;
       if (detail.inlined.length || detail.remaining.length) helpers[name] = detail;
     }
@@ -825,9 +914,9 @@ function storySourcesCode(sources) {
 }
 
 // src/vite-plugin.ts
-function storybookDocs(options) {
-  const { config } = options;
-  let projectRoot = options.root ?? process.cwd();
+function storybookDocs(options2) {
+  const { config } = options2;
+  let projectRoot = options2.root ?? process.cwd();
   let catalog = buildCatalog(scanStories(config.stories, projectRoot), config.groups);
   catalog.files.clear();
   const engineStyles = path7.join(import.meta.dirname, "styles.css");
@@ -874,7 +963,7 @@ export const storySource = ${JSON.stringify(config.stories.from)};`,
     },
     configResolved(resolved) {
       propsCollector.setBuildMode(resolved.command === "build");
-      projectRoot = options.root ?? resolved.root;
+      projectRoot = options2.root ?? resolved.root;
       catalog = buildCatalog(scanStories(config.stories, projectRoot), config.groups);
       guidanceFiles = indexGuidance(config.guidance, projectRoot);
       this.info?.(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jfrader/storybook-docs",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "type": "module",
   "description": "A documentation front for any design system that has Storybook: navigation, live examples and API tables are generated from the story files themselves.",
   "exports": {