@stacksjs/stx 0.2.0 → 0.2.3

package/dist/view-composers.d.ts

@@ -1,26 +1,171 @@
 /**
- * Register a composer for a specific view
+ * Register a composer for a specific view.
+ *
+ * The view can be either the full file path or just the view name (filename without extension).
+ * Both will be checked when determining which composers to run.
+ *
+ * @param view - The view name or full file path to match
+ * @param callback - Function to execute when the view is rendered
+ *
+ * @example
+ * ```typescript
+ * // Match by view name
+ * composer('profile', (context) => {
+ *   context.tabs = ['overview', 'settings', 'security']
+ * })
+ *
+ * // Match by full path
+ * composer('/app/views/users/edit.stx', async (context) => {
+ *   context.timezones = await loadTimezones()
+ * })
+ * ```
  */
 export declare function composer(view: string, callback: ViewComposerCallback): void;
 /**
- * Register a composer for all views matching a pattern
+ * Register a composer for all views matching a pattern.
+ *
+ * The pattern is tested against both the full file path and the view name.
+ * If either matches, the composer will run.
+ *
+ * @param pattern - A RegExp or string pattern (strings are converted to RegExp)
+ * @param callback - Function to execute when a matching view is rendered
+ *
+ * @example
+ * ```typescript
+ * // Match all admin views using RegExp
+ * composerPattern(/^admin/, (context) => {
+ *   context.adminNav = loadAdminNavigation()
+ * })
+ *
+ * // Match views containing 'settings' using string pattern
+ * composerPattern('settings', (context) => {
+ *   context.settingsVersion = '2.0'
+ * })
+ *
+ * // Match views ending with '-form'
+ * composerPattern(/-form$/, (context) => {
+ *   context.csrfToken = generateCsrfToken()
+ * })
+ * ```
  */
 export declare function composerPattern(pattern: string | RegExp, callback: ViewComposerCallback): void;
 /**
- * Execute all composers for a given view
+ * Execute all composers for a given view.
+ *
+ * This function is called automatically during template processing.
+ * You typically don't need to call this directly.
+ *
+ * Execution order:
+ * 1. Exact match by full file path
+ * 2. Exact match by view name (filename without extension)
+ * 3. Pattern matches (in registration order)
+ *
+ * @param filePath - Full path to the template file being rendered
+ * @param context - The template context object to be modified by composers
+ *
+ * @internal
  */
 export declare function runComposers(filePath: string, context: Record<string, any>): Promise<void>;
 /**
- * Clear all registered composers
- * (Mainly for testing purposes)
+ * Clear all registered composers.
+ *
+ * Removes all exact match and pattern match composers.
+ * Primarily used for testing to reset state between tests.
+ *
+ * @example
+ * ```typescript
+ * import { clearComposers, composer } from 'stx'
+ *
+ * describe('MyComponent', () => {
+ *   beforeEach(() => {
+ *     clearComposers() // Reset before each test
+ *   })
+ *
+ *   it('should inject user data', () => {
+ *     composer('profile', (ctx) => { ctx.user = mockUser })
+ *     // ... test
+ *   })
+ * })
+ * ```
  */
 export declare function clearComposers(): void;
 /**
- * View Composers functionality for stx templating
- * Similar to Laravel's View Composers, this allows registering
- * callbacks that should run whenever a specific view is rendered.
+ * View Composers Module
+ *
+ * Similar to Laravel's View Composers, this module allows registering callbacks
+ * that automatically run whenever a specific view (or views matching a pattern)
+ * is rendered. Use this to inject data into templates without manually passing
+ * it every time.
+ *
+ * ## Use Cases
+ *
+ * - Inject user data into all views
+ * - Add navigation data to layout templates
+ * - Load settings for specific page types
+ * - Populate dropdown options across forms
+ *
+ * ## Registration Methods
+ *
+ * ### Exact Match
+ * ```typescript
+ * import { composer } from 'stx'
+ *
+ * // Match by exact view name
+ * composer('dashboard', async (context) => {
+ *   context.stats = await fetchDashboardStats()
+ * })
+ *
+ * // Match by full file path
+ * composer('/views/admin/users.stx', (context) => {
+ *   context.roles = ['admin', 'editor', 'viewer']
+ * })
+ * ```
+ *
+ * ### Pattern Match
+ * ```typescript
+ * import { composerPattern } from 'stx'
+ *
+ * // Match all admin views
+ * composerPattern(/^admin/, (context) => {
+ *   context.isAdmin = true
+ * })
+ *
+ * // Match with string pattern (converted to RegExp)
+ * composerPattern('.*\\.settings\\.', (context) => {
+ *   context.settingsMenu = loadSettingsMenu()
+ * })
+ * ```
+ *
+ * ## Execution Order
+ *
+ * 1. Exact match composers (by full file path)
+ * 2. Exact match composers (by view name only)
+ * 3. Pattern match composers (in registration order)
+ *
+ * All composers for a matching view run in sequence.
+ * Async composers are awaited before the next runs.
+ *
+ * ## Important Notes
+ *
+ * - Composers modify the context object directly (no return value needed)
+ * - Composers are global and persist for the application lifetime
+ * - Use `clearComposers()` to reset in tests
+ *
+ * @module view-composers
  */
 /**
- * Type definition for view composer callback function
+ * Callback function type for view composers.
+ *
+ * @param context - The template context object (modify this directly)
+ * @param filePath - Full path to the template file being rendered
+ * @returns void or a Promise that resolves to void
+ *
+ * @example
+ * ```typescript
+ * const myComposer: ViewComposerCallback = async (context, filePath) => {
+ *   context.user = await getCurrentUser()
+ *   context.viewPath = filePath
+ * }
+ * ```
  */
 export type ViewComposerCallback = (context: Record<string, any>, filePath: string) => void | Promise<void>

package/dist/virtual-scrolling.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Creates a virtual scroll instance for a list of items
+ */
+export declare function createVirtualList<T>(items: T[], options: VirtualListOptions): VirtualScrollInstance;
+/**
+ * Process @virtualList directives in templates
+ */
+export declare function processVirtualListDirectives(template: string, context?: Record<string, unknown>, _filePath?: string): string;
+/**
+ * Generate CSS for virtual list styling
+ */
+export declare function generateVirtualListCSS(): string;
+/**
+ * Hook to create a reactive virtual list
+ */
+export declare function useVirtualList<T>(items: () => T[], options: VirtualListOptions): {
+  visibleItems: () => T[]
+  totalHeight: () => number
+  containerProps: () => Record<string, unknown>
+  itemProps: (index: number) => Record<string, unknown>
+  scrollToIndex: (index: number) => void
+};
+/**
+ * Process @infiniteList directives for infinite scrolling
+ */
+export declare function processInfiniteListDirectives(template: string, context?: Record<string, unknown>, _filePath?: string): string;
+/**
+ * Process @virtualGrid directives for grid virtualization
+ */
+export declare function processVirtualGridDirectives(template: string, context?: Record<string, unknown>, _filePath?: string): string;
+/**
+ * Virtual Scrolling Module
+ *
+ * Provides efficient rendering of large lists using windowing/virtualization.
+ * Only renders items that are visible in the viewport, dramatically improving
+ * performance for lists with thousands of items.
+ *
+ * @example
+ * ```html
+ * @virtualList(items, { itemHeight: 50, containerHeight: 400 })
+ *   <div class="item">{{ item.name }}</div>
+ * @endvirtualList
+ * ```
+ */
+// ============================================================================
+// Types
+// ============================================================================
+export declare interface VirtualListOptions {
+  itemHeight: number
+  containerHeight: number
+  overscan?: number
+  keyProperty?: string
+  dynamicHeight?: boolean
+  estimatedItemHeight?: number
+  scrollBehavior?: 'auto' | 'smooth'
+  direction?: 'vertical' | 'horizontal'
+  containerClass?: string
+  viewportClass?: string
+  itemClass?: string
+}
+export declare interface VirtualListState {
+  startIndex: number
+  endIndex: number
+  scrollTop: number
+  totalHeight: number
+  visibleItems: unknown[]
+  itemHeights: Map<number, number>
+}
+export declare interface VirtualScrollInstance {
+  scrollToIndex: (index: number, behavior?: ScrollBehavior) => void
+  scrollToOffset: (offset: number, behavior?: ScrollBehavior) => void
+  getState: () => VirtualListState
+  refresh: () => void
+  setItems: (items: unknown[]) => void
+  destroy: () => void
+}
+// ============================================================================
+// Infinite Scroll Support
+// ============================================================================
+export declare interface InfiniteScrollOptions extends VirtualListOptions {
+  threshold?: number
+  onLoadMore?: () => Promise<void>
+  hasMore?: boolean
+  isLoading?: boolean
+}
+// ============================================================================
+// Grid Virtualization
+// ============================================================================
+export declare interface VirtualGridOptions {
+  columns: number
+  rowHeight: number
+  containerHeight: number
+  gap?: number
+  overscan?: number
+}
+export default {
+  createVirtualList,
+  processVirtualListDirectives,
+  processInfiniteListDirectives,
+  processVirtualGridDirectives,
+  generateVirtualListCSS,
+  useVirtualList,
+};

package/dist/visual-editor.d.ts

@@ -0,0 +1,209 @@
+/**
+ * Generate a hierarchical outline of the template.
+ * Used for document outline view in IDEs.
+ */
+export declare function getTemplateOutline(template: string): OutlineNode;
+/**
+ * Analyze a template for visual editor purposes
+ * (Alias: analyzeTemplateContent)
+ */
+export declare function analyzeVisualEditorTemplate(template: string): TemplateAnalysis;
+/**
+ * Analyze a template string and extract all relevant information
+ * Use this for analyzing template content directly (not from a file path)
+ */
+export declare function analyzeTemplateContent(template: string): TemplateAnalysis;
+/**
+ * Generate preview HTML for a template.
+ * This is a simplified preview for editor integration.
+ */
+export declare function generatePreview(template: string, options?: VisualEditorPreviewOptions): Promise<string>;
+/**
+ * Get default component palette items.
+ */
+export declare function getDefaultPalette(): PaletteItem[];
+/**
+ * Generate insert result for a palette item.
+ */
+export declare function insertPaletteItem(item: PaletteItem, position: EditorPosition, indentation?: string): InsertResult;
+/** Template outline node */
+export declare interface OutlineNode {
+  type: OutlineNodeType
+  name: string
+  label: string
+  range: { start: number, end: number, line: number, column: number }
+  children: OutlineNode[]
+  attributes?: Record<string, string | true>
+  directiveCategory?: DirectiveCategory
+  isClosable?: boolean
+  icon?: string
+  description?: string
+}
+/** Template analysis result */
+export declare interface TemplateAnalysis {
+  variables: VariableUsage[]
+  components: ComponentReference[]
+  directives: VisualEditorDirectiveUsage[]
+  slots: SlotDefinition[]
+  sections: SectionDefinition[]
+  scripts: ScriptBlock[]
+  styles: StyleBlock[]
+  layout?: LayoutInfo
+  metrics: VisualEditorMetrics
+}
+/** Variable usage info */
+export declare interface VariableUsage {
+  name: string
+  line: number
+  column: number
+  context: 'expression' | 'directive' | 'attribute'
+  inferredType?: string
+}
+/** Component reference info */
+export declare interface ComponentReference {
+  name: string
+  path?: string
+  line: number
+  props: Record<string, string | true>
+  hasSlot: boolean
+}
+/** Visual editor directive usage info */
+export declare interface VisualEditorDirectiveUsage {
+  name: string
+  category: DirectiveCategory
+  line: number
+  params?: string
+  hasEndTag: boolean
+}
+/** Slot definition */
+export declare interface SlotDefinition {
+  name: string
+  line: number
+  isNamed: boolean
+  defaultContent?: string
+}
+/** Section definition */
+export declare interface SectionDefinition {
+  name: string
+  line: number
+  content: string
+}
+/** Script block info */
+export declare interface ScriptBlock {
+  type: 'typescript' | 'javascript'
+  line: number
+  content: string
+  exports: string[]
+}
+/** Style block info */
+export declare interface StyleBlock {
+  type: 'css' | 'scss' | 'less'
+  line: number
+  content: string
+  scoped: boolean
+}
+/** Layout info */
+export declare interface LayoutInfo {
+  extends: string
+  line: number
+  sections: string[]
+}
+/** Visual editor template complexity metrics */
+export declare interface VisualEditorMetrics {
+  lines: number
+  characters: number
+  maxNestingDepth: number
+  directiveCount: number
+  componentCount: number
+  expressionCount: number
+  complexity: number
+}
+/** Visual editor preview options */
+export declare interface VisualEditorPreviewOptions {
+  context?: Record<string, unknown>
+  includeStyles?: boolean
+  includeScripts?: boolean
+  wrapInDocument?: boolean
+  baseUrl?: string
+  customCss?: string
+}
+/** Component palette item */
+export declare interface PaletteItem {
+  name: string
+  displayName: string
+  category: string
+  description: string
+  icon?: string
+  snippet: string
+  props?: VisualEditorPropDefinition[]
+  slots?: string[]
+}
+/** Visual editor prop definition for palette */
+export declare interface VisualEditorPropDefinition {
+  name: string
+  type: string
+  required: boolean
+  default?: string
+  description?: string
+}
+/** Editor selection/position */
+export declare interface EditorPosition {
+  line: number
+  column: number
+  offset: number
+}
+/** Insert operation result */
+export declare interface InsertResult {
+  content: string
+  cursorPosition: EditorPosition
+}
+/**
+ * Visual Editor Integration Module
+ *
+ * Provides APIs for visual template editing in IDEs and editors.
+ * This module enables:
+ * - Template AST visualization
+ * - Component outline/structure view
+ * - Drag-and-drop component editing
+ * - Live preview support
+ * - Template property inspection
+ *
+ * ## Usage
+ *
+ * ```typescript
+ * import { analyzeTemplate, getTemplateOutline, generatePreview } from 'stx/visual-editor'
+ *
+ * // Analyze template structure
+ * const analysis = analyzeTemplate(templateContent)
+ *
+ * // Get hierarchical outline
+ * const outline = getTemplateOutline(templateContent)
+ *
+ * // Generate preview HTML
+ * const preview = await generatePreview(templateContent, context)
+ * ```
+ *
+ * @module visual-editor
+ */
+/** Node types in template outline */
+export type OutlineNodeType = | 'document'
+  | 'element'
+  | 'component'
+  | 'directive'
+  | 'slot'
+  | 'section'
+  | 'expression'
+  | 'script'
+  | 'style'
+  | 'comment'
+  | 'text'
+/** Directive category for visual grouping */
+export type DirectiveCategory = | 'control-flow'
+  | 'loop'
+  | 'layout'
+  | 'component'
+  | 'auth'
+  | 'form'
+  | 'seo'
+  | 'i18n'
+  | 'custom'

package/dist/visual-testing.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Create a snapshot tester
+ */
+export declare function createSnapshotTester(config?: VisualTestConfig): void;
+/**
+ * Create a visual regression tester
+ */
+export declare function createVisualRegressionTester(config?: VisualTestConfig): void;
+/**
+ * Create a story-based visual tester
+ */
+export declare function createStoryTester(config?: VisualTestConfig): void;
+/**
+ * Generate visual test report
+ */
+export declare function generateReport(results: VisualTestResult[], config?: ReportConfig): Promise<string>;
+/**
+ * Quick snapshot test
+ */
+export declare function snapshot(html: string, name: string): Promise<SnapshotResult>;
+/**
+ * Quick JSON snapshot test
+ */
+export declare function snapshotJson(data: unknown, name: string): Promise<SnapshotResult>;
+/**
+ * Reset default tester (for testing)
+ */
+export declare function resetDefaultTester(): void;
+// =============================================================================
+// Default Viewports
+// =============================================================================
+export declare const defaultViewports: Viewport[];
+// =============================================================================
+// Types
+// =============================================================================
+export declare interface VisualTestConfig {
+  snapshotDir?: string
+  screenshotDir?: string
+  updateSnapshots?: boolean
+  threshold?: number
+  viewports?: Viewport[]
+  generateDiff?: boolean
+  diffDir?: string
+  compare?: (actual: Buffer, expected: Buffer) => Promise<ComparisonResult>
+  ci?: boolean
+  retries?: number
+}
+export declare interface Viewport {
+  name: string
+  width: number
+  height: number
+  deviceScaleFactor?: number
+  isMobile?: boolean
+  hasTouch?: boolean
+}
+export declare interface SnapshotResult {
+  passed: boolean
+  snapshotPath: string
+  actualPath?: string
+  diffPath?: string
+  message?: string
+}
+export declare interface ComparisonResult {
+  match: boolean
+  diffPercentage: number
+  diffPixels: number
+  diffImage?: Buffer
+}
+export declare interface VisualTestResult {
+  name: string
+  passed: boolean
+  duration: number
+  snapshots: SnapshotResult[]
+  screenshots: ScreenshotResult[]
+  errors: Error[]
+}
+export declare interface ScreenshotResult {
+  viewport: string
+  passed: boolean
+  baselinePath: string
+  actualPath?: string
+  diffPath?: string
+  diffPercentage?: number
+}
+export declare interface Story {
+  name: string
+  component: string
+  render: () => string | Promise<string>
+  args?: Record<string, unknown>
+  viewports?: Viewport[]
+}
+// =============================================================================
+// Test Reporter
+// =============================================================================
+export declare interface ReportConfig {
+  outputDir?: string
+  format?: 'html' | 'json' | 'markdown'
+  title?: string
+  includeScreenshots?: boolean
+}
+export default {
+  createSnapshotTester,
+  createVisualRegressionTester,
+  createStoryTester,
+  generateReport,
+  snapshot,
+  snapshotJson,
+  defaultViewports,
+};