@signality/core 0.0.1-alpha.2

package/browser/vibration/index.d.ts

@@ -0,0 +1,37 @@
+import { type Signal } from '@angular/core';
+import type { MaybeSignal, WithInjector } from '@signality/core/types';
+export interface VibrationOptions extends WithInjector {
+    readonly pattern?: MaybeSignal<number | number[]>;
+}
+export interface VibrationRef {
+    /** Whether Vibration API is supported */
+    readonly isSupported: Signal<boolean>;
+    /** Whether currently vibrating */
+    readonly isVibrating: Signal<boolean>;
+    /** Start vibration */
+    readonly vibrate: (pattern?: number | number[]) => void;
+    /** Stop vibration */
+    readonly stop: () => void;
+}
+/**
+ * Signal-based wrapper around the 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
+ * ```
+ *
+ * @example
+ * ```typescript
+ * const vib = vibration({ pattern: 200 });
+ *
+ * vib.vibrate(); // Uses default 200ms pattern
+ * ```
+ */
+export declare function vibration(options?: VibrationOptions): VibrationRef;

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

@@ -0,0 +1,37 @@
+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 */
+    readonly autoReacquire?: boolean;
+}
+export interface WakeLockRef {
+    /** Whether Screen Wake Lock API is supported */
+    readonly isSupported: Signal<boolean>;
+    /** Whether wake lock is currently active */
+    readonly isActive: Signal<boolean>;
+    /** Current wake lock sentinel */
+    readonly sentinel: Signal<WakeLockSentinel | null>;
+    /** Request a wake lock */
+    readonly request: () => Promise<void>;
+    /** Force request a wake lock (releases existing one first) */
+    readonly forceRequest: () => Promise<void>;
+    /** Release the wake lock */
+    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).
+ *
+ * @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
+ * }
+ * ```
+ */
+export declare function wakeLock(options?: WakeLockOptions): WakeLockRef;

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

@@ -0,0 +1,58 @@
+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.
+     */
+    readonly autoClose?: MaybeSignal<number>;
+}
+export interface WebNotificationRef {
+    /** Whether Notifications API is supported */
+    readonly isSupported: Signal<boolean>;
+    /** Current permission state */
+    readonly permission: Signal<NotificationPermission>;
+    /** Current active notification instance */
+    readonly notification: Signal<Notification | null>;
+    /** Request notification permission */
+    readonly requestPermission: () => Promise<NotificationPermission>;
+    /** Show a notification (auto-closes previous). Per-call options override defaults from constructor. */
+    readonly show: (title: string, options?: NotificationOptions) => Notification | undefined;
+    /** Close the current notification */
+    readonly close: () => void;
+}
+/**
+ * Signal-based wrapper around the Notifications API.
+ *
+ * Tracks the current notification as a signal. Calling `show()` auto-closes
+ * the previous notification. Calling `close()` closes the current one.
+ *
+ * @param options - Optional configuration and default notification options
+ * @returns A WebNotificationRef with notification state and control methods
+ *
+ * @example
+ * ```typescript
+ * @Component({
+ *   template: `
+ *     <button (click)="requestPermission()">Request Permission</button>
+ *     <button (click)="showNotification()" [disabled]="notif.permission() !== 'granted'">
+ *       Show Notification
+ *     </button>
+ *     @if (notif.notification()) {
+ *       <button (click)="notif.close()">Close</button>
+ *     }
+ *   `
+ * })
+ * class NotificationComponent {
+ *   readonly notif = webNotification({ icon: '/icon.png' });
+ *
+ *   async requestPermission() {
+ *     await this.notif.requestPermission();
+ *   }
+ *
+ *   showNotification() {
+ *     this.notif.show('Hello!', { body: 'This is a notification' });
+ *   }
+ * }
+ * ```
+ */
+export declare function webNotification(options?: WebNotificationOptions): WebNotificationRef;

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

@@ -0,0 +1,42 @@
+import { type Signal } from '@angular/core';
+import type { WithInjector } from '@signality/core/types';
+export interface WebShareRef {
+    /** Whether Web Share API is supported */
+    readonly isSupported: Signal<boolean>;
+    /** Whether the share dialog is currently open */
+    readonly isSharing: Signal<boolean>;
+    /** Open the native share dialog */
+    readonly share: (data: ShareData) => Promise<void>;
+    /** Check if data can be shared */
+    readonly canShare: (data?: ShareData) => boolean;
+}
+/**
+ * Signal-based wrapper around the [Web Share API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Share_API).
+ *
+ * @param options - Optional injector for DI context
+ * @returns A WebShareRef with share methods and state signals
+ *
+ * @example
+ * ```typescript
+ * @Component({
+ *   template: `
+ *     @if (webShare.isSupported()) {
+ *       <button (click)="shareContent()" [disabled]="webShare.isSharing()">
+ *         Share This Page
+ *       </button>
+ *     }
+ *   `
+ * })
+ * class WebShareComponent {
+ *   readonly webShare = webShare();
+ *
+ *   async shareContent() {
+ *     await this.webShare.share({
+ *       title: 'Check this out!',
+ *       url: window.location.href,
+ *     });
+ *   }
+ * }
+ * ```
+ */
+export declare function webShare(options?: WithInjector): WebShareRef;

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

@@ -0,0 +1,52 @@
+import { type Signal } from '@angular/core';
+import type { MaybeSignal, WithInjector } from '@signality/core/types';
+export interface WebWorkerOptions extends WithInjector {
+    /**
+     * Worker type.
+     * @default 'classic'
+     */
+    readonly type?: 'classic' | 'module';
+    /**
+     * Credentials mode.
+     */
+    readonly credentials?: RequestCredentials;
+    /**
+     * Worker name for debugging.
+     */
+    readonly name?: string;
+}
+export interface WebWorkerRef<I, O> {
+    /** Last message received from worker */
+    readonly data: Signal<O | undefined>;
+    /** Whether worker is ready */
+    readonly isReady: Signal<boolean>;
+    /** Last error from worker */
+    readonly error: Signal<Error | null>;
+    /** Send message to worker */
+    readonly post: (data: I) => void;
+    /** Terminate the worker */
+    readonly terminate: () => void;
+}
+/**
+ * Signal-based wrapper around the Web Workers API.
+ *
+ * @param url - Worker script URL
+ * @param options - Optional configuration
+ * @returns A WebWorkerRef with data signal and control methods
+ *
+ * @example
+ * ```typescript
+ * @Component({
+ *   template: `
+ *     <button (click)="worker.post(42)">Calculate</button>
+ *     @if (worker.data()) {
+ *       <p>Result: {{ worker.data() }}</p>
+ *     }
+ *   `
+ * })
+ * class WorkerComponent {
+ *   readonly worker = webWorker<number, number>('/workers/calc.js');
+ * }
+ * ```
+ */
+export declare function webWorker<I, O>(url: MaybeSignal<string | URL>, options?: WebWorkerOptions): WebWorkerRef<I, O>;

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

@@ -0,0 +1,27 @@
+import { type CreateSignalOptions, type Signal } from '@angular/core';
+import type { WithInjector } from '@signality/core/types';
+export type ActiveElementOptions = CreateSignalOptions<Element | null> & WithInjector;
+/**
+ * Signal-based wrapper around the [document.activeElement](https://developer.mozilla.org/en-US/docs/Web/API/Document/activeElement) property.
+ *
+ * @param options - Optional configuration including signal options and injector
+ * @returns A signal containing the currently active element, or null
+ *
+ * @example
+ * ```typescript
+ * @Component({
+ *   template: `
+ *     @if (activeEl(); as el) {
+ *       <p>Active element: {{ el.tagName }}</p>
+ *     } @else {
+ *       <p>No element is active</p>
+ *     }
+ *   `
+ * })
+ * class ActiveElementComponent {
+ *   readonly activeEl = activeElement();
+ * }
+ * ```
+ */
+export declare function activeElement(options?: ActiveElementOptions): Signal<Element | null>;
+export declare const ACTIVE_ELEMENT: import("@angular/core").ProviderToken<Signal<Element | null>>;

package/elements/dropzone/index.d.ts

@@ -0,0 +1,61 @@
+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 ['*']
+     */
+    readonly accept?: MaybeSignal<string[]>;
+    /**
+     * Allow multiple files.
+     * @default true
+     */
+    readonly multiple?: MaybeSignal<boolean>;
+    /**
+     * Prevent drops outside the zone.
+     * @default true
+     */
+    readonly preventDocumentDrop?: boolean;
+}
+export interface DropzoneRef {
+    /** Dropped files */
+    readonly files: WritableSignal<File[]>;
+    /** Whether dragging over the zone */
+    readonly isOver: Signal<boolean>;
+    /** Whether any drag is in progress (document-wide) */
+    readonly isDragging: Signal<boolean>;
+}
+/**
+ * Signal-based wrapper around the [HTML Drag and Drop API](https://developer.mozilla.org/en-US/docs/Web/API/HTML_Drag_and_Drop_API).
+ *
+ * @param target - Drop zone element
+ * @param options - Optional configuration
+ * @returns An object with isOver, files, data, and isDragging signals
+ *
+ * @example
+ * ```typescript
+ * @Component({
+ *   template: `
+ *     <div
+ *       #zone
+ *       [class.over]="drop.isOver()"
+ *       [class.dragging]="drop.isDragging()"
+ *     >
+ *       Drop files here
+ *       @if (drop.files().length > 0) {
+ *         <ul>
+ *           @for (file of drop.files(); track file.name) {
+ *             <li>{{ file.name }} ({{ file.size }} bytes)</li>
+ *           }
+ *         </ul>
+ *       }
+ *     </div>
+ *   `
+ * })
+ * class DropzoneComponent {
+ *   readonly zone = viewChild<ElementRef>('zone');
+ *   readonly drop = dropzone(this.zone, { accept: ['image/*'], multiple: true });
+ * }
+ * ```
+ */
+export declare function dropzone(target: MaybeElementSignal<HTMLElement>, options?: DropzoneOptions): DropzoneRef;

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

@@ -0,0 +1,38 @@
+import { type CreateSignalOptions, type Signal } from '@angular/core';
+import type { MaybeElementSignal, WithInjector } from '@signality/core/types';
+export interface ElementFocusOptions extends CreateSignalOptions<boolean>, WithInjector {
+    /**
+     * Track focus using the `:focus-visible` pseudo-class.
+     * The browser uses heuristics to determine when focus should be visually indicated
+     * (e.g., keyboard navigation, programmatic focus, or when the element requires user attention).
+     *
+     * @see {@link https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Selectors/:focus-visible MDN: :focus-visible}
+     * @default false
+     */
+    readonly focusVisible?: boolean;
+}
+/**
+ * Reactive tracking of focus state on an element.
+ * Detects when an element gains or loses focus.
+ *
+ * @param target - The element to track focus state on
+ * @param options - Optional configuration including focusVisible mode and injector
+ * @returns A signal that is `true` when the element has focus
+ *
+ * @example
+ * ```typescript
+ * @Component({
+ *   template: `
+ *     <input #input [class.focused]="isFocused()" />
+ *     @if (isFocused()) {
+ *       <p>Input is focused</p>
+ *     }
+ *   `
+ * })
+ * class FocusComponent {
+ *   readonly input = viewChild<ElementRef>('input');
+ *   readonly isFocused = elementFocus(this.input);
+ * }
+ * ```
+ */
+export declare function elementFocus(target: MaybeElementSignal<HTMLElement>, options?: ElementFocusOptions): Signal<boolean>;

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

@@ -0,0 +1,29 @@
+import { type CreateSignalOptions, type Signal } from '@angular/core';
+import type { MaybeElementSignal, WithInjector } from '@signality/core/types';
+export type ElementFocusWithinOptions = CreateSignalOptions<boolean> & WithInjector;
+/**
+ * Reactive tracking of focus-within state on an element.
+ * Detects when focus is inside an element or any of its descendants,
+ * analogous to the CSS `:focus-within` pseudo-class.
+ *
+ * @param target - The element to track focus-within state on
+ * @param options - Optional configuration including signal options and injector
+ * @returns A signal that is `true` when focus is within the element
+ *
+ * @example
+ * ```typescript
+ * @Component({
+ *   template: `
+ *     <div #container [class.focused]="isFocusedWithin()">
+ *       <input placeholder="First" />
+ *       <input placeholder="Second" />
+ *     </div>
+ *   `
+ * })
+ * class FocusWithinComponent {
+ *   readonly container = viewChild<ElementRef>('container');
+ *   readonly isFocusedWithin = elementFocusWithin(this.container);
+ * }
+ * ```
+ */
+export declare function elementFocusWithin(target: MaybeElementSignal<HTMLElement>, options?: ElementFocusWithinOptions): Signal<boolean>;

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

@@ -0,0 +1,27 @@
+import { type CreateSignalOptions, type Signal } from '@angular/core';
+import type { MaybeElementSignal, WithInjector } from '@signality/core/types';
+export type ElementHoverOptions = CreateSignalOptions<boolean> & WithInjector;
+/**
+ * Reactive tracking of the hover state on an element.
+ * Detects when the mouse enters or leaves an element.
+ *
+ * @param target - The element to track hover state on
+ * @param options - Optional configuration including signal options and injector
+ * @returns A signal that is `true` when the element is being hovered
+ *
+ * @example
+ * ```typescript
+ * @Component({
+ *   template: `
+ *     <div #box [class.hovered]="isHovered()">
+ *       Hover over me!
+ *     </div>
+ *   `
+ * })
+ * class HoverComponent {
+ *   readonly box = viewChild<ElementRef>('box');
+ *   readonly isHovered = elementHover(this.box);
+ * }
+ * ```
+ */
+export declare function elementHover(target: MaybeElementSignal<HTMLElement>, options?: ElementHoverOptions): Signal<boolean>;

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

@@ -0,0 +1,40 @@
+import { type CreateSignalOptions, type Signal } from '@angular/core';
+import type { MaybeElementSignal, MaybeSignal, WithInjector } from '@signality/core/types';
+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>;
+}
+/**
+ * Signal-based wrapper around the [ResizeObserver API](https://developer.mozilla.org/en-US/docs/Web/API/ResizeObserver).
+ *
+ * @param target - The element to observe
+ * @param options - Optional configuration including signal options (equal, debugName), box model, and injector
+ * @returns A signal containing the current element dimensions
+ *
+ * @example
+ * ```typescript
+ * @Component({
+ *   template: `
+ *     <div #box>
+ *       Size: {{ size().width }} × {{ size().height }}px
+ *     </div>
+ *   `
+ * })
+ * class SizeComponent {
+ *   readonly box = viewChild<ElementRef>('box');
+ *   readonly size = elementSize(this.box);
+ * }
+ * ```
+ */
+export declare function elementSize(target: MaybeElementSignal<HTMLElement>, options?: ElementSizeOptions): Signal<ElementSizeValue>;

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

@@ -0,0 +1,53 @@
+import { type CreateSignalOptions, type Signal } from '@angular/core';
+import type { MaybeElementSignal, MaybeSignal, WithInjector } from '@signality/core/types';
+export interface ElementVisibilityOptions extends CreateSignalOptions<ElementVisibilityValue>, WithInjector {
+    /**
+     * Visibility threshold(s). A number between 0 and 1, or an array of thresholds.
+     * @default 0
+     */
+    readonly threshold?: MaybeSignal<number | number[]>;
+    /**
+     * Scrollable ancestor element (null = viewport).
+     * @default undefined
+     */
+    readonly root?: MaybeElementSignal<Element> | Document;
+    /**
+     * Margin around the root element.
+     * @default '0px'
+     */
+    readonly rootMargin?: MaybeSignal<string>;
+    /**
+     * Initial value for SSR.
+     * @default { isVisible: true, ratio: 1 }
+     */
+    readonly initialValue?: ElementVisibilityValue;
+}
+export interface ElementVisibilityValue {
+    /** Whether the element is visible in the viewport */
+    readonly isVisible: boolean;
+    /** Intersection ratio (0.0 to 1.0) */
+    readonly ratio: number;
+}
+/**
+ * Signal-based wrapper around the [Intersection Observer API](https://developer.mozilla.org/en-US/docs/Web/API/Intersection_Observer_API).
+ *
+ * @param target - The element to observe
+ * @param options - Optional configuration including signal options (equal, debugName), observer options (threshold, root, rootMargin, initialValue), and injector
+ * @returns A signal containing the current visibility state
+ *
+ * @example
+ * ```typescript
+ * @Component({
+ *   template: `
+ *     <div #section [class.visible]="visibility().isVisible">
+ *       Visibility: {{ visibility().ratio * 100 }}%
+ *     </div>
+ *   `
+ * })
+ * class VisibilityComponent {
+ *   readonly section = viewChild<ElementRef>('section');
+ *   readonly visibility = elementVisibility(this.section);
+ * }
+ * ```
+ */
+export declare function elementVisibility(target: MaybeElementSignal<HTMLElement>, options?: ElementVisibilityOptions): Signal<ElementVisibilityValue>;

package/elements/index.d.ts

@@ -0,0 +1,16 @@
+export * from '@signality/core/elements/active-element';
+export * from '@signality/core/elements/dropzone';
+export * from '@signality/core/elements/element-focus';
+export * from '@signality/core/elements/element-focus-within';
+export * from '@signality/core/elements/element-hover';
+export * from '@signality/core/elements/element-size';
+export * from '@signality/core/elements/element-visibility';
+export * from '@signality/core/elements/on-click-outside';
+export * from '@signality/core/elements/on-long-press';
+export * from '@signality/core/elements/mouse-position';
+export * from '@signality/core/elements/pointer-swipe';
+export * from '@signality/core/elements/on-disconnect';
+export * from '@signality/core/elements/scroll-position';
+export * from '@signality/core/elements/swipe';
+export * from '@signality/core/elements/text-selection';
+export * from '@signality/core/elements/window-size';

package/elements/mouse-position/index.d.ts

@@ -0,0 +1,64 @@
+import { type Signal } from '@angular/core';
+import type { MaybeElementSignal, WithInjector } from '@signality/core/types';
+export interface MousePosition {
+    readonly x: number;
+    readonly y: number;
+}
+export type MouseCoordinateType = 'page' | 'client' | 'screen';
+export interface MousePositionOptions extends WithInjector {
+    /**
+     * Element or window to track mouse position on.
+     * @default window
+     */
+    readonly target?: MaybeElementSignal<Element> | Window;
+    /**
+     * Coordinate type to use.
+     * @default 'page'
+     */
+    readonly type?: MouseCoordinateType;
+    /**
+     * Whether to track touch events as well.
+     * @default true
+     */
+    readonly touch?: boolean;
+    /**
+     * Initial mouse position.
+     */
+    readonly initialValue?: MousePosition;
+}
+/**
+ * Reactive tracking of mouse position.
+ * Track cursor coordinates globally or relative to an element.
+ *
+ * @param options - Optional configuration
+ * @returns A signal containing the current mouse position
+ *
+ * @example
+ * ```typescript
+ * @Component({
+ *   template: `
+ *     <p>Mouse position: X={{ position().x }}, Y={{ position().y }}</p>
+ *   `
+ * })
+ * class MouseTracker {
+ *   readonly position = mousePosition();
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Track mouse position on a specific element
+ * @Component({
+ *   template: `
+ *     <div #box>
+ *       <p>Position: X={{ position().x }}, Y={{ position().y }}</p>
+ *     </div>
+ *   `
+ * })
+ * class MouseElementTracker {
+ *   readonly box = viewChild<ElementRef>('box');
+ *   readonly position = mousePosition({ target: this.box });
+ * }
+ * ```
+ */
+export declare function mousePosition(options?: MousePositionOptions): Signal<MousePosition>;

package/elements/on-click-outside/index.d.ts

@@ -0,0 +1,42 @@
+import type { MaybeElementSignal, WithInjector } from '@signality/core/types';
+export interface OnClickOutsideOptions extends WithInjector {
+    /**
+     * Elements that should not trigger the outside click handler.
+     */
+    readonly ignore?: MaybeElementSignal<Element>[];
+}
+export interface OnClickOutsideRef {
+    /** Stops listening for outside clicks. */
+    readonly destroy: () => void;
+}
+/**
+ * Detects clicks outside a target element and invokes a callback.
+ * Useful for closing dropdowns, modals, and popovers when the user clicks elsewhere.
+ *
+ * @param target - Element to detect clicks outside of
+ * @param handler - Callback invoked when a click outside the target is detected
+ * @param options - Optional configuration including ignore list and injector
+ * @returns An OnClickOutsideRef with a destroy method to stop detection
+ *
+ * @example
+ * ```typescript
+ * @Component({
+ *   template: `
+ *     <div #dropdown class="dropdown">
+ *       <p>Dropdown content</p>
+ *     </div>
+ *   `
+ * })
+ * class DropdownComponent {
+ *   readonly dropdown = viewChild<ElementRef>('dropdown');
+ *   readonly isOpen = signal(true);
+ *
+ *   constructor() {
+ *     onClickOutside(this.dropdown, () => {
+ *       this.isOpen.set(false);
+ *     });
+ *   }
+ * }
+ * ```
+ */
+export declare function onClickOutside(target: MaybeElementSignal<HTMLElement>, handler: (event: PointerEvent | FocusEvent) => void, options?: OnClickOutsideOptions): OnClickOutsideRef;