@jfrader/storybook-docs 0.4.3 → 0.4.4

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

@@ -6,7 +6,7 @@ import { site as site3, themeCss, theme as theme2 } from "virtual:storybook-docs
 
 // 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 { 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
@@ -531,6 +531,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 +575,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 +606,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 +700,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 +844,7 @@ function ComponentDemo({
   children
 }) {
   const [codeOpen, setCodeOpen] = useState4(false);
+  const controlsLabelId = useId();
   const canvasRef = useRef3(null);
   const [scrollable, setScrollable] = useState4(false);
   useEffect4(() => {
@@ -844,8 +890,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
       ] }),
@@ -1756,6 +1802,8 @@ function DocsApp() {
   const [route, setRoute] = useState8(() => parseRoute(window.location.hash));
   const [mode, setMode] = useState8(theme.values?.[0] ?? "dark");
   const [navOpen, setNavOpen] = useState8(false);
+  const navRef = useRef5(null);
+  useRailFollow(navRef);
   const headerRef = useRef5(null);
   const mainRef = useRef5(null);
   useEffect7(() => {
@@ -1845,7 +1893,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 +1937,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/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/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.4.4",
   "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"
+  }
+}