@stacksjs/stx 0.2.10 → 0.2.12

package/dist/client-helpers.d.ts

@@ -1,3 +1,4 @@
+/* eslint-disable prefer-const, style/max-statements-per-line, no-super-linear-backtracking, regexp/no-unused-capturing-group */
 /**
  * Client-side helper utilities for stx applications.
  * Injected as a <script> tag to provide common UI patterns.
@@ -130,7 +131,8 @@ export declare const stxClientHelpers: `
       if (rows) {
         if (!Array.isArray(rows) && typeof rows === 'object') {
           Object.keys(rows).forEach(function(k) { inner += stx.detail.row(k, rows[k]) })
-        } else {
+        }
+else {
           rows.forEach(function(r) {
             if (Array.isArray(r)) inner += stx.detail.row(r[0], r[1])
             else inner += stx.detail.row(r.label, r.value)
@@ -273,9 +275,11 @@ export declare const stxClientHelpers: `
         pages.forEach(function(p) {
           if (p === '...') {
             h += '<span class="px-2 text-sm" style="color:var(--text-muted)">\\u2026</span>'
-          } else if (p === page) {
+          }
+else if (p === page) {
             h += \`<button class="w-9 h-9 rounded-lg text-sm font-medium" style="background:var(--btn-primary-bg, var(--text-accent));color:#fff">\${p}</button>\`
-          } else {
+          }
+else {
             h += btn(p, p, false)
           }
         })

package/dist/client-script-bundler.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Check if a script has user imports that need Bun.build bundling.
+ *
+ * Returns false for:
+ * - `import type { ... }` (type-only — stripped by TS transpiler)
+ * - `import { ... } from 'stx'` (auto-imported from window.stx)
+ * - `import { ... } from '@stacksjs/browser'` (auto-imported)
+ * - `import { ... } from '@stores'` (handled by transformStoreImports)
+ * - `import { ... } from '@composables'` (handled by transformStoreImports)
+ */
+export declare function hasUserImports(code: string): boolean;
+/**
+ * Bundle a client script using Bun.build.
+ *
+ * Resolves local imports (@/, ./), npm packages, and tree-shakes unused exports.
+ * stx runtime, @stores, and @composables are marked as external.
+ *
+ * @param code - The script content (may contain import statements)
+ * @param filePath - The .stx template file path (for relative import resolution)
+ * @param options - Bundling options
+ * @returns Bundled code with all imports resolved and inlined
+ */
+export declare function bundleClientScript(code: string, filePath: string, options?: {
+    projectRoot?: string
+    minify?: boolean
+    cacheDir?: string
+  }): Promise<string>;

package/dist/client-script.d.ts

@@ -11,7 +11,7 @@ import type { ParsedEvent } from './events';
  * @param options - Event bindings and other processing options
  * @returns A complete `<script>...</script>` tag ready for browser injection
  */
-export declare function processClientScript(scriptContent: string, options?: ClientScriptOptions): string;
+export declare function processClientScript(scriptContent: string, options?: ClientScriptOptions): Promise<string>;
 // =============================================================================
 // Types
 // =============================================================================
@@ -20,4 +20,8 @@ export declare interface ClientScriptOptions {
   autoImports?: boolean
   attrs?: string
   hasColonDirectives?: boolean
+  templateContent?: string
+  filePath?: string
+  projectRoot?: string
+  production?: boolean
 }

package/dist/client.d.ts

@@ -17,4 +17,5 @@ declare type IslandHandlers = Record<string, () => Promise<any>>;
 /**
  * Island hydration function
  */
+// eslint-disable-next-line pickier/no-unused-vars
 declare type IslandHydrationFn = (element: any, props: any) => void | Promise<void>;

package/dist/component-hmr.d.ts

@@ -14,6 +14,7 @@ export declare function getHMRHandler(config?: ComponentHMRConfig): ComponentHMR
  * Reset global HMR handler
  */
 export declare function resetHMRHandler(): void;
+/* eslint-disable prefer-const, style/max-statements-per-line, no-super-linear-backtracking, regexp/no-unused-capturing-group */
 /**
  * Component HMR (Hot Module Replacement)
  *

package/dist/component-processing.d.ts

@@ -0,0 +1,107 @@
+import type { StxOptions } from './types';
+/**
+ * Convert PascalCase to kebab-case with proper handling of consecutive uppercase letters.
+ *
+ * Examples:
+ * - `UserCard` → `user-card`
+ * - `XMLParser` → `xml-parser` (not `x-m-l-parser`)
+ * - `HTMLElement` → `html-element`
+ * - `MyURLParser` → `my-url-parser`
+ * - `IOStream` → `io-stream`
+ *
+ * The algorithm:
+ * 1. Insert hyphen before uppercase letters that follow lowercase letters
+ * 2. Insert hyphen before the last uppercase in a sequence of uppercase letters (before lowercase)
+ * 3. Convert to lowercase
+ */
+export declare function pascalToKebab(str: string): string;
+/**
+ * Find component tags in HTML, properly handling quoted strings
+ * This solves the issue where `>` inside attribute values would incorrectly end the tag
+ *
+ * @param html - The HTML string to search
+ * @param tagPattern - Regex pattern for tag name (for PascalCase components)
+ * @param skipTags - Optional set of tag names to skip (for HTML tags)
+ * @returns Array of found component tags
+ */
+export declare function findComponentTags(html: string, tagPattern: RegExp, skipTags?: Set<string>): ComponentTagMatch[];
+/**
+ * Parse multiline attributes from a component tag
+ * Handles HTML content inside attribute values correctly
+ *
+ * @param attributesStr - The attributes string (may be multiline)
+ * @returns Object mapping attribute names to values
+ */
+export declare function parseMultilineAttributes(attributesStr: string): Record<string, string>;
+export declare function parseAttributes(attributesStr: string): ParsedAttribute[];
+/**
+ * Process built-in STX components like <stx-loading-indicator>
+ */
+export declare function processBuiltInComponents(template: string, _context: Record<string, any>, _filePath: string, _options: StxOptions): Promise<string>;
+/**
+ * Process @import directives for explicit component imports.
+ *
+ * Syntax:
+ *   @import('components/Card')
+ *   @import('ui/Button', 'ui/Modal')
+ *   @import('Card', 'Button', 'Modal')
+ *
+ * This allows explicit importing of components from any path,
+ * overriding the auto-import from the components directory.
+ */
+export declare function processImportDirectives(template: string, context: Record<string, any>, filePath: string, options: StxOptions, dependencies: Set<string>): Promise<string>;
+/**
+ * Process @component directives
+ */
+export declare function processComponentDirectives(template: string, context: Record<string, any>, filePath: string, componentsDir: string, options: StxOptions, dependencies: Set<string>): Promise<string>;
+/**
+ * Process custom element components (both kebab-case and PascalCase)
+ * Uses a proper parser that handles HTML content inside attribute values
+ */
+export declare function processCustomElements(template: string, context: Record<string, any>, filePath: string, componentsDir: string, options: StxOptions, dependencies: Set<string>): Promise<string>;
+/**
+ * Parse HTML/JSX-like attributes from a string.
+ *
+ * Properly handles:
+ * - Simple attributes: `name="value"`
+ * - Boolean attributes: `disabled`
+ * - Dynamic values: `prop="{{ expr }}"` (evaluated at SSR)
+ * - Attributes with `=` in values: `url="https://example.com?a=1&b=2"`
+ * - Single and double quoted values
+ * - Escaped quotes within values
+ *
+ * ## Dynamic Data Syntax
+ *
+ * Use `{{ }}` for all dynamic data interpolation:
+ * ```html
+ * <Component title="{{ pageTitle }}" count="{{ items.length }}" />
+ * <div class="{{ isActive ? 'active' : '' }}">{{ content }}</div>
+ * ```
+ *
+ * ## Event Syntax (Alpine-style)
+ *
+ * ```html
+ * <button @click="handleClick()">Click me</button>
+ * <form @submit.prevent="handleSubmit()">...</form>
+ * <input @keydown.enter="send()" @keydown.escape="cancel()">
+ * ```
+ *
+ * @param attributesStr - The attributes portion of a tag (between tag name and closing)
+ * @returns Array of parsed attributes with name and value
+ */
+export declare interface ParsedAttribute {
+  name: string
+  value: string | true
+}
+/**
+ * Component tag match result
+ */
+export declare interface ComponentTagMatch {
+  fullMatch: string
+  tagName: string
+  attributes: string
+  content: string
+  startIndex: number
+  endIndex: number
+  isSelfClosing: boolean
+}

package/dist/component-registry.d.ts

@@ -0,0 +1,54 @@
+import type { StxOptions } from './types';
+/**
+ * Convert a kebab-case string to PascalCase.
+ *
+ * @example kebabToPascal("stx-link") // "StxLink"
+ */
+export declare function kebabToPascal(str: string): string;
+/**
+ * Convert a PascalCase string to kebab-case.
+ *
+ * @example pascalToKebab("StxLink") // "stx-link"
+ */
+export declare function pascalToKebab(str: string): string;
+/** Singleton registry instance shared across the framework */
+export declare const registry: ComponentRegistry;
+/**
+ * Context passed to builtin component render functions.
+ */
+export declare interface RenderContext {
+  context: Record<string, any>
+  filePath: string
+  options: StxOptions
+  dependencies: Set<string>
+}
+/**
+ * Props resolved from component attributes, categorized by binding type.
+ */
+export declare interface ResolvedProps {
+  static: Record<string, string | boolean>
+  serverDynamic: Record<string, unknown>
+  clientReactive: Record<string, string>
+  events: Record<string, string>
+}
+/**
+ * Definition for a builtin component that renders without a .stx file.
+ */
+export declare interface BuiltinComponentDef {
+  name: string
+  aliases: string[]
+  render(props: ResolvedProps, slotContent: string, ctx: RenderContext): string
+}
+/**
+ * Central registry for STX components.
+ *
+ * Manages builtin components (registered in-memory) and provides
+ * file-based component resolution with multi-directory search.
+ */
+export declare class ComponentRegistry {
+  builtins: Map<string, BuiltinComponentDef>;
+  registerBuiltin(def: BuiltinComponentDef): void;
+  isBuiltin(name: string): boolean;
+  getBuiltin(name: string): BuiltinComponentDef | null;
+  resolveFile(name: string, fromFile: string, options: StxOptions, parentContext?: Record<string, any>): Promise<string | null>;
+}

package/dist/component-renderer.d.ts

@@ -0,0 +1,18 @@
+import type { StxOptions } from './types';
+/**
+ * Unified component processing entry point.
+ *
+ * Processes all component-related syntax in the template in the correct order:
+ * 1. Register builtin components (once)
+ * 2. Process `@import` directives
+ * 3. Process `@component` directives
+ * 4. Process custom element tags (builtins and file-based)
+ *
+ * @param template - The template string to process
+ * @param context - Template variable context
+ * @param filePath - Absolute path of the template being processed
+ * @param options - Compiler options
+ * @param dependencies - Set to track file dependencies for cache invalidation
+ * @returns The processed template with all components rendered
+ */
+export declare function processComponents(template: string, context: Record<string, any>, filePath: string, options: StxOptions, dependencies: Set<string>): Promise<string>;

package/dist/components/StxImage.stx

@@ -0,0 +1,12 @@
+<img
+  src='{{ src }}'
+  alt='{{ alt || "" }}'
+  @if(typeof width !== 'undefined' && width) width='{{ width }}' @endif
+  @if(typeof height !== 'undefined' && height) height='{{ height }}' @endif
+  loading='{{ typeof lazy !== "undefined" && lazy === false ? "eager" : "lazy" }}'
+  decoding='async'
+  @if(typeof sizes !== 'undefined' && sizes) sizes='{{ sizes }}' @endif
+  @if(typeof srcset !== 'undefined' && srcset) srcset='{{ srcset }}' @endif
+  @if(typeof placeholder !== 'undefined' && placeholder) style='background-image: url({{ placeholder }}); background-size: cover;' @endif
+  class='{{ className || "" }}'
+/>

package/dist/components/StxLink.stx

@@ -1,8 +1,18 @@
-<a
-  href="{{ to }}"
-  class="{{ className || '' }}"
-  data-stx-link
-  data-stx-active-class="{{ activeClass || 'active' }}"
-  data-stx-exact-active-class="{{ exactActiveClass || 'exact-active' }}"
-  @if(typeof prefetch !== 'undefined' && prefetch) data-stx-prefetch @endif
->{!! slot !!}</a>
+@if(typeof __bindTo !== 'undefined' && __bindTo)
+<stx-link
+  :to="{{ __bindTo }}"
+  class='{{ className || "" }}'
+  active-class='{{ activeClass || "active" }}'
+  exact-active-class='{{ exactActiveClass || "exact-active" }}'
+  @if(typeof prefetch !== 'undefined' && prefetch) prefetch @endif
+>{!! slot !!}</stx-link>
+@endif
+@if(typeof __bindTo === 'undefined' || !__bindTo)
+<stx-link
+  to='{{ to }}'
+  class='{{ className || "" }}'
+  active-class='{{ activeClass || "active" }}'
+  exact-active-class='{{ exactActiveClass || "exact-active" }}'
+  @if(typeof prefetch !== 'undefined' && prefetch) prefetch @endif
+>{!! slot !!}</stx-link>
+@endif

package/dist/composables/index.d.ts

@@ -243,6 +243,13 @@ export {
   type WebSocketOptions,
   type WebSocketRef,
 } from './use-websocket';
+// Broadcasting Channels (ts-broadcasting)
+export {
+  useChannel,
+  type ChannelState,
+  type ChannelOptions,
+  type ChannelRef,
+} from './use-channel';
 // Device Orientation & Motion
 export {
   useDeviceOrientation,

package/dist/composables/use-broadcast-channel.d.ts

@@ -55,4 +55,5 @@ export declare interface BroadcastChannelRef<T = unknown> {
   isSupported: () => boolean
 }
 declare type BroadcastEventType = 'message' | 'error';
+// eslint-disable-next-line pickier/no-unused-vars
 declare type BroadcastEventCallback = (data: MessageEvent) => void;

package/dist/composables/use-channel.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Subscribe to a broadcasting channel.
+ *
+ * Connects to the stx broadcasting server via WebSocket, subscribes
+ * to the named channel, and pushes every incoming event through the
+ * reactive subscriber set.
+ *
+ * @param channelName - Channel to subscribe to (e.g. `'notifications'`, `'private-orders.123'`)
+ * @param options     - Connection options (host, port, reconnect behaviour)
+ */
+export declare function useChannel<T = unknown>(channelName: string, options?: ChannelOptions): ChannelRef<T>;
+/**
+ * Broadcasting Channel Composables
+ *
+ * Reactive client-side subscriptions to ts-broadcasting channels.
+ * Auto-connects to the stx broadcasting server, handles the WebSocket
+ * protocol, and provides a subscriber-based reactive API.
+ *
+ * @example
+ * ```ts
+ * const channel = useChannel<{ count: number }>('metrics')
+ *
+ * channel.subscribe((state) => {
+ *   console.log(state.data)        // latest event payload
+ *   console.log(state.isSubscribed) // channel subscription status
+ *   console.log(state.isConnected)  // WebSocket connection status
+ * })
+ *
+ * // Listen for a specific event
+ * channel.on('metrics.updated', (data) => {
+ *   document.getElementById('cpu').textContent = data.cpu
+ * })
+ *
+ * // Clean up
+ * channel.close()
+ * ```
+ */
+// ── Types ──────────────────────────────────────────────────────
+export declare interface ChannelState<T = unknown> {
+  data: T | null
+  event: string | null
+  isSubscribed: boolean
+  isConnected: boolean
+  socketId: string | null
+}
+export declare interface ChannelOptions {
+  host?: string
+  port?: number
+  scheme?: 'ws' | 'wss'
+  autoConnect?: boolean
+  autoReconnect?: boolean
+  maxReconnectAttempts?: number
+  reconnectDelay?: number
+}
+export declare interface ChannelRef<T = unknown> {
+  get: () => ChannelState<T>
+  subscribe: (fn: (state: ChannelState<T>) => void) => () => void
+  on: (event: string, callback: (data: any) => void) => () => void
+  close: () => void
+  open: () => void
+}
+// ── Helpers ────────────────────────────────────────────────────
+declare global {
+  interface Window {
+  __stx_broadcasting?: { port?: number, host?: string, scheme?: string }
+}
+}

package/dist/composables/use-intersection-observer.d.ts

@@ -5,6 +5,7 @@ export declare function useIntersectionObserver(target: Element | (() => Element
 /**
  * Simple visibility check - returns true when element is in viewport
  */
+// eslint-disable-next-line pickier/no-unused-vars
 export declare function useElementVisibility(target: Element | (() => Element | null) | null, options?: Omit<IntersectionObserverOptions, 'once'>): {
   get: () => boolean
   subscribe: (fn: (visible: boolean) => void) => () => void
@@ -78,4 +79,5 @@ export declare interface IntersectionObserverRef {
   stop: () => void
   start: () => void
 }
+// eslint-disable-next-line pickier/no-unused-vars
 declare type IntersectionCallback = (entry: IntersectionObserverEntry, observer: IntersectionObserver) => void;

package/dist/composables/use-keyboard.d.ts

@@ -96,4 +96,5 @@ export declare interface HotkeyOptions {
   keyup?: boolean
   ignoreInputs?: boolean
 }
+// eslint-disable-next-line pickier/no-unused-vars
 declare type HotkeyCallback = (event: KeyboardEvent) => void;

package/dist/composables/use-mouse.d.ts

@@ -5,6 +5,7 @@ export declare function useMouse(options?: MouseOptions): MouseRef;
 /**
  * Track mouse position relative to an element
  */
+// eslint-disable-next-line pickier/no-unused-vars
 export declare function useMouseInElement(element: HTMLElement | (() => HTMLElement | null) | null, options?: Omit<MouseOptions, 'target'>): ElementMouseRef;
 /**
  * Track pointer (unified mouse + touch + pen)

package/dist/composables/use-router.d.ts

@@ -27,6 +27,10 @@ export declare function goForward(): void;
  * ```
  */
 export declare function useRoute(): RouteInfo;
+/**
+ * Set route params (called by server injection or page scripts).
+ */
+export declare function setRouteParams(params: Record<string, string>): void;
 /**
  * Reactive URL search parameters with get/set/setAll methods.
  *

package/dist/composables/use-websocket.d.ts

@@ -66,4 +66,5 @@ export declare interface WebSocketRef<T = unknown> {
  */
 export type WebSocketStatus = 'connecting' | 'open' | 'closing' | 'closed';
 declare type WebSocketEventType = 'open' | 'message' | 'close' | 'error';
+// eslint-disable-next-line pickier/no-unused-vars
 declare type WebSocketEventCallback = (event: Event | MessageEvent | CloseEvent) => void;

package/dist/composables.d.ts

@@ -245,6 +245,7 @@ export declare interface ComponentInstance {
   watchers: Array<{ stop: () => void }>
   isMounted: boolean
 }
+/* eslint-disable prefer-const, style/max-statements-per-line, no-super-linear-backtracking, regexp/no-unused-capturing-group */
 /**
  * STX Composables
  *
@@ -260,6 +261,7 @@ export declare interface ComponentInstance {
 // =============================================================================
 export type LifecycleHook = () => void | (() => void);
 export type CleanupFn = () => void;
+// eslint-disable-next-line pickier/no-unused-vars
 export type WatchCallback<T> = (newValue: T, oldValue: T | undefined) => void | CleanupFn;
 export type WatchSource<T> = () => T;
 /** Symbol for injection keys */

package/dist/composition-api.d.ts

@@ -174,4 +174,5 @@ export declare interface StxComponentInstance {
   isMounted: boolean
 }
 /** Type-safe emit function */
+// eslint-disable-next-line pickier/no-unused-vars
 export type EmitFn<T extends string = string> = (event: T, ...args: any[]) => void;

package/dist/computed.d.ts

@@ -22,6 +22,7 @@ export declare function shallowRef<T>(initialValue: T): Ref<T>;
  * Create a computed property with automatic dependency tracking
  */
 export declare function computed<T>(getter: () => T): ComputedRef<T>;
+// eslint-disable-next-line pickier/no-unused-vars
 export declare function computed<T>(options: ComputedOptions<T>): WritableComputedRef<T>;
 /**
  * Watch a reactive source and run a callback when it changes

package/dist/config.d.ts

@@ -1,5 +1,16 @@
+import path from 'node:path';
 import type { StxConfig, StxOptions } from './types';
-export declare function loadStxConfig(): Promise<StxConfig>;
+/**
+ * Load the stx config for a project.
+ *
+ * `cwd` lets the caller specify which directory to search in — critical for
+ * the dev server, which may be invoked as `stx <app-dir>` from outside the
+ * app. Without it, `process.cwd()` is used, which can accidentally pick up
+ * a stray `stx.config.ts` / `.config/stx.ts` from a parent directory.
+ *
+ * Results are cached per cwd so repeated calls don't re-read disk.
+ */
+export declare function loadStxConfig(cwd?: string): Promise<StxConfig>;
 /**
  * Helper function to define stx configuration
  */

package/dist/craft-bridge.d.ts

@@ -111,7 +111,8 @@ export declare const CRAFT_BRIDGE_SCRIPT: `
     let data;
     try {
       data = event.detail || (typeof event.data === 'string' ? JSON.parse(event.data) : event.data);
-    } catch (e) {
+    }
+catch (e) {
       return;
     }
 
@@ -128,11 +129,13 @@ export declare const CRAFT_BRIDGE_SCRIPT: `
         pending.delete(data.id);
         if (data.error) {
           req.reject(new Error(data.error.message));
-        } else {
+        }
+else {
           req.resolve(data.result);
         }
       }
-    } else if (data.type === 'event' && data.method) {
+    }
+else if (data.type === 'event' && data.method) {
       const listeners = eventListeners.get(data.method) || [];
       listeners.forEach(fn => fn(data.params));
     }

package/dist/craft-components.d.ts

@@ -370,6 +370,7 @@ export declare const CRAFT_COMPONENT_STYLES: `
 }
 </style>
 `;
+/* eslint-disable prefer-const, style/max-statements-per-line, no-super-linear-backtracking, regexp/no-unused-capturing-group */
 /**
  * Craft Native Components for stx
  *