@stacksjs/stx 0.2.0 → 0.2.3

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

@@ -0,0 +1,336 @@
+import type { ComponentConfig, DocGeneratorConfig, WebComponentConfig } from './component-types';
+import type { CspConfig } from './csp-types';
+import type { CustomDirective, Middleware } from './directive-types';
+import type { HeatmapConfig } from '../heatmap';
+import type { MediaConfig } from '../media/types';
+import type { MiddlewareMode } from '../route-middleware';
+import type { PwaConfig } from './pwa-types';
+/**
+ * Internationalization (i18n) configuration
+ */
+export declare interface I18nConfig {
+  defaultLocale: string
+  locale: string
+  translationsDir: string
+  format: 'json' | 'yaml' | 'yml' | 'js'
+  fallbackToKey: boolean
+  cache: boolean
+}
+/**
+ * Streaming configuration
+ */
+export declare interface StreamingConfig {
+  enabled: boolean
+  bufferSize: number
+  strategy: 'auto' | 'manual' | 'sections'
+  timeout: number
+}
+/**
+ * Stream renderer for progressive loading
+ */
+export declare interface StreamRenderer {
+  renderShell: (data?: Record<string, unknown>) => Promise<string>
+  renderSection: (section: string, data?: Record<string, unknown>) => Promise<string>
+  getSections: () => string[]
+  getTemplate: () => string
+}
+/**
+ * Hydration configuration
+ */
+export declare interface HydrationConfig {
+  enabled: boolean
+  mode: 'progressive' | 'islands'
+  clientEntry: string
+  autoMarkers: boolean
+  preload: 'none' | 'eager' | 'lazy'
+}
+/**
+ * Island definition for partial hydration
+ */
+export declare interface Island {
+  id: string
+  component: string
+  props?: Record<string, unknown>
+  priority?: 'eager' | 'lazy'
+  shadowDOM?: boolean
+}
+/**
+ * Accessibility configuration
+ */
+export declare interface A11yConfig {
+  enabled: boolean
+  addSrOnlyStyles: boolean
+  level: 'AA' | 'AAA'
+  ignoreChecks?: string[]
+  autoFix: boolean
+}
+/**
+ * SEO OpenGraph configuration
+ */
+export declare interface OpenGraphConfig {
+  type?: string
+  title?: string
+  description?: string
+  url?: string
+  image?: string
+  imageAlt?: string
+  imageWidth?: number
+  imageHeight?: number
+  siteName?: string
+}
+/**
+ * SEO Twitter card configuration
+ */
+export declare interface TwitterConfig {
+  card?: 'summary' | 'summary_large_image' | 'app' | 'player'
+  title?: string
+  description?: string
+  image?: string
+  site?: string
+  creator?: string
+}
+/**
+ * SEO configuration
+ */
+export declare interface SeoConfig {
+  title?: string
+  description?: string
+  keywords?: string[] | string
+  robots?: string
+  canonical?: string
+  openGraph?: OpenGraphConfig
+  twitter?: TwitterConfig
+  structuredData?: Record<string, unknown>
+}
+/**
+ * SEO features configuration
+ */
+export declare interface SeoFeatureConfig {
+  enabled: boolean
+  defaultConfig?: SeoConfig
+  socialPreview?: boolean
+  defaultImage?: string
+}
+/**
+ * Analytics configuration for automatic script injection
+ */
+export declare interface AnalyticsConfig {
+  enabled: boolean
+  driver: AnalyticsDriver
+  fathom?: {
+    /** Fathom site ID */
+    siteId: string
+    /** Custom script URL (default: https://cdn.usefathom.com/script.js) */
+    scriptUrl?: string
+    /** Honor Do Not Track browser setting */
+    honorDnt?: boolean
+    /** Defer script loading (default: true) */
+    defer?: boolean
+    /** Enable SPA mode for client-side routing */
+    spa?: boolean
+    /** Canonical URL override */
+    canonical?: string
+    /** Auto-track page views (default: true) */
+    auto?: boolean
+  }
+  googleAnalytics?: {
+    /** GA4 Measurement ID (e.g., G-XXXXXXXXXX) */
+    measurementId: string
+    /** Enable debug mode */
+    debug?: boolean
+  }
+  plausible?: {
+    /** Your domain (e.g., example.com) */
+    domain: string
+    /** Custom script URL (default: https://plausible.io/js/script.js) */
+    scriptUrl?: string
+    /** Track localhost */
+    trackLocalhost?: boolean
+    /** Enable hash-based routing */
+    hashMode?: boolean
+  }
+  selfHosted?: {
+    /** Site ID for tracking */
+    siteId: string
+    /** API endpoint URL for collecting analytics */
+    apiEndpoint: string
+    /** Honor Do Not Track browser setting */
+    honorDnt?: boolean
+    /** Track hash changes as page views */
+    trackHashChanges?: boolean
+    /** Track outbound link clicks */
+    trackOutboundLinks?: boolean
+  }
+  custom?: {
+    /** Custom script URL */
+    scriptUrl: string
+    /** Script ID attribute */
+    scriptId?: string
+    /** Additional script attributes */
+    attributes?: Record<string, string>
+    /** Inline script content (instead of external URL) */
+    inlineScript?: string
+  }
+}
+/**
+ * Animation configuration
+ */
+export declare interface AnimationConfig {
+  enabled: boolean
+  defaultDuration: number
+  defaultEase: string
+  respectMotionPreferences: boolean
+  staggerDelay: number
+}
+/**
+ * Route middleware configuration
+ */
+export declare interface RouteMiddlewareConfig {
+  enabled: boolean
+  dir: string
+  global?: string[]
+  defaultMode: MiddlewareMode
+}
+/**
+ * Loop directive configuration
+ */
+export declare interface LoopConfig {
+  maxWhileIterations: number
+  useAltLoopVariable: boolean
+}
+/**
+ * Syntax highlighting configuration
+ */
+export declare interface SyntaxHighlightingConfig {
+  enabled: boolean
+  serverSide: boolean
+  defaultTheme: SyntaxHighlightTheme
+  highlightUnknownLanguages: boolean
+  additionalThemes?: SyntaxHighlightTheme[]
+}
+/**
+ * Markdown configuration
+ */
+export declare interface MarkdownConfig {
+  enabled: boolean
+  dir?: string
+  syntaxHighlighting?: Partial<SyntaxHighlightingConfig>
+}
+/**
+ * Configuration for form directives
+ */
+export declare interface FormConfig {
+  classes?: {
+    /** Class for text inputs, textareas, and selects */
+    input?: string
+    /** Class added to inputs with validation errors */
+    inputError?: string
+    /** Class for checkboxes and radios */
+    checkInput?: string
+    /** Class for labels */
+    label?: string
+    /** Class for error message containers */
+    errorFeedback?: string
+  }
+}
+/**
+ * stx configuration options
+ */
+export declare interface StxConfig {
+  templatesDir?: string
+  defaultTitle?: string
+  defaultDescription?: string
+  defaultImage?: string
+  cache?: boolean
+  cacheDir?: string
+  cacheVersion?: string
+  enabled: boolean
+  partialsDir: string
+  componentsDir: string
+  layoutsDir?: string
+  defaultLayout?: string
+  debug: boolean
+  cachePath: string
+  customDirectives?: CustomDirective[]
+  middleware?: Middleware[]
+  i18n?: Partial<I18nConfig>
+  webComponents?: Partial<WebComponentConfig>
+  docs?: Partial<DocGeneratorConfig>
+  streaming?: Partial<StreamingConfig>
+  hydration?: Partial<HydrationConfig>
+  a11y?: Partial<A11yConfig>
+  seo?: Partial<SeoFeatureConfig>
+  analytics?: Partial<AnalyticsConfig>
+  animation?: Partial<AnimationConfig>
+  skipDefaultSeoTags?: boolean
+  skipSignalsRuntime?: boolean
+  skipEventDirectives?: boolean
+  markdown?: Partial<MarkdownConfig>
+  loops?: Partial<LoopConfig>
+  forms?: Partial<FormConfig>
+  csp?: Partial<CspConfig>
+  story?: Partial<import('../story/types').StoryConfig>
+  pwa?: Partial<PwaConfig>
+  components?: Partial<ComponentConfig>
+  routeMiddleware?: Partial<RouteMiddlewareConfig>
+  heatmap?: Partial<HeatmapConfig>
+  build?: Partial<BuildConfig>
+  media?: Partial<MediaConfig>
+}
+/**
+ * SSG Build configuration for static site generation
+ */
+export declare interface BuildConfig {
+  pagesDir: string
+  outputDir: string
+  baseUrl: string
+  domain?: string
+  sitemap: boolean
+  rss?: boolean | import('../ssg').RSSConfig
+  minify: boolean
+  cache: boolean
+  cacheDir: string
+  concurrency: number
+  generate404: boolean
+  publicDir: string
+  trailingSlash: boolean
+  cleanOutput: boolean
+  revalidate?: number | false
+}
+/**
+ * Analytics driver type
+ */
+export type AnalyticsDriver = 'fathom' | 'google-analytics' | 'plausible' | 'self-hosted' | 'custom'
+/**
+ * Available syntax highlighting themes
+ */
+export type SyntaxHighlightTheme = | 'css-variables'
+  | 'dark-plus'
+  | 'dracula'
+  | 'dracula-soft'
+  | 'github-dark'
+  | 'github-dark-dimmed'
+  | 'github-light'
+  | 'hc_light'
+  | 'light-plus'
+  | 'material-theme'
+  | 'material-theme-darker'
+  | 'material-theme-lighter'
+  | 'material-theme-ocean'
+  | 'material-theme-palenight'
+  | 'min-dark'
+  | 'min-light'
+  | 'monokai'
+  | 'nord'
+  | 'one-dark-pro'
+  | 'poimandres'
+  | 'rose-pine'
+  | 'rose-pine-dawn'
+  | 'rose-pine-moon'
+  | 'slack-dark'
+  | 'slack-ochin'
+  | 'solarized-dark'
+  | 'solarized-light'
+  | 'vitesse-dark'
+  | 'vitesse-light'
+export type StxOptions = Partial<StxConfig>

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

@@ -0,0 +1,99 @@
+import type { StxOptions } from './config-types';
+/**
+ * Loop context object available within @foreach loops
+ * Provides iteration metadata for template logic
+ */
+export declare interface LoopContext {
+  index: number
+  iteration: number
+  first: boolean
+  last: boolean
+  count: number
+}
+/**
+ * Authentication context for @auth, @guest, @can directives
+ * Required shape for auth-related template directives
+ *
+ * @example
+ * ```typescript
+ * const authContext: AuthContext = {
+ *   check: true,
+ *   user: { id: 1, name: 'John', role: 'admin' }
+ * }
+ * ```
+ */
+export declare interface AuthContext {
+  check: boolean
+  user: Record<string, unknown> | null
+}
+/**
+ * Permissions context for @can, @cannot directives
+ *
+ * @example
+ * ```typescript
+ * const permissions: PermissionsContext = {
+ *   check: (ability, type?, id?) => {
+ *     // Check if user has the ability
+ *     return user.abilities.includes(ability)
+ *   }
+ * }
+ * ```
+ */
+export declare interface PermissionsContext {
+  check: (ability: string, type?: string, id?: unknown) => boolean
+}
+/**
+ * Translation context for @translate, @t directives
+ */
+export declare interface TranslationContext {
+
+}
+/**
+ * Base template context with common properties
+ * Extend this interface for specific template contexts
+ */
+export declare interface BaseTemplateContext {
+  auth?: AuthContext
+  permissions?: PermissionsContext
+  userCan?: Record<string, boolean>
+  __translations?: TranslationContext
+  __sections?: Record<string, string>
+  __stx_options?: StxOptions
+  loop?: LoopContext
+  $loop?: LoopContext
+  slot?: string
+}
+/**
+ * Template context type alias for backward compatibility
+ * Use BaseTemplateContext for new code
+ */
+export type TemplateContext = BaseTemplateContext
+/**
+ * Generic template context that allows specifying custom typed properties
+ *
+ * @example
+ * ```typescript
+ * // Define your typed context
+ * interface MyContext extends TypedContext<{
+ *   user: { name: string; email: string }
+ *   items: string[]
+ *   count: number
+ * }> {}
+ *
+ * // Use in template processing
+ * const ctx: MyContext = {
+ *   user: { name: 'John', email: 'john@example.com' },
+ *   items: ['a', 'b'],
+ *   count: 42
+ * }
+ * ```
+ */
+export type TypedContext<T extends Record<string, unknown>> = BaseTemplateContext & T
+/**
+ * Utility type to extract the value type from a context key
+ */
+export type ContextValue<C extends BaseTemplateContext, K extends keyof C> = C[K]
+/**
+ * Utility type to make certain context properties required
+ */
+export type RequireContextKeys<C extends BaseTemplateContext, K extends keyof C> = Required<Pick<C, K>> & Omit<C, K>

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

@@ -0,0 +1,79 @@
+/**
+ * Individual CSP directive configuration
+ * Maps directive names to arrays of allowed sources
+ */
+export declare interface CspDirectives {
+  'default-src'?: CspSourceValue[]
+  'script-src'?: CspSourceValue[]
+  'style-src'?: CspSourceValue[]
+  'img-src'?: CspSourceValue[]
+  'font-src'?: CspSourceValue[]
+  'connect-src'?: CspSourceValue[]
+  'media-src'?: CspSourceValue[]
+  'object-src'?: CspSourceValue[]
+  'frame-src'?: CspSourceValue[]
+  'worker-src'?: CspSourceValue[]
+  'child-src'?: CspSourceValue[]
+  'manifest-src'?: CspSourceValue[]
+  'form-action'?: CspSourceValue[]
+  'frame-ancestors'?: CspSourceValue[]
+  'prefetch-src'?: CspSourceValue[]
+  'navigate-to'?: CspSourceValue[]
+  'base-uri'?: CspSourceValue[]
+  'report-uri'?: string[]
+  'report-to'?: string[]
+  'upgrade-insecure-requests'?: boolean
+  'block-all-mixed-content'?: boolean
+  'sandbox'?: (
+    | 'allow-forms'
+    | 'allow-modals'
+    | 'allow-orientation-lock'
+    | 'allow-pointer-lock'
+    | 'allow-popups'
+    | 'allow-popups-to-escape-sandbox'
+    | 'allow-presentation'
+    | 'allow-same-origin'
+    | 'allow-scripts'
+    | 'allow-top-navigation'
+    | 'allow-top-navigation-by-user-activation'
+  )[]
+  'require-trusted-types-for'?: ('script')[]
+  'trusted-types'?: string[]
+}
+/**
+ * CSP configuration options
+ */
+export declare interface CspConfig {
+  enabled: boolean
+  reportOnly?: boolean
+  directives: CspDirectives
+  useNonce?: boolean
+  addMetaTag?: boolean
+  nonceGenerator?: () => string
+}
+/**
+ * Content Security Policy Types
+ */
+/**
+ * CSP directive source values
+ * These are the standard source values that can be used in CSP directives
+ */
+export type CspSourceValue = | '\'self\''
+  | '\'unsafe-inline\''
+  | '\'unsafe-eval\''
+  | '\'unsafe-hashes\''
+  | '\'strict-dynamic\''
+  | '\'report-sample\''
+  | '\'wasm-unsafe-eval\''
+  | '\'none\''
+  | 'data:'
+  | 'blob:'
+  | 'https:'
+  | 'http:'
+  | 'ws:'
+  | 'wss:'
+  | string
+/**
+ * Preset CSP configurations for common use cases
+ */
+export type CspPreset = 'strict' | 'moderate' | 'relaxed' | 'api'