@jfrader/storybook-docs 0.4.4 → 0.6.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/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,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 { 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";
 
 // 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);
@@ -510,6 +511,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;
@@ -534,34 +606,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) {
@@ -705,7 +752,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(
@@ -730,7 +777,7 @@ function PageRail({ pageKey }) {
         }
       ) }, story.id)) }) : null
     ] }, section.id)) })
-  ] }) : null });
+  ] }) }) : null });
 }
 
 // src/component-demo.tsx
@@ -980,7 +1027,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);
@@ -996,12 +1043,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,
@@ -1049,6 +1097,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";
@@ -1175,6 +1224,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 ?? {};
@@ -1246,7 +1308,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: [
@@ -1256,7 +1318,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" }),
@@ -1577,7 +1639,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
@@ -1628,19 +1690,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();
@@ -1663,7 +1725,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" });
@@ -1785,6 +1847,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/")) {
@@ -1799,14 +1878,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;
@@ -1821,7 +1900,7 @@ function DocsApp() {
       else root.style.removeProperty("--sd-header-height");
     };
   }, []);
-  useEffect7(() => {
+  useEffect8(() => {
     const onHash = () => {
       setRoute(parseRoute(window.location.hash));
       setNavOpen(false);
@@ -1831,7 +1910,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"];
@@ -1893,7 +1972,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",
@@ -1910,22 +1989,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}`),
@@ -1936,9 +2013,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

@@ -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

@@ -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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jfrader/storybook-docs",
-  "version": "0.4.4",
+  "version": "0.6.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": {