@stacksjs/stx 0.1.16 → 0.2.3

package/dist/testing.d.ts

@@ -0,0 +1,289 @@
+import type { StxOptions } from './types';
+/**
+ * Render an STX template to HTML.
+ *
+ * @example
+ * ```typescript
+ * const { html, container } = await render('<h1>{{ title }}</h1>', {
+ *   context: { title: 'Hello World' }
+ * })
+ * expect(html).toContain('Hello World')
+ * ```
+ */
+export declare function render(template: string, options?: MountOptions): Promise<RenderResult>;
+/**
+ * Mount an STX component for testing.
+ *
+ * @example
+ * ```typescript
+ * const wrapper = await mount('<Button @click="handleClick">Click me</Button>', {
+ *   props: { disabled: false },
+ *   context: { handleClick: vi.fn() }
+ * })
+ *
+ * await wrapper.find('button')?.trigger('click')
+ * expect(wrapper.emitted('click')).toBeDefined()
+ * ```
+ */
+export declare function mount(template: string, options?: MountOptions): Promise<ComponentWrapper>;
+/**
+ * Wait for the next tick.
+ */
+export declare function nextTick(): Promise<void>;
+/**
+ * Wait for a condition to be true.
+ */
+export declare function waitFor(condition: () => boolean | Promise<boolean>, options?: { timeout?: number; interval?: number }): Promise<void>;
+/**
+ * Wait for element to appear.
+ */
+export declare function waitForElement(wrapper: ComponentWrapper, selector: string, options?: { timeout?: number }): Promise<ElementWrapper | null>;
+/**
+ * Flush all pending promises.
+ */
+export declare function flushPromises(): Promise<void>;
+/**
+ * Create a mock function.
+ */
+export declare function createMockFn<T extends (...args: unknown[]) => unknown>(): MockFn<T>;
+/**
+ * Create a mock store for testing.
+ *
+ * @example
+ * ```ts
+ * const store = createMockStore({ count: 0, user: null })
+ *
+ * store.setState({ count: 5 })
+ * expect(store.getState().count).toBe(5)
+ *
+ * // Check history
+ * expect(store.getHistory()).toEqual([
+ *   { count: 0, user: null },
+ *   { count: 5, user: null }
+ * ])
+ *
+ * // Reset
+ * store.reset()
+ * expect(store.getState().count).toBe(0)
+ * ```
+ */
+export declare function createMockStore<T extends Record<string, unknown>>(initialState: T): MockStore<T>;
+/**
+ * Create a test context with common setup.
+ */
+export declare function createTestContext(options?: {
+  props?: Record<string, unknown>
+  context?: Record<string, unknown>
+  mocks?: Record<string, unknown>
+}): {
+  props: Record<string, unknown>
+  context: Record<string, unknown>
+  mocks: Record<string, MockFn>
+};
+/**
+ * Clean up after tests.
+ */
+export declare function cleanup(): void;
+/**
+ * Fire events on elements.
+ */
+export declare const fireEvent: {
+  /**
+   * Fire a click event.
+   */
+  async click(
+    target: HTMLElement | ElementWrapper | ComponentWrapper | null,
+    options?: MouseEventInit,
+  ): unknown;
+  /**
+   * Fire a double click event.
+   */
+  async dblClick(
+    target: HTMLElement | ElementWrapper | ComponentWrapper | null,
+    options?: MouseEventInit,
+  ): unknown;
+  /**
+   * Fire an input event.
+   */
+  async input(
+    target: HTMLElement | ElementWrapper | ComponentWrapper | null,
+    value: string,
+  ): unknown;
+  /**
+   * Fire a change event.
+   */
+  async change(
+    target: HTMLElement | ElementWrapper | ComponentWrapper | null,
+    value?: string,
+  ): unknown;
+  /**
+   * Fire a submit event.
+   */
+  async submit(
+    target: HTMLElement | ElementWrapper | ComponentWrapper | null,
+  ): unknown;
+  /**
+   * Fire a focus event.
+   */
+  async focus(
+    target: HTMLElement | ElementWrapper | ComponentWrapper | null,
+  ): unknown;
+  /**
+   * Fire a blur event.
+   */
+  async blur(
+    target: HTMLElement | ElementWrapper | ComponentWrapper | null,
+  ): unknown;
+  /**
+   * Fire a keydown event.
+   */
+  async keyDown(
+    target: HTMLElement | ElementWrapper | ComponentWrapper | null,
+    key: string,
+    options?: KeyboardEventInit,
+  ): unknown;
+  /**
+   * Fire a keyup event.
+   */
+  async keyUp(
+    target: HTMLElement | ElementWrapper | ComponentWrapper | null,
+    key: string,
+    options?: KeyboardEventInit,
+  ): unknown;
+  /**
+   * Fire a custom event.
+   */
+  async custom(
+    target: HTMLElement | ElementWrapper | ComponentWrapper | null,
+    eventName: string,
+    options?: FireEventOptions,
+  ): unknown
+};
+/**
+ * Create custom matchers for testing.
+ */
+export declare const matchers: {
+  /**
+   * Check if wrapper contains text.
+   */
+  toContainText(wrapper: ComponentWrapper | ElementWrapper, text: string): unknown;
+  /**
+   * Check if wrapper has class.
+   */
+  toHaveClass(wrapper: ComponentWrapper | ElementWrapper, className: string): unknown;
+  /**
+   * Check if wrapper has attribute.
+   */
+  toHaveAttribute(
+    wrapper: ComponentWrapper | ElementWrapper,
+    name: string,
+    value?: string,
+  ): unknown;
+  /**
+   * Check if wrapper is visible.
+   */
+  toBeVisible(wrapper: ComponentWrapper | ElementWrapper): unknown;
+  /**
+   * Check if wrapper exists.
+   */
+  toExist(wrapper: ComponentWrapper | ElementWrapper | null): unknown;
+  /**
+   * Check if event was emitted.
+   */
+  toHaveEmitted(wrapper: ComponentWrapper, event: string, times?: number): unknown;
+  /**
+   * Check if event was emitted with payload.
+   */
+  toHaveEmittedWith(wrapper: ComponentWrapper, event: string, payload: unknown): (boolean { const emitted?) if (!emitted) return false return emitted.some((args)) => unknown
+};
+/** Mount options */
+export declare interface MountOptions {
+  props?: Record<string, unknown>
+  slots?: Record<string, string>
+  context?: Record<string, unknown>
+  stxOptions?: Partial<StxOptions>
+  attachTo?: HTMLElement | string
+  mocks?: Record<string, unknown>
+  stubs?: Record<string, string | boolean>
+  plugins?: unknown[]
+}
+/** Render result */
+export declare interface RenderResult {
+  html: string
+  document: Document
+  container: HTMLElement
+  context: Record<string, unknown>
+  dependencies: Set<string>
+}
+/** Wrapper for mounted component */
+export declare interface ComponentWrapper {
+  element: HTMLElement
+  html(): string
+  text(): string
+  find(selector: string): ElementWrapper<T> | null
+  findAll(selector: string): ElementWrapper<T>[]
+  findComponent(name: string): ComponentWrapper | null
+  findAllComponents(name: string): ComponentWrapper[]
+  exists(): boolean
+  isVisible(): boolean
+  attributes(): Record<string, string>
+  attributes(name: string): string | null
+  classes(): string[]
+  classes(name: string): boolean
+  props(): Record<string, unknown>
+  props(name: string): T | undefined
+  emitted(): Record<string, unknown[][]>
+  emitted(event: string): unknown[][] | undefined
+  setProps(props: Record<string, unknown>): Promise<void>
+  setData(data: Record<string, unknown>): Promise<void>
+  trigger(event: string, payload?: unknown): Promise<void>
+  getValue(): string | boolean | string[]
+  setValue(value: string | boolean): Promise<void>
+  unmount(): void
+  vm: {
+    $nextTick(): Promise<void>
+  }
+}
+/** Wrapper for DOM elements */
+export declare interface ElementWrapper<T extends HTMLElement = HTMLElement> {
+  element: T
+  html(): string
+  text(): string
+  find(selector: string): ElementWrapper<E> | null
+  findAll(selector: string): ElementWrapper<E>[]
+  exists(): boolean
+  isVisible(): boolean
+  attributes(): Record<string, string>
+  attributes(name: string): string | null
+  classes(): string[]
+  classes(name: string): boolean
+  trigger(event: string, payload?: unknown): Promise<void>
+  getValue(): string | boolean | string[]
+  setValue(value: string | boolean): Promise<void>
+}
+/** Fire event options */
+export declare interface FireEventOptions {
+  bubbles?: boolean
+  cancelable?: boolean
+  detail?: unknown
+}
+/** Mock function type */
+export declare interface MockFn<T extends (...args: unknown[]) => unknown = (...args: unknown[]) => unknown> {
+  (...args: Parameters<T>): ReturnType<T> | undefined
+  mock: {
+    calls: unknown[][]
+    results: unknown[]
+  }
+  mockImplementation(impl: T): MockFn<T>
+  mockReturnValue(value: unknown): MockFn<T>
+  mockClear(): MockFn<T>
+  mockReset(): MockFn<T>
+}
+/** Mock store interface */
+export declare interface MockStore<T extends Record<string, unknown>> {
+  getState(): T
+  setState(partial: Partial<T>): void
+  reset(): void
+  getHistory(): T[]
+  subscribe(listener: (state: T) => void): () => void
+}

package/dist/transitions.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Perform an enter transition on an element.
+ */
+export declare function performEnter(el: Element, options?: TransitionOptions): Promise<void>;
+/**
+ * Perform a leave transition on an element.
+ */
+export declare function performLeave(el: Element, options?: TransitionOptions): Promise<void>;
+/**
+ * Process @transition directives in templates.
+ *
+ * Syntax:
+ *   @transition(name: 'fade')
+ *   @transition(name: 'slide', duration: 300)
+ *   @transition(name: 'fade', mode: 'out-in')
+ */
+export declare function processTransitionDirectives(template: string, _context?: Record<string, unknown>, _filePath?: string): string;
+/**
+ * Generate CSS for common transition presets.
+ */
+export declare function generateTransitionCSS(): string;
+/**
+ * Generate the client-side transition runtime.
+ */
+export declare function generateTransitionRuntime(): string;
+/**
+ * Process @transition attribute on elements.
+ *
+ * Usage:
+ *   <div @transition.fade="visible">Content</div>
+ *   <div @transition.slide-up.300="isOpen">Content</div>
+ */
+export declare function processTransitionAttributes(template: string): string;
+/**
+ * STX Transitions
+ *
+ * Vue-inspired transition system for enter/leave animations.
+ * Supports CSS transitions, CSS animations, and JavaScript hooks.
+ *
+ * @module transitions
+ *
+ * @example
+ * ```html
+ * @transition(name: 'fade')
+ *   @if (visible)
+ *     <div class="modal">Content</div>
+ *   @endif
+ * @endtransition
+ * ```
+ *
+ * CSS classes applied:
+ * - `.fade-enter-from` - Starting state for enter
+ * - `.fade-enter-active` - Active state during enter
+ * - `.fade-enter-to` - Ending state for enter
+ * - `.fade-leave-from` - Starting state for leave
+ * - `.fade-leave-active` - Active state during leave
+ * - `.fade-leave-to` - Ending state for leave
+ */
+// =============================================================================
+// Types
+// =============================================================================
+export declare interface TransitionOptions {
+  name?: string
+  duration?: number | { enter: number; leave: number }
+  easing?: string
+  mode?: 'in-out' | 'out-in' | 'default'
+  css?: boolean
+  enterClass?: string
+  enterActiveClass?: string
+  enterToClass?: string
+  leaveClass?: string
+  leaveActiveClass?: string
+  leaveToClass?: string
+  onBeforeEnter?: (el: Element) => void
+  onEnter?: (el: Element, done: () => void) => void
+  onAfterEnter?: (el: Element) => void
+  onEnterCancelled?: (el: Element) => void
+  onBeforeLeave?: (el: Element) => void
+  onLeave?: (el: Element, done: () => void) => void
+  onAfterLeave?: (el: Element) => void
+  onLeaveCancelled?: (el: Element) => void
+}
+export declare interface TransitionState {
+  isEntering: boolean
+  isLeaving: boolean
+  isCancelled: boolean
+}

package/dist/type-checker.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Create a type checker instance
+ */
+export declare function createTypeChecker(options?: TypeCheckerOptions): TemplateTypeChecker;
+/**
+ * Check a template file
+ */
+export declare function checkTemplateFile(filePath: string, options?: TypeCheckerOptions): TypeCheckResult;
+/**
+ * Check a template string
+ */
+export declare function checkTemplate(template: string, options?: TypeCheckerOptions): TypeCheckResult;
+/**
+ * Format type check errors for display
+ */
+export declare function formatTypeErrors(result: TypeCheckResult): string;
+/**
+ * Type definition for a variable or expression
+ */
+export declare interface TypeDefinition {
+  kind: 'primitive' | 'object' | 'array' | 'function' | 'union' | 'intersection' | 'literal'
+  name?: string
+  value?: PrimitiveType | string
+  properties?: Record<string, TypeDefinition>
+  elementType?: TypeDefinition
+  params?: Array<{ name: string, type: TypeDefinition, optional?: boolean }>
+  returnType?: TypeDefinition
+  types?: TypeDefinition[]
+}
+/**
+ * Type error reported by the checker
+ */
+export declare interface TypeCheckError {
+  message: string
+  file: string
+  line: number
+  column: number
+  expression: string
+  expected?: string
+  received?: string
+  severity: 'error' | 'warning'
+}
+/**
+ * Type check result
+ */
+export declare interface TypeCheckResult {
+  valid: boolean
+  errors: TypeCheckError[]
+  warnings: TypeCheckError[]
+  variables: Map<string, TypeDefinition>
+}
+/**
+ * Options for the type checker
+ */
+export declare interface TypeCheckerOptions {
+  strict?: boolean
+  allowAny?: boolean
+  checkPropertyAccess?: boolean
+  checkFunctionCalls?: boolean
+  includeBuiltins?: boolean
+  customTypes?: Record<string, TypeDefinition>
+  baseDir?: string
+}
+/**
+ * Primitive types supported by the type checker
+ */
+export type PrimitiveType = | 'string'
+  | 'number'
+  | 'boolean'
+  | 'null'
+  | 'undefined'
+  | 'any'
+  | 'unknown'
+  | 'void'
+  | 'never'
+/**
+ * Template Type Checker class
+ */
+export declare class TemplateTypeChecker {
+  private options: TypeCheckerOptions;
+  private variables: Map<string, TypeDefinition>;
+  private errors: TypeCheckError[];
+  private warnings: TypeCheckError[];
+  private currentFile: string;
+  constructor(options?: TypeCheckerOptions);
+  checkFile(filePath: string): TypeCheckResult;
+  checkTemplate(template: string, filePath?: string): TypeCheckResult;
+  private analyzeScript(script: string, scriptOffset: number): void;
+  private extractTypedVariables(line: string, lineNum: number): void;
+  private extractInterfaces(line: string, lines: string[], index: number, lineNum: number): void;
+  private extractTypeAliases(line: string, lineNum: number): void;
+  private parseTypeAnnotation(annotation: string): TypeDefinition;
+  private inferType(value: string): TypeDefinition;
+  private parseParams(paramsStr: string): Array<{ name: string, type: TypeDefinition, optional?: boolean }>;
+  private checkExpressions(template: string): void;
+  private checkExpression(expression: string, line: number, column: number): void;
+  private checkDirectives(template: string): void;
+  private resolvePropertyAccess(expr: string): TypeDefinition;
+  private isLiteral(expr: string): boolean;
+  private extractObjectLiteral(expr: string): Record<string, string>;
+  private splitByComma(str: string): string[];
+  private getLineNumber(position: number, template?: string): number;
+  private getColumn(position: number, template: string): number;
+  private addError(message: string, line: number, column: number, expression: string, expected?: string, received?: string): void;
+  private addWarning(message: string, line: number, column: number, expression: string, expected?: string, received?: string): void;
+  private getResult(): TypeCheckResult;
+  addVariable(name: string, type: TypeDefinition): void;
+  reset(): void;
+}

package/dist/types/component-types.d.ts

@@ -0,0 +1,129 @@
+/**
+ * Component prop definition for validation
+ */
+export declare interface PropDefinition {
+  type: PropType | PropType[]
+  required?: boolean
+  default?: unknown
+  validator?: (value: unknown) => boolean
+}
+/**
+ * Component props schema for validation
+ *
+ * @example
+ * ```typescript
+ * const alertProps: ComponentPropsSchema = {
+ *   title: { type: 'string', required: true },
+ *   type: { type: 'string', default: 'info' },
+ *   dismissible: { type: 'boolean', default: false }
+ * }
+ * ```
+ */
+export declare interface ComponentPropsSchema {
+
+}
+/**
+ * Component definition with metadata
+ */
+export declare interface ComponentDefinition {
+  name: string
+  path?: string
+  props?: ComponentPropsSchema
+  description?: string
+}
+/**
+ * Component configuration
+ */
+export declare interface ComponentConfig {
+  validateProps?: boolean
+  components?: Record<string, ComponentDefinition>
+}
+/**
+ * Web component definition
+ */
+export declare interface WebComponent {
+  name: string
+  tag: string
+  file: string
+  extends?: string
+  shadowDOM?: boolean
+  template?: boolean
+  styleSource?: string
+  attributes?: string[]
+  description?: string
+  outputFormat?: 'js' | 'ts'
+  attributeTypes?: Record<string, 'string' | 'number' | 'boolean' | 'object'>
+}
+/**
+ * Web components configuration
+ */
+export declare interface WebComponentConfig {
+  enabled: boolean
+  outputDir: string
+  components: WebComponent[]
+}
+/**
+ * Component property documentation
+ */
+export declare interface ComponentPropDoc {
+  name: string
+  type?: string
+  required?: boolean
+  default?: string
+  description?: string
+}
+/**
+ * Component documentation
+ */
+export declare interface ComponentDoc {
+  name: string
+  path: string
+  description?: string
+  props: ComponentPropDoc[]
+  example?: string
+  isWebComponent?: boolean
+  tag?: string
+}
+/**
+ * Template documentation
+ */
+export declare interface TemplateDoc {
+  name: string
+  path: string
+  description?: string
+  components?: string[]
+  directives?: string[]
+}
+/**
+ * Directive documentation
+ */
+export declare interface DirectiveDoc {
+  name: string
+  description?: string
+  hasEndTag: boolean
+  example?: string
+}
+/**
+ * Documentation generator configuration
+ */
+export declare interface DocGeneratorConfig {
+  enabled: boolean
+  outputDir: string
+  format: DocFormat
+  components: boolean
+  templates: boolean
+  directives: boolean
+  extraContent?: string
+  template?: string
+}
+/**
+ * Component System Types
+ */
+/**
+ * Prop type definition for component prop validation
+ */
+export type PropType = 'string' | 'number' | 'boolean' | 'array' | 'object' | 'function' | 'any'
+/**
+ * Documentation format options
+ */
+export type DocFormat = 'markdown' | 'html' | 'json'