@poveste/shared 0.19.1 → 0.20.0

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,92 @@
+/**
+ * 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;
+    tags: DocTag[];
+}
+export interface DocEvent {
+    name: string;
+    description?: string;
+    type?: string;
+    tags: DocTag[];
+}
+export interface ComponentDoc {
+    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 {
+    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 {
+    /** Whether a resolved file is a component 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;
+    /**
+     * 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[];
+}

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

@@ -67,7 +67,12 @@ export interface Story {
     docsOnly?: boolean;
     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 +83,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;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@poveste/shared",
   "type": "module",
-  "version": "0.19.1",
+  "version": "0.20.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.20.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.4",
+    "vue-router": "^5.4.0"
   },
   "scripts": {
     "build": "rimraf dist && tsc",