@stacksjs/stx 0.2.0 → 0.2.3

package/dist/story/performance.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Generate performance panel HTML
+ */
+export declare function getPerformancePanelHtml(metrics: ComponentMetrics[]): string;
+/**
+ * Generate performance panel styles
+ */
+export declare function getPerformancePanelStyles(): string;
+/**
+ * Generate performance client script
+ */
+export declare function getPerformanceScript(): string;
+/**
+ * Global profiler instance
+ */
+export declare const profiler: PerformanceProfiler;
+/**
+ * STX Story - Component Performance Profiling
+ * Track render times, re-render counts, and memory usage
+ */
+/**
+ * Performance metrics for a component
+ */
+export declare interface ComponentMetrics {
+  componentId: string
+  componentName: string
+  renderCount: number
+  totalRenderTime: number
+  avgRenderTime: number
+  minRenderTime: number
+  maxRenderTime: number
+  lastRenderTime: number
+  memoryUsage?: number
+  history: RenderRecord[]
+}
+/**
+ * Single render record
+ */
+export declare interface RenderRecord {
+  timestamp: number
+  duration: number
+  props?: Record<string, any>
+  memory?: number
+}
+/**
+ * Performance profiler
+ */
+export declare class PerformanceProfiler {
+  private metrics: any;
+  private maxHistorySize: any;
+  private enabled: any;
+  setEnabled(enabled: boolean): void;
+  recordRender(componentId: string, componentName: string, duration: number, props?: Record<string, any>): void;
+  getMetrics(componentId: string): ComponentMetrics | undefined;
+  getAllMetrics(): ComponentMetrics[];
+  getSlowestComponents(limit?: any): ComponentMetrics[];
+  getMostRenderedComponents(limit?: any): ComponentMetrics[];
+  clear(): void;
+  clearComponent(componentId: string): void;
+  private getMemoryUsage(): number | undefined;
+  exportMetrics(): string;
+  createTimer(componentId: string, componentName: string): RenderTimer;
+}
+/**
+ * Render timer helper
+ */
+export declare class RenderTimer {
+  private startTime: number;
+  private props?: Record<string, any>;
+  private profiler: PerformanceProfiler;
+  private componentId: string;
+  private componentName: string;
+  constructor(profiler: PerformanceProfiler, componentId: string, componentName: string);
+  setProps(props: Record<string, any>): this;
+  end(): number;
+}

package/dist/story/presets.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Generate presets panel HTML
+ */
+export declare function getPresetsPanelHtml(presets: PropPreset[]): string;
+/**
+ * Generate presets panel styles
+ */
+export declare function getPresetsPanelStyles(): string;
+/**
+ * Generate presets client script
+ */
+export declare function getPresetsScript(): string;
+/**
+ * Prop preset
+ */
+export declare interface PropPreset {
+  id: string
+  name: string
+  description?: string
+  props: Record<string, any>
+  componentId?: string
+  created: number
+  lastUsed?: number
+  usageCount: number
+  tags?: string[]
+}
+/**
+ * Presets storage
+ */
+export declare interface PresetsStorage {
+  version: number
+  presets: PropPreset[]
+  recentIds: string[]
+}
+/**
+ * Presets manager
+ */
+export declare class PresetsManager {
+  private storage: PresetsStorage;
+  private storagePath: string;
+  private dirty: any;
+  constructor(rootDir: string);
+  private loadStorage(): PresetsStorage;
+  private migrateStorage(data: any): PresetsStorage;
+  save(): Promise<void>;
+  createPreset(name: string, props: Record<string, any>, options?: {
+      description?: string
+      componentId?: string
+      tags?: string[]
+    }): PropPreset;
+  getPreset(id: string): PropPreset | undefined;
+  getAllPresets(): PropPreset[];
+  getPresetsForComponent(componentId: string): PropPreset[];
+  getRecentPresets(): PropPreset[];
+  usePreset(id: string): PropPreset | undefined;
+  updatePreset(id: string, updates: Partial<Omit<PropPreset, 'id' | 'created'>>): PropPreset | undefined;
+  deletePreset(id: string): boolean;
+  searchPresets(query: string): PropPreset[];
+  getMostUsedPresets(limit?: any): PropPreset[];
+  exportPresets(ids?: string[]): string;
+  importPresets(json: string, overwrite?: any): number;
+}

package/dist/story/props-validation.d.ts

@@ -0,0 +1,45 @@
+import type { StoryAnalyzedProp } from './types';
+/**
+ * Validate props against their definitions
+ */
+export declare function validateProps(props: Record<string, any>, definitions: StoryAnalyzedProp[]): ValidationResult;
+/**
+ * Generate validation script for client-side
+ */
+export declare function getValidationScript(definitions: StoryAnalyzedProp[]): string;
+/**
+ * Format validation result for display
+ */
+export declare function formatValidationResult(result: ValidationResult): string;
+/**
+ * Generate HTML for validation errors display
+ */
+export declare function generateValidationErrorsHTML(result: ValidationResult): string;
+/**
+ * Get validation panel styles
+ */
+export declare function getValidationStyles(): string;
+/**
+ * Validation result
+ */
+export declare interface ValidationResult {
+  valid: boolean
+  errors: ValidationError[]
+  warnings: ValidationWarning[]
+}
+/**
+ * Validation error
+ */
+export declare interface ValidationError {
+  prop: string
+  message: string
+  expected?: string
+  actual?: string
+}
+/**
+ * Validation warning
+ */
+export declare interface ValidationWarning {
+  prop: string
+  message: string
+}

package/dist/story/renderer.d.ts

@@ -0,0 +1,53 @@
+import type { ServerStoryFile, StoryContext } from './types';
+/**
+ * Render a story component with props
+ */
+export declare function renderStoryComponent(ctx: StoryContext, componentPath: string, options?: StoryRenderOptions): Promise<StoryRenderResult>;
+/**
+ * Render a story variant
+ */
+export declare function renderStoryVariant(ctx: StoryContext, story: ServerStoryFile, variantId: string, props?: Record<string, any>): Promise<StoryRenderResult>;
+/**
+ * Render an inline template string
+ */
+export declare function renderInlineTemplate(ctx: StoryContext, template: string, props?: Record<string, any>): Promise<StoryRenderResult>;
+/**
+ * Clear the story component cache
+ */
+export declare function clearStoryCache(): void;
+/**
+ * Get cache statistics
+ */
+export declare function getCacheStats(): { size: number, entries: string[] };
+/**
+ * Preload components into cache
+ */
+export declare function preloadComponents(paths: string[]): Promise<number>;
+/**
+ * Generate preview HTML document
+ */
+export declare function generatePreviewDocument(result: StoryRenderResult, options?: {
+    title?: string
+    theme?: 'light' | 'dark'
+    background?: string
+    crosswindCss?: string
+  }): string;
+/**
+ * Story render options
+ */
+export declare interface StoryRenderOptions {
+  props?: Record<string, any>
+  slots?: Record<string, string>
+  includeStyles?: boolean
+  includeCrosswind?: boolean
+}
+/**
+ * Story render result
+ */
+export declare interface StoryRenderResult {
+  html: string
+  css: string
+  js: string
+  errors: string[]
+  duration: number
+}

package/dist/story/search-index.d.ts

@@ -0,0 +1,47 @@
+import path from 'node:path';
+import type { AnalyzedComponent, ServerStoryFile, StoryContext } from './types';
+/**
+ * Load search index from disk
+ */
+export declare function loadSearchIndex(ctx: StoryContext): Promise<PersistedSearchIndex | null>;
+/**
+ * Save search index to disk
+ */
+export declare function saveSearchIndex(ctx: StoryContext, entries: SearchIndexEntry[]): Promise<void>;
+/**
+ * Build persisted search index from story files
+ */
+export declare function buildPersistedSearchIndex(storyFiles: ServerStoryFile[], components: Map<string, AnalyzedComponent>): SearchIndexEntry[];
+/**
+ * Check if index is stale (any file modified since index was built)
+ */
+export declare function isIndexStale(ctx: StoryContext, index: PersistedSearchIndex): Promise<boolean>;
+/**
+ * Search the index
+ */
+export declare function searchIndex(index: PersistedSearchIndex, query: string): SearchIndexEntry[];
+/**
+ * Get or build search index
+ */
+export declare function getOrBuildSearchIndex(ctx: StoryContext, storyFiles: ServerStoryFile[], components: Map<string, AnalyzedComponent>, forceRebuild?: any): Promise<SearchIndexEntry[]>;
+/**
+ * Search index entry
+ */
+export declare interface SearchIndexEntry {
+  id: string
+  name: string
+  path: string
+  searchText: string
+  props: string[]
+  tags: string[]
+  mtime: number
+}
+/**
+ * Persisted search index
+ */
+export declare interface PersistedSearchIndex {
+  version: number
+  created: number
+  updated: number
+  entries: SearchIndexEntry[]
+}

package/dist/story/search.d.ts

@@ -0,0 +1,45 @@
+import type { AnalyzedComponent, StoryContext } from './types';
+/**
+ * Build search index from story files
+ */
+export declare function buildSearchIndex(ctx: StoryContext): void;
+/**
+ * Build search index from analyzed components
+ */
+export declare function buildComponentSearchIndex(components: AnalyzedComponent[]): void;
+/**
+ * Search the index
+ */
+export declare function search(query: string, limit?: any): SearchResult[];
+/**
+ * Get recent searches from localStorage (client-side)
+ */
+export declare function getRecentSearches(): string[];
+/**
+ * Clear the search index
+ */
+export declare function clearSearchIndex(): void;
+/**
+ * Get search index size
+ */
+export declare function getSearchIndexSize(): number;
+/**
+ * Generate search index JSON for static builds
+ */
+export declare function exportSearchIndex(): string;
+/**
+ * Import search index from JSON
+ */
+export declare function importSearchIndex(json: string): void;
+/**
+ * Search result item
+ */
+export declare interface SearchResult {
+  type: 'story' | 'component' | 'prop' | 'slot'
+  title: string
+  description?: string
+  storyId: string
+  variantId?: string
+  score: number
+  match: string
+}

package/dist/story/server.d.ts

@@ -0,0 +1,21 @@
+import type { StoryContext } from './types';
+/**
+ * Create and start the story server
+ */
+export declare function createStoryServer(ctx: StoryContext, options: ServerOptions): Promise<StoryServer>;
+/**
+ * Server options
+ */
+export declare interface ServerOptions {
+  port: number
+  open?: boolean
+  host?: string | boolean
+}
+/**
+ * Story server instance
+ */
+export declare interface StoryServer {
+  server: ReturnType<typeof Bun.serve>
+  url: string
+  close: () => Promise<void>
+}

package/dist/story/setup.d.ts

@@ -0,0 +1,47 @@
+import type { StoryContext } from './types';
+/**
+ * Load and execute the setup file
+ */
+export declare function loadSetupFile(ctx: StoryContext): Promise<void>;
+/**
+ * Get all registered global components
+ */
+export declare function getGlobalComponents(): Map<string, any>;
+/**
+ * Get all global CSS
+ */
+export declare function getGlobalCSS(): string;
+/**
+ * Get all global scripts
+ */
+export declare function getGlobalScripts(): string;
+/**
+ * Get global state
+ */
+export declare function getGlobalState(): Map<string, any>;
+/**
+ * Get a specific global state value
+ */
+export declare function getState<T = any>(key: string): T | undefined;
+/**
+ * Reset all global setup (for testing)
+ */
+export declare function resetSetup(): void;
+/**
+ * Generate HTML for global setup (CSS + scripts)
+ */
+export declare function getSetupHTML(): string;
+/**
+ * Context passed to setup function
+ */
+export declare interface SetupContext {
+  storyContext: StoryContext
+  registerComponent: (name: string, component: any) => void
+  addCSS: (css: string) => void
+  addScript: (script: string) => void
+  setState: (key: string, value: any) => void
+}
+/**
+ * Setup function signature
+ */
+export type SetupFunction = (ctx: SetupContext) => void | Promise<void>

package/dist/story/snapshots.d.ts

@@ -0,0 +1,65 @@
+import type { StoryContext } from './types';
+/**
+ * Get snapshot directory
+ */
+export declare function getSnapshotDir(ctx: StoryContext): string;
+/**
+ * Load snapshot versions
+ */
+export declare function loadSnapshotVersions(ctx: StoryContext, storyId: string): Promise<VersionedSnapshot | null>;
+/**
+ * Save snapshot version
+ */
+export declare function saveSnapshotVersion(ctx: StoryContext, storyId: string, description?: string): Promise<SnapshotVersion>;
+/**
+ * Restore snapshot to a previous version
+ */
+export declare function restoreSnapshotVersion(ctx: StoryContext, storyId: string, version: number): Promise<boolean>;
+/**
+ * Generate diff between two HTML snapshots
+ * Returns a simple text-based diff (for actual image diff, you'd need canvas/image processing)
+ */
+export declare function generateTextDiff(oldHtml: string, newHtml: string): DiffResult;
+/**
+ * Generate visual diff HTML
+ */
+export declare function generateDiffHTML(oldHtml: string, newHtml: string): string;
+/**
+ * Get diff styles
+ */
+export declare function getDiffStyles(): string;
+/**
+ * List all snapshot versions for a story
+ */
+export declare function listSnapshotVersions(ctx: StoryContext, storyId: string): Promise<SnapshotVersion[]>;
+/**
+ * Delete old snapshot versions
+ */
+export declare function pruneSnapshotVersions(ctx: StoryContext, storyId: string, keepCount?: number): Promise<number>;
+/**
+ * Snapshot version info
+ */
+export declare interface SnapshotVersion {
+  version: number
+  timestamp: number
+  commit?: string
+  description?: string
+}
+/**
+ * Snapshot with version history
+ */
+export declare interface VersionedSnapshot {
+  current: SnapshotVersion
+  history: SnapshotVersion[]
+  maxVersions: number
+}
+/**
+ * Diff result
+ */
+export declare interface DiffResult {
+  hasDiff: boolean
+  percentage: number
+  diffImagePath?: string
+  changedPixels: number
+  totalPixels: number
+}

package/dist/story/testing.d.ts

@@ -0,0 +1,58 @@
+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
+ */
+export declare function runA11yTests(ctx: StoryContext, _options?: TestOptions): Promise<TestResult>;
+/**
+ * Test options
+ */
+export declare interface TestOptions {
+  update?: boolean
+  filter?: string[]
+  threshold?: number
+  snapshotDir?: string
+}
+/**
+ * Test result
+ */
+export declare interface TestResult {
+  total: number
+  passed: number
+  failed: number
+  new: number
+  failures: TestFailure[]
+  duration: number
+}
+/**
+ * Test failure details
+ */
+export declare interface TestFailure {
+  storyId: string
+  variantId: string
+  component: string
+  message: string
+  diffPath?: string
+  difference?: number
+}
+/**
+ * Snapshot metadata
+ */
+export declare interface SnapshotMeta {
+  storyId: string
+  variantId: string
+  component: string
+  timestamp: number
+  hash: string
+}

package/dist/story/theme.d.ts

@@ -0,0 +1,68 @@
+import type { StoryContext } from './types';
+/**
+ * Get current theme
+ */
+export declare function getCurrentTheme(): ThemeConfig;
+/**
+ * Check if dark mode is active
+ */
+export declare function isDark(): boolean;
+/**
+ * Toggle dark mode
+ */
+export declare function toggleDarkMode(): void;
+/**
+ * Set theme
+ */
+export declare function setTheme(theme: Partial<ThemeConfig>): void;
+/**
+ * Initialize theme from context
+ */
+export declare function initializeTheme(ctx: StoryContext): void;
+/**
+ * Generate CSS variables from theme
+ */
+export declare function generateThemeCSS(theme?: ThemeConfig): string;
+/**
+ * Generate theme toggle button HTML
+ */
+export declare function generateThemeToggle(): string;
+/**
+ * Get theme toggle script
+ */
+export declare function getThemeToggleScript(): string;
+/**
+ * Export theme tokens to JSON
+ */
+export declare function exportThemeTokensJSON(theme?: ThemeConfig): string;
+/**
+ * Export theme tokens to CSS custom properties
+ */
+export declare function exportThemeTokensCSS(theme?: ThemeConfig): string;
+/**
+ * Get theme styles
+ */
+export declare function getThemeStyles(): string;
+/**
+ * Default light theme
+ */
+export declare const lightTheme: ThemeConfig;
+/**
+ * Default dark theme
+ */
+export declare const darkTheme: ThemeConfig;
+/**
+ * Theme configuration
+ */
+export declare interface ThemeConfig {
+  colorScheme: 'light' | 'dark' | 'auto'
+  primaryColor: string
+  backgroundColor: string
+  textColor: string
+  borderColor: string
+  secondaryBackground: string
+  secondaryText: string
+  fontFamily: string
+  codeFontFamily: string
+  borderRadius: string
+}