@poveste/shared 0.20.0 → 0.21.1

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/docgen.d.ts

@@ -23,6 +23,15 @@ 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 {
@@ -32,6 +41,10 @@ export interface DocEvent {
     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[];
@@ -42,6 +55,10 @@ export interface ComponentDoc {
  * 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>;
@@ -64,7 +81,16 @@ export interface DocgenExtractorModule {
     createExtractor: (context: DocgenExtractorContext) => DocgenExtractor | Promise<DocgenExtractor>;
 }
 export interface PluginDocgen {
-    /** Whether a resolved file is a component this plugin documents. */
+    /**
+     * 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
@@ -73,6 +99,20 @@ export interface PluginDocgen {
     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,
@@ -90,3 +130,11 @@ export interface AutoDocsOptions {
     /** 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/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,6 +73,7 @@ export interface Story {
     icon?: string;
     iconColor?: string;
     docsOnly?: boolean;
+    autoDocs?: boolean | AutoDocsSection[] | undefined;
     file?: StoryFile;
     lastSelectedVariant?: Variant;
     /** The story's own slots. Any of the three can be absent: a story may define none. */
@@ -174,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.20.0",
+  "version": "0.21.1",
   "description": "Shared utilities for Poveste",
   "author": {
     "name": "Sorin Gitlan",
@@ -39,7 +39,7 @@
     "vite": "^8.0.0"
   },
   "dependencies": {
-    "@poveste/vendors": "^0.20.0",
+    "@poveste/vendors": "^0.21.1",
     "@types/fs-extra": "^11.0.4",
     "chokidar": "^5.0.0",
     "markdown-it": "^15.0.3",
@@ -51,7 +51,7 @@
     "@types/node": "^26.6.5",
     "typescript": "6.0.3",
     "vite": "^8.3.4",
-    "vitest": "^5.0.4",
+    "vitest": "^5.0.5",
     "vue-router": "^5.4.0"
   },
   "scripts": {