sibujs 4.4.0 → 4.6.0

package/dist/browser.d.cts

@@ -1,9 +1,22 @@
 /**
- * media returns a reactive boolean that tracks whether a CSS media query matches.
+ * media tracks whether a CSS media query matches.
  * Uses `window.matchMedia` and listens to `change` events for live updates.
  *
+ * It returns an object, not a bare `() => boolean`. The `change` listener stays
+ * attached until `dispose()` is called, so a query created by a component must
+ * be released with it (e.g. `onUnmount(dispose, el)`). After disposal `matches()`
+ * keeps returning its last value.
+ *
+ * @example
+ * ```ts
+ * const { matches: small, dispose } = media("(max-width: 640px)");
+ *
+ * small();
+ * dispose();
+ * ```
+ *
  * @param query CSS media query string (e.g. "(max-width: 768px)")
- * @returns Object with reactive matches getter and dispose function for cleanup
+ * @returns `{ matches, dispose }` — a reactive getter and the listener release
  */
 declare function media(query: string): {
     matches: () => boolean;
@@ -147,15 +160,6 @@ declare function draggable(element: ElementTarget, data?: unknown): {
     isDragging: () => boolean;
     dispose: () => void;
 };
-/**
- * dropZone turns an element into a drop zone and tracks drag-over state.
- * Listens for dragenter, dragleave, dragover, and drop events.
- * Calls options.onDrop with the parsed data payload and the DragEvent.
- *
- * @param element Reactive getter or ref returning the HTMLElement to use as drop zone (or null)
- * @param options Object with onDrop callback receiving the transferred data and event
- * @returns Object with reactive isOver getter and dispose function
- */
 declare function dropZone(element: ElementTarget, options: {
     onDrop: (data: unknown, event: DragEvent) => void;
 }): {
@@ -205,9 +209,11 @@ declare function colorScheme(): {
 declare function formatNumber(value: number, options?: Intl.NumberFormatOptions & {
     locale?: string;
 }): string;
-declare function formatCurrency(value: number, currency: string, options?: Intl.NumberFormatOptions & {
+/** Options for {@link formatCurrency}: any `Intl.NumberFormat` option except the ones it fixes. */
+type CurrencyFormatOptions = Omit<Intl.NumberFormatOptions, "style" | "currency"> & {
     locale?: string;
-}): string;
+};
+declare function formatCurrency(value: number, currency: string, options?: CurrencyFormatOptions): string;
 
 /**
  * visibility tracks the document's Page Visibility state.
@@ -371,6 +377,15 @@ declare function windowSize(): {
 interface UrlStateOptions {
     /** Use `replaceState` instead of `pushState`. Default: false */
     replace?: boolean;
+    /**
+     * The history entry's state. When omitted, the current `history.state` is
+     * kept — on a replaced entry and carried forward onto a pushed one — so router
+     * metadata, scroll restoration data and application state are not erased. A
+     * pushed entry does not inherit `scrollRestoration()`'s entry identity
+     * (`__sibuScrollKey`), which belongs to the entry it was set on.
+     * Pass it (including `null`) only to set new state deliberately.
+     */
+    state?: unknown;
 }
 declare function urlState(): {
     params: () => URLSearchParams;
@@ -397,6 +412,9 @@ declare function urlState(): {
  * the local `last()` signal — BroadcastChannel doesn't deliver to its own
  * sender, matching the browser's native behavior.
  *
+ * After `dispose()`, `post()` is a no-op and `last()` no longer changes;
+ * `dispose()` may be called repeatedly.
+ *
  * @param channelName Name of the broadcast channel
  * @returns `{ last, post, dispose }`
  *
@@ -639,11 +657,27 @@ interface SpeakOptions {
     /** Voice name (match against `getVoices()[i].name`). */
     voice?: string;
 }
+/**
+ * Reset the shared queue. Intended for tests only.
+ *
+ * @internal
+ */
+declare function __resetSpeechCoordinator(): void;
 /**
  * speech wraps the Web Speech Synthesis API as a reactive controller.
  * Exposes `speaking` / `paused` reactive booleans plus `speak()`, `pause()`,
  * `resume()`, `cancel()` actions.
  *
+ * Controllers are isolated from each other: utterances from every controller
+ * play in order, one at a time, and `cancel()`, `pause()`, `resume()` and
+ * `dispose()` affect only this controller's utterances. The native
+ * `speechSynthesis` queue is paused, resumed or cancelled only while one of this
+ * controller's utterances is the one being spoken — and native cancellation
+ * also drops utterances queued directly on `speechSynthesis` by other code.
+ *
+ * - `speaking()` — this controller has an utterance playing or waiting.
+ * - `paused()` — this controller is paused; its waiting utterances do not start.
+ *
  * Automatically gracefully degrades on runtimes without `speechSynthesis`.
  *
  * @example
@@ -718,7 +752,15 @@ declare function gamepad(): {
  */
 declare function pointerLock(): {
     locked: () => boolean;
-    request: (element: Element) => void;
+    /**
+     * Request pointer lock on `element`. Resolves once the browser grants it and
+     * rejects with the browser's own error (e.g. missing user activation), so the
+     * failure can be caught and shown. Resolves without doing anything when the
+     * element has no Pointer Lock support (e.g. iOS Safari) or during SSR, so a
+     * fire-and-forget `onclick: () => lock.request(el)` never raises an unhandled
+     * rejection there; check `locked()` to see whether the lock took effect.
+     */
+    request: (element: Element) => Promise<void>;
     exit: () => void;
     dispose: () => void;
 };
@@ -816,7 +858,10 @@ interface ImageLoaderState {
     width: () => number;
     /** Intrinsic height, 0 until loaded. */
     height: () => number;
-    /** Abort in-flight load and reset state. */
+    /**
+     * Stop tracking `src`, best-effort cancel an in-flight load (its result is
+     * ignored either way), and reset every signal to its initial value.
+     */
     dispose: () => void;
 }
 /**
@@ -840,4 +885,4 @@ interface ImageLoaderState {
  */
 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 };
+export { type AnimationFrameOptions, type BoundsRect, type CurrencyFormatOptions, type GamepadSnapshot, type ImageLoaderState, type KeyboardOptions, type MouseOptions, type MutationObserverOptions, type SpeakOptions, type SwipeDirection, type SwipeOptions, type TextSelectionState, type UrlStateOptions, __resetSpeechCoordinator, 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 };

package/dist/browser.d.ts

@@ -1,9 +1,22 @@
 /**
- * media returns a reactive boolean that tracks whether a CSS media query matches.
+ * media tracks whether a CSS media query matches.
  * Uses `window.matchMedia` and listens to `change` events for live updates.
  *
+ * It returns an object, not a bare `() => boolean`. The `change` listener stays
+ * attached until `dispose()` is called, so a query created by a component must
+ * be released with it (e.g. `onUnmount(dispose, el)`). After disposal `matches()`
+ * keeps returning its last value.
+ *
+ * @example
+ * ```ts
+ * const { matches: small, dispose } = media("(max-width: 640px)");
+ *
+ * small();
+ * dispose();
+ * ```
+ *
  * @param query CSS media query string (e.g. "(max-width: 768px)")
- * @returns Object with reactive matches getter and dispose function for cleanup
+ * @returns `{ matches, dispose }` — a reactive getter and the listener release
  */
 declare function media(query: string): {
     matches: () => boolean;
@@ -147,15 +160,6 @@ declare function draggable(element: ElementTarget, data?: unknown): {
     isDragging: () => boolean;
     dispose: () => void;
 };
-/**
- * dropZone turns an element into a drop zone and tracks drag-over state.
- * Listens for dragenter, dragleave, dragover, and drop events.
- * Calls options.onDrop with the parsed data payload and the DragEvent.
- *
- * @param element Reactive getter or ref returning the HTMLElement to use as drop zone (or null)
- * @param options Object with onDrop callback receiving the transferred data and event
- * @returns Object with reactive isOver getter and dispose function
- */
 declare function dropZone(element: ElementTarget, options: {
     onDrop: (data: unknown, event: DragEvent) => void;
 }): {
@@ -205,9 +209,11 @@ declare function colorScheme(): {
 declare function formatNumber(value: number, options?: Intl.NumberFormatOptions & {
     locale?: string;
 }): string;
-declare function formatCurrency(value: number, currency: string, options?: Intl.NumberFormatOptions & {
+/** Options for {@link formatCurrency}: any `Intl.NumberFormat` option except the ones it fixes. */
+type CurrencyFormatOptions = Omit<Intl.NumberFormatOptions, "style" | "currency"> & {
     locale?: string;
-}): string;
+};
+declare function formatCurrency(value: number, currency: string, options?: CurrencyFormatOptions): string;
 
 /**
  * visibility tracks the document's Page Visibility state.
@@ -371,6 +377,15 @@ declare function windowSize(): {
 interface UrlStateOptions {
     /** Use `replaceState` instead of `pushState`. Default: false */
     replace?: boolean;
+    /**
+     * The history entry's state. When omitted, the current `history.state` is
+     * kept — on a replaced entry and carried forward onto a pushed one — so router
+     * metadata, scroll restoration data and application state are not erased. A
+     * pushed entry does not inherit `scrollRestoration()`'s entry identity
+     * (`__sibuScrollKey`), which belongs to the entry it was set on.
+     * Pass it (including `null`) only to set new state deliberately.
+     */
+    state?: unknown;
 }
 declare function urlState(): {
     params: () => URLSearchParams;
@@ -397,6 +412,9 @@ declare function urlState(): {
  * the local `last()` signal — BroadcastChannel doesn't deliver to its own
  * sender, matching the browser's native behavior.
  *
+ * After `dispose()`, `post()` is a no-op and `last()` no longer changes;
+ * `dispose()` may be called repeatedly.
+ *
  * @param channelName Name of the broadcast channel
  * @returns `{ last, post, dispose }`
  *
@@ -639,11 +657,27 @@ interface SpeakOptions {
     /** Voice name (match against `getVoices()[i].name`). */
     voice?: string;
 }
+/**
+ * Reset the shared queue. Intended for tests only.
+ *
+ * @internal
+ */
+declare function __resetSpeechCoordinator(): void;
 /**
  * speech wraps the Web Speech Synthesis API as a reactive controller.
  * Exposes `speaking` / `paused` reactive booleans plus `speak()`, `pause()`,
  * `resume()`, `cancel()` actions.
  *
+ * Controllers are isolated from each other: utterances from every controller
+ * play in order, one at a time, and `cancel()`, `pause()`, `resume()` and
+ * `dispose()` affect only this controller's utterances. The native
+ * `speechSynthesis` queue is paused, resumed or cancelled only while one of this
+ * controller's utterances is the one being spoken — and native cancellation
+ * also drops utterances queued directly on `speechSynthesis` by other code.
+ *
+ * - `speaking()` — this controller has an utterance playing or waiting.
+ * - `paused()` — this controller is paused; its waiting utterances do not start.
+ *
  * Automatically gracefully degrades on runtimes without `speechSynthesis`.
  *
  * @example
@@ -718,7 +752,15 @@ declare function gamepad(): {
  */
 declare function pointerLock(): {
     locked: () => boolean;
-    request: (element: Element) => void;
+    /**
+     * Request pointer lock on `element`. Resolves once the browser grants it and
+     * rejects with the browser's own error (e.g. missing user activation), so the
+     * failure can be caught and shown. Resolves without doing anything when the
+     * element has no Pointer Lock support (e.g. iOS Safari) or during SSR, so a
+     * fire-and-forget `onclick: () => lock.request(el)` never raises an unhandled
+     * rejection there; check `locked()` to see whether the lock took effect.
+     */
+    request: (element: Element) => Promise<void>;
     exit: () => void;
     dispose: () => void;
 };
@@ -816,7 +858,10 @@ interface ImageLoaderState {
     width: () => number;
     /** Intrinsic height, 0 until loaded. */
     height: () => number;
-    /** Abort in-flight load and reset state. */
+    /**
+     * Stop tracking `src`, best-effort cancel an in-flight load (its result is
+     * ignored either way), and reset every signal to its initial value.
+     */
     dispose: () => void;
 }
 /**
@@ -840,4 +885,4 @@ interface ImageLoaderState {
  */
 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 };
+export { type AnimationFrameOptions, type BoundsRect, type CurrencyFormatOptions, type GamepadSnapshot, type ImageLoaderState, type KeyboardOptions, type MouseOptions, type MutationObserverOptions, type SpeakOptions, type SwipeDirection, type SwipeOptions, type TextSelectionState, type UrlStateOptions, __resetSpeechCoordinator, 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 };

package/dist/browser.js

@@ -1,4 +1,5 @@
 import {
+  __resetSpeechCoordinator,
   animationFrame,
   battery,
   bounds,
@@ -35,16 +36,17 @@ import {
   visibility,
   wakeLock,
   windowSize
-} from "./chunk-LYVUX7NT.js";
+} from "./chunk-OXUY2A6L.js";
 import "./chunk-H3SRKIYX.js";
 import "./chunk-52XFPGSN.js";
 import "./chunk-7ZHH77QA.js";
-import "./chunk-7GIHSAWB.js";
-import "./chunk-5DXA2J44.js";
-import "./chunk-NVNJH22U.js";
-import "./chunk-3BTTCZ5J.js";
-import "./chunk-2WLZ6757.js";
+import "./chunk-XC4MEKGA.js";
+import "./chunk-7XHATCIH.js";
+import "./chunk-D33YTSX5.js";
+import "./chunk-5Q4R7HCL.js";
+import "./chunk-NYNYSPK7.js";
 export {
+  __resetSpeechCoordinator,
   animationFrame,
   battery,
   bounds,