@poveste/shared 0.13.1 → 0.15.0

package/dist/codegen/serialize-js.js

@@ -42,7 +42,7 @@ function objectToSourceLines(object, seen, indentCount = 0) {
         lines.push('{');
         lines.push(...createLines(1, (lines) => {
             for (const key in object) {
-                const value = object[key];
+                const value = Reflect.get(object, key);
                 let printedKey = key;
                 if (KEY_ESCAPE_REG.test(key)) {
                     printedKey = `'${printedKey}'`;
@@ -66,11 +66,11 @@ function arrayToSourceLines(array, seen, indentCount = 0) {
                 addLinesFromValue(lines, value, '', ',', seen);
             }
         });
-        if (contentLines.length === 0) {
+        const [first] = contentLines;
+        if (!first) {
             lines.push('[]');
         }
         else if (contentLines.length <= MAX_SINGLE_LINE_ARRAY_LENGTH && !contentLines.some(line => line.spaces > 1)) {
-            const [first] = contentLines;
             first.line = contentLines.map(({ line }) => line.substring(0, line.length - 1)).join(', ');
             first.line = `[${first.line}]`;
             first.spaces--;
@@ -120,7 +120,11 @@ function addLinesFromValue(lines, value, before, after, seen) {
     lines.push(before + result + after);
 }
 function wrap(lines, before, after) {
-    lines[0].line = before + lines[0].line;
-    lines[lines.length - 1].line += after;
+    const first = lines[0];
+    const last = lines.at(-1);
+    if (first)
+        first.line = before + first.line;
+    if (last)
+        last.line += after;
     return lines;
 }

package/dist/codegen/util.js

@@ -4,7 +4,9 @@ export function indent(lines, count = 1) {
 export function unindent(code) {
     const lines = code.split('\n');
     let indentLevel = -1;
-    let indentText;
+    // Empty until a non-blank line is seen: `replace(undefined, '')` would look for
+    // the literal text "undefined" (TS6 reports it as used before assignment).
+    let indentText = '';
     const linesToAnalyze = lines.filter(line => line.trim().length > 0);
     for (const line of linesToAnalyze) {
         const match = /^\s*/.exec(line);
@@ -51,7 +53,7 @@ export function createAutoBuildingObject(format, specialKeysHandler, key = '', d
             if (!cache[p]) {
                 const childKey = key ? `${key}.${p.toString()}` : p.toString();
                 const child = createAutoBuildingObject(format, specialKeysHandler, childKey, depth + 1);
-                cache[p] = { key: childKey, ...child };
+                cache[p] = child;
             }
             return cache[p].proxy;
         },

package/dist/setup.d.ts

@@ -2,6 +2,11 @@ export type SetupModule = Record<string, unknown> | undefined;
 /**
  * Reads a setup hook (`setupVanilla`, `setupVue3`, ...) out of a setup module.
  *
+ * `retired` names hooks a plugin has stopped accepting. Nothing passes a
+ * non-empty list today; it exists so that removing a name at 1.0 is a string
+ * moving between two arrays rather than a failure mode designed under release
+ * pressure.
+ *
  * Takes the module as an argument instead of letting callers access it inline:
  * the setup modules are namespace imports of virtual or user-provided files that
  * aren't guaranteed to declare every hook, and a static `namespace.setupVue3`
@@ -9,4 +14,4 @@ export type SetupModule = Record<string, unknown> | undefined;
  * consumer build. Passing the namespace through a call forces it to be
  * materialized, so the lookup happens at runtime where it belongs.
  */
-export declare function getSetupHook<T>(mod: SetupModule, name: string | string[]): T | undefined;
+export declare function getSetupHook<T>(mod: SetupModule, name: string | string[], retired?: string[]): T | undefined;

package/dist/setup.js

@@ -1,6 +1,11 @@
 /**
  * Reads a setup hook (`setupVanilla`, `setupVue3`, ...) out of a setup module.
  *
+ * `retired` names hooks a plugin has stopped accepting. Nothing passes a
+ * non-empty list today; it exists so that removing a name at 1.0 is a string
+ * moving between two arrays rather than a failure mode designed under release
+ * pressure.
+ *
  * Takes the module as an argument instead of letting callers access it inline:
  * the setup modules are namespace imports of virtual or user-provided files that
  * aren't guaranteed to declare every hook, and a static `namespace.setupVue3`
@@ -8,9 +13,28 @@
  * consumer build. Passing the namespace through a call forces it to be
  * materialized, so the lookup happens at runtime where it belongs.
  */
-export function getSetupHook(mod, name) {
+export function getSetupHook(mod, name, retired = []) {
     const names = typeof name === 'string' ? [name] : name;
     const present = names.filter(candidate => typeof mod?.[candidate] === 'function');
+    // Dropping a name is otherwise silent: the export stops being looked up, and a
+    // file that has it does nothing at all — no error, no warning, no hook. The
+    // people most likely to hold one are working from an older recipe, which is
+    // the worst audience for a silent failure.
+    //
+    // `retired` is a parameter rather than a constant so the mechanism can be
+    // exercised with a fixture list while every production list is still empty.
+    // An empty detector that has only ever been seen to pass cannot be told apart
+    // from one that does not work (#157).
+    const dropped = retired.filter(candidate => typeof mod?.[candidate] === 'function');
+    if (dropped.length > 0) {
+        // Two different situations, and the message has to say which: with no live
+        // name exported the setup does not run at all, and with one it does — so
+        // "nothing runs" would send someone to debug a setup that is working.
+        const consequence = present.length > 0
+            ? `${present[0]} runs; the old export is ignored.`
+            : `Rename to ${names[names.length - 1]} — nothing runs until you do.`;
+        console.warn(`[poveste] Setup file exports ${dropped.join(', ')}, which ${dropped.length === 1 ? 'is' : 'are'} no longer read. ${consequence}`);
+    }
     // Earlier names win, so a plugin lists its established hook first and a newer
     // alias after it: an existing setup file keeps the exact behaviour it had.
     // Running both instead would apply the same setup twice, which for Vue means
@@ -19,5 +43,6 @@ export function getSetupHook(mod, name) {
         console.warn(`[poveste] Setup file exports ${present.length} interchangeable setup hooks (${present.join(', ')}). `
             + `Only ${present[0]} runs. Keep one — they are aliases, not separate hooks.`);
     }
-    return present.length > 0 ? mod[present[0]] : undefined;
+    const [first] = present;
+    return first ? mod[first] : undefined;
 }

package/dist/state.d.ts

@@ -1,5 +1,5 @@
 export declare function clone(data: any): any;
-export declare function omit(data: any, keys: string[]): {};
+export declare function omit(data: any, keys: string[]): Record<string, any>;
 /**
  * Structural comparison, deliberately narrow: it recurses into plain objects and
  * arrays and compares everything else by `Object.is`.

package/dist/state.js

@@ -1,3 +1,5 @@
+// `any` in and out, as it has always been published: #709 decides whether this
+// helper stays public, and typing it here would change it for callers first.
 export function clone(data) {
     try {
         return structuredClone(data);

package/dist/story-error.d.ts

@@ -1,13 +1,13 @@
 export declare const SANDBOX_ERROR = "__poveste:sandbox-error";
 export interface StoryError {
     message: string;
-    stack?: string;
+    stack?: string | undefined;
     /**
      * Which occupant threw. A warm realm is retargeted rather than reloaded
      * (#240), so the host has to reject a report from the previous one.
      */
-    storyId?: string;
-    variantId?: string;
+    storyId?: string | undefined;
+    variantId?: string | undefined;
 }
 export declare function toStoryError(error: unknown): Pick<StoryError, 'message' | 'stack'>;
 export declare function reportStoryError(error: unknown, occupant?: Pick<StoryError, 'storyId' | 'variantId'>): void;

package/dist/types/command.d.ts

@@ -23,8 +23,16 @@ export interface ClientCommandOptions extends CommonCommandOptions {
 export type ClientCommand = Command & ClientCommandOptions;
 export interface ClientCommandContext {
     route: RouteLocationNormalizedLoaded;
-    currentStory: Story;
-    currentVariant: Variant;
+    /**
+     * The story the route names, or undefined on any route that names none — the
+     * home page, or a story id that is not loaded. Declared non-optional here
+     * until #667: the app has always filled it from a `.find()`, so a plugin
+     * writing `ctx.currentStory.id` in `showIf` was reading a value the type
+     * promised and the app did not always supply.
+     */
+    currentStory: Story | undefined;
+    /** The selected variant, or undefined. Null in the tick between a story being routed to and its variant being chosen. */
+    currentVariant: Variant | undefined;
 }
 export interface PluginCommand<TParams = Record<string, any>> extends Command {
     serverAction?: (params: TParams) => unknown;

package/dist/types/config.d.ts

@@ -1,4 +1,4 @@
-import type MarkdownIt from 'markdown-it';
+import type { MarkdownIt } from 'markdown-it';
 import type { UseHeadInput } from 'unhead/types';
 import type { UserConfig as ViteConfig, ConfigEnv as ViteConfigEnv } from 'vite';
 import type { Plugin } from './plugin.js';
@@ -14,7 +14,7 @@ export type GrayColorKeys = ColorKeys | '750' | '850' | '950';
 export interface ResponsivePreset {
     label: string;
     width: number;
-    height?: number;
+    height?: number | null;
 }
 export interface BackgroundPreset {
     label: string;
@@ -76,7 +76,7 @@ export interface PovesteConfig {
         groups?: TreeGroupConfig[];
     };
     /**
-     * Customize the look of the histoire book.
+     * Customize the look of the book.
      */
     theme: {
         /**

package/dist/types/plugin.d.ts

@@ -7,6 +7,11 @@ import type { Awaitable } from '../type-utils.js';
 import type { PluginCommand } from './command.js';
 import type { ConfigMode, PovesteConfig } from './config.js';
 import type { ServerStory, ServerStoryFile, ServerVariant } from './story.js';
+/**
+ * A framework's collection strategy: how a story file written for that framework
+ * is imported and mounted. `@poveste/plugin-vue` and `@poveste/plugin-svelte`
+ * each expose one, and `supportMatch` in the config decides which files it claims.
+ */
 export interface SupportPlugin {
     id: string;
     moduleName: string;
@@ -14,37 +19,121 @@ export interface SupportPlugin {
     importStoriesPrepend?: string;
     importStoryComponent: (file: ServerStoryFile, index: number) => string;
 }
+/**
+ * A {@link SupportPlugin} after Poveste has resolved it. Identical to the
+ * declared shape today; it exists so resolution can add fields without changing
+ * what a plugin author writes.
+ */
 export interface FinalSupportPlugin extends SupportPlugin {
 }
+/**
+ * Loads a module through Vite, so a plugin can read a user's `.ts` or `.vue`
+ * file the way the collector does rather than reaching for `import`.
+ *
+ * `loadModule` resolves to `undefined` on an error it has already logged, so a
+ * caller that needs to fail has to check the result. `clearCache` invalidates
+ * Vite's module graph as well as the runner's, which is what makes a re-read
+ * after a file change return the new contents.
+ */
 export interface ModuleLoader {
     clearCache: () => void;
     loadModule: (file: string) => Promise<any>;
     destroy: () => void;
 }
+/** What changed under a path passed to `api.watch`. */
+export type WatchEvent = 'add' | 'change' | 'unlink';
+/** Called by `api.watch` with what happened and the absolute path it happened to. */
+export type WatchCallback = (event: WatchEvent, path: string) => Awaitable<unknown>;
+/**
+ * What every plugin hook receives.
+ *
+ * Prefer `log`/`warn`/`error` over `console`: they prefix the plugin's name, so
+ * a line in a busy build says what printed it.
+ */
 export interface PluginApiBase {
+    /**
+     * Poveste's own picocolors.
+     *
+     * @deprecated Import `picocolors` directly. Works for the rest of 0.x and is removable at 1.0 (#356).
+     */
     colors: typeof pc;
+    /**
+     * Poveste's own pathe.
+     *
+     * @deprecated Import `node:path`, or `pathe` for forward slashes on Windows. Works for the rest of
+     * 0.x and is removable at 1.0 (#356).
+     */
     path: typeof path;
+    /**
+     * Poveste's own fs-extra.
+     *
+     * @deprecated Import `node:fs` or `node:fs/promises` directly. Works for the rest of 0.x and is
+     * removable at 1.0 (#356).
+     */
     fs: typeof fs;
     moduleLoader: ModuleLoader;
     readonly pluginTempDir: string;
-    log: (...msg: any[]) => void;
-    warn: (...msg: any[]) => void;
-    error: (...msg: any[]) => void;
+    log: (...msg: unknown[]) => void;
+    warn: (...msg: unknown[]) => void;
+    error: (...msg: unknown[]) => void;
     getStories: () => ServerStory[];
     addStoryFile: (file: string) => void;
     getConfig: () => PovesteConfig;
+    /**
+     * Calls `callback` when a file under `paths` is added, changed or removed after
+     * the call. What already exists raises nothing.
+     *
+     * Poveste owns the watcher and closes it with the dev server, however the server
+     * ends, so a plugin has nothing to release. The returned function stops watching
+     * sooner. A callback that throws or rejects is logged with the plugin's name.
+     *
+     * Only `poveste dev` watches. In a build this does nothing, because a watcher
+     * opened while a failed build closes its server is what kept that build's
+     * process alive (#434).
+     */
+    watch: (paths: string | string[], callback: WatchCallback) => () => Promise<void>;
 }
+/**
+ * {@link PluginApiBase} as passed to `onDev`.
+ */
 export interface PluginApiDev extends PluginApiBase {
+    /**
+     * Poveste's own chokidar module. A watcher opened from it is the plugin's to close.
+     *
+     * @deprecated Use {@link PluginApiBase.watch}, which Poveste closes with the dev server. Works for
+     * the rest of 0.x and is removable at 1.0 (#356).
+     */
     watcher: typeof chokidar;
 }
+/**
+ * Mutates the Vite config Poveste is about to build with. Registered through
+ * `changeViteConfig`, and run once, before the build starts.
+ */
 export type ChangeViteConfigCallback = (config: ViteInlineConfig) => Awaitable<void>;
+/**
+ * Runs after a build **succeeds**. A build that fails never reaches it, which is
+ * why anything that must be released belongs in `onCleanup` instead (#434).
+ */
 export type BuildEndCallback = () => Awaitable<void>;
+/**
+ * Runs once per variant **after** the build has finished, against a preview
+ * server started for the purpose, with the URL that variant is served from.
+ * This is the hook a screenshot or visual-diff plugin uses.
+ *
+ * Registering one is what makes the build start that server at all, so a plugin
+ * that registers unconditionally adds a preview boot to every build.
+ */
 export type PreviewStoryCallback = (payload: {
     file: string;
     story: ServerStory;
     variant: ServerVariant;
     url: string;
 }) => Awaitable<void>;
+/**
+ * {@link PluginApiBase} plus the build hooks, passed to `onBuild`. The three
+ * arrays are the registered callbacks; the three functions are how a plugin adds
+ * to them.
+ */
 export interface PluginApiBuild extends PluginApiBase {
     changeViteConfigCallbacks: ChangeViteConfigCallback[];
     buildEndCallbacks: BuildEndCallback[];
@@ -53,17 +142,29 @@ export interface PluginApiBuild extends PluginApiBase {
     onBuildEnd: (cb: BuildEndCallback) => void;
     onPreviewStory: (cb: PreviewStoryCallback) => void;
 }
+/**
+ * {@link PluginApiBase} plus the event that triggered the hook, passed to
+ * `onDevEvent`. `payload` is whatever the client sent to `sendEvent`, unvalidated.
+ */
 export interface PluginApiDevEvent extends PluginApiBase {
     event: string;
     payload: any;
 }
+/**
+ * A Poveste plugin: a name and whichever hooks it needs. Listed in `plugins` in
+ * `poveste.config.ts`, and every hook is optional.
+ *
+ * The hooks below run in the order they are declared — `defaultConfig`, `config`
+ * and `configResolved` while the config settles, then `onDev`, `onBuild` or
+ * `onPreview` depending on the command.
+ */
 export interface Plugin {
     /**
      * Name of the plugin
      */
     name: string;
     /**
-     * Modify histoire default config. The hook can either mutate the passed config or
+     * Modify Poveste's default config. The hook can either mutate the passed config or
      * return a partial config object that will be deeply merged into the existing
      * config. User config will have higher priority than default config.
      *
@@ -72,7 +173,7 @@ export interface Plugin {
      */
     defaultConfig?: (defaultConfig: PovesteConfig, mode: ConfigMode) => Partial<PovesteConfig> | null | void | Promise<Partial<PovesteConfig> | null | void>;
     /**
-     * Modify histoire config. The hook can either mutate the passed config or
+     * Modify the Poveste config. The hook can either mutate the passed config or
      * return a partial config object that will be deeply merged into the existing
      * config.
      *
@@ -81,7 +182,7 @@ export interface Plugin {
      */
     config?: (config: PovesteConfig, mode: ConfigMode) => Partial<PovesteConfig> | null | void | Promise<Partial<PovesteConfig> | null | void>;
     /**
-     * Use this hook to read and store the final resolved histoire config.
+     * Use this hook to read and store the final resolved Poveste config.
      */
     configResolved?: (config: PovesteConfig) => Awaitable<void>;
     /**
@@ -91,8 +192,7 @@ export interface Plugin {
     onDev?: (api: PluginApiDev, onCleanup: (cb: () => Awaitable<void>) => void) => Awaitable<void>;
     /**
      * Use this hook to do processing during production build.
-     */
-    /**
+     *
      * `onCleanup` runs however the build ends, including when it fails. Anything a
      * plugin opened belongs there rather than in `onBuildEnd`, which only runs when
      * the build succeeded — a plugin holding a framework instance or a watcher kept

package/dist/types/story.d.ts

@@ -75,26 +75,26 @@ export interface VariantMeta extends CommonMeta {
 export interface Variant {
     id: string;
     title: string;
-    icon?: string;
-    iconColor?: string;
-    setupApp?: (payload: any) => unknown;
-    slots?: () => {
+    icon?: string | undefined;
+    iconColor?: string | undefined;
+    setupApp?: ((payload: any) => unknown) | undefined;
+    slots?: (() => {
         default: any;
         controls: any;
         source: any;
-    };
+    }) | undefined;
     state: any;
-    source?: string;
-    responsiveDisabled?: boolean;
-    autoPropsDisabled?: boolean;
-    configReady?: boolean;
-    previewReady?: boolean;
-    meta?: VariantMeta;
+    source?: string | undefined;
+    responsiveDisabled?: boolean | undefined;
+    autoPropsDisabled?: boolean | undefined;
+    configReady?: boolean | undefined;
+    previewReady?: boolean | undefined;
+    meta?: VariantMeta | undefined;
 }
 export interface PropDefinition {
     name: string;
-    types?: string[];
-    required?: boolean;
+    types?: string[] | undefined;
+    required?: boolean | undefined;
     default?: any;
 }
 export interface AutoPropComponentDefinition {
@@ -123,7 +123,7 @@ export interface ServerStoryFile {
     /**
      * Generated path for tree UI
      */
-    treePath?: string[];
+    treePath?: string[] | undefined;
     /**
      * Use the module id in imports to allow HMR
      */
@@ -131,23 +131,23 @@ export interface ServerStoryFile {
     /**
      * Resolved story data from story file execution
      */
-    story?: ServerStory;
+    story?: ServerStory | undefined;
     /**
      * Data sent to user tree config functions
      */
-    treeFile?: ServerTreeFile;
+    treeFile?: ServerTreeFile | undefined;
     /**
      * Is virtual module
      */
-    virtual?: boolean;
+    virtual?: boolean | undefined;
     /**
      * Virtual module code
      */
-    moduleCode?: string;
+    moduleCode?: string | undefined;
     /**
      * Related markdown docs
      */
-    markdownFile?: ServerMarkdownFile;
+    markdownFile?: ServerMarkdownFile | undefined;
 }
 export interface ServerMarkdownFile {
     id: string;
@@ -155,28 +155,28 @@ export interface ServerMarkdownFile {
     absolutePath: string;
     isRelatedToStory: boolean;
     frontmatter?: any;
-    html?: string;
-    content?: string;
-    storyFile?: ServerStoryFile;
+    html?: string | undefined;
+    content?: string | undefined;
+    storyFile?: ServerStoryFile | undefined;
 }
 export interface ServerStory {
     id: string;
     title: string;
-    group?: string;
+    group?: string | undefined;
     variants: ServerVariant[];
-    layout?: StoryLayout;
-    icon?: string;
-    iconColor?: string;
-    docsOnly?: boolean;
-    docsText?: string;
-    meta?: StoryMeta;
+    layout?: StoryLayout | undefined;
+    icon?: string | undefined;
+    iconColor?: string | undefined;
+    docsOnly?: boolean | undefined;
+    docsText?: string | undefined;
+    meta?: StoryMeta | undefined;
 }
 export interface ServerVariant {
     id: string;
     title: string;
-    icon?: string;
-    iconColor?: string;
-    meta?: VariantMeta;
+    icon?: string | undefined;
+    iconColor?: string | undefined;
+    meta?: VariantMeta | undefined;
 }
 export interface ServerTreeFile {
     title: string;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@poveste/shared",
   "type": "module",
-  "version": "0.13.1",
+  "version": "0.15.0",
   "description": "Shared utilities for Poveste",
   "author": {
     "name": "Sorin Gitlan",
@@ -39,18 +39,18 @@
     "vite": "^8.0.0"
   },
   "dependencies": {
-    "@poveste/vendors": "^0.13.1",
+    "@poveste/vendors": "^0.15.0",
     "@types/fs-extra": "^11.0.4",
-    "@types/markdown-it": "^14.1.2",
-    "chokidar": "^4.0.1",
-    "pathe": "^1.1.2",
+    "chokidar": "^5.0.0",
+    "markdown-it": "^15.0.2",
+    "pathe": "^2.0.3",
     "picocolors": "^1.1.1",
     "unhead": "^3.1.0"
   },
   "devDependencies": {
-    "typescript": "5.6.3",
+    "typescript": "6.0.3",
     "vite": "^8.2.0",
-    "vitest": "^4.1.10"
+    "vitest": "^5.0.0"
   },
   "scripts": {
     "build": "rimraf dist && tsc",