@stacksjs/stx 0.2.155 → 0.2.157

package/dist/story/cli.d.ts

@@ -1,3 +1,126 @@
+/**
+ * STX Story - CLI Integration
+ * Provides CLI commands for the story feature
+ */
+/**
+ * CLI command definitions for integration with @stacksjs/clapp
+ */
+export declare const storyCommands: {
+    /**
+     * Main story command (defaults to dev)
+     */
+    story: {
+        description: string;
+        options: {
+            port: {
+                alias: string;
+                type: 'number';
+                description: string;
+            };
+            open: {
+                alias: string;
+                type: 'boolean';
+                description: string;
+            };
+            host: {
+                type: 'string';
+                description: string;
+            };
+        };
+        action: (options: {
+            port?: number;
+            open?: boolean;
+            host?: string;
+        }) => Promise<void>;
+    };
+    /**
+     * Story dev subcommand
+     */
+    'story:dev': {
+        description: string;
+        options: {
+            port: {
+                alias: string;
+                type: 'number';
+                description: string;
+            };
+            open: {
+                alias: string;
+                type: 'boolean';
+                description: string;
+            };
+            host: {
+                type: 'string';
+                description: string;
+            };
+        };
+        action: (options: {
+            port?: number;
+            open?: boolean;
+            host?: string;
+        }) => Promise<void>;
+    };
+    /**
+     * Story build subcommand
+     */
+    'story:build': {
+        description: string;
+        options: {
+            outDir: {
+                alias: string;
+                type: 'string';
+                description: string;
+            };
+        };
+        action: (options: {
+            outDir?: string;
+        }) => Promise<void>;
+    };
+    /**
+     * Story preview subcommand
+     */
+    'story:preview': {
+        description: string;
+        options: {
+            port: {
+                alias: string;
+                type: 'number';
+                description: string;
+            };
+            open: {
+                alias: string;
+                type: 'boolean';
+                description: string;
+            };
+        };
+        action: (options: {
+            port?: number;
+            open?: boolean;
+        }) => Promise<void>;
+    };
+    /**
+     * Story test subcommand
+     */
+    'story:test': {
+        description: string;
+        options: {
+            update: {
+                alias: string;
+                type: 'boolean';
+                description: string;
+            };
+            filter: {
+                alias: string;
+                type: 'string';
+                description: string;
+            };
+        };
+        action: (options: {
+            update?: boolean;
+            filter?: string;
+        }) => Promise<void>;
+    };
+};
 /**
  * Register story commands with a CLI instance
  * This is a helper for manual CLI integration
@@ -7,72 +130,3 @@ export declare function registerStoryCommands(cli: any): void;
  * Run story CLI directly (for standalone usage)
  */
 export declare function runStoryCLI(args?: string[]): Promise<void>;
-/**
- * CLI command definitions for integration with @stacksjs/clapp
- * @defaultValue
- * ```ts
- * {
- *   'story': {
- *     description: 'Component showcase and testing',
- *     options: {
- *       port: { alias: 'p', description: 'Server port (default: 6006)' },
- *       open: { alias: 'o', description: 'Open browser automatically' },
- *       host: { description: 'Host to bind to' }
- *     },
- *     action: (options: { port?: number, open?: boolean, host?: string }): Promise<void> => Promise<unknown>
- *   },
- *   'story:dev': {
- *     description: 'Start story development server',
- *     options: {
- *       port: { alias: 'p', description: 'Server port (default: 6006)' },
- *       open: { alias: 'o', description: 'Open browser automatically' },
- *       host: { description: 'Host to bind to' }
- *     },
- *     action: (options: { port?: number, open?: boolean, host?: string }): Promise<void> => Promise<unknown>
- *   },
- *   'story:build': {
- *     description: 'Build static story site',
- *     options: { outDir: { alias: 'o', description: 'Output directory' } },
- *     action: (options: { outDir?: string }): Promise<void> => Promise<unknown>
- *   },
- *   'story:preview': {
- *     description: 'Preview built story site',
- *     options: {
- *       port: { alias: 'p', description: 'Server port (default: 4173)' },
- *       open: { alias: 'o', description: 'Open browser automatically' }
- *     },
- *     action: (options: { port?: number, open?: boolean }): Promise<void> => Promise<unknown>
- *   },
- *   'story:test': {
- *     description: 'Run visual regression tests',
- *     options: {
- *       update: { alias: 'u', description: 'Update snapshots' },
- *       filter: { alias: 'f', description: 'Filter components by name' }
- *     },
- *     action: (options: { update?: boolean, filter?: string }): Promise<void> => Promise<unknown>
- *   }
- * }
- * ```
- */
-export declare const storyCommands: {
-  /**
-   * Main story command (defaults to dev)
-   */
-  'story': { /** @defaultValue 'Component showcase and testing' */ description: string; options: { port: { /** @defaultValue 'p' */ alias: string; type: 'number'; /** @defaultValue 'Server port (default: 6006)' */ description: string }; open: { /** @defaultValue 'o' */ alias: string; type: 'boolean'; /** @defaultValue 'Open browser automatically' */ description: string }; host: { type: 'string'; /** @defaultValue 'Host to bind to' */ description: string } }; action: (options: { port?: number, open?: boolean, host?: string }): Promise<void> => Promise<unknown> };
-  /**
-   * Story dev subcommand
-   */
-  'story:dev': { /** @defaultValue 'Start story development server' */ description: string; options: { port: { /** @defaultValue 'p' */ alias: string; type: 'number'; /** @defaultValue 'Server port (default: 6006)' */ description: string }; open: { /** @defaultValue 'o' */ alias: string; type: 'boolean'; /** @defaultValue 'Open browser automatically' */ description: string }; host: { type: 'string'; /** @defaultValue 'Host to bind to' */ description: string } }; action: (options: { port?: number, open?: boolean, host?: string }): Promise<void> => Promise<unknown> };
-  /**
-   * Story build subcommand
-   */
-  'story:build': { /** @defaultValue 'Build static story site' */ description: string; options: { outDir: { /** @defaultValue 'o' */ alias: string; type: 'string'; /** @defaultValue 'Output directory' */ description: string } }; action: (options: { outDir?: string }): Promise<void> => Promise<unknown> };
-  /**
-   * Story preview subcommand
-   */
-  'story:preview': { /** @defaultValue 'Preview built story site' */ description: string; options: { port: { /** @defaultValue 'p' */ alias: string; type: 'number'; /** @defaultValue 'Server port (default: 4173)' */ description: string }; open: { /** @defaultValue 'o' */ alias: string; type: 'boolean'; /** @defaultValue 'Open browser automatically' */ description: string } }; action: (options: { port?: number, open?: boolean }): Promise<void> => Promise<unknown> };
-  /**
-   * Story test subcommand
-   */
-  'story:test': { /** @defaultValue 'Run visual regression tests' */ description: string; options: { update: { /** @defaultValue 'u' */ alias: string; type: 'boolean'; /** @defaultValue 'Update snapshots' */ description: string }; filter: { /** @defaultValue 'f' */ alias: string; type: 'string'; /** @defaultValue 'Filter components by name' */ description: string } }; action: (options: { update?: boolean, filter?: string }): Promise<void> => Promise<unknown> }
-};

package/dist/story/collect/scanner.d.ts

@@ -1,3 +1,7 @@
+/**
+ * STX Story - Story file scanner
+ * Discovers .story.stx files in the project
+ */
 import type { ServerStoryFile, StoryContext } from '../types';
 /**
  * Scan for story files matching the configured patterns

package/dist/story/collect/tree.d.ts

@@ -1,3 +1,7 @@
+/**
+ * STX Story - Tree builder
+ * Builds the navigation tree from story files
+ */
 import type { ResolvedStoryConfig, ServerStoryFile, ServerTree, ServerTreeLeaf } from '../types';
 /**
  * Create tree path from a story file
@@ -14,4 +18,7 @@ export declare function flattenTree(tree: ServerTree): number[];
 /**
  * Find a story in the tree by index
  */
-export declare function findStoryInTree(tree: ServerTree, index: number): { path: string[], node: ServerTreeLeaf } | null;
+export declare function findStoryInTree(tree: ServerTree, index: number): {
+    path: string[];
+    node: ServerTreeLeaf;
+} | null;

package/dist/story/commands/build.d.ts

@@ -1,3 +1,14 @@
+/**
+ * STX Story - Build command
+ * Build static story site for deployment
+ */
+/**
+ * Options for the build command
+ */
+export interface BuildOptions {
+    /** Output directory (overrides config) */
+    outDir?: string;
+}
 /**
  * Build static story site
  */
@@ -6,9 +17,3 @@ export declare function buildCommand(options?: BuildOptions): Promise<void>;
  * Run build command (alias)
  */
 export declare const build: typeof buildCommand;
-/**
- * Options for the build command
- */
-export declare interface BuildOptions {
-  outDir?: string
-}

package/dist/story/commands/dev.d.ts

@@ -1,3 +1,18 @@
+/**
+ * STX Story - Dev command
+ * Start the story development server
+ */
+/**
+ * Options for the dev command
+ */
+export interface DevOptions {
+    /** Server port (default: 6006) */
+    port?: number;
+    /** Open browser automatically */
+    open?: boolean;
+    /** Host to bind to */
+    host?: string | boolean;
+}
 /**
  * Start the story development server
  */
@@ -6,11 +21,3 @@ export declare function devCommand(options?: DevOptions): Promise<void>;
  * Run dev command (alias for devCommand)
  */
 export declare const dev: typeof devCommand;
-/**
- * Options for the dev command
- */
-export declare interface DevOptions {
-  port?: number
-  open?: boolean
-  host?: string | boolean
-}

package/dist/story/commands/preview.d.ts

@@ -1,3 +1,16 @@
+/**
+ * STX Story - Preview command
+ * Preview the built story site locally
+ */
+/**
+ * Options for the preview command
+ */
+export interface PreviewOptions {
+    /** Server port (default: 4173) */
+    port?: number;
+    /** Open browser automatically */
+    open?: boolean;
+}
 /**
  * Preview the built story site
  */
@@ -6,10 +19,3 @@ export declare function previewCommand(options?: PreviewOptions): Promise<void>;
  * Run preview command (alias)
  */
 export declare const preview: typeof previewCommand;
-/**
- * Options for the preview command
- */
-export declare interface PreviewOptions {
-  port?: number
-  open?: boolean
-}

package/dist/story/config-watcher.d.ts

@@ -1,4 +1,24 @@
+/**
+ * STX Story - Config file watcher
+ * Watches stx.config.ts for changes and triggers restart
+ */
 import type { StoryContext } from './types';
+/**
+ * Config watcher options
+ */
+export interface ConfigWatcherOptions {
+    /** Callback when config changes */
+    onChange: () => void | Promise<void>;
+    /** Debounce delay in ms */
+    debounceMs?: number;
+}
+/**
+ * Config watcher instance
+ */
+export interface ConfigWatcher {
+    /** Stop watching */
+    stop: () => void;
+}
 /**
  * Watch the config file for changes
  */
@@ -11,16 +31,3 @@ export declare function findConfigFile(root: string): string | null;
  * Get the last modified time of the config file
  */
 export declare function getConfigModifiedTime(root: string): Promise<number | null>;
-/**
- * Config watcher options
- */
-export declare interface ConfigWatcherOptions {
-  onChange: () => void | Promise<void>
-  debounceMs?: number
-}
-/**
- * Config watcher instance
- */
-export declare interface ConfigWatcher {
-  stop: () => void
-}

package/dist/story/config.d.ts

@@ -1,13 +1,7 @@
-import type { BackgroundPreset, ResolvedStoryConfig, ResponsivePreset, StoryConfig, StoryTreeConfig } from './types';
 /**
- * Resolve story configuration with defaults
+ * STX Story - Configuration handling
  */
-export declare function resolveStoryConfig(config?: StoryConfig): ResolvedStoryConfig;
-/**
- * Get the default story configuration
- * Useful for extending defaults in user config
- */
-export declare function getDefaultStoryConfig(): StoryConfig;
+import type { BackgroundPreset, ResolvedStoryConfig, ResponsivePreset, StoryConfig, StoryTreeConfig } from './types';
 /**
  * Default responsive presets
  */
@@ -24,3 +18,12 @@ export declare const defaultTreeConfig: Required<StoryTreeConfig>;
  * Default story configuration
  */
 export declare const defaultStoryConfig: StoryConfig;
+/**
+ * Resolve story configuration with defaults
+ */
+export declare function resolveStoryConfig(config?: StoryConfig): ResolvedStoryConfig;
+/**
+ * Get the default story configuration
+ * Useful for extending defaults in user config
+ */
+export declare function getDefaultStoryConfig(): StoryConfig;

package/dist/story/context.d.ts

@@ -1,4 +1,18 @@
+/**
+ * STX Story - Context management
+ */
 import type { ServerStoryFile, ServerTree, StoryConfig, StoryContext } from './types';
+/**
+ * Options for creating a story context
+ */
+export interface CreateContextOptions {
+    /** Mode: 'dev' or 'build' */
+    mode: 'dev' | 'build';
+    /** Root directory (defaults to cwd) */
+    root?: string;
+    /** Story configuration override */
+    config?: StoryConfig;
+}
 /**
  * Create a story context
  */
@@ -11,11 +25,3 @@ export declare function updateContextStoryFiles(ctx: StoryContext, storyFiles: S
  * Update context with built tree
  */
 export declare function updateContextTree(ctx: StoryContext, tree: ServerTree): void;
-/**
- * Options for creating a story context
- */
-export declare interface CreateContextOptions {
-  mode: 'dev' | 'build'
-  root?: string
-  config?: StoryConfig
-}

package/dist/story/hmr.d.ts

@@ -1,4 +1,28 @@
+/**
+ * STX Story - Hot Module Reload
+ * WebSocket-based HMR for story updates
+ */
 import type { ServerWebSocket } from 'bun';
+/**
+ * HMR message types
+ */
+export type HmrMessageType = 'connected' | 'story-update' | 'story-add' | 'story-remove' | 'config-change' | 'full-reload' | 'error';
+/**
+ * HMR message structure
+ */
+export interface HmrMessage {
+    type: HmrMessageType;
+    data?: any;
+    timestamp?: number;
+}
+/**
+ * Create WebSocket upgrade handler for HMR
+ */
+export interface HmrWebSocketHandler {
+    open: (ws: ServerWebSocket<unknown>) => void;
+    close: (ws: ServerWebSocket<unknown>) => void;
+    message: (ws: ServerWebSocket<unknown>, message: string | ArrayBuffer) => void;
+}
 export declare function createHmrHandler(): HmrWebSocketHandler;
 /**
  * Broadcast a message to all connected clients
@@ -36,29 +60,3 @@ export declare function getClientCount(): number;
  * Get HMR client script to inject into the page
  */
 export declare function getHmrClientScript(wsUrl: string): string;
-/**
- * HMR message structure
- */
-export declare interface HmrMessage {
-  type: HmrMessageType
-  data?: any
-  timestamp?: number
-}
-/**
- * Create WebSocket upgrade handler for HMR
- */
-export declare interface HmrWebSocketHandler {
-  open: (ws: ServerWebSocket<unknown>) => void
-  close: (ws: ServerWebSocket<unknown>) => void
-  message: (ws: ServerWebSocket<unknown>, message: string | ArrayBuffer) => void
-}
-/**
- * HMR message types
- */
-export type HmrMessageType = | 'connected'
-  | 'story-update'
-  | 'story-add'
-  | 'story-remove'
-  | 'config-change'
-  | 'full-reload'
-  | 'error';

package/dist/story/hot-swap.d.ts

@@ -1,16 +1,3 @@
-/**
- * Generate hot swap client script
- * Injects into the story UI for seamless variant switching
- */
-export declare function getHotSwapScript(): string;
-/**
- * Generate variant selector UI
- */
-export declare function getVariantSelectorHtml(variants: Array<{ id: string, title: string }>, currentVariantId: string): string;
-/**
- * Generate variant selector styles
- */
-export declare function getVariantSelectorStyles(): string;
 /**
  * STX Story - Hot Swap
  * Switch story variants without full page reload
@@ -18,18 +5,42 @@ export declare function getVariantSelectorStyles(): string;
 /**
  * Hot swap state
  */
-export declare interface HotSwapState {
-  storyId: string | null
-  variantId: string | null
-  props: Record<string, any>
-  iframe: HTMLIFrameElement | null
+export interface HotSwapState {
+    /** Current story ID */
+    storyId: string | null;
+    /** Current variant ID */
+    variantId: string | null;
+    /** Current props */
+    props: Record<string, any>;
+    /** Iframe element reference */
+    iframe: HTMLIFrameElement | null;
 }
 /**
  * Hot swap options
  */
-export declare interface HotSwapOptions {
-  animationDuration?: number
-  preserveScroll?: boolean
-  onBeforeSwap?: (state: HotSwapState) => void
-  onAfterSwap?: (state: HotSwapState) => void
+export interface HotSwapOptions {
+    /** Animation duration in ms */
+    animationDuration?: number;
+    /** Preserve scroll position */
+    preserveScroll?: boolean;
+    /** Callback before swap */
+    onBeforeSwap?: (state: HotSwapState) => void;
+    /** Callback after swap */
+    onAfterSwap?: (state: HotSwapState) => void;
 }
+/**
+ * Generate hot swap client script
+ * Injects into the story UI for seamless variant switching
+ */
+export declare function getHotSwapScript(): string;
+/**
+ * Generate variant selector UI
+ */
+export declare function getVariantSelectorHtml(variants: Array<{
+    id: string;
+    title: string;
+}>, currentVariantId: string): string;
+/**
+ * Generate variant selector styles
+ */
+export declare function getVariantSelectorStyles(): string;

package/dist/story/keyboard-shortcuts.d.ts

@@ -1,3 +1,26 @@
+/**
+ * STX Story - Keyboard Shortcuts
+ * Keyboard shortcuts panel and handler
+ */
+/**
+ * Keyboard shortcut definition
+ */
+export interface KeyboardShortcut {
+    /** Shortcut key(s) */
+    key: string;
+    /** Modifier keys */
+    modifiers?: ('ctrl' | 'alt' | 'shift' | 'meta')[];
+    /** Description */
+    description: string;
+    /** Category */
+    category: string;
+    /** Action to perform */
+    action: string;
+}
+/**
+ * Default keyboard shortcuts
+ */
+export declare const defaultShortcuts: KeyboardShortcut[];
 /**
  * Format shortcut key for display
  */
@@ -14,21 +37,3 @@ export declare function getShortcutsStyles(): string;
  * Generate keyboard shortcuts handler script
  */
 export declare function getShortcutsScript(): string;
-/**
- * Default keyboard shortcuts
- */
-export declare const defaultShortcuts: KeyboardShortcut[];
-/**
- * STX Story - Keyboard Shortcuts
- * Keyboard shortcuts panel and handler
- */
-/**
- * Keyboard shortcut definition
- */
-export declare interface KeyboardShortcut {
-  key: string
-  modifiers?: ('ctrl' | 'alt' | 'shift' | 'meta')[]
-  description: string
-  category: string
-  action: string
-}