@stacksjs/stx 0.2.152 → 0.2.154

package/dist/x-element.js

@@ -1,5 +1,5 @@
 export function generateXElementRuntime() {
-  return `<script data-stx-scoped data-stx-x-element-runtime>
+  return `<script data-stx-scoped data-stx-x-element-runtime data-stx-run="always">
 (function() {
   'use strict';
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@stacksjs/stx",
   "type": "module",
-  "version": "0.2.152",
+  "version": "0.2.154",
   "description": "A performant UI Framework. Powered by Bun.",
   "author": "Chris Breuer <chris@stacksjs.org>",
   "license": "MIT",
@@ -117,12 +117,12 @@
   "dependencies": {
     "@cwcss/crosswind": "^0.2.14",
     "@stacksjs/clapp": "^0.2.0",
-    "@stacksjs/desktop": "0.2.152",
-    "@stacksjs/sanitizer": "0.2.152",
+    "@stacksjs/desktop": "0.2.154",
+    "@stacksjs/sanitizer": "0.2.154",
     "@stacksjs/ts-i18n": "^0.1.11",
-    "bun-plugin-stx": "0.2.152",
+    "bun-plugin-stx": "0.2.154",
     "bunfig": "^0.15.17",
-    "stx-router": "0.2.152",
+    "stx-router": "0.2.154",
     "ts-broadcasting": "^0.0.9",
     "ts-images": "^0.1.9",
     "ts-syntax-highlighter": "^0.2.1"

package/stx.d.ts

@@ -82,23 +82,49 @@ 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: HTMLElement | null, info: string) => boolean | void): void
+// onBeforeUpdate / onUpdated / onErrorCaptured are NOT declared: they exist in
+// reactivity.ts and composition-api.ts but have no client-runtime counterpart,
+// so declaring them promised a global that resolved to undefined (#1804).
 
 // ============================================================================
 // Template refs
 // ============================================================================
 
+/** Stable per-component id, unique across instances. */
+declare function useId(_prefix?: string): string
+/**
+ * Signal tracking a parent-driven `:prop="signal()"` attribute on the
+ * component's root element. One-way: parent to child.
+ */
+declare function useReactiveProp<T = unknown>(
+  _name: string,
+  _defaultValue?: T,
+  _options?: { parse?: (_value: string) => T },
+): StxSignal<T>
 declare function useRef<T = HTMLElement>(_name: string): { current: T | null }
 
 // ============================================================================
 // Routing / navigation
 // ============================================================================
 
-declare function navigate(_url: string, _options?: { replace?: boolean }): void
+interface StxNavigateOptions {
+  /** Replace the current history entry instead of pushing a new one. */
+  replace?: boolean
+  /** Bypass the SPA router and perform a full document load. */
+  reload?: boolean
+}
+
+/**
+ * Navigate via the SPA router.
+ *
+ * The second argument is deliberately NOT typed to also accept a boolean. The
+ * legacy positional `forceReload` boolean still works at runtime — it was the
+ * shape that actually shipped — but keeping it out of the type means nothing
+ * that type-checks today changes meaning (#1807).
+ */
+declare function navigate(_url: string, _options?: StxNavigateOptions): void
 declare function goBack(): void
 declare function goForward(): void
 declare function useRoute(): {
@@ -108,11 +134,39 @@ declare function useRoute(): {
   hash: string
 }
 declare function setRouteParams(_params: Record<string, string>): void
+/** How a search-param mutation is written to session history (#1825). */
+interface StxSearchParamsCommitOptions {
+  /** Replace the current history entry instead of pushing a new one. */
+  replace?: boolean
+}
+
+/**
+ * Reactive access to the URL query string.
+ *
+ * The declaration was wrong in both directions (#1806): it promised `delete`
+ * and `has`, which did not exist at runtime, and omitted `setAll` and `data`,
+ * which did. `delete`/`has` are now implemented rather than dropped; `get`
+ * returns `undefined` for a missing key, not `null`, which is what the runtime
+ * and the docs have always said.
+ */
 declare function useSearchParams(): {
-  get: (key: string) => string | null
-  set: (key: string, value: string) => void
-  delete: (key: string) => void
-  has: (key: string) => boolean
+  /** The backing signal — read it to make a binding reactive to the query. */
+  data: StxSignal<Record<string, string>>
+  get: (_key: string) => string | undefined
+  has: (_key: string) => boolean
+  /** Set a param. Pushes a history entry unless `{ replace: true }` is passed. */
+  set: (_key: string, _value: string, _options?: StxSearchParamsCommitOptions) => void
+  /**
+   * Remove a param. Pushes a history entry unless `{ replace: true }` is passed.
+   *
+   * CONSUMING a one-shot param — an OAuth callback result, `?checkout=success`,
+   * a flash token — needs `{ replace: true }`. Under the default push, the URL
+   * that still carries the param becomes the previous history entry, so Back
+   * replays the callback and re-runs whatever consuming it triggered (#1825).
+   */
+  delete: (_key: string, _options?: StxSearchParamsCommitOptions) => void
+  /** Set several params. Pushes a history entry unless `{ replace: true }` is passed. */
+  setAll: (_values: Record<string, string>, _options?: StxSearchParamsCommitOptions) => void
 }
 
 // ============================================================================
@@ -160,7 +214,6 @@ declare function useEventListener(
 declare function useScrollLock(
   _target?: HTMLElement | null | { current?: HTMLElement | null, value?: HTMLElement | null } | (() => HTMLElement | null | undefined),
 ): StxSignal<boolean>
-declare function useMeta(_meta: Record<string, string>): void
 declare function useClickOutside(_target: HTMLElement | StxRef<HTMLElement | null> | string | null, _handler: (event: MouseEvent) => void): StxCleanup
 declare function useFocus(_target: HTMLElement | StxRef<HTMLElement | null> | string | null): { focused: StxSignal<boolean>, focus: () => void, blur: () => void }
 
@@ -209,6 +262,44 @@ declare function useAsync<T>(_fn: () => Promise<T>): {
 declare function useLocalStorage<T>(_key: string, _defaultValue: T): StxSignal<T>
 declare function useSessionStorage<T>(_key: string, _defaultValue: T): StxSignal<T>
 
+/**
+ * Options accepted by the auto-imported `useCookie` global.
+ *
+ * This describes the CLIENT RUNTIME's cookie composable, which is what a bare
+ * `useCookie(...)` in a `<script client>` block resolves to. The module export
+ * `@stacksjs/stx/composables` accepts a slightly wider `expires` (Date, epoch ms
+ * or parseable string); the runtime calls `.toUTCString()` on it, so only a Date
+ * works there. See #1710.
+ */
+interface StxCookieOptions {
+  /** Max age in seconds. */
+  maxAge?: number
+  /** Expiration date. */
+  expires?: Date
+  /** Cookie path. Defaults to '/'. */
+  path?: string
+  /** Cookie domain. */
+  domain?: string
+  /** Secure flag. Defaults to true when location.protocol is https:. */
+  secure?: boolean
+  /** SameSite attribute. Defaults to 'Lax'. */
+  sameSite?: 'Strict' | 'Lax' | 'None' | 'strict' | 'lax' | 'none'
+  /** Value returned when the cookie is absent. Defaults to ''. */
+  defaultValue?: string
+  /** Custom encoder. Defaults to encodeURIComponent. */
+  encode?: (_value: string) => string
+  /** Custom decoder. Defaults to decodeURIComponent. */
+  decode?: (_value: string) => string
+}
+
+/**
+ * Reactive binding to a single cookie (#1808).
+ *
+ * Returns a signal, like `useLocalStorage` — writes serialise straight to
+ * `document.cookie`, and `.set('')` deletes by emitting `max-age=0`.
+ */
+declare function useCookie(_name: string, _options?: StxCookieOptions): StxSignal<string>
+
 // ============================================================================
 // WebSocket
 // ============================================================================
@@ -237,11 +328,19 @@ interface StxColorModeOptions {
   /** localStorage key holding the preference. @default 'stx-color-mode' */
   storageKey?: string
   /** Mode used when nothing valid is stored. @default 'auto' */
-  initialMode?: 'light' | 'dark' | 'auto'
-  /** Class applied to `<html>` when dark. @default 'dark' */
-  darkClass?: string
-  /** Attribute applied to `<html>` INSTEAD of the class, e.g. 'data-theme'. */
-  attribute?: string
+  initialMode?: 'light' | 'dark' | 'auto' | 'system'
+  /**
+   * Class applied to `<html>` when dark. @default 'dark'
+   * Applied alongside `attribute`; pass `null` to opt out of the class.
+   */
+  darkClass?: string | null
+  /** Attribute set to the resolved mode on `<html>`, e.g. 'data-theme'. */
+  attribute?: string | null
+  /**
+   * Spelling written to storage for "follow the system".
+   * @default whatever is already stored, else 'auto'
+   */
+  autoValue?: 'auto' | 'system'
   /** Suppress CSS transitions across a mode switch. @default true */
   disableTransitions?: boolean
 }
@@ -257,7 +356,7 @@ declare function useColorMode(_options?: StxColorModeOptions): {
   /** User preference, which may be 'auto'. */
   readonly preference: 'light' | 'dark' | 'auto'
   readonly isDark: boolean
-  set: (mode: 'light' | 'dark' | 'auto') => void
+  set: (mode: 'light' | 'dark' | 'auto' | 'system') => void
   toggle: () => void
   subscribe: (fn: (mode: 'light' | 'dark', preference: 'light' | 'dark' | 'auto') => void) => () => void
 }
@@ -309,6 +408,8 @@ interface StxSeoMetaConfig {
 
 declare function useHead(_config: StxHeadConfig): void
 declare function useSeoMeta(_config: StxSeoMetaConfig): void
+/** No-op on the client; the real one runs at SSR/SSG time. */
+declare function definePageMeta(_meta: Record<string, unknown>): void
 
 // ============================================================================
 // Vue-style reactivity (alternative API)
@@ -340,9 +441,9 @@ declare function defineExpose<T extends Record<string, any>>(_exposed: T): void
 declare function defineSlots<T extends Record<string, (..._args: any[]) => any> = Record<string, (..._args: any[]) => any>>(): T
 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>
+// getCurrentInstance / useAttrs are NOT declared — composition-api.ts exports
+// them for server use; no client-runtime counterpart exists (#1804).
 declare function $computed<T>(_getter: () => T): StxRef<T>
 declare function $watch<T>(
   _source: (() => T) | StxRef<T> | StxSignal<T>,
@@ -454,16 +555,18 @@ declare function defineStore<S extends Record<string, any>, G extends Record<str
   },
 ): () => 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
+declare function registerStoresClient(_stores: Record<string, unknown>): void
+// createStore / createSelector are exported by state-management.ts for server
+// use and `action` has no implementation anywhere; none reaches window.stx, so
+// none is declared as an ambient global (#1804).
 
 // ============================================================================
 // JSX runtime (Vue/React style)
 // ============================================================================
 
-declare function h(_tag: string | Function, _props?: Record<string, any> | null, ..._children: any[]): any
-declare const Fragment: unique symbol
+// h / Fragment belong to the JSX runtime (jsx-runtime.ts) and are resolved by
+// the transform, not destructured off window.stx — so they are not ambient
+// globals (#1804). Import them explicitly if you call them directly.
 
 // ============================================================================
 // window.stx registry