@stacksjs/stx 0.2.0 → 0.2.3

package/dist/story/types.d.ts

@@ -0,0 +1,249 @@
+/**
+ * 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'

package/dist/story/ui/code-panel.d.ts

@@ -0,0 +1,42 @@
+import type { AnalyzedComponent, ServerStoryFile } from '../types';
+/**
+ * Generate code panel HTML
+ */
+export declare function generateCodePanel(story: ServerStoryFile, component: AnalyzedComponent | null, activeTab?: CodePanelTab): string;
+/**
+ * Get source code for a component
+ */
+export declare function getComponentSource(filePath: string): Promise<string>;
+/**
+ * Get story code with current props
+ */
+export declare function getStoryCode(componentName: string, props: Record<string, any>): string;
+/**
+ * Get props as JSON
+ */
+export declare function getPropsJson(props: Record<string, any>): string;
+/**
+ * Apply syntax highlighting to code
+ * Uses simple regex-based highlighting without external deps
+ */
+export declare function highlightCode(code: string, language: string): string;
+/**
+ * Get syntax highlighting styles
+ */
+export declare function getHighlightStyles(): string;
+/**
+ * Get code panel styles
+ */
+export declare function getCodePanelStyles(): string;
+/**
+ * Copy code to clipboard (client-side)
+ */
+export declare function getCopyCodeScript(): string;
+/**
+ * Open in VS Code (client-side)
+ */
+export declare function getOpenInVSCodeScript(filePath: string): string;
+/**
+ * Code panel tabs
+ */
+export type CodePanelTab = 'source' | 'story' | 'compiled' | 'props'

package/dist/story/ui/controls-panel.d.ts

@@ -0,0 +1,25 @@
+import type { AnalyzedComponent } from '../types';
+/**
+ * Create initial controls panel state
+ */
+export declare function createControlsPanelState(component: AnalyzedComponent | null): ControlsPanelState;
+/**
+ * Generate controls panel HTML
+ */
+export declare function generateControlsPanel(component: AnalyzedComponent | null, state: ControlsPanelState): string;
+/**
+ * Generate auto props disabled message
+ */
+export declare function generateAutoPropsDisabled(): string;
+/**
+ * Get controls panel styles
+ */
+export declare function getControlsPanelStyles(): string;
+/**
+ * Controls panel state
+ */
+export declare interface ControlsPanelState {
+  collapsed: boolean
+  values: Record<string, any>
+  filter: string
+}

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

@@ -0,0 +1,4 @@
+export * from './code-panel';
+export * from './controls-panel';
+export * from './navigation';
+export * from './preview';

package/dist/story/ui/navigation.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Create initial navigation state
+ */
+export declare function createNavigationState(): NavigationState;
+/**
+ * Parse hash from URL for routing
+ */
+export declare function parseHash(hash: string): { storyId: string | null, variantId: string | null };
+/**
+ * Generate hash for URL
+ */
+export declare function generateHash(storyId: string | null, variantId: string | null): string;
+/**
+ * Add story to recent list
+ */
+export declare function addToRecent(state: NavigationState, storyId: string): void;
+/**
+ * Get keyboard navigation script
+ */
+export declare function getKeyboardNavigationScript(): string;
+/**
+ * Get navigation styles
+ */
+export declare function getNavigationStyles(): string;
+/**
+ * Generate recent stories list HTML
+ */
+export declare function generateRecentList(recentStories: string[], storyMap: Map<string, string>): string;
+/**
+ * State persistence helpers
+ */
+export declare function saveNavigationState(state: NavigationState): void;
+/**
+ * Load navigation state from storage
+ */
+export declare function loadNavigationState(): Partial<NavigationState>;
+/**
+ * Get state persistence script
+ */
+export declare function getStatePersistenceScript(): string;
+/**
+ * STX Story - Navigation
+ * Keyboard navigation, hash routing, and recent components
+ */
+/**
+ * Navigation state
+ */
+export declare interface NavigationState {
+  selectedStoryId: string | null
+  selectedVariantId: string | null
+  recentStories: string[]
+  maxRecent: number
+  searchQuery: string
+  focusedIndex: number
+}

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

@@ -0,0 +1,46 @@
+import type { ResponsivePreset, ServerStoryFile, StoryContext } from '../types';
+/**
+ * Create initial preview state
+ */
+export declare function createPreviewState(): PreviewState;
+/**
+ * Generate iframe HTML for component preview
+ */
+export declare function generatePreviewIframe(story: ServerStoryFile, variantId: string, state: PreviewState, ctx: StoryContext): string;
+/**
+ * Generate viewport selector HTML
+ */
+export declare function generateViewportSelector(presets: ResponsivePreset[], currentWidth: number | null): string;
+/**
+ * Generate zoom controls HTML
+ */
+export declare function generateZoomControls(currentZoom: number): string;
+/**
+ * Generate background selector HTML
+ */
+export declare function generateBackgroundSelector(presets: { label: string, color: string }[], currentColor: string): string;
+/**
+ * Generate toolbar overlay buttons
+ */
+export declare function generateOverlayButtons(state: PreviewState): string;
+/**
+ * Generate side-by-side comparison view
+ */
+export declare function generateComparisonView(story: ServerStoryFile, variantId1: string, variantId2: string, ctx: StoryContext): string;
+/**
+ * Get preview styles
+ */
+export declare function getPreviewStyles(): string;
+/**
+ * Preview state
+ */
+export declare interface PreviewState {
+  viewportWidth: number | null
+  viewportHeight: number | null
+  zoom: number
+  background: string
+  showGrid: boolean
+  showRuler: boolean
+  showOutline: boolean
+  props: Record<string, any>
+}

package/dist/story/visual-testing.d.ts

@@ -0,0 +1,45 @@
+import type { StoryContext } from './types';
+/**
+ * Run visual regression tests
+ */
+export declare function runScreenshotTests(ctx: StoryContext, options?: VisualTestOptions): Promise<VisualTestResult>;
+/**
+ * Generate visual test report HTML
+ */
+export declare function generateVisualTestReport(result: VisualTestResult): string;
+/**
+ * Visual test options
+ */
+export declare interface VisualTestOptions {
+  update?: boolean
+  threshold?: number
+  snapshotDir?: string
+  width?: number
+  height?: number
+  deviceScaleFactor?: number
+  filter?: string[]
+}
+/**
+ * Visual test result
+ */
+export declare interface VisualTestResult {
+  total: number
+  passed: number
+  failed: number
+  new: number
+  failures: VisualTestFailure[]
+  duration: number
+}
+/**
+ * Visual test failure
+ */
+export declare interface VisualTestFailure {
+  storyId: string
+  variantId: string
+  component: string
+  message: string
+  baselinePath?: string
+  actualPath?: string
+  diffPath?: string
+  diffPercentage?: number
+}

package/dist/streaming.d.ts

@@ -1,11 +1,27 @@
 import type { CustomDirective, StreamRenderer, StxOptions } from './types';
 /**
- * Stream a template with data
+ * Stream a template with data using chunked transfer encoding.
+ *
+ * This implements actual progressive streaming by:
+ * 1. Sending the shell (content before suspense) immediately
+ * 2. Processing suspense boundaries in parallel
+ * 3. Streaming each resolved suspense content as it completes
+ * 4. Using out-of-order streaming with client-side reordering
+ *
  * @param templatePath Path to the template
  * @param data Data to render with the template
  * @param options stx options
  */
 export declare function streamTemplate(templatePath: string, data?: Record<string, any>, options?: StxOptions): Promise<ReadableStream<string>>;
+/**
+ * Stream a template with data (simple version without suspense).
+ * Returns full content in chunks based on buffer size.
+ *
+ * @param templatePath Path to the template
+ * @param data Data to render with the template
+ * @param options stx options
+ */
+export declare function streamTemplateSimple(templatePath: string, data?: Record<string, any>, options?: StxOptions): Promise<ReadableStream<string>>;
 /**
  * Create a stream renderer for progressive loading
  * @param templatePath Path to the template
@@ -24,7 +40,71 @@ export declare function registerStreamingDirectives(options?: StxOptions): Custo
  * @param _options stx options
  */
 export declare function processSectionDirectives(content: string, context: Record<string, any>, filePath: string, _options?: StxOptions): Promise<string>;
+/**
+ * Wrap a ReadableStream<string> in a proper Response with chunked transfer encoding headers.
+ *
+ * Makes it trivial to use streaming from a Bun server handler:
+ *
+ * @example
+ * ```typescript
+ * const server = Bun.serve({
+ *   async fetch(req) {
+ *     const stream = await streamTemplate('index.stx', { title: 'Home' })
+ *     return streamToResponse(stream)
+ *   }
+ * })
+ * ```
+ *
+ * @param stream - The template ReadableStream
+ * @param init - Optional additional ResponseInit (headers, status, etc.)
+ * @returns A Response with proper streaming headers
+ */
+export declare function streamToResponse(stream: ReadableStream<string>, init?: ResponseInit): Response;
+/**
+ * Generate client-side hydration runtime script.
+ *
+ * This script handles:
+ * - Finding islands in the DOM
+ * - Loading island components based on priority
+ * - Hydrating islands with their props
+ *
+ * Usage: Include the generated script in your page, then call
+ * `window.__stx.hydrate()` when ready.
+ *
+ * @example
+ * ```html
+ * <script>
+ *   {{ generateHydrationRuntime({ mode: 'full' }) }}
+ * </script>
+ * ```
+ */
+export declare function generateHydrationRuntime(config?: HydrationRuntimeConfig): string;
+/**
+ * Custom directive for marking suspense boundaries in streaming templates.
+ *
+ * Usage:
+ * ```html
+ * @suspense('heavy-content')
+ *   <div>This content will stream after the shell</div>
+ * @endsuspense
+ * ```
+ *
+ * The content inside suspense boundaries will be:
+ * 1. Replaced with a placeholder in the initial shell
+ * 2. Processed in parallel with other suspense boundaries
+ * 3. Streamed to the client as it resolves
+ * 4. Injected into the placeholder via client-side JavaScript
+ */
+export declare const streamingSuspenseDirective: CustomDirective;
 /**
  * Custom directive for creating islands (for partial hydration)
  */
-export declare const islandDirective: CustomDirective;
+export declare const islandDirective: CustomDirective;
+/**
+ * Configuration for hydration runtime generation
+ */
+export declare interface HydrationRuntimeConfig {
+  mode: 'full' | 'loader'
+  components?: Record<string, string>
+  dynamicImports?: boolean
+}

package/dist/suspense.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Process @suspense directives in templates.
+ *
+ * Syntax:
+ *   @suspense
+ *     <async content>
+ *   @fallback
+ *     <loading fallback>
+ *   @endsuspense
+ *
+ * With options:
+ *   @suspense(timeout: 10000)
+ */
+export declare function processSuspenseDirectives(template: string, _context?: Record<string, unknown>, _filePath?: string): string;
+/**
+ * Create an SSR suspense boundary.
+ * Returns the fallback immediately, then streams the content when ready.
+ */
+export declare function createSSRSuspense(id: string, contentPromise: Promise<string>, fallback: string): SSRSuspenseBoundary;
+/**
+ * Render SSR suspense boundaries for streaming.
+ * Returns initial HTML with fallbacks, plus a script to replace them when content loads.
+ */
+export declare function renderSSRSuspense(boundaries: SSRSuspenseBoundary[]): Promise<{ initial: string; streaming: AsyncGenerator<string> }>;
+/**
+ * Generate CSS for suspense styling.
+ */
+export declare function generateSuspenseCSS(): string;
+/**
+ * Generate client-side runtime for suspense.
+ */
+export declare function generateSuspenseRuntime(): string;
+/**
+ * STX Suspense
+ *
+ * Coordinates async loading across component trees, showing a fallback
+ * until all async children are resolved.
+ *
+ * @module suspense
+ *
+ * @example
+ * ```html
+ * @suspense
+ *   <UserProfile :id="userId" />
+ *   <UserActivity :id="userId" />
+ *   <UserStats :id="userId" />
+ * @fallback
+ *   <PageSkeleton />
+ * @endsuspense
+ * ```
+ */
+// =============================================================================
+// Types
+// =============================================================================
+export declare interface SuspenseOptions {
+  id?: string
+  timeout?: number
+  onResolve?: () => void
+  onError?: (error: Error) => void
+  onPending?: () => void
+}
+export declare interface SuspenseState {
+  status: 'pending' | 'resolved' | 'rejected'
+  pending: Set<string>
+  resolved: Set<string>
+  error: Error | null
+}
+export declare interface SuspenseBoundary {
+  id: string
+  state: SuspenseState
+  register: (childId: string) => void
+  resolve: (childId: string) => void
+  reject: (childId: string, error: Error) => void
+  reset: () => void
+}
+/**
+ * Server-side suspense boundary for SSR streaming.
+ */
+export declare interface SSRSuspenseBoundary {
+  id: string
+  fallback: string
+  content: Promise<string>
+}

package/dist/teleport.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Process @teleport directives in template
+ */
+export declare function processTeleportDirectives(template: string, context: Record<string, unknown>, _filePath: string): string;
+/**
+ * Ensure teleport targets exist in the document
+ * Call this to create common teleport targets if they don't exist
+ */
+export declare function ensureTeleportTargets(): string;