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

A performant UI Framework. Powered by Bun.

/**
 * Type guard to check if a directive is a specific kind
 */
export declare function isDirectiveKind<K extends Directive['kind']>(directive: Directive, kind: K): directive is Extract<Directive, { kind: K }>;
/**
 * Directive Types - Discriminated Unions for all directive types
 */
/**
 * Base directive type with common properties
 */
declare interface BaseDirective {
  kind: string
  raw: string
  start: number
  end: number
}
/**
 * Conditional directive (@if, @elseif, @else, @unless, @isset, @empty)
 */
export declare interface ConditionalDirective extends BaseDirective {
  kind: 'conditional'
  type: 'if' | 'elseif' | 'else' | 'endif' | 'unless' | 'endunless' | 'isset' | 'endisset' | 'empty' | 'endempty'
  condition?: string
  content?: string
}
/**
 * Loop directive (@foreach, @for, @while, @forelse)
 */
export declare interface LoopDirective extends BaseDirective {
  kind: 'loop'
  type: 'foreach' | 'endforeach' | 'for' | 'endfor' | 'while' | 'endwhile' | 'forelse' | 'empty' | 'endforelse'
  expression?: string
  itemVar?: string
  arrayExpr?: string
  content?: string
  emptyContent?: string
}
/**
 * Include directive (@include, @includeIf, @includeWhen, @includeUnless, @includeFirst)
 */
export declare interface IncludeDirective extends BaseDirective {
  kind: 'include'
  type: 'include' | 'includeIf' | 'includeWhen' | 'includeUnless' | 'includeFirst' | 'partial' | 'once'
  path?: string
  paths?: string[]
  condition?: string
  variables?: Record<string, unknown>
}
/**
 * Layout directive (@layout, @extends, @section, @yield, @parent)
 */
export declare interface LayoutDirective extends BaseDirective {
  kind: 'layout'
  type: 'layout' | 'extends' | 'section' | 'endsection' | 'yield' | 'parent' | 'show'
  name?: string
  defaultContent?: string
  content?: string
}
/**
 * Component directive (@component, x-component)
 */
export declare interface ComponentDirective extends BaseDirective {
  kind: 'component'
  type: 'component' | 'endcomponent' | 'slot' | 'endslot'
  name?: string
  props?: Record<string, unknown>
  slotName?: string
  content?: string
}
/**
 * Auth directive (@auth, @guest, @can, @cannot)
 */
export declare interface AuthDirective extends BaseDirective {
  kind: 'auth'
  type: 'auth' | 'endauth' | 'guest' | 'endguest' | 'can' | 'endcan' | 'cannot' | 'endcannot' | 'role' | 'endrole'
  guard?: string
  ability?: string
  arguments?: unknown[]
  content?: string
}
/**
 * Form directive (@csrf, @method, @error, @old)
 */
export declare interface FormDirective extends BaseDirective {
  kind: 'form'
  type: 'csrf' | 'method' | 'error' | 'enderror' | 'old'
  method?: 'PUT' | 'PATCH' | 'DELETE'
  field?: string
  content?: string
}
/**
 * Stack directive (@push, @prepend, @stack)
 */
export declare interface StackDirective extends BaseDirective {
  kind: 'stack'
  type: 'push' | 'endpush' | 'prepend' | 'endprepend' | 'stack'
  name: string
  content?: string
}
/**
 * Expression directive ({{ }}, {!! !!})
 */
export declare interface ExpressionDirective extends BaseDirective {
  kind: 'expression'
  type: 'escaped' | 'raw'
  expression: string
  filters?: Array<{
    name: string
    args?: unknown[]
  }>
}
/**
 * Switch directive (@switch, @case, @default)
 */
export declare interface SwitchDirective extends BaseDirective {
  kind: 'switch'
  type: 'switch' | 'case' | 'default' | 'break' | 'endswitch'
  expression?: string
  caseValue?: unknown
  content?: string
}
/**
 * SEO directive (@meta, @seo, @og, @twitter, @jsonld)
 */
export declare interface SeoDirective extends BaseDirective {
  kind: 'seo'
  type: 'meta' | 'seo' | 'og' | 'twitter' | 'jsonld' | 'canonical' | 'robots'
  name?: string
  metaContent?: string
  config?: Record<string, unknown>
}
/**
 * Accessibility directive (@a11y, @screenReader, @ariaDescribe)
 */
export declare interface A11yDirective extends BaseDirective {
  kind: 'a11y'
  type: 'screenReader' | 'srOnly' | 'ariaDescribe' | 'a11y'
  text?: string
  target?: string
  descriptionId?: string
}
/**
 * JavaScript/TypeScript execution directive (@js, @ts)
 */
export declare interface ScriptDirective extends BaseDirective {
  kind: 'script'
  type: 'js' | 'ts'
  code: string
}
/**
 * Environment directive (@env, @production, @development)
 */
export declare interface EnvDirective extends BaseDirective {
  kind: 'env'
  type: 'env' | 'endenv' | 'production' | 'endproduction' | 'development' | 'enddevelopment'
  environments?: string[]
  content?: string
}
/**
 * i18n directive (@translate, @t, @lang)
 */
export declare interface I18nDirective extends BaseDirective {
  kind: 'i18n'
  type: 'translate' | 't' | 'lang' | 'endlang' | 'choice'
  key?: string
  params?: Record<string, unknown>
  count?: number
  locale?: string
  content?: string
}
/**
 * Custom directive (user-defined)
 */
export declare interface UserCustomDirective extends BaseDirective {
  kind: 'custom'
  name: string
  params: string[]
  content?: string
}
/**
 * Custom directive definition
 */
export declare interface CustomDirective {
  name: string
  handler: CustomDirectiveHandler
  hasEndTag?: boolean
  description?: string
}
/**
 * Middleware definition
 */
export declare interface Middleware {
  name: string
  handler: MiddlewareHandler
  timing: 'before' | 'after'
  description?: string
}
/**
 * Union type of all directive types (discriminated union)
 *
 * Use the `kind` property to narrow the type:
 *
 * @example
 * ```typescript
 * function processDirective(directive: Directive) {
 *   switch (directive.kind) {
 *     case 'conditional':
 *       // TypeScript knows directive is ConditionalDirective here
 *       if (directive.type === 'if') {
 *         console.log(directive.condition)
 *       }
 *       break
 *     case 'loop':
 *       // TypeScript knows directive is LoopDirective here
 *       console.log(directive.expression)
 *       break
 *     // ... other cases
 *   }
 * }
 * ```
 */
export type Directive = | ConditionalDirective
  | LoopDirective
  | IncludeDirective
  | LayoutDirective
  | ComponentDirective
  | AuthDirective
  | FormDirective
  | StackDirective
  | ExpressionDirective
  | SwitchDirective
  | SeoDirective
  | A11yDirective
  | ScriptDirective
  | EnvDirective
  | I18nDirective
  | UserCustomDirective
/**
 * Helper type to extract directive by kind
 */
export type DirectiveOfKind<K extends Directive['kind']> = Extract<Directive, { kind: K }>
/**
 * Custom directive handler function
 */
export type CustomDirectiveHandler = (
  content: string,
  params: string[],
  context: Record<string, unknown>,
  filePath: string
) => string | Promise<string>
/**
 * Middleware handler function
 */
export type MiddlewareHandler = (
  template: string,
  context: Record<string, unknown>,
  filePath: string,
  options: import('./config-types').StxOptions
) => string | Promise<string>