@stacksjs/stx 0.2.9 → 0.2.11

package/dist/ssr.d.ts

@@ -88,6 +88,7 @@ export declare interface AppConfig {
   sessionStore?: SessionStore
 }
 /** Route handler */
+// eslint-disable-next-line pickier/no-unused-vars
 export type RouteHandler = (ctx: RequestContext) => Response | Promise<Response>;
 /** Middleware function */
 export type Middleware = (ctx: RequestContext, next: () => Promise<Response>) => Response | Promise<Response>;

package/dist/state-management.d.ts

@@ -146,6 +146,32 @@ export declare function initDevTools(): void;
  * </script>
  * ```
  */
+/**
+ * Define a store using a setup function (composition API style).
+ * The function receives no arguments and returns an object of signals,
+ * derived values, and action functions.
+ *
+ * ```ts
+ * defineStore('auth', () => {
+ *   const user = state(null)
+ *   const isAuthenticated = derived(() => !!user())
+ *   function login(data) { user.set(data) }
+ *   return { user, isAuthenticated, login }
+ * })
+ * ```
+ */
+export declare function defineStore<T extends Record<string, any>>(id: string, setup: () => T, options?: { persist?: boolean | { pick?: string[], storage?: string, key?: string } }): T;
+/**
+ * Define a store using an options object (options API style).
+ *
+ * ```ts
+ * defineStore('counter', {
+ *   state: () => ({ count: 0 }),
+ *   getters: { doubled: (s) => s.count * 2 },
+ *   actions: { increment() { this.count++ } },
+ * })
+ * ```
+ */
 export declare function defineStore<S extends object, G extends Record<string, (state: S) => any> = Record<string, never>, A extends Record<string, (...args: any[]) => any> = Record<string, never>,>(id: string, options: DefineStoreOptions<S, G, A>): DefinedStoreWithGettersAndActions<S, G, A>;
 /**
  * Get a defined store by name.
@@ -263,6 +289,7 @@ export declare interface DefinedStore<S, G extends Record<string, (state: S) =>
   $id: string
 }
 /** Subscription callback */
+// eslint-disable-next-line pickier/no-unused-vars
 export type Subscriber<T> = (value: T, previousValue: T | undefined) => void;
 /** Unsubscribe function */
 export type Unsubscribe = () => void;

package/dist/store-imports.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Store Import Transformation
+ *
+ * Transforms `import { x } from '@stores'` statements in client scripts
+ * into runtime lookups against the global store registry.
+ *
+ * @module store-imports
+ */
+/**
+ * Transform import statements from @stores to runtime code.
+ *
+ * Transforms:
+ * ```js
+ * import { appStore, chatStore } from '@stores'
+ * ```
+ *
+ * Into:
+ * ```js
+ * const { appStore, chatStore } = window.__STX_STORES__
+ * ```
+ *
+ * Also transforms @composables imports to window.__composables.
+ */
+export declare function transformStoreImports(code: string): string;

package/dist/store-loader.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Discover store files from storesDir and bundle them into a single
+ * script that can be injected into the page.
+ *
+ * The bundle runs `defineStore(...)` for each store — since the signals
+ * runtime is already loaded, `defineStore`/`state`/`derived` are globals.
+ *
+ * Pass an absolute `storesDir` to look up stores there. When omitted, falls
+ * back to reading `storesDir` from the stx config at the current working
+ * directory — which is only correct when run from the app's own root.
+ */
+export declare function getStoreScript(storesDir?: string): Promise<string | null>;
+/**
+ * Clear the cached store script (for dev mode hot reload).
+ */
+export declare function clearStoreCache(): void;

package/dist/story/bun-test.d.ts

@@ -19,6 +19,7 @@ export declare function createStoryTests(options?: BunTestOptions): Promise<void
 /**
  * Run story tests programmatically
  */
+// eslint-disable-next-line pickier/no-unused-vars
 export declare function runStoryTests(options?: BunTestOptions): Promise<{
   passed: number
   failed: number

package/dist/story/compiled-output.d.ts

@@ -2,6 +2,7 @@ import type { ServerStoryFile, StoryContext } from './types';
 /**
  * Get compiled HTML output for a story variant
  */
+// eslint-disable-next-line pickier/no-unused-vars
 export declare function getCompiledOutput(ctx: StoryContext, story: ServerStoryFile, variantId: string, options?: CompiledOutputOptions): Promise<string>;
 /**
  * Generate compiled output panel HTML

package/dist/story/interactions.d.ts

@@ -6,6 +6,7 @@ export declare function parseInteractionBlocks(content: string): InteractionTest
 /**
  * Run interaction tests for a story
  */
+// eslint-disable-next-line pickier/no-unused-vars
 export declare function runInteractionTests(_ctx: StoryContext, story: ServerStoryFile, tests: InteractionTest[]): Promise<InteractionTestResult[]>;
 /**
  * Generate interaction test helpers script (for browser)

package/dist/story/renderer.d.ts

@@ -2,6 +2,7 @@ import type { ServerStoryFile, StoryContext } from './types';
 /**
  * Render a story component with props
  */
+// eslint-disable-next-line pickier/no-unused-vars
 export declare function renderStoryComponent(ctx: StoryContext, componentPath: string, options?: StoryRenderOptions): Promise<StoryRenderResult>;
 /**
  * Render a story variant
@@ -10,6 +11,7 @@ export declare function renderStoryVariant(ctx: StoryContext, story: ServerStory
 /**
  * Render an inline template string
  */
+// eslint-disable-next-line pickier/no-unused-vars
 export declare function renderInlineTemplate(ctx: StoryContext, template: string, props?: Record<string, any>): Promise<StoryRenderResult>;
 /**
  * Clear the story component cache

package/dist/story/setup.d.ts

@@ -44,4 +44,5 @@ export declare interface SetupContext {
 /**
  * Setup function signature
  */
+// eslint-disable-next-line pickier/no-unused-vars
 export type SetupFunction = (ctx: SetupContext) => void | Promise<void>;

package/dist/story/ui/code-panel.d.ts

@@ -2,6 +2,7 @@ import type { AnalyzedComponent, ServerStoryFile } from '../types';
 /**
  * Generate code panel HTML
  */
+// eslint-disable-next-line pickier/no-unused-vars
 export declare function generateCodePanel(story: ServerStoryFile, component: AnalyzedComponent | null, activeTab?: CodePanelTab): string;
 /**
  * Get source code for a component

package/dist/stx.d.ts

@@ -0,0 +1,437 @@
+/**
+ * STX Ambient Type Declarations
+ *
+ * This file is shipped with the @stacksjs/stx package and referenced from
+ * the package's main types entry. When stx is installed, TypeScript picks
+ * these declarations up automatically — apps do NOT need to write their own
+ * stx.d.ts workaround for runtime globals.
+ *
+ * What's declared here:
+ *   1. Module declarations for `*.stx` and `*.md` imports
+ *   2. Runtime globals injected by the stx signals runtime into <script client>
+ *      blocks (signals, lifecycle, stores, composables, head, routing, etc.)
+ *   3. The `window.stx` registry interface
+ *
+ * Source of truth for the auto-imported global list:
+ *   packages/stx/src/client-script.ts → STX_AUTO_IMPORTS
+ *   packages/stx/src/signals.ts → window.stx = { ... }
+ */
+
+// ============================================================================
+// Module declarations
+// ============================================================================
+
+// Allow importing .stx files
+declare module '*.stx'
+
+// Allow importing .md files with frontmatter
+declare module '*.md' {
+  const content: string
+  const data: Record<string, any>
+  export default content
+  export { data }
+}
+
+// ============================================================================
+// Signal types
+// ============================================================================
+
+interface StxSignal<T> {
+  (): T
+  set: (value: T) => void
+  update: (fn: (current: T) => T) => void
+  subscribe: (cb: (value: T) => void) => () => void
+  readonly _isSignal: true
+}
+
+interface StxDerivedSignal<T> {
+  (): T
+  readonly _isSignal: true
+}
+
+interface StxRef<T> {
+  value: T
+}
+
+type StxCleanup = () => void
+
+// ============================================================================
+// Signals (modern reactivity)
+// ============================================================================
+
+declare function state<T>(initial: T): StxSignal<T>
+declare function derived<T>(compute: () => T): StxDerivedSignal<T>
+declare function effect(fn: () => void | StxCleanup): StxCleanup
+declare function batch(fn: () => void): void
+declare function untrack<T>(value: T | StxSignal<T> | StxDerivedSignal<T>): T
+declare function peek<T>(fn: () => T): T
+declare function isSignal(value: unknown): value is StxSignal<unknown>
+declare function isDerived(value: unknown): value is StxDerivedSignal<unknown>
+
+// ============================================================================
+// Lifecycle
+// ============================================================================
+
+declare function onMount(fn: () => void | StxCleanup): void
+declare function onDestroy(fn: () => void): void
+declare function onBeforeMount(fn: () => void): void
+declare function onMounted(fn: () => void | StxCleanup): void
+declare function onBeforeUpdate(fn: () => void): void
+declare function onUpdated(fn: () => void): void
+declare function onBeforeUnmount(fn: () => void): void
+declare function onUnmounted(fn: () => void): void
+declare function onErrorCaptured(fn: (error: unknown, instance: any, info: string) => boolean | void): void
+
+// ============================================================================
+// Template refs
+// ============================================================================
+
+declare function useRef<T = HTMLElement>(name: string): { current: T | null }
+
+// ============================================================================
+// Routing / navigation
+// ============================================================================
+
+declare function navigate(url: string, options?: { replace?: boolean }): void
+declare function goBack(): void
+declare function goForward(): void
+declare function useRoute(): {
+  path: string
+  params: Record<string, string>
+  query: Record<string, string>
+  hash: string
+}
+declare function setRouteParams(params: Record<string, string>): void
+declare function useSearchParams(): {
+  get: (key: string) => string | null
+  set: (key: string, value: string) => void
+  delete: (key: string) => void
+  has: (key: string) => boolean
+}
+
+// ============================================================================
+// Data fetching
+// ============================================================================
+
+interface StxQueryResult<T> {
+  data: StxSignal<T | null>
+  loading: StxSignal<boolean>
+  error: StxSignal<Error | null>
+  refetch: () => Promise<void>
+}
+
+interface StxMutationResult<T> {
+  data: StxSignal<T | null>
+  loading: StxSignal<boolean>
+  error: StxSignal<Error | null>
+  mutate: (body?: any) => Promise<T>
+}
+
+declare function useFetch<T = any>(url: string, options?: any): StxQueryResult<T>
+declare function useQuery<T = any>(url: string, options?: any): StxQueryResult<T>
+declare function useMutation<T = any>(url: string, options?: any): StxMutationResult<T>
+
+// ============================================================================
+// DOM utilities
+// ============================================================================
+
+declare function useEventListener<K extends keyof WindowEventMap>(
+  target: Window | Document | HTMLElement | string | null,
+  event: K,
+  handler: (event: WindowEventMap[K]) => void,
+  options?: boolean | AddEventListenerOptions,
+): StxCleanup
+declare function useEventListener(
+  target: Window | Document | HTMLElement | string | null,
+  event: string,
+  handler: (event: Event) => void,
+  options?: boolean | AddEventListenerOptions,
+): StxCleanup
+declare function useMeta(meta: Record<string, string>): void
+declare function useClickOutside(target: any, handler: (event: MouseEvent) => void): StxCleanup
+declare function useFocus(target: any): { focused: StxSignal<boolean>, focus: () => void, blur: () => void }
+
+// ============================================================================
+// Timers / scheduling
+// ============================================================================
+
+declare function useDebounce<T extends (...args: any[]) => any>(fn: T, delay: number): T
+declare function useDebouncedValue<T>(value: StxSignal<T>, delay: number): StxSignal<T>
+declare function useThrottle<T extends (...args: any[]) => any>(fn: T, delay: number): T
+declare function useInterval(fn: () => void, ms: number, options?: { immediate?: boolean }): {
+  start: () => void
+  stop: () => void
+  isActive: StxSignal<boolean>
+}
+declare function useTimeout(fn: () => void, ms: number): {
+  start: () => void
+  stop: () => void
+  isPending: StxSignal<boolean>
+}
+declare function nextTick(fn?: () => void): Promise<void>
+
+// ============================================================================
+// State utilities
+// ============================================================================
+
+declare function useToggle(initial?: boolean): [StxSignal<boolean>, (value?: boolean) => void]
+declare function useCounter(initial?: number, options?: { min?: number, max?: number }): {
+  count: StxSignal<number>
+  inc: (n?: number) => void
+  dec: (n?: number) => void
+  set: (n: number) => void
+  reset: () => void
+}
+declare function useAsync<T>(fn: () => Promise<T>): {
+  data: StxSignal<T | null>
+  loading: StxSignal<boolean>
+  error: StxSignal<Error | null>
+  execute: () => Promise<T>
+}
+
+// ============================================================================
+// Storage
+// ============================================================================
+
+declare function useLocalStorage<T>(key: string, defaultValue: T): StxSignal<T>
+declare function useSessionStorage<T>(key: string, defaultValue: T): StxSignal<T>
+
+// ============================================================================
+// WebSocket
+// ============================================================================
+
+declare function useWebSocket(url: string, options?: {
+  immediate?: boolean
+  autoReconnect?: boolean | { retries?: number, delay?: number }
+  onMessage?: (event: MessageEvent) => void
+  onConnected?: () => void
+  onDisconnected?: () => void
+  onError?: (event: Event) => void
+}): {
+  status: StxSignal<'CONNECTING' | 'OPEN' | 'CLOSING' | 'CLOSED'>
+  data: StxSignal<any>
+  send: (data: string | ArrayBuffer | Blob) => void
+  open: () => void
+  close: () => void
+  ws: WebSocket | null
+}
+
+// ============================================================================
+// Color mode
+// ============================================================================
+
+declare function useColorMode(): {
+  mode: StxSignal<'light' | 'dark' | 'auto'>
+  setMode: (mode: 'light' | 'dark' | 'auto') => void
+}
+declare function useDark(): StxSignal<boolean>
+
+// ============================================================================
+// Head / SEO
+// ============================================================================
+
+interface StxHeadConfig {
+  title?: string
+  titleTemplate?: string | ((title?: string) => string)
+  meta?: Array<Record<string, string>>
+  link?: Array<Record<string, string>>
+  script?: Array<Record<string, string> & { children?: string }>
+  style?: Array<Record<string, string> & { children?: string }>
+  htmlAttrs?: Record<string, string>
+  bodyAttrs?: Record<string, string>
+}
+
+interface StxSeoMetaConfig {
+  title?: string
+  description?: string
+  keywords?: string
+  author?: string
+  ogTitle?: string
+  ogDescription?: string
+  ogImage?: string
+  ogUrl?: string
+  ogType?: string
+  twitterCard?: 'summary' | 'summary_large_image' | 'app' | 'player'
+  twitterTitle?: string
+  twitterDescription?: string
+  twitterImage?: string
+  robots?: string
+  canonical?: string
+}
+
+declare function useHead(config: StxHeadConfig): void
+declare function useSeoMeta(config: StxSeoMetaConfig): void
+
+// ============================================================================
+// Vue-style reactivity (alternative API)
+// ============================================================================
+
+declare function ref<T>(value: T): StxRef<T>
+declare function reactive<T extends object>(target: T): T
+declare function computed<T>(getter: () => T): StxRef<T>
+declare function watch<T>(
+  source: (() => T) | StxRef<T> | StxSignal<T>,
+  callback: (value: T, oldValue: T) => void,
+  options?: { immediate?: boolean, deep?: boolean },
+): StxCleanup
+declare function watchEffect(fn: () => void): StxCleanup
+declare function watchMultiple(
+  sources: Array<() => any>,
+  callback: (values: any[], oldValues: any[]) => void,
+  options?: { immediate?: boolean },
+): StxCleanup
+
+// ============================================================================
+// Component definition / composition API
+// ============================================================================
+
+declare function defineProps<T extends Record<string, any> = Record<string, any>>(definitions?: any): T
+declare function withDefaults<T extends Record<string, any>>(props: T, defaults: Partial<T>): T
+declare function defineEmits<T extends string = string>(): (event: T, payload?: any) => void
+declare function defineExpose<T extends Record<string, any>>(exposed: T): void
+declare function provide<T>(key: string | symbol, value: T): void
+declare function inject<T>(key: string | symbol, defaultValue?: T): T | undefined
+declare function getCurrentInstance(): any
+declare function useSlots(): Record<string, any>
+declare function useAttrs(): Record<string, any>
+declare function $computed<T>(getter: () => T): StxRef<T>
+declare function $watch<T>(
+  source: (() => T) | StxRef<T> | StxSignal<T>,
+  callback: (value: T, oldValue: T) => void,
+  options?: { immediate?: boolean, deep?: boolean },
+): StxCleanup
+
+// ============================================================================
+// Stores (Pinia-inspired, signals-based)
+// ============================================================================
+
+interface StxStorePersistOptions {
+  pick?: string[]
+  storage?: 'localStorage' | 'sessionStorage'
+  key?: string
+}
+
+interface StxStoreOptions {
+  persist?: boolean | StxStorePersistOptions
+}
+
+declare function defineStore<T>(
+  id: string,
+  setup: () => T,
+  options?: StxStoreOptions,
+): () => T
+declare function defineStore<S extends Record<string, any>, G extends Record<string, any>, A extends Record<string, any>>(
+  id: string,
+  options: {
+    state?: () => S
+    getters?: G
+    actions?: A
+    persist?: boolean | StxStorePersistOptions
+  },
+): () => S & G & A
+declare function useStore<T = any>(id: string): T
+declare function createStore<T>(setup: () => T, options?: StxStoreOptions): () => T
+declare function action<T extends (...args: any[]) => any>(fn: T): T
+declare function createSelector<T, R>(selector: (state: T) => R): (state: T) => R
+
+// ============================================================================
+// JSX runtime (Vue/React style)
+// ============================================================================
+
+declare function h(tag: string | Function, props?: Record<string, any> | null, ...children: any[]): any
+declare const Fragment: unique symbol
+
+// ============================================================================
+// window.stx registry
+// ============================================================================
+
+interface StxRuntimeRegistry {
+  // Signals
+  state: typeof state
+  derived: typeof derived
+  effect: typeof effect
+  batch: typeof batch
+  untrack: typeof untrack
+  peek: typeof peek
+  isSignal: typeof isSignal
+
+  // Lifecycle
+  onMount: typeof onMount
+  onDestroy: typeof onDestroy
+
+  // Composables
+  useFetch: typeof useFetch
+  useRef: typeof useRef
+  useQuery: typeof useQuery
+  useMutation: typeof useMutation
+
+  // Routing
+  navigate: typeof navigate
+  goBack: typeof goBack
+  goForward: typeof goForward
+  useRoute: typeof useRoute
+  setRouteParams: typeof setRouteParams
+  useSearchParams: typeof useSearchParams
+
+  // Composition
+  provide: typeof provide
+  defineProps: typeof defineProps
+  withDefaults: typeof withDefaults
+  defineEmits: typeof defineEmits
+  defineExpose: typeof defineExpose
+
+  // Vue compat
+  ref: typeof ref
+  reactive: typeof reactive
+  computed: typeof computed
+  watch: typeof watch
+  watchEffect: typeof watchEffect
+  $computed: typeof $computed
+  $watch: typeof $watch
+
+  // Utilities
+  useDebounce: typeof useDebounce
+  useDebouncedValue: typeof useDebouncedValue
+  useThrottle: typeof useThrottle
+  useInterval: typeof useInterval
+  useTimeout: typeof useTimeout
+  useToggle: typeof useToggle
+  useCounter: typeof useCounter
+  useClickOutside: typeof useClickOutside
+  useFocus: typeof useFocus
+  useAsync: typeof useAsync
+  useLocalStorage: typeof useLocalStorage
+  useEventListener: typeof useEventListener
+  useWebSocket: typeof useWebSocket
+  useColorMode: typeof useColorMode
+  useDark: typeof useDark
+  useHead: typeof useHead
+  useSeoMeta: typeof useSeoMeta
+
+  // Stores
+  defineStore: typeof defineStore
+  useStore: typeof useStore
+
+  // Mount API
+  mount: (setupFn: () => any) => void
+  mountEl: (selector: string, setupFn: () => any) => void
+
+  // Helpers (template helpers — populated by app)
+  helpers: Record<string, any>
+
+  // Internals (escape hatch)
+  [key: string]: any
+}
+
+// Bare global so existing code that references `stx` (without `window.`) still works
+declare const stx: StxRuntimeRegistry
+
+// Augment Window so `window.stx` is typed
+interface Window {
+  stx: StxRuntimeRegistry
+  __STX_STORES__?: Record<string, any>
+  __STX_CURRENT_PROPS__?: Record<string, any>
+  __STX_CURRENT_ELEMENT__?: HTMLElement | null
+  __stxRouter?: boolean
+  __stxRouterConfig?: Record<string, any>
+}

package/dist/style-scoping.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Process all `<style scoped>` blocks in a template.
+ *
+ * For each `<style scoped>` block:
+ * 1. Generates a deterministic hash from the file path
+ * 2. Prefixes all CSS selectors with `[data-v-{hash}]`
+ * 3. Adds `data-v-{hash}` attribute to all top-level HTML elements
+ * 4. Replaces the `<style scoped>` tag with scoped CSS
+ *
+ * Non-scoped `<style>` tags pass through unchanged.
+ *
+ * @param template - The HTML template string
+ * @param filePath - Source file path (used for deterministic hash generation)
+ * @returns Processed template with scoped styles
+ */
+export declare function processScopedStyles(template: string, filePath: string): ScopedStyleResult;
+/**
+ * Result of processing scoped styles in a template
+ */
+export declare interface ScopedStyleResult {
+  html: string
+  hasScoped: boolean
+}

package/dist/template-compiler.d.ts

@@ -0,0 +1,31 @@
+import { type PlaceholderMap } from './placeholder';
+/**
+ * Compile a single .stx template file.
+ *
+ * Runs the full processDirectives pipeline in build mode ('compile'),
+ * producing pre-rendered HTML with placeholder tokens for dynamic content.
+ *
+ * @param filePath - Absolute path to the .stx file
+ * @param route - The URL route this page serves (e.g. '/jobs')
+ * @param options - Additional compilation options
+ */
+export declare function compileTemplate(filePath: string, route: string, options?: {
+    componentsDir?: string
+    partialsDir?: string
+    layoutsDir?: string
+    debug?: boolean
+  }): Promise<CompiledTemplate>;
+/**
+ * A pre-compiled template ready for serve-time hydration.
+ */
+export declare interface CompiledTemplate {
+  route: string
+  sourceFile: string
+  html: string
+  fragment: string
+  placeholders: PlaceholderMap
+  hasServerScripts: boolean
+  serverScriptContent: string[]
+  dependencies: string[]
+  contentHash: string
+}

package/dist/template-hydrator.d.ts

@@ -0,0 +1,18 @@
+import type { CompiledTemplate } from './template-compiler';
+/**
+ * Hydrate a pre-compiled template with request-time data.
+ *
+ * This is the serve-time counterpart to compileTemplate(). It takes a
+ * compiled template (with placeholder tokens) and a request context,
+ * executes server scripts, evaluates expressions, and returns final HTML.
+ *
+ * @param compiled - The pre-compiled template from build time
+ * @param requestContext - Request-time context (route params, session, etc.)
+ * @returns Final HTML ready to send to the browser
+ */
+export declare function hydrateTemplate(compiled: CompiledTemplate, requestContext?: Record<string, any>): Promise<string>;
+/**
+ * Hydrate a fragment (for SPA navigation).
+ * Same as hydrateTemplate but returns the fragment portion.
+ */
+export declare function hydrateFragment(compiled: CompiledTemplate, requestContext?: Record<string, any>): Promise<string>;

package/dist/transitions.d.ts

@@ -31,6 +31,7 @@ export declare function generateTransitionRuntime(): string;
  *   <div @transition.slide-up.300="isOpen">Content</div>
  */
 export declare function processTransitionAttributes(template: string): string;
+/* eslint-disable prefer-const, style/max-statements-per-line, no-super-linear-backtracking, regexp/no-unused-capturing-group */
 /**
  * STX Transitions
  *