@jfrader/storybook-docs 0.8.0 → 0.9.1

package/dist/index.css

@@ -115,11 +115,13 @@
   }
   .toc-track {
     display: block;
+    min-width: 0;
     grid-column: 3;
     grid-row: 2;
   }
   .toc {
     display: block;
+    min-width: 0;
     padding: 34px 18px 40px 6px;
     font-size: 12.5px;
   }
@@ -140,9 +142,12 @@
     border-left: 1px solid var(--sd-border);
   }
   .toc-link {
-    display: flex;
-    align-items: center;
+    display: block;
     width: 100%;
+    min-width: 0;
+    overflow: hidden;
+    white-space: nowrap;
+    text-overflow: ellipsis;
     min-block-size: 24px;
     padding: 4px 8px;
     font: inherit;

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 { useEffect as useEffect8, useLayoutEffect as useLayoutEffect2, 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";
 
@@ -363,6 +363,9 @@ function serializable(value, ancestors = /* @__PURE__ */ new Set()) {
   ancestors.delete(value);
   return result;
 }
+function jsxRootTag(example) {
+  return example.replace(/^\s*\/\/[^\n]*(?:\n|$)/gm, "").match(/<([A-Za-z_$][\w$]*(?:\.[\w$]+)*)[\s/>]/)?.[1]?.split(".")[0];
+}
 function usageSnippet(componentName, args) {
   if (!args || Object.keys(args).length === 0) return null;
   const attributes = [];
@@ -374,8 +377,8 @@ function usageSnippet(componentName, args) {
     else attributes.push(`${key}={${JSON.stringify(value)}}`);
   }
   const opening = `<${componentName}${attributes.length ? ` ${attributes.join(" ")}` : ""}`;
-  if (args.children === void 0) return attributes.length ? `${opening} />` : null;
-  if (!serializable(args.children) || args.children !== null && typeof args.children === "object") return null;
+  if (args.children === void 0 || args.children === null) return attributes.length ? `${opening} />` : null;
+  if (!serializable(args.children) || typeof args.children === "object") return null;
   const children = typeof args.children === "string" && !/[&<>{}]/.test(args.children) ? args.children : `{${JSON.stringify(args.children)}}`;
   return `${opening}>${children}</${componentName}>`;
 }
@@ -389,11 +392,12 @@ function buildUsageSnippet({ componentName, from, args, source, renderSource, js
   const excerpt = extracted?.startsWith(STORY_EXCERPT);
   const example = source?.trim() || (excerpt ? generated() || extracted : extracted || generated());
   if (!example) return null;
+  const rootTag = jsxRootTag(example);
   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;
+  if (rootTag !== rootName) 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}';
@@ -522,11 +526,12 @@ function LazySection({ children, placeholder = "\u2026" }) {
 }
 
 // src/toc.tsx
-import { useCallback, useEffect as useEffect3, useRef as useRef2, useState as useState3 } from "react";
+import { useCallback, useEffect as useEffect3, useLayoutEffect, useRef as useRef2, useState as useState3 } from "react";
 
 // src/rail.ts
 var RAIL_MEDIA = "(min-width: 1180px)";
 var RAIL_GAP = 20;
+var RAIL_SETTLE_MS = 120;
 function followRail(rail, header) {
   const track = rail.parentElement;
   if (!track) return () => {
@@ -535,6 +540,8 @@ function followRail(rail, header) {
   let lastY = window.scrollY;
   let direction = "down";
   let spacer = 0;
+  let scrolling = false;
+  let settleTimer;
   const geometry = () => {
     const top = header.offsetHeight + RAIL_GAP;
     const viewportBottom = window.innerHeight - RAIL_GAP;
@@ -544,8 +551,8 @@ function followRail(rail, header) {
       viewportBottom,
       height,
       fits: top + height <= viewportBottom,
-      trackTop: track.getBoundingClientRect().top + window.scrollY,
-      maxOffset: Math.max(0, track.clientHeight - height)
+      trackTop: track.getBoundingClientRect().top + window.scrollY + RAIL_GAP,
+      maxOffset: Math.max(0, track.clientHeight - height - RAIL_GAP)
     };
   };
   const clear = () => {
@@ -558,17 +565,28 @@ function followRail(rail, header) {
       return;
     }
     spacer = g.fits ? 0 : Math.min(spacer, g.maxOffset);
+    track.style.setProperty("--sd-rail-start", `${RAIL_GAP}px`);
     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";
+    const parkedTop = g.fits ? g.top : g.viewportBottom - g.height;
+    const armedTop = Number.parseFloat(rail.style.top);
+    const stableTop = scrolling && Number.isFinite(armedTop) ? Math.min(armedTop, parkedTop) : parkedTop;
+    rail.style.top = g.fits || direction === "down" ? `${stableTop}px` : "auto";
     rail.style.bottom = g.fits || direction === "down" ? "auto" : `${window.innerHeight - g.top - g.height}px`;
   };
   const onScroll = () => {
     const y = window.scrollY;
+    scrolling = true;
+    window.clearTimeout(settleTimer);
+    settleTimer = window.setTimeout(() => {
+      scrolling = false;
+      arm();
+    }, RAIL_SETTLE_MS);
     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);
+      const armedTop = Number.parseFloat(rail.style.top);
+      spacer = direction === "down" ? Math.min(Math.max(spacer, lastY + (Number.isFinite(armedTop) ? armedTop : g.viewportBottom - g.height) - g.trackTop), g.maxOffset) : Math.max(Math.min(spacer, lastY + g.top - g.trackTop), 0);
       direction = next;
       arm(g);
     }
@@ -586,6 +604,7 @@ function followRail(rail, header) {
   arm();
   return () => {
     observer.disconnect();
+    window.clearTimeout(settleTimer);
     window.removeEventListener("scroll", onScroll);
     window.removeEventListener("resize", relayout);
     media.removeEventListener("change", relayout);
@@ -615,13 +634,13 @@ 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(() => {
+function useRailFollow(ref, ready = true, pageKey) {
+  useLayoutEffect(() => {
     const element = ref.current;
     const header = element?.closest(".app")?.querySelector(".top");
-    if (!element || !header) return;
+    if (!ready || !element || !header) return;
     return followRail(element, header);
-  }, [ready, ref]);
+  }, [ready, ref, pageKey]);
 }
 function scanPage(root, pageKey) {
   const used = /* @__PURE__ */ new Set();
@@ -677,11 +696,14 @@ function scanPage(root, pageKey) {
 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(";")}`;
 var prefersReducedMotion = () => window.matchMedia("(prefers-reduced-motion: reduce)").matches;
 function scrollToElement(element) {
+  const hash = window.location.hash;
   element.scrollIntoView({ behavior: prefersReducedMotion() ? "auto" : "smooth", block: "start" });
   let ticks = SETTLE_TICKS;
   let lastY = window.scrollY;
+  let timer;
+  let cancelled = false;
   const settle = () => {
-    if (!element.isConnected || ticks === 0) return;
+    if (cancelled || window.location.hash !== hash || !element.isConnected || ticks === 0) return;
     ticks -= 1;
     const moving = window.scrollY !== lastY;
     lastY = window.scrollY;
@@ -689,9 +711,13 @@ function scrollToElement(element) {
       element.scrollIntoView({ behavior: "auto", block: "start" });
       lastY = window.scrollY;
     }
-    window.setTimeout(settle, SETTLE_TICK_MS);
+    timer = window.setTimeout(settle, SETTLE_TICK_MS);
+  };
+  timer = window.setTimeout(settle, SETTLE_TICK_MS);
+  return () => {
+    cancelled = true;
+    window.clearTimeout(timer);
   };
-  window.setTimeout(settle, SETTLE_TICK_MS);
 }
 function useActiveIds(scan) {
   const [active, setActive] = useState3({ section: null, story: null });
@@ -721,6 +747,12 @@ function PageRail({ pageKey }) {
   pageKeyRef.current = pageKey;
   const [target, setTarget] = useState3(() => storyFromHash(window.location.hash));
   const flashed = useRef2(null);
+  const cancelScroll = useRef2(null);
+  const go = useCallback((element) => {
+    cancelScroll.current?.();
+    cancelScroll.current = scrollToElement(element);
+  }, []);
+  useEffect3(() => () => cancelScroll.current?.(), []);
   useEffect3(() => {
     const main = document.querySelector(".main");
     if (!main) return;
@@ -752,17 +784,16 @@ function PageRail({ pageKey }) {
     if (!target || !scan || scan.pageKey !== pageKey) return;
     const match = scan.frames.find((frame) => frame.story === target) ?? scan.frames.find((frame) => frame.story.toLowerCase() === target.toLowerCase()) ?? scan.frames.find((frame) => frame.name === target) ?? scan.frames.find((frame) => frame.name.toLowerCase() === target.toLowerCase());
     if (!match) return;
-    scrollToElement(match.element);
+    go(match.element);
     flashed.current?.classList.remove("toc-flash");
     match.element.classList.add("toc-flash");
     flashed.current = match.element;
     window.setTimeout(() => match.element.classList.remove("toc-flash"), FLASH_MS);
     setTarget(null);
-  }, [target, scan, pageKey]);
+  }, [target, scan, pageKey, go]);
   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__ */ 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" }),
@@ -772,17 +803,19 @@ function PageRail({ pageKey }) {
         {
           type: "button",
           className: "toc-link",
+          title: section.title,
           "aria-current": active.section === section.id ? "location" : void 0,
           onClick: () => go(section.heading),
           children: section.title
         }
       ),
-      section.subs.length > 0 ? /* @__PURE__ */ jsx5("ul", { children: section.subs.map((sub) => /* @__PURE__ */ jsx5("li", { children: /* @__PURE__ */ jsx5("button", { type: "button", className: "toc-link toc-sub", onClick: () => go(sub.element), children: sub.title }) }, sub.id)) }) : null,
+      section.subs.length > 0 ? /* @__PURE__ */ jsx5("ul", { children: section.subs.map((sub) => /* @__PURE__ */ jsx5("li", { children: /* @__PURE__ */ jsx5("button", { type: "button", className: "toc-link toc-sub", title: sub.title, onClick: () => go(sub.element), children: sub.title }) }, sub.id)) }) : null,
       section.stories.length > 0 ? /* @__PURE__ */ jsx5("ul", { children: section.stories.map((story) => /* @__PURE__ */ jsx5("li", { children: /* @__PURE__ */ jsx5(
         "button",
         {
           type: "button",
           className: "toc-link toc-story",
+          title: story.name,
           "aria-current": active.story === story.id ? "location" : void 0,
           onClick: () => go(story.element),
           children: story.name
@@ -1885,9 +1918,20 @@ function DocsApp() {
   const [mode, setMode] = useState9(theme.values?.[0] ?? "dark");
   const [navOpen, setNavOpen] = useState9(false);
   const navRef = useRef5(null);
-  useRailFollow(navRef);
+  const pageKey = route.kind === "component" ? `components/${route.slug}` : route.kind;
   const headerRef = useRef5(null);
   const mainRef = useRef5(null);
+  const renderedPage = useRef5(pageKey);
+  useLayoutEffect2(() => {
+    if (renderedPage.current !== pageKey) {
+      const reset = () => window.scrollTo({ top: 0, left: 0, behavior: "instant" });
+      reset();
+      const frame = requestAnimationFrame(reset);
+      renderedPage.current = pageKey;
+      return () => cancelAnimationFrame(frame);
+    }
+  }, [pageKey]);
+  useRailFollow(navRef, true, pageKey);
   useEffect8(() => {
     const header = headerRef.current;
     if (!header) return;
@@ -1907,7 +1951,6 @@ function DocsApp() {
     const onHash = () => {
       setRoute(parseRoute(window.location.hash));
       setNavOpen(false);
-      window.scrollTo(0, 0);
       mainRef.current?.focus({ preventScroll: true });
     };
     window.addEventListener("hashchange", onHash);
@@ -2019,8 +2062,8 @@ function DocsApp() {
         )) }, `${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
+    /* @__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) }, pageKey) : 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 }, pageKey) : null
   ] });
 }
 

package/dist/styles.css

@@ -194,7 +194,7 @@ body {
   .rail-track::before {
     content: '';
     display: block;
-    height: var(--sd-rail-offset, 0px);
+    height: calc(var(--sd-rail-start, 0px) + var(--sd-rail-offset, 0px));
   }
 }
 .nav {

package/dist/toc.d.ts

@@ -6,7 +6,7 @@ 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;
-export declare function useRailFollow(ref: RefObject<HTMLElement | null>, ready?: boolean): void;
+export declare function useRailFollow(ref: RefObject<HTMLElement | null>, ready?: boolean, pageKey?: string): void;
 /** The "On this page" rail and the `?story=` deep-link landing. */
 export declare function PageRail({ pageKey }: {
     pageKey: string;

package/package.json

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