@stacksjs/stx 0.2.155 → 0.2.157

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

@@ -0,0 +1,91 @@
+/**
+ * useForm — reactive form state reachable from a <script client> block
+ * (stacksjs/stx#1846, renamed in #1843).
+ *
+ * Named `defineForm` until it turned out to be the odd one out. In this
+ * codebase `define*` DECLARES — defineProps, defineEmits, defineExpose,
+ * definePageMeta, defineSlots, defineStore — while `use*` returns live reactive
+ * state: useFetch, useCookie, useMutation, useDark. This returns signal-backed
+ * state and a handleSubmit, so it was a `use*` wearing a `define*` name, and the
+ * file being called use-form.ts while exporting defineForm meant grepping for
+ * either one found the wrong half.
+ *
+ * `defineForm` remains as a deprecated alias below.
+ *
+ * ---
+ *
+ * THERE IS A SECOND `useForm`, in @stacksjs/composables
+ * (storage/framework/core/composables/src/useForm.ts). It is not this one, and
+ * the two are not interchangeable — they were written independently because
+ * neither side could find the other's, which is #1843's adoption problem
+ * happening to the framework itself.
+ *
+ *   this one                        @stacksjs/composables
+ *   useForm(schema, initialValues)  useForm({ initialValues, onSubmit })
+ *   form.values.email               form.values.value.email
+ *   form.getFieldState('email')     form.field('email')
+ *   v.required().email()            schema.string().email()  (ts-validation)
+ *   validate() -> Promise<string[]> validate() -> { valid, errors }
+ *   has: validating, validateField  has: isSubmitting, isValid, isDirty,
+ *                                        setErrors (422), clearErrors,
+ *                                        submitButtonProps, firstErrorField,
+ *                                        aria inputProps
+ *
+ * Before adding a feature here, check whether it exists there — and say so in
+ * the PR either way. Unifying them is a breaking change to one side's public
+ * API, not a re-export, so it needs a deliberate decision rather than drift.
+ *
+ * Lifted out of forms-validation.ts so the framework-composables demand-bundler
+ * (src/framework-composables.ts) can ship it to the browser. That bundler scans
+ * THIS directory, takes each file whole, strips the imports — every name they
+ * pull from stx is a runtime global by the time the emitted script runs — and
+ * merges the export onto window.stx. defineForm was exported from the package
+ * and type-checked, yet reached the client by no path at all, so an app that
+ * wanted reactive form state hand-rolled it. #1856 made it reactive; this makes
+ * it reachable.
+ *
+ * The signal comes from signals-api, whose `state` is published as a bare global
+ * (signals.ts does `window.state = state`), so the stripped `import { state }`
+ * below still resolves once the bundle runs. reactivity.ts's `reactive()` would
+ * NOT — it tracks a separate effect context the template runtime never reads
+ * (see #1885).
+ */
+import type { FormState, Validator } from '../forms-validation';
+/**
+ * Reactive form state from a validation schema.
+ *
+ * @example
+ * ```typescript
+ * const form = useForm({
+ *   email: v.required().email(),
+ *   password: v.required().min(8),
+ *   age: v.number().between(18, 100)
+ * })
+ *
+ * // Access form state
+ * form.values.email
+ * form.errors.email
+ * form.isValid
+ *
+ * // Validate
+ * await form.validate()
+ *
+ * // Handle submit
+ * form.handleSubmit((values) => {
+ *   console.log(values)
+ * })
+ * ```
+ */
+export declare function useForm<T extends Record<string, Validator>>(schema: T, initialValues?: Partial<{
+    [K in keyof T]: unknown;
+}>): FormState<T>;
+/**
+ * @deprecated Use {@link useForm}. Renamed in stacksjs/stx#1843 so the name
+ * matches what it does: `define*` declares in this codebase, `use*` returns
+ * live reactive state, and this returns the latter.
+ *
+ * A plain alias, not a wrapper — same reference, so `defineForm === useForm`
+ * and anything comparing or spying on the function keeps working. Kept for a
+ * minor; existing apps do not have to move in the same release they upgrade in.
+ */
+export declare const defineForm: typeof useForm;

package/dist/composables/use-form.js

@@ -0,0 +1,112 @@
+import { state } from "../signals-api.js";
+function signalRecord(fields, init) {
+  const signals = {};
+  for (const field of fields)
+    signals[field] = state(init(field));
+  return new Proxy({}, {
+    get: (_target, prop) => signals[prop]?.(),
+    set: (_target, prop, value) => {
+      if (signals[prop])
+        signals[prop].set(value);
+      else
+        signals[prop] = state(value);
+      return !0;
+    },
+    has: (_target, prop) => (prop in signals),
+    deleteProperty: (_target, prop) => {
+      delete signals[prop];
+      return !0;
+    },
+    ownKeys: () => Reflect.ownKeys(signals),
+    getOwnPropertyDescriptor: (_target, prop) => (prop in signals) ? { enumerable: !0, configurable: !0, writable: !0, value: signals[prop]() } : void 0
+  });
+}
+function snapshot(record, fields) {
+  const out = {};
+  for (const field of fields)
+    out[field] = record[field];
+  return out;
+}
+export function useForm(schema, initialValues) {
+  const fields = Object.keys(schema), values = signalRecord(fields, (f) => initialValues?.[f] ?? schema[f].getDefaultValue()), errors = signalRecord(fields, () => []), touched = signalRecord(fields, () => !1), dirty = signalRecord(fields, () => !1), validating = signalRecord(fields, () => !1), isValidatingSignal = state(!1);
+  async function validateField(field) {
+    validating[field] = !0;
+    const fieldErrors = await schema[field].validate(values[field], values);
+    errors[field] = fieldErrors;
+    validating[field] = !1;
+    return fieldErrors.length === 0;
+  }
+  async function validate() {
+    isValidatingSignal.set(!0);
+    const results = await Promise.all(fields.map(validateField));
+    isValidatingSignal.set(!1);
+    return results.every(Boolean);
+  }
+  function reset() {
+    for (const field of fields) {
+      values[field] = initialValues?.[field] ?? schema[field].getDefaultValue();
+      errors[field] = [];
+      touched[field] = !1;
+      dirty[field] = !1;
+    }
+  }
+  function setValues(newValues) {
+    for (const field of fields)
+      if (field in newValues) {
+        values[field] = newValues[field];
+        dirty[field] = !0;
+      }
+  }
+  function setFieldValue(field, value) {
+    values[field] = value;
+    dirty[field] = !0;
+  }
+  function setFieldTouched(field, isTouched = !0) {
+    touched[field] = isTouched;
+    if (isTouched)
+      validateField(field);
+  }
+  function getFieldState(field) {
+    return {
+      value: values[field],
+      errors: errors[field],
+      touched: touched[field],
+      dirty: dirty[field],
+      valid: errors[field].length === 0,
+      validating: validating[field]
+    };
+  }
+  function handleSubmit(onSubmit) {
+    return async (e) => {
+      e?.preventDefault?.();
+      for (const field of fields)
+        touched[field] = !0;
+      if (await validate())
+        await onSubmit(snapshot(values, fields));
+    };
+  }
+  return {
+    values,
+    errors,
+    touched,
+    dirty,
+    get isValid() {
+      return fields.every((f) => errors[f].length === 0);
+    },
+    get isValidating() {
+      return isValidatingSignal() || fields.some((f) => validating[f]);
+    },
+    get isDirty() {
+      return fields.some((f) => dirty[f]);
+    },
+    validate,
+    validateField,
+    reset,
+    setValues,
+    setFieldValue,
+    setFieldTouched,
+    getFieldState,
+    handleSubmit
+  };
+}
+export const defineForm = useForm;

package/dist/composables.d.ts

@@ -1,3 +1,33 @@
+/**
+ * STX Composables
+ *
+ * Vue-inspired composable utilities for STX components:
+ * - Lifecycle hooks (onMount, onDestroy, onUpdate)
+ * - Refs for DOM element references
+ * - Watch and computed for reactivity
+ *
+ * @module composables
+ */
+export type LifecycleHook = () => void | (() => void);
+export type CleanupFn = () => void;
+export type WatchCallback<T> = (newValue: T, oldValue: T | undefined) => void | CleanupFn;
+export type WatchSource<T> = () => T;
+export interface Ref<T> {
+    value: T | null;
+    readonly current: T | null;
+}
+export interface ComponentInstance {
+    id: string;
+    element: Element | null;
+    mountHooks: LifecycleHook[];
+    destroyHooks: CleanupFn[];
+    updateHooks: LifecycleHook[];
+    refs: Map<string, Ref<any>>;
+    watchers: Array<{
+        stop: () => void;
+    }>;
+    isMounted: boolean;
+}
 /**
  * Create a new component instance context.
  * Called internally when a component script starts executing.
@@ -65,6 +95,18 @@ export declare function onDestroy(hook: CleanupFn): void;
  * ```
  */
 export declare function onUpdate(hook: LifecycleHook): void;
+/**
+ * Alias for onMount - matches common naming conventions.
+ */
+export declare const onMounted: typeof onMount;
+/**
+ * Alias for onDestroy - matches Vue naming.
+ */
+export declare const onUnmounted: typeof onDestroy;
+/**
+ * Alias for onUpdate - matches Vue naming.
+ */
+export declare const onUpdated: typeof onUpdate;
 /**
  * Create a ref for holding a DOM element reference.
  *
@@ -106,7 +148,9 @@ export declare function namedRef<T = HTMLElement>(name: string, initialValue?: T
  * </script>
  * ```
  */
-export declare function watch<T>(source: WatchSource<T>, callback: WatchCallback<T>, options?: { immediate?: boolean }): () => void;
+export declare function watch<T>(source: WatchSource<T>, callback: WatchCallback<T>, options?: {
+    immediate?: boolean;
+}): () => void;
 /**
  * Create a computed value that updates when dependencies change.
  *
@@ -123,7 +167,9 @@ export declare function watch<T>(source: WatchSource<T>, callback: WatchCallback
  * </script>
  * ```
  */
-export declare function computed<T>(getter: () => T): { readonly value: T };
+export declare function computed<T>(getter: () => T): {
+    readonly value: T;
+};
 /**
  * Initialize a component and run its setup.
  * This is called by the STX runtime when a component is created.
@@ -145,6 +191,10 @@ export declare function destroyComponent(instance: ComponentInstance): void;
  * Generate the client-side runtime script for lifecycle management.
  */
 export declare function generateLifecycleRuntime(): string;
+/** Symbol for injection keys */
+export type InjectionKey<T> = symbol & {
+    __type?: T;
+};
 /**
  * Create a typed injection key.
  *
@@ -209,65 +259,19 @@ export declare function withInjectionScope<T>(fn: () => T | Promise<T>): Promise
  * Clear all injections (for testing).
  */
 export declare function clearInjections(): void;
-/**
- * Alias for onMount - matches common naming conventions.
- */
-export declare const onMounted: unknown;
-/**
- * Alias for onDestroy - matches Vue naming.
- */
-export declare const onUnmounted: unknown;
-/**
- * Alias for onUpdate - matches Vue naming.
- */
-export declare const onUpdated: unknown;
 /** Built-in injection key for theme */
-export declare const ThemeKey: unknown;
+export declare const ThemeKey: InjectionKey<{
+    mode: 'light' | 'dark';
+    accent?: string;
+}>;
 /** Built-in injection key for router */
-export declare const RouterKey: (createInjectionKey<{
-  currentRoute: string
-  navigate: (path: string)) => unknown;
+export declare const RouterKey: InjectionKey<{
+    currentRoute: string;
+    navigate: (path: string) => void;
+}>;
 /** Built-in injection key for i18n */
-export declare const I18nKey: (createInjectionKey<{
-  locale: string
-  t: (key: string)) => unknown;
-export declare interface Ref<T> {
-  value: T | null
-  readonly current: T | null
-}
-export declare interface ComponentInstance {
-  id: string
-  element: Element | null
-  mountHooks: LifecycleHook[]
-  destroyHooks: CleanupFn[]
-  updateHooks: LifecycleHook[]
-  refs: Map<string, Ref<any>>
-  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
- *
- * Vue-inspired composable utilities for STX components:
- * - Lifecycle hooks (onMount, onDestroy, onUpdate)
- * - Refs for DOM element references
- * - Watch and computed for reactivity
- *
- * @module composables
- */
-// =============================================================================
-// Types
-// =============================================================================
-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 */
-export type InjectionKey<T> = symbol & { __type?: T }
-// =============================================================================
-// Export helpers for client-side usage
-// =============================================================================
-// Re-export for convenient importing
+export declare const I18nKey: InjectionKey<{
+    locale: string;
+    t: (key: string) => string;
+}>;
 export { ref as createRef };

package/dist/computed.d.ts

@@ -1,3 +1,65 @@
+/**
+ * Computed Properties Module
+ *
+ * Provides reactive computed values with automatic dependency tracking.
+ * Computed properties automatically update when their dependencies change,
+ * and are cached until dependencies are modified.
+ *
+ * @example
+ * ```typescript
+ * const firstName = ref('John')
+ * const lastName = ref('Doe')
+ *
+ * const fullName = computed(() => `${firstName.value} ${lastName.value}`)
+ *
+ * console.log(fullName.value) // 'John Doe'
+ * firstName.value = 'Jane'
+ * console.log(fullName.value) // 'Jane Doe'
+ * ```
+ */
+export interface Ref<T> {
+    value: T;
+    /** Subscribe to value changes */
+    subscribe: (callback: (value: T) => void) => () => void;
+    /** Get raw value without tracking */
+    peek: () => T;
+}
+export interface ComputedRef<T> extends Ref<T> {
+    /** Force recalculation */
+    invalidate: () => void;
+    /** Check if value is dirty (needs recalculation) */
+    readonly dirty: boolean;
+    /** Get all dependencies */
+    readonly deps: Set<Ref<unknown>>;
+}
+export interface WritableComputedRef<T> extends ComputedRef<T> {
+    value: T;
+}
+export interface ComputedOptions<T> {
+    /** Getter function */
+    get: () => T;
+    /** Optional setter function */
+    set?: (value: T) => void;
+    /** Lazy evaluation (default: true) */
+    lazy?: boolean;
+    /** Custom equality check */
+    equals?: (a: T, b: T) => boolean;
+}
+export interface WatchOptions {
+    /** Run immediately with current value */
+    immediate?: boolean;
+    /** Deep watch for object changes */
+    deep?: boolean;
+    /** Flush timing: 'pre' | 'post' | 'sync' */
+    flush?: 'pre' | 'post' | 'sync';
+    /** Stop watching after first change */
+    once?: boolean;
+}
+export interface WatchStopHandle {
+    (): void;
+    pause: () => void;
+    resume: () => void;
+}
 /**
  * Create a reactive reference
  */
@@ -13,7 +75,9 @@ export declare function unref<T>(value: T | Ref<T>): T;
 /**
  * Convert all properties of an object to refs
  */
-export declare function toRefs<T extends object>(obj: T): { [K in keyof T]: Ref<T[K]> };
+export declare function toRefs<T extends object>(obj: T): {
+    [K in keyof T]: Ref<T[K]>;
+};
 /**
  * Create a shallow reactive object
  */
@@ -22,7 +86,6 @@ 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
@@ -31,10 +94,11 @@ export declare function watch<T>(source: Ref<T> | (() => T), callback: (newValue
 /**
  * Watch multiple sources
  */
-export declare function watchMultiple<T extends readonly Ref<unknown>[]>(sources: [...T], callback: (
-    newValues: { [K in keyof T]: T[K] extends Ref<infer V> ? V : never },
-    oldValues: { [K in keyof T]: T[K] extends Ref<infer V> ? V | undefined : never }
-  ) => void, options?: WatchOptions): WatchStopHandle;
+export declare function watchMultiple<T extends readonly Ref<unknown>[]>(sources: [...T], callback: (newValues: {
+    [K in keyof T]: T[K] extends Ref<infer V> ? V : never;
+}, oldValues: {
+    [K in keyof T]: T[K] extends Ref<infer V> ? V | undefined : never;
+}) => void, options?: WatchOptions): WatchStopHandle;
 /**
  * Watch and run effect immediately, auto-tracking dependencies
  */
@@ -55,90 +119,20 @@ export declare function debouncedComputed<T>(getter: () => T, delay?: number): C
  * Create a throttled computed
  */
 export declare function throttledComputed<T>(getter: () => T, limit?: number): ComputedRef<T>;
-/**
- * Computed Properties Module
- *
- * Provides reactive computed values with automatic dependency tracking.
- * Computed properties automatically update when their dependencies change,
- * and are cached until dependencies are modified.
- *
- * @example
- * ```typescript
- * const firstName = ref('John')
- * const lastName = ref('Doe')
- *
- * const fullName = computed(() => `${firstName.value} ${lastName.value}`)
- *
- * console.log(fullName.value) // 'John Doe'
- * firstName.value = 'Jane'
- * console.log(fullName.value) // 'Jane Doe'
- * ```
- */
-// ============================================================================
-// Types
-// ============================================================================
-export declare interface Ref<T> {
-  value: T
-  subscribe: (callback: (value: T) => void) => () => void
-  peek: () => T
-}
-export declare interface ComputedRef<T> extends Ref<T> {
-  invalidate: () => void
-  readonly dirty: boolean
-  readonly deps: Set<Ref<unknown>>
-}
-export declare interface WritableComputedRef<T> extends ComputedRef<T> {
-  value: T
-}
-export declare interface ComputedOptions<T> {
-  get: () => T
-  set?: (value: T) => void
-  lazy?: boolean
-  equals?: (a: T, b: T) => boolean
-}
-export declare interface WatchOptions {
-  immediate?: boolean
-  deep?: boolean
-  flush?: 'pre' | 'post' | 'sync'
-  once?: boolean
-}
-export declare interface WatchStopHandle {
-  (): void
-  pause: () => void
-  resume: () => void
-}
-// ============================================================================
-// Aliased Exports (to avoid conflicts with other modules)
-// ============================================================================
-// Export with 'stx' prefix to avoid naming conflicts
-export {
-  ref as stxRef,
-  computed as stxComputed,
-  watch as stxWatch,
-  watchMultiple as stxWatchMultiple,
-  watchEffect as stxWatchEffect,
-  isRef as stxIsRef,
-  unref as stxUnref,
-  toRefs as stxToRefs,
-  shallowRef as stxShallowRef,
-  debouncedComputed as stxDebouncedComputed,
-  throttledComputed as stxThrottledComputed,
-};
-// ============================================================================
-// Exports
-// ============================================================================
-export default {
-  ref,
-  computed,
-  watch,
-  watchMultiple,
-  watchEffect,
-  isRef,
-  unref,
-  toRefs,
-  shallowRef,
-  debouncedComputed,
-  throttledComputed,
-  processComputedDirectives,
-  processWatchDirectives,
+export { ref as stxRef, computed as stxComputed, watch as stxWatch, watchMultiple as stxWatchMultiple, watchEffect as stxWatchEffect, isRef as stxIsRef, unref as stxUnref, toRefs as stxToRefs, shallowRef as stxShallowRef, debouncedComputed as stxDebouncedComputed, throttledComputed as stxThrottledComputed, };
+declare const _default: {
+    ref: typeof ref;
+    computed: typeof computed;
+    watch: typeof watch;
+    watchMultiple: typeof watchMultiple;
+    watchEffect: typeof watchEffect;
+    isRef: typeof isRef;
+    unref: typeof unref;
+    toRefs: typeof toRefs;
+    shallowRef: typeof shallowRef;
+    debouncedComputed: typeof debouncedComputed;
+    throttledComputed: typeof throttledComputed;
+    processComputedDirectives: typeof processComputedDirectives;
+    processWatchDirectives: typeof processWatchDirectives;
 };
+export default _default;

package/dist/conditionals.d.ts

@@ -1,3 +1,27 @@
+/**
+ * Module for processing conditional directives (@if, @elseif, @else, @unless)
+ *
+ * Regex Pattern Reference:
+ * ========================
+ *
+ * NESTED_PARENS_PATTERN: `(?:[^()]|\([^()]*\))*`
+ *   - Matches content with one level of nested parentheses
+ *   - `[^()]` - Match any character except parentheses
+ *   - `\([^()]*\)` - OR match balanced parentheses (one level deep)
+ *   - Used in: @switch, @case, @if expressions to handle function calls
+ *   - Example matches: `user.role`, `getRole()`, `check(a, b)`
+ *   - Limitation: Only handles ONE level of nesting. `fn(a(b))` won't work correctly.
+ *
+ * DIRECTIVE_WITH_CONTENT: `@directive\s*\(EXPR\)([\s\S]*?)@enddirective`
+ *   - `\s*` - Optional whitespace after directive name
+ *   - `\(EXPR\)` - Parenthesized expression
+ *   - `[\s\S]*?` - Non-greedy match of ANY content (including newlines)
+ *   - `?` makes it non-greedy to match shortest possible content
+ *
+ * IF_ELSEIF_ELSE: Complex multi-branch matching
+ *   - Processes from inside-out to handle nesting
+ *   - Each @elseif/@else creates a branch in the condition chain
+ */
 /**
  * Process switch statements (@switch, @case, @default)
  *
@@ -7,14 +31,6 @@
  * - @break directives
  */
 export declare function processSwitchStatements(template: string, context: Record<string, any>, _filePath: string): string;
-/**
- * Process conditionals (@if, @elseif, @else, @unless)
- *
- * Uses the parser module for proper handling of:
- * - Nested parentheses in conditions (e.g., @if(fn(a, fn(b))))
- * - Nested @if blocks
- * - Multiple @elseif branches
- */
 export declare function processConditionals(template: string, context: Record<string, any>, filePath: string): string;
 /**
  * Process @auth and permissions directives

package/dist/conditionals.js

@@ -69,7 +69,23 @@ export function processSwitchStatements(template, context, _filePath) {
   }
   return output;
 }
+function maskScripts(template) {
+  const scripts = [];
+  return { masked: template.replace(/<script\b[\s\S]*?<\/script\s*>/gi, (match) => {
+    scripts.push(match);
+    return `\x00stx-script-${scripts.length - 1}\x00`;
+  }), scripts };
+}
+function restoreScripts(output, scripts) {
+  if (scripts.length === 0)
+    return output;
+  return output.replace(/\u0000stx-script-(\d+)\u0000/g, (match, index) => scripts[Number(index)] ?? match);
+}
 export function processConditionals(template, context, filePath) {
+  const { masked, scripts } = maskScripts(template);
+  return restoreScripts(processConditionalsIn(masked, context, filePath), scripts);
+}
+function processConditionalsIn(template, context, filePath) {
   let output = template;
   output = processSwitchStatements(output, context, filePath);
   {