@ohos-ports/stacksjs-stx 0.2.287-beta.0

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

@@ -0,0 +1,152 @@
+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;
+  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 = normalizeColorMode(initialMode) ?? "auto", resolved = "light";
+  const listeners = new Set, cleanups = [], isBrowser = typeof window < "u";
+  function getSystemPreference() {
+    if (!isBrowser)
+      return "light";
+    return window.matchMedia("(prefers-color-scheme: dark)").matches ? "dark" : "light";
+  }
+  function resolve(pref) {
+    return pref === "auto" ? getSystemPreference() : pref;
+  }
+  function applyToDOM(mode) {
+    if (!isBrowser)
+      return;
+    const el = document.documentElement;
+    if (disableTransitions)
+      el.style.setProperty("transition", "none", "important");
+    if (attribute)
+      el.setAttribute(attribute, mode);
+    if (darkClass)
+      if (mode === "dark")
+        el.classList.add(darkClass);
+      else
+        el.classList.remove(darkClass);
+    if (disableTransitions) {
+      el.offsetHeight;
+      el.style.removeProperty("transition");
+    }
+  }
+  function readRaw() {
+    if (!isBrowser)
+      return null;
+    try {
+      return localStorage.getItem(storageKey);
+    } catch {
+      return null;
+    }
+  }
+  const storedRaw = readRaw();
+  let autoValue = autoValueOption ?? (storedRaw !== null && AUTO_VALUES.includes(storedRaw) ? storedRaw : "auto");
+  function persist(pref) {
+    if (!isBrowser)
+      return;
+    try {
+      localStorage.setItem(storageKey, pref === "auto" ? autoValue : pref);
+    } catch {}
+  }
+  function update(pref, persistChoice = !0) {
+    preference = normalizeColorMode(pref) ?? "auto";
+    resolved = resolve(preference);
+    applyToDOM(resolved);
+    if (persistChoice)
+      persist(preference);
+    listeners.forEach((fn) => fn(resolved, preference));
+  }
+  update(normalizeColorMode(storedRaw) ?? initialMode, !1);
+  if (isBrowser) {
+    const mql = window.matchMedia("(prefers-color-scheme: dark)"), onSystemChange = () => {
+      if (preference === "auto") {
+        resolved = getSystemPreference();
+        applyToDOM(resolved);
+        listeners.forEach((fn) => fn(resolved, preference));
+      }
+    };
+    mql.addEventListener("change", onSystemChange);
+    cleanups.push(() => mql.removeEventListener("change", onSystemChange));
+    const onStorage = (e) => {
+      if (e.key !== storageKey)
+        return;
+      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);
+        listeners.forEach((fn) => fn(resolved, preference));
+      }
+    };
+    window.addEventListener("storage", onStorage);
+    cleanups.push(() => window.removeEventListener("storage", onStorage));
+  }
+  if (typeof globalThis.onDestroy === "function")
+    globalThis.onDestroy(() => {
+      cleanups.forEach((fn) => fn());
+      listeners.clear();
+    });
+  return {
+    get mode() {
+      return resolved;
+    },
+    get preference() {
+      return preference;
+    },
+    get isDark() {
+      return resolved === "dark";
+    },
+    set(mode) {
+      update(mode);
+    },
+    toggle() {
+      update(resolved === "dark" ? "light" : "dark");
+    },
+    subscribe(fn) {
+      listeners.add(fn);
+      return () => {
+        listeners.delete(fn);
+      };
+    }
+  };
+}
+export function useDark(options = {}) {
+  const cm = useColorMode(options);
+  return {
+    get isDark() {
+      return cm.isDark;
+    },
+    toggle() {
+      cm.toggle();
+    },
+    set(dark) {
+      cm.set(dark ? "dark" : "light");
+    },
+    subscribe(fn) {
+      return cm.subscribe((mode) => fn(mode === "dark"));
+    }
+  };
+}

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

@@ -0,0 +1,59 @@
+import type { Signal } from '../signals-api';
+/**
+ * Parse all cookies from `document.cookie` into a plain object.
+ */
+export declare function parseCookies(): Record<string, string>;
+/**
+ * Read a single cookie's value. Returns `null` when missing.
+ */
+export declare function getCookie(name: string): string | null;
+/**
+ * Write a cookie. No reactivity — use `useCookie()` for that.
+ */
+export declare function setCookie(name: string, value: string, options?: CookieOptions): void;
+/**
+ * Delete a cookie (sets max-age=0 and expires=epoch).
+ */
+export declare function removeCookie(name: string, options?: Pick<CookieOptions, 'path' | 'domain'>): void;
+/**
+ * Create a reactive Signal bound to a cookie. Mirrors `useLocalStorage`'s
+ * shape: read with `c()`, write with `c.set(v)`. Setting to `''` deletes the
+ * cookie. The signal is one-way (writes propagate to document.cookie on `set`);
+ * cookies don't fire a 'storage' event, so cross-tab updates aren't
+ * auto-reflected.
+ *
+ * Construction is a pure read: declaring a cookie writes nothing, so a caller
+ * that only wants the value cannot disturb the attributes its owner set. A
+ * `defaultValue` therefore does not reach `document.cookie` until something
+ * writes (#1933).
+ *
+ * @example
+ * ```ts
+ * const token = useCookie('auth-token', { maxAge: 60 * 60 * 24 * 7 })
+ * token()           // read current value
+ * token.set('xyz')  // persist
+ * token.set('')     // delete
+ * ```
+ */
+export declare function useCookie(name: string, options?: CookieOptions): Signal<string>;
+/**
+ * Snapshot of all currently-readable cookies as a plain object.
+ */
+export declare function useCookies(): Record<string, string>;
+/**
+ * Best-effort clear of every cookie visible to JavaScript. HttpOnly cookies
+ * and cookies under a different path/domain won't be touched.
+ */
+export declare function clearCookies(options?: Pick<CookieOptions, 'path' | 'domain'>): void;
+export declare interface CookieOptions {
+  maxAge?: number
+  expires?: Date | number | string
+  path?: string
+  domain?: string
+  secure?: boolean
+  httpOnly?: boolean
+  sameSite?: 'strict' | 'lax' | 'none' | 'Strict' | 'Lax' | 'None'
+  defaultValue?: string
+  encode?: (value: string) => string
+  decode?: (value: string) => string
+}

package/dist/composables/use-cookie.js

@@ -0,0 +1,86 @@
+import { state } from "../signals-api.js";
+const defaultEncode = encodeURIComponent, defaultDecode = decodeURIComponent;
+export function parseCookies() {
+  if (typeof document > "u")
+    return {};
+  const cookies = {}, pairs = document.cookie.split(";");
+  for (const pair of pairs) {
+    const [key, ...valueParts] = pair.trim().split("=");
+    if (key)
+      try {
+        cookies[key] = defaultDecode(valueParts.join("="));
+      } catch {
+        cookies[key] = valueParts.join("=");
+      }
+  }
+  return cookies;
+}
+export function getCookie(name) {
+  return parseCookies()[name] ?? null;
+}
+function serializeAttrs(name, value, options) {
+  const {
+    maxAge,
+    expires,
+    path = "/",
+    domain,
+    secure,
+    sameSite = "Lax",
+    encode = defaultEncode
+  } = options, parts = [`${name}=${value ? encode(value) : ""}`];
+  if (path)
+    parts.push(`path=${path}`);
+  if (domain)
+    parts.push(`domain=${domain}`);
+  if (value === "")
+    parts.push("max-age=0");
+  else if (typeof maxAge === "number")
+    parts.push(`max-age=${maxAge}`);
+  else if (expires !== void 0) {
+    const expiresDate = expires instanceof Date ? expires : typeof expires === "number" ? new Date(Date.now() + expires * 1000) : new Date(expires);
+    parts.push(`expires=${expiresDate.toUTCString()}`);
+  }
+  parts.push(`SameSite=${sameSite}`);
+  let secureFinal = secure;
+  if (secureFinal === void 0)
+    secureFinal = typeof location < "u" && location.protocol === "https:";
+  if (secureFinal)
+    parts.push("Secure");
+  return parts.join("; ");
+}
+export function setCookie(name, value, options = {}) {
+  if (typeof document > "u")
+    return;
+  document.cookie = serializeAttrs(name, value, options);
+}
+export function removeCookie(name, options = {}) {
+  setCookie(name, "", {
+    ...options,
+    maxAge: 0,
+    expires: new Date(0)
+  });
+}
+export function useCookie(name, options = {}) {
+  const decode = options.decode || defaultDecode, defaultValue = options.defaultValue ?? "", escapedName = name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"), nameRe = new RegExp(`(?:^|; )${escapedName}=([^;]*)`);
+  function read() {
+    if (typeof document > "u")
+      return defaultValue;
+    const m = document.cookie.match(nameRe);
+    return m ? decode(m[1]) : defaultValue;
+  }
+  const s = state(read());
+  s.subscribe((value) => {
+    if (typeof document > "u")
+      return;
+    document.cookie = serializeAttrs(name, value, options);
+  });
+  return s;
+}
+export function useCookies() {
+  return parseCookies();
+}
+export function clearCookies(options = {}) {
+  const cookies = parseCookies();
+  for (const name of Object.keys(cookies))
+    removeCookie(name, options);
+}

package/dist/composables/use-device-orientation.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Check if DeviceOrientation is supported
+ */
+export declare function isDeviceOrientationSupported(): boolean;
+/**
+ * Check if DeviceMotion is supported
+ */
+export declare function isDeviceMotionSupported(): boolean;
+/**
+ * Request permission for device orientation (required on iOS 13+)
+ */
+export declare function requestOrientationPermission(): Promise<boolean>;
+/**
+ * Request permission for device motion (required on iOS 13+)
+ */
+export declare function requestMotionPermission(): Promise<boolean>;
+/**
+ * Create a reactive device orientation tracker
+ *
+ * @example
+ * ```ts
+ * const orientation = useDeviceOrientation()
+ *
+ * // Request permission first (required on iOS)
+ * await orientation.requestPermission()
+ *
+ * // Subscribe to orientation changes
+ * orientation.subscribe((state) => {
+ *   console.log('Alpha (compass):', state.alpha)
+ *   console.log('Beta (front/back):', state.beta)
+ *   console.log('Gamma (left/right):', state.gamma)
+ * })
+ * ```
+ */
+export declare function useDeviceOrientation(): DeviceOrientationRef;
+/**
+ * Create a reactive device motion tracker
+ *
+ * @example
+ * ```ts
+ * const motion = useDeviceMotion()
+ *
+ * // Request permission first (required on iOS)
+ * await motion.requestPermission()
+ *
+ * // Subscribe to motion changes
+ * motion.subscribe((state) => {
+ *   console.log('Acceleration:', state.acceleration)
+ *   console.log('Rotation rate:', state.rotationRate)
+ * })
+ * ```
+ */
+export declare function useDeviceMotion(): DeviceMotionRef;
+/**
+ * Simple tilt detection for parallax effects
+ *
+ * @example
+ * ```ts
+ * const tilt = useParallax()
+ *
+ * tilt.subscribe(({ x, y }) => {
+ *   element.style.transform = `translate(${x * 10}px, ${y * 10}px)`
+ * })
+ * ```
+ */
+export declare function useParallax(): ParallaxRef;
+/**
+ * Device Orientation & Motion Composables
+ *
+ * Reactive utilities for device orientation and motion sensors.
+ */
+export declare interface DeviceOrientationState {
+  isSupported: boolean
+  isAbsolute: boolean
+  alpha: number | null
+  beta: number | null
+  gamma: number | null
+}
+export declare interface DeviceMotionState {
+  isSupported: boolean
+  acceleration: {
+    x: number | null
+    y: number | null
+    z: number | null
+  }
+  accelerationIncludingGravity: {
+    x: number | null
+    y: number | null
+    z: number | null
+  }
+  rotationRate: {
+    alpha: number | null
+    beta: number | null
+    gamma: number | null
+  }
+  interval: number
+}
+export declare interface DeviceOrientationRef {
+  get: () => DeviceOrientationState
+  subscribe: (fn: (state: DeviceOrientationState) => void) => () => void
+  isSupported: () => boolean
+  requestPermission: () => Promise<boolean>
+}
+/** Handle returned by {@link useParallax}. */
+export declare interface ParallaxRef {
+  get: () => { x: number, y: number }
+  subscribe: (fn: (state: { x: number, y: number }) => void) => () => void
+  isSupported: () => boolean
+  requestPermission: () => Promise<boolean>
+}
+export declare interface DeviceMotionRef {
+  get: () => DeviceMotionState
+  subscribe: (fn: (state: DeviceMotionState) => void) => () => void
+  isSupported: () => boolean
+  requestPermission: () => Promise<boolean>
+}

package/dist/composables/use-device-orientation.js

@@ -0,0 +1,181 @@
+export function isDeviceOrientationSupported() {
+  return typeof window < "u" && "DeviceOrientationEvent" in window;
+}
+export function isDeviceMotionSupported() {
+  return typeof window < "u" && "DeviceMotionEvent" in window;
+}
+export async function requestOrientationPermission() {
+  if (typeof window > "u")
+    return !1;
+  const DeviceOrientationEvent = window.DeviceOrientationEvent;
+  if (typeof DeviceOrientationEvent?.requestPermission === "function")
+    try {
+      return await DeviceOrientationEvent.requestPermission() === "granted";
+    } catch {
+      return !1;
+    }
+  return !0;
+}
+export async function requestMotionPermission() {
+  if (typeof window > "u")
+    return !1;
+  const DeviceMotionEvent = window.DeviceMotionEvent;
+  if (typeof DeviceMotionEvent?.requestPermission === "function")
+    try {
+      return await DeviceMotionEvent.requestPermission() === "granted";
+    } catch {
+      return !1;
+    }
+  return !0;
+}
+export function useDeviceOrientation() {
+  const supported = isDeviceOrientationSupported(), subscribers = new Set;
+  let state = {
+    isSupported: supported,
+    isAbsolute: !1,
+    alpha: null,
+    beta: null,
+    gamma: null
+  }, cleanup = null;
+  function notify() {
+    subscribers.forEach((fn) => fn(state));
+  }
+  function handleOrientation(event) {
+    state = {
+      ...state,
+      isAbsolute: event.absolute,
+      alpha: event.alpha,
+      beta: event.beta,
+      gamma: event.gamma
+    };
+    notify();
+  }
+  function startListening() {
+    if (!supported || cleanup)
+      return;
+    window.addEventListener("deviceorientation", handleOrientation, !0);
+    cleanup = () => {
+      window.removeEventListener("deviceorientation", handleOrientation, !0);
+    };
+  }
+  function stopListening() {
+    cleanup?.();
+    cleanup = null;
+  }
+  async function requestPermission() {
+    const granted = await requestOrientationPermission();
+    if (granted)
+      startListening();
+    return granted;
+  }
+  if (supported)
+    startListening();
+  return {
+    get: () => state,
+    subscribe: (fn) => {
+      subscribers.add(fn);
+      fn(state);
+      return () => {
+        subscribers.delete(fn);
+        if (subscribers.size === 0)
+          stopListening();
+      };
+    },
+    isSupported: () => supported,
+    requestPermission
+  };
+}
+export function useDeviceMotion() {
+  const supported = isDeviceMotionSupported(), subscribers = new Set;
+  let state = {
+    isSupported: supported,
+    acceleration: { x: null, y: null, z: null },
+    accelerationIncludingGravity: { x: null, y: null, z: null },
+    rotationRate: { alpha: null, beta: null, gamma: null },
+    interval: 0
+  }, cleanup = null;
+  function notify() {
+    subscribers.forEach((fn) => fn(state));
+  }
+  function handleMotion(event) {
+    state = {
+      ...state,
+      acceleration: {
+        x: event.acceleration?.x ?? null,
+        y: event.acceleration?.y ?? null,
+        z: event.acceleration?.z ?? null
+      },
+      accelerationIncludingGravity: {
+        x: event.accelerationIncludingGravity?.x ?? null,
+        y: event.accelerationIncludingGravity?.y ?? null,
+        z: event.accelerationIncludingGravity?.z ?? null
+      },
+      rotationRate: {
+        alpha: event.rotationRate?.alpha ?? null,
+        beta: event.rotationRate?.beta ?? null,
+        gamma: event.rotationRate?.gamma ?? null
+      },
+      interval: event.interval
+    };
+    notify();
+  }
+  function startListening() {
+    if (!supported || cleanup)
+      return;
+    window.addEventListener("devicemotion", handleMotion, !0);
+    cleanup = () => {
+      window.removeEventListener("devicemotion", handleMotion, !0);
+    };
+  }
+  function stopListening() {
+    cleanup?.();
+    cleanup = null;
+  }
+  async function requestPermission() {
+    const granted = await requestMotionPermission();
+    if (granted)
+      startListening();
+    return granted;
+  }
+  if (supported)
+    startListening();
+  return {
+    get: () => state,
+    subscribe: (fn) => {
+      subscribers.add(fn);
+      fn(state);
+      return () => {
+        subscribers.delete(fn);
+        if (subscribers.size === 0)
+          stopListening();
+      };
+    },
+    isSupported: () => supported,
+    requestPermission
+  };
+}
+export function useParallax() {
+  const orientation = useDeviceOrientation(), subscribers = new Set;
+  let tilt = { x: 0, y: 0 };
+  orientation.subscribe((state) => {
+    if (state.gamma !== null && state.beta !== null) {
+      tilt = {
+        x: Math.max(-1, Math.min(1, (state.gamma || 0) / 45)),
+        y: Math.max(-1, Math.min(1, (state.beta || 0) / 45))
+      };
+      subscribers.forEach((fn) => fn(tilt));
+    }
+  });
+  return {
+    get: () => tilt,
+    subscribe: (fn) => {
+      subscribers.add(fn);
+      fn(tilt);
+      return () => {
+        subscribers.delete(fn);
+      };
+    },
+    isSupported: orientation.isSupported,
+    requestPermission: orientation.requestPermission
+  };
+}

package/dist/composables/use-event-listener.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Attach an event listener with auto-cleanup.
+ *
+ * @example
+ * ```ts
+ * // Listen on window (default)
+ * useEventListener('resize', () => console.log('resized'))
+ *
+ * // Listen on document
+ * useEventListener('click', handler, { target: document })
+ *
+ * // Listen on a specific element by selector
+ * useEventListener('click', handler, { target: '#my-button' })
+ *
+ * // Manual removal
+ * const { remove } = useEventListener('scroll', handler)
+ * remove()
+ * ```
+ */
+export declare function useEventListener(event: string, handler: EventListenerOrEventListenerObject, options?: UseEventListenerOptions): EventListenerRef;
+/**
+ * useEventListener - Event listener composable with auto-cleanup
+ *
+ * Attaches event listeners and automatically removes them on component destroy.
+ * Replaces raw `window.addEventListener` / `document.addEventListener` usage.
+ */
+export declare interface UseEventListenerOptions {
+  target?: EventTarget | string
+  capture?: boolean
+  passive?: boolean
+  once?: boolean
+}
+export declare interface EventListenerRef {
+  remove: () => void
+}

package/dist/composables/use-event-listener.js

@@ -0,0 +1,27 @@
+export function useEventListener(event, handler, options) {
+  if (typeof window > "u")
+    return { remove: () => {} };
+  let target = window;
+  if (options?.target)
+    if (typeof options.target === "string") {
+      const resolved = document.querySelector(options.target);
+      if (!resolved) {
+        console.warn(`[stx] useEventListener: selector "${options.target}" did not match any element. Listener not attached.`);
+        return { remove: () => {} };
+      }
+      target = resolved;
+    } else
+      target = options.target;
+  const listenerOptions = {
+    capture: options?.capture,
+    passive: options?.passive,
+    once: options?.once
+  };
+  target.addEventListener(event, handler, listenerOptions);
+  const remove = () => {
+    target.removeEventListener(event, handler, listenerOptions);
+  };
+  if (typeof globalThis.onDestroy === "function")
+    globalThis.onDestroy(remove);
+  return { remove };
+}