@signality/core 0.0.1-alpha.2

package/README.md

@@ -0,0 +1,60 @@
+# @signality/core
+
+Signal-first utility collection for Angular. Comprehensive library of reactive utilities for browser APIs, DOM elements, and common patterns.
+
+## Installation
+
+```bash
+npm install @signality/core
+```
+
+## Features
+
+### Browser Utilities
+- **`battery()`** — Reactive battery status and charging state
+- **`clipboard()`** — Reactive clipboard read/write operations
+- **`geolocation()`** — Reactive geolocation tracking
+- **`pageVisibility()`** — Reactive page visibility state
+- **`storage()`** — Reactive localStorage/sessionStorage with sync
+- **`network()`** — Reactive network connection status
+- **`fullscreen()`** — Reactive fullscreen API
+- And [many more...](https://signality.dev/browser/battery)
+
+### Element Utilities
+- **`elementSize()`** — Reactive element dimensions
+- **`elementVisibility()`** — Reactive Intersection Observer
+- **`dropzone()`** — Reactive drag & drop zone
+- **`windowSize()`** — Reactive window dimensions
+- **`scrollPosition()`** — Reactive scroll position
+- And [many more...](https://signality.dev/elements/active-element)
+
+### Utils
+- **`debounced()`** — Debounced writable signal
+- **`throttled()`** — Throttled writable signal
+
+## Usage
+
+```typescript
+import { battery, clipboard, elementSize, debounced } from '@signality/core';
+
+// Battery status
+const batteryStatus = battery();
+// batteryStatus.level(), batteryStatus.charging()
+
+// Clipboard operations
+const clipboard = clipboard();
+await clipboard.copy('Hello');
+const text = await clipboard.paste();
+
+// Element size tracking
+const element = viewChild<ElementRef<HTMLDivElement>>('myElement');
+const size = elementSize(element);
+// size.width(), size.height()
+
+// Debounced signal
+const searchQuery = debounced('', 300);
+```
+
+## Documentation
+
+Full documentation available at [signality.dev](https://signality.dev)

package/browser/battery/index.d.ts

@@ -0,0 +1,34 @@
+import { type Signal } from '@angular/core';
+import type { WithInjector } from '@signality/core/types';
+export type BatteryOptions = WithInjector;
+export interface BatteryRef {
+    readonly charging: Signal<boolean>;
+    readonly chargingTime: Signal<number>;
+    readonly dischargingTime: Signal<number>;
+    readonly level: Signal<number>;
+    readonly isSupported: Signal<boolean>;
+}
+/**
+ * Signal-based wrapper around the [Battery Status API](https://developer.mozilla.org/en-US/docs/Web/API/Battery_Status_API).
+ *
+ * @param options - Optional configuration with injector
+ * @returns A BatteryRef with battery status signals
+ *
+ * @example
+ * ```typescript
+ * @Component({
+ *   template: `
+ *     @if (batteryStatus.isSupported()) {
+ *       <div>
+ *         <p>Charging: {{ batteryStatus.charging() }}</p>
+ *         <p>Level: {{ batteryStatus.level() * 100 }}%</p>
+ *       </div>
+ *     }
+ *   `
+ * })
+ * class BatteryComponent {
+ *   readonly batteryStatus = battery();
+ * }
+ * ```
+ */
+export declare function battery(options?: BatteryOptions): BatteryRef;

package/browser/bluetooth/index.d.ts

@@ -0,0 +1,56 @@
+import { type Signal } from '@angular/core';
+import type { WithInjector } from '@signality/core/types';
+export interface BluetoothOptions extends WithInjector {
+    /**
+     * Accept any Bluetooth device.
+     */
+    readonly acceptAllDevices?: boolean;
+    /**
+     * Filters for device selection.
+     */
+    readonly filters?: BluetoothLEScanFilter[];
+    /**
+     * Optional services to access.
+     */
+    readonly optionalServices?: BluetoothServiceUUID[];
+}
+export interface BluetoothRef {
+    /** Whether Web Bluetooth API is supported */
+    readonly isSupported: Signal<boolean>;
+    /** Whether a device is currently connected */
+    readonly isConnected: Signal<boolean>;
+    /** Whether connection is in progress */
+    readonly isConnecting: Signal<boolean>;
+    /** Connected Bluetooth device */
+    readonly device: Signal<BluetoothDevice | null>;
+    /** GATT server of connected device */
+    readonly server: Signal<BluetoothRemoteGATTServer | null>;
+    /** Last error that occurred */
+    readonly error: Signal<Error | null>;
+    /** Request device connection */
+    readonly request: (options?: RequestDeviceOptions) => Promise<void>;
+    /** Disconnect from device */
+    readonly disconnect: () => void;
+}
+/**
+ * Signal-based wrapper around the [Web Bluetooth API](https://developer.mozilla.org/en-US/docs/Web/API/Bluetooth).
+ *
+ * @param options - Optional configuration
+ * @returns A BluetoothRef with connection state and control methods
+ *
+ * @example
+ * ```typescript
+ * @Component({
+ *   template: `
+ *     <button (click)="bt.request()">Connect</button>
+ *     @if (bt.isConnected()) {
+ *       <p>{{ bt.device()?.name }}</p>
+ *     }
+ *   `
+ * })
+ * class BluetoothComponent {
+ *   readonly bt = bluetooth();
+ * }
+ * ```
+ */
+export declare function bluetooth(options?: BluetoothOptions): BluetoothRef;

package/browser/breakpoints/index.d.ts

@@ -0,0 +1,32 @@
+import { type Signal } from '@angular/core';
+import type { WithInjector } from '@signality/core/types';
+export interface BreakpointsOptions<T extends Record<string, string>> extends WithInjector {
+    /**
+     * Initial values for SSR.
+     */
+    readonly initialValue?: Partial<Record<keyof T, boolean>>;
+}
+export type BreakpointsRef<T extends Record<string, string>> = {
+    readonly [K in keyof T]: Signal<boolean>;
+} & {
+    readonly current: Signal<(keyof T)[]>;
+};
+/**
+ * Reactive breakpoint matching using matchMedia.
+ * Track responsive breakpoints with Angular signals.
+ *
+ * @param map - Object mapping breakpoint names to media queries
+ * @param options - Optional configuration
+ * @returns An object with signals for each breakpoint
+ *
+ * @example
+ * ```typescript
+ * const bp = breakpoints({
+ *   mobile: '(max-width: 767px)',
+ *   desktop: '(min-width: 768px)',
+ * });
+ *
+ * // In template: @if (bp.mobile()) { ... }
+ * ```
+ */
+export declare function breakpoints<T extends Record<string, string>>(map: T, options?: BreakpointsOptions<T>): BreakpointsRef<T>;

package/browser/broadcast-channel/index.d.ts

@@ -0,0 +1,42 @@
+import { type Signal } from '@angular/core';
+import type { WithInjector } from '@signality/core/types';
+export type BroadcastChannelOptions = WithInjector;
+export interface BroadcastChannelRef<T> {
+    /** Last received data */
+    readonly data: Signal<T | null>;
+    /** The last error that occurred */
+    readonly error: Signal<MessageEvent | null>;
+    /** Whether the channel is closed */
+    readonly isClosed: Signal<boolean>;
+    /** Send a message to all tabs */
+    readonly post: (data: T) => void;
+    /** Close the channel */
+    readonly close: () => void;
+}
+/**
+ * Signal-based wrapper around the [Broadcast Channel API](https://developer.mozilla.org/en-US/docs/Web/API/Broadcast_Channel_API).
+ *
+ * @param name - Channel name (must match across tabs)
+ * @param options - Optional configuration
+ * @returns A BroadcastChannelRef with data signal and control methods
+ *
+ * @example
+ * ```typescript
+ * @Component({
+ *   template: `
+ *     @if (channel.data(); as data) {
+ *       <p>Received: {{ data }}</p>
+ *     }
+ *     <button (click)="sendMessage()">Send Message</button>
+ *   `
+ * })
+ * class ChatComponent {
+ *   readonly channel = broadcastChannel<string>('my-channel');
+ *
+ *   sendMessage() {
+ *     this.channel.post('Hello from this tab!');
+ *   }
+ * }
+ * ```
+ */
+export declare function broadcastChannel<T>(name: string, options?: BroadcastChannelOptions): BroadcastChannelRef<T>;

package/browser/browser-language/index.d.ts

@@ -0,0 +1,34 @@
+import { type CreateSignalOptions, type Signal } from '@angular/core';
+import type { WithInjector } from '@signality/core/types';
+export interface BrowserLanguageOptions extends CreateSignalOptions<string>, WithInjector {
+    /**
+     * Initial value for SSR.
+     * @default ''
+     */
+    readonly initialValue?: string;
+}
+/**
+ * Reactive wrapper around the [Navigator.language](https://developer.mozilla.org/en-US/docs/Web/API/Navigator/language) property.
+ *
+ * @param options - Optional configuration including signal options and injector
+ * @returns A signal containing the current browser language in BCP 47 format (e.g., 'en-US', 'fr-FR')
+ *
+ * @example
+ * ```typescript
+ * @Component({
+ *   template: `
+ *     <p>Current language: {{ language() }}</p>
+ *     @if (language() === 'en-US') {
+ *       <p>Welcome!</p>
+ *     } @else if (language() === 'fr-FR') {
+ *       <p>Bienvenue!</p>
+ *     }
+ *   `
+ * })
+ * class LanguageComponent {
+ *   readonly language = browserLanguage();
+ * }
+ * ```
+ */
+export declare function browserLanguage(options?: BrowserLanguageOptions): Signal<string>;
+export declare const BROWSER_LANGUAGE: import("@angular/core").ProviderToken<Signal<string>>;

package/browser/clipboard/index.d.ts

@@ -0,0 +1,48 @@
+import { type Signal } from '@angular/core';
+import type { MaybeSignal, WithInjector } from '@signality/core/types';
+export interface ClipboardOptions extends WithInjector {
+    /**
+     * How long `copied` stays `true` after copy (ms).
+     * @default 1500
+     */
+    readonly copiedDuration?: MaybeSignal<number>;
+}
+export interface ClipboardRef {
+    /** Whether Clipboard API is supported */
+    readonly isSupported: Signal<boolean>;
+    /** Current clipboard text content */
+    readonly text: Signal<string>;
+    /** Whether content was recently copied (resets after timeout) */
+    readonly copied: Signal<boolean>;
+    /** Copy text to clipboard */
+    readonly copy: (text: string) => Promise<void>;
+    /** Read text from clipboard */
+    readonly paste: () => Promise<string>;
+}
+/**
+ * Signal-based wrapper around the [Clipboard API](https://developer.mozilla.org/en-US/docs/Web/API/Clipboard_API).
+ *
+ * @param options - Optional configuration
+ * @returns A ClipboardRef with text, copied, isSupported signals and copy/paste methods
+ *
+ * @example
+ * ```typescript
+ * @Component({
+ *   template: `
+ *     <input #input value="Hello World!" />
+ *     <button (click)="copyText(input.value)">Copy</button>
+ *     @if (cb.copied()) {
+ *       <span>Copied!</span>
+ *     }
+ *   `
+ * })
+ * class ClipboardComponent {
+ *   readonly cb = clipboard();
+ *
+ *   async copyText(text: string) {
+ *     await this.cb.copy(text);
+ *   }
+ * }
+ * ```
+ */
+export declare function clipboard(options?: ClipboardOptions): ClipboardRef;

package/browser/device-posture/index.d.ts

@@ -0,0 +1,18 @@
+import { type Signal } from '@angular/core';
+import type { WithInjector } from '@signality/core/types';
+export type DevicePostureType = 'continuous' | 'folded';
+export interface DevicePostureRef {
+    /** Whether Device Posture API is supported */
+    readonly isSupported: Signal<boolean>;
+    /** Current device posture */
+    readonly type: Signal<DevicePostureType>;
+}
+/**
+ * Signal-based wrapper around the [Device Posture API](https://developer.mozilla.org/en-US/docs/Web/API/Device_Posture_API).
+ * Track device posture state for foldable devices.
+ *
+ * @param options - Optional configuration including injector
+ * @returns A DevicePostureRef with type signal
+ *
+ */
+export declare function devicePosture(options?: WithInjector): DevicePostureRef;

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

@@ -0,0 +1,80 @@
+import { type Signal } from '@angular/core';
+import type { WithInjector } from '@signality/core/types';
+export interface DisplayMediaOptions extends WithInjector {
+    /**
+     * Video constraints.
+     * @default true
+     */
+    readonly video?: boolean | MediaTrackConstraints;
+    /**
+     * Audio constraints.
+     * @default false
+     */
+    readonly audio?: boolean | MediaTrackConstraints;
+}
+export interface DisplayMediaRef {
+    /** Whether Screen Capture API is supported */
+    readonly isSupported: Signal<boolean>;
+    /** Whether currently capturing */
+    readonly isActive: Signal<boolean>;
+    /** Current media stream */
+    readonly stream: Signal<MediaStream | null>;
+    /** Last error */
+    readonly error: Signal<Error | null>;
+    /** Start screen capture */
+    readonly start: (options?: DisplayMediaOptions) => Promise<MediaStream | null>;
+    /** Stop screen capture */
+    readonly stop: () => void;
+}
+/**
+ * Signal-based wrapper around the [Screen Capture API](https://developer.mozilla.org/en-US/docs/Web/API/Screen_Capture_API).
+ * Capture screen content with Angular signals.
+ *
+ * @param options - Optional default configuration
+ * @returns A DisplayMediaRef with isSupported, stream, error signals and control methods
+ *
+ * @example
+ * ```typescript
+ * @Component({
+ *   template: `
+ *     @if (screen.isSupported()) {
+ *       <button (click)="toggleCapture()">
+ *         {{ screen.isActive() ? 'Stop' : 'Start' }} Screen Capture
+ *       </button>
+ *       @if (screen.stream(); as stream) {
+ *         <video [srcObject]="stream" autoplay></video>
+ *       }
+ *       @if (screen.error(); as error) {
+ *         <p class="error">{{ error.message }}</p>
+ *       }
+ *     } @else {
+ *       <p>Screen Capture API not supported</p>
+ *     }
+ *   `
+ * })
+ * class ScreenCaptureComponent {
+ *   readonly screen = displayMedia();
+ *
+ *   async toggleCapture() {
+ *     if (this.screen.isActive()) {
+ *       this.screen.stop();
+ *     } else {
+ *       await this.screen.start();
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With custom constraints
+ * const screen = displayMedia({
+ *   video: {
+ *     width: { ideal: 1920 },
+ *     height: { ideal: 1080 },
+ *   },
+ *   audio: true,
+ * });
+ * ```
+ */
+export declare function displayMedia(options?: DisplayMediaOptions): DisplayMediaRef;

package/browser/eye-dropper/index.d.ts

@@ -0,0 +1,47 @@
+import { type Signal } from '@angular/core';
+import type { WithInjector } from '@signality/core/types';
+export interface EyeDropperOptions extends WithInjector {
+    /**
+     * Initial color value in sRGB hex format.
+     * @default ''
+     */
+    readonly initialValue?: string;
+}
+export interface EyeDropperRef {
+    /** Current selected color in sRGB hex format */
+    readonly sRGBHex: Signal<string>;
+    /** Whether EyeDropper API is supported */
+    readonly isSupported: Signal<boolean>;
+    /** Open the eyedropper tool to select a color */
+    readonly open: () => Promise<void>;
+    /** Cancel the active eyedropper operation */
+    readonly close: () => void;
+}
+/**
+ * Signal-based wrapper around the [EyeDropper API](https://developer.mozilla.org/en-US/docs/Web/API/EyeDropper_API).
+ *
+ * @param options - Optional configuration
+ * @returns An {@link EyeDropperRef} with `isSupported`, `sRGBHex` signals and `open`/`close` methods
+ *
+ * @example
+ * ```typescript
+ * @Component({
+ *   template: `
+ *     @if (eyeDropper.isSupported()) {
+ *       <button (click)="pickColor()">Pick Color</button>
+ *       <div [style.background-color]="eyeDropper.sRGBHex()">
+ *         Selected: {{ eyeDropper.sRGBHex() }}
+ *       </div>
+ *     }
+ *   `
+ * })
+ * class ColorPickerComponent {
+ *   readonly eyeDropper = eyeDropper();
+ *
+ *   async pickColor() {
+ *     await this.eyeDropper.open();
+ *   }
+ * }
+ * ```
+ */
+export declare function eyeDropper(options?: EyeDropperOptions): EyeDropperRef;

package/browser/favicon/index.d.ts

@@ -0,0 +1,39 @@
+import { type Signal } from '@angular/core';
+import type { WithInjector } from '@signality/core/types';
+export interface FaviconOptions extends WithInjector {
+    readonly baseUrl?: string;
+}
+export interface FaviconRef {
+    readonly current: Signal<string>;
+    readonly original: Signal<string>;
+    readonly set: (url: string) => void;
+    readonly setEmoji: (emoji: string) => void;
+    readonly reset: () => void;
+}
+/**
+ * Reactive favicon manipulation.
+ * Dynamically change the page favicon based on application state.
+ *
+ * @param options - Optional configuration
+ * @returns A FaviconRef with favicon control methods
+ *
+ * @example
+ * ```typescript
+ * @Component({
+ *   template: `
+ *     <button (click)="setNotification()">Set Notification</button>
+ *     <button (click)="fav.reset()">Reset Favicon</button>
+ *     <p>Current: {{ fav.current() }}</p>
+ *   `
+ * })
+ * class FaviconComponent {
+ *   readonly fav = favicon();
+ *
+ *   setNotification() {
+ *     this.fav.setEmoji('🔴');
+ *   }
+ * }
+ * ```
+ */
+export declare function favicon(options?: FaviconOptions): FaviconRef;
+export declare const FAVICON: import("@angular/core").ProviderToken<FaviconRef>;

package/browser/fps/index.d.ts

@@ -0,0 +1,46 @@
+import { type Signal } from '@angular/core';
+import type { WithInjector } from '@signality/core/types';
+export interface FpsOptions extends WithInjector {
+    /**
+     * Start monitoring immediately.
+     * @default true
+     */
+    readonly immediate?: boolean;
+    /**
+     * Number of frames to average.
+     * @default 60
+     */
+    readonly sampleSize?: number;
+}
+export interface FpsRef {
+    /** Current frames per second */
+    readonly fps: Signal<number>;
+    /** Whether monitoring is active */
+    readonly isRunning: Signal<boolean>;
+    /** Start FPS monitoring */
+    readonly start: () => void;
+    /** Stop FPS monitoring */
+    readonly stop: () => void;
+}
+/**
+ * Reactive FPS monitor using requestAnimationFrame.
+ *
+ * @param options - Configuration options
+ * @returns An FpsRef with fps signal and control methods
+ *
+ * @example
+ * ```typescript
+ * @Component({
+ *   template: `
+ *     <p>FPS: {{ fpsMonitor.fps() }}</p>
+ *     <button (click)="fpsMonitor.stop()">Stop</button>
+ *     <button (click)="fpsMonitor.start()">Start</button>
+ *   `
+ * })
+ * class FpsComponent {
+ *   readonly fpsMonitor = fps();
+ * }
+ * ```
+ */
+export declare function fps(options?: FpsOptions): FpsRef;
+export declare const FPS: import("@angular/core").ProviderToken<FpsRef>;

package/browser/gamepad/index.d.ts

@@ -0,0 +1,28 @@
+import { type Signal } from '@angular/core';
+import type { WithInjector } from '@signality/core/types';
+export interface GamepadRef {
+    /** Whether Gamepad API is supported */
+    readonly isSupported: Signal<boolean>;
+    /** Array of connected gamepads */
+    readonly gamepads: Signal<(Gamepad | null)[]>;
+    /** First connected gamepad */
+    readonly activeGamepad: Signal<Gamepad | undefined>;
+    /** Axes values of active gamepad */
+    readonly axes: Signal<readonly number[]>;
+    /** Button states of active gamepad */
+    readonly buttons: Signal<readonly GamepadButton[]>;
+}
+/**
+ * Signal-based wrapper around the 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) { ... }
+ * ```
+ */
+export declare function gamepad(options?: WithInjector): GamepadRef;

package/browser/geolocation/index.d.ts

@@ -0,0 +1,64 @@
+import { type Signal } from '@angular/core';
+import type { WithInjector } from '@signality/core/types';
+export interface GeolocationOptions extends WithInjector {
+    /**
+     * Start tracking immediately.
+     * @default true
+     */
+    readonly immediate?: boolean;
+    /**
+     * Use GPS for better accuracy.
+     * @default true
+     */
+    readonly enableHighAccuracy?: boolean;
+    /**
+     * Max age of cached position (ms).
+     * @default 0
+     */
+    readonly maximumAge?: number;
+    /**
+     * Request timeout (ms).
+     * @default Infinity
+     */
+    readonly timeout?: number;
+}
+export interface GeolocationRef {
+    /** Whether Geolocation is supported */
+    readonly isSupported: Signal<boolean>;
+    /** Full position object with timestamp */
+    readonly position: Signal<GeolocationPosition | null>;
+    /** Last error */
+    readonly error: Signal<GeolocationPositionError | null>;
+    /** Whether location tracking is currently active */
+    readonly isActive: Signal<boolean>;
+    /** Whether currently fetching location */
+    readonly isLoading: Signal<boolean>;
+    /** Start/resume watching position */
+    readonly start: () => void;
+    /** Stop watching position */
+    readonly stop: () => void;
+}
+/**
+ * Signal-based wrapper around the [Geolocation API](https://developer.mozilla.org/en-US/docs/Web/API/Geolocation_API).
+ *
+ * @param options - Configuration options
+ * @returns A GeolocationRef with location signals and control methods
+ *
+ * @example
+ * ```typescript
+ * @Component({
+ *   template: `
+ *     @if (geo.isLoading()) {
+ *       <p>Getting your location...</p>
+ *     } @else if (geo.position()?.coords; as coords) {
+ *       <p>{{ coords.latitude }}, {{ coords.longitude }}</p>
+ *     }
+ *     <button (click)="geo.stop()">Stop</button>
+ *     <button (click)="geo.start()">Start</button>
+ * })
+ * class LocationComponent {
+ *   readonly geo = geolocation();
+ * }
+ * ```
+ */
+export declare function geolocation(options?: GeolocationOptions): GeolocationRef;

package/browser/index.d.ts

@@ -0,0 +1,29 @@
+export * from '@signality/core/browser/battery';
+export * from '@signality/core/browser/bluetooth';
+export * from '@signality/core/browser/breakpoints';
+export * from '@signality/core/browser/broadcast-channel';
+export * from '@signality/core/browser/browser-language';
+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/favicon';
+export * from '@signality/core/browser/fps';
+export * from '@signality/core/browser/gamepad';
+export * from '@signality/core/browser/geolocation';
+export * from '@signality/core/browser/input-modality';
+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/page-visibility';
+export * from '@signality/core/browser/picture-in-picture';
+export * from '@signality/core/browser/web-share';
+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/vibration';
+export * from '@signality/core/browser/wake-lock';
+export * from '@signality/core/browser/web-notification';
+export * from '@signality/core/browser/web-worker';