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

package/browser/fps/index.d.ts

@@ -37,7 +37,7 @@ export interface FpsRef {
  *     <button (click)="fpsMonitor.start()">Start</button>
  *   `
  * })
- * class FpsComponent {
+ * export class FpsMonitor {
  *   readonly fpsMonitor = fps();
  * }
  * ```

package/browser/fullscreen/index.d.ts

@@ -0,0 +1,78 @@
+import { type Signal } from '@angular/core';
+import type { MaybeElementSignal, WithInjector } from '@signality/core/types';
+export interface FullscreenOptions extends WithInjector {
+    /**
+     * Element to make fullscreen.
+     * @default document.documentElement
+     */
+    readonly target?: MaybeElementSignal<Element>;
+}
+export interface FullscreenRef {
+    /**
+     * Whether the Fullscreen API is supported in the current browser.
+     *
+     * @see [Fullscreen API browser compatibility on MDN](https://developer.mozilla.org/en-US/docs/Web/API/Fullscreen_API#browser_compatibility)
+     */
+    readonly isSupported: Signal<boolean>;
+    /**
+     * Whether the target element is currently displayed in fullscreen mode.
+     *
+     * @see [Document: fullscreenElement on MDN](https://developer.mozilla.org/en-US/docs/Web/API/Document/fullscreenElement)
+     */
+    readonly isActive: Signal<boolean>;
+    /**
+     * Enter fullscreen mode for the target element.
+     *
+     * @see [Element: requestFullscreen() on MDN](https://developer.mozilla.org/en-US/docs/Web/API/Element/requestFullscreen)
+     */
+    readonly enter: () => Promise<void>;
+    /**
+     * Exit fullscreen mode.
+     *
+     * @see [Document: exitFullscreen() on MDN](https://developer.mozilla.org/en-US/docs/Web/API/Document/exitFullscreen)
+     */
+    readonly exit: () => Promise<void>;
+    /**
+     * Toggle fullscreen mode — enters if inactive, exits if active.
+     */
+    readonly toggle: () => Promise<void>;
+}
+/**
+ * Signal-based wrapper around the [Fullscreen API](https://developer.mozilla.org/en-US/docs/Web/API/Fullscreen_API).
+ *
+ * @param options - Optional configuration including target element and injector
+ * @returns A {@link FullscreenRef} with `isSupported`, `isActive` signals and `enter`/`exit`/`toggle` methods
+ *
+ * @example
+ * ```typescript
+ * @Component({
+ *   template: `
+ *     @if (fs.isSupported()) {
+ *       <button (click)="fs.toggle()">Toggle Fullscreen</button>
+ *       <p>Active: {{ fs.isActive() }}</p>
+ *     }
+ *   `
+ * })
+ * export class FullscreenDemo {
+ *   readonly fs = fullscreen();
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Fullscreen a specific element
+ * @Component({
+ *   template: `
+ *     <div #container>
+ *       <p>This content can go fullscreen</p>
+ *       <button (click)="fs.toggle()">Toggle</button>
+ *     </div>
+ *   `
+ * })
+ * export class ElementFullscreen {
+ *   readonly container = viewChild<ElementRef>('container');
+ *   readonly fs = fullscreen({ target: this.container });
+ * }
+ * ```
+ */
+export declare function fullscreen(options?: FullscreenOptions): FullscreenRef;

package/browser/gamepad/index.d.ts

@@ -1,28 +1,58 @@
 import { type Signal } from '@angular/core';
 import type { WithInjector } from '@signality/core/types';
 export interface GamepadRef {
-    /** Whether Gamepad API is supported */
+    /**
+     * Whether the Gamepad API is supported in the current browser.
+     *
+     * @see [Gamepad API browser compatibility on MDN](https://developer.mozilla.org/en-US/docs/Web/API/Gamepad_API#browser_compatibility)
+     */
     readonly isSupported: Signal<boolean>;
-    /** Array of connected gamepads */
+    /**
+     * Array of all connected gamepads. Indices match the gamepad's `index` property. May contain `null` for disconnected slots.
+     *
+     * @see [Navigator: getGamepads() on MDN](https://developer.mozilla.org/en-US/docs/Web/API/Navigator/getGamepads)
+     */
     readonly gamepads: Signal<(Gamepad | null)[]>;
-    /** First connected gamepad */
+    /**
+     * The first connected gamepad, or `undefined` if none are connected.
+     *
+     * @see [Gamepad on MDN](https://developer.mozilla.org/en-US/docs/Web/API/Gamepad)
+     */
     readonly activeGamepad: Signal<Gamepad | undefined>;
-    /** Axes values of active gamepad */
+    /**
+     * Axes values of the active gamepad. Each value is in the range `[-1, 1]`.
+     *
+     * @see [Gamepad: axes on MDN](https://developer.mozilla.org/en-US/docs/Web/API/Gamepad/axes)
+     */
     readonly axes: Signal<readonly number[]>;
-    /** Button states of active gamepad */
+    /**
+     * Button states of the active gamepad.
+     *
+     * @see [Gamepad: buttons on MDN](https://developer.mozilla.org/en-US/docs/Web/API/Gamepad/buttons)
+     */
     readonly buttons: Signal<readonly GamepadButton[]>;
 }
 /**
- * Signal-based wrapper around the Gamepad API.
+ * Signal-based wrapper around the [Gamepad API](https://developer.mozilla.org/en-US/docs/Web/API/Gamepad_API).
  *
  * @param options - Optional injector for DI context
  * @returns A GamepadRef with gamepad state signals
  *
  * @example
  * ```typescript
- * const gp = gamepad();
- *
- * // In template: @for (pad of gp.gamepads(); track pad?.index) { ... }
+ * @Component({
+ *   template: `
+ *     @if (gp.isSupported()) {
+ *       @for (pad of gp.gamepads(); track pad?.index) {
+ *         <p>{{ pad?.id }}</p>
+ *       }
+ *       <p>Axes: {{ gp.axes() }}</p>
+ *     }
+ *   `
+ * })
+ * export class GamepadDemo {
+ *   readonly gp = gamepad();
+ * }
  * ```
  */
 export declare function gamepad(options?: WithInjector): GamepadRef;

package/browser/geolocation/index.d.ts

@@ -2,40 +2,71 @@ import { type Signal } from '@angular/core';
 import type { WithInjector } from '@signality/core/types';
 export interface GeolocationOptions extends WithInjector {
     /**
-     * Start tracking immediately.
-     * @default true
+     * Start tracking immediately on initialization.
+     *
+     * @default false
      */
     readonly immediate?: boolean;
     /**
-     * Use GPS for better accuracy.
+     * Use GPS for higher accuracy. May be slower and consume more power.
+     *
      * @default true
+     * @see [PositionOptions: enableHighAccuracy on MDN](https://developer.mozilla.org/en-US/docs/Web/API/PositionOptions/enableHighAccuracy)
      */
     readonly enableHighAccuracy?: boolean;
     /**
-     * Max age of cached position (ms).
+     * Maximum age of a cached position in milliseconds. `0` forces a fresh lookup.
+     *
      * @default 0
+     * @see [PositionOptions: maximumAge on MDN](https://developer.mozilla.org/en-US/docs/Web/API/PositionOptions/maximumAge)
      */
     readonly maximumAge?: number;
     /**
-     * Request timeout (ms).
+     * Maximum time in milliseconds allowed to retrieve a position before erroring.
+     *
      * @default Infinity
+     * @see [PositionOptions: timeout on MDN](https://developer.mozilla.org/en-US/docs/Web/API/PositionOptions/timeout)
      */
     readonly timeout?: number;
 }
 export interface GeolocationRef {
-    /** Whether Geolocation is supported */
+    /**
+     * Whether the Geolocation API is supported in the current browser.
+     *
+     * @see [Geolocation API browser compatibility on MDN](https://developer.mozilla.org/en-US/docs/Web/API/Geolocation_API#browser_compatibility)
+     */
     readonly isSupported: Signal<boolean>;
-    /** Full position object with timestamp */
+    /**
+     * The most recent position, including coordinates and timestamp. `null` until first fix.
+     *
+     * @see [GeolocationPosition on MDN](https://developer.mozilla.org/en-US/docs/Web/API/GeolocationPosition)
+     */
     readonly position: Signal<GeolocationPosition | null>;
-    /** Last error */
+    /**
+     * The last error returned by the Geolocation API, or `null` if no error.
+     *
+     * @see [GeolocationPositionError on MDN](https://developer.mozilla.org/en-US/docs/Web/API/GeolocationPositionError)
+     */
     readonly error: Signal<GeolocationPositionError | null>;
-    /** Whether location tracking is currently active */
+    /**
+     * Whether position watching is currently active.
+     */
     readonly isActive: Signal<boolean>;
-    /** Whether currently fetching location */
+    /**
+     * Whether a position fix is currently being fetched.
+     */
     readonly isLoading: Signal<boolean>;
-    /** Start/resume watching position */
+    /**
+     * Start watching the device position.
+     *
+     * @see [Geolocation: watchPosition() on MDN](https://developer.mozilla.org/en-US/docs/Web/API/Geolocation/watchPosition)
+     */
     readonly start: () => void;
-    /** Stop watching position */
+    /**
+     * Stop watching the device position.
+     *
+     * @see [Geolocation: clearWatch() on MDN](https://developer.mozilla.org/en-US/docs/Web/API/Geolocation/clearWatch)
+     */
     readonly stop: () => void;
 }
 /**
@@ -56,7 +87,7 @@ export interface GeolocationRef {
  *     <button (click)="geo.stop()">Stop</button>
  *     <button (click)="geo.start()">Start</button>
  * })
- * class LocationComponent {
+ * export class LocationDemo {
  *   readonly geo = geolocation();
  * }
  * ```

package/browser/index.d.ts

@@ -7,8 +7,10 @@ export * from '@signality/core/browser/clipboard';
 export * from '@signality/core/browser/device-posture';
 export * from '@signality/core/browser/display-media';
 export * from '@signality/core/browser/eye-dropper';
+export * from '@signality/core/browser/file-dialog';
 export * from '@signality/core/browser/favicon';
 export * from '@signality/core/browser/fps';
+export * from '@signality/core/browser/fullscreen';
 export * from '@signality/core/browser/gamepad';
 export * from '@signality/core/browser/geolocation';
 export * from '@signality/core/browser/input-modality';
@@ -16,14 +18,18 @@ export * from '@signality/core/browser/listener';
 export * from '@signality/core/browser/media-query';
 export * from '@signality/core/browser/network';
 export * from '@signality/core/browser/online';
+export * from '@signality/core/browser/permission-state';
 export * from '@signality/core/browser/page-visibility';
 export * from '@signality/core/browser/picture-in-picture';
-export * from '@signality/core/browser/web-share';
+export * from '@signality/core/browser/screen-orientation';
 export * from '@signality/core/browser/speech-recognition';
 export * from '@signality/core/browser/speech-synthesis';
 export * from '@signality/core/browser/storage';
 export * from '@signality/core/browser/text-direction';
+export * from '@signality/core/browser/text-selection';
 export * from '@signality/core/browser/vibration';
-export * from '@signality/core/browser/wake-lock';
 export * from '@signality/core/browser/web-notification';
+export * from '@signality/core/browser/web-share';
 export * from '@signality/core/browser/web-worker';
+export * from '@signality/core/browser/window-focus';
+export * from '@signality/core/browser/window-size';

package/browser/input-modality/index.d.ts

@@ -17,7 +17,7 @@ export type InputModality = 'keyboard' | 'mouse' | 'touch' | null;
  *     </div>
  *   `
  * })
- * export class ModalityComponent {
+ * export class ModalityDemo {
  *   readonly modality = inputModality();
  * }
  * ```

package/browser/listener/index.d.ts

@@ -32,7 +32,7 @@ export interface ListenerFunction {
  * @Component({
  *   template: `<button #btn>Click me</button>`,
  * })
- * class ListenerComponent {
+ * export class ListenerDemo {
  *   readonly btn = viewChild<ElementRef>('btn');
  *
  *   constructor() {

package/browser/media-query/index.d.ts

@@ -26,7 +26,7 @@ export interface MediaQueryOptions extends CreateSignalOptions<boolean>, WithInj
  *     }
  *   `
  * })
- * class ThemeComponent {
+ * export class ThemeDemo {
  *   readonly prefersDark = mediaQuery('(prefers-color-scheme: dark)');
  * }
  * ```

package/browser/network/index.d.ts

@@ -4,23 +4,51 @@ export type EffectiveConnectionType = 'slow-2g' | '2g' | '3g' | '4g';
 export type ConnectionType = 'bluetooth' | 'cellular' | 'ethernet' | 'wifi' | 'wimax' | 'none' | 'other' | 'unknown';
 export type NetworkOptions = WithInjector;
 export interface NetworkRef {
-    /** Whether Network Information API is supported */
+    /**
+     * Whether the Network Information API is supported in the current browser.
+     *
+     * @see [Network Information API browser compatibility on MDN](https://developer.mozilla.org/en-US/docs/Web/API/Network_Information_API#browser_compatibility)
+     */
     readonly isSupported: Signal<boolean>;
-    /** Whether the browser is online */
+    /**
+     * Whether the browser currently has network connectivity.
+     *
+     * @see [Navigator: onLine on MDN](https://developer.mozilla.org/en-US/docs/Web/API/Navigator/onLine)
+     */
     readonly isOnline: Signal<boolean>;
-    /** Effective connection type */
+    /**
+     * Estimated effective connection type based on recently observed network conditions.
+     *
+     * @see [NetworkInformation: effectiveType on MDN](https://developer.mozilla.org/en-US/docs/Web/API/NetworkInformation/effectiveType)
+     */
     readonly effectiveType: Signal<EffectiveConnectionType | undefined>;
-    /** Downlink speed in Mbps */
+    /**
+     * Estimated downlink bandwidth in Mbps.
+     *
+     * @see [NetworkInformation: downlink on MDN](https://developer.mozilla.org/en-US/docs/Web/API/NetworkInformation/downlink)
+     */
     readonly downlink: Signal<number | undefined>;
-    /** Round-trip time in ms */
+    /**
+     * Estimated round-trip latency in milliseconds.
+     *
+     * @see [NetworkInformation: rtt on MDN](https://developer.mozilla.org/en-US/docs/Web/API/NetworkInformation/rtt)
+     */
     readonly rtt: Signal<number | undefined>;
-    /** Whether user has data saver enabled */
+    /**
+     * Whether the user has enabled a data-saving mode in their browser or OS.
+     *
+     * @see [NetworkInformation: saveData on MDN](https://developer.mozilla.org/en-US/docs/Web/API/NetworkInformation/saveData)
+     */
     readonly saveData: Signal<boolean>;
-    /** Connection type (wifi, cellular, etc.) */
+    /**
+     * The physical connection type (e.g. `'wifi'`, `'cellular'`).
+     *
+     * @see [NetworkInformation: type on MDN](https://developer.mozilla.org/en-US/docs/Web/API/NetworkInformation/type)
+     */
     readonly type: Signal<ConnectionType | undefined>;
 }
 /**
- * Signal-based wrapper around the Network Information API and online/offline events.
+ * Signal-based wrapper around the [Network Information API](https://developer.mozilla.org/en-US/docs/Web/API/Network_Information_API) and online/offline events.
  *
  * @param options - Optional configuration including injector
  * @returns A NetworkRef with network status signals
@@ -35,7 +63,7 @@ export interface NetworkRef {
  *     }
  *   `
  * })
- * class NetworkComponent {
+ * export class NetworkComponent {
  *   readonly net = network();
  * }
  * ```

package/browser/online/index.d.ts

@@ -18,7 +18,7 @@ export type OnlineOptions = CreateSignalOptions<boolean> & WithInjector;
  *     }
  *   `
  * })
- * class NetworkStatusComponent {
+ * export class NetworkStatus {
  *   readonly isOnline = online();
  * }
  * ```

package/browser/page-visibility/index.d.ts

@@ -18,7 +18,7 @@ export type PageVisibilityOptions = CreateSignalOptions<DocumentVisibilityState>
  *     }
  *   `
  * })
- * class VisibilityComponent {
+ * export class VisibilityDemo {
  *   readonly visibility = pageVisibility();
  * }
  * ```

package/browser/permission-state/index.d.ts

@@ -0,0 +1,23 @@
+import { type CreateSignalOptions, type Signal } from '@angular/core';
+import type { WithInjector } from '@signality/core/types';
+export type PermissionStateOptions = CreateSignalOptions<PermissionState> & WithInjector;
+/**
+ * Signal-based wrapper around the [Permissions API](https://developer.mozilla.org/en-US/docs/Web/API/Permissions_API).
+ *
+ * @param name - The permission name to query
+ * @param options - Optional configuration including signal options and injector
+ * @returns A signal containing the current `PermissionState` (`'granted'`, `'denied'`, or `'prompt'`)
+ *
+ * @example
+ * ```typescript
+ * @Component({
+ *   template: `
+ *     <p>Camera permission: {{ cameraPermission() }}</p>
+ *   `
+ * })
+ * export class PermissionDemo {
+ *   readonly cameraPermission = permissionState('camera');
+ * }
+ * ```
+ */
+export declare function permissionState(name: PermissionName, options?: PermissionStateOptions): Signal<PermissionState>;

package/browser/picture-in-picture/index.d.ts

@@ -2,15 +2,33 @@ import { type Signal } from '@angular/core';
 import type { MaybeElementSignal, WithInjector } from '@signality/core/types';
 export type PictureInPictureOptions = WithInjector;
 export interface PictureInPictureRef {
-    /** Whether Picture-in-Picture API is supported */
+    /**
+     * Whether the Picture-in-Picture API is supported in the current browser.
+     *
+     * @see [Picture-in-Picture API browser compatibility on MDN](https://developer.mozilla.org/en-US/docs/Web/API/Picture-in-Picture_API#browser_compatibility)
+     */
     readonly isSupported: Signal<boolean>;
-    /** Whether Picture-in-Picture is active */
+    /**
+     * Whether the target video element is currently displayed in Picture-in-Picture mode.
+     *
+     * @see [Document: pictureInPictureElement on MDN](https://developer.mozilla.org/en-US/docs/Web/API/Document/pictureInPictureElement)
+     */
     readonly isActive: Signal<boolean>;
-    /** Enter Picture-in-Picture mode */
+    /**
+     * Enter Picture-in-Picture mode for the target video element.
+     *
+     * @see [HTMLVideoElement: requestPictureInPicture() on MDN](https://developer.mozilla.org/en-US/docs/Web/API/HTMLVideoElement/requestPictureInPicture)
+     */
     readonly enter: () => Promise<void>;
-    /** Exit Picture-in-Picture mode */
+    /**
+     * Exit Picture-in-Picture mode.
+     *
+     * @see [Document: exitPictureInPicture() on MDN](https://developer.mozilla.org/en-US/docs/Web/API/Document/exitPictureInPicture)
+     */
     readonly exit: () => Promise<void>;
-    /** Toggle Picture-in-Picture mode */
+    /**
+     * Toggle Picture-in-Picture mode — enters if inactive, exits if active.
+     */
     readonly toggle: () => Promise<void>;
 }
 /**
@@ -33,7 +51,7 @@ export interface PictureInPictureRef {
  *     }
  *   `
  * })
- * class PiPComponent {
+ * export class PiPDemo {
  *   readonly video = viewChild<HTMLVideoElement>('video');
  *   readonly pip = pictureInPicture(this.video);
  * }

package/browser/screen-orientation/index.d.ts

@@ -21,7 +21,7 @@ export interface ScreenOrientationOptions extends CreateSignalOptions<Orientatio
  *     <p>Orientation: {{ orientation() }}</p>
  *   `
  * })
- * class OrientationComponent {
+ * export class OrientationDemo {
  *   readonly orientation = screenOrientation();
  * }
  * ```

package/browser/speech-recognition/index.d.ts

@@ -2,42 +2,80 @@ import { type Signal } from '@angular/core';
 import type { MaybeSignal, WithInjector } from '@signality/core/types';
 export interface SpeechRecognitionOptions extends WithInjector {
     /**
-     * Language for speech recognition.
+     * BCP 47 language tag for recognition (e.g. `'en-US'`).
+     *
      * @default 'en-US'
+     * @see [SpeechRecognition: lang on MDN](https://developer.mozilla.org/en-US/docs/Web/API/SpeechRecognition/lang)
      */
     readonly lang?: MaybeSignal<string>;
     /**
-     * Whether to return interim results.
+     * Whether to return interim (in-progress) results alongside final ones.
+     *
      * @default false
+     * @see [SpeechRecognition: interimResults on MDN](https://developer.mozilla.org/en-US/docs/Web/API/SpeechRecognition/interimResults)
      */
     readonly interimResults?: boolean;
     /**
-     * Whether to continue recognition after speech ends.
+     * Whether recognition continues after the user stops speaking.
+     *
      * @default false
+     * @see [SpeechRecognition: continuous on MDN](https://developer.mozilla.org/en-US/docs/Web/API/SpeechRecognition/continuous)
      */
     readonly continuous?: boolean;
     /**
-     * Maximum number of alternative transcripts.
+     * Maximum number of alternative recognition results per utterance.
+     *
      * @default 1
+     * @see [SpeechRecognition: maxAlternatives on MDN](https://developer.mozilla.org/en-US/docs/Web/API/SpeechRecognition/maxAlternatives)
      */
     readonly maxAlternatives?: number;
 }
 export interface SpeechRecognitionRef {
-    /** Whether Speech Recognition API is supported */
+    /**
+     * Whether the Speech Recognition API is supported in the current browser.
+     *
+     * @see [SpeechRecognition browser compatibility on MDN](https://developer.mozilla.org/en-US/docs/Web/API/SpeechRecognition#browser_compatibility)
+     */
     readonly isSupported: Signal<boolean>;
-    /** Whether recognition is currently active */
+    /**
+     * Whether speech recognition is currently active and listening.
+     */
     readonly isListening: Signal<boolean>;
-    /** Final transcript text */
+    /**
+     * Accumulated final transcript text.
+     *
+     * @see [SpeechRecognitionResult on MDN](https://developer.mozilla.org/en-US/docs/Web/API/SpeechRecognitionResult)
+     */
     readonly text: Signal<string>;
-    /** Interim transcript text */
+    /**
+     * In-progress interim transcript. Only populated when `interimResults` is `true`.
+     *
+     * @see [SpeechRecognition: interimResults on MDN](https://developer.mozilla.org/en-US/docs/Web/API/SpeechRecognition/interimResults)
+     */
     readonly interimText: Signal<string>;
-    /** Error if recognition failed */
+    /**
+     * The last recognition error, or `null` if no error occurred.
+     *
+     * @see [SpeechRecognitionErrorEvent on MDN](https://developer.mozilla.org/en-US/docs/Web/API/SpeechRecognitionErrorEvent)
+     */
     readonly error: Signal<SpeechRecognitionErrorEvent | Error | null>;
-    /** Start speech recognition */
+    /**
+     * Start listening for speech input.
+     *
+     * @see [SpeechRecognition: start() on MDN](https://developer.mozilla.org/en-US/docs/Web/API/SpeechRecognition/start)
+     */
     readonly start: () => void;
-    /** Stop speech recognition */
+    /**
+     * Stop listening and return any remaining results.
+     *
+     * @see [SpeechRecognition: stop() on MDN](https://developer.mozilla.org/en-US/docs/Web/API/SpeechRecognition/stop)
+     */
     readonly stop: () => void;
-    /** Abort speech recognition */
+    /**
+     * Abort recognition immediately without returning results.
+     *
+     * @see [SpeechRecognition: abort() on MDN](https://developer.mozilla.org/en-US/docs/Web/API/SpeechRecognition/abort)
+     */
     readonly abort: () => void;
 }
 /**
@@ -61,7 +99,7 @@ export interface SpeechRecognitionRef {
  *     }
  *   `
  * })
- * class SpeechComponent {
+ * export class SpeechComponent {
  *   readonly recognition = speechRecognition();
  *
  *   toggleRecognition() {