@poveste/shared 0.19.1 → 0.21.0

package/dist/index.d.ts

@@ -5,3 +5,4 @@ export * from './story-error.js';
 export * from './story.js';
 export * from './type-utils.js';
 export * from './types/index.js';
+export * from './virtual.js';

package/dist/index.js

@@ -5,3 +5,4 @@ export * from './story-error.js';
 export * from './story.js';
 export * from './type-utils.js';
 export * from './types/index.js';
+export * from './virtual.js';

package/dist/story.js

@@ -7,6 +7,8 @@ export const omitInheritStoryProps = [
     'file',
     'slots',
     'lastSelectedVariant',
+    // The Docs tab belongs to the story, not to a variant (#1398).
+    'autoDocs',
 ];
 /**
  * Auto-props bookkeeping, which is not story state.

package/dist/types/config.d.ts

@@ -1,6 +1,7 @@
 import type { MarkdownIt } from 'markdown-it';
 import type { UseHeadInput } from 'unhead/types';
 import type { UserConfig as ViteConfig, ConfigEnv as ViteConfigEnv } from 'vite';
+import type { AutoDocsOptions } from './docgen.js';
 import type { Plugin } from './plugin.js';
 import type { ServerTreeFile, StoryProps } from './story.js';
 export interface SupportMatchPattern {
@@ -89,6 +90,13 @@ export interface PovesteConfig {
      * in iframes. Set to false to restore pre-1.0 behavior. See guide/css.md.
      */
     isolateStyles?: boolean;
+    /**
+     * Auto-docs: a props, slots and events table read from each component's types.
+     * Extraction starts the first time a reader opens a story's docs, in a worker,
+     * and only for the components that story imports; it holds a type checker while
+     * it runs. Set to false to turn it off. Default: on.
+     */
+    autoDocs?: boolean | AutoDocsOptions;
     /**
      * CSS files loaded into the main app (not into stories). Wrapped in
      * @layer poveste-user-globals — lower priority than chrome.

package/dist/types/docgen.d.ts

@@ -0,0 +1,140 @@
+/**
+ * Auto-docs: what a framework extractor reads off a component, and the contract
+ * between it and the shell that decides when it runs (#159, #1159).
+ */
+export interface DocTag {
+    name: string;
+    text?: string;
+}
+export interface DocProp {
+    name: string;
+    description?: string;
+    type: string;
+    required: boolean;
+    /** The default the code applies, which wins over the tag when both exist. */
+    default?: string;
+    /** The default a `@default` or `@defaultValue` tag states. */
+    defaultTag?: string;
+    /** Both defaults exist and say different things: the code's is shown, and this flags it. */
+    defaultConflict?: boolean;
+    tags: DocTag[];
+}
+export interface DocSlot {
+    name: string;
+    description?: string;
+    type?: string;
+    /**
+     * What it passes its content, `open` in `<template #default="{ open }">`, one row each,
+     * so the JSDoc on each shows (#1436).
+     */
+    props?: {
+        name: string;
+        type: string;
+        description?: string;
+    }[];
+    tags: DocTag[];
+}
+export interface DocEvent {
+    name: string;
+    description?: string;
+    type?: string;
+    tags: DocTag[];
+}
+export interface ComponentDoc {
+    /** The component's own name, when the file it was read from is not named after it. */
+    name?: string;
+    /** Its type parameters as the source declares them, `T extends string = string`, when it has any. */
+    generic?: string;
+    props: DocProp[];
+    slots: DocSlot[];
+    events: DocEvent[];
+}
+/**
+ * One framework's extractor, created inside the docgen worker the first time a
+ * component of its kind is asked for. It may hold a type checker, which is the
+ * memory this whole design is about: `dispose` must let it go.
+ */
+export interface DocgenExtractor {
+    /**
+     * A failure is thrown. When the file is not named after the component, as with a
+     * JSX story, an error carrying a `component` string names it for the reader.
+     */
+    extract: (file: string) => ComponentDoc | undefined | Promise<ComponentDoc | undefined>;
+    /** A file changed on disk. Called for any file, not only components. */
+    update?: (file: string) => void | Promise<void>;
+    /**
+     * The files its program read, outside `node_modules`. The dev server watches
+     * them: a types file the browser never loads, or one outside the book's root,
+     * is otherwise never seen to change (#1190).
+     */
+    sources?: () => string[] | Promise<string[]>;
+    dispose: () => void | Promise<void>;
+}
+export interface DocgenExtractorContext {
+    /** The book's root. */
+    root: string;
+    /** Whatever the plugin passed as `docgen.options`. */
+    options: unknown;
+}
+/** The shape of the module a plugin names in `docgen.module`. */
+export interface DocgenExtractorModule {
+    createExtractor: (context: DocgenExtractorContext) => DocgenExtractor | Promise<DocgenExtractor>;
+}
+export interface PluginDocgen {
+    /**
+     * What a request hands the extractor. `imports`: each file the story's module
+     * imports that `match` accepts, as a Vue story imports its `.vue` files.
+     * `story`: the story file itself, for a story collection gave to this plugin's
+     * `supportPlugin` and that `match` accepts, in a format whose story names its
+     * component in a `component` field the extractor resolves. `autoDocs.exclude`
+     * reaches the extractor in its options, since only it knows the component's file.
+     */
+    scope?: 'imports' | 'story';
+    /** Whether a resolved file is one this plugin documents. */
+    match: (file: string) => boolean;
+    /**
+     * An absolute path or `file:` URL to a module exporting `createExtractor`. It is
+     * imported in a worker thread, so it travels as a specifier rather than a function.
+     */
+    module: string;
+    /** Passed to `createExtractor`; it has to survive a structured clone. */
+    options?: unknown;
+    /**
+     * Where the extractor loads `typescript` from, when it reads types with it: a file
+     * whose `require` it uses, or `'book'` for the book's own root. In a book where that
+     * finds no TypeScript, or one newer than 6, auto-docs is off for this plugin with one
+     * log line (#1382, #1401). A value rather than a function, so a plugin whose entry
+     * also runs in the browser can declare it.
+     */
+    typescript?: 'book' | (string & {});
+    /**
+     * Type packages the book must have for the extractor to read its framework's types,
+     * such as `@types/react`. Missing one, auto-docs is off for this plugin with one log
+     * line naming it, rather than an error under every component it would read as `any`.
+     */
+    types?: string[];
+    /**
+     * Why this plugin cannot document the book at `root`, or nothing when it can.
+     * With a reason, auto-docs is off for this plugin and the reason is logged once,
+     * in place of an error under every component (#1382).
+     */
+    unavailable?: (root: string) => string | undefined;
+}
+/** `autoDocs` in the config, when it is more than on or off. */
+export interface AutoDocsOptions {
+    /**
+     * Packages whose props are documented although they are declared under
+     * `node_modules`: a design system a library builds on, such as `reka-ui`.
+     */
+    allow?: string[];
+    /** Component files to leave out, matched as substrings of the path. */
+    exclude?: string[];
+}
+/**
+ * The field a story format uses to name the component it documents, shared by
+ * the JSX formats so Solid and React spell it the same way (#1110, #1161).
+ */
+export interface StoryComponentOptions<C> {
+    /** The component this story documents. Auto-docs reads its props from its type. */
+    component?: C;
+}

package/dist/types/docgen.js

@@ -0,0 +1,5 @@
+/**
+ * Auto-docs: what a framework extractor reads off a component, and the contract
+ * between it and the shell that decides when it runs (#159, #1159).
+ */
+export {};

package/dist/types/index.d.ts

@@ -1,5 +1,6 @@
 export * from './command.js';
 export * from './config.js';
+export * from './docgen.js';
 export * from './plugin.js';
 export * from './prompt.js';
 export * from './story.js';

package/dist/types/index.js

@@ -1,5 +1,6 @@
 export * from './command.js';
 export * from './config.js';
+export * from './docgen.js';
 export * from './plugin.js';
 export * from './prompt.js';
 export * from './story.js';

package/dist/types/plugin.d.ts

@@ -6,6 +6,7 @@ import type { InlineConfig as ViteInlineConfig, Plugin as VitePlugin } from 'vit
 import type { Awaitable } from '../type-utils.js';
 import type { PluginCommand } from './command.js';
 import type { ConfigMode, PovesteConfig } from './config.js';
+import type { PluginDocgen } from './docgen.js';
 import type { ServerStory, ServerStoryFile, ServerVariant, Variant } from './story.js';
 /**
  * A framework's collection strategy: how a story file written for that framework
@@ -233,6 +234,11 @@ export interface Plugin {
      * Handle a custom event from the client in development mode.
      */
     onDevEvent?: (api: PluginApiDevEvent) => Awaitable<any>;
+    /**
+     * Auto-docs for this framework's components: which files it documents, and the
+     * module that extracts them, run lazily in a worker (#1159).
+     */
+    docgen?: PluginDocgen;
     /**
      * Use this hook to manipulate Vite plugins before they are passed to Vite.
      */

package/dist/types/story.d.ts

@@ -41,10 +41,18 @@ export interface InheritedProps {
 }
 export interface VariantProps extends CommonProps, InheritedProps {
 }
+/** A section of the auto-docs table on a story's Docs tab. */
+export type AutoDocsSection = 'props' | 'slots' | 'events';
 export interface StoryProps extends CommonProps, InheritedProps {
     group?: string;
     layout?: StoryLayout;
     docsOnly?: boolean;
+    /**
+     * The auto-docs table on this story's Docs tab: `false` for none, never extracting
+     * the story's components; an array for only those sections. Left out, the story
+     * follows the book's `autoDocs`, which a story cannot turn on (#1398).
+     */
+    autoDocs?: boolean | AutoDocsSection[];
 }
 export interface CommonMeta {
 }
@@ -65,9 +73,15 @@ export interface Story {
     icon?: string;
     iconColor?: string;
     docsOnly?: boolean;
+    autoDocs?: boolean | AutoDocsSection[] | undefined;
     file?: StoryFile;
     lastSelectedVariant?: Variant;
-    slots?: () => any;
+    /** The story's own slots. Any of the three can be absent: a story may define none. */
+    slots?: () => {
+        default?: any;
+        controls?: any;
+        source?: any;
+    };
     meta?: StoryMeta;
 }
 export interface VariantMeta extends CommonMeta {
@@ -78,10 +92,11 @@ export interface Variant {
     icon?: string | undefined;
     iconColor?: string | undefined;
     setupApp?: ((payload: any) => unknown) | undefined;
+    /** The variant's own slots. Any of the three can be absent: a variant may define none. */
     slots?: (() => {
-        default: any;
-        controls: any;
-        source: any;
+        default?: any;
+        controls?: any;
+        source?: any;
     }) | undefined;
     state: any;
     source?: string | undefined;
@@ -168,6 +183,7 @@ export interface ServerStory {
     icon?: string | undefined;
     iconColor?: string | undefined;
     docsOnly?: boolean | undefined;
+    autoDocs?: boolean | AutoDocsSection[] | undefined;
     docsText?: string | undefined;
     meta?: StoryMeta | undefined;
 }

package/dist/virtual.d.ts

@@ -0,0 +1,37 @@
+import type { PovesteConfig } from './types/config.js';
+/**
+ * The virtual modules Poveste's client imports, by the ids core serves them
+ * under. A story test's Vite plugin serves the same ones, from this list.
+ */
+export declare const VIRTUAL_IDS: {
+    readonly setup: "virtual:$poveste-setup";
+    readonly generatedGlobalSetup: "virtual:$poveste-generated-global-setup";
+    readonly config: "virtual:$poveste-config";
+    readonly markdownFiles: "virtual:$poveste-markdown-files";
+    readonly componentDocs: "virtual:$poveste-component-docs";
+    readonly supportPluginsClient: "virtual:$poveste-support-plugins-client";
+};
+/**
+ * The config as the browser gets it: the fields `@poveste/app` reads, and no
+ * others. The rest is build-side, and holds paths on the machine that built the
+ * book (`outDir`, each plugin's modules, the logo files), which a built book
+ * published in full (#1383). The logos reach the browser as `logos`, below.
+ */
+export declare function clientConfig(config: Partial<PovesteConfig>): {
+    theme: {
+        title: string | undefined;
+        logoHref: string | undefined;
+        defaultColorScheme: "light" | "dark" | "auto" | undefined;
+        hideColorSchemeSwitch: boolean | undefined;
+        storeColorScheme: boolean | undefined;
+        darkClass: string | undefined;
+    };
+    routerMode: "history" | "hash" | undefined;
+    autoApplyContrastColor: boolean | undefined;
+    responsivePresets: import("./index.js").ResponsivePreset[] | undefined;
+    backgroundPresets: import("./index.js").BackgroundPreset[] | undefined;
+    defaultBackgroundColor: string | undefined;
+    preview: import("./index.js").PreviewConfig | undefined;
+    isolateStyles: boolean | undefined;
+    sandboxDarkClass: string | undefined;
+};

package/dist/virtual.js

@@ -0,0 +1,41 @@
+/**
+ * The virtual modules Poveste's client imports, by the ids core serves them
+ * under. A story test's Vite plugin serves the same ones, from this list.
+ */
+export const VIRTUAL_IDS = {
+    setup: 'virtual:$poveste-setup',
+    generatedGlobalSetup: 'virtual:$poveste-generated-global-setup',
+    config: 'virtual:$poveste-config',
+    markdownFiles: 'virtual:$poveste-markdown-files',
+    componentDocs: 'virtual:$poveste-component-docs',
+    supportPluginsClient: 'virtual:$poveste-support-plugins-client',
+};
+/**
+ * The config as the browser gets it: the fields `@poveste/app` reads, and no
+ * others. The rest is build-side, and holds paths on the machine that built the
+ * book (`outDir`, each plugin's modules, the logo files), which a built book
+ * published in full (#1383). The logos reach the browser as `logos`, below.
+ */
+export function clientConfig(config) {
+    const theme = config.theme ?? {};
+    return {
+        theme: {
+            title: theme.title,
+            logoHref: theme.logoHref,
+            defaultColorScheme: theme.defaultColorScheme,
+            hideColorSchemeSwitch: theme.hideColorSchemeSwitch,
+            storeColorScheme: theme.storeColorScheme,
+            darkClass: theme.darkClass,
+        },
+        routerMode: config.routerMode,
+        autoApplyContrastColor: config.autoApplyContrastColor,
+        responsivePresets: config.responsivePresets,
+        backgroundPresets: config.backgroundPresets,
+        // eslint-disable-next-line ts/no-deprecated -- the app still reads it as a fallback
+        defaultBackgroundColor: config.defaultBackgroundColor,
+        preview: config.preview,
+        isolateStyles: config.isolateStyles,
+        // eslint-disable-next-line ts/no-deprecated -- the app still reads it as a fallback
+        sandboxDarkClass: config.sandboxDarkClass,
+    };
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@poveste/shared",
   "type": "module",
-  "version": "0.19.1",
+  "version": "0.21.0",
   "description": "Shared utilities for Poveste",
   "author": {
     "name": "Sorin Gitlan",
@@ -39,20 +39,20 @@
     "vite": "^8.0.0"
   },
   "dependencies": {
-    "@poveste/vendors": "^0.19.1",
+    "@poveste/vendors": "^0.21.0",
     "@types/fs-extra": "^11.0.4",
     "chokidar": "^5.0.0",
-    "markdown-it": "^15.0.2",
+    "markdown-it": "^15.0.3",
     "pathe": "^2.0.3",
     "picocolors": "^1.1.1",
-    "unhead": "^3.4.1"
+    "unhead": "^3.4.3"
   },
   "devDependencies": {
-    "@types/node": "^26.6.3",
+    "@types/node": "^26.6.5",
     "typescript": "6.0.3",
-    "vite": "^8.3.1",
-    "vitest": "^5.0.2",
-    "vue-router": "^5.3.1"
+    "vite": "^8.3.4",
+    "vitest": "^5.0.5",
+    "vue-router": "^5.4.0"
   },
   "scripts": {
     "build": "rimraf dist && tsc",