@stacksjs/stx 0.2.154 → 0.2.156

package/dist/story/testing.d.ts

@@ -1,58 +1,83 @@
-import type { StoryContext } from './types';
-/**
- * Run visual regression tests
- */
-export declare function runVisualTests(ctx: StoryContext, options?: TestOptions): Promise<TestResult>;
-/**
- * Update all snapshots
- */
-export declare function updateSnapshots(ctx: StoryContext, options?: TestOptions): Promise<number>;
-/**
- * Format test results for console output
- */
-export declare function formatTestResults(result: TestResult): string;
 /**
- * Run accessibility tests on stories
+ * STX Story - Visual Regression Testing
+ * Snapshot-based testing for component renders
  */
-export declare function runA11yTests(ctx: StoryContext, _options?: TestOptions): Promise<TestResult>;
+import type { StoryContext } from './types';
 /**
  * Test options
  */
-export declare interface TestOptions {
-  update?: boolean
-  filter?: string[]
-  threshold?: number
-  snapshotDir?: string
+export interface TestOptions {
+    /** Update snapshots instead of comparing */
+    update?: boolean;
+    /** Only test specific components */
+    filter?: string[];
+    /** Threshold for pixel difference (0-1) */
+    threshold?: number;
+    /** Directory to store snapshots */
+    snapshotDir?: string;
 }
 /**
  * Test result
  */
-export declare interface TestResult {
-  total: number
-  passed: number
-  failed: number
-  new: number
-  failures: TestFailure[]
-  duration: number
+export interface TestResult {
+    /** Total number of tests */
+    total: number;
+    /** Number of passed tests */
+    passed: number;
+    /** Number of failed tests */
+    failed: number;
+    /** Number of new snapshots */
+    new: number;
+    /** Test failures */
+    failures: TestFailure[];
+    /** Duration in milliseconds */
+    duration: number;
 }
 /**
  * Test failure details
  */
-export declare interface TestFailure {
-  storyId: string
-  variantId: string
-  component: string
-  message: string
-  diffPath?: string
-  difference?: number
+export interface TestFailure {
+    /** Story ID */
+    storyId: string;
+    /** Variant ID */
+    variantId: string;
+    /** Component name */
+    component: string;
+    /** Error message */
+    message: string;
+    /** Path to diff image (if applicable) */
+    diffPath?: string;
+    /** Difference percentage */
+    difference?: number;
 }
 /**
  * Snapshot metadata
  */
-export declare interface SnapshotMeta {
-  storyId: string
-  variantId: string
-  component: string
-  timestamp: number
-  hash: string
+export interface SnapshotMeta {
+    /** Story ID */
+    storyId: string;
+    /** Variant ID */
+    variantId: string;
+    /** Component name */
+    component: string;
+    /** Timestamp of snapshot creation */
+    timestamp: number;
+    /** Hash of the rendered content */
+    hash: string;
 }
+/**
+ * Run visual regression tests
+ */
+export declare function runVisualTests(ctx: StoryContext, options?: TestOptions): Promise<TestResult>;
+/**
+ * Update all snapshots
+ */
+export declare function updateSnapshots(ctx: StoryContext, options?: TestOptions): Promise<number>;
+/**
+ * Format test results for console output
+ */
+export declare function formatTestResults(result: TestResult): string;
+/**
+ * Run accessibility tests on stories
+ */
+export declare function runA11yTests(ctx: StoryContext, _options?: TestOptions): Promise<TestResult>;

package/dist/story/types.d.ts

@@ -1,240 +1,342 @@
+/**
+ * STX Story - Component showcase and testing
+ * Type definitions for the story feature
+ */
 /**
  * Tree group configuration for organizing stories
  */
-export declare interface TreeGroupConfig {
-  title: string
-  id?: string
-  include?: (file: StoryTreeFile) => boolean
+export interface TreeGroupConfig {
+    /** Display title for the group */
+    title: string;
+    /** Unique identifier for the group */
+    id?: string;
+    /** Function to determine if a file belongs to this group */
+    include?: (file: StoryTreeFile) => boolean;
 }
 /**
  * Responsive viewport preset
  */
-export declare interface ResponsivePreset {
-  label: string
-  width: number
-  height?: number
+export interface ResponsivePreset {
+    /** Display label */
+    label: string;
+    /** Viewport width in pixels */
+    width: number;
+    /** Viewport height in pixels (optional) */
+    height?: number;
 }
 /**
  * Background preset for story canvas
  */
-export declare interface BackgroundPreset {
-  label: string
-  color: string
-  contrastColor?: string
+export interface BackgroundPreset {
+    /** Display label */
+    label: string;
+    /** Background color (CSS value) */
+    color: string;
+    /** Contrast color for text (optional) */
+    contrastColor?: string;
 }
 /**
  * Story theme configuration
  */
-export declare interface StoryThemeConfig {
-  title?: string
-  logo?: {
-    square?: string
-    light?: string
-    dark?: string
-  }
-  favicon?: string
-  colors?: {
-    primary?: Record<string, string>
-    gray?: Record<string, string>
-  }
-  defaultColorScheme?: 'light' | 'dark' | 'auto'
-  hideColorSchemeSwitch?: boolean
-  darkClass?: string
+export interface StoryThemeConfig {
+    /** Title displayed in the story UI */
+    title?: string;
+    /** Logo configuration */
+    logo?: {
+        /** Square logo (for favicon/small displays) */
+        square?: string;
+        /** Light theme logo */
+        light?: string;
+        /** Dark theme logo */
+        dark?: string;
+    };
+    /** Favicon path */
+    favicon?: string;
+    /** Custom colors */
+    colors?: {
+        /** Primary accent color shades */
+        primary?: Record<string, string>;
+        /** Gray color shades */
+        gray?: Record<string, string>;
+    };
+    /** Default color scheme */
+    defaultColorScheme?: 'light' | 'dark' | 'auto';
+    /** Hide the color scheme toggle */
+    hideColorSchemeSwitch?: boolean;
+    /** CSS class to apply for dark mode */
+    darkClass?: string;
 }
 /**
  * Story tree configuration
  */
-export declare interface StoryTreeConfig {
-  file?: 'title' | 'path' | ((file: StoryTreeFile) => string[])
-  order?: 'asc' | ((a: string, b: string) => number)
-  groups?: TreeGroupConfig[]
+export interface StoryTreeConfig {
+    /** How to generate tree paths from files */
+    file?: 'title' | 'path' | ((file: StoryTreeFile) => string[]);
+    /** Sort order for tree items */
+    order?: 'asc' | ((a: string, b: string) => number);
+    /** Group configurations */
+    groups?: TreeGroupConfig[];
 }
 /**
  * Story configuration (part of StxConfig)
  */
-export declare interface StoryConfig {
-  enabled?: boolean
-  outDir?: string
-  storyMatch?: string[]
-  storyIgnored?: string[]
-  tree?: StoryTreeConfig
-  theme?: StoryThemeConfig
-  responsivePresets?: ResponsivePreset[]
-  backgroundPresets?: BackgroundPreset[]
-  autoApplyContrastColor?: boolean
-  setupFile?: string
-  port?: number
-  autoPropsDisabled?: boolean
+export interface StoryConfig {
+    /** Enable the story feature */
+    enabled?: boolean;
+    /** Output directory for built story site */
+    outDir?: string;
+    /** Glob patterns to match story files */
+    storyMatch?: string[];
+    /** Glob patterns to ignore */
+    storyIgnored?: string[];
+    /** Tree organization configuration */
+    tree?: StoryTreeConfig;
+    /** Theme configuration */
+    theme?: StoryThemeConfig;
+    /** Responsive viewport presets */
+    responsivePresets?: ResponsivePreset[];
+    /** Background presets */
+    backgroundPresets?: BackgroundPreset[];
+    /** Auto-apply contrast color to text */
+    autoApplyContrastColor?: boolean;
+    /** Path to setup file for global configuration */
+    setupFile?: string;
+    /** Default server port */
+    port?: number;
+    /** Disable auto-generated props controls globally */
+    autoPropsDisabled?: boolean;
 }
 /**
  * File information for tree configuration
  */
-export declare interface StoryTreeFile {
-  title: string
-  path: string
+export interface StoryTreeFile {
+    /** Story title */
+    title: string;
+    /** File path */
+    path: string;
 }
 /**
  * Server-side story file representation
  */
-export declare interface ServerStoryFile {
-  id: string
-  path: string
-  relativePath: string
-  fileName: string
-  treePath?: string[]
-  treeFile?: StoryTreeFile
-  story?: ServerStory
+export interface ServerStoryFile {
+    /** Unique identifier */
+    id: string;
+    /** Absolute file path */
+    path: string;
+    /** Relative file path */
+    relativePath: string;
+    /** File name without extension */
+    fileName: string;
+    /** Generated tree path */
+    treePath?: string[];
+    /** Tree file data for config functions */
+    treeFile?: StoryTreeFile;
+    /** Parsed story data */
+    story?: ServerStory;
 }
+/**
+ * Story layout configuration
+ */
+export type StoryLayout = {
+    type: 'single';
+    iframe?: boolean;
+} | {
+    type: 'grid';
+    width?: number | string;
+};
 /**
  * Server-side story representation
  */
-export declare interface ServerStory {
-  id: string
-  title: string
-  group?: string
-  variants: ServerVariant[]
-  layout?: StoryLayout
-  icon?: string
-  iconColor?: string
-  docsOnly?: boolean
-  autoPropsDisabled?: boolean
+export interface ServerStory {
+    /** Unique identifier */
+    id: string;
+    /** Story title */
+    title: string;
+    /** Group this story belongs to */
+    group?: string;
+    /** Story variants */
+    variants: ServerVariant[];
+    /** Layout configuration */
+    layout?: StoryLayout;
+    /** Icon name (iconify format) */
+    icon?: string;
+    /** Icon color */
+    iconColor?: string;
+    /** Show only in docs, not in canvas */
+    docsOnly?: boolean;
+    /** Disable auto-generated props controls for this story */
+    autoPropsDisabled?: boolean;
 }
 /**
  * Server-side variant representation
  */
-export declare interface ServerVariant {
-  id: string
-  title: string
-  icon?: string
-  iconColor?: string
-  state?: Record<string, any>
-  source?: string
-  responsiveDisabled?: boolean
+export interface ServerVariant {
+    /** Unique identifier */
+    id: string;
+    /** Variant title */
+    title: string;
+    /** Icon name */
+    icon?: string;
+    /** Icon color */
+    iconColor?: string;
+    /** Initial state for controls */
+    state?: Record<string, any>;
+    /** Source code for display */
+    source?: string;
+    /** Disable responsive controls */
+    responsiveDisabled?: boolean;
 }
 /**
  * Tree leaf node (story)
  */
-export declare interface ServerTreeLeaf {
-  title: string
-  index: number
+export interface ServerTreeLeaf {
+    /** Display title */
+    title: string;
+    /** Index in story files array */
+    index: number;
 }
 /**
  * Tree folder node
  */
-export declare interface ServerTreeFolder {
-  title: string
-  children: ServerTreeNode[]
+export interface ServerTreeFolder {
+    /** Display title */
+    title: string;
+    /** Child nodes */
+    children: ServerTreeNode[];
 }
 /**
  * Tree group node
  */
-export declare interface ServerTreeGroup {
-  group: true
-  id: string
-  title: string
-  children: ServerTreeNode[]
+export interface ServerTreeGroup {
+    /** Indicates this is a group */
+    group: true;
+    /** Group identifier */
+    id: string;
+    /** Display title */
+    title: string;
+    /** Child nodes */
+    children: ServerTreeNode[];
 }
+/**
+ * Any tree node type
+ */
+export type ServerTreeNode = ServerTreeGroup | ServerTreeFolder | ServerTreeLeaf;
+/**
+ * Complete server tree
+ */
+export type ServerTree = ServerTreeNode[];
 /**
  * Analyzed component prop for story
  */
-export declare interface StoryAnalyzedProp {
-  name: string
-  type: string
-  required: boolean
-  default?: any
-  description?: string
-  options?: any[]
+export interface StoryAnalyzedProp {
+    /** Prop name */
+    name: string;
+    /** Inferred or declared type */
+    type: string;
+    /** Whether the prop is required */
+    required: boolean;
+    /** Default value if any */
+    default?: any;
+    /** Description from JSDoc */
+    description?: string;
+    /** Options for enum/select types */
+    options?: any[];
 }
 /**
  * Analyzed component slot
  */
-export declare interface AnalyzedSlot {
-  name: string
-  description?: string
+export interface AnalyzedSlot {
+    /** Slot name ('default' for main slot) */
+    name: string;
+    /** Description from comments */
+    description?: string;
 }
 /**
  * Directive usage in a component
  */
-export declare interface DirectiveUsage {
-  name: string
-  count: number
+export interface DirectiveUsage {
+    /** Directive name (e.g., 'if', 'foreach', 'component') */
+    name: string;
+    /** Number of times used */
+    count: number;
 }
 /**
  * Analyzed component metadata
  */
-export declare interface AnalyzedComponent {
-  name: string
-  path: string
-  description?: string
-  props: StoryAnalyzedProp[]
-  slots: AnalyzedSlot[]
-  dependencies: string[]
-  cssClasses: string[]
-  directives?: DirectiveUsage[]
-  category?: string
-  tags?: string[]
+export interface AnalyzedComponent {
+    /** Component name */
+    name: string;
+    /** File path */
+    path: string;
+    /** Component description */
+    description?: string;
+    /** Analyzed props */
+    props: StoryAnalyzedProp[];
+    /** Analyzed slots */
+    slots: AnalyzedSlot[];
+    /** Component dependencies (other components used) */
+    dependencies: string[];
+    /** CSS classes used (for Crosswind) */
+    cssClasses: string[];
+    /** Directives used in the component */
+    directives?: DirectiveUsage[];
+    /** Category/group */
+    category?: string;
+    /** Tags for filtering */
+    tags?: string[];
 }
+/**
+ * Control type for prop editing
+ */
+export type ControlType = 'text' | 'number' | 'boolean' | 'select' | 'radio' | 'color' | 'date' | 'json' | 'textarea' | 'slider' | 'buttongroup';
 /**
  * Control configuration
  */
-export declare interface ControlConfig {
-  type: ControlType
-  title?: string
-  options?: { value: any, label: string }[] | string[] | Record<string, string>
-  min?: number
-  max?: number
-  step?: number
+export interface ControlConfig {
+    /** Control type */
+    type: ControlType;
+    /** Display title */
+    title?: string;
+    /** Options for select/radio */
+    options?: {
+        value: any;
+        label: string;
+    }[] | string[] | Record<string, string>;
+    /** Min value for number/slider */
+    min?: number;
+    /** Max value for number/slider */
+    max?: number;
+    /** Step for number/slider */
+    step?: number;
 }
 /**
  * Story context for server operations
  */
-export declare interface StoryContext {
-  root: string
-  config: ResolvedStoryConfig
-  storyFiles: ServerStoryFile[]
-  tree?: ServerTree
-  mode: 'dev' | 'build'
+export interface StoryContext {
+    /** Root directory */
+    root: string;
+    /** Resolved configuration */
+    config: ResolvedStoryConfig;
+    /** Discovered story files */
+    storyFiles: ServerStoryFile[];
+    /** Built tree structure */
+    tree?: ServerTree;
+    /** Mode (dev or build) */
+    mode: 'dev' | 'build';
 }
 /**
  * Resolved story configuration with all defaults applied
  */
-export declare interface ResolvedStoryConfig {
-  enabled: boolean
-  outDir: string
-  storyMatch: string[]
-  storyIgnored: string[]
-  tree: Required<StoryTreeConfig>
-  theme: StoryThemeConfig
-  responsivePresets: ResponsivePreset[]
-  backgroundPresets: BackgroundPreset[]
-  autoApplyContrastColor: boolean
-  setupFile?: string
-  port: number
+export interface ResolvedStoryConfig {
+    enabled: boolean;
+    outDir: string;
+    storyMatch: string[];
+    storyIgnored: string[];
+    tree: Required<StoryTreeConfig>;
+    theme: StoryThemeConfig;
+    responsivePresets: ResponsivePreset[];
+    backgroundPresets: BackgroundPreset[];
+    autoApplyContrastColor: boolean;
+    setupFile?: string;
+    port: number;
 }
-/**
- * Story layout configuration
- */
-export type StoryLayout = | { type: 'single', iframe?: boolean }
-  | { type: 'grid', width?: number | string }
-/**
- * Any tree node type
- */
-export type ServerTreeNode = ServerTreeGroup | ServerTreeFolder | ServerTreeLeaf;
-/**
- * Complete server tree
- */
-export type ServerTree = ServerTreeNode[];
-/**
- * Control type for prop editing
- */
-export type ControlType = | 'text'
-  | 'number'
-  | 'boolean'
-  | 'select'
-  | 'radio'
-  | 'color'
-  | 'date'
-  | 'json'
-  | 'textarea'
-  | 'slider'
-  | 'buttongroup';