@stacksjs/stx/dist/directive-api.d.ts

A performant UI Framework. Powered by Bun.

import type { CustomDirective } from './types';
/**
 * Register a directive globally.
 */
export declare function registerDirective<P extends DirectiveParams = DirectiveParams>(definition: FullDirectiveDefinition<P>): void;
/**
 * Get a registered directive.
 */
export declare function getDirective(name: string): FullDirectiveDefinition | undefined;
/**
 * Get all registered directives.
 */
export declare function getDirectives(): FullDirectiveDefinition[];
/**
 * Unregister a directive.
 */
export declare function unregisterDirective(name: string): boolean;
/**
 * Define a custom directive.
 *
 * @example
 * ```typescript
 * // Simple transform directive
 * const uppercase = defineDirective({
 *   name: 'uppercase',
 *   transform: (content) => content.toUpperCase()
 * })
 *
 * // Directive with parameters and validation
 * const truncate = defineDirective({
 *   name: 'truncate',
 *   defaults: { length: 100, suffix: '...' },
 *   validate: ({ length }) => length > 0 || 'Length must be positive',
 *   transform: (content, { length, suffix }) =>
 *     content.length > length
 *       ? content.slice(0, length) + suffix
 *       : content
 * })
 *
 * // Client-side directive
 * const tooltip = defineDirective({
 *   name: 'tooltip',
 *   transform: (content, { text }) =>
 *     `<span data-tooltip="${text}">${content}</span>`,
 *   client: {
 *     mounted(el, { value }) {
 *       el.title = value
 *     }
 *   }
 * })
 * ```
 */
export declare function defineDirective<P extends DirectiveParams = DirectiveParams, T = unknown>(definition: FullDirectiveDefinition<P, T>): CustomDirective;
/**
 * Define a client-only directive.
 */
export declare function defineClientDirective<T = unknown>(name: string, definition: ClientDirectiveDefinition<T> | ((el: HTMLElement, binding: DirectiveBinding<T>) => void)): ClientDirectiveDefinition<T>;
/**
 * Create common built-in directives.
 */
export declare function createBuiltinDirectives(): CustomDirective[];
/**
 * Generate client-side directive runtime.
 */
export declare function generateDirectiveRuntime(): string;
/**
 * Process v-directive attributes in templates.
 * Converts v-directive:arg.mod="value" to data attributes and client setup.
 */
export declare function processDirectiveAttributes(template: string): string;
/** Directive binding for client-side directives */
export declare interface DirectiveBinding<T = unknown> {
  value: T
  oldValue?: T
  arg?: string
  modifiers: Record<string, boolean>
  instance: unknown
  dir: ClientDirectiveDefinition<T>
}
/** Server-side directive definition */
export declare interface DirectiveDefinition<P extends DirectiveParams = DirectiveParams> {
  name: string
  hasEndTag?: boolean
  description?: string
  transform?: (
    content: string,
    params: P,
    context: Record<string, unknown>,
    filePath: string,
  ) => string | Promise<string>
  validate?: (params: P) => boolean | string
  defaults?: Partial<P>
  clientScript?: (params: P) => string
  css?: (params: P) => string
}
/** Client-side directive hooks */
export declare interface ClientDirectiveDefinition<T = unknown> {
  created?: (el: HTMLElement, binding: DirectiveBinding<T>) => void
  beforeMount?: (el: HTMLElement, binding: DirectiveBinding<T>) => void
  mounted?: (el: HTMLElement, binding: DirectiveBinding<T>) => void
  beforeUpdate?: (el: HTMLElement, binding: DirectiveBinding<T>) => void
  updated?: (el: HTMLElement, binding: DirectiveBinding<T>) => void
  beforeUnmount?: (el: HTMLElement, binding: DirectiveBinding<T>) => void
  unmounted?: (el: HTMLElement, binding: DirectiveBinding<T>) => void
}
/** Combined directive (server + client) */
export declare interface FullDirectiveDefinition<P extends DirectiveParams = DirectiveParams, T = unknown> extends DirectiveDefinition<P> {
  client?: ClientDirectiveDefinition<T>
}
/** Directive parameter types */
export type DirectiveParams = Record<string, unknown>