@stacksjs/stx/dist/story/types.d.ts

A performant UI Framework. Powered by Bun.

/**
 * 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
}
/**
 * Responsive viewport preset
 */
export declare interface ResponsivePreset {
  label: string
  width: number
  height?: number
}
/**
 * Background preset for story canvas
 */
export declare interface BackgroundPreset {
  label: string
  color: string
  contrastColor?: string
}
/**
 * Story theme configuration
 */
export declare interface StoryThemeConfig {
  title?: string
  logo?: {
    /** Square logo (for favicon/small displays) */
    square?: string
    /** Light theme logo */
    light?: string
    /** Dark theme logo */
    dark?: string
  }
  favicon?: string
  colors?: {
    /** Primary accent color shades */
    primary?: Record<string, string>
    /** Gray color shades */
    gray?: Record<string, string>
  }
  defaultColorScheme?: 'light' | 'dark' | 'auto'
  hideColorSchemeSwitch?: boolean
  darkClass?: string
}
/**
 * Story tree configuration
 */
export declare interface StoryTreeConfig {
  file?: 'title' | 'path' | ((file: StoryTreeFile) => string[])
  order?: 'asc' | ((a: string, b: string) => number)
  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
}
/**
 * File information for tree configuration
 */
export declare interface StoryTreeFile {
  title: string
  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
}
/**
 * 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
}
/**
 * Server-side variant representation
 */
export declare interface ServerVariant {
  id: string
  title: string
  icon?: string
  iconColor?: string
  state?: Record<string, any>
  source?: string
  responsiveDisabled?: boolean
}
/**
 * Tree leaf node (story)
 */
export declare interface ServerTreeLeaf {
  title: string
  index: number
}
/**
 * Tree folder node
 */
export declare interface ServerTreeFolder {
  title: string
  children: ServerTreeNode[]
}
/**
 * Tree group node
 */
export declare interface ServerTreeGroup {
  group: true
  id: string
  title: string
  children: ServerTreeNode[]
}
/**
 * Analyzed component prop for story
 */
export declare interface StoryAnalyzedProp {
  name: string
  type: string
  required: boolean
  default?: any
  description?: string
  options?: any[]
}
/**
 * Analyzed component slot
 */
export declare interface AnalyzedSlot {
  name: string
  description?: string
}
/**
 * Directive usage in a component
 */
export declare interface DirectiveUsage {
  name: string
  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[]
}
/**
 * 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
}
/**
 * Story context for server operations
 */
export declare interface StoryContext {
  root: string
  config: ResolvedStoryConfig
  storyFiles: ServerStoryFile[]
  tree?: ServerTree
  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
}
/**
 * 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'