@jfrader/storybook-docs 0.4.3 → 0.5.0

package/dist/build/story-sources.d.ts

@@ -0,0 +1,15 @@
+interface HelperExpansion {
+    inlined: string[];
+    remaining: {
+        name: string;
+        reason: string;
+    }[];
+}
+export declare function extractStorySourceDetails(source: string): {
+    sources: Record<string, string>;
+    helpers: Record<string, HelperExpansion>;
+};
+export declare function extractStorySources(source: string): Record<string, string>;
+export declare function storySourcesIndexCode(slugs: Iterable<string>): string;
+export declare function storySourcesCode(sources: Record<string, string>): string;
+export {};

package/dist/controls.d.ts

@@ -40,10 +40,11 @@ export declare function getStoryControls(meta: StoryShape, story: StoryShape, co
     controls: StoryControl[];
     unavailable: string | null;
 };
-export declare function ControlledStoryFrame({ module, story, componentName, componentDefaults }: {
+export declare function ControlledStoryFrame({ module, story, componentName, componentDefaults, renderSource }: {
     module: Record<string, unknown>;
     story: string;
     componentName: string;
     /** Defaults read from the component source, shown until the reader changes them. */
     componentDefaults?: Record<string, unknown>;
+    renderSource?: string;
 }): import("react").JSX.Element;

package/dist/css.d.ts

@@ -0,0 +1 @@
+declare module '*.css';

package/dist/index.css

@@ -114,11 +114,8 @@
     display: block;
     grid-column: 3;
     grid-row: 2;
-    position: sticky;
-    top: var(--sd-header-height, 56px);
     align-self: start;
-    max-height: calc(100dvh - var(--sd-header-height, 56px));
-    overflow-y: auto;
+    transform: translateY(var(--sd-rail-follow, 0px));
     padding: 34px 18px 40px 6px;
     font-size: 12.5px;
   }
@@ -173,13 +170,12 @@
   margin: 0;
   padding: 0 20px 18px;
   min-width: 0;
-  border: 0;
   background: none;
   color: var(--sd-text-muted);
   font-size: 13px;
 }
-.sd-controls legend {
-  padding: 0;
+.sd-controls-label {
+  margin: 16px 0 10px;
   font-size: 11px;
   font-weight: 600;
   letter-spacing: 0.06em;

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 /// <reference path="./virtual.d.ts" />
+/// <reference path="./css.d.ts" />
 export { start } from './start.js';
 export { ComponentDemo, type ComponentDemoProps } from './component-demo.js';
 export type { StorybookDocsConfig, CatalogEntry, ThemeRole } from './config.js';

package/dist/index.js

@@ -5,12 +5,12 @@ 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 useEffect7, useRef as useRef5, useState as useState8 } from "react";
-import { catalog as catalog3, groups as groups2, stats as stats2 } from "virtual:storybook-docs/catalog";
+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";
 
 // src/pages/component-page.tsx
-import { useMemo as useMemo3 } from "react";
+import { useEffect as useEffect6, useMemo as useMemo3, useState as useState7 } from "react";
 import { storySource as storySource2 } from "virtual:storybook-docs/catalog";
 
 // src/guidance.tsx
@@ -374,7 +374,8 @@ function usageSnippet(componentName, args) {
   const children = typeof args.children === "string" && !/[&<>{}]/.test(args.children) ? args.children : `{${JSON.stringify(args.children)}}`;
   return `${opening}>${children}</${componentName}>`;
 }
-function buildUsageSnippet({ componentName, from, args, source, jsxName, component }) {
+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);
@@ -531,6 +532,39 @@ function storyLink(location, story) {
   return `${base}${hashPath(location.hash)}?${new URLSearchParams({ [STORY_PARAM]: story })}`;
 }
 var slugify = (text) => text.normalize("NFKD").replace(/[̀-ͯ]/g, "").toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
+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);
+    };
+  }, [ready, ref]);
+}
 function scanPage(root, pageKey) {
   const used = /* @__PURE__ */ new Set();
   const unique = (prefix, text) => {
@@ -542,9 +576,12 @@ function scanPage(root, pageKey) {
   };
   const sections = [];
   const frames = [];
-  const subHeadings = [...root.querySelectorAll("h3")].filter((heading) => heading.textContent);
+  const subHeadings = [...root.querySelectorAll("h3")].filter(
+    (heading) => heading.textContent && !heading.closest(".story-lane") && !heading.closest(".frame")
+  );
   root.querySelectorAll("h2").forEach((heading) => {
     if (!heading.textContent) return;
+    if (heading.closest(".story-lane") || heading.closest(".frame")) return;
     heading.id ||= unique("section", heading.textContent);
     heading.dataset.toc = "";
     const section = heading.parentElement?.tagName === "SECTION" ? heading.parentElement : null;
@@ -570,6 +607,13 @@ function scanPage(root, pageKey) {
     });
     sections.push({ id: heading.id, title: heading.textContent, element: section ?? heading, heading, stories, subs });
   });
+  const counts = /* @__PURE__ */ new Map();
+  for (const item of frames) counts.set(item.name, (counts.get(item.name) ?? 0) + 1);
+  for (const item of frames) {
+    if ((counts.get(item.name) ?? 0) > 1 && item.story && item.story !== item.name) {
+      item.name = `${item.name} \xB7 ${item.story}`;
+    }
+  }
   return { pageKey, sections, frames };
 }
 var signature = (scan) => `${scan.pageKey}|${scan.sections.map((s) => `${s.id}(${s.subs.map((sub) => sub.id).join("+")}):${s.stories.map((st) => `${st.id}:${st.name}`).join(",")}`).join(";")}`;
@@ -657,10 +701,12 @@ function PageRail({ pageKey }) {
     window.setTimeout(() => match.element.classList.remove("toc-flash"), FLASH_MS);
     setTarget(null);
   }, [target, scan, pageKey]);
+  const railRef = useRef2(null);
+  useRailFollow(railRef, scan !== null);
   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", children: [
+  return /* @__PURE__ */ jsx5(Fragment, { children: scan.sections.length > 0 ? /* @__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(
@@ -799,6 +845,7 @@ function ComponentDemo({
   children
 }) {
   const [codeOpen, setCodeOpen] = useState4(false);
+  const controlsLabelId = useId();
   const canvasRef = useRef3(null);
   const [scrollable, setScrollable] = useState4(false);
   useEffect4(() => {
@@ -844,8 +891,8 @@ function ComponentDemo({
       skipped.join(", "),
       ". See it in Storybook."
     ] }) : null,
-    unavailable ? /* @__PURE__ */ jsx6("p", { className: "sd-controls-note", children: unavailable }) : /* @__PURE__ */ jsxs4("fieldset", { className: "sd-controls", children: [
-      /* @__PURE__ */ jsxs4("legend", { children: [
+    unavailable ? /* @__PURE__ */ jsx6("p", { className: "sd-controls-note", children: unavailable }) : /* @__PURE__ */ jsxs4("div", { className: "sd-controls", role: "group", "aria-labelledby": controlsLabelId, children: [
+      /* @__PURE__ */ jsxs4("p", { className: "sd-controls-label", id: controlsLabelId, children: [
         "Controls for ",
         storyName
       ] }),
@@ -934,7 +981,7 @@ function getStoryControls(meta, story, componentDefaults = {}) {
     unavailable: controls.length === 0 ? "No controls." : null
   };
 }
-function ControlledStoryFrame({ module, story, componentName, componentDefaults }) {
+function ControlledStoryFrame({ module, story, componentName, componentDefaults, renderSource }) {
   const meta = module.default ?? {};
   const definition = module[story] ?? {};
   const { args: defaults, controls, unavailable } = getStoryControls(meta, definition, componentDefaults);
@@ -950,12 +997,13 @@ function ControlledStoryFrame({ module, story, componentName, componentDefaults
   const storyName = definition.name ?? story;
   const skipped = ["loaders", "beforeEach"].filter((key) => meta[key] || definition[key]);
   if (definition.parameters?.viewport ?? meta.parameters?.viewport) skipped.push("viewport");
-  const codeLanguage = docsOverride?.source?.language ?? docsMeta?.source?.language ?? "tsx";
+  const codeLanguage = authoredCode?.trim() ? docsOverride?.source?.language ?? docsMeta?.source?.language ?? "tsx" : "tsx";
   const snippet = buildUsageSnippet({
     componentName,
     from: storySource,
     args: { ...meta.args, ...definition.args, ...edits },
     source: authoredCode,
+    renderSource,
     // A story name is not a component name: only a part-qualified name (the rare `Dialog.Content`
     // story) is worth using as the JSX tag, otherwise the component's own name is the honest one.
     jsxName: storyName.includes(".") ? storyName : void 0,
@@ -1003,6 +1051,7 @@ function useProps(slug) {
 }
 
 // src/pages/component-page.tsx
+import { loadStorySources } from "virtual:storybook-docs/story-sources";
 import { Fragment as Fragment3, jsx as jsx8, jsxs as jsxs5 } from "react/jsx-runtime";
 function formatValue(value) {
   if (value === void 0) return "\u2014";
@@ -1129,6 +1178,19 @@ function PropsTable({
 }
 function ComponentPage({ entry }) {
   const { module, error } = useStoryModule(entry);
+  const [storySources, setStorySources] = useState7(null);
+  useEffect6(() => {
+    let active = true;
+    loadStorySources(entry.slug).then(({ sources: sources2 }) => {
+      if (active) setStorySources({ slug: entry.slug, sources: sources2 });
+    }).catch(() => {
+      if (active) setStorySources(null);
+    });
+    return () => {
+      active = false;
+    };
+  }, [entry.slug]);
+  const sources = storySources?.slug === entry.slug ? storySources.sources : {};
   const props = useProps(entry.slug);
   const meta = module?.default ?? {};
   const argTypes = meta.argTypes ?? {};
@@ -1200,7 +1262,7 @@ function ComponentPage({ entry }) {
       /* @__PURE__ */ jsx8(Skeleton, { height: 150 })
     ] }) : null,
     module ? /* @__PURE__ */ jsxs5(Fragment3, { children: [
-      example ? /* @__PURE__ */ jsx8(ControlledStoryFrame, { module, story: example, componentName: entry.name, componentDefaults }, `${entry.slug}:${example}`) : null,
+      example ? /* @__PURE__ */ jsx8(ControlledStoryFrame, { module, story: example, componentName: entry.name, componentDefaults, renderSource: sources[example] }, `${entry.slug}:${example}`) : null,
       entry.hasComponent ? /* @__PURE__ */ jsx8("h2", { children: "Usage" }) : null,
       snippet ? /* @__PURE__ */ jsx8(CodeBlock, { code: snippet, language: codeLanguage }) : entry.hasComponent ? /* @__PURE__ */ jsx8("p", { children: "No usage code is authored for this component." }) : null,
       usage ? /* @__PURE__ */ jsxs5(Fragment3, { children: [
@@ -1210,7 +1272,7 @@ function ComponentPage({ entry }) {
       /* @__PURE__ */ jsx8(Guidance, { slug: entry.slug }),
       sections.map((section) => /* @__PURE__ */ jsxs5("section", { children: [
         /* @__PURE__ */ jsx8("h2", { children: section.title }),
-        section.stories.map((story) => /* @__PURE__ */ jsx8(ControlledStoryFrame, { module, story, componentName: entry.name, componentDefaults }, `${entry.slug}:${story}`))
+        section.stories.map((story) => /* @__PURE__ */ jsx8(ControlledStoryFrame, { module, story, componentName: entry.name, componentDefaults, renderSource: sources[story] }, `${entry.slug}:${story}`))
       ] }, section.title))
     ] }) : null,
     /* @__PURE__ */ jsx8("h2", { children: "Props" }),
@@ -1531,7 +1593,7 @@ function ReleasesPage() {
 }
 
 // src/search.tsx
-import { useEffect as useEffect6, useMemo as useMemo4, useRef as useRef4, useState as useState7 } from "react";
+import { useEffect as useEffect7, useMemo as useMemo4, useRef as useRef4, useState as useState8 } from "react";
 import { catalog as catalog2 } from "virtual:storybook-docs/catalog";
 
 // src/search-match.ts
@@ -1582,19 +1644,19 @@ function renderHighlighted(text, query) {
   );
 }
 function SearchBox() {
-  const [query, setQuery] = useState7("");
-  const [open, setOpen] = useState7(false);
-  const [active, setActive] = useState7(0);
+  const [query, setQuery] = useState8("");
+  const [open, setOpen] = useState8(false);
+  const [active, setActive] = useState8(0);
   const inputRef = useRef4(null);
   const listId = "storybook-docs-search-results";
   const optionId = (key) => `${listId}-${key}`;
   const results = useMemo4(() => {
     return searchCatalog(catalog2, query);
   }, [query]);
-  useEffect6(() => {
+  useEffect7(() => {
     setActive(0);
   }, [query]);
-  useEffect6(() => {
+  useEffect7(() => {
     const onGlobalKeyDown = (event) => {
       if ((event.metaKey || event.ctrlKey) && event.key.toLowerCase() === "k") {
         event.preventDefault();
@@ -1617,7 +1679,7 @@ function SearchBox() {
   const showDropdown = open && (hasResults || hasQuery);
   const activeRow = hasResults && results[active] ? results[active] : void 0;
   const activeOptionId = activeRow ? optionId(rowKey(activeRow)) : void 0;
-  useEffect6(() => {
+  useEffect7(() => {
     if (showDropdown && activeOptionId) {
       const el = document.getElementById(activeOptionId);
       el?.scrollIntoView({ block: "nearest" });
@@ -1753,12 +1815,14 @@ function parseRoute(hash) {
   return { kind: "overview" };
 }
 function DocsApp() {
-  const [route, setRoute] = useState8(() => parseRoute(window.location.hash));
-  const [mode, setMode] = useState8(theme.values?.[0] ?? "dark");
-  const [navOpen, setNavOpen] = useState8(false);
+  const [route, setRoute] = useState9(() => parseRoute(window.location.hash));
+  const [mode, setMode] = useState9(theme.values?.[0] ?? "dark");
+  const [navOpen, setNavOpen] = useState9(false);
+  const navRef = useRef5(null);
+  useRailFollow(navRef);
   const headerRef = useRef5(null);
   const mainRef = useRef5(null);
-  useEffect7(() => {
+  useEffect8(() => {
     const header = headerRef.current;
     if (!header) return;
     const root = document.documentElement;
@@ -1773,7 +1837,7 @@ function DocsApp() {
       else root.style.removeProperty("--sd-header-height");
     };
   }, []);
-  useEffect7(() => {
+  useEffect8(() => {
     const onHash = () => {
       setRoute(parseRoute(window.location.hash));
       setNavOpen(false);
@@ -1783,7 +1847,7 @@ function DocsApp() {
     window.addEventListener("hashchange", onHash);
     return () => window.removeEventListener("hashchange", onHash);
   }, []);
-  useEffect7(() => {
+  useEffect8(() => {
     document.documentElement.setAttribute(theme.attribute ?? "data-theme", mode);
   }, [mode]);
   const [darkMode, lightMode] = theme.values ?? ["dark", "light"];
@@ -1845,7 +1909,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", 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",
@@ -1889,14 +1953,7 @@ function DocsApp() {
           },
           entry.slug
         ))
-      ] }, group)),
-      /* @__PURE__ */ jsxs13("div", { className: "nav-note", children: [
-        "navigation, examples and API tables generated from ",
-        stats2.components,
-        " story files \xB7 ",
-        stats2.stories,
-        " stories"
-      ] })
+      ] }, group))
     ] }),
     /* @__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/sections.d.ts

@@ -42,11 +42,12 @@ export interface ExampleStory {
 export declare function selectExample(stories: ExampleStory[], parts?: string[], defaults?: Record<string, unknown> | null): string | null;
 /** Only story-authored values: never synthesize children or component defaults. */
 export declare function usageSnippet(componentName: string, args: Record<string, unknown> | undefined): string | null;
-export declare function buildUsageSnippet({ componentName, from, args, source, jsxName, component }: {
+export declare function buildUsageSnippet({ componentName, from, args, source, renderSource, jsxName, component }: {
     componentName: string;
     from: string;
     args?: Record<string, unknown>;
     source?: string;
+    renderSource?: string;
     jsxName?: string;
     component?: unknown;
 }): string | null;

package/dist/styles.css

@@ -190,6 +190,9 @@ body {
   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));
 }
 .nav a {
   display: block;
@@ -217,12 +220,6 @@ body {
   color: var(--sd-text-muted);
   font-weight: 700;
 }
-.nav-note {
-  margin: 22px 10px 0;
-  font-size: 11.5px;
-  line-height: 1.6;
-  color: var(--sd-text-muted);
-}
 
 .main {
   padding: 48px clamp(28px, 4vw, 64px) 160px;

package/dist/toc.d.ts

@@ -1,9 +1,18 @@
+/** @jsxImportSource react */
+import { type RefObject } from 'react';
 import './toc.css';
 /** The hash without its query: `#/components/button?story=Variants` → `#/components/button`. */
 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 }: {
     pageKey: string;

package/dist/virtual.d.ts

@@ -28,6 +28,10 @@ declare module 'virtual:storybook-docs/guidance' {
   export function loadGuidance(slug: string): Promise<{ markdown: string }>;
 }
 
+declare module 'virtual:storybook-docs/story-sources' {
+  export function loadStorySources(slug: string): Promise<{ sources: Record<string, string> }>;
+}
+
 declare module 'virtual:storybook-docs/releases' {
   export const releases: { version: string | null; changelog: string | null };
 }

package/dist/vite-plugin.js

@@ -608,6 +608,222 @@ export const fireEvent = () => true;
 export const cleanup = () => {};
 `;
 
+// src/build/story-sources.ts
+import ts2 from "typescript";
+function unwrap(node) {
+  while (ts2.isParenthesizedExpression(node) || ts2.isAsExpression(node) || ts2.isSatisfiesExpression(node) || ts2.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 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)) {
+      for (const declaration of statement.declarationList.declarations) {
+        if (!ts2.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) {
+      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)) {
+      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;
+    node = unwrap(node);
+    if (ts2.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;
+    for (const property of [...node.properties].reverse()) {
+      if (ts2.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;
+        return null;
+      }
+    }
+  };
+  const hasJsx = (node) => ts2.isJsxElement(node) || ts2.isJsxSelfClosingElement(node) || ts2.isJsxFragment(node) || (ts2.forEachChild(node, hasJsx) ?? false);
+  const returnsCache = /* @__PURE__ */ new Map();
+  const returnCounts = /* @__PURE__ */ new Map();
+  const returnedJsx = (render) => {
+    const cached = returnsCache.get(render);
+    if (cached) return cached;
+    const expressions = [];
+    if (!render.body) return expressions;
+    let returnCount = 0;
+    if (ts2.isBlock(render.body)) {
+      const visit = (node) => {
+        if (ts2.isFunctionLike(node)) return;
+        if (ts2.isReturnStatement(node)) {
+          returnCount += 1;
+          if (node.expression && hasJsx(node.expression)) expressions.push(unwrap(node.expression));
+          return;
+        }
+        ts2.forEachChild(node, visit);
+      };
+      ts2.forEachChild(render.body, visit);
+    } else {
+      returnCount = 1;
+      if (hasJsx(render.body)) expressions.push(unwrap(render.body));
+    }
+    returnsCache.set(render, expressions);
+    returnCounts.set(render, returnCount);
+    return expressions;
+  };
+  const helperFor = (name, seen = /* @__PURE__ */ new Set()) => {
+    if (seen.has(name)) return;
+    seen.add(name);
+    const declaration = declarations.get(name);
+    if (!declaration) return;
+    if (ts2.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;
+  };
+  const bindingContains = (binding, name) => ts2.isIdentifier(binding) ? binding.text === name : binding.elements.some((element) => ts2.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;
+    }
+    return false;
+  };
+  const mapCache = /* @__PURE__ */ new Map();
+  const hasUnknownMap = (helper, jsx) => {
+    const cached = mapCache.get(jsx);
+    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);
+    }
+    const bind = (scope2, name, initializer) => {
+      if (ts2.isIdentifier(name)) scope2.set(name.text, initializer);
+      else for (const element of name.elements) {
+        if (ts2.isBindingElement(element)) bind(scope2, element.name, element.initializer);
+      }
+    };
+    const addScope = (node, parent) => {
+      const scope2 = new Map(parent);
+      if (ts2.isFunctionLike(node)) {
+        for (const parameter of node.parameters) bind(scope2, parameter.name, parameter.initializer);
+      }
+      if (ts2.isBlock(node)) {
+        for (const statement of node.statements) {
+          if (ts2.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);
+        }
+      }
+      return scope2;
+    };
+    const ancestors = [];
+    for (let node = jsx.parent; node !== helper; node = node.parent) ancestors.push(node);
+    let scope = addScope(helper, bindings);
+    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 (ts2.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)) {
+        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)) {
+        const target = node.expression;
+        const map = ts2.isPropertyAccessExpression(target) && target.name.text === "map" || ts2.isElementAccessExpression(target) && ts2.isStringLiteral(target.argumentExpression) && target.argumentExpression.text === "map";
+        if (map && !knownCollection(target.expression, bindings2)) return true;
+      }
+      return ts2.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 helper = name && helperFor(name);
+    if (!name || !declarations.has(name)) return expression.getText(file);
+    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)}`;
+    }
+    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;
+    if (reason) {
+      detail.remaining.push({ name, reason });
+      return `// ${name} not expanded: ${reason}.
+${expression.getText(file)}`;
+    }
+    detail.inlined.push(name);
+    return `// JSX from ${name}, as authored.
+${inlineRoot(jsx, detail, [...trail, name])}`;
+  };
+  const sources = {};
+  const helpers = {};
+  for (const [name, local] of exports) {
+    const declaration = declarations.get(local);
+    const render = declaration && renderFor(declaration);
+    if (!render?.body) continue;
+    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.
+${jsx}` : jsx;
+      if (detail.inlined.length || detail.remaining.length) helpers[name] = detail;
+    }
+  }
+  return { sources, helpers };
+}
+function extractStorySources(source) {
+  return extractStorySourceDetails(source).sources;
+}
+function storySourcesIndexCode(slugs) {
+  return `
+export function loadStorySources(slug) {
+  switch (slug) {
+${[...slugs].map((slug) => `    case ${JSON.stringify(slug)}: return import(${JSON.stringify(`${VIRTUAL_PREFIX}story-sources/${slug}`)});`).join("\n")}
+    default: return Promise.resolve({ sources: {} });
+  }
+}
+`;
+}
+function storySourcesCode(sources) {
+  return `export const sources = ${JSON.stringify(sources)};`;
+}
+
 // src/vite-plugin.ts
 function storybookDocs(options) {
   const { config } = options;
@@ -616,6 +832,7 @@ function storybookDocs(options) {
   catalog.files.clear();
   const engineStyles = path7.join(import.meta.dirname, "styles.css");
   const propsCache = /* @__PURE__ */ new Map();
+  const storySourcesCache = /* @__PURE__ */ new Map();
   const propsCollector = createPropsCollector();
   let guidanceFiles = /* @__PURE__ */ new Map();
   const loadProps = (slug) => {
@@ -636,6 +853,7 @@ export const storySource = ${JSON.stringify(config.stories.from)};`,
     "stub-storybook-test": () => STORYBOOK_TEST_STUB,
     props: () => propsIndexCode(catalog.entries.map((entry) => entry.slug)),
     guidance: () => guidanceIndexCode(guidanceFiles.keys()),
+    "story-sources": () => storySourcesIndexCode(catalog.files.keys()),
     releases: () => releasesCode(readReleases(config, projectRoot)),
     code: () => codeModuleCode(resolveCodeModule(config.code?.module, projectRoot))
   };
@@ -665,6 +883,7 @@ export const storySource = ${JSON.stringify(config.stories.from)};`,
     },
     buildStart() {
       propsCache.clear();
+      storySourcesCache.clear();
       propsCollector.clearPrograms();
     },
     closeBundle() {
@@ -682,11 +901,26 @@ export const storySource = ${JSON.stringify(config.stories.from)};`,
       const module = Object.hasOwn(modules, name) ? modules[name] : void 0;
       if (module) return module();
       if (name.startsWith("props/")) return loadProps(name.slice("props/".length));
+      if (name.startsWith("story-sources/")) {
+        const storyFile = catalog.files.get(name.slice("story-sources/".length));
+        if (!storyFile) return storySourcesCode({});
+        const file = realpathSync(storyFile);
+        let sources = storySourcesCache.get(file);
+        if (!sources) {
+          sources = extractStorySources(readFileSync3(file, "utf8"));
+          storySourcesCache.set(file, sources);
+        }
+        this.addWatchFile(file);
+        return storySourcesCode(sources);
+      }
       if (name.startsWith("guidance/")) {
         const file = guidanceFiles.get(name.slice("guidance/".length));
         return guidanceCode(file ? readFileSync3(file, "utf8") : "");
       }
       return null;
+    },
+    watchChange(file) {
+      storySourcesCache.delete(file);
     }
   };
 }

package/docs/RELEASING.md

@@ -125,3 +125,29 @@ Official npm references (check them when changing authentication):
 [trusted publishers](https://docs.npmjs.com/trusted-publishers/),
 [provenance](https://docs.npmjs.com/generating-provenance-statements/),
 [granular tokens](https://docs.npmjs.com/creating-and-viewing-access-tokens/).
+
+## First publish of a new package name
+
+Established procedure, after a morning spent rediscovering it:
+
+1. **`npm trust` works before the package exists.** `npm trust github <pkg> --repo <owner>/<repo> --file publish.yml --allow-publish`
+   returns **201** even for a name that has never been published, as long as you are authenticated. Do this first; it is
+   what lets every later `v*` tag publish itself through OIDC with provenance, no tokens.
+2. **Workflows that set `NODE_AUTH_TOKEN` cannot use trusted publishing.** An empty secret sends an
+   unauthenticated request and npm answers `404` on the `PUT`, which reads like a missing package. This workflow
+   therefore sets no token.
+3. **The first publish has to happen once from a machine** — the registry has no artifact yet:
+
+   ```bash
+   cd <the package checkout>
+   npm login --registry https://registry.npmjs.org     # prints a browser URL; no OTP code needed
+   NPM_CONFIG_USERCONFIG=<config> npm publish          # browser URL again, then "+ <pkg>@<version>"
+   ```
+
+   A `~/.npmrc` that maps the scope to another registry (e.g. `@scope:registry=https://npm.pkg.github.com/`) makes a
+   plain `npm publish` target that registry instead and fail with `403`. Point the scope at npmjs in the config used
+   for the publish.
+4. **Verify from the registry, not from the local output:** `curl -s https://registry.npmjs.org/<scope>%2f<pkg>`
+   must list the version. Until it does, nothing is published.
+5. After that, releases are tags: `git tag -a vX.Y.Z && git push origin vX.Y.Z`, and the publish workflow does the
+   rest. Do **not** push a tag for a version you already published by hand — npm rejects the duplicate.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jfrader/storybook-docs",
-  "version": "0.4.3",
+  "version": "0.5.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": {
@@ -27,12 +27,6 @@
     "react-dom": "^19.3.0",
     "vite": "^8.3.4"
   },
-  "packageManager": "pnpm@10.12.1",
-  "pnpm": {
-    "onlyBuiltDependencies": [
-      "esbuild"
-    ]
-  },
   "dependencies": {
     "marked": "^18.1.1",
     "react-docgen-typescript": "^2.4.0",
@@ -60,15 +54,6 @@
     "props",
     "docs"
   ],
-  "scripts": {
-    "test": "node --test test/*.test.ts",
-    "typecheck": "tsc --noEmit",
-    "build": "pnpm build:package && pnpm --dir examples/jfrader-ui build",
-    "build:package": "node scripts/build.mjs",
-    "smoke:package": "node scripts/smoke-package.mjs",
-    "check:frames": "node scripts/check-example-frames.mjs",
-    "prepack": "pnpm build:package"
-  },
   "engines": {
     "node": ">=22.12.0"
   },
@@ -81,5 +66,13 @@
   ],
   "sideEffects": [
     "**/*.css"
-  ]
-}
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.ts",
+    "typecheck": "tsc --noEmit",
+    "build": "pnpm build:package && pnpm --dir examples/jfrader-ui build",
+    "build:package": "node scripts/build.mjs",
+    "smoke:package": "node scripts/smoke-package.mjs",
+    "check:frames": "node scripts/check-example-frames.mjs"
+  }
+}