@jfrader/storybook-docs 0.5.0 → 0.7.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.css

@@ -106,16 +106,20 @@
 .toc {
   display: none;
 }
+.toc-track {
+  display: none;
+}
 @media (min-width: 1180px) {
   .app.has-toc {
     grid-template-columns: 276px minmax(0, 1fr) 224px;
   }
-  .toc {
+  .toc-track {
     display: block;
     grid-column: 3;
     grid-row: 2;
-    align-self: start;
-    transform: translateY(var(--sd-rail-follow, 0px));
+  }
+  .toc {
+    display: block;
     padding: 34px 18px 40px 6px;
     font-size: 12.5px;
   }

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 { useEffect as useEffect8, useRef as useRef5, useState as useState9 } from "react";
+import { Children, 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}';
@@ -511,6 +523,77 @@ function LazySection({ children, placeholder = "\u2026" }) {
 
 // src/toc.tsx
 import { useCallback, useEffect as useEffect3, useRef as useRef2, useState as useState3 } from "react";
+
+// src/rail.ts
+var RAIL_MEDIA = "(min-width: 1180px)";
+var RAIL_GAP = 20;
+function followRail(rail, header) {
+  const track = rail.parentElement;
+  if (!track) return () => {
+  };
+  const media = window.matchMedia(RAIL_MEDIA);
+  let lastY = window.scrollY;
+  let direction = "down";
+  let spacer = 0;
+  const geometry = () => {
+    const top = header.offsetHeight + RAIL_GAP;
+    const viewportBottom = window.innerHeight - RAIL_GAP;
+    const height = rail.offsetHeight;
+    return {
+      top,
+      viewportBottom,
+      height,
+      fits: top + height <= viewportBottom,
+      trackTop: track.getBoundingClientRect().top + window.scrollY,
+      maxOffset: Math.max(0, track.clientHeight - height)
+    };
+  };
+  const clear = () => {
+    rail.removeAttribute("style");
+    track.removeAttribute("style");
+  };
+  const arm = (g = geometry()) => {
+    if (!media.matches) {
+      clear();
+      return;
+    }
+    spacer = g.fits ? 0 : Math.min(spacer, g.maxOffset);
+    track.style.setProperty("--sd-rail-offset", `${spacer}px`);
+    rail.style.position = "sticky";
+    rail.style.top = g.fits ? `${g.top}px` : direction === "down" ? `${g.viewportBottom - g.height}px` : "auto";
+    rail.style.bottom = g.fits || direction === "down" ? "auto" : `${window.innerHeight - g.top - g.height}px`;
+  };
+  const onScroll = () => {
+    const y = window.scrollY;
+    const next = y > lastY ? "down" : y < lastY ? "up" : direction;
+    if (next !== direction && media.matches) {
+      const g = geometry();
+      spacer = direction === "down" ? Math.min(Math.max(spacer, lastY + g.viewportBottom - g.height - g.trackTop), g.maxOffset) : Math.max(Math.min(spacer, lastY + g.top - g.trackTop), 0);
+      direction = next;
+      arm(g);
+    }
+    direction = next;
+    lastY = y;
+  };
+  const relayout = () => arm();
+  const observer = new ResizeObserver(relayout);
+  observer.observe(rail);
+  observer.observe(track);
+  observer.observe(header);
+  window.addEventListener("scroll", onScroll, { passive: true });
+  window.addEventListener("resize", relayout);
+  media.addEventListener("change", relayout);
+  arm();
+  return () => {
+    observer.disconnect();
+    window.removeEventListener("scroll", onScroll);
+    window.removeEventListener("resize", relayout);
+    media.removeEventListener("change", relayout);
+    clear();
+  };
+}
+
+// src/toc.tsx
 import { Fragment, jsx as jsx5, jsxs as jsxs3 } from "react/jsx-runtime";
 var STORY_PARAM = "story";
 var SCROLL_OFFSET_PX = 76;
@@ -535,34 +618,9 @@ var slugify = (text) => text.normalize("NFKD").replace(/[̀-ͯ]/g, "").toLowerCa
 function useRailFollow(ref, ready = true) {
   useEffect3(() => {
     const element = ref.current;
-    if (!element) return;
-    let frame = 0;
-    let applied = 0;
-    const limit = () => window.innerHeight - (Number.parseFloat(getComputedStyle(document.documentElement).getPropertyValue("--sd-header-height")) || 56) - 20;
-    const apply = () => {
-      frame = 0;
-      const bottomInDocument = element.getBoundingClientRect().bottom + window.scrollY - applied;
-      const crossing = bottomInDocument - limit();
-      const next = Math.max(0, window.scrollY - crossing);
-      if (next !== applied) {
-        applied = next;
-        element.style.setProperty("--sd-rail-follow", `${next}px`);
-      }
-    };
-    const schedule = () => {
-      if (!frame) frame = requestAnimationFrame(apply);
-    };
-    apply();
-    window.addEventListener("scroll", schedule, { passive: true });
-    window.addEventListener("resize", schedule);
-    const observer = new ResizeObserver(schedule);
-    observer.observe(element);
-    return () => {
-      window.removeEventListener("scroll", schedule);
-      window.removeEventListener("resize", schedule);
-      observer.disconnect();
-      if (frame) cancelAnimationFrame(frame);
-    };
+    const header = element?.closest(".app")?.querySelector(".top");
+    if (!element || !header) return;
+    return followRail(element, header);
   }, [ready, ref]);
 }
 function scanPage(root, pageKey) {
@@ -706,7 +764,7 @@ function PageRail({ pageKey }) {
   const active = useActiveIds(scan);
   const go = useCallback((element) => scrollToElement(element), []);
   if (!scan) return null;
-  return /* @__PURE__ */ jsx5(Fragment, { children: scan.sections.length > 0 ? /* @__PURE__ */ jsxs3("aside", { className: "toc", "aria-label": "On this page", ref: railRef, children: [
+  return /* @__PURE__ */ jsx5(Fragment, { children: scan.sections.length > 0 ? /* @__PURE__ */ jsx5("div", { className: "rail-track toc-track", children: /* @__PURE__ */ jsxs3("aside", { className: "toc", "aria-label": "On this page", ref: railRef, children: [
     /* @__PURE__ */ jsx5("div", { className: "toc-title", children: "On this page" }),
     /* @__PURE__ */ jsx5("ul", { children: scan.sections.map((section) => /* @__PURE__ */ jsxs3("li", { children: [
       /* @__PURE__ */ jsx5(
@@ -731,7 +789,7 @@ function PageRail({ pageKey }) {
         }
       ) }, story.id)) }) : null
     ] }, section.id)) })
-  ] }) : null });
+  ] }) }) : null });
 }
 
 // src/component-demo.tsx
@@ -992,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]);
@@ -1251,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
@@ -1276,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 })
   ] });
 }
 
@@ -1801,6 +1857,23 @@ 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;
+  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
+    ] })
+  ] });
+}
 function parseRoute(hash) {
   const path = hashPath(hash).replace(new RegExp(`^#?\\/?${STORYBOOK_DOCS_BASE}`), "").replace(/^\/+/, "");
   if (path.startsWith("components/")) {
@@ -1909,7 +1982,7 @@ function DocsApp() {
         /* @__PURE__ */ jsx16("span", { "aria-hidden": "true", children: "\u2197" })
       ] }, link.href))
     ] }),
-    /* @__PURE__ */ jsxs13("nav", { id: "docs-nav", className: navOpen ? "nav open" : "nav", "aria-label": "Documentation", ref: navRef, children: [
+    /* @__PURE__ */ jsx16("div", { className: "rail-track nav-track", children: /* @__PURE__ */ jsxs13("nav", { id: "docs-nav", className: navOpen ? "nav open" : "nav", "aria-label": "Documentation", ref: navRef, children: [
       /* @__PURE__ */ jsx16("a", { href: routeHref("/"), className: route.kind === "overview" ? "on" : void 0, "aria-current": route.kind === "overview" ? "page" : void 0, children: "Overview" }),
       releases2.changelog ? /* @__PURE__ */ jsxs13(
         "a",
@@ -1926,22 +1999,20 @@ function DocsApp() {
           ]
         }
       ) : null,
-      foundations.length > 0 ? /* @__PURE__ */ jsxs13("div", { role: "group", "aria-labelledby": "nav-grp-foundations", children: [
-        /* @__PURE__ */ jsx16("div", { className: "grp", id: "nav-grp-foundations", children: "Foundations" }),
-        foundations.map((item) => /* @__PURE__ */ jsx16(
-          "a",
-          {
-            href: item.href,
-            className: route.kind === item.kind ? "on" : void 0,
-            "aria-current": route.kind === item.kind ? "page" : void 0,
-            children: item.label
-          },
-          item.href
-        ))
-      ] }) : null,
-      groups2.map((group, index) => /* @__PURE__ */ jsxs13("div", { role: "group", "aria-labelledby": `nav-grp-${index}`, children: [
-        /* @__PURE__ */ jsx16("div", { className: "grp", id: `nav-grp-${index}`, children: group }),
-        catalog3.filter((entry) => entry.group === group).map((entry) => /* @__PURE__ */ jsx16(
+      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(
+        "a",
+        {
+          href: item.href,
+          className: route.kind === item.kind ? "on" : void 0,
+          "aria-current": route.kind === item.kind ? "page" : void 0,
+          children: item.label
+        },
+        item.href
+      )) }, `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(
           "a",
           {
             href: routeHref(`/components/${entry.slug}`),
@@ -1952,9 +2023,9 @@ function DocsApp() {
             children: entry.name
           },
           entry.slug
-        ))
-      ] }, group))
-    ] }),
+        )) }, `${group}-${activeSlug ?? route.kind}`);
+      })
+    ] }) }),
     /* @__PURE__ */ jsx16("main", { id: "main", className: "main", tabIndex: -1, ref: mainRef, children: route.kind === "component" ? /* @__PURE__ */ jsx16(ComponentPage, { entry: catalog3.find((entry) => entry.slug === route.slug) }) : route.kind === "color" ? /* @__PURE__ */ jsx16(ColorPage, {}) : route.kind === "typography" ? /* @__PURE__ */ jsx16(TypePage, {}) : route.kind === "spacing" ? /* @__PURE__ */ jsx16(SpacingPage, {}) : route.kind === "effects" ? /* @__PURE__ */ jsx16(EffectsPage, {}) : route.kind === "releases" ? /* @__PURE__ */ jsx16(ReleasesPage, {}) : /* @__PURE__ */ jsx16(OverviewPage, {}) }),
     route.kind !== "overview" ? /* @__PURE__ */ jsx16(PageRail, { pageKey: activeSlug ?? route.kind }) : null
   ] });

package/dist/rail.d.ts

@@ -0,0 +1 @@
+export declare function followRail(rail: HTMLElement, header: HTMLElement): () => void;

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

@@ -186,23 +186,44 @@ body {
   outline-offset: 2px;
 }
 
+.rail-track {
+  overflow-anchor: none;
+  min-width: 0;
+}
+@media (min-width: 1180px) {
+  .rail-track::before {
+    content: '';
+    display: block;
+    height: var(--sd-rail-offset, 0px);
+  }
+}
 .nav {
   border-right: 0;
   background: var(--sd-surface);
-  padding: 14px 12px 80px;
-  /* Follows the document like the right rail, parking when its own end is visible. */
-  align-self: start;
-  transform: translateY(var(--sd-rail-follow, 0px));
+  padding: 14px 12px 12px;
 }
-.nav a {
-  display: block;
-  padding: 6px 10px;
+.nav a,
+.nav-more {
+  display: flex;
+  align-items: center;
+  box-sizing: border-box;
+  min-height: 28px;
+  padding: 4px 10px;
   border-radius: 8px;
   color: var(--sd-text-muted);
   font-size: 13.5px;
   text-decoration: none;
 }
-.nav a:hover {
+.nav-more {
+  width: 100%;
+  background: none;
+  border: 0;
+  font-family: inherit;
+  cursor: pointer;
+  text-align: left;
+}
+.nav a:hover,
+.nav-more:hover {
   background: var(--sd-surface-hover);
   color: var(--sd-text);
 }
@@ -212,13 +233,26 @@ body {
   font-weight: 600;
 }
 .grp {
-  margin: 16px 0 4px;
+  margin: 3px 0 2px;
   padding: 0 10px;
   font-size: 10.5px;
   letter-spacing: 0.09em;
   text-transform: uppercase;
   color: var(--sd-text-muted);
   font-weight: 700;
+  display: block;
+  width: 100%;
+  text-align: left;
+  font-family: inherit;
+  background: none;
+  border: 0;
+  cursor: pointer;
+  min-height: 28px;
+}
+.grp:focus-visible,
+.nav-more:focus-visible {
+  outline: 2px solid var(--sd-focus-ring);
+  outline-offset: 2px;
 }
 
 .main {
@@ -618,6 +652,9 @@ code.type {
   .nav-toggle {
     display: inline-block;
   }
+  .nav-track {
+    display: contents;
+  }
   .search {
     order: 10;
     flex: 1 1 100%;

package/dist/toc.d.ts

@@ -6,12 +6,6 @@ export declare function hashPath(hash: string): string;
 /** The `?story=` deep-link target of a hash, if any. */
 export declare function storyFromHash(hash: string): string | null;
 export declare function storyLink(location: Location, story: string): string;
-/**
- * A rail travels with the document until its own end would pass the fold, then it parks there —
- * the reader keeps seeing where it continues, and scrolling up lets it fall back into flow. This is
- * the scroll-linked translation docs sites use, because `position: sticky` cannot move an element
- * taller than the viewport.
- */
 export declare function useRailFollow(ref: RefObject<HTMLElement | null>, ready?: boolean): void;
 /** The "On this page" rail and the `?story=` deep-link landing. */
 export declare function PageRail({ pageKey }: {

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.5.0",
+  "version": "0.7.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": {