@poveste/shared 0.13.1 → 0.14.0

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

@@ -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,13 +19,35 @@ 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 every plugin hook receives. `colors`, `path` and `fs` are Poveste's own
+ * picocolors, pathe and fs-extra, handed over so a plugin can use them without
+ * adding a second copy to the tree.
+ *
+ * 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 {
     colors: typeof pc;
     path: typeof path;
@@ -34,17 +61,42 @@ export interface PluginApiBase {
     addStoryFile: (file: string) => void;
     getConfig: () => PovesteConfig;
 }
+/**
+ * {@link PluginApiBase} plus the file watcher, passed to `onDev`. Only the dev
+ * server has one — a build never watches.
+ */
 export interface PluginApiDev extends PluginApiBase {
     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 +105,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 +136,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 +145,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 +155,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/package.json

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