@stacksjs/stx 0.2.155 → 0.2.156

package/dist/a11y.d.ts

@@ -1,4 +1,41 @@
+/**
+ * Accessibility (A11y) Module
+ *
+ * Provides directives and utilities for accessibility compliance:
+ * - `@a11y('type', 'message')` - Add accessibility hints as HTML comments
+ * - `@screenReader(...)@endScreenReader` - Screen reader only content
+ * - `@ariaDescribe('id', 'description')` - Connect elements with descriptions
+ *
+ * Also provides automated accessibility checking via `checkA11y()` and
+ * directory scanning via `scanA11yIssues()`.
+ *
+ * ## Accessibility Checks
+ *
+ * The automated checker validates:
+ * - Images have alt attributes
+ * - Interactive elements have accessible names
+ * - Form inputs have associated labels
+ * - Heading hierarchy is maintained
+ * - Document has lang attribute
+ */
 import type { CustomDirective, StxOptions } from './types';
+/**
+ * Accessibility violation found during a11y checks
+ */
+export interface A11yViolation {
+    /** Type/category of violation */
+    type: string;
+    /** The problematic HTML element */
+    element: string;
+    /** Description of the issue */
+    message: string;
+    /** Impact level of the violation */
+    impact: 'critical' | 'serious' | 'moderate' | 'minor';
+    /** Suggested fix */
+    help: string;
+    /** URL to more information */
+    helpUrl?: string;
+}
 /**
  * Process accessibility directives.
  * Handles @a11y hints, @screenReader content, and @ariaDescribe.
@@ -48,7 +85,49 @@ export declare function checkA11y(html: string, filePath: string): Promise<A11yV
  * Scan a directory of stx files for accessibility issues.
  * Returns a map of file paths to their violations.
  */
-export declare function scanA11yIssues(directory: string, options?: { recursive?: boolean, ignorePaths?: string[] }): Promise<Record<string, A11yViolation[]>>;
+export declare function scanA11yIssues(directory: string, options?: {
+    recursive?: boolean;
+    ignorePaths?: string[];
+}): Promise<Record<string, A11yViolation[]>>;
+/**
+ * Auto-fix result
+ */
+export interface A11yFixResult {
+    /** Original HTML */
+    original: string;
+    /** Fixed HTML */
+    fixed: string;
+    /** Number of fixes applied */
+    fixCount: number;
+    /** Details of each fix */
+    fixes: Array<{
+        type: string;
+        description: string;
+        before: string;
+        after: string;
+    }>;
+}
+/**
+ * Auto-fix configuration
+ */
+export interface A11yAutoFixConfig {
+    /** Fix images without alt text by adding empty alt="" */
+    fixMissingAlt?: boolean;
+    /** Fix buttons/links without accessible names by adding aria-label */
+    fixMissingLabels?: boolean;
+    /** Fix form inputs without labels by adding aria-label */
+    fixMissingFormLabels?: boolean;
+    /** Fix tables without headers by adding scope attribute */
+    fixTableHeaders?: boolean;
+    /** Add lang attribute to html element */
+    fixMissingLang?: boolean;
+    /** Fix positive tabindex values */
+    fixPositiveTabindex?: boolean;
+    /** Fix custom buttons without tabindex */
+    fixButtonFocusable?: boolean;
+    /** Default language for lang attribute */
+    defaultLang?: string;
+}
 /**
  * Auto-fix accessibility issues in HTML content.
  *
@@ -88,15 +167,11 @@ export declare function autoFixA11yFile(filePath: string, config?: A11yAutoFixCo
  * @returns Map of file paths to fix results
  */
 export declare function autoFixA11yDirectory(directory: string, config?: A11yAutoFixConfig, options?: {
-    recursive?: boolean
-    ignorePaths?: string[]
-    writeBack?: boolean
-    extensions?: string[]
-  }): Promise<Record<string, A11yFixResult>>;
-/**
- * Register all a11y directives
- */
-export declare function registerA11yDirectives(): CustomDirective[];
+    recursive?: boolean;
+    ignorePaths?: string[];
+    writeBack?: boolean;
+    extensions?: string[];
+}): Promise<Record<string, A11yFixResult>>;
 /**
  * A11y directive for adding accessibility hints
  */
@@ -106,40 +181,6 @@ export declare const a11yDirective: CustomDirective;
  */
 export declare const screenReaderDirective: CustomDirective;
 /**
- * Accessibility violation found during a11y checks
- */
-export declare interface A11yViolation {
-  type: string
-  element: string
-  message: string
-  impact: 'critical' | 'serious' | 'moderate' | 'minor'
-  help: string
-  helpUrl?: string
-}
-/**
- * Auto-fix result
- */
-export declare interface A11yFixResult {
-  original: string
-  fixed: string
-  fixCount: number
-  fixes: Array<{
-    type: string
-    description: string
-    before: string
-    after: string
-  }>
-}
-/**
- * Auto-fix configuration
+ * Register all a11y directives
  */
-export declare interface A11yAutoFixConfig {
-  fixMissingAlt?: boolean
-  fixMissingLabels?: boolean
-  fixMissingFormLabels?: boolean
-  fixTableHeaders?: boolean
-  fixMissingLang?: boolean
-  fixPositiveTabindex?: boolean
-  fixButtonFocusable?: boolean
-  defaultLang?: string
-}
+export declare function registerA11yDirectives(): CustomDirective[];

package/dist/animation.d.ts

@@ -1,34 +1,97 @@
 import type { CustomDirective, StxOptions } from './types';
 /**
- * Create an animation timeline for coordinated animations
+ * Available transition types that can be used with @transition directive
  */
-export declare function createAnimationTimeline(entries: TimelineEntry[]): string;
+export declare enum TransitionType {
+    Fade = "fade",
+    Slide = "slide",
+    Scale = "scale",
+    Flip = "flip",
+    Rotate = "rotate",
+    Custom = "custom"
+}
 /**
- * Generate CSS for a custom animation
+ * Available transition directions that can be used with @transition directive
  */
-export declare function generateAnimationCSS(name: string, keyframes: Keyframe[], options: KeyframeAnimationOptions): string;
+export declare enum TransitionDirection {
+    In = "in",
+    Out = "out",
+    Both = "both"
+}
 /**
- * Parse animation shorthand string
- * Format: "duration [delay] [easing] [iterations] [direction] [fill]"
+ * Available ease functions for transitions
  */
-export declare function parseAnimationShorthand(shorthand: string): KeyframeAnimationOptions;
+export declare enum TransitionEase {
+    Linear = "linear",
+    Ease = "ease",
+    EaseIn = "ease-in",
+    EaseOut = "ease-out",
+    EaseInOut = "ease-in-out",
+    Spring = "spring"
+}
 /**
- * Generate client-side animation runtime
+ * Default transition options
  */
-export declare function generateAnimationRuntime(): string;
+export declare const DEFAULT_TRANSITION_OPTIONS: {
+    duration: number;
+    delay: number;
+    ease: string;
+    direction: string;
+};
 /**
- * Register animation directives
+ * Transition directive for applying transitions to elements
  */
-export declare function registerAnimationDirectives(options: StxOptions): StxOptions;
+export declare const transitionDirective: CustomDirective;
 /**
- * Default transition options
+ * Scroll animation directive for triggering animations on scroll
  */
-export declare const DEFAULT_TRANSITION_OPTIONS: {
-  duration: number
-  delay: number
-  ease: string
-  direction: string
-};
+export declare const scrollAnimateDirective: CustomDirective;
+/**
+ * Animation group directive for coordinating multiple animations
+ */
+export declare const animationGroupDirective: CustomDirective;
+/**
+ * Motion preferences directive for controlling animation preferences
+ */
+export declare const motionDirective: CustomDirective;
+/**
+ * Process animation directives in the template
+ */
+export declare function processAnimationDirectives(template: string, context: Record<string, any>, filePath: string, options: StxOptions): string;
+/** Keyframe definition */
+export interface Keyframe {
+    offset?: number;
+    properties: Record<string, string | number>;
+    easing?: string;
+}
+/** Animation timeline entry */
+export interface TimelineEntry {
+    selector: string;
+    keyframes: Keyframe[];
+    options: KeyframeAnimationOptions;
+}
+/** Keyframe animation options */
+export interface KeyframeAnimationOptions {
+    duration: number;
+    delay?: number;
+    easing?: string;
+    iterations?: number | 'infinite';
+    direction?: 'normal' | 'reverse' | 'alternate' | 'alternate-reverse';
+    fill?: 'none' | 'forwards' | 'backwards' | 'both';
+}
+/** Spring animation config */
+export interface SpringConfig {
+    stiffness: number;
+    damping: number;
+    mass: number;
+    velocity?: number;
+}
+/** Preset spring configurations */
+export declare const SPRING_PRESETS: Record<string, SpringConfig>;
+/**
+ * @keyframe directive for custom keyframe animations
+ */
+export declare const keyframeDirective: CustomDirective;
 /**
  * @stagger directive for staggered child animations
  */
@@ -38,32 +101,23 @@ export declare const staggerDirective: CustomDirective;
  */
 export declare const springDirective: CustomDirective;
 /**
- * Available transition types that can be used with @transition directive
+ * Create an animation timeline for coordinated animations
  */
-export declare enum TransitionType {
-  Fade = 'fade',
-  Slide = 'slide',
-  Scale = 'scale',
-  Flip = 'flip',
-  Rotate = 'rotate',
-  Custom = 'custom',
-}
+export declare function createAnimationTimeline(entries: TimelineEntry[]): string;
 /**
- * Available transition directions that can be used with @transition directive
+ * Generate CSS for a custom animation
  */
-export declare enum TransitionDirection {
-  In = 'in',
-  Out = 'out',
-  Both = 'both',
-}
+export declare function generateAnimationCSS(name: string, keyframes: Keyframe[], options: KeyframeAnimationOptions): string;
 /**
- * Available ease functions for transitions
+ * Parse animation shorthand string
+ * Format: "duration [delay] [easing] [iterations] [direction] [fill]"
  */
-export declare enum TransitionEase {
-  Linear = 'linear',
-  Ease = 'ease',
-  EaseIn = 'ease-in',
-  EaseOut = 'ease-out',
-  EaseInOut = 'ease-in-out',
-  Spring = 'spring',
-}
+export declare function parseAnimationShorthand(shorthand: string): KeyframeAnimationOptions;
+/**
+ * Generate client-side animation runtime
+ */
+export declare function generateAnimationRuntime(): string;
+/**
+ * Register animation directives
+ */
+export declare function registerAnimationDirectives(options: StxOptions): StxOptions;

package/dist/appearance-bootstrap.d.ts

@@ -1,20 +1,54 @@
 /**
- * Transform every `@appearanceBootstrap({...})` directive in a template.
+ * Declarative pre-paint appearance bootstrapping.
+ *
+ * Client composables apply appearance reactively after mount, but that is too
+ * late for the first paint. This directive emits a compiler-owned synchronous
+ * script at the directive location so persisted root attributes and the dark
+ * class are present before the browser parses the application shell.
+ *
+ * @example
+ * ```stx
+ * @appearanceBootstrap({
+ *   storageKey: 'app-appearance',
+ *   appearance: {
+ *     key: 'sidebarStyle',
+ *     attribute: 'appearance',
+ *     allowed: ['macos', 'arc'],
+ *     default: 'macos',
+ *   },
+ *   colorMode: {
+ *     key: 'colorMode',
+ *     attribute: 'color-mode',
+ *     default: 'system',
+ *   },
+ * })
+ * ```
  */
-export declare function processAppearanceBootstrapDirective(template: string, context: Record<string, unknown>): string;
-export declare interface AppearanceBootstrapValue {
-  key: string
-  attribute: string
-  allowed: string[]
-  default: string
+export interface AppearanceBootstrapValue {
+    /** Property read from the persisted JSON object. */
+    key: string;
+    /** Root data attribute name without the `data-` prefix. */
+    attribute: string;
+    /** Persisted values accepted by the bootstrap. */
+    allowed: string[];
+    /** Value used when storage is absent, malformed, or outside the allowlist. */
+    default: string;
 }
-export declare interface ColorModeBootstrapValue {
-  key: string
-  attribute: string
-  default: 'light' | 'dark' | 'system'
+export interface ColorModeBootstrapValue {
+    /** Property read from the persisted JSON object. */
+    key: string;
+    /** Root data attribute name without the `data-` prefix. */
+    attribute: string;
+    /** Mode used when storage is absent or malformed. */
+    default: 'light' | 'dark' | 'system';
 }
-export declare interface AppearanceBootstrapOptions {
-  storageKey: string
-  appearance: AppearanceBootstrapValue
-  colorMode: ColorModeBootstrapValue
+export interface AppearanceBootstrapOptions {
+    /** localStorage key containing the persisted JSON preference object. */
+    storageKey: string;
+    appearance: AppearanceBootstrapValue;
+    colorMode: ColorModeBootstrapValue;
 }
+/**
+ * Transform every `@appearanceBootstrap({...})` directive in a template.
+ */
+export declare function processAppearanceBootstrapDirective(template: string, context: Record<string, unknown>): string;

package/dist/asset-roots.d.ts

@@ -0,0 +1,32 @@
+/**
+ * The conventional asset root, shared by the serve path and every build path.
+ *
+ * `serve()` resolves `/assets/*` from `resources/assets/*` as well as from
+ * `publicDir` — the Stacks/Laravel-style layout that `buddy make:*` produces.
+ * No build path had ever heard of it: they copy `publicDir` and nothing else.
+ *
+ * So `<script src="/assets/scripts/site-mode.js">` resolved under `stx dev` and
+ * 404'd in `dist/`, with nothing in the build reporting it. The only way to
+ * notice was to diff the build output against the served tree
+ * (stacksjs/stx#1876).
+ *
+ * It lives here rather than in one of the three builders because there are
+ * three of them — ssg.ts, site-builder/build.ts and production-builder.ts —
+ * each with its own copy mechanism, and a convention restated three times is
+ * one that will be fixed in one place and left behind in the others.
+ *
+ * @module asset-roots
+ */
+/**
+ * Directory whose contents are served at `/assets/*`, in addition to
+ * `publicDir`. Relative to the project root, and deliberately not a config
+ * option — it mirrors what `serve()` hardcodes.
+ */
+export declare const CONVENTIONAL_ASSET_ROOT = "resources/assets";
+/** Where its contents must land so `/assets/*` resolves in built output. */
+export declare const CONVENTIONAL_ASSET_OUTPUT = "assets";
+/**
+ * Absolute path to the conventional asset root, or `null` when the project
+ * does not use that layout.
+ */
+export declare function resolveConventionalAssetRoot(root?: string): string | null;

package/dist/asset-roots.js

@@ -0,0 +1,7 @@
+import fs from "node:fs";
+import path from "node:path";
+export const CONVENTIONAL_ASSET_ROOT = "resources/assets", CONVENTIONAL_ASSET_OUTPUT = "assets";
+export function resolveConventionalAssetRoot(root = process.cwd()) {
+  const dir = path.resolve(root, CONVENTIONAL_ASSET_ROOT);
+  return fs.existsSync(dir) && fs.statSync(dir).isDirectory() ? dir : null;
+}

package/dist/assets.d.ts

@@ -1,19 +1,21 @@
 import type { StxOptions } from './types';
+export declare const markdownCache: Map<string, {
+    content: string;
+    data: Record<string, any>;
+    updatedAt: number;
+}>;
 /**
  * Read and parse a markdown file with frontmatter
  * @param filePath Path to the markdown file
  * @param options stx options
  * @returns Object containing parsed content and frontmatter data
  */
-export declare function readMarkdownFile(filePath: string, options?: StxOptions): Promise<{ content: string, data: Record<string, any> }>;
+export declare function readMarkdownFile(filePath: string, options?: StxOptions): Promise<{
+    content: string;
+    data: Record<string, any>;
+}>;
 /**
  * Process @markdown-file directive
  * This directive includes markdown files in templates
  */
 export declare function processMarkdownFileDirectives(template: string, context: Record<string, any>, filePath?: string, options?: StxOptions): Promise<string>;
-// Define a cache for markdown files to avoid repeated file reads
-export declare const markdownCache: Map<string, {
-  content: string
-  data: Record<string, any>
-  updatedAt: number
-}>;

package/dist/async-components.d.ts

@@ -1,30 +1,3 @@
-/**
- * Process @async directives in templates.
- *
- * Syntax:
- *   @async(component: 'ComponentName', timeout: 5000)
- *     <loading content>
- *   @error
- *     <error content>
- *   @endasync
- */
-export declare function processAsyncDirectives(template: string, _context?: Record<string, unknown>, _filePath?: string): string;
-/**
- * Define an async component.
- */
-export declare function defineAsyncComponent(options: DefineAsyncComponentOptions | (() => Promise<{ default: string } | string>)): AsyncComponentDefinition;
-/**
- * Check if a value is an async component definition.
- */
-export declare function isAsyncComponent(value: unknown): value is AsyncComponentDefinition;
-/**
- * Generate CSS for async component styling.
- */
-export declare function generateAsyncComponentCSS(): string;
-/**
- * Generate client-side runtime for async components.
- */
-export declare function generateAsyncComponentRuntime(): string;
 /**
  * STX Async Components
  *
@@ -52,25 +25,45 @@ export declare function generateAsyncComponentRuntime(): string;
  * </AsyncComponent>
  * ```
  */
-// =============================================================================
-// Types
-// =============================================================================
-export declare interface AsyncComponentOptions {
-  component: string
-  timeout?: number
-  delay?: number
-  suspensible?: boolean
-  loadingComponent?: string
-  errorComponent?: string
-  retries?: number
-  props?: Record<string, unknown>
+export interface AsyncComponentOptions {
+    /** Component path or name to load */
+    component: string;
+    /** Timeout in milliseconds (default: 30000) */
+    timeout?: number;
+    /** Delay before showing loading state in ms (default: 200) */
+    delay?: number;
+    /** Whether to suspend parent Suspense boundary */
+    suspensible?: boolean;
+    /** Custom loading component */
+    loadingComponent?: string;
+    /** Custom error component */
+    errorComponent?: string;
+    /** Retry attempts on failure (default: 0) */
+    retries?: number;
+    /** Props to pass to the loaded component */
+    props?: Record<string, unknown>;
 }
-export declare interface AsyncComponentState {
-  status: 'pending' | 'loading' | 'resolved' | 'rejected'
-  component: string | null
-  error: Error | null
-  attempts: number
+export interface AsyncComponentState {
+    /** Current loading state */
+    status: 'pending' | 'loading' | 'resolved' | 'rejected';
+    /** The loaded component content */
+    component: string | null;
+    /** Error if loading failed */
+    error: Error | null;
+    /** Number of retry attempts made */
+    attempts: number;
 }
+/**
+ * Process @async directives in templates.
+ *
+ * Syntax:
+ *   @async(component: 'ComponentName', timeout: 5000)
+ *     <loading content>
+ *   @error
+ *     <error content>
+ *   @endasync
+ */
+export declare function processAsyncDirectives(template: string, _context?: Record<string, unknown>, _filePath?: string): string;
 /**
  * Define an async component for programmatic use.
  *
@@ -85,17 +78,46 @@ export declare interface AsyncComponentState {
  * })
  * ```
  */
-export declare interface DefineAsyncComponentOptions {
-  loader: () => Promise<{ default: string } | string>
-  loadingComponent?: string
-  errorComponent?: string
-  delay?: number
-  timeout?: number
-  suspensible?: boolean
-  onLoadStart?: () => void
-  onLoadEnd?: () => void
-  onError?: (error: Error, retry: () => void, fail: () => void, attempts: number) => void
+export interface DefineAsyncComponentOptions {
+    /** Function that returns a Promise resolving to the component */
+    loader: () => Promise<{
+        default: string;
+    } | string>;
+    /** Component to show while loading */
+    loadingComponent?: string;
+    /** Component to show on error */
+    errorComponent?: string;
+    /** Delay before showing loading component (ms) */
+    delay?: number;
+    /** Timeout before showing error (ms) */
+    timeout?: number;
+    /** Whether to suspend parent Suspense */
+    suspensible?: boolean;
+    /** Called when loading starts */
+    onLoadStart?: () => void;
+    /** Called when component is loaded */
+    onLoadEnd?: () => void;
+    /** Called on error */
+    onError?: (error: Error, retry: () => void, fail: () => void, attempts: number) => void;
 }
-export declare interface AsyncComponentDefinition extends DefineAsyncComponentOptions {
-  __asyncComponent: true
+/**
+ * Define an async component.
+ */
+export declare function defineAsyncComponent(options: DefineAsyncComponentOptions | (() => Promise<{
+    default: string;
+} | string>)): AsyncComponentDefinition;
+export interface AsyncComponentDefinition extends DefineAsyncComponentOptions {
+    __asyncComponent: true;
 }
+/**
+ * Check if a value is an async component definition.
+ */
+export declare function isAsyncComponent(value: unknown): value is AsyncComponentDefinition;
+/**
+ * Generate CSS for async component styling.
+ */
+export declare function generateAsyncComponentCSS(): string;
+/**
+ * Generate client-side runtime for async components.
+ */
+export declare function generateAsyncComponentRuntime(): string;

package/dist/auth.d.ts

@@ -1,3 +1,6 @@
+/**
+ * Module for handling authentication and authorization in templates
+ */
 /**
  * Safely evaluates an auth expression within the given context
  * Similar to evaluateExpression but specialized for auth conditionals

package/dist/build-externalize.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Lift shared inline blobs out of built HTML into content-hashed assets.
+ *
+ * The static build inlines the whole signals runtime and the whole generated
+ * stylesheet into every page. On a 35-page site that is ~118KB of
+ * byte-identical runtime per page and a separate copy of the reset in each one,
+ * none of it cacheable across a navigation, and `find dist -name '*.js'`
+ * returns nothing at all (stacksjs/stx#1865, #1878).
+ *
+ * Done as a post-pass over the emitted HTML rather than by threading
+ * `buildMode` through the renderer, deliberately. The existing `compile` branch
+ * emits `/__stx/runtime.__STX_HASH__.js`, a placeholder only the production
+ * builder knows how to rewrite, and setting that mode also suppresses the
+ * document shell — so reusing it on the SSG path produces pages that reference
+ * a 404 and lose their `<html>` wrapper. A post-pass needs neither.
+ *
+ * Content-addressed, so identical blobs across pages collapse to one file: the
+ * runtime is byte-identical everywhere and becomes a single asset, while
+ * per-page CSS dedupes only where pages genuinely share a stylesheet.
+ *
+ * @module build-externalize
+ */
+/** Where externalized assets are written, relative to the output directory. */
+export declare const EXTERNALIZED_ASSET_DIR = "_stx";
+export interface ExternalizeResult {
+    /** HTML files rewritten. */
+    pages: number;
+    /** Distinct asset files written. */
+    assets: number;
+    /** Bytes removed from HTML (before any compression). */
+    bytesInlined: number;
+}
+/**
+ * Rewrite every HTML file under `outDir`, moving the signals runtime and the
+ * generated stylesheet into `_stx/` and linking to them.
+ *
+ * Safe to run twice: a page whose runtime is already a `src=` reference has no
+ * inline body to match, so a second pass is a no-op.
+ */
+export declare function externalizeSharedAssets(outDir: string): ExternalizeResult;