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

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

@@ -0,0 +1,90 @@
+/**
+ * Check if EventSource is supported
+ */
+export declare function isEventSourceSupported(): boolean;
+/**
+ * Create a reactive Server-Sent Events connection
+ *
+ * @example
+ * ```ts
+ * const sse = useEventSource('/api/events', {
+ *   events: ['notification', 'update'],
+ *   onMessage: (event) => console.log('Message:', event.data),
+ * })
+ *
+ * // Subscribe to state changes
+ * sse.subscribe((state) => {
+ *   console.log('Status:', state.status)
+ *   console.log('Last data:', state.data)
+ * })
+ *
+ * // Listen to specific events
+ * sse.on('notification', (event) => {
+ *   console.log('Notification:', event.data)
+ * })
+ *
+ * // Close connection
+ * sse.close()
+ * ```
+ */
+export declare function useEventSource<T = unknown>(url: string | URL, options?: EventSourceOptions): EventSourceRef<T>;
+/**
+ * Simple SSE connection for receiving JSON data
+ *
+ * @example
+ * ```ts
+ * const { data, status, close } = useSSE<{ count: number }>('/api/counter')
+ *
+ * data.subscribe((value) => {
+ *   console.log('Count:', value?.count)
+ * })
+ * ```
+ */
+export declare function useSSE<T = unknown>(url: string): SSERef<T>;
+export declare interface EventSourceState<T = unknown> {
+  status: EventSourceStatus
+  data: T | null
+  event: string | null
+  lastEventId: string | null
+  error: Event | null
+}
+export declare interface EventSourceOptions {
+  withCredentials?: boolean
+  autoReconnect?: boolean | {
+    retries?: number
+    delay?: number
+    onFailed?: () => void
+  }
+  immediate?: boolean
+  events?: string[]
+  onOpen?: (event: Event) => void
+  onMessage?: (event: MessageEvent) => void
+  onError?: (event: Event) => void
+}
+/** Handle returned by {@link useSSE}. */
+export declare interface SSERef<T = unknown> {
+  data: {
+    get: () => T | null
+    subscribe: (fn: (data: T | null) => void) => () => void
+  }
+  status: {
+    get: () => EventSourceStatus
+    subscribe: (fn: (status: EventSourceStatus) => void) => () => void
+  }
+  close: () => void
+  open: () => void
+}
+export declare interface EventSourceRef<T = unknown> {
+  get: () => EventSourceState<T>
+  subscribe: (fn: (state: EventSourceState<T>) => void) => () => void
+  open: () => void
+  close: () => void
+  eventSource: () => EventSource | null
+  on: (eventName: string, callback: (event: MessageEvent) => void) => () => void
+}
+/**
+ * Event Source (SSE) Composables
+ *
+ * Reactive utilities for Server-Sent Events.
+ */
+export type EventSourceStatus = 'connecting' | 'open' | 'closed' | 'error';

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

@@ -0,0 +1,166 @@
+export function isEventSourceSupported() {
+  return typeof window < "u" && "EventSource" in window;
+}
+export function useEventSource(url, options = {}) {
+  const {
+    withCredentials = !1,
+    autoReconnect = !0,
+    immediate = !0,
+    events = [],
+    onOpen,
+    onMessage,
+    onError
+  } = options, subscribers = new Set, eventListeners = new Map;
+  let state = {
+    status: "closed",
+    data: null,
+    event: null,
+    lastEventId: null,
+    error: null
+  }, eventSource = null, retryCount = 0, explicitlyClosed = !1;
+  function notify() {
+    subscribers.forEach((fn) => fn(state));
+  }
+  function emitEvent(eventName, event) {
+    const listeners = eventListeners.get(eventName);
+    if (listeners)
+      listeners.forEach((fn) => fn(event));
+  }
+  function getReconnectConfig() {
+    if (typeof autoReconnect === "object")
+      return {
+        retries: autoReconnect.retries ?? 3,
+        delay: autoReconnect.delay ?? 1000,
+        onFailed: autoReconnect.onFailed
+      };
+    return { retries: 3, delay: 1000, onFailed: void 0 };
+  }
+  function connect() {
+    if (!isEventSourceSupported())
+      return;
+    explicitlyClosed = !1;
+    state = { ...state, status: "connecting" };
+    notify();
+    try {
+      eventSource = new EventSource(url.toString(), { withCredentials });
+      eventSource.onopen = (event) => {
+        state = { ...state, status: "open" };
+        retryCount = 0;
+        notify();
+        onOpen?.(event);
+      };
+      eventSource.onmessage = (event) => {
+        let parsedData;
+        try {
+          parsedData = JSON.parse(event.data);
+        } catch {
+          parsedData = event.data;
+        }
+        state = {
+          ...state,
+          data: parsedData,
+          event: "message",
+          lastEventId: event.lastEventId || null
+        };
+        notify();
+        emitEvent("message", event);
+        onMessage?.(event);
+      };
+      eventSource.onerror = (event) => {
+        state = { ...state, status: "error", error: event };
+        notify();
+        onError?.(event);
+        if (eventSource?.readyState === EventSource.CLOSED) {
+          state = { ...state, status: "closed" };
+          notify();
+          if (autoReconnect && !explicitlyClosed) {
+            const config = getReconnectConfig();
+            if (retryCount < config.retries) {
+              retryCount++;
+              setTimeout(connect, config.delay * retryCount);
+            } else
+              config.onFailed?.();
+          }
+        }
+      };
+      for (const eventName of events)
+        eventSource.addEventListener(eventName, (event) => {
+          const messageEvent = event;
+          let parsedData;
+          try {
+            parsedData = JSON.parse(messageEvent.data);
+          } catch {
+            parsedData = messageEvent.data;
+          }
+          state = {
+            ...state,
+            data: parsedData,
+            event: eventName,
+            lastEventId: messageEvent.lastEventId || null
+          };
+          notify();
+          emitEvent(eventName, messageEvent);
+        });
+    } catch (error) {
+      state = { ...state, status: "error", error };
+      notify();
+    }
+  }
+  function close() {
+    explicitlyClosed = !0;
+    if (eventSource) {
+      eventSource.close();
+      eventSource = null;
+      state = { ...state, status: "closed" };
+      notify();
+    }
+  }
+  function on(eventName, callback) {
+    if (!eventListeners.has(eventName)) {
+      eventListeners.set(eventName, new Set);
+      if (eventSource && !events.includes(eventName))
+        eventSource.addEventListener(eventName, (event) => {
+          emitEvent(eventName, event);
+        });
+    }
+    eventListeners.get(eventName).add(callback);
+    return () => {
+      eventListeners.get(eventName)?.delete(callback);
+    };
+  }
+  if (immediate)
+    connect();
+  return {
+    get: () => state,
+    subscribe: (fn) => {
+      subscribers.add(fn);
+      fn(state);
+      return () => {
+        subscribers.delete(fn);
+      };
+    },
+    open: connect,
+    close,
+    eventSource: () => eventSource,
+    on
+  };
+}
+export function useSSE(url) {
+  const sse = useEventSource(url);
+  return {
+    data: {
+      get: () => sse.get().data,
+      subscribe: (fn) => {
+        return sse.subscribe((state) => fn(state.data));
+      }
+    },
+    status: {
+      get: () => sse.get().status,
+      subscribe: (fn) => {
+        return sse.subscribe((state) => fn(state.status));
+      }
+    },
+    close: sse.close,
+    open: sse.open
+  };
+}

package/dist/composables/use-eye-dropper.d.ts

@@ -0,0 +1,117 @@
+/**
+ * Check if EyeDropper API is supported
+ */
+export declare function isEyeDropperSupported(): boolean;
+/**
+ * Create a reactive eye dropper color picker
+ *
+ * The EyeDropper API allows users to pick colors from anywhere on their
+ * screen, not just within the browser window. Great for design tools,
+ * color pickers, and accessibility features.
+ *
+ * @example
+ * ```ts
+ * const eyeDropper = useEyeDropper({
+ *   onPick: (color) => {
+ *     console.log('Picked color:', color) // e.g., "#ff6188"
+ *   }
+ * })
+ *
+ * // Subscribe to state changes
+ * eyeDropper.subscribe((state) => {
+ *   if (state.sRGBHex) {
+ *     document.body.style.backgroundColor = state.sRGBHex
+ *   }
+ * })
+ *
+ * // Open the color picker
+ * const color = await eyeDropper.open()
+ * ```
+ */
+export declare function useEyeDropper(options?: EyeDropperOptions): EyeDropperRef;
+/**
+ * Simple color picker that returns the color
+ *
+ * @example
+ * ```ts
+ * const color = await pickColor()
+ * if (color) {
+ *   console.log('Picked:', color)
+ * }
+ * ```
+ */
+export declare function pickColor(): Promise<string | null>;
+/**
+ * Convert hex color to RGB values
+ */
+export declare function hexToRgb(hex: string): { r: number, g: number, b: number } | null;
+/**
+ * Convert hex color to HSL values
+ */
+export declare function hexToHsl(hex: string): { h: number, s: number, l: number } | null;
+/**
+ * Pick a color with history tracking
+ *
+ * @example
+ * ```ts
+ * const colorPicker = useColorHistory({
+ *   maxHistory: 10
+ * })
+ *
+ * await colorPicker.pick()
+ *
+ * colorPicker.subscribe((state) => {
+ *   console.log('History:', state.history)
+ *   console.log('Current:', state.current)
+ * })
+ * ```
+ */
+export declare function useColorHistory(options?: {
+  maxHistory?: number
+  onPick?: (color: string) => void
+}): ColorHistoryRef;
+/**
+ * EyeDropper Composables
+ *
+ * Reactive utilities for the EyeDropper API to pick colors from the screen.
+ */
+export declare interface EyeDropperState {
+  isSupported: boolean
+  isOpen: boolean
+  sRGBHex: string | null
+  error: Error | null
+}
+export declare interface EyeDropperResult {
+  sRGBHex: string
+}
+export declare interface EyeDropperOptions {
+  onPick?: (color: string) => void
+  onAbort?: () => void
+  onError?: (error: Error) => void
+}
+/** Handle returned by {@link useColorHistory}. */
+export declare interface ColorHistoryRef {
+  get: () => { current: string | null, history: string[] }
+  subscribe: (fn: (state: { current: string | null, history: string[] }) => void) => () => void
+  pick: () => Promise<string | null>
+  clearHistory: () => void
+  removeFromHistory: (color: string) => void
+  isSupported: () => boolean
+}
+export declare interface EyeDropperRef {
+  get: () => EyeDropperState
+  subscribe: (fn: (state: EyeDropperState) => void) => () => void
+  open: () => Promise<string | null>
+  isSupported: () => boolean
+}
+// Extend Window for EyeDropper
+declare interface EyeDropperConstructor {
+  new (): {
+    open: (options?: { signal?: AbortSignal }) => Promise<EyeDropperResult>
+  }
+}
+declare global {
+  interface Window {
+  EyeDropper?: EyeDropperConstructor
+}
+}

package/dist/composables/use-eye-dropper.js

@@ -0,0 +1,142 @@
+export function isEyeDropperSupported() {
+  return typeof window < "u" && "EyeDropper" in window;
+}
+export function useEyeDropper(options = {}) {
+  const { onPick, onAbort, onError } = options, supported = isEyeDropperSupported(), subscribers = new Set;
+  let state = {
+    isSupported: supported,
+    isOpen: !1,
+    sRGBHex: null,
+    error: null
+  }, abortController = null;
+  function notify() {
+    subscribers.forEach((fn) => fn(state));
+  }
+  async function open() {
+    if (!supported || !window.EyeDropper) {
+      const error = Error("EyeDropper API not supported");
+      state = { ...state, error };
+      notify();
+      onError?.(error);
+      return null;
+    }
+    abortController?.abort();
+    abortController = new AbortController;
+    state = { ...state, isOpen: !0, error: null };
+    notify();
+    try {
+      const result = await new window.EyeDropper().open({ signal: abortController.signal });
+      state = { ...state, isOpen: !1, sRGBHex: result.sRGBHex };
+      notify();
+      onPick?.(result.sRGBHex);
+      return result.sRGBHex;
+    } catch (error) {
+      state = { ...state, isOpen: !1 };
+      if (error.name === "AbortError") {
+        onAbort?.();
+        notify();
+        return null;
+      }
+      state = { ...state, error };
+      notify();
+      onError?.(error);
+      return null;
+    }
+  }
+  return {
+    get: () => state,
+    subscribe: (fn) => {
+      subscribers.add(fn);
+      fn(state);
+      return () => {
+        subscribers.delete(fn);
+        if (subscribers.size === 0)
+          abortController?.abort();
+      };
+    },
+    open,
+    isSupported: () => supported
+  };
+}
+export async function pickColor() {
+  if (!isEyeDropperSupported() || !window.EyeDropper)
+    return null;
+  try {
+    return (await new window.EyeDropper().open()).sRGBHex;
+  } catch {
+    return null;
+  }
+}
+export function hexToRgb(hex) {
+  const result = /^#?([a-f\d]{2})([a-f\d]{2})([a-f\d]{2})$/i.exec(hex);
+  return result ? {
+    r: Number.parseInt(result[1], 16),
+    g: Number.parseInt(result[2], 16),
+    b: Number.parseInt(result[3], 16)
+  } : null;
+}
+export function hexToHsl(hex) {
+  const rgb = hexToRgb(hex);
+  if (!rgb)
+    return null;
+  const r = rgb.r / 255, g = rgb.g / 255, b = rgb.b / 255, max = Math.max(r, g, b), min = Math.min(r, g, b), l = (max + min) / 2;
+  if (max === min)
+    return { h: 0, s: 0, l: Math.round(l * 100) };
+  const d = max - min, s = l > 0.5 ? d / (2 - max - min) : d / (max + min);
+  let h = 0;
+  switch (max) {
+    case r:
+      h = ((g - b) / d + (g < b ? 6 : 0)) / 6;
+      break;
+    case g:
+      h = ((b - r) / d + 2) / 6;
+      break;
+    case b:
+      h = ((r - g) / d + 4) / 6;
+      break;
+  }
+  return {
+    h: Math.round(h * 360),
+    s: Math.round(s * 100),
+    l: Math.round(l * 100)
+  };
+}
+export function useColorHistory(options = {}) {
+  const { maxHistory = 20, onPick } = options, eyeDropper = useEyeDropper({ onPick }), subscribers = new Set;
+  let history = [];
+  function notify() {
+    const state = { current: eyeDropper.get().sRGBHex, history };
+    subscribers.forEach((fn) => fn(state));
+  }
+  eyeDropper.subscribe((state) => {
+    if (state.sRGBHex && !history.includes(state.sRGBHex)) {
+      history = [state.sRGBHex, ...history].slice(0, maxHistory);
+      notify();
+    }
+  });
+  async function pick() {
+    return eyeDropper.open();
+  }
+  function clearHistory() {
+    history = [];
+    notify();
+  }
+  function removeFromHistory(color) {
+    history = history.filter((c) => c !== color);
+    notify();
+  }
+  return {
+    get: () => ({ current: eyeDropper.get().sRGBHex, history }),
+    subscribe: (fn) => {
+      subscribers.add(fn);
+      fn({ current: eyeDropper.get().sRGBHex, history });
+      return () => {
+        subscribers.delete(fn);
+      };
+    },
+    pick,
+    clearHistory,
+    removeFromHistory,
+    isSupported: eyeDropper.isSupported
+  };
+}

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

@@ -0,0 +1,59 @@
+import { state } from '../signals-api';
+import type { Signal } from '../signals-api';
+/**
+ * Reactive fetch with loading/error states. Returns Signal-shaped state.
+ */
+export declare function useFetch<T = unknown>(url: string | (() => string), options?: FetchOptions<T>): FetchRef<T>;
+/**
+ * Generic async data fetcher. Same Signal shape as `useFetch`.
+ */
+export declare function useAsyncData<T>(fetcher: () => Promise<T>, options?: {
+    immediate?: boolean
+    transform?: (data: T) => T
+    initialData?: T | null
+    key?: string
+    cacheTime?: number
+  }): FetchRef<T>;
+/**
+ * POST request helper. Returns the fetch state plus an execute(body) helper.
+ */
+export declare function usePost<T = unknown, B = unknown>(url: string, options?: Omit<FetchOptions<T>, 'method' | 'body'>): {
+    execute: (body?: B) => Promise<T | null>
+    state: FetchRef<T>
+  };
+/** Clear fetch cache (one key or all). */
+export declare function clearFetchCache(key?: string): void;
+/** Prefetch data into cache. */
+export declare function prefetch<T>(url: string, options?: FetchOptions<T>): Promise<void>;
+export declare interface FetchOptions<T = unknown> extends Omit<RequestInit, 'body'> {
+  body?: BodyInit | Record<string, unknown> | null
+  baseURL?: string
+  query?: Record<string, string | number | boolean | undefined>
+  immediate?: boolean
+  transform?: (data: unknown) => T
+  parseResponse?: (response: Response) => Promise<unknown>
+  timeout?: number
+  retry?: number
+  retryDelay?: number
+  key?: string
+  cacheTime?: number
+  refetchOnFocus?: boolean
+  refetchInterval?: number
+  initialData?: T | null
+}
+/** How one run of the request should behave. */
+export declare interface RefetchOptions {
+  background?: boolean
+}
+/** Signal-shaped fetch result. Matches the runtime's `useFetch` return. */
+export declare interface FetchRef<T> {
+  data: Signal<T | null>
+  loading: Signal<boolean>
+  isFetching: Signal<boolean>
+  error: Signal<Error | null>
+  status: Signal<number | null>
+  statusText: Signal<string | null>
+  refetch: (_options?: RefetchOptions) => Promise<void>
+  execute: () => Promise<void>
+  abort: () => void
+}