@jfrader/storybook-docs 0.0.0-stage → 0.4.4

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Fran
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,139 @@
-# Temporary Holding Version
+# @jfrader/storybook-docs
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A documentation front for **any design system that has Storybook**. Point it at a set of
+story files; it generates the navigation, renders every story in place, and builds API
+tables from the stories' own `argTypes`. There is no second component list anywhere.
+
+```
+example/            # a consumer you can copy
+  docs.config.mjs   # ← the only place the design system is described
+  vite.config.ts    # registers the plugin
+  index.html
+  src/main.tsx      # six lines
+```
+
+## What it does with your stories
+
+| Piece | Source of truth |
+| --- | --- |
+| Sidebar, groups, slugs | each story module's `title` (scoped to the `meta` object, so fixtures never leak in) |
+| Search (⌘K) | the catalog, scored over component, group and story names |
+| Examples (all of them, inline, in sections) | the story module itself — meta `component` + merged `args`, or the story's `render` |
+| Sections (Overview / Variants & sizes / States / Interaction & keyboard / Content & layout / Environments / Edge cases) | the story names, bucketed by convention |
+| Props tables (one per component and part, with native-element notes) | the component sources — `react-docgen-typescript` for components, the TypeScript compiler API for exported `*Props` types (where compound parts live) |
+| Usage snippet | the default story's own arguments |
+| Per-example Code disclosures | the story's merged args (hidden when the story uses a custom render, so a snippet never lies) |
+| Authored guidance per component | Markdown files in the configured guidance directories, with `> Do —` / `> Don't —` blockquotes rendered as do/don't cards — the part stories cannot generate |
+| Foundations: Color, Typography, Spacing & shape, Elevation & motion | your token module (optional) |
+| Docs chrome theme | your CSS custom properties (optional) |
+
+Known limits: compound parts declared as property assignments (`Dialog.Content = …`) are picked up
+through their exported `*Props` types; parts with no exported props type stay invisible. Stories that
+need project-level Storybook decorators fail soft (an error boundary per story frame). Play functions,
+controls and a11y checks stay in Storybook — this front is for reading and browsing.
+
+## What it looks like
+
+| | |
+| --- | --- |
+| ![Overview: browse-by-area directory](docs/images/overview.png) | ![Search with highlighted matches and story-level results](docs/images/search.png) |
+| The overview: stat tiles, then a card per area with counts and links into every component. | ⌘K search: matches highlighted, story hits listed as `Component › Story`. |
+| ![A component page with examples and their controls](docs/images/component.png) | ![Authored guidance with Do and Don't callouts](docs/images/guidance.png) |
+| Every story renders in place, bucketed into sections, with live controls and a Code disclosure per frame. | Authored Markdown becomes typed React blocks: Do/Don't cards, tables, code with language. |
+| ![The releases page and version chip](docs/images/releases.png) | ![Foundations: spacing scale and radii from the token source](docs/images/foundations.png) |
+| Releases: the changelog rendered in place, with the current version read from the package. | Foundations: colour, type, spacing/shape and elevation/motion, all from the token module. |
+
+## The reference consumer
+
+`examples/fixtures/` is a second, synthetic design system (Acme UI) used by the scanner tests and by CI
+as the build gate that needs no credentials — it proves the engine is not shaped around jfrader/ui.
+`examples/jfrader-ui/` is the real one; its `link:` paths resolve against the main clone layout, so a
+git worktree copy needs those symlinks repointed locally (see its `node_modules/@jfrader` entries).
+
+## Development
+
+```bash
+pnpm install
+pnpm test                 # engine unit tests (glob, title extraction, sections, snippets)
+pnpm --dir examples/fixtures install
+pnpm --dir examples/fixtures dev # the synthetic consumer (port 4334)
+```
+
+To check what a running docs site actually renders, point the frame check at it. It visits every
+component page, mounts the lazy frames, and reports stories that fail to render, content painted
+outside its frame, zero-size controls and components that collapsed to nothing — the check that
+caught a component rendering at 0×0 with its own tests green. It needs Playwright, so run it from a
+directory where that resolves (normally your Storybook app):
+
+```bash
+node scripts/check-example-frames.mjs http://localhost:4320 [--json report.json]
+```
+
+It exits non-zero when a component has a real finding, so it can gate CI. Zero-size component roots
+are reported as notes: an empty group or a progress bar at zero is legitimate.
+
+## Use it
+
+```bash
+pnpm add react@^19 react-dom@^19
+pnpm add -D @jfrader/storybook-docs vite @vitejs/plugin-react @types/node @types/react @types/react-dom
+```
+
+Use Node 22.12 or newer (maintainer tests need Node 22.18 or newer). React 19 and Vite 6, 7 or 8
+are peers supplied by the consumer. Published packages and linked checkouts both expose built
+JavaScript and types (`dist/`); run `pnpm build:package` after editing a linked engine checkout.
+The browser entry imports its CSS automatically; no stylesheet subpath or manual `virtual.d.ts`
+reference is needed. Importing the root entry also loads the virtual-module declarations.
+
+Maintainers can run `pnpm smoke:package` to pack, install and typecheck/build an isolated minimal
+consumer without links or private dependencies. See [release instructions](docs/RELEASING.md).
+
+The consumer contract is four files:
+
+```js
+// docs.config.mjs
+export default {
+  site: { title: 'acme/ui', mark: 'a', links: [{ label: 'GitHub', href: '…' }] },
+  stories: { from: '@acme/ui', pattern: 'src/components/*/*.stories.tsx' },
+  groups: { rename: { Data: 'Data display' }, order: ['Foundations', 'Inputs', 'Components'] },
+  theme: {
+    attribute: 'data-theme',
+    values: ['dark', 'light'],
+    vars: { bg: 'var(--acme-bg)', text: 'var(--acme-text)', accent: 'var(--acme-accent)' },
+  },
+  tokens: { varsModule: '@acme/tokens/vars', varsExport: 'vars', css: ['@acme/tokens/tokens.css'] },
+};
+```
+
+```ts
+// vite.config.ts
+import react from '@vitejs/plugin-react';
+import { defineConfig } from 'vite';
+import { storybookDocs } from '@jfrader/storybook-docs/vite';
+import config from './docs.config.mjs';
+
+export default defineConfig({ plugins: [storybookDocs({ config }), react()] });
+```
+
+```html
+<!-- index.html -->
+<div id="root"></div><script type="module" src="/src/main.tsx"></script>
+```
+
+```ts
+// src/main.tsx
+import { start } from '@jfrader/storybook-docs';
+start();
+```
+
+## Notes and limits
+
+- The plugin scans the resolved package directory and imports story files by absolute
+  path, so it works with workspace links and does not require the design system to publish
+  its stories or expose extra package exports.
+- If the design system is consumed from a published tarball that only ships built files,
+  point `stories.from` at a checkout (or publish the story sources) — the tool reads
+  source modules by design, because that is what Storybook renders.
+- Mounting under a sub-path: set `window.__STORYBOOK_DOCS_BASE__ = '/docs'` before `start()`.
+- Not included yet: search, versioned docs, prose authoring, adoption analytics. All of
+  them are free/OSS additions once the shape earns them.

package/dist/app.d.ts

@@ -0,0 +1 @@
+export declare function DocsApp(): import("react").JSX.Element;

package/dist/base.d.ts

@@ -0,0 +1,3 @@
+/** Consumers mount under a sub-path by exporting `window.__STORYBOOK_DOCS_BASE__` (e.g. '/docs'). */
+export declare const STORYBOOK_DOCS_BASE: string;
+export declare const hrefFor: (path: string) => string;

package/dist/build/catalog.d.ts

@@ -0,0 +1,20 @@
+import { readStoryFile } from '../scan.ts';
+import type { CatalogEntry, StorybookDocsConfig } from '../config.js';
+export interface StoryFile {
+    file: string;
+    facts: NonNullable<ReturnType<typeof readStoryFile>>;
+}
+export interface Catalog {
+    entries: CatalogEntry[];
+    groups: string[];
+    stats: {
+        components: number;
+        stories: number;
+        groups: number;
+    };
+    files: Map<string, string>;
+}
+export declare function resolveStoryRoot(from: string, root: string): string;
+export declare function scanStories(config: StorybookDocsConfig['stories'], root: string): StoryFile[];
+export declare function buildCatalog(stories: StoryFile[], groupsConfig: StorybookDocsConfig['groups']): Catalog;
+export declare function catalogCode(catalog: Catalog): string;

package/dist/build/code.d.ts

@@ -0,0 +1,2 @@
+export declare function resolveCodeModule(module: string | undefined, root: string): string | undefined;
+export declare function codeModuleCode(resolved: string | undefined): string;

package/dist/build/global-styles.d.ts

@@ -0,0 +1 @@
+export declare function globalStylesCode(engineStyles: string, css?: string[]): string;

package/dist/build/guidance.d.ts

@@ -0,0 +1,4 @@
+import type { StorybookDocsConfig } from '../config.js';
+export declare function indexGuidance(guidance: StorybookDocsConfig['guidance'], root: string): Map<string, string>;
+export declare function guidanceIndexCode(slugs: Iterable<string>): string;
+export declare function guidanceCode(markdown: string): string;

package/dist/build/module-ids.d.ts

@@ -0,0 +1,2 @@
+export declare const VIRTUAL_PREFIX = "virtual:storybook-docs/";
+export declare const FILE_PREFIX = "storybook-docs-file:";

package/dist/build/props.d.ts

@@ -0,0 +1,10 @@
+import type { ComponentPropsDoc, PropDoc } from '../prop-docs.js';
+export declare function toPropDoc(prop: unknown): PropDoc;
+export declare function createPropsCollector(): {
+    collect: (storyFile: string | undefined, entryName: string, slug: string) => ComponentPropsDoc[];
+    setBuildMode(value: boolean): void;
+    clearPrograms(): void;
+};
+export declare function mergePropsTables(tables: ComponentPropsDoc[]): ComponentPropsDoc[];
+export declare function propsCode(components: ComponentPropsDoc[]): string;
+export declare function propsIndexCode(slugs: Iterable<string>): string;

package/dist/build/releases.d.ts

@@ -0,0 +1,7 @@
+import type { StorybookDocsConfig } from '../config.js';
+export interface Releases {
+    version: string | null;
+    changelog: string | null;
+}
+export declare function readReleases(config: StorybookDocsConfig, root: string): Releases;
+export declare function releasesCode(releases: Releases): string;

package/dist/build/site.d.ts

@@ -0,0 +1,2 @@
+import { type StorybookDocsConfig } from '../config.ts';
+export declare function siteCode(config: StorybookDocsConfig): string;

package/dist/build/storybook-test.d.ts

@@ -0,0 +1,2 @@
+/** A permissive stand-in for `storybook/test`: play functions never run in the docs front. */
+export declare const STORYBOOK_TEST_STUB = "\nconst chainable = (impl) => {\n  const callable = (...args) => (typeof impl === 'function' ? impl(...args) : undefined);\n  const chain = () => callable;\n  for (const name of [\n    'mockName', 'mockImplementation', 'mockImplementationOnce', 'mockResolvedValue',\n    'mockResolvedValueOnce', 'mockRejectedValue', 'mockReturnValue', 'mockReturnThis',\n    'mockReset', 'mockClear', 'mockRestore',\n  ]) callable[name] = chain;\n  callable.mock = { calls: [], results: [] };\n  return callable;\n};\nexport const fn = (impl) => chainable(impl);\nexport const spyOn = () => chainable();\nexport const mocked = (value) => value;\nexport const expect = () => new Proxy({}, { get: () => () => undefined });\nexport const within = () => new Proxy({}, { get: () => () => ({}) });\nexport const waitFor = (callback) => Promise.resolve(typeof callback === 'function' ? callback() : undefined);\nexport const userEvent = new Proxy({}, { get: () => () => Promise.resolve() });\nexport const fireEvent = () => true;\nexport const cleanup = () => {};\n";

package/dist/build/tokens.d.ts

@@ -0,0 +1,2 @@
+import type { StorybookDocsConfig } from '../config.js';
+export declare function tokensCode(tokens: StorybookDocsConfig['tokens']): string;

package/dist/code.d.ts

@@ -0,0 +1,16 @@
+export type CodeBlockProps = {
+    code: string;
+    /** Language hint for the consumer's highlighter, as an id (`tsx`, `bash`, `json`). */
+    language?: string;
+    /**
+     * What this code is, for a screen reader. Each example on a page needs its own, or every
+     * renderer's landmark carries the same name and the page has duplicate landmarks.
+     */
+    label?: string;
+};
+/**
+ * One code block for every place the docs show code: the page snippet, each example's Code panel
+ * and every fenced block in authored Markdown. Renders the design system's own code block when the
+ * consumer provides one, so code looks exactly as it does in the system it documents.
+ */
+export declare function CodeBlock({ code, language, label }: CodeBlockProps): import("react").JSX.Element;

package/dist/component-demo.d.ts

@@ -0,0 +1,23 @@
+/** @jsxImportSource react */
+import { type ReactNode } from 'react';
+import type { StoryControl } from './controls';
+import './controls.css';
+import './component-demo.css';
+export interface ComponentDemoProps {
+    story: string;
+    storyName: string;
+    authoredStory?: string;
+    skipped: string[];
+    controls: StoryControl[];
+    args: Record<string, unknown>;
+    unavailable: string | null;
+    changed: boolean;
+    onControlChange: (name: string, value: unknown) => void;
+    onReset: () => void;
+    storyLayout: 'centered' | 'fullscreen' | 'padded';
+    snippet: string | null;
+    codeLanguage: string;
+    children: ReactNode;
+}
+export declare function hasHorizontalOverflow({ scrollWidth, clientWidth }: Pick<HTMLElement, 'scrollWidth' | 'clientWidth'>): boolean;
+export declare function ComponentDemo({ story, storyName, authoredStory, skipped, controls, args, unavailable, changed, onControlChange, onReset, storyLayout, snippet, codeLanguage, children, }: ComponentDemoProps): import("react").JSX.Element;

package/dist/config.d.ts

@@ -0,0 +1,98 @@
+/**
+ * The consumer-facing configuration. Nothing in the engine is bound to a specific
+ * design system: every path, package name, theme variable and label comes from here.
+ */
+export interface StorybookDocsConfig {
+    /** Branding and header content. */
+    site: {
+        title: string;
+        mark?: string;
+        tagline?: string;
+        links?: Array<{
+            label: string;
+            href: string;
+        }>;
+        /** Shown as a chip in the header; leave unset to read it from `releases.versionFrom`. */
+        version?: string;
+    };
+    /**
+     * Optional release information. Point `changelog` at the design system's changelog file
+     * (rendered as a Releases page) and `versionFrom` at the package whose `version` field is
+     * the current release.
+     */
+    releases?: {
+        changelog?: string;
+        versionFrom?: string;
+    };
+    /**
+     * Where the story files live. `from` is either a package name (`@acme/ui`) or a path
+     * relative to the config file (`../packages/ui`); `pattern` is a glob relative to that
+     * root — the files it matches are the source of truth for navigation, examples and
+     * API tables.
+     */
+    stories: {
+        from: string;
+        pattern: string;
+    };
+    /** Optional information architecture: explicit group order and renames. */
+    groups?: {
+        order?: string[];
+        rename?: Record<string, string>;
+    };
+    /**
+     * Optional theme bridge. `vars` maps the engine's semantic roles to the design
+     * system's own CSS custom properties, so the docs chrome is themed by the system it
+     * documents (and the toggle works through the system's own theme attribute).
+     */
+    theme?: {
+        attribute?: string;
+        values?: [string, string];
+        vars?: Partial<Record<ThemeRole, string>>;
+    };
+    /** Optional token source that enables the Foundations pages. */
+    tokens?: {
+        varsModule: string;
+        /** Named export in `varsModule` holding the token object. Defaults to `vars`. */
+        varsExport?: string;
+        /** CSS files to load for the consumer's tokens (bare specifiers). */
+        css?: string[];
+    };
+    /**
+     * Optional authored prose. A directory of Markdown files named after component slugs
+     * (`button.md`) plus optionally `index.md` for the overview; each is rendered on that
+     * component's page. This is the part stories cannot generate. Several directories may be
+     * listed; for the same slug, a later directory wins.
+     */
+    guidance?: {
+        dir: string | string[];
+    };
+    /**
+     * Optional code renderer. `module` is a path to a module in the consumer app (relative to the
+     * config) whose default export renders `{ code, language }` — normally the design system's own
+     * code block, wired to its highlighter, so examples look exactly as they do in the system.
+     * Without it, code renders in the engine's plain block.
+     */
+    code?: {
+        module: string;
+    };
+    /** Optional page switches. Foundations pages require `tokens`. */
+    pages?: {
+        overview?: boolean;
+        color?: boolean;
+        typography?: boolean;
+        spacing?: boolean;
+        effects?: boolean;
+        api?: boolean;
+    };
+}
+export declare const THEME_ROLES: readonly ["bg", "surface", "surfaceRaised", "surfaceHover", "border", "borderSubtle", "text", "textMuted", "textSubtle", "accent", "accentText", "accentSoft", "accentContrast", "danger", "dangerText", "success", "focusRing"];
+export type ThemeRole = (typeof THEME_ROLES)[number];
+export interface CatalogEntry {
+    slug: string;
+    name: string;
+    group: string;
+    storybookTitle: string;
+    stories: string[];
+    hasComponent: boolean;
+    load: () => Promise<Record<string, unknown>>;
+}

package/dist/controls.d.ts

@@ -0,0 +1,49 @@
+export { hasHorizontalOverflow } from './component-demo';
+import { type DocsParameters } from './sections';
+interface StoryShape {
+    name?: string;
+    args?: Record<string, unknown>;
+    argTypes?: Record<string, Record<string, unknown>>;
+    render?: unknown;
+    loaders?: unknown;
+    beforeEach?: unknown;
+    parameters?: {
+        docs?: DocsParameters;
+        layout?: string;
+        viewport?: unknown;
+    };
+}
+export interface StoryControl {
+    name: string;
+    type: 'boolean' | 'select' | 'number' | 'text' | 'range' | 'object';
+    options?: unknown[];
+    min?: number;
+    max?: number;
+    step?: number;
+}
+/** Storybook's argTypes can declare a default; the component's own default comes from docgen as a
+ * source snippet, so it is parsed back into a value the controls can show. */
+export declare function parseDefault(value: string): unknown;
+/** Every prop docgen gave a default for. Declared before the component's own default so an
+ *  argType default still wins. */
+/** Docgen reports the default either as a source snippet or as `{ value }`; accept both. */
+export declare function defaultsFromProps(props?: Array<{
+    defaultValue?: string | {
+        value?: string;
+    } | null;
+    name: string;
+}>): Record<string, unknown>;
+export declare function getStoryControls(meta: StoryShape, story: StoryShape, componentDefaults?: Record<string, unknown>): {
+    args: {
+        [x: string]: unknown;
+    };
+    controls: StoryControl[];
+    unavailable: string | null;
+};
+export declare function ControlledStoryFrame({ module, story, componentName, componentDefaults }: {
+    module: Record<string, unknown>;
+    story: string;
+    componentName: string;
+    /** Defaults read from the component source, shown until the reader changes them. */
+    componentDefaults?: Record<string, unknown>;
+}): import("react").JSX.Element;

package/dist/css.d.ts

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

package/dist/guidance-model.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Authored guidance Markdown → a small block model the docs render as React nodes.
+ * Blockquotes that open with a do/don't marker (`✅ **Do** —`, `Don't:`, `⛔`) become
+ * do/don't cards; every other blockquote is a neutral callout. Pure: no DOM, no React.
+ */
+import { type Token } from 'marked';
+export type CalloutTone = 'do' | 'dont' | 'note';
+export type Align = 'left' | 'center' | 'right' | null;
+export type Inline = {
+    kind: 'text';
+    text: string;
+} | {
+    kind: 'strong' | 'em' | 'del';
+    children: Inline[];
+} | {
+    kind: 'code';
+    text: string;
+} | {
+    kind: 'link';
+    href: string;
+    external: boolean;
+    children: Inline[];
+} | {
+    kind: 'image';
+    src: string;
+    alt: string;
+} | {
+    kind: 'br';
+};
+export type Block = {
+    kind: 'heading';
+    depth: number;
+    children: Inline[];
+} | {
+    kind: 'paragraph';
+    children: Inline[];
+}
+/** Tight list-item content: inline nodes without a paragraph around them. */
+ | {
+    kind: 'text';
+    children: Inline[];
+} | {
+    kind: 'list';
+    ordered: boolean;
+    start: number;
+    items: Block[][];
+} | {
+    kind: 'code';
+    lang: string;
+    text: string;
+} | {
+    kind: 'table';
+    align: Align[];
+    header: Inline[][];
+    rows: Inline[][][];
+} | {
+    kind: 'callout';
+    tone: CalloutTone;
+    children: Block[];
+} | {
+    kind: 'rule';
+};
+/**
+ * Reads a blockquote's leading do/don't marker. A symbol is a marker on its own; a bare
+ * word counts only when emphasised (`**Do**`) or followed by a separator or line end, so
+ * "Do you need…" stays a neutral callout. The marker is removed from the returned body.
+ */
+export declare function readCallout(text: string): {
+    tone: CalloutTone;
+    body: string;
+};
+/** Converts `marked.lexer()` tokens into the guidance block model. */
+export declare function toBlocks(tokens: Token[]): Block[];
+export declare function parseGuidance(markdown: string): Block[];

package/dist/guidance.d.ts

@@ -0,0 +1,9 @@
+import './guidance.css';
+/** Renders parsed guidance Markdown — reused by the Releases page for the changelog. */
+export declare function MarkdownView({ markdown, className }: {
+    markdown: string;
+    className?: string;
+}): import("react").JSX.Element;
+export declare function Guidance({ slug }: {
+    slug: string;
+}): import("react").JSX.Element | null;