@stacksjs/stx 0.1.16 → 0.2.3

package/dist/story/desktop-preview.d.ts

@@ -0,0 +1,34 @@
+import type { ServerStoryFile, StoryContext } from './types';
+/**
+ * Check if desktop preview is available
+ */
+export declare function isDesktopPreviewAvailable(): Promise<boolean>;
+/**
+ * Open a story in a native desktop window
+ */
+export declare function openDesktopPreview(ctx: StoryContext, story: ServerStoryFile, variantId: string, options?: DesktopPreviewOptions): Promise<DesktopPreviewInstance | null>;
+/**
+ * Get desktop preview button HTML
+ */
+export declare function getDesktopPreviewButton(storyId: string, variantId: string): string;
+/**
+ * Get desktop preview styles
+ */
+export declare function getDesktopPreviewStyles(): string;
+/**
+ * Desktop preview options
+ */
+export declare interface DesktopPreviewOptions {
+  width?: number
+  height?: number
+  title?: string
+  devTools?: boolean
+}
+/**
+ * Desktop preview instance
+ */
+export declare interface DesktopPreviewInstance {
+  close: () => void
+  reload: () => void
+  update: (html: string) => void
+}

package/dist/story/docs-generator.d.ts

@@ -0,0 +1,30 @@
+import type { AnalyzedComponent, ServerStoryFile, StoryContext } from './types';
+/**
+ * Generate documentation for all components
+ */
+export declare function generateStoryDocs(ctx: StoryContext, components: AnalyzedComponent[], options?: DocsOptions): Promise<void>;
+/**
+ * Generate documentation index
+ */
+export declare function generateDocsIndex(components: AnalyzedComponent[]): string;
+/**
+ * Generate documentation for a single component
+ */
+export declare function generateComponentDocs(component: AnalyzedComponent, storyFile?: ServerStoryFile, options?: DocsOptions): string;
+/**
+ * Generate JSON catalog of all components
+ */
+export declare function generateComponentCatalog(components: AnalyzedComponent[]): string;
+/**
+ * Export design tokens from components
+ */
+export declare function exportDesignTokens(components: AnalyzedComponent[]): Record<string, any>;
+/**
+ * Documentation options
+ */
+export declare interface DocsOptions {
+  outDir?: string
+  includeStories?: boolean
+  includeSource?: boolean
+  template?: string
+}

package/dist/story/errors.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Create a story error
+ */
+export declare function createStoryError(type: StoryErrorType, message: string, details?: Partial<StoryError>): StoryError;
+/**
+ * Format error for display
+ */
+export declare function formatStoryError(error: StoryError): string;
+/**
+ * Generate error display HTML
+ */
+export declare function generateErrorHTML(error: StoryError): string;
+/**
+ * Get error styles
+ */
+export declare function getErrorStyles(): string;
+/**
+ * Create error boundary wrapper
+ */
+export declare function createErrorBoundary(content: string, componentName: string): string;
+/**
+ * Story error
+ */
+export declare interface StoryError {
+  type: StoryErrorType
+  message: string
+  file?: string
+  line?: number
+  column?: number
+  stack?: string
+  suggestions?: string[]
+}
+/**
+ * STX Story - Error Handling
+ * Graceful error display and recovery suggestions
+ */
+/**
+ * Story error types
+ */
+export type StoryErrorType = | 'parse_error'
+  | 'component_error'
+  | 'render_error'
+  | 'config_error'
+  | 'file_not_found'
+  | 'circular_dependency'
+  | 'prop_type_error'
+  | 'unknown'

package/dist/story/figma-export.d.ts

@@ -0,0 +1,169 @@
+import type { AnalyzedComponent } from './types';
+/**
+ * Export components to Figma format
+ */
+export declare function exportToFigma(components: AnalyzedComponent[], options?: FigmaExportOptions): FigmaDocument;
+/**
+ * Export to Figma JSON file
+ */
+export declare function exportToFigmaFile(components: AnalyzedComponent[], outputPath: string, options?: FigmaExportOptions): Promise<void>;
+/**
+ * Convert CSS color to Figma color
+ */
+export declare function cssColorToFigma(cssColor: string): FigmaColor;
+/**
+ * Convert Figma color to CSS
+ */
+export declare function figmaColorToCss(color: FigmaColor): string;
+/**
+ * Generate Figma plugin manifest
+ */
+export declare function generateFigmaPluginManifest(name: string): object;
+/**
+ * Generate Figma import code snippet
+ */
+export declare function generateFigmaImportCode(components: AnalyzedComponent[]): string;
+/**
+ * Figma color
+ */
+export declare interface FigmaColor {
+  r: number
+  g: number
+  b: number
+  a: number
+}
+/**
+ * Figma paint (fill/stroke)
+ */
+export declare interface FigmaPaint {
+  type: 'SOLID' | 'GRADIENT_LINEAR' | 'GRADIENT_RADIAL' | 'IMAGE'
+  color?: FigmaColor
+  opacity?: number
+}
+/**
+ * Figma text style
+ */
+export declare interface FigmaTextStyle {
+  fontFamily: string
+  fontWeight: number
+  fontSize: number
+  lineHeight?: { value: number, unit: 'PIXELS' | 'PERCENT' | 'AUTO' }
+  letterSpacing?: { value: number, unit: 'PIXELS' | 'PERCENT' }
+  textAlign?: 'LEFT' | 'CENTER' | 'RIGHT' | 'JUSTIFIED'
+}
+/**
+ * Figma node base
+ */
+export declare interface FigmaNodeBase {
+  id: string
+  name: string
+  type: FigmaNodeType
+  visible?: boolean
+  locked?: boolean
+}
+/**
+ * Figma frame node
+ */
+export declare interface FigmaFrameNode extends FigmaNodeBase {
+  type: 'FRAME' | 'COMPONENT' | 'COMPONENT_SET'
+  children: FigmaNode[]
+  absoluteBoundingBox?: { x: number, y: number, width: number, height: number }
+  constraints?: { horizontal: string, vertical: string }
+  fills?: FigmaPaint[]
+  strokes?: FigmaPaint[]
+  strokeWeight?: number
+  cornerRadius?: number
+  paddingLeft?: number
+  paddingRight?: number
+  paddingTop?: number
+  paddingBottom?: number
+  itemSpacing?: number
+  layoutMode?: 'NONE' | 'HORIZONTAL' | 'VERTICAL'
+  primaryAxisAlignItems?: 'MIN' | 'CENTER' | 'MAX' | 'SPACE_BETWEEN'
+  counterAxisAlignItems?: 'MIN' | 'CENTER' | 'MAX'
+}
+/**
+ * Figma text node
+ */
+export declare interface FigmaTextNode extends FigmaNodeBase {
+  type: 'TEXT'
+  characters: string
+  style?: FigmaTextStyle
+  fills?: FigmaPaint[]
+}
+/**
+ * Figma rectangle node
+ */
+export declare interface FigmaRectangleNode extends FigmaNodeBase {
+  type: 'RECTANGLE'
+  absoluteBoundingBox?: { x: number, y: number, width: number, height: number }
+  fills?: FigmaPaint[]
+  strokes?: FigmaPaint[]
+  strokeWeight?: number
+  cornerRadius?: number
+}
+/**
+ * Figma document
+ */
+export declare interface FigmaDocument {
+  name: string
+  lastModified: string
+  version: string
+  document: {
+    id: string
+    name: string
+    type: 'DOCUMENT'
+    children: FigmaNode[]
+  }
+  components: Record<string, FigmaComponentMeta>
+  styles: Record<string, FigmaStyleMeta>
+}
+/**
+ * Figma component metadata
+ */
+export declare interface FigmaComponentMeta {
+  key: string
+  name: string
+  description: string
+}
+/**
+ * Figma style metadata
+ */
+export declare interface FigmaStyleMeta {
+  key: string
+  name: string
+  styleType: 'FILL' | 'TEXT' | 'EFFECT' | 'GRID'
+}
+/**
+ * Export options
+ */
+export declare interface FigmaExportOptions {
+  includeVariants?: boolean
+  includeProps?: boolean
+  frameWidth?: number
+  frameHeight?: number
+  componentSpacing?: number
+}
+/**
+ * Figma node types
+ */
+export type FigmaNodeType = | 'DOCUMENT'
+  | 'CANVAS'
+  | 'FRAME'
+  | 'GROUP'
+  | 'VECTOR'
+  | 'BOOLEAN_OPERATION'
+  | 'STAR'
+  | 'LINE'
+  | 'ELLIPSE'
+  | 'REGULAR_POLYGON'
+  | 'RECTANGLE'
+  | 'TEXT'
+  | 'SLICE'
+  | 'COMPONENT'
+  | 'COMPONENT_SET'
+  | 'INSTANCE'
+/**
+ * Union of all Figma node types
+ */
+export type FigmaNode = FigmaFrameNode | FigmaTextNode | FigmaRectangleNode | FigmaNodeBase

package/dist/story/generator.d.ts

@@ -0,0 +1,21 @@
+import type { AnalyzedComponent, ControlConfig, ServerStory, StoryAnalyzedProp } from './types';
+/**
+ * Generate a story from analyzed component metadata
+ */
+export declare function generateAutoStory(component: AnalyzedComponent): ServerStory;
+/**
+ * Infer control configuration from a prop
+ */
+export declare function inferControl(prop: StoryAnalyzedProp): ControlConfig;
+/**
+ * Generate controls for all props
+ */
+export declare function generateControls(props: StoryAnalyzedProp[]): ControlConfig[];
+/**
+ * Generate story source code from component and state
+ */
+export declare function generateStorySource(componentName: string, state: Record<string, any>): string;
+/**
+ * Generate a complete story file content
+ */
+export declare function generateStoryFileContent(component: AnalyzedComponent): string;

package/dist/story/hmr.d.ts

@@ -0,0 +1,64 @@
+import type { ServerWebSocket } from 'bun';
+export declare function createHmrHandler(): HmrWebSocketHandler;
+/**
+ * Broadcast a message to all connected clients
+ */
+export declare function broadcast(message: HmrMessage): void;
+/**
+ * Notify clients of a story update
+ */
+export declare function notifyStoryUpdate(storyId: string, data?: any): void;
+/**
+ * Notify clients of a new story
+ */
+export declare function notifyStoryAdd(storyId: string, data?: any): void;
+/**
+ * Notify clients of a removed story
+ */
+export declare function notifyStoryRemove(storyId: string): void;
+/**
+ * Notify clients of a config change
+ */
+export declare function notifyConfigChange(): void;
+/**
+ * Notify clients to do a full reload
+ */
+export declare function notifyFullReload(): void;
+/**
+ * Notify clients of an error
+ */
+export declare function notifyError(error: string): void;
+/**
+ * Get the number of connected clients
+ */
+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

@@ -0,0 +1,35 @@
+/**
+ * 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
+ */
+/**
+ * Hot swap state
+ */
+export declare interface HotSwapState {
+  storyId: string | null
+  variantId: string | null
+  props: Record<string, any>
+  iframe: HTMLIFrameElement | null
+}
+/**
+ * Hot swap options
+ */
+export declare interface HotSwapOptions {
+  animationDuration?: number
+  preserveScroll?: boolean
+  onBeforeSwap?: (state: HotSwapState) => void
+  onAfterSwap?: (state: HotSwapState) => void
+}

package/dist/story/index.d.ts

@@ -0,0 +1,51 @@
+export type { CreateContextOptions } from './context';
+export type { ServerOptions, StoryServer } from './server';
+export * from './addons';
+export * from './analytics';
+export * from './auto-stories';
+export * from './bookmarks';
+export * from './bun-test';
+export * from './cli';
+export * from './collect';
+export * from './commands';
+export * from './compiled-output';
+export * from './composition';
+export {
+  defaultBackgroundPresets,
+  defaultResponsivePresets,
+  defaultStoryConfig,
+  getDefaultStoryConfig,
+  resolveStoryConfig,
+} from './config';
+export * from './config-watcher';
+export {
+  createContext,
+  updateContextStoryFiles,
+  updateContextTree,
+} from './context';
+export * from './controls';
+export * from './desktop-preview';
+export * from './docs-generator';
+export * from './errors';
+export * from './figma-export';
+export * from './generator';
+export * from './crosswind';
+export * from './hmr';
+export * from './hot-swap';
+export * from './interactions';
+export * from './keyboard-shortcuts';
+export * from './output';
+export * from './performance';
+export * from './presets';
+export * from './props-validation';
+export * from './renderer';
+export * from './search';
+export * from './search-index';
+export { createStoryServer } from './server';
+export * from './setup';
+export * from './snapshots';
+export * from './testing';
+export * from './theme';
+export * from './types';
+export * from './ui';
+export * from './visual-testing';

package/dist/story/interactions.d.ts

@@ -0,0 +1,52 @@
+import type { ServerStoryFile, StoryContext } from './types';
+/**
+ * Parse @interaction blocks from story content
+ */
+export declare function parseInteractionBlocks(content: string): InteractionTest[];
+/**
+ * Run interaction tests for a story
+ */
+export declare function runInteractionTests(_ctx: StoryContext, story: ServerStoryFile, tests: InteractionTest[]): Promise<InteractionTestResult[]>;
+/**
+ * Generate interaction test helpers script (for browser)
+ */
+export declare function getInteractionHelpersScript(): string;
+/**
+ * Format interaction test results
+ */
+export declare function formatInteractionResults(results: InteractionTestResult[]): string;
+/**
+ * Interaction step
+ */
+export declare interface InteractionStep {
+  action: 'click' | 'type' | 'select' | 'hover' | 'focus' | 'blur' | 'wait' | 'assert'
+  selector?: string
+  value?: string
+  duration?: number
+  assertion?: {
+    type: 'text' | 'value' | 'visible' | 'hidden' | 'class' | 'attribute'
+    expected: any
+    attribute?: string
+  }
+}
+/**
+ * Interaction test definition
+ */
+export declare interface InteractionTest {
+  name: string
+  storyId: string
+  variantId: string
+  steps: InteractionStep[]
+  setup?: () => Promise<void>
+  teardown?: () => Promise<void>
+}
+/**
+ * Interaction test result
+ */
+export declare interface InteractionTestResult {
+  name: string
+  passed: boolean
+  error?: string
+  duration: number
+  failedStep?: number
+}

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

@@ -0,0 +1,34 @@
+/**
+ * Format shortcut key for display
+ */
+export declare function formatShortcutKey(shortcut: KeyboardShortcut): string;
+/**
+ * Generate keyboard shortcuts modal HTML
+ */
+export declare function getShortcutsModalHtml(shortcuts?: KeyboardShortcut[]): string;
+/**
+ * Generate keyboard shortcuts styles
+ */
+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
+}

package/dist/story/output.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Apply color to text
+ */
+export declare function color(text: string, colorName: keyof typeof colors): string;
+/**
+ * Apply style to text
+ */
+export declare function style(text: string, styleName: keyof typeof styles): string;
+/**
+ * Print the STX Story banner
+ */
+export declare function printBanner(): void;
+/**
+ * Print server URLs
+ */
+export declare function printServerUrls(url: string, networkUrl?: string): void;
+/**
+ * Print story count
+ */
+export declare function printStoryCount(count: number): void;
+/**
+ * Print file change event
+ */
+export declare function printFileChange(event: string, file: string): void;
+/**
+ * Print error message
+ */
+export declare function printError(message: string, details?: string): void;
+/**
+ * Print warning message
+ */
+export declare function printWarning(message: string): void;
+/**
+ * Print success message
+ */
+export declare function printSuccess(message: string): void;
+/**
+ * Print info message
+ */
+export declare function printInfo(message: string): void;
+/**
+ * Print build summary
+ */
+export declare function printBuildSummary(storyCount: number, outDir: string, duration: number): void;
+/**
+ * Print test summary
+ */
+export declare function printTestSummary(total: number, passed: number, failed: number, duration: number): void;
+/**
+ * Print keyboard shortcuts help
+ */
+export declare function printHelp(): void;
+/**
+ * Clear the console
+ */
+export declare function clearConsole(): void;
+/**
+ * Create a spinner
+ */
+export declare function createSpinner(text: string): {
+  start: () => void
+  stop: (success?: boolean) => void
+  update: (newText: string) => void
+};
+/**
+ * Format duration in human-readable format
+ */
+export declare function formatDuration(ms: number): string;
+/**
+ * Format file size in human-readable format
+ */
+export declare function formatSize(bytes: number): string;
+// Convenience functions
+export declare const red: (text: string) => string;
+export declare const green: (text: string) => string;
+export declare const yellow: (text: string) => string;
+export declare const blue: (text: string) => string;
+export declare const magenta: (text: string) => string;
+export declare const cyan: (text: string) => string;
+export declare const white: (text: string) => string;
+export declare const gray: (text: string) => string;
+export declare const bold: (text: string) => string;
+export declare const dim: (text: string) => string;
+export declare const italic: (text: string) => string;
+export declare const underline: (text: string) => string;