@stacksjs/stx 0.2.152 → 0.2.154

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

@@ -19,11 +19,6 @@ export declare function useClipboard(options?: { timeout?: number }): ClipboardR
  * Copy text to clipboard (one-shot helper)
  */
 export declare function copyToClipboard(text: string): Promise<boolean>;
-/**
- * useClipboard - Reactive clipboard composable
- *
- * Provides easy access to the Clipboard API with fallbacks.
- */
 export declare interface ClipboardRef {
   text: string
   isSupported: boolean
@@ -31,4 +26,5 @@ export declare interface ClipboardRef {
   copy: (text: string) => Promise<boolean>
   read: () => Promise<string>
   subscribe: (callback: (text: string) => void) => () => void
+  stop: () => void
 }

package/dist/composables/use-clipboard.js

@@ -1,3 +1,4 @@
+import { onDestroy } from "../signals-api.js";
 export function useClipboard(options = {}) {
   const { timeout = 1500 } = options, subscribers = new Set;
   let currentText = "", copied = !1, copiedTimeout = null;
@@ -8,42 +9,17 @@ export function useClipboard(options = {}) {
       } catch (e) {
         console.error("[useClipboard] Subscriber error:", e);
       }
-  };
-  return {
-    get text() {
-      return currentText;
-    },
-    get isSupported() {
-      return isSupported;
-    },
-    get copied() {
-      return copied;
-    },
-    copy: async (text) => {
-      if (!isSupported)
-        try {
-          const textarea = document.createElement("textarea");
-          textarea.value = text;
-          textarea.style.position = "fixed";
-          textarea.style.opacity = "0";
-          document.body.appendChild(textarea);
-          textarea.select();
-          document.execCommand("copy");
-          document.body.removeChild(textarea);
-          currentText = text;
-          copied = !0;
-          notify(text);
-          if (copiedTimeout)
-            clearTimeout(copiedTimeout);
-          copiedTimeout = setTimeout(() => {
-            copied = !1;
-          }, timeout);
-          return !0;
-        } catch {
-          return !1;
-        }
+  }, copy = async (text) => {
+    if (!isSupported)
       try {
-        await navigator.clipboard.writeText(text);
+        const textarea = document.createElement("textarea");
+        textarea.value = text;
+        textarea.style.position = "fixed";
+        textarea.style.opacity = "0";
+        document.body.appendChild(textarea);
+        textarea.select();
+        document.execCommand("copy");
+        document.body.removeChild(textarea);
         currentText = text;
         copied = !0;
         notify(text);
@@ -51,27 +27,62 @@ export function useClipboard(options = {}) {
           clearTimeout(copiedTimeout);
         copiedTimeout = setTimeout(() => {
           copied = !1;
+          notify(currentText);
         }, timeout);
         return !0;
       } catch {
         return !1;
       }
+    try {
+      await navigator.clipboard.writeText(text);
+      currentText = text;
+      copied = !0;
+      notify(text);
+      if (copiedTimeout)
+        clearTimeout(copiedTimeout);
+      copiedTimeout = setTimeout(() => {
+        copied = !1;
+        notify(currentText);
+      }, timeout);
+      return !0;
+    } catch {
+      return !1;
+    }
+  }, read = async () => {
+    if (!isSupported)
+      return "";
+    try {
+      const text = await navigator.clipboard.readText();
+      currentText = text;
+      return text;
+    } catch {
+      return "";
+    }
+  }, stop = () => {
+    if (copiedTimeout) {
+      clearTimeout(copiedTimeout);
+      copiedTimeout = null;
+    }
+    subscribers.clear();
+  };
+  onDestroy(stop);
+  return {
+    get text() {
+      return currentText;
     },
-    read: async () => {
-      if (!isSupported)
-        return "";
-      try {
-        const text = await navigator.clipboard.readText();
-        currentText = text;
-        return text;
-      } catch {
-        return "";
-      }
+    get isSupported() {
+      return isSupported;
     },
+    get copied() {
+      return copied;
+    },
+    copy,
+    read,
     subscribe: (callback) => {
       subscribers.add(callback);
       return () => subscribers.delete(callback);
-    }
+    },
+    stop
   };
 }
 export async function copyToClipboard(text) {

package/dist/composables/use-color-mode.d.ts

@@ -1,3 +1,8 @@
+/**
+ * Map any accepted spelling onto the canonical vocabulary, or null if the value
+ * is not a color-mode preference at all.
+ */
+export declare function normalizeColorMode(value: unknown): ColorMode | null;
 /**
  * Full-featured color-mode manager.
  *
@@ -21,16 +26,17 @@ export declare function useColorMode(options?: ColorModeOptions): ColorModeRef;
 export declare function useDark(options?: ColorModeOptions): DarkRef;
 export declare interface ColorModeOptions {
   storageKey?: string
-  initialMode?: ColorMode
-  darkClass?: string
-  attribute?: string
+  initialMode?: ColorModeInput
+  darkClass?: string | null
+  attribute?: string | null
+  autoValue?: AutoValue
   disableTransitions?: boolean
 }
 export declare interface ColorModeRef {
   readonly mode: 'light' | 'dark'
   readonly preference: ColorMode
   readonly isDark: boolean
-  set: (mode: ColorMode) => void
+  set: (mode: ColorModeInput) => void
   toggle: () => void
   subscribe: (fn: (mode: 'light' | 'dark', preference: ColorMode) => void) => () => void
 }
@@ -50,3 +56,12 @@ export declare interface DarkRef {
 // Types
 // =============================================================================
 export type ColorMode = 'light' | 'dark' | 'auto';
+/**
+ * What may be *written* into storage for "follow the system".
+ *
+ * `'system'` is a common spelling for the same concept, and an app that already
+ * persists it must not have that overwritten (stacksjs/stx#1788).
+ */
+export type AutoValue = 'auto' | 'system';
+/** Accepted on input anywhere a ColorMode is; normalised to ColorMode. */
+export type ColorModeInput = ColorMode | 'system';

package/dist/composables/use-color-mode.js

@@ -1,12 +1,29 @@
+const AUTO_VALUES = ["auto", "system"];
+export function normalizeColorMode(value) {
+  if (value === "light" || value === "dark")
+    return value;
+  if (typeof value === "string" && AUTO_VALUES.includes(value))
+    return "auto";
+  return null;
+}
 export function useColorMode(options = {}) {
-  const boot = typeof window < "u" ? window.__STX_COLOR_MODE__ : null, {
-    storageKey = boot?.storageKey ?? "stx-color-mode",
-    initialMode = boot?.initialMode ?? "auto",
-    darkClass = boot?.darkClass ?? "dark",
-    attribute = boot?.attribute,
+  const boot = typeof window < "u" ? window.__STX_COLOR_MODE__ : null;
+  function pick(fromOptions, fromBoot, fallback) {
+    if (fromOptions !== void 0)
+      return fromOptions;
+    if (boot && typeof boot === "object" && fromBoot !== void 0)
+      return fromBoot;
+    return fallback;
+  }
+  const {
+    storageKey = pick(void 0, boot?.storageKey, "stx-color-mode"),
+    initialMode = pick(void 0, boot?.initialMode, "auto"),
+    darkClass = pick(void 0, boot?.darkClass, "dark"),
+    attribute = pick(void 0, boot?.attribute, null),
+    autoValue: autoValueOption = boot?.autoValue,
     disableTransitions = !0
   } = options;
-  let preference = initialMode, resolved = "light";
+  let preference = normalizeColorMode(initialMode) ?? "auto", resolved = "light";
   const listeners = new Set, cleanups = [], isBrowser = typeof window < "u";
   function getSystemPreference() {
     if (!isBrowser)
@@ -24,41 +41,43 @@ export function useColorMode(options = {}) {
       el.style.setProperty("transition", "none", "important");
     if (attribute)
       el.setAttribute(attribute, mode);
-    else if (mode === "dark")
-      el.classList.add(darkClass);
-    else
-      el.classList.remove(darkClass);
+    if (darkClass)
+      if (mode === "dark")
+        el.classList.add(darkClass);
+      else
+        el.classList.remove(darkClass);
     if (disableTransitions) {
       el.offsetHeight;
       el.style.removeProperty("transition");
     }
   }
-  function persist(pref) {
+  function readRaw() {
     if (!isBrowser)
-      return;
+      return null;
     try {
-      localStorage.setItem(storageKey, pref);
-    } catch {}
+      return localStorage.getItem(storageKey);
+    } catch {
+      return null;
+    }
   }
-  function readPersisted() {
+  const storedRaw = readRaw();
+  let autoValue = autoValueOption ?? (storedRaw !== null && AUTO_VALUES.includes(storedRaw) ? storedRaw : "auto");
+  function persist(pref) {
     if (!isBrowser)
-      return null;
+      return;
     try {
-      const v = localStorage.getItem(storageKey);
-      if (v === "light" || v === "dark" || v === "auto")
-        return v;
+      localStorage.setItem(storageKey, pref === "auto" ? autoValue : pref);
     } catch {}
-    return null;
   }
-  function update(pref) {
-    preference = pref;
-    resolved = resolve(pref);
+  function update(pref, persistChoice = !0) {
+    preference = normalizeColorMode(pref) ?? "auto";
+    resolved = resolve(preference);
     applyToDOM(resolved);
-    persist(pref);
+    if (persistChoice)
+      persist(preference);
     listeners.forEach((fn) => fn(resolved, preference));
   }
-  const persisted = readPersisted();
-  update(persisted ?? initialMode);
+  update(normalizeColorMode(storedRaw) ?? initialMode, !1);
   if (isBrowser) {
     const mql = window.matchMedia("(prefers-color-scheme: dark)"), onSystemChange = () => {
       if (preference === "auto") {
@@ -72,8 +91,10 @@ export function useColorMode(options = {}) {
     const onStorage = (e) => {
       if (e.key !== storageKey)
         return;
-      const v = e.newValue;
-      if (v === "light" || v === "dark" || v === "auto") {
+      const v = normalizeColorMode(e.newValue);
+      if (v) {
+        if (v === "auto" && e.newValue && AUTO_VALUES.includes(e.newValue))
+          autoValue = e.newValue;
         preference = v;
         resolved = resolve(v);
         applyToDOM(resolved);

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

@@ -1,13 +1,20 @@
 /**
- * Navigate to a URL. Uses stxRouter if available, otherwise falls back to location.href.
+ * Navigate to a URL. Uses stxRouter if available, otherwise falls back to a
+ * full document load.
+ *
+ * Kept in step with the client runtime's `navigate` (#1807), which used to take
+ * a bare `forceReload` boolean while the shipped declaration promised
+ * `{ replace }` — so `navigate(url, { replace: true })` type-checked and then
+ * did a full load that PUSHED a history entry.
  *
  * @example
  * ```ts
  * navigate('/about')
- * navigate('https://example.com')
+ * navigate('/dashboard', { replace: true })
+ * navigate('/legacy', { reload: true })
  * ```
  */
-export declare function navigate(url: string): void;
+export declare function navigate(url: string, options?: NavigateOptions | boolean): void;
 /**
  * Go back in browser history.
  */
@@ -42,12 +49,6 @@ export declare function setRouteParams(params: Record<string, string>): void;
  * ```
  */
 export declare function useSearchParams(): SearchParamsRef;
-/**
- * useRouter - Navigation composable for STX applications
- *
- * Provides clean APIs for navigation without raw `window.location` or `window.history`.
- * These are server-safe stubs; the actual runtime implementations live in signals.ts.
- */
 export declare interface RouteInfo {
   path: string
   fullPath: string
@@ -55,9 +56,25 @@ export declare interface RouteInfo {
   query: Record<string, string>
   params: Record<string, string>
 }
+/**
+ * How a search-param mutation is written to session history.
+ *
+ * Spelled `{ replace }` to match `navigate()`, which already takes it — before
+ * this the two halves of the routing API disagreed on whether replacing was
+ * expressible at all.
+ */
+export declare interface SearchParamsCommitOptions {
+  replace?: boolean
+}
 export declare interface SearchParamsRef {
   data: { (): Record<string, string>, set: (v: Record<string, string>) => void }
   get: (key: string) => string | undefined
-  set: (key: string, value: string) => void
-  setAll: (obj: Record<string, string>) => void
+  has: (key: string) => boolean
+  set: (key: string, value: string, options?: SearchParamsCommitOptions) => void
+  delete: (key: string, options?: SearchParamsCommitOptions) => void
+  setAll: (obj: Record<string, string>, options?: SearchParamsCommitOptions) => void
+}
+export declare interface NavigateOptions {
+  replace?: boolean
+  reload?: boolean
 }

package/dist/composables/use-router.js

@@ -1,9 +1,16 @@
-export function navigate(url) {
-  if (typeof window < "u")
-    if (window.stxRouter?.navigate)
-      window.stxRouter.navigate(url);
-    else
-      window.location.href = url;
+import { state } from "../signals-api.js";
+export function navigate(url, options) {
+  if (typeof window > "u")
+    return;
+  const opts = options && typeof options === "object" ? options : { reload: !!options }, router = window.stxRouter;
+  if (!opts.reload && router?.navigate) {
+    router.navigate(url, { replace: !!opts.replace });
+    return;
+  }
+  if (opts.replace)
+    window.location.replace(url);
+  else
+    window.location.href = url;
 }
 export function goBack() {
   if (typeof window < "u")
@@ -45,7 +52,54 @@ export function setRouteParams(params) {
     window.stx.setRouteParams(params);
 }
 export function useSearchParams() {
-  return { data: Object.assign(() => ({}), { set: () => {} }), get: () => {
-    return;
-  }, set: () => {}, setAll: () => {} };
+  if (typeof window < "u" && window.stx?.useSearchParams)
+    return window.stx.useSearchParams();
+  if (typeof window > "u")
+    return {
+      data: Object.assign(() => ({}), { set: () => {} }),
+      get: () => {
+        return;
+      },
+      has: () => !1,
+      set: () => {},
+      delete: () => {},
+      setAll: () => {}
+    };
+  const read = () => {
+    const out = {};
+    new URLSearchParams(window.location.search).forEach((v, k) => {
+      out[k] = v;
+    });
+    return out;
+  }, data = state(read()), sync = () => data.set(read());
+  window.addEventListener("popstate", sync);
+  window.addEventListener("stx:navigate", sync);
+  const commit = (url, options) => {
+    if (!!(options && typeof options === "object" && options.replace))
+      window.history.replaceState({}, "", url);
+    else
+      window.history.pushState({}, "", url);
+    sync();
+  }, has = (key) => Object.prototype.hasOwnProperty.call(data(), key);
+  return {
+    data,
+    get: (key) => has(key) ? data()[key] : void 0,
+    has,
+    set: (key, value, options) => {
+      const url = new URL(window.location.href);
+      url.searchParams.set(key, value);
+      commit(url, options);
+    },
+    delete: (key, options) => {
+      const url = new URL(window.location.href);
+      url.searchParams.delete(key);
+      commit(url, options);
+    },
+    setAll: (obj, options) => {
+      const url = new URL(window.location.href);
+      for (const [k, v] of Object.entries(obj))
+        url.searchParams.set(k, v);
+      commit(url, options);
+    }
+  };
 }

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

@@ -1,3 +1,4 @@
+import type { Signal } from '../signals-api';
 /**
  * Create a reactive storage reference
  *
@@ -19,19 +20,23 @@
  */
 export declare function useStorage<T>(key: string, defaultValue: T, options?: UseStorageOptions<T>): StorageRef<T>;
 /**
- * Shorthand for useStorage with localStorage
+ * Reactive localStorage binding. Returns a Signal: `s()` reads, `s.set(v)`
+ * writes and persists.
  *
- * The return type is annotated rather than inferred on purpose: the shipped
- * declarations are emitted by bun-plugin-dtsx, which resolves an unannotated
- * export to `void`. Consumers importing from `@stacksjs/stx/composables` then
- * got `Property 'value' does not exist on type 'void'` for a function that
- * plainly returns a StorageRef. See stacksjs/stx#1796.
+ * The same shape the ambient `stx.d.ts` declares and the same shape a
+ * `<script client>` block gets from `window.stx` — one identifier, one
+ * contract, whichever way it's imported (stacksjs/stx#1797). It used to return
+ * a `StorageRef` here and a signal there, so `.value` worked or silently
+ * yielded `undefined` depending on which entry point resolved.
+ *
+ * For the richer object API — `.value`, `.remove()`, `.subscribe()`, custom
+ * serializers — use {@link useStorage}, which is unchanged.
  */
-export declare function useLocalStorage<T>(key: string, defaultValue: T, options?: Omit<UseStorageOptions<T>, 'storage'>): StorageRef<T>;
+export declare function useLocalStorage<T>(key: string, defaultValue: T, options?: Omit<UseStorageOptions<T>, 'storage'>): Signal<T>;
 /**
- * Shorthand for useStorage with sessionStorage
+ * Reactive sessionStorage binding. Returns a Signal — see {@link useLocalStorage}.
  */
-export declare function useSessionStorage<T>(key: string, defaultValue: T, options?: Omit<UseStorageOptions<T>, 'storage'>): StorageRef<T>;
+export declare function useSessionStorage<T>(key: string, defaultValue: T, options?: Omit<UseStorageOptions<T>, 'storage'>): Signal<T>;
 /**
  * Clear all items from storage
  */
@@ -61,10 +66,4 @@ export declare interface StorageRef<T> {
   remove: () => void
   subscribe: (callback: (value: T, prev: T | undefined) => void) => () => void
 }
-/**
- * useStorage - Reactive localStorage/sessionStorage composable
- *
- * Similar to Nuxt's useStorage but for STX applications.
- * Provides a reactive, type-safe wrapper around Web Storage APIs.
- */
 export type StorageType = 'local' | 'session';

package/dist/composables/use-storage.js

@@ -1,3 +1,4 @@
+import { effect, state } from "../signals-api.js";
 const defaultSerializer = {
   read: (value) => {
     try {
@@ -106,11 +107,71 @@ export function useStorage(key, defaultValue, options = {}) {
   };
   return ref;
 }
+function storageSignal(storageType, label, key, defaultValue, options = {}) {
+  const {
+    serializer = defaultSerializer,
+    mergeDefaults = !1,
+    listenToStorageChanges = !0
+  } = options, isClient = typeof window < "u", getStorage = () => {
+    if (!isClient)
+      return null;
+    return storageType === "session" ? sessionStorage : localStorage;
+  }, parse = (raw) => {
+    if (raw === null || raw === void 0)
+      return defaultValue;
+    try {
+      const parsed = serializer.read(raw);
+      if (mergeDefaults && typeof defaultValue === "object" && defaultValue !== null)
+        return { ...defaultValue, ...parsed };
+      return parsed;
+    } catch (e) {
+      console.warn(`[${label}] Failed to read key "${key}":`, e);
+      return defaultValue;
+    }
+  }, signal = state((() => {
+    const store = getStorage();
+    if (!store)
+      return defaultValue;
+    try {
+      return parse(store.getItem(key));
+    } catch (e) {
+      console.warn(`[${label}] Cannot read "${key}":`, e);
+      return defaultValue;
+    }
+  })());
+  effect(() => {
+    const value = signal(), store = getStorage();
+    if (!store)
+      return;
+    try {
+      if (value === null || value === void 0)
+        store.removeItem(key);
+      else
+        store.setItem(key, serializer.write(value));
+    } catch (e) {
+      console.warn(`[${label}] Cannot persist "${key}":`, e);
+    }
+  });
+  if (isClient && listenToStorageChanges) {
+    const onStorage = (event) => {
+      if (event.key !== key)
+        return;
+      if (event.storageArea && event.storageArea !== getStorage())
+        return;
+      signal.set(parse(event.newValue));
+    };
+    window.addEventListener("storage", onStorage);
+    const maybeOnDestroy = globalThis.onDestroy;
+    if (typeof maybeOnDestroy === "function")
+      maybeOnDestroy(() => window.removeEventListener("storage", onStorage));
+  }
+  return signal;
+}
 export function useLocalStorage(key, defaultValue, options) {
-  return useStorage(key, defaultValue, { ...options, storage: "local" });
+  return storageSignal("local", "useLocalStorage", key, defaultValue, options);
 }
 export function useSessionStorage(key, defaultValue, options) {
-  return useStorage(key, defaultValue, { ...options, storage: "session" });
+  return storageSignal("session", "useSessionStorage", key, defaultValue, options);
 }
 export function clearStorage(type = "local") {
   if (typeof window > "u")

package/dist/config.js

@@ -103,7 +103,7 @@ export const defaultConfig = {
   },
   router: {
     enabled: !0,
-    container: "#app-content",
+    container: "main",
     linkSelector: "a[href]",
     viewTransitions: !0,
     scrollToTop: !0,
@@ -360,18 +360,31 @@ export const defaultConfig = {
     verbose: !1
   }
 };
-function resolveStxRoot(configRoot, configPagesDir) {
+function resolveStxRoot(configRoot, configPagesDir, cwd) {
   const defaultPagesDir = configPagesDir || "pages";
   if (configRoot)
     return { root: configRoot, pagesDir: defaultPagesDir };
-  const resourcesViews = path.join(process.cwd(), "resources", "views"), resourcesLayouts = path.join(process.cwd(), "resources", "layouts");
+  const base = cwd || process.cwd(), resourcesViews = path.join(base, "resources", "views"), resourcesLayouts = path.join(base, "resources", "layouts");
   if (fs.existsSync(resourcesViews) && fs.existsSync(resourcesLayouts))
     return { root: "resources", pagesDir: "views" };
-  const resourcesViewsPages = path.join(process.cwd(), "resources", "views", "pages");
+  const resourcesViewsPages = path.join(base, "resources", "views", "pages");
   if (fs.existsSync(resourcesViewsPages))
     return { root: "resources/views", pagesDir: defaultPagesDir };
   return { root: ".", pagesDir: defaultPagesDir };
 }
+function warnMissingDirs(loaded, cwd) {
+  const keys = ["componentsDir", "layoutsDir", "partialsDir"];
+  for (const key of keys) {
+    const value = loaded[key];
+    if (typeof value !== "string" || !value)
+      continue;
+    const abs = path.isAbsolute(value) ? value : path.join(cwd, value);
+    if (fs.existsSync(abs))
+      continue;
+    const prefixed = !!loaded.root && loaded.root !== ".";
+    console.warn(`[stx] ${String(key)} resolves to "${abs}", which does not exist. Configured as "${value}"` + (prefixed ? ` and prefixed with root "${loaded.root}" \u2014 a value that already includes the root gets it twice.` : "."));
+  }
+}
 function applyStateDir(loaded) {
   setStateDir(loaded.stateDir);
   loaded.stateDir = stateDirName();
@@ -405,7 +418,7 @@ export async function loadStxConfig(cwd) {
       verbose: !1
     })).config;
     applyStateDir(loaded);
-    const resolved = resolveStxRoot(loaded.root, loaded.pagesDir);
+    const resolved = resolveStxRoot(loaded.root, loaded.pagesDir, effectiveCwd);
     loaded.root = resolved.root;
     loaded.pagesDir = resolved.pagesDir;
     if (loaded.root && loaded.root !== ".") {
@@ -417,6 +430,7 @@ export async function loadStxConfig(cwd) {
       if (loaded.layoutsDir && !path.isAbsolute(loaded.layoutsDir))
         loaded.layoutsDir = path.join(rootPrefix, loaded.layoutsDir);
     }
+    warnMissingDirs(loaded, effectiveCwd);
     if (loaded.plugins && loaded.plugins.length > 0) {
       const { pluginManager } = await import("./plugin-system.js"), pluginComponentDirs = [], pluginPageDirs = [];
       for (const pluginEntry of loaded.plugins) {
@@ -434,8 +448,9 @@ export async function loadStxConfig(cwd) {
           const plugin = pluginModule.default || pluginModule;
           pluginManager.register(plugin, loaded);
           if (plugin.components) {
-            const dir = path.resolve(pluginDir, plugin.components);
-            pluginComponentDirs.push(dir);
+            const dirs = Array.isArray(plugin.components) ? plugin.components : [plugin.components];
+            for (const entry of dirs)
+              pluginComponentDirs.push(path.resolve(pluginDir, entry));
           }
           if (plugin.pages) {
             const dir = path.resolve(pluginDir, plugin.pages), prefix = pluginOptions.path || "/";