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

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

@@ -0,0 +1,98 @@
+/**
+ * Reactive notification controller
+ */
+export declare function useNotification(): NotificationRef;
+/**
+ * Simple notification helper
+ */
+export declare function notify(title: string, options?: NotificationOptions): Promise<Notification | null>;
+/**
+ * Check if notifications are supported and permitted
+ */
+export declare function canNotify(): boolean;
+/**
+ * Request notification permission
+ */
+export declare function requestNotificationPermission(): Promise<NotificationPermission>;
+/**
+ * Show notification with common patterns
+ * @defaultValue
+ * ```ts
+ * {
+ *   success: (message: string, options?: NotificationOptions) => unknown,
+ *   error: (message: string, options?: NotificationOptions) => unknown,
+ *   warning: (message: string, options?: NotificationOptions) => unknown,
+ *   info: (message: string, options?: NotificationOptions) => unknown
+ * }
+ * ```
+ */
+export declare const notifications: {
+  /** Success notification */
+  success: (message: string, options?: NotificationOptions) => unknown;
+  /** Error notification */
+  error: (message: string, options?: NotificationOptions) => unknown;
+  /** Warning notification */
+  warning: (message: string, options?: NotificationOptions) => unknown;
+  /** Info notification */
+  info: (message: string, options?: NotificationOptions) => unknown
+};
+export declare interface NotificationState {
+  permission: NotificationPermission
+  isSupported: boolean
+}
+export declare interface NotificationOptions {
+  body?: string
+  icon?: string
+  badge?: string
+  image?: string
+  tag?: string
+  requireInteraction?: boolean
+  renotify?: boolean
+  silent?: boolean
+  vibrate?: number | number[]
+  data?: unknown
+  autoClose?: number
+  dir?: 'auto' | 'ltr' | 'rtl'
+  lang?: string
+  actions?: NotificationAction[]
+  timestamp?: number
+}
+export declare interface NotificationAction {
+  action: string
+  title: string
+  icon?: string
+}
+export declare interface NotificationRef {
+  get: () => NotificationState
+  subscribe: (fn: (state: NotificationState) => void) => () => void
+  isSupported: () => boolean
+  permission: () => NotificationPermission
+  requestPermission: () => Promise<NotificationPermission>
+  show: (title: string, options?: NotificationOptions) => Notification | null
+  close: (tag: string) => void
+}
+/**
+ * useNotification - Web Notifications API wrapper
+ *
+ * Display native browser notifications with reactive permission state.
+ *
+ * @example
+ * ```ts
+ * const { permission, isSupported, show, requestPermission } = useNotification()
+ *
+ * // Request permission
+ * await requestPermission()
+ *
+ * // Show notification
+ * const notification = show('Hello!', {
+ *   body: 'This is a notification',
+ *   icon: '/icon.png',
+ * })
+ *
+ * // Handle click
+ * notification?.addEventListener('click', () => {
+ *   window.focus()
+ * })
+ * ```
+ */
+export type NotificationPermission = 'default' | 'granted' | 'denied';

package/dist/composables/use-notification.js

@@ -0,0 +1,94 @@
+const activeNotifications = new Map;
+export function useNotification() {
+  const isSupported = typeof window < "u" && "Notification" in window;
+  let state = {
+    permission: isSupported ? Notification.permission : "denied",
+    isSupported
+  }, listeners = [];
+  const notify = () => {
+    listeners.forEach((fn) => fn(state));
+  }, updatePermission = () => {
+    if (!isSupported)
+      return;
+    state = {
+      ...state,
+      permission: Notification.permission
+    };
+    notify();
+  };
+  return {
+    get: () => state,
+    subscribe: (fn) => {
+      listeners.push(fn);
+      fn(state);
+      return () => {
+        listeners = listeners.filter((l) => l !== fn);
+      };
+    },
+    isSupported: () => state.isSupported,
+    permission: () => state.permission,
+    requestPermission: async () => {
+      if (!isSupported)
+        return "denied";
+      try {
+        const result = await Notification.requestPermission();
+        state = { ...state, permission: result };
+        notify();
+        return result;
+      } catch {
+        return state.permission;
+      }
+    },
+    show: (title, options = {}) => {
+      if (!isSupported || state.permission !== "granted")
+        return null;
+      const { autoClose, ...notificationOptions } = options;
+      try {
+        const notification = new Notification(title, notificationOptions);
+        if (options.tag) {
+          const existing = activeNotifications.get(options.tag);
+          if (existing)
+            existing.close();
+          activeNotifications.set(options.tag, notification);
+          notification.addEventListener("close", () => {
+            activeNotifications.delete(options.tag);
+          });
+        }
+        if (autoClose && autoClose > 0)
+          setTimeout(() => {
+            notification.close();
+          }, autoClose);
+        return notification;
+      } catch {
+        return null;
+      }
+    },
+    close: (tag) => {
+      const notification = activeNotifications.get(tag);
+      if (notification) {
+        notification.close();
+        activeNotifications.delete(tag);
+      }
+    }
+  };
+}
+export async function notify(title, options) {
+  const notifier = useNotification();
+  if (notifier.permission() === "default")
+    await notifier.requestPermission();
+  return notifier.show(title, options);
+}
+export function canNotify() {
+  return typeof window < "u" && "Notification" in window && Notification.permission === "granted";
+}
+export async function requestNotificationPermission() {
+  if (typeof window > "u" || !("Notification" in window))
+    return "denied";
+  return Notification.requestPermission();
+}
+export const notifications = {
+  success: (message, options) => notify("Success", { body: message, icon: "\u2705", ...options }),
+  error: (message, options) => notify("Error", { body: message, icon: "\u274C", ...options }),
+  warning: (message, options) => notify("Warning", { body: message, icon: "\u26A0\uFE0F", ...options }),
+  info: (message, options) => notify("Info", { body: message, icon: "\u2139\uFE0F", ...options })
+};

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

@@ -0,0 +1,119 @@
+/**
+ * Query a single permission
+ */
+export declare function usePermission(name: PermissionName): PermissionRef;
+/**
+ * Query multiple permissions at once
+ */
+export declare function usePermissions(names: PermissionName[]): MultiPermissionRef;
+/**
+ * Check if a permission is granted
+ */
+export declare function isPermissionGranted(name: PermissionName): Promise<boolean>;
+/**
+ * Check if camera permission is granted
+ */
+export declare function hasCameraPermission(): Promise<boolean>;
+/**
+ * Check if microphone permission is granted
+ */
+export declare function hasMicrophonePermission(): Promise<boolean>;
+/**
+ * Check if geolocation permission is granted
+ */
+export declare function hasGeolocationPermission(): Promise<boolean>;
+/**
+ * Check if notifications permission is granted
+ */
+export declare function hasNotificationPermission(): Promise<boolean>;
+/**
+ * Request camera and microphone permissions by accessing media
+ */
+export declare function requestMediaPermissions(options?: { video?: boolean; audio?: boolean }): Promise<{ granted: boolean; stream?: MediaStream; error?: Error }>;
+/**
+ * Common permission groups
+ * @defaultValue
+ * ```ts
+ * {
+ *   media: ['camera', 'microphone'] as PermissionName[],
+ *   location: ['geolocation'] as PermissionName[],
+ *   notifications: ['notifications', 'push'] as PermissionName[],
+ *   sensors: ['accelerometer', 'gyroscope', 'magnetometer'] as PermissionName[],
+ *   clipboard: ['clipboard-read', 'clipboard-write'] as PermissionName[]
+ * }
+ * ```
+ */
+export declare const permissionGroups: {
+  media: (string | unknown)[];
+  location: unknown[];
+  notifications: (string | unknown)[];
+  sensors: (string | unknown)[];
+  clipboard: (string | unknown)[]
+};
+export declare interface PermissionStatus {
+  state: PermissionState
+  isGranted: boolean
+  isDenied: boolean
+  isPrompt: boolean
+}
+export declare interface PermissionRef {
+  get: () => PermissionStatus
+  subscribe: (fn: (status: PermissionStatus) => void) => () => void
+  query: () => Promise<PermissionStatus>
+  isSupported: () => boolean
+}
+export declare interface MultiPermissionRef {
+  get: () => Record<string, PermissionStatus>
+  subscribe: (fn: (states: Record<string, PermissionStatus>) => void) => () => void
+  queryAll: () => Promise<Record<string, PermissionStatus>>
+  isSupported: () => boolean
+}
+/**
+ * usePermissions - Permissions API wrapper
+ *
+ * Query and monitor browser permission states for various APIs.
+ *
+ * @example
+ * ```ts
+ * // Check camera permission
+ * const camera = usePermission('camera')
+ * camera.subscribe(state => {
+ *   console.log('Camera permission:', state.state) // 'granted', 'denied', 'prompt'
+ * })
+ *
+ * // Check multiple permissions
+ * const permissions = usePermissions(['camera', 'microphone', 'geolocation'])
+ * permissions.subscribe(states => {
+ *   console.log('Camera:', states.camera)
+ *   console.log('Microphone:', states.microphone)
+ * })
+ * ```
+ */
+export type PermissionName = | 'accelerometer'
+  | 'accessibility-events'
+  | 'ambient-light-sensor'
+  | 'background-fetch'
+  | 'background-sync'
+  | 'bluetooth'
+  | 'camera'
+  | 'clipboard-read'
+  | 'clipboard-write'
+  | 'device-info'
+  | 'display-capture'
+  | 'geolocation'
+  | 'gyroscope'
+  | 'magnetometer'
+  | 'microphone'
+  | 'midi'
+  | 'nfc'
+  | 'notifications'
+  | 'payment-handler'
+  | 'periodic-background-sync'
+  | 'persistent-storage'
+  | 'push'
+  | 'screen-wake-lock'
+  | 'speaker-selection'
+  | 'storage-access'
+  | 'window-management'
+  | 'xr-spatial-tracking';
+export type PermissionState = 'granted' | 'denied' | 'prompt';

package/dist/composables/use-permissions.js

@@ -0,0 +1,132 @@
+function createStatus(state) {
+  return {
+    state,
+    isGranted: state === "granted",
+    isDenied: state === "denied",
+    isPrompt: state === "prompt"
+  };
+}
+function isPermissionsSupported() {
+  return typeof navigator < "u" && "permissions" in navigator;
+}
+export function usePermission(name) {
+  const supported = isPermissionsSupported();
+  let status = createStatus("prompt"), listeners = [], permissionStatus = null, cleanup = null;
+  const notify = () => {
+    listeners.forEach((fn) => fn(status));
+  }, updateStatus = () => {
+    if (permissionStatus) {
+      status = createStatus(permissionStatus.state);
+      notify();
+    }
+  }, query = async () => {
+    if (!supported)
+      return createStatus("prompt");
+    try {
+      permissionStatus = await navigator.permissions.query({ name });
+      status = createStatus(permissionStatus.state);
+      permissionStatus.addEventListener("change", updateStatus);
+      cleanup = () => {
+        permissionStatus?.removeEventListener("change", updateStatus);
+      };
+      return status;
+    } catch {
+      return createStatus("prompt");
+    }
+  };
+  return {
+    get: () => status,
+    subscribe: (fn) => {
+      if (listeners.length === 0 && supported)
+        query();
+      listeners.push(fn);
+      fn(status);
+      return () => {
+        listeners = listeners.filter((l) => l !== fn);
+        if (listeners.length === 0 && cleanup) {
+          cleanup();
+          cleanup = null;
+        }
+      };
+    },
+    query,
+    isSupported: () => supported
+  };
+}
+export function usePermissions(names) {
+  const supported = isPermissionsSupported();
+  let states = {}, listeners = [];
+  const permissionRefs = {}, unsubscribers = [];
+  for (const name of names) {
+    states[name] = createStatus("prompt");
+    permissionRefs[name] = usePermission(name);
+  }
+  const notify = () => {
+    listeners.forEach((fn) => fn(states));
+  };
+  return {
+    get: () => states,
+    subscribe: (fn) => {
+      if (listeners.length === 0)
+        for (const name of names) {
+          const unsub = permissionRefs[name].subscribe((status) => {
+            states[name] = status;
+            notify();
+          });
+          unsubscribers.push(unsub);
+        }
+      listeners.push(fn);
+      fn(states);
+      return () => {
+        listeners = listeners.filter((l) => l !== fn);
+        if (listeners.length === 0) {
+          unsubscribers.forEach((unsub) => unsub());
+          unsubscribers.length = 0;
+        }
+      };
+    },
+    queryAll: async () => {
+      const results = await Promise.all(names.map(async (name) => {
+        const result = await permissionRefs[name].query();
+        return [name, result];
+      }));
+      states = Object.fromEntries(results);
+      return states;
+    },
+    isSupported: () => supported
+  };
+}
+export async function isPermissionGranted(name) {
+  return (await usePermission(name).query()).isGranted;
+}
+export async function hasCameraPermission() {
+  return isPermissionGranted("camera");
+}
+export async function hasMicrophonePermission() {
+  return isPermissionGranted("microphone");
+}
+export async function hasGeolocationPermission() {
+  return isPermissionGranted("geolocation");
+}
+export async function hasNotificationPermission() {
+  return isPermissionGranted("notifications");
+}
+export async function requestMediaPermissions(options = { video: !0, audio: !0 }) {
+  if (typeof navigator > "u" || !navigator.mediaDevices)
+    return { granted: !1, error: Error("MediaDevices API not supported") };
+  try {
+    return { granted: !0, stream: await navigator.mediaDevices.getUserMedia(options) };
+  } catch (err) {
+    return {
+      granted: !1,
+      error: err instanceof Error ? err : Error(String(err))
+    };
+  }
+}
+export const permissionGroups = {
+  media: ["camera", "microphone"],
+  location: ["geolocation"],
+  notifications: ["notifications", "push"],
+  sensors: ["accelerometer", "gyroscope", "magnetometer"],
+  clipboard: ["clipboard-read", "clipboard-write"]
+};

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

@@ -0,0 +1,48 @@
+/**
+ * useQuery / useMutation - Data fetching composable types for STX
+ *
+ * Runtime implementations live in signals.ts. These are TypeScript interfaces
+ * and server-safe stubs.
+ */
+export declare interface UseQueryOptions<T = unknown> {
+  initialData?: T
+  staleTime?: number
+  cacheTime?: number
+  cacheKey?: string
+  headers?: Record<string, string>
+  transform?: (data: unknown) => T
+  refetchOnFocus?: boolean
+  refetchInterval?: number
+  immediate?: boolean
+  onSuccess?: (data: T) => void
+  onError?: (error: Error) => void
+}
+/** How one run of a request should behave. */
+export declare interface QueryRefetchOptions {
+  background?: boolean
+}
+export declare interface UseQueryResult<T = unknown> {
+  data: { (): T | null, set: (v: T | null) => void }
+  loading: { (): boolean, set: (v: boolean) => void }
+  isFetching: { (): boolean, set: (v: boolean) => void }
+  error: { (): string | null, set: (v: string | null) => void }
+  isStale: { (): boolean, set: (v: boolean) => void }
+  refetch: (options?: QueryRefetchOptions) => Promise<void>
+  invalidate: (options?: QueryRefetchOptions) => Promise<void>
+}
+export declare interface UseMutationOptions<T = unknown> {
+  method?: 'POST' | 'PUT' | 'PATCH' | 'DELETE'
+  headers?: Record<string, string>
+  transform?: (data: unknown) => T
+  optimisticData?: T | ((body: unknown) => T)
+  invalidateQueries?: string[]
+  onSuccess?: (data: T) => void
+  onError?: (error: Error) => void
+}
+export declare interface UseMutationResult<T = unknown> {
+  data: { (): T | null, set: (v: T | null) => void }
+  loading: { (): boolean, set: (v: boolean) => void }
+  error: { (): string | null, set: (v: string | null) => void }
+  mutate: (body?: unknown) => Promise<T>
+  reset: () => void
+}

package/dist/composables/use-resize-observer.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Observe element size changes
+ */
+export declare function useResizeObserver(target: Element | (() => Element | null) | null, callback?: (entries: ResizeObserverEntry[]) => void, options?: ResizeObserverOptions): ResizeObserverRef;
+/**
+ * Observe multiple elements
+ */
+export declare function useResizeObserverMultiple(targets: Element[] | (() => Element[]), callback?: (entries: ResizeObserverEntry[]) => void, options?: ResizeObserverOptions): ResizeObserverRef & { states: () => Map<Element, ResizeObserverState> };
+/**
+ * Get element dimensions reactively
+ */
+export declare function useElementSize(target: Element | (() => Element | null) | null): {
+  get: () => { width: number; height: number }
+  subscribe: (fn: (size: { width: number; height: number }) => void) => () => void
+  isSupported: () => boolean
+};
+/**
+ * Check if ResizeObserver is supported (standalone function)
+ */
+export declare function hasResizeObserver(): boolean;
+/**
+ * useResizeObserver - Resize Observer API wrapper
+ *
+ * Monitor element size changes reactively.
+ *
+ * @example
+ * ```ts
+ * const observer = useResizeObserver(element)
+ * observer.subscribe(entries => {
+ *   console.log('Size changed:', entries[0].contentRect)
+ * })
+ *
+ * // With callback
+ * useResizeObserver(element, (entries) => {
+ *   console.log('Width:', entries[0].contentRect.width)
+ * })
+ * ```
+ */
+export declare interface ResizeObserverSize {
+  width: number
+  height: number
+  inlineSize: number
+  blockSize: number
+}
+export declare interface ResizeObserverState {
+  contentRect: DOMRectReadOnly | null
+  contentBoxSize: ResizeObserverSize | null
+  borderBoxSize: ResizeObserverSize | null
+  devicePixelContentBoxSize: ResizeObserverSize | null
+}
+export declare interface ResizeObserverOptions {
+  box?: 'content-box' | 'border-box' | 'device-pixel-content-box'
+}
+export declare interface ResizeObserverRef {
+  get: () => ResizeObserverState
+  subscribe: (fn: (entries: ResizeObserverEntry[]) => void) => () => void
+  observe: () => void
+  disconnect: () => void
+  isSupported: () => boolean
+}