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

package/dist/composables/use-fetch.js

@@ -0,0 +1,273 @@
+import { state } from "../signals-api.js";
+const fetchCache = new Map;
+function buildURL(url, baseURL, query) {
+  let fullURL = baseURL ? `${baseURL.replace(/\/$/, "")}/${url.replace(/^\//, "")}` : url;
+  if (query) {
+    const params = new URLSearchParams;
+    for (const [key, value] of Object.entries(query))
+      if (value !== void 0)
+        params.append(key, String(value));
+    const queryString = params.toString();
+    if (queryString)
+      fullURL += (fullURL.includes("?") ? "&" : "?") + queryString;
+  }
+  return fullURL;
+}
+export function useFetch(url, options = {}) {
+  const {
+    immediate = !0,
+    transform,
+    parseResponse = (r) => r.json(),
+    timeout = 30000,
+    retry = 0,
+    retryDelay = 1000,
+    key,
+    cacheTime = 0,
+    refetchOnFocus = !1,
+    refetchInterval,
+    initialData = null,
+    baseURL,
+    query,
+    body,
+    ...fetchOptions
+  } = options, data = state(initialData), loading = state(!1), isFetching = state(!1), error = state(null), status = state(null), statusText = state(null);
+  let abortController = null, focusHandler = null, intervalId = null;
+  const getURL = () => {
+    const rawURL = typeof url === "function" ? url() : url;
+    return buildURL(rawURL, baseURL, query);
+  }, getCacheKey = () => key || getURL(), getFromCache = () => {
+    if (cacheTime <= 0)
+      return null;
+    const cached = fetchCache.get(getCacheKey());
+    if (cached && Date.now() - cached.timestamp < cacheTime)
+      return cached.data;
+    return null;
+  }, setCache = (value) => {
+    if (cacheTime > 0)
+      fetchCache.set(getCacheKey(), { data: value, timestamp: Date.now() });
+  }, doFetch = async (attempt = 0, background = !1) => {
+    const cached = getFromCache();
+    if (cached !== null) {
+      data.set(cached);
+      loading.set(!1);
+      isFetching.set(!1);
+      error.set(null);
+      return;
+    }
+    if (abortController)
+      abortController.abort();
+    abortController = new AbortController;
+    if (!background)
+      loading.set(!0);
+    isFetching.set(!0);
+    if (!background)
+      error.set(null);
+    const timeoutId = setTimeout(() => abortController?.abort(), timeout);
+    try {
+      let requestBody;
+      if (body)
+        if (typeof body === "object" && !(body instanceof FormData) && !(body instanceof URLSearchParams)) {
+          requestBody = JSON.stringify(body);
+          fetchOptions.headers = {
+            "Content-Type": "application/json",
+            ...fetchOptions.headers
+          };
+        } else
+          requestBody = body;
+      const response = await fetch(getURL(), {
+        ...fetchOptions,
+        body: requestBody,
+        signal: abortController.signal
+      });
+      clearTimeout(timeoutId);
+      status.set(response.status);
+      statusText.set(response.statusText);
+      if (!response.ok) {
+        let body = null;
+        try {
+          const text = await response.text();
+          if (text)
+            try {
+              body = JSON.parse(text);
+            } catch {
+              body = text;
+            }
+        } catch {
+          body = null;
+        }
+        let detail = "";
+        if (body && typeof body === "object")
+          detail = String(body.message ?? body.error ?? "");
+        else if (typeof body === "string")
+          detail = body.slice(0, 200);
+        let message = `HTTP ${response.status}`;
+        if (response.statusText)
+          message += `: ${response.statusText}`;
+        if (detail)
+          message += ` - ${detail}`;
+        const httpError = Error(message);
+        httpError.status = response.status;
+        httpError.statusText = response.statusText;
+        httpError.data = body;
+        httpError.response = response;
+        throw httpError;
+      }
+      let payload = await parseResponse(response);
+      if (transform)
+        payload = transform(payload);
+      setCache(payload);
+      data.set(payload);
+      if (background)
+        error.set(null);
+      if (!background)
+        loading.set(!1);
+      isFetching.set(!1);
+    } catch (err) {
+      clearTimeout(timeoutId);
+      if (err instanceof Error && err.name === "AbortError")
+        return;
+      if (attempt < retry) {
+        await new Promise((resolve) => setTimeout(resolve, retryDelay));
+        return doFetch(attempt + 1, background);
+      }
+      error.set(err instanceof Error ? err : Error(String(err)));
+      if (!background)
+        loading.set(!1);
+      isFetching.set(!1);
+    }
+  }, setupRefetchOnFocus = () => {
+    if (!refetchOnFocus || typeof window > "u")
+      return;
+    focusHandler = () => {
+      if (document.visibilityState === "visible")
+        doFetch(0, !0);
+    };
+    document.addEventListener("visibilitychange", focusHandler);
+  }, setupRefetchInterval = () => {
+    if (!refetchInterval || typeof window > "u")
+      return;
+    intervalId = setInterval(() => void doFetch(0, !0), refetchInterval);
+  };
+  if (immediate) {
+    doFetch();
+    setupRefetchOnFocus();
+    setupRefetchInterval();
+  }
+  return {
+    data,
+    loading,
+    isFetching,
+    error,
+    status,
+    statusText,
+    refetch: (refetchOptions) => doFetch(0, !!refetchOptions?.background),
+    execute: async () => {
+      await doFetch();
+      setupRefetchOnFocus();
+      setupRefetchInterval();
+    },
+    abort: () => {
+      if (abortController)
+        abortController.abort();
+      if (focusHandler) {
+        document.removeEventListener("visibilitychange", focusHandler);
+        focusHandler = null;
+      }
+      if (intervalId) {
+        clearInterval(intervalId);
+        intervalId = null;
+      }
+    }
+  };
+}
+export function useAsyncData(fetcher, options = {}) {
+  const {
+    immediate = !0,
+    transform,
+    initialData = null,
+    key,
+    cacheTime = 0
+  } = options, data = state(initialData), loading = state(!1), isFetching = state(!1), error = state(null), status = state(null), statusText = state(null), getCacheKey = () => key || fetcher.toString(), getFromCache = () => {
+    if (cacheTime <= 0)
+      return null;
+    const cached = fetchCache.get(getCacheKey());
+    if (cached && Date.now() - cached.timestamp < cacheTime)
+      return cached.data;
+    return null;
+  }, setCache = (value) => {
+    if (cacheTime > 0)
+      fetchCache.set(getCacheKey(), { data: value, timestamp: Date.now() });
+  }, doFetch = async (background = !1) => {
+    const cached = getFromCache();
+    if (cached !== null) {
+      data.set(cached);
+      loading.set(!1);
+      isFetching.set(!1);
+      error.set(null);
+      return;
+    }
+    if (!background)
+      loading.set(!0);
+    isFetching.set(!0);
+    if (!background)
+      error.set(null);
+    try {
+      let payload = await fetcher();
+      if (transform)
+        payload = transform(payload);
+      setCache(payload);
+      data.set(payload);
+      if (background)
+        error.set(null);
+      if (!background)
+        loading.set(!1);
+      isFetching.set(!1);
+    } catch (err) {
+      error.set(err instanceof Error ? err : Error(String(err)));
+      if (!background)
+        loading.set(!1);
+      isFetching.set(!1);
+    }
+  };
+  if (immediate)
+    doFetch();
+  return {
+    data,
+    loading,
+    isFetching,
+    error,
+    status,
+    statusText,
+    refetch: (refetchOptions) => doFetch(!!refetchOptions?.background),
+    execute: () => doFetch(),
+    abort: () => {}
+  };
+}
+export function usePost(url, options = {}) {
+  let requestBody;
+  const fetchState = useFetch(url, {
+    ...options,
+    method: "POST",
+    immediate: !1,
+    get body() {
+      return requestBody;
+    }
+  });
+  return {
+    execute: async (body) => {
+      requestBody = body;
+      await fetchState.execute();
+      return fetchState.data();
+    },
+    state: fetchState
+  };
+}
+export function clearFetchCache(key) {
+  if (key)
+    fetchCache.delete(key);
+  else
+    fetchCache.clear();
+}
+export async function prefetch(url, options) {
+  await useFetch(url, { ...options, immediate: !1 }).execute();
+}

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/use-fullscreen.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Reactive fullscreen controller
+ */
+export declare function useFullscreen(target?: Element | (() => Element | null) | null, options?: FullscreenOptions): FullscreenRef;
+/**
+ * Simple fullscreen toggle for document
+ */
+export declare function toggleFullscreen(): Promise<void>;
+/**
+ * Check if currently in fullscreen mode
+ */
+export declare function isInFullscreen(): boolean;
+/**
+ * useFullscreen - Reactive Fullscreen API wrapper
+ *
+ * Control fullscreen mode for elements or the entire document.
+ *
+ * @example
+ * ```ts
+ * // Document fullscreen
+ * const { isFullscreen, toggle, enter, exit } = useFullscreen()
+ *
+ * // Element fullscreen
+ * const { isFullscreen, toggle } = useFullscreen(videoElement)
+ *
+ * // With keyboard shortcut
+ * useHotkey('f', () => toggle())
+ * ```
+ */
+export declare interface FullscreenState {
+  isFullscreen: boolean
+  isSupported: boolean
+  element: Element | null
+}
+export declare interface FullscreenOptions {
+  navigationUI?: 'auto' | 'hide' | 'show'
+  autoExit?: boolean
+}
+export declare interface FullscreenRef {
+  get: () => FullscreenState
+  subscribe: (fn: (state: FullscreenState) => void) => () => void
+  isFullscreen: () => boolean
+  isSupported: () => boolean
+  enter: () => Promise<void>
+  exit: () => Promise<void>
+  toggle: () => Promise<void>
+}

package/dist/composables/use-fullscreen.js

@@ -0,0 +1,110 @@
+function getFullscreenElement() {
+  return document.fullscreenElement || document.webkitFullscreenElement || document.mozFullScreenElement || document.msFullscreenElement || null;
+}
+function isFullscreenSupported() {
+  return !!(document.fullscreenEnabled || document.webkitFullscreenEnabled || document.mozFullScreenEnabled || document.msFullscreenEnabled);
+}
+async function requestFullscreen(element, options) {
+  const opts = options?.navigationUI ? { navigationUI: options.navigationUI } : void 0;
+  if (element.requestFullscreen)
+    await element.requestFullscreen(opts);
+  else if (element.webkitRequestFullscreen)
+    await element.webkitRequestFullscreen();
+  else if (element.mozRequestFullScreen)
+    await element.mozRequestFullScreen();
+  else if (element.msRequestFullscreen)
+    await element.msRequestFullscreen();
+}
+async function exitFullscreen() {
+  if (document.exitFullscreen)
+    await document.exitFullscreen();
+  else if (document.webkitExitFullscreen)
+    await document.webkitExitFullscreen();
+  else if (document.mozCancelFullScreen)
+    await document.mozCancelFullScreen();
+  else if (document.msExitFullscreen)
+    await document.msExitFullscreen();
+}
+export function useFullscreen(target, options = {}) {
+  const supported = typeof document < "u" && isFullscreenSupported();
+  let state = {
+    isFullscreen: !1,
+    isSupported: supported,
+    element: null
+  }, listeners = [], cleanup = null;
+  const getElement = () => {
+    if (!target)
+      return document.documentElement;
+    if (typeof target === "function")
+      return target() || document.documentElement;
+    return target;
+  }, notify = () => {
+    listeners.forEach((fn) => fn(state));
+  }, updateState = () => {
+    const fullscreenElement = getFullscreenElement();
+    state = {
+      ...state,
+      isFullscreen: !!fullscreenElement,
+      element: fullscreenElement
+    };
+    notify();
+  }, setupListeners = () => {
+    if (typeof document > "u")
+      return;
+    const events = [
+      "fullscreenchange",
+      "webkitfullscreenchange",
+      "mozfullscreenchange",
+      "MSFullscreenChange"
+    ];
+    for (const event of events)
+      document.addEventListener(event, updateState);
+    cleanup = () => {
+      for (const event of events)
+        document.removeEventListener(event, updateState);
+    };
+    updateState();
+  }, enter = async () => {
+    if (!supported)
+      return;
+    const element = getElement();
+    await requestFullscreen(element, options);
+  }, exit = async () => {
+    if (!supported)
+      return;
+    if (getFullscreenElement())
+      await exitFullscreen();
+  };
+  return {
+    get: () => state,
+    subscribe: (fn) => {
+      if (listeners.length === 0)
+        setupListeners();
+      listeners.push(fn);
+      fn(state);
+      return () => {
+        listeners = listeners.filter((l) => l !== fn);
+        if (listeners.length === 0 && cleanup) {
+          cleanup();
+          cleanup = null;
+        }
+      };
+    },
+    isFullscreen: () => state.isFullscreen,
+    isSupported: () => state.isSupported,
+    enter,
+    exit,
+    toggle: async () => {
+      if (state.isFullscreen)
+        await exit();
+      else
+        await enter();
+    }
+  };
+}
+export function toggleFullscreen() {
+  return useFullscreen().toggle();
+}
+export function isInFullscreen() {
+  return !!getFullscreenElement();
+}

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

@@ -0,0 +1,62 @@
+/**
+ * Get current position as a Promise
+ */
+export declare function getCurrentPosition(options?: PositionOptions): Promise<GeolocationPosition>;
+/**
+ * Calculate distance between two coordinates (Haversine formula)
+ * @returns Distance in meters
+ */
+export declare function calculateDistance(lat1: number, lon1: number, lat2: number, lon2: number): number;
+/**
+ * Reactive geolocation composable with watch support
+ */
+export declare function useGeolocation(options?: GeolocationOptions): GeolocationRef;
+/**
+ * Watch position changes (alias for useGeolocation with watch)
+ */
+export declare function useGeolocationWatch(options?: GeolocationOptions): GeolocationRef;
+/**
+ * useGeolocation - Reactive Geolocation API wrapper
+ *
+ * Provides easy access to the browser's Geolocation API with reactive state.
+ *
+ * @example
+ * ```ts
+ * const geo = useGeolocation()
+ * geo.subscribe(state => {
+ *   console.log(state.coords?.latitude, state.coords?.longitude)
+ * })
+ *
+ * // Or get current position once
+ * const position = await getCurrentPosition()
+ * ```
+ */
+export declare interface GeolocationCoords {
+  latitude: number
+  longitude: number
+  altitude: number | null
+  accuracy: number
+  altitudeAccuracy: number | null
+  heading: number | null
+  speed: number | null
+}
+export declare interface GeolocationState {
+  coords: GeolocationCoords | null
+  timestamp: number | null
+  error: GeolocationPositionError | null
+  loading: boolean
+  supported: boolean
+}
+export declare interface GeolocationOptions {
+  enableHighAccuracy?: boolean
+  timeout?: number
+  maximumAge?: number
+  immediate?: boolean
+}
+export declare interface GeolocationRef {
+  get: () => GeolocationState
+  subscribe: (fn: (state: GeolocationState) => void) => () => void
+  refresh: () => void
+  pause: () => void
+  resume: () => void
+}