@stacksjs/stx 0.2.0 → 0.2.3

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

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

package/dist/types/index.d.ts

@@ -0,0 +1,98 @@
+export type {
+  AuthContext,
+  BaseTemplateContext,
+  ContextValue,
+  LoopContext,
+  PermissionsContext,
+  RequireContextKeys,
+  TemplateContext,
+  TranslationContext,
+  TypedContext,
+} from './context-types';
+export type {
+  A11yDirective,
+  AuthDirective,
+  ComponentDirective,
+  ConditionalDirective,
+  CustomDirective,
+  CustomDirectiveHandler,
+  Directive,
+  DirectiveOfKind,
+  EnvDirective,
+  ExpressionDirective,
+  FormDirective,
+  I18nDirective,
+  IncludeDirective,
+  LayoutDirective,
+  LoopDirective,
+  Middleware,
+  MiddlewareHandler,
+  ScriptDirective,
+  SeoDirective,
+  StackDirective,
+  SwitchDirective,
+  UserCustomDirective,
+} from './directive-types';
+export type {
+  ComponentConfig,
+  ComponentDefinition,
+  ComponentDoc,
+  ComponentPropDoc,
+  ComponentPropsSchema,
+  DirectiveDoc,
+  DocFormat,
+  DocGeneratorConfig,
+  PropDefinition,
+  PropType,
+  TemplateDoc,
+  WebComponent,
+  WebComponentConfig,
+} from './component-types';
+export type {
+  A11yConfig,
+  AnalyticsConfig,
+  AnalyticsDriver,
+  AnimationConfig,
+  FormConfig,
+  HydrationConfig,
+  I18nConfig,
+  Island,
+  LoopConfig,
+  MarkdownConfig,
+  OpenGraphConfig,
+  SeoConfig,
+  SeoFeatureConfig,
+  StreamingConfig,
+  StreamRenderer,
+  StxConfig,
+  StxOptions,
+  SyntaxHighlightingConfig,
+  SyntaxHighlightTheme,
+  TwitterConfig,
+} from './config-types';
+export type {
+  PwaBackgroundSyncConfig,
+  PwaCacheStorageConfig,
+  PwaCacheStrategy,
+  PwaConfig,
+  PwaFileHandlerConfig,
+  PwaIconConfig,
+  PwaManifestConfig,
+  PwaOfflineConfig,
+  PwaPrecacheConfig,
+  PwaProtocolHandlerConfig,
+  PwaPushConfig,
+  PwaRouteCache,
+  PwaScreenshot,
+  PwaServiceWorkerConfig,
+  PwaShareTargetConfig,
+  PwaShortcut,
+  PwaUpdateConfig,
+} from './pwa-types';
+export type {
+  CspConfig,
+  CspDirectives,
+  CspPreset,
+  CspSourceValue,
+} from './csp-types';
+export { isDirectiveKind } from './directive-types';

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

@@ -0,0 +1,218 @@
+/**
+ * PWA route cache configuration
+ * Defines how specific routes should be cached by the service worker
+ */
+export declare interface PwaRouteCache {
+  pattern: string
+  strategy: PwaCacheStrategy
+  cacheName?: string
+  maxAgeSeconds?: number
+  maxEntries?: number
+}
+/**
+ * PWA icon configuration for automatic generation
+ */
+export declare interface PwaIconConfig {
+  src: string
+  sizes?: number[]
+  generateWebP?: boolean
+  generateAppleIcons?: boolean
+  outputDir?: string
+  purpose?: ('any' | 'maskable' | 'monochrome')[]
+}
+/**
+ * PWA shortcut definition for app shortcuts menu
+ */
+export declare interface PwaShortcut {
+  name: string
+  shortName?: string
+  description?: string
+  url: string
+  icons?: Array<{ src: string, sizes: string, type?: string }>
+}
+/**
+ * PWA screenshot definition for app store listings
+ */
+export declare interface PwaScreenshot {
+  src: string
+  sizes: string
+  type?: string
+  label?: string
+  platform?: 'wide' | 'narrow'
+}
+/**
+ * PWA Web App Manifest configuration
+ */
+export declare interface PwaManifestConfig {
+  name: string
+  shortName?: string
+  description?: string
+  startUrl?: string
+  display?: 'fullscreen' | 'standalone' | 'minimal-ui' | 'browser'
+  displayOverride?: string[]
+  orientation?: 'portrait' | 'landscape' | 'any' | 'portrait-primary' | 'portrait-secondary' | 'landscape-primary' | 'landscape-secondary'
+  themeColor?: string
+  backgroundColor?: string
+  scope?: string
+  lang?: string
+  dir?: 'ltr' | 'rtl' | 'auto'
+  id?: string
+  categories?: string[]
+  shortcuts?: PwaShortcut[]
+  screenshots?: PwaScreenshot[]
+  launchHandler?: 'auto' | 'focus-existing' | 'navigate-new' | 'navigate-existing'
+  handleLinks?: 'auto' | 'preferred' | 'not-preferred'
+  edgeSidePanel?: {
+    enabled: boolean
+    preferredWidth?: number
+  }
+}
+/**
+ * PWA offline fallback page configuration
+ */
+export declare interface PwaOfflineConfig {
+  enabled: boolean
+  page?: string
+  fallbackTitle?: string
+  fallbackMessage?: string
+  precacheAssets?: string[]
+}
+/**
+ * Service worker configuration
+ */
+export declare interface PwaServiceWorkerConfig {
+  fileName?: string
+  cacheVersion?: string
+  skipWaiting?: boolean
+  clientsClaim?: boolean
+  navigationPreload?: boolean
+  excludeRoutes?: string[]
+  cacheFileTypes?: string[]
+  useWorkbox?: boolean
+}
+/**
+ * Push notification configuration
+ */
+export declare interface PwaPushConfig {
+  enabled: boolean
+  vapidPublicKey?: string
+  subscriptionEndpoint?: string
+  defaultIcon?: string
+  defaultBadge?: string
+  defaultOptions?: {
+    /** Enable vibration */
+    vibrate?: number[]
+    /** Require interaction to dismiss */
+    requireInteraction?: boolean
+  }
+}
+/**
+ * Background sync configuration
+ */
+export declare interface PwaBackgroundSyncConfig {
+  enabled: boolean
+  queueName?: string
+  maxRetentionMinutes?: number
+  maxRetries?: number
+  minInterval?: number
+  forms?: string[]
+  endpoints?: string[]
+}
+/**
+ * Share target configuration for receiving shared content
+ */
+export declare interface PwaShareTargetConfig {
+  enabled: boolean
+  action: string
+  method?: 'GET' | 'POST'
+  enctype?: 'application/x-www-form-urlencoded' | 'multipart/form-data'
+  params?: {
+    /** Parameter name for shared title */
+    title?: string
+    /** Parameter name for shared text */
+    text?: string
+    /** Parameter name for shared URL */
+    url?: string
+  }
+  acceptFiles?: Array<{
+    name: string
+    accept: string[]
+  }>
+}
+/**
+ * File handler configuration for handling specific file types
+ */
+export declare interface PwaFileHandlerConfig {
+  enabled: boolean
+  action?: string
+  accept?: Record<string, string[]>
+  launchType?: 'single-client' | 'multiple-clients'
+  icons?: Array<{ src: string, sizes: string, type: string }>
+}
+/**
+ * Protocol handler configuration
+ */
+export declare interface PwaProtocolHandlerConfig {
+  protocol: string
+  url: string
+}
+/**
+ * Cache storage limits configuration
+ */
+export declare interface PwaCacheStorageConfig {
+  maxSize?: number
+  maxEntries?: number
+  maxAge?: number
+  purgeStrategy?: 'lru' | 'fifo' | 'lfu'
+}
+/**
+ * Update notification configuration
+ */
+export declare interface PwaUpdateConfig {
+  enabled: boolean
+  promptUser?: boolean
+  autoReload?: boolean
+  message?: string
+  uiSelector?: string
+}
+/**
+ * Auto-precaching configuration
+ */
+export declare interface PwaPrecacheConfig {
+  enabled: boolean
+  includeHtml?: boolean
+  includeJs?: boolean
+  includeCss?: boolean
+  includeImages?: boolean
+  includeFonts?: boolean
+  include?: string[]
+  exclude?: string[]
+  maxFileSizeKB?: number
+}
+/**
+ * Complete PWA configuration
+ */
+export declare interface PwaConfig {
+  enabled: boolean
+  manifest: PwaManifestConfig
+  icons?: PwaIconConfig
+  routes?: PwaRouteCache[]
+  offline?: PwaOfflineConfig
+  serviceWorker?: PwaServiceWorkerConfig
+  autoInject?: boolean
+  push?: PwaPushConfig
+  backgroundSync?: PwaBackgroundSyncConfig
+  shareTarget?: PwaShareTargetConfig
+  fileHandlers?: PwaFileHandlerConfig
+  protocolHandlers?: PwaProtocolHandlerConfig[]
+  cacheStorage?: PwaCacheStorageConfig
+  updates?: PwaUpdateConfig
+  precache?: PwaPrecacheConfig
+}
+/**
+ * Progressive Web App (PWA) Types
+ */
+/**
+ * PWA caching strategy for service worker routes
+ */
+export type PwaCacheStrategy = 'cache-first' | 'network-first' | 'stale-while-revalidate' | 'network-only' | 'cache-only'