@signality/core 0.0.1-alpha.2 → 0.0.1-alpha.3

package/browser/text-direction/index.d.ts

@@ -10,7 +10,7 @@ export interface TextDirectionOptions extends CreateSignalOptions<TextDirection>
      */
     readonly target?: MaybeElementSignal<HTMLElement>;
     /**
-     * Initial direction value used during SSR or before the DOM is read.
+     * Initial value for SSR.
      * @default 'ltr'
      */
     readonly initialValue?: TextDirection;
@@ -19,9 +19,6 @@ export interface TextDirectionOptions extends CreateSignalOptions<TextDirection>
  * Reactive read/write wrapper around an element's `dir` attribute for detecting and controlling
  * [text directionality](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/dir).
  *
- * Returns a `WritableSignal` that reflects the current `dir` attribute value and updates the DOM
- * when written to. Changes made to the attribute externally are picked up via `MutationObserver`.
- *
  * @param options - Optional configuration including target element, initial value and injector
  * @returns A writable signal of the current text direction
  *
@@ -34,7 +31,7 @@ export interface TextDirectionOptions extends CreateSignalOptions<TextDirection>
  *     <button (click)="dir.set('ltr')">Set LTR</button>
  *   `
  * })
- * class TextDirectionComponent {
+ * export class TextDirectionDemo {
  *   readonly dir = textDirection();
  * }
  * ```

package/{elements → browser}/text-selection/index.d.ts

@@ -30,7 +30,7 @@ export interface TextSelectionRef {
  *     }
  *   `
  * })
- * class TextSelectionComponent {
+ * export class TextSelectionDemo {
  *   readonly selection = textSelection();
  * }
  * ```

package/browser/vibration/index.d.ts

@@ -1,34 +1,63 @@
 import { type Signal } from '@angular/core';
 import type { MaybeSignal, WithInjector } from '@signality/core/types';
 export interface VibrationOptions extends WithInjector {
+    /**
+     * Default vibration pattern in milliseconds. A single number vibrates for that duration;
+     * an array alternates between vibration and pause durations.
+     *
+     * @see [Navigator: vibrate() pattern on MDN](https://developer.mozilla.org/en-US/docs/Web/API/Navigator/vibrate#pattern)
+     */
     readonly pattern?: MaybeSignal<number | number[]>;
 }
 export interface VibrationRef {
-    /** Whether Vibration API is supported */
+    /**
+     * Whether the Vibration API is supported in the current browser.
+     *
+     * @see [Vibration API browser compatibility on MDN](https://developer.mozilla.org/en-US/docs/Web/API/Vibration_API#browser_compatibility)
+     */
     readonly isSupported: Signal<boolean>;
-    /** Whether currently vibrating */
+    /**
+     * Whether the device is currently vibrating.
+     */
     readonly isVibrating: Signal<boolean>;
-    /** Start vibration */
+    /**
+     * Trigger vibration with an optional pattern. Falls back to the default pattern from options, then `200ms`.
+     *
+     * @see [Navigator: vibrate() on MDN](https://developer.mozilla.org/en-US/docs/Web/API/Navigator/vibrate)
+     */
     readonly vibrate: (pattern?: number | number[]) => void;
-    /** Stop vibration */
+    /**
+     * Stop any active vibration by calling `navigator.vibrate(0)`.
+     *
+     * @see [Navigator: vibrate() on MDN](https://developer.mozilla.org/en-US/docs/Web/API/Navigator/vibrate)
+     */
     readonly stop: () => void;
 }
 /**
- * Signal-based wrapper around the Vibration API.
+ * Signal-based wrapper around the [Vibration API](https://developer.mozilla.org/en-US/docs/Web/API/Vibration_API).
  *
  * @param options - Optional configuration including default pattern and injector
  * @returns A VibrationRef with vibration control methods
  *
  * @example
  * ```typescript
- * const vib = vibration();
- *
- * vib.vibrate(100); // Vibrate for 100ms
- * vib.vibrate([100, 50, 100]); // Pattern: vibrate, pause, vibrate
+ * @Component({
+ *   template: `
+ *     @if (vib.isSupported()) {
+ *       <button (click)="vib.vibrate(100)">Vibrate 100ms</button>
+ *       <button (click)="vib.vibrate([100, 50, 100])">Pattern</button>
+ *       <button (click)="vib.stop()">Stop</button>
+ *     }
+ *   `
+ * })
+ * export class VibrationDemo {
+ *   readonly vib = vibration();
+ * }
  * ```
  *
  * @example
  * ```typescript
+ * // With a default pattern
  * const vib = vibration({ pattern: 200 });
  *
  * vib.vibrate(); // Uses default 200ms pattern

package/browser/wake-lock/index.d.ts

@@ -1,36 +1,75 @@
 import { type Signal } from '@angular/core';
 import type { WithInjector } from '@signality/core/types';
 export interface WakeLockOptions extends WithInjector {
-    /** Whether to automatically reacquire wake lock when document becomes visible */
+    /**
+     * Whether to automatically reacquire the wake lock when the document becomes visible again
+     * after being hidden (e.g. tab switch or screen lock).
+     *
+     * Defaults to `true`.
+     *
+     * @see [Page Visibility API on MDN](https://developer.mozilla.org/en-US/docs/Web/API/Page_Visibility_API)
+     */
     readonly autoReacquire?: boolean;
 }
 export interface WakeLockRef {
-    /** Whether Screen Wake Lock API is supported */
+    /**
+     * Whether the Screen Wake Lock API is supported in the current browser.
+     *
+     * @see [Screen Wake Lock API browser compatibility on MDN](https://developer.mozilla.org/en-US/docs/Web/API/Screen_Wake_Lock_API#browser_compatibility)
+     */
     readonly isSupported: Signal<boolean>;
-    /** Whether wake lock is currently active */
+    /**
+     * Whether the wake lock is currently active.
+     * `false` when the sentinel is released or the document is not visible.
+     */
     readonly isActive: Signal<boolean>;
-    /** Current wake lock sentinel */
+    /**
+     * The active `WakeLockSentinel` instance, or `null` when no wake lock is held.
+     *
+     * @see [WakeLockSentinel on MDN](https://developer.mozilla.org/en-US/docs/Web/API/WakeLockSentinel)
+     */
     readonly sentinel: Signal<WakeLockSentinel | null>;
-    /** Request a wake lock */
+    /**
+     * Request a wake lock. No-op if a lock is already active.
+     * If the document is not visible, the request will be deferred until it becomes visible
+     * (only when `autoReacquire` is `true`).
+     *
+     * @see [WakeLock.request() on MDN](https://developer.mozilla.org/en-US/docs/Web/API/WakeLock/request)
+     */
     readonly request: () => Promise<void>;
-    /** Force request a wake lock (releases existing one first) */
+    /**
+     * Request a wake lock unconditionally, releasing the existing sentinel first if present.
+     *
+     * @see [WakeLockSentinel.release() on MDN](https://developer.mozilla.org/en-US/docs/Web/API/WakeLockSentinel/release)
+     */
     readonly forceRequest: () => Promise<void>;
-    /** Release the wake lock */
+    /**
+     * Release the active wake lock and clear the sentinel.
+     *
+     * @see [WakeLockSentinel.release() on MDN](https://developer.mozilla.org/en-US/docs/Web/API/WakeLockSentinel/release)
+     */
     readonly release: () => Promise<void>;
 }
 /**
  * Signal-based wrapper around the [Screen Wake Lock API](https://developer.mozilla.org/en-US/docs/Web/API/Screen_Wake_Lock_API).
+ * Prevents the screen from turning off while the wake lock is active.
  *
  * @param options - Optional configuration
  * @returns A WakeLockRef with isSupported, isActive, sentinel signals and control methods
  *
  * @example
  * ```typescript
- * const wakeLock = wakeLock();
- *
- * if (wakeLock.isSupported()) {
- *   await wakeLock.request();
- *   // Screen will stay awake
+ * @Component({
+ *   template: `
+ *     @if (wl.isSupported()) {
+ *       <button (click)="wl.request()">Keep screen on</button>
+ *       <button (click)="wl.release()">Release</button>
+ *       <p>Active: {{ wl.isActive() }}</p>
+ *     }
+ *   `
+ * })
+ * export class WakeLockDemo {
+ *   readonly wl = wakeLock();
  * }
  * ```
  */

package/browser/web-notification/index.d.ts

@@ -2,26 +2,52 @@ import { type Signal } from '@angular/core';
 import type { MaybeSignal, WithInjector } from '@signality/core/types';
 export interface WebNotificationOptions extends NotificationOptions, WithInjector {
     /**
-     * Auto-close notification after specified milliseconds.
+     * Auto-close the notification after the specified number of milliseconds.
+     *
+     * @see [Notification: close() on MDN](https://developer.mozilla.org/en-US/docs/Web/API/Notification/close)
      */
     readonly autoClose?: MaybeSignal<number>;
 }
 export interface WebNotificationRef {
-    /** Whether Notifications API is supported */
+    /**
+     * Whether the Notifications API is supported in the current browser.
+     *
+     * @see [Notifications API browser compatibility on MDN](https://developer.mozilla.org/en-US/docs/Web/API/Notifications_API#browser_compatibility)
+     */
     readonly isSupported: Signal<boolean>;
-    /** Current permission state */
+    /**
+     * Current notification permission state: `'granted'`, `'denied'`, or `'default'`.
+     *
+     * @see [Notification: permission static property on MDN](https://developer.mozilla.org/en-US/docs/Web/API/Notification/permission_static)
+     */
     readonly permission: Signal<NotificationPermission>;
-    /** Current active notification instance */
+    /**
+     * The currently active notification instance, or `null` if none is shown.
+     *
+     * @see [Notification on MDN](https://developer.mozilla.org/en-US/docs/Web/API/Notification)
+     */
     readonly notification: Signal<Notification | null>;
-    /** Request notification permission */
+    /**
+     * Request permission to show notifications.
+     *
+     * @see [Notification: requestPermission() on MDN](https://developer.mozilla.org/en-US/docs/Web/API/Notification/requestPermission_static)
+     */
     readonly requestPermission: () => Promise<NotificationPermission>;
-    /** Show a notification (auto-closes previous). Per-call options override defaults from constructor. */
+    /**
+     * Show a notification. Automatically closes the previous one. Per-call options override constructor defaults.
+     *
+     * @see [Notification() constructor on MDN](https://developer.mozilla.org/en-US/docs/Web/API/Notification/Notification)
+     */
     readonly show: (title: string, options?: NotificationOptions) => Notification | undefined;
-    /** Close the current notification */
+    /**
+     * Close the currently active notification.
+     *
+     * @see [Notification: close() on MDN](https://developer.mozilla.org/en-US/docs/Web/API/Notification/close)
+     */
     readonly close: () => void;
 }
 /**
- * Signal-based wrapper around the Notifications API.
+ * Signal-based wrapper around the [Notifications API](https://developer.mozilla.org/en-US/docs/Web/API/Notifications_API).
  *
  * Tracks the current notification as a signal. Calling `show()` auto-closes
  * the previous notification. Calling `close()` closes the current one.
@@ -42,7 +68,7 @@ export interface WebNotificationRef {
  *     }
  *   `
  * })
- * class NotificationComponent {
+ * export class NotificationDemo {
  *   readonly notif = webNotification({ icon: '/icon.png' });
  *
  *   async requestPermission() {

package/browser/web-share/index.d.ts

@@ -1,13 +1,27 @@
 import { type Signal } from '@angular/core';
 import type { WithInjector } from '@signality/core/types';
 export interface WebShareRef {
-    /** Whether Web Share API is supported */
+    /**
+     * Whether the Web Share API is supported in the current browser.
+     *
+     * @see [Web Share API browser compatibility on MDN](https://developer.mozilla.org/en-US/docs/Web/API/Web_Share_API#browser_compatibility)
+     */
     readonly isSupported: Signal<boolean>;
-    /** Whether the share dialog is currently open */
+    /**
+     * Whether the native share dialog is currently open.
+     */
     readonly isSharing: Signal<boolean>;
-    /** Open the native share dialog */
+    /**
+     * Open the native share dialog with the provided data.
+     *
+     * @see [Navigator: share() on MDN](https://developer.mozilla.org/en-US/docs/Web/API/Navigator/share)
+     */
     readonly share: (data: ShareData) => Promise<void>;
-    /** Check if data can be shared */
+    /**
+     * Check whether the given data can be shared via the Web Share API.
+     *
+     * @see [Navigator: canShare() on MDN](https://developer.mozilla.org/en-US/docs/Web/API/Navigator/canShare)
+     */
     readonly canShare: (data?: ShareData) => boolean;
 }
 /**
@@ -27,7 +41,7 @@ export interface WebShareRef {
  *     }
  *   `
  * })
- * class WebShareComponent {
+ * export class WebShareDemo {
  *   readonly webShare = webShare();
  *
  *   async shareContent() {

package/browser/web-worker/index.d.ts

@@ -2,35 +2,59 @@ import { type Signal } from '@angular/core';
 import type { MaybeSignal, WithInjector } from '@signality/core/types';
 export interface WebWorkerOptions extends WithInjector {
     /**
-     * Worker type.
+     * Worker script type.
+     *
      * @default 'classic'
+     * @see [Worker: Worker() constructor — type on MDN](https://developer.mozilla.org/en-US/docs/Web/API/Worker/Worker#type)
      */
     readonly type?: 'classic' | 'module';
     /**
-     * Credentials mode.
+     * Credentials mode used when fetching the worker script.
+     *
+     * @see [Worker: Worker() constructor — credentials on MDN](https://developer.mozilla.org/en-US/docs/Web/API/Worker/Worker#credentials)
      */
     readonly credentials?: RequestCredentials;
     /**
-     * Worker name for debugging.
+     * Identifying name for the worker, useful for debugging in DevTools.
+     *
+     * @see [Worker: Worker() constructor — name on MDN](https://developer.mozilla.org/en-US/docs/Web/API/Worker/Worker#name)
      */
     readonly name?: string;
 }
 export interface WebWorkerRef<I, O> {
-    /** Last message received from worker */
+    /**
+     * The last message received from the worker via `postMessage`.
+     * `undefined` until the first message is received.
+     */
     readonly data: Signal<O | undefined>;
-    /** Whether worker is ready */
+    /**
+     * Whether the worker has been successfully created and is ready to receive messages.
+     */
     readonly isReady: Signal<boolean>;
-    /** Last error from worker */
+    /**
+     * The last error emitted by the worker, or `null` if no error has occurred.
+     */
     readonly error: Signal<Error | null>;
-    /** Send message to worker */
+    /**
+     * Send a message to the worker.
+     *
+     * @see [Worker.postMessage() on MDN](https://developer.mozilla.org/en-US/docs/Web/API/Worker/postMessage)
+     */
     readonly post: (data: I) => void;
-    /** Terminate the worker */
+    /**
+     * Terminate the worker immediately, discarding any pending messages.
+     *
+     * @see [Worker.terminate() on MDN](https://developer.mozilla.org/en-US/docs/Web/API/Worker/terminate)
+     */
     readonly terminate: () => void;
 }
 /**
- * Signal-based wrapper around the Web Workers API.
+ * Signal-based wrapper around the [Web Workers API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API).
+ * Run scripts in background threads without blocking the main thread.
+ *
+ * When `url` is a signal, the worker is automatically recreated whenever the URL changes.
  *
- * @param url - Worker script URL
+ * @param url - Worker script URL (static or reactive signal)
  * @param options - Optional configuration
  * @returns A WebWorkerRef with data signal and control methods
  *
@@ -44,7 +68,7 @@ export interface WebWorkerRef<I, O> {
  *     }
  *   `
  * })
- * class WorkerComponent {
+ * export class WorkerDemo {
  *   readonly worker = webWorker<number, number>('/workers/calc.js');
  * }
  * ```

package/browser/window-focus/index.d.ts

@@ -0,0 +1,27 @@
+import { type CreateSignalOptions, type Signal } from '@angular/core';
+import type { WithInjector } from '@signality/core/types';
+export type WindowFocusOptions = CreateSignalOptions<boolean> & WithInjector;
+/**
+ * Signal-based wrapper around the [Window focus/blur events](https://developer.mozilla.org/en-US/docs/Web/API/Window/focus_event).
+ *
+ * @param options - Optional configuration including signal options and injector
+ * @returns A signal containing the current window focus state (`true` if focused, `false` if blurred)
+ *
+ * @example
+ * ```typescript
+ * @Component({
+ *   template: `
+ *     @if (isFocused()) {
+ *       <p>Window is focused</p>
+ *     } @else {
+ *       <p>Window is not focused</p>
+ *     }
+ *   `
+ * })
+ * export class FocusDemo {
+ *   readonly isFocused = windowFocus();
+ * }
+ * ```
+ */
+export declare function windowFocus(options?: WindowFocusOptions): Signal<boolean>;
+export declare const WINDOW_FOCUS: import("@angular/core").ProviderToken<Signal<boolean>>;

package/{elements → browser}/window-size/index.d.ts

@@ -3,21 +3,20 @@ import type { WithInjector } from '@signality/core/types';
 export interface WindowSizeOptions extends CreateSignalOptions<WindowSizeValue>, WithInjector {
     /**
      * Include scrollbar in dimensions calculation.
+     *
      * @default false
      */
     readonly includeScrollbar?: boolean;
     /**
-     * Initial dimensions for SSR.
+     * Initial value for SSR and before the first measurement.
+     *
+     * @default { width: 0, height: 0 }
      */
-    readonly initialValue?: Pick<WindowSizeValue, 'width' | 'height'>;
+    readonly initialValue?: WindowSizeValue;
 }
 export interface WindowSizeValue {
     readonly width: number;
     readonly height: number;
-    readonly innerWidth: number;
-    readonly innerHeight: number;
-    readonly outerWidth: number;
-    readonly outerHeight: number;
 }
 /**
  * Signal-based wrapper around the [Window API](https://developer.mozilla.org/en-US/docs/Web/API/Window) dimensions.
@@ -37,7 +36,7 @@ export interface WindowSizeValue {
  *     </div>
  *   `
  * })
- * class WindowSizeComponent {
+ * export class WindowSizeComponent {
  *   readonly size = windowSize();
  * }
  * ```

package/elements/active-element/index.d.ts

@@ -18,7 +18,7 @@ export type ActiveElementOptions = CreateSignalOptions<Element | null> & WithInj
  *     }
  *   `
  * })
- * class ActiveElementComponent {
+ * export class ActiveElementDemo {
  *   readonly activeEl = activeElement();
  * }
  * ```

package/elements/dropzone/index.d.ts

@@ -2,27 +2,77 @@ import { type Signal, type WritableSignal } from '@angular/core';
 import type { MaybeElementSignal, MaybeSignal, WithInjector } from '@signality/core/types';
 export interface DropzoneOptions extends WithInjector {
     /**
-     * Accepted MIME types.
-     * @default ['*']
+     * Comma-separated list of accepted file types, matching the native HTML
+     * [`accept`](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Attributes/accept) attribute format.
+     * Supports MIME types (`'image/png'`), wildcards (`'image/*'`), and file extensions (`'.pdf'`).
+     * Use `'*'` to accept all file types.
+     *
+     * @default '*'
+     * @see [accept attribute on MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Attributes/accept)
      */
-    readonly accept?: MaybeSignal<string[]>;
+    readonly accept?: MaybeSignal<string>;
     /**
-     * Allow multiple files.
+     * Whether to allow dropping multiple files at once.
+     * When `false`, only the first accepted file is kept.
+     *
      * @default true
      */
     readonly multiple?: MaybeSignal<boolean>;
     /**
-     * Prevent drops outside the zone.
+     * When `true`, prevents files from being dropped anywhere outside the drop zone
+     * by intercepting `dragover` and `drop` events on the document.
+     *
      * @default true
      */
     readonly preventDocumentDrop?: boolean;
+    /**
+     * Custom validation predicate called for each dropped file.
+     * Return `true` to keep the file, `false` to reject it.
+     *
+     * When provided, the `accept` option is ignored — the validator
+     * takes full responsibility for deciding which files are valid.
+     *
+     * @example
+     * ```typescript
+     * dropzone(target, {
+     *   validator: (file) => file.size <= 5 * 1024 * 1024, // max 5 MB
+     * });
+     * ```
+     */
+    readonly validator?: (file: File) => boolean;
+    /**
+     * Callback invoked with files that were rejected during a drop.
+     * Called once per drop with the full array of rejected files.
+     * Useful for showing toast notifications or validation errors.
+     *
+     * @example
+     * ```typescript
+     * dropzone(target, {
+     *   accept: 'image/*',
+     *   onReject: (rejected) => {
+     *     rejected.forEach(f => toast.error(`${f.name} is not an image`));
+     *   },
+     * });
+     * ```
+     */
+    readonly onReject?: (files: File[]) => void;
 }
 export interface DropzoneRef {
-    /** Dropped files */
+    /**
+     * List of files dropped onto the zone, filtered by `accept` and `multiple`.
+     * A `WritableSignal` — can be reset externally (e.g. after upload).
+     *
+     * @see [DataTransfer.files on MDN](https://developer.mozilla.org/en-US/docs/Web/API/DataTransfer/files)
+     */
     readonly files: WritableSignal<File[]>;
-    /** Whether dragging over the zone */
+    /**
+     * Whether the user is currently dragging over the drop zone.
+     */
     readonly isOver: Signal<boolean>;
-    /** Whether any drag is in progress (document-wide) */
+    /**
+     * Whether any drag operation is in progress anywhere on the document.
+     * Useful for showing a global drop overlay.
+     */
     readonly isDragging: Signal<boolean>;
 }
 /**
@@ -52,9 +102,9 @@ export interface DropzoneRef {
  *     </div>
  *   `
  * })
- * class DropzoneComponent {
+ * export class DropzoneDemo {
  *   readonly zone = viewChild<ElementRef>('zone');
- *   readonly drop = dropzone(this.zone, { accept: ['image/*'], multiple: true });
+ *   readonly drop = dropzone(this.zone, { accept: 'image/*', multiple: true });
  * }
  * ```
  */

package/elements/element-focus/index.d.ts

@@ -29,7 +29,7 @@ export interface ElementFocusOptions extends CreateSignalOptions<boolean>, WithI
  *     }
  *   `
  * })
- * class FocusComponent {
+ * export class FocusDemo {
  *   readonly input = viewChild<ElementRef>('input');
  *   readonly isFocused = elementFocus(this.input);
  * }

package/elements/element-focus-within/index.d.ts

@@ -20,7 +20,7 @@ export type ElementFocusWithinOptions = CreateSignalOptions<boolean> & WithInjec
  *     </div>
  *   `
  * })
- * class FocusWithinComponent {
+ * export class FocusWithinDemo {
  *   readonly container = viewChild<ElementRef>('container');
  *   readonly isFocusedWithin = elementFocusWithin(this.container);
  * }

package/elements/element-hover/index.d.ts

@@ -18,7 +18,7 @@ export type ElementHoverOptions = CreateSignalOptions<boolean> & WithInjector;
  *     </div>
  *   `
  * })
- * class HoverComponent {
+ * export class HoverDemo {
  *   readonly box = viewChild<ElementRef>('box');
  *   readonly isHovered = elementHover(this.box);
  * }

package/elements/element-size/index.d.ts

@@ -3,17 +3,20 @@ import type { MaybeElementSignal, MaybeSignal, WithInjector } from '@signality/c
 export interface ElementSizeValue {
     readonly width: number;
     readonly height: number;
-    readonly contentWidth: number;
-    readonly contentHeight: number;
-    readonly borderBoxWidth: number;
-    readonly borderBoxHeight: number;
 }
 export interface ElementSizeOptions extends CreateSignalOptions<ElementSizeValue>, WithInjector {
     /**
      * Which box model to observe. Can be a reactive signal.
+     *
      * @default 'border-box'
      */
     readonly box?: MaybeSignal<ResizeObserverBoxOptions>;
+    /**
+     * Initial value for SSR and before the first measurement.
+     *
+     * @default { width: 0, height: 0 }
+     */
+    readonly initialValue?: ElementSizeValue;
 }
 /**
  * Signal-based wrapper around the [ResizeObserver API](https://developer.mozilla.org/en-US/docs/Web/API/ResizeObserver).
@@ -31,7 +34,7 @@ export interface ElementSizeOptions extends CreateSignalOptions<ElementSizeValue
  *     </div>
  *   `
  * })
- * class SizeComponent {
+ * export class ElementSizeDemo {
  *   readonly box = viewChild<ElementRef>('box');
  *   readonly size = elementSize(this.box);
  * }