sibujs 1.2.0 → 1.4.0

package/dist/browser.d.cts

@@ -195,4 +195,594 @@ declare function formatCurrency(value: number, currency: string, options?: Intl.
     locale?: string;
 }): string;
 
-export { battery, clipboard, colorScheme, draggable, dropZone, formatCurrency, formatNumber, geo, idle, media, online, permissions, resize, scroll, title };
+/**
+ * visibility tracks the document's Page Visibility state.
+ * Returns a reactive boolean that is `true` while the tab is visible.
+ *
+ * Useful for pausing animations, polling, or video playback while the tab
+ * is hidden — a common optimization to save CPU and battery.
+ *
+ * @returns Object with reactive `visible` getter and `dispose` function
+ *
+ * @example
+ * ```ts
+ * const { visible, dispose } = visibility();
+ * effect(() => {
+ *   if (visible()) resumePolling();
+ *   else pausePolling();
+ * });
+ * ```
+ */
+declare function visibility(): {
+    visible: () => boolean;
+    dispose: () => void;
+};
+
+type EffectiveType = "slow-2g" | "2g" | "3g" | "4g" | "unknown";
+/**
+ * network tracks the browser's Network Information API.
+ * Returns reactive getters for effective connection type, downlink bandwidth,
+ * round-trip time, and save-data preference.
+ *
+ * Useful for adapting content (image quality, prefetching, polling intervals)
+ * to the user's actual connection — not just online/offline state.
+ *
+ * Falls back to sensible defaults on browsers without the API (notably Safari).
+ *
+ * @returns Reactive network info with dispose function
+ *
+ * @example
+ * ```ts
+ * const { effectiveType, saveData } = network();
+ * const imageQuality = derived(() =>
+ *   saveData() || effectiveType() === "2g" ? "low" : "high"
+ * );
+ * ```
+ */
+declare function network(): {
+    effectiveType: () => EffectiveType;
+    downlink: () => number;
+    rtt: () => number;
+    saveData: () => boolean;
+    dispose: () => void;
+};
+
+interface MouseOptions {
+    /** Track touch events as well (unified pointer tracking). Default: true */
+    touch?: boolean;
+    /** Target element. Defaults to `window`. */
+    target?: HTMLElement;
+}
+/**
+ * mouse tracks the pointer position (mouse + optional touch) as reactive signals.
+ * Returns `x`, `y` getters updated on every `pointermove` / `touchmove`.
+ *
+ * @param options Optional tracking configuration
+ * @returns Reactive mouse coordinates with dispose function
+ *
+ * @example
+ * ```ts
+ * const { x, y, dispose } = mouse();
+ * effect(() => console.log(`${x()}, ${y()}`));
+ * ```
+ */
+declare function mouse(options?: MouseOptions): {
+    x: () => number;
+    y: () => number;
+    dispose: () => void;
+};
+
+type SwipeDirection = "left" | "right" | "up" | "down";
+interface SwipeOptions {
+    /** Minimum distance in pixels for a swipe to count. Default: 50 */
+    threshold?: number;
+    /** Fired when a swipe is detected. */
+    onSwipe?: (direction: SwipeDirection, distance: number) => void;
+}
+/**
+ * swipe detects touch swipe gestures on a target element.
+ * Returns a reactive signal of the last-detected direction plus dispose.
+ *
+ * Works on touch devices (touchstart/touchend). Uses only native events —
+ * no external library.
+ *
+ * @param target Element to attach listeners to
+ * @param options Threshold and onSwipe callback
+ * @returns Reactive direction getter and dispose
+ *
+ * @example
+ * ```ts
+ * const el = div({ class: "card" });
+ * swipe(el, {
+ *   threshold: 80,
+ *   onSwipe: (dir) => {
+ *     if (dir === "left") goNext();
+ *     if (dir === "right") goPrev();
+ *   },
+ * });
+ * ```
+ */
+declare function swipe(target: HTMLElement, options?: SwipeOptions): {
+    direction: () => SwipeDirection | null;
+    dispose: () => void;
+};
+
+/**
+ * windowSize tracks the viewport dimensions as reactive signals.
+ * Unlike `resize()` (which observes a specific element), this watches the
+ * full window via the `resize` event.
+ *
+ * Useful for responsive layouts, breakpoint logic, and canvas sizing.
+ *
+ * @returns Reactive `width`, `height` getters and dispose
+ *
+ * @example
+ * ```ts
+ * const { width, height } = windowSize();
+ * const isMobile = derived(() => width() < 768);
+ * ```
+ */
+declare function windowSize(): {
+    width: () => number;
+    height: () => number;
+    dispose: () => void;
+};
+
+/**
+ * urlState returns reactive getters for the current URL's search params and
+ * hash, plus setters that call `history.pushState` / `replaceState`.
+ *
+ * Works independently of `createRouter()` — useful for apps that only need
+ * to sync a handful of UI state bits with the URL (filters, tabs, modals)
+ * without a full router setup.
+ *
+ * Listens to `popstate` so browser back/forward updates the signals.
+ *
+ * @example
+ * ```ts
+ * const url = urlState();
+ * const search = derived(() => url.params().get("q") ?? "");
+ * input({
+ *   value: search,
+ *   on: { input: (e) => {
+ *     const p = new URLSearchParams(url.params());
+ *     p.set("q", (e.target as HTMLInputElement).value);
+ *     url.setParams(p, { replace: true });
+ *   }},
+ * });
+ * ```
+ */
+interface UrlStateOptions {
+    /** Use `replaceState` instead of `pushState`. Default: false */
+    replace?: boolean;
+}
+declare function urlState(): {
+    params: () => URLSearchParams;
+    hash: () => string;
+    setParams: (next: URLSearchParams | Record<string, string>, opts?: UrlStateOptions) => void;
+    setHash: (next: string, opts?: UrlStateOptions) => void;
+    dispose: () => void;
+};
+
+/**
+ * broadcast wraps the BroadcastChannel API as a reactive signal.
+ * Unlike the `storage` event (which only fires for localStorage writes and
+ * sends only the serialized value), a `BroadcastChannel` can send arbitrary
+ * structured-cloneable payloads between same-origin tabs, iframes, and
+ * workers — instantly, without touching storage.
+ *
+ * Returns the last received message as a reactive signal plus a `post()`
+ * sender and `dispose()` cleanup. The `post()` call does NOT echo back into
+ * the local `last()` signal — BroadcastChannel doesn't deliver to its own
+ * sender, matching the browser's native behavior.
+ *
+ * @param channelName Name of the broadcast channel
+ * @returns `{ last, post, dispose }`
+ *
+ * @example
+ * ```ts
+ * const chat = broadcast<{ user: string; text: string }>("chat");
+ * chat.post({ user: "alice", text: "hi" });
+ * effect(() => {
+ *   const m = chat.last();
+ *   if (m) renderIncoming(m);
+ * });
+ * ```
+ */
+declare function broadcast<T = unknown>(channelName: string): {
+    last: () => T | null;
+    post: (message: T) => void;
+    dispose: () => void;
+};
+
+/**
+ * fullscreen wraps the Fullscreen API as a reactive signal plus `enter`/
+ * `exit`/`toggle` actions. Tracks `document.fullscreenElement` via the
+ * `fullscreenchange` event so the signal stays in sync when the user presses
+ * Escape or the browser forces an exit.
+ *
+ * @returns `{ isFullscreen, element, enter, exit, toggle, dispose }`
+ *
+ * @example
+ * ```ts
+ * const fs = fullscreen();
+ * button({
+ *   nodes: () => (fs.isFullscreen() ? "Exit fullscreen" : "Enter fullscreen"),
+ *   on: { click: () => fs.toggle(videoEl) },
+ * });
+ * ```
+ */
+declare function fullscreen(): {
+    isFullscreen: () => boolean;
+    element: () => Element | null;
+    enter: (el: Element) => Promise<void>;
+    exit: () => Promise<void>;
+    toggle: (el: Element) => Promise<void>;
+    dispose: () => void;
+};
+
+/**
+ * wakeLock wraps the Screen Wake Lock API to keep the screen awake while the
+ * app is doing something the user is watching (video, timer, recipe, nav).
+ *
+ * Returns a reactive `active` boolean plus `request` / `release` actions.
+ * The lock is automatically re-requested if the page becomes visible again
+ * after being hidden (browsers auto-release wake locks on tab hide).
+ *
+ * Gracefully degrades on browsers without the API.
+ *
+ * @example
+ * ```ts
+ * const lock = wakeLock();
+ * await lock.request();
+ * // ... later
+ * await lock.release();
+ * ```
+ */
+declare function wakeLock(): {
+    active: () => boolean;
+    request: () => Promise<void>;
+    release: () => Promise<void>;
+    dispose: () => void;
+};
+
+interface AnimationFrameOptions {
+    /** Maximum FPS. Frames that would exceed this are skipped. Default: unlimited. */
+    fpsLimit?: number;
+    /** Start immediately. Default: true. */
+    immediate?: boolean;
+}
+/**
+ * animationFrame emits a reactive `delta` (ms since previous frame) and
+ * `elapsed` (ms since start) tracked via `requestAnimationFrame`. Useful for
+ * declarative animations, game loops, or real-time visual updates — without
+ * forcing callers to manage the rAF id manually.
+ *
+ * The loop is paused automatically when `pause()` is called and resumed with
+ * `resume()`. `dispose()` cancels the loop permanently.
+ *
+ * @example
+ * ```ts
+ * const frame = animationFrame();
+ * effect(() => {
+ *   const dt = frame.delta();
+ *   setAngle((a) => (a + dt * 0.1) % 360);
+ * });
+ * ```
+ */
+declare function animationFrame(options?: AnimationFrameOptions): {
+    delta: () => number;
+    elapsed: () => number;
+    running: () => boolean;
+    pause: () => void;
+    resume: () => void;
+    dispose: () => void;
+};
+
+interface MutationObserverOptions extends MutationObserverInit {
+}
+/**
+ * mutationObserver wraps the DOM MutationObserver as a reactive signal of
+ * the latest batch of mutations. Typical uses: reacting to externally
+ * injected content (third-party embeds), watching attribute flips the app
+ * doesn't directly control, or migrating legacy non-reactive code.
+ *
+ * For anything inside a single component prefer reactive DOM bindings —
+ * this is an escape hatch for cross-boundary observation.
+ *
+ * @param target Element to observe
+ * @param options Standard MutationObserverInit (childList, subtree, …)
+ *
+ * @example
+ * ```ts
+ * const obs = mutationObserver(document.body, { childList: true, subtree: true });
+ * effect(() => {
+ *   const records = obs.records();
+ *   if (records.length) handleExternalChanges(records);
+ * });
+ * ```
+ */
+declare function mutationObserver(target: Node, options?: MutationObserverOptions): {
+    records: () => MutationRecord[];
+    dispose: () => void;
+};
+
+interface BoundsRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    top: number;
+    left: number;
+    right: number;
+    bottom: number;
+}
+/**
+ * bounds tracks an element's `getBoundingClientRect()` as a reactive signal.
+ * Updates when the element resizes OR when the window scrolls (so absolute
+ * top/left stay accurate for overlays, tooltips, and popovers).
+ *
+ * Implementation detail: uses a `ResizeObserver` for size changes and a
+ * passive window `scroll` listener for position changes. Both are torn down
+ * on `dispose()`.
+ *
+ * @example
+ * ```ts
+ * const el = div({ class: "anchor" });
+ * const rect = bounds(el);
+ * effect(() => {
+ *   const r = rect.rect();
+ *   positionTooltip(r.left, r.bottom);
+ * });
+ * ```
+ */
+declare function bounds(target: Element): {
+    rect: () => BoundsRect;
+    refresh: () => void;
+    dispose: () => void;
+};
+
+interface KeyboardOptions {
+    /** Target element. Defaults to `window`. */
+    target?: HTMLElement;
+    /** Filter: only track these keys (matches `KeyboardEvent.key`). */
+    keys?: string[];
+}
+/**
+ * keyboard tracks the set of keys currently held down as a reactive signal.
+ * Useful for combo detection, editor-like keybindings, games, and modifier
+ * gating ("Shift+click").
+ *
+ * The returned `pressed` is a reactive `Set<string>` (keyed by
+ * `KeyboardEvent.key`). On every key event the signal is replaced with a
+ * new Set instance so reactive subscribers see the change.
+ *
+ * Also listens to `window.blur` to clear stuck keys if the window loses
+ * focus mid-press — otherwise held modifiers can "ghost" forever.
+ *
+ * @example
+ * ```ts
+ * const kb = keyboard();
+ * const isShift = derived(() => kb.pressed().has("Shift"));
+ * ```
+ */
+declare function keyboard(options?: KeyboardOptions): {
+    pressed: () => Set<string>;
+    isPressed: (key: string) => boolean;
+    dispose: () => void;
+};
+
+interface SpeakOptions {
+    /** BCP-47 language tag. Defaults to the utterance's default. */
+    lang?: string;
+    /** Playback speed (0.1–10). Default: 1. */
+    rate?: number;
+    /** Pitch (0–2). Default: 1. */
+    pitch?: number;
+    /** Volume (0–1). Default: 1. */
+    volume?: number;
+    /** Voice name (match against `getVoices()[i].name`). */
+    voice?: string;
+}
+/**
+ * speech wraps the Web Speech Synthesis API as a reactive controller.
+ * Exposes `speaking` / `paused` reactive booleans plus `speak()`, `pause()`,
+ * `resume()`, `cancel()` actions.
+ *
+ * Automatically gracefully degrades on runtimes without `speechSynthesis`.
+ *
+ * @example
+ * ```ts
+ * const tts = speech();
+ * button({
+ *   nodes: "Read it to me",
+ *   on: { click: () => tts.speak("Hello, world!", { rate: 1.1 }) },
+ * });
+ * ```
+ */
+declare function speech(): {
+    speaking: () => boolean;
+    paused: () => boolean;
+    speak: (text: string, options?: SpeakOptions) => void;
+    pause: () => void;
+    resume: () => void;
+    cancel: () => void;
+    dispose: () => void;
+};
+
+interface GamepadSnapshot {
+    index: number;
+    id: string;
+    connected: boolean;
+    buttons: readonly {
+        pressed: boolean;
+        value: number;
+    }[];
+    axes: readonly number[];
+}
+/**
+ * gamepad exposes the Gamepad API as reactive snapshots. Unlike the
+ * native API (which requires polling each frame), this wrapper polls for
+ * you via `requestAnimationFrame` and emits a signal update whenever ANY
+ * button or axis changes.
+ *
+ * Returns `pads()` — a reactive array of currently-connected gamepads — and
+ * `dispose()` to stop polling. Listens to `gamepadconnected` and
+ * `gamepaddisconnected` to auto-start/stop the poll loop.
+ *
+ * @example
+ * ```ts
+ * const gp = gamepad();
+ * effect(() => {
+ *   const pad = gp.pads()[0];
+ *   if (pad?.buttons[0]?.pressed) jump();
+ *   setAngle((pad?.axes[0] ?? 0) * 90);
+ * });
+ * ```
+ */
+declare function gamepad(): {
+    pads: () => GamepadSnapshot[];
+    dispose: () => void;
+};
+
+/**
+ * pointerLock wraps the Pointer Lock API as a reactive controller.
+ * Exposes a `locked` signal plus `request(el)` / `exit()` actions.
+ *
+ * Pointer lock hides the cursor and delivers unbounded relative-motion
+ * mouse events — essential for FPS games, 3D viewers, sketching apps.
+ *
+ * @example
+ * ```ts
+ * const pl = pointerLock();
+ * canvas.addEventListener("click", () => pl.request(canvas));
+ * window.addEventListener("mousemove", (e) => {
+ *   if (pl.locked()) turnCamera(e.movementX, e.movementY);
+ * });
+ * ```
+ */
+declare function pointerLock(): {
+    locked: () => boolean;
+    request: (element: Element) => void;
+    exit: () => void;
+    dispose: () => void;
+};
+
+/**
+ * vibrate triggers the Vibration API. Accepts a single duration in ms or
+ * a pattern array alternating vibration and pause durations. Returns `true`
+ * if the call was dispatched, `false` if the API is unsupported.
+ *
+ * Wrapped for consistency with the rest of `sibujs/browser` and to avoid
+ * runtime errors on non-mobile browsers.
+ *
+ * @example
+ * ```ts
+ * vibrate(50);           // single 50ms tap
+ * vibrate([100, 30, 100]); // pulse-pause-pulse
+ * vibrate(0);            // cancel any active vibration
+ * ```
+ */
+declare function vibrate(pattern: number | number[]): boolean;
+
+/**
+ * favicon sets or updates the page favicon at runtime.
+ *
+ * Passes a `url` (to set `href`) or accepts an inline SVG string via
+ * `data:image/svg+xml` encoding. Useful for notification badges, theme
+ * switching, dynamic status indicators.
+ *
+ * Ensures a `<link rel="icon">` exists — creates one if missing, updates
+ * the `href` otherwise.
+ *
+ * @param url Favicon URL or `data:` URI
+ *
+ * @example
+ * ```ts
+ * favicon("/icons/default.png");
+ * // Unread count badge on the favicon
+ * effect(() => {
+ *   const n = unreadCount();
+ *   favicon(n > 0 ? "/icons/badge.png" : "/icons/default.png");
+ * });
+ * ```
+ */
+declare function favicon(url: string): void;
+/**
+ * Encode an SVG string into a `data:image/svg+xml` URI suitable for use
+ * with `favicon()`. Handles URL encoding of special characters so inline
+ * SVG content can be embedded safely.
+ *
+ * @example
+ * ```ts
+ * favicon(svgFavicon(`<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 10 10"><circle cx="5" cy="5" r="5" fill="red"/></svg>`));
+ * ```
+ */
+declare function svgFavicon(svg: string): string;
+
+interface TextSelectionState {
+    /** Selected text, or empty string. */
+    text: () => string;
+    /** DOMRect of the selection (for positioning floating action bars) or null. */
+    rect: () => DOMRect | null;
+    /** True when there is a non-empty selection. */
+    hasSelection: () => boolean;
+    /** Programmatically clear the current selection. */
+    clear: () => void;
+    dispose: () => void;
+}
+/**
+ * textSelection tracks the user's current text selection as reactive state.
+ * Great for "selection toolbars" (bold/italic popovers), citation tools,
+ * and any UI that needs to show contextual actions when the user highlights
+ * text on the page.
+ *
+ * Listens to `selectionchange` on the document, which fires for mouse drag,
+ * keyboard selection (Shift+arrow), and touch selection all the same.
+ *
+ * @example
+ * ```ts
+ * const sel = textSelection();
+ * effect(() => {
+ *   const rect = sel.rect();
+ *   if (rect) positionToolbar(rect);
+ *   else hideToolbar();
+ * });
+ * ```
+ */
+declare function textSelection(): TextSelectionState;
+
+interface ImageLoaderState {
+    /** Reactive loading state: "pending" | "loaded" | "error". */
+    status: () => "pending" | "loaded" | "error";
+    /** The loaded HTMLImageElement (null until `status === "loaded"`). */
+    image: () => HTMLImageElement | null;
+    /** Intrinsic width, 0 until loaded. */
+    width: () => number;
+    /** Intrinsic height, 0 until loaded. */
+    height: () => number;
+    /** Abort in-flight load and reset state. */
+    dispose: () => void;
+}
+/**
+ * imageLoader reactively loads an image via a hidden `Image()` instance.
+ * Exposes `status`, `image`, `width`, `height` as reactive signals — useful
+ * for responsive layouts that need the intrinsic dimensions before render,
+ * lazy-loaded galleries, and preloading checks.
+ *
+ * Accepts a reactive `src` getter OR a plain string. When a getter is given
+ * and its value changes, the previous load is abandoned and a new one
+ * starts.
+ *
+ * @example
+ * ```ts
+ * const img = imageLoader("/hero.jpg");
+ * // Size the container so there's no layout jump
+ * div({ style: () => ({
+ *   aspectRatio: `${img.width()} / ${img.height() || 1}`,
+ * })});
+ * ```
+ */
+declare function imageLoader(src: string | (() => string)): ImageLoaderState;
+
+export { type AnimationFrameOptions, type BoundsRect, type GamepadSnapshot, type ImageLoaderState, type KeyboardOptions, type MouseOptions, type MutationObserverOptions, type SpeakOptions, type SwipeDirection, type SwipeOptions, type TextSelectionState, type UrlStateOptions, animationFrame, battery, bounds, broadcast, clipboard, colorScheme, draggable, dropZone, favicon, formatCurrency, formatNumber, fullscreen, gamepad, geo, idle, imageLoader, keyboard, media, mouse, mutationObserver, network, online, permissions, pointerLock, resize, scroll, speech, svgFavicon, swipe, textSelection, title, urlState, vibrate, visibility, wakeLock, windowSize };