@stacksjs/stx 0.2.0 → 0.2.3

package/dist/story/analytics.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Generate analytics dashboard HTML
+ */
+export declare function getAnalyticsDashboardHtml(mostViewed: Array<{ componentId: string, viewCount: number }>, mostChangedProps: Array<{ propName: string, changeCount: number }>): string;
+/**
+ * Generate analytics styles
+ */
+export declare function getAnalyticsStyles(): string;
+/**
+ * Analytics event
+ */
+export declare interface AnalyticsEvent {
+  type: AnalyticsEventType
+  timestamp: number
+  componentId?: string
+  variantId?: string
+  propName?: string
+  query?: string
+  metadata?: Record<string, any>
+}
+/**
+ * Component analytics summary
+ */
+export declare interface ComponentAnalytics {
+  componentId: string
+  componentName: string
+  viewCount: number
+  uniqueViews: number
+  lastViewed?: number
+  propChanges: Record<string, number>
+  topChangedProps: string[]
+  variantViews: Record<string, number>
+  avgTimeSpent: number
+}
+/**
+ * Analytics storage
+ */
+export declare interface AnalyticsStorage {
+  version: number
+  events: AnalyticsEvent[]
+  sessions: AnalyticsSession[]
+}
+/**
+ * Analytics session
+ */
+export declare interface AnalyticsSession {
+  id: string
+  startTime: number
+  endTime?: number
+  componentViews: string[]
+}
+/**
+ * Analytics event types
+ */
+export type AnalyticsEventType = | 'view'
+  | 'prop_change'
+  | 'variant_switch'
+  | 'search'
+  | 'bookmark'
+  | 'copy_code'
+  | 'test_run'
+/**
+ * Analytics tracker
+ */
+export declare class AnalyticsTracker {
+  private storage: AnalyticsStorage;
+  private storagePath: string;
+  private currentSession: AnalyticsSession | null;
+  private dirty: any;
+  private viewStartTimes: any;
+  constructor(rootDir: string);
+  private loadStorage(): AnalyticsStorage;
+  save(): Promise<void>;
+  startSession(): void;
+  endSession(): void;
+  track(event: Omit<AnalyticsEvent, 'timestamp'>): void;
+  trackView(componentId: string, variantId?: string): void;
+  private endViewTiming(componentId: string): void;
+  trackPropChange(componentId: string, propName: string, value: any): void;
+  trackVariantSwitch(componentId: string, variantId: string): void;
+  trackSearch(query: string, resultCount: number): void;
+  getComponentAnalytics(componentId: string, componentName: string): ComponentAnalytics;
+  getMostViewedComponents(limit?: any): Array<{ componentId: string, viewCount: number }>;
+  getMostChangedProps(limit?: any): Array<{ propName: string, changeCount: number }>;
+  getSearchAnalytics(): {
+    totalSearches: number
+    topQueries: Array<{ query: string, count: number }>
+    avgResultCount: number
+  };
+  clear(): void;
+  exportAnalytics(): string;
+}

package/dist/story/auto-stories.d.ts

@@ -0,0 +1,38 @@
+import type { AnalyzedComponent } from './types';
+/**
+ * Auto-generate stories for components
+ */
+export declare function autoGenerateStories(options: AutoGenerateOptions): Promise<GeneratedStory[]>;
+/**
+ * Generate story content for a component
+ */
+export declare function generateStoryContent(analysis: AnalyzedComponent, options?: { generateVariants?: boolean, includeDefaults?: boolean }): string;
+/**
+ * Generate story for a single component
+ */
+export declare function generateStoryForComponent(componentPath: string, options?: { generateVariants?: boolean, includeDefaults?: boolean }): Promise<string>;
+/**
+ * CLI command for auto-generating stories
+ */
+export declare function autoGenerateCommand(args: string[]): Promise<void>;
+/**
+ * Auto-generation options
+ */
+export declare interface AutoGenerateOptions {
+  componentsDir: string
+  outputDir?: string
+  include?: string[]
+  exclude?: string[]
+  generateVariants?: boolean
+  includeDefaults?: boolean
+  overwrite?: boolean
+}
+/**
+ * Generated story result
+ */
+export declare interface GeneratedStory {
+  componentPath: string
+  storyPath: string
+  content: string
+  status: 'created' | 'skipped' | 'updated'
+}

package/dist/story/bookmarks.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Generate bookmarks panel HTML
+ */
+export declare function getBookmarksPanelHtml(bookmarks: Bookmark[]): string;
+/**
+ * Generate bookmarks panel styles
+ */
+export declare function getBookmarksPanelStyles(): string;
+/**
+ * Generate bookmarks client script
+ */
+export declare function getBookmarksScript(): string;
+/**
+ * Bookmark entry
+ */
+export declare interface Bookmark {
+  id: string
+  name: string
+  storyId: string
+  variantId: string
+  props: Record<string, any>
+  created: number
+  notes?: string
+  color?: string
+}
+/**
+ * Bookmarks storage
+ */
+export declare interface BookmarksStorage {
+  version: number
+  bookmarks: Bookmark[]
+}
+/**
+ * Bookmarks manager
+ */
+export declare class BookmarksManager {
+  private storage: BookmarksStorage;
+  private storagePath: string;
+  private dirty: any;
+  constructor(rootDir: string);
+  private loadStorage(): BookmarksStorage;
+  save(): Promise<void>;
+  addBookmark(storyId: string, variantId: string, props: Record<string, any>, options?: { name?: string, notes?: string, color?: string }): Bookmark;
+  getAllBookmarks(): Bookmark[];
+  getBookmarksForStory(storyId: string): Bookmark[];
+  getBookmark(id: string): Bookmark | undefined;
+  isBookmarked(storyId: string, variantId: string): boolean;
+  updateBookmark(id: string, updates: Partial<Omit<Bookmark, 'id' | 'created'>>): Bookmark | undefined;
+  deleteBookmark(id: string): boolean;
+  toggleBookmark(storyId: string, variantId: string, props: Record<string, any>): { added: boolean, bookmark?: Bookmark };
+  exportBookmarks(): string;
+  importBookmarks(json: string, merge?: any): number;
+}

package/dist/story/bun-test.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Create a Bun test suite for stories
+ * Usage in test file:
+ *
+ * ```typescript
+ * import { createStoryTestSuite } from '@stacksjs/stx/story'
+ *
+ * createStoryTestSuite({
+ *   filter: ['Button', 'Card'],
+ *   threshold: 0.01,
+ * })
+ * ```
+ */
+export declare function createStoryTestSuite(options?: BunTestOptions): Promise<void>;
+/**
+ * Create individual test cases for each story
+ */
+export declare function createStoryTests(options?: BunTestOptions): Promise<void>;
+/**
+ * Run story tests programmatically
+ */
+export declare function runStoryTests(options?: BunTestOptions): Promise<{
+  passed: number
+  failed: number
+  total: number
+  duration: number
+}>;
+/**
+ * Generate test file content for stories
+ */
+export declare function generateTestFile(storyNames: string[]): string;
+/**
+ * Watch mode for story tests
+ */
+export declare function watchStoryTests(options?: BunTestOptions): Promise<void>;
+/**
+ * Test options for Bun integration
+ */
+export declare interface BunTestOptions {
+  filter?: string[]
+  update?: boolean
+  threshold?: number
+  timeout?: number
+}

package/dist/story/cli.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Register story commands with a CLI instance
+ * This is a helper for manual CLI integration
+ */
+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
+ */
+export declare const storyCommands: {
+  /**
+   * Main story command (defaults to dev)
+   */
+  'story': { description: 'Component showcase and testing'; options: { port: { alias: 'p'; type: 'number'; description: 'Server port (default: 6006)' }; open: { alias: 'o'; type: 'boolean'; description: 'Open browser automatically' }; host: { type: 'string'; description: 'Host to bind to' } }; action: (options: { port?: number, open?: boolean, host?: string }) => any };
+  /**
+   * Story dev subcommand
+   */
+  'story:dev': { description: 'Start story development server'; options: { port: { alias: 'p'; type: 'number'; description: 'Server port (default: 6006)' }; open: { alias: 'o'; type: 'boolean'; description: 'Open browser automatically' }; host: { type: 'string'; description: 'Host to bind to' } }; action: (options: { port?: number, open?: boolean, host?: string }) => any };
+  /**
+   * Story build subcommand
+   */
+  'story:build': { description: 'Build static story site'; options: { outDir: { alias: 'o'; type: 'string'; description: 'Output directory' } }; action: (options: { outDir?: string }) => any };
+  /**
+   * Story preview subcommand
+   */
+  'story:preview': { description: 'Preview built story site'; options: { port: { alias: 'p'; type: 'number'; description: 'Server port (default: 4173)' }; open: { alias: 'o'; type: 'boolean'; description: 'Open browser automatically' } }; action: (options: { port?: number, open?: boolean }) => any };
+  /**
+   * Story test subcommand
+   */
+  'story:test': { description: 'Run visual regression tests'; options: { update: { alias: 'u'; type: 'boolean'; description: 'Update snapshots' }; filter: { alias: 'f'; type: 'string'; description: 'Filter components by name' } }; action: (options: { update?: boolean, filter?: string }) => any }
+};

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

@@ -0,0 +1,33 @@
+import type { AnalyzedComponent, AnalyzedSlot, DirectiveUsage, StoryAnalyzedProp } from '../types';
+/**
+ * Analyze a component file and extract metadata
+ */
+export declare function analyzeComponentFile(filePath: string): Promise<AnalyzedComponent>;
+/**
+ * Analyze component content and extract metadata
+ */
+export declare function analyzeComponent(content: string, name: string, filePath: string): AnalyzedComponent;
+/**
+ * Extract props from script tags using proper tokenization
+ */
+export declare function extractProps(content: string): StoryAnalyzedProp[];
+/**
+ * Extract slots from template
+ */
+export declare function extractSlots(content: string): AnalyzedSlot[];
+/**
+ * Extract component description from comments
+ */
+export declare function extractDescription(content: string): string | undefined;
+/**
+ * Extract component dependencies (other components used)
+ */
+export declare function extractDependencies(content: string): string[];
+/**
+ * Extract CSS classes from template (for Crosswind integration)
+ */
+export declare function extractCssClasses(content: string): string[];
+/**
+ * Extract directive usage from template
+ */
+export declare function extractDirectives(content: string): DirectiveUsage[];

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

@@ -0,0 +1,27 @@
+export {
+  analyzeComponent,
+  analyzeComponentFile,
+  extractCssClasses,
+  extractDependencies,
+  extractDescription,
+  extractDirectives,
+  extractProps,
+  extractSlots,
+} from './analyzer';
+export {
+  extractScriptContent,
+  extractTemplateContent,
+  parseStoryContent,
+  parseStoryFile,
+} from './parser';
+export {
+  isNonComponentFile,
+  scanStoryFiles,
+  watchStoryFiles,
+} from './scanner';
+export {
+  buildTree,
+  createTreePath,
+  findStoryInTree,
+  flattenTree,
+} from './tree';

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

@@ -0,0 +1,17 @@
+import type { ServerStory } from '../types';
+/**
+ * Parse a story file and extract story definitions
+ */
+export declare function parseStoryFile(filePath: string): Promise<ServerStory | null>;
+/**
+ * Parse story content and extract story definitions
+ */
+export declare function parseStoryContent(content: string, filePath: string): ServerStory | null;
+/**
+ * Extract script content from a story file
+ */
+export declare function extractScriptContent(content: string): string;
+/**
+ * Extract template content from a story file (everything outside script tags)
+ */
+export declare function extractTemplateContent(content: string): string;

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

@@ -0,0 +1,13 @@
+import type { ServerStoryFile, StoryContext } from '../types';
+/**
+ * Scan for story files matching the configured patterns
+ */
+export declare function scanStoryFiles(ctx: StoryContext): Promise<ServerStoryFile[]>;
+/**
+ * Check if a file is a non-component file (layout, page, partial)
+ */
+export declare function isNonComponentFile(relativePath: string): boolean;
+/**
+ * Watch for story file changes
+ */
+export declare function watchStoryFiles(ctx: StoryContext, onChange: (event: 'add' | 'change' | 'unlink', file: ServerStoryFile) => void): () => void;

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

@@ -0,0 +1,17 @@
+import type { ResolvedStoryConfig, ServerStoryFile, ServerTree, ServerTreeLeaf,  } from '../types';
+/**
+ * Create tree path from a story file
+ */
+export declare function createTreePath(config: ResolvedStoryConfig, file: ServerStoryFile): string[];
+/**
+ * Build the navigation tree from story files
+ */
+export declare function buildTree(config: ResolvedStoryConfig, files: ServerStoryFile[]): ServerTree;
+/**
+ * Flatten tree to get all leaf indices in order
+ */
+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;

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

@@ -0,0 +1,14 @@
+/**
+ * Build static story site
+ */
+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

@@ -0,0 +1,16 @@
+/**
+ * Start the story development server
+ */
+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/index.d.ts

@@ -0,0 +1,6 @@
+export type { BuildOptions } from './build';
+export type { DevOptions } from './dev';
+export type { PreviewOptions } from './preview';
+export { build, buildCommand } from './build';
+export { dev, devCommand } from './dev';
+export { preview, previewCommand } from './preview';

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

@@ -0,0 +1,15 @@
+/**
+ * Preview the built story site
+ */
+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/compiled-output.d.ts

@@ -0,0 +1,26 @@
+import type { ServerStoryFile, StoryContext } from './types';
+/**
+ * Get compiled HTML output for a story variant
+ */
+export declare function getCompiledOutput(ctx: StoryContext, story: ServerStoryFile, variantId: string, options?: CompiledOutputOptions): Promise<string>;
+/**
+ * Generate compiled output panel HTML
+ */
+export declare function generateCompiledOutputPanel(compiledHtml: string): string;
+/**
+ * Get compiled output styles
+ */
+export declare function getCompiledOutputStyles(): string;
+/**
+ * Get compiled output toggle script
+ */
+export declare function getCompiledOutputScript(): string;
+/**
+ * Compiled output options
+ */
+export declare interface CompiledOutputOptions {
+  includeStyles?: boolean
+  includeScripts?: boolean
+  minify?: boolean
+  format?: boolean
+}

package/dist/story/composition.d.ts

@@ -0,0 +1,47 @@
+import type { AnalyzedComponent } from './types';
+/**
+ * Build dependency graph from analyzed components
+ */
+export declare function buildDependencyGraph(components: AnalyzedComponent[]): DependencyGraph;
+/**
+ * Get all dependencies of a component (recursive)
+ */
+export declare function getAllDependencies(graph: DependencyGraph, componentName: string): string[];
+/**
+ * Get all dependents of a component (recursive)
+ */
+export declare function getAllDependents(graph: DependencyGraph, componentName: string): string[];
+/**
+ * Detect circular dependencies
+ */
+export declare function detectCircularDependencies(graph: DependencyGraph): string[][];
+/**
+ * Generate dependency graph visualization HTML
+ */
+export declare function generateDependencyGraphHTML(graph: DependencyGraph, selectedComponent?: string): string;
+/**
+ * Get dependency graph styles
+ */
+export declare function getDependencyGraphStyles(): string;
+/**
+ * Generate component detail panel HTML
+ */
+export declare function generateComponentDetailHTML(graph: DependencyGraph, componentName: string): string;
+/**
+ * Dependency graph node
+ */
+export declare interface DependencyNode {
+  name: string
+  path: string
+  dependencies: string[]
+  dependents: string[]
+  depth: number
+}
+/**
+ * Dependency graph
+ */
+export declare interface DependencyGraph {
+  nodes: Map<string, DependencyNode>
+  roots: string[]
+  leaves: string[]
+}

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

@@ -0,0 +1,26 @@
+import type { StoryContext } from './types';
+/**
+ * Watch the config file for changes
+ */
+export declare function watchConfigFile(ctx: StoryContext, options: ConfigWatcherOptions): ConfigWatcher;
+/**
+ * Get the config file path if it exists
+ */
+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

@@ -0,0 +1,26 @@
+import type { BackgroundPreset, ResolvedStoryConfig, ResponsivePreset, StoryConfig, StoryTreeConfig,  } from './types';
+/**
+ * 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;
+/**
+ * Default responsive presets
+ */
+export declare const defaultResponsivePresets: ResponsivePreset[];
+/**
+ * Default background presets
+ */
+export declare const defaultBackgroundPresets: BackgroundPreset[];
+/**
+ * Default tree configuration
+ */
+export declare const defaultTreeConfig: Required<StoryTreeConfig>;
+/**
+ * Default story configuration
+ */
+export declare const defaultStoryConfig: StoryConfig;

package/dist/story/context.d.ts

@@ -0,0 +1,21 @@
+import type { ServerStoryFile, ServerTree, StoryConfig, StoryContext } from './types';
+/**
+ * Create a story context
+ */
+export declare function createContext(options: CreateContextOptions): Promise<StoryContext>;
+/**
+ * Update context with discovered story files
+ */
+export declare function updateContextStoryFiles(ctx: StoryContext, storyFiles: ServerStoryFile[]): void;
+/**
+ * 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/controls/index.d.ts

@@ -0,0 +1,54 @@
+import type { ControlConfig } from '../types';
+/**
+ * Render a control component as HTML
+ */
+export declare function renderControl(config: ControlConfig, value: any, onChange: string): string;
+/**
+ * Text input control
+ */
+export declare function renderTextControl(title: string, value: string, onChange: string): string;
+/**
+ * Number input control
+ */
+export declare function renderNumberControl(title: string, value: number, onChange: string, config: ControlConfig): string;
+/**
+ * Checkbox control
+ */
+export declare function renderCheckboxControl(title: string, value: boolean, onChange: string): string;
+/**
+ * Select dropdown control
+ */
+export declare function renderSelectControl(title: string, value: any, onChange: string, config: ControlConfig): string;
+/**
+ * Radio button group control
+ */
+export declare function renderRadioControl(title: string, value: any, onChange: string, config: ControlConfig): string;
+/**
+ * Color picker control
+ */
+export declare function renderColorControl(title: string, value: string, onChange: string): string;
+/**
+ * Textarea control
+ */
+export declare function renderTextareaControl(title: string, value: string, onChange: string): string;
+/**
+ * Slider control
+ */
+export declare function renderSliderControl(title: string, value: number, onChange: string, config: ControlConfig): string;
+/**
+ * JSON editor control
+ */
+export declare function renderJsonControl(title: string, value: any, onChange: string): string;
+/**
+ * Date input control
+ */
+export declare function renderDateControl(title: string, value: string, onChange: string): string;
+/**
+ * Get CSS styles for controls
+ */
+export declare function getControlStyles(): string;
+/**
+ * Button group control
+ */
+export declare function renderButtonGroupControl(title: string, value: any, onChange: string, config: ControlConfig): string;
+declare type ControlOption = string | { value: any, label: string }

package/dist/story/crosswind.d.ts

@@ -0,0 +1,29 @@
+import type { StoryContext } from './types';
+/**
+ * Check if Crosswind is available
+ */
+export declare function isCrosswindAvailable(root: string): Promise<boolean>;
+/**
+ * Load Crosswind CSS
+ */
+export declare function loadCrosswindCSS(ctx: StoryContext, options?: CrosswindOptions): Promise<string>;
+/**
+ * Generate style tag with Crosswind CSS
+ */
+export declare function generateCrosswindStyleTag(ctx: StoryContext, options?: CrosswindOptions): Promise<string>;
+/**
+ * Extract used utility classes from HTML
+ */
+export declare function extractUsedClasses(html: string): string[];
+/**
+ * Generate optimized CSS with only used classes
+ */
+export declare function generateOptimizedCSS(fullCSS: string, usedClasses: string[]): string;
+/**
+ * Crosswind CSS options
+ */
+export declare interface CrosswindOptions {
+  cssPath?: string
+  includeReset?: boolean
+  includeBase?: boolean
+}