@signality/core 0.0.1-alpha.2

package/internal/providers/index.d.ts

@@ -0,0 +1,3 @@
+export * from './is-browser';
+export * from './is-mobile';
+export * from './is-server';

package/internal/providers/is-browser.d.ts

@@ -0,0 +1,2 @@
+import { InjectionToken } from '@angular/core';
+export declare const IS_BROWSER: InjectionToken<boolean>;

package/internal/providers/is-mobile.d.ts

@@ -0,0 +1,2 @@
+import { InjectionToken } from '@angular/core';
+export declare const IS_MOBILE: InjectionToken<boolean>;

package/internal/providers/is-server.d.ts

@@ -0,0 +1,2 @@
+import { InjectionToken } from '@angular/core';
+export declare const IS_SERVER: InjectionToken<boolean>;

package/internal/types/index.d.ts

@@ -0,0 +1,2 @@
+export * from './timer';
+export * from './union';

package/internal/types/timer.d.ts

@@ -0,0 +1 @@
+export type Timer = ReturnType<typeof setTimeout> | undefined;

package/internal/types/union.d.ts

@@ -0,0 +1 @@
+export type Union<T, U> = T | (U & {});

package/internal/utils/bom/index.d.ts

@@ -0,0 +1 @@
+export * from './is-window';

package/internal/utils/bom/is-window.d.ts

@@ -0,0 +1 @@
+export declare function isWindow(obj: object | null): obj is Window;

package/internal/utils/const-signal.d.ts

@@ -0,0 +1,10 @@
+import type { Signal } from '@angular/core';
+/***
+ * Creates a lightweight, readonly signal.
+ * This is primarily used to provide fallback values for states that cannot be
+ * computed in the current environment. For example:
+ * - During SSR where browser-only APIs are unavailable
+ * - In environments that lack support for specific APIs
+ * @internal
+ */
+export declare function constSignal<T>(value: T): Signal<T>;

package/internal/utils/context.d.ts

@@ -0,0 +1,18 @@
+import { type Injector } from '@angular/core';
+export interface ContextRef {
+    readonly injector: Injector;
+    readonly isServer: boolean;
+    readonly isBrowser: boolean;
+    readonly isMobile: boolean;
+    readonly onCleanup: (cleanupFn: () => void) => void;
+}
+export interface SetupContextRef {
+    runInContext<T>(fn: (context: ContextRef) => T): T;
+}
+/**
+ * @internal
+ *
+ * @param injector - injector to use for context
+ * @param debugFn - context owner function
+ */
+export declare function setupContext(injector?: Injector, debugFn?: (...args: any[]) => any): SetupContextRef;

package/internal/utils/create-token.d.ts

@@ -0,0 +1,8 @@
+import { InjectionToken, type ProviderToken } from '@angular/core';
+/**
+ * Creates an Angular InjectionToken with a factory function.
+ * @internal
+ */
+export declare function createToken<T>(factory: () => T, providedIn?: ProvidedIn): ProviderToken<T>;
+type ProvidedIn = NonNullable<ConstructorParameters<typeof InjectionToken>[1]>['providedIn'];
+export {};

package/internal/utils/dom/get-active-element.d.ts

@@ -0,0 +1 @@
+export declare function getActiveElement(document: Document): Element | null;

package/internal/utils/dom/get-event-target.d.ts

@@ -0,0 +1 @@
+export declare function getEventTarget<T extends EventTarget>(event: Event): T | null;

package/internal/utils/dom/get-pip-element.d.ts

@@ -0,0 +1 @@
+export declare function getPipElement(document: Document): Element | null;

package/internal/utils/dom/get-shadow-root.d.ts

@@ -0,0 +1 @@
+export declare function getShadowRoot(element: Element | null): ShadowRoot | null;

package/internal/utils/dom/index.d.ts

@@ -0,0 +1,6 @@
+export * from './get-active-element';
+export * from './get-event-target';
+export * from './get-pip-element';
+export * from './get-shadow-root';
+export * from './is-element';
+export * from './is-node-within';

package/internal/utils/dom/is-element.d.ts

@@ -0,0 +1 @@
+export declare function isElement(obj: Element | EventTarget | Node | object | null): obj is Element;

package/internal/utils/dom/is-node-within.d.ts

@@ -0,0 +1 @@
+export declare function isNodeWithin(node: Node, root: Element): boolean;

package/internal/utils/index.d.ts

@@ -0,0 +1,10 @@
+export * from './bom';
+export * from './dom';
+export * from './context';
+export * from './create-token';
+export * from './is-query-signal';
+export * from './is-plain-object';
+export * from './const-signal';
+export * from './proxy-signal';
+export * from './to-element';
+export * from './to-value';

package/internal/utils/is-plain-object.d.ts

@@ -0,0 +1 @@
+export declare function isPlainObject(value: unknown): value is Record<PropertyKey, unknown>;

package/internal/utils/is-query-signal.d.ts

@@ -0,0 +1,10 @@
+import { type Signal } from '@angular/core';
+/**
+ * Determines if a signal is a query signal (viewChild, contentChild).
+ * Query signals have a special internal structure with a `_dirtyCounter` property that tracks
+ * when query results change.
+
+ * See: https://github.com/angular/angular/blob/main/packages/core/src/render3/queries/query_reactive.ts#L43
+ * @internal
+ */
+export declare function isQuerySignal(val: unknown): val is Signal<unknown>;

package/internal/utils/proxy-signal.d.ts

@@ -0,0 +1,18 @@
+import { type Signal, type WritableSignal } from '@angular/core';
+/**
+ * @internal
+ */
+export interface SignalProxyHandler<T> {
+    get?(source: Signal<T>): T;
+    set?(value: T, source: WritableSignal<T>): void;
+}
+/**
+ * Creates a proxy wrapper around a {@link Signal}
+ * @internal
+ */
+export declare function proxySignal<T>(source: Signal<T>, handler: Omit<SignalProxyHandler<T>, 'set'>): Signal<T>;
+/**
+ * Creates a proxy wrapper around a {@link WritableSignal}
+ * @internal
+ */
+export declare function proxySignal<T>(source: WritableSignal<T>, handler: SignalProxyHandler<T>): WritableSignal<T>;

package/internal/utils/to-element.d.ts

@@ -0,0 +1,12 @@
+import { ElementRef, type Signal } from '@angular/core';
+export interface ToElementFn extends ToElementBase {
+    untracked: ToElementBase;
+}
+export interface ToElementBase {
+    <T extends Element>(element: T | ElementRef<T>): T;
+    <T extends Element>(element: Signal<T | ElementRef<T> | null>): T | null;
+    <T extends Element>(element: Signal<T | ElementRef<T> | undefined>): T | undefined;
+    <T extends Element>(element: Signal<T | ElementRef<T> | null | undefined>): T | null | undefined;
+    <T extends Element>(element: T | ElementRef<T> | Signal<T | ElementRef<T> | null | undefined>): T | null | undefined;
+}
+export declare const toElement: ToElementFn;

package/internal/utils/to-value.d.ts

@@ -0,0 +1,6 @@
+import type { MaybeSignal } from '@signality/core/types';
+export interface ToValueFn {
+    <T>(maybeSignal: MaybeSignal<T>): T;
+    untracked: <T>(maybeSignal: MaybeSignal<T>) => T;
+}
+export declare const toValue: ToValueFn;

package/observers/index.d.ts

@@ -0,0 +1,4 @@
+export * from '@signality/core/observers/intersection-observer';
+export * from '@signality/core/observers/mutation-observer';
+export * from '@signality/core/observers/performance-observer';
+export * from '@signality/core/observers/resize-observer';

package/observers/intersection-observer/index.d.ts

@@ -0,0 +1,42 @@
+import { type CreateEffectOptions } from '@angular/core';
+import type { MaybeElementSignal, MaybeSignal } from '@signality/core/types';
+export interface IntersectionObserverInitOptions extends Omit<CreateEffectOptions, 'allowSignalWrites'> {
+    readonly root?: MaybeElementSignal<Element> | Document | null;
+    readonly rootMargin?: MaybeSignal<string>;
+    readonly threshold?: MaybeSignal<number | number[]>;
+}
+export interface IntersectionObserverRef {
+    readonly destroy: () => void;
+}
+/**
+ * Low-level utility for observing element intersection with viewport using the [Intersection Observer API](https://developer.mozilla.org/en-US/docs/Web/API/Intersection_Observer_API).
+ * Provides fine-grained control over the observation lifecycle.
+ *
+ * @param target - Element(s) to observe
+ * @param callback - Callback function called when intersection changes
+ * @param options - Optional configuration (see {@link IntersectionObserverInitOptions})
+ * @returns An IntersectionObserverRef with a `destroy()` method to stop observing the element(s)
+ *
+ * @example
+ * ```typescript
+ * @Component({
+ *   template: `
+ *     <div #section>Section content</div>
+ *     @if (isVisible()) {
+ *       <p>Section is visible!</p>
+ *     }
+ *   `
+ * })
+ * class IntersectionComponent {
+ *   readonly section = viewChild<ElementRef>('section');
+ *   readonly isVisible = signal(false);
+ *
+ *   constructor() {
+ *     intersectionObserver(this.section, entries => {
+ *       this.isVisible.set(entries[0].isIntersecting);
+ *     }, { threshold: 0.5 });
+ *   }
+ * }
+ * ```
+ */
+export declare function intersectionObserver(target: MaybeElementSignal<Element> | MaybeElementSignal<Element>[], callback: (entries: readonly IntersectionObserverEntry[], observer: IntersectionObserver) => void, options?: IntersectionObserverInitOptions): IntersectionObserverRef;

package/observers/mutation-observer/index.d.ts

@@ -0,0 +1,45 @@
+import { type CreateEffectOptions } from '@angular/core';
+import type { MaybeElementSignal, MaybeSignal } from '@signality/core/types';
+export interface MutationObserverInitOptions extends Omit<CreateEffectOptions, 'allowSignalWrites'> {
+    readonly childList?: MaybeSignal<boolean>;
+    readonly attributes?: MaybeSignal<boolean>;
+    readonly characterData?: MaybeSignal<boolean>;
+    readonly subtree?: MaybeSignal<boolean>;
+    readonly attributeOldValue?: MaybeSignal<boolean>;
+    readonly characterDataOldValue?: MaybeSignal<boolean>;
+    readonly attributeFilter?: MaybeSignal<string[]>;
+}
+export interface MutationObserverRef {
+    readonly destroy: () => void;
+}
+/**
+ * Low-level utility for observing DOM tree changes using the [MutationObserver API](https://developer.mozilla.org/en-US/docs/Web/API/MutationObserver).
+ * Provides fine-grained control over the observation lifecycle.
+ *
+ * @param target - Element(s) to observe
+ * @param callback - Callback function called when DOM mutations occur
+ * @param options - Optional configuration (see {@link MutationObserverInitOptions})
+ * @returns MutationObserverRef with a `destroy()` method to stop observing the element(s)
+ *
+ * @example
+ * ```typescript
+ * @Component({
+ *   template: `
+ *     <div #container>
+ *       <p>Children: {{ childCount() }}</p>
+ *     </div>
+ *   `
+ * })
+ * class MutationComponent {
+ *   readonly container = viewChild<ElementRef>('container');
+ *   readonly childCount = signal(0);
+ *
+ *   constructor() {
+ *     mutationObserver(this.container, mutations => {
+ *       this.childCount.set(mutations[0].target.childNodes.length);
+ *     }, { childList: true });
+ *   }
+ * }
+ * ```
+ */
+export declare function mutationObserver(target: MaybeElementSignal<Element> | MaybeElementSignal<Element>[], callback: (mutations: readonly MutationRecord[], observer: MutationObserver) => void, options: MutationObserverInitOptions): MutationObserverRef;

package/observers/performance-observer/index.d.ts

@@ -0,0 +1,58 @@
+import { type CreateEffectOptions } from '@angular/core';
+import type { MaybeSignal } from '@signality/core/types';
+export interface PerformanceObserverInitOptions extends Omit<CreateEffectOptions, 'allowSignalWrites'> {
+    readonly entryTypes?: MaybeSignal<string[]>;
+    readonly type?: MaybeSignal<string>;
+    readonly buffered?: MaybeSignal<boolean>;
+}
+export interface PerformanceObserverRef {
+    readonly destroy: () => void;
+}
+/**
+ * Low-level utility for observing performance measurement events using the [Performance Observer API](https://developer.mozilla.org/en-US/docs/Web/API/PerformanceObserver).
+ * Provides reactive access to performance entries as they are recorded in the browser's performance timeline.
+ *
+ * @param callback - Callback function called when performance entries are recorded
+ * @param options - Optional configuration (see {@link PerformanceObserverInitOptions})
+ * @returns PerformanceObserverRef with a `destroy()` method to stop observing
+ *
+ * @example
+ * ```typescript
+ * @Component({
+ *   template: `
+ *     <div>LCP: {{ lcp() }}ms</div>
+ *   `
+ * })
+ * class PerformanceComponent {
+ *   readonly lcp = signal(0);
+ *
+ *   constructor() {
+ *     performanceObserver(entries => {
+ *       const lcpEntry = entries.find(e => e.entryType === 'largest-contentful-paint');
+ *       if (lcpEntry) {
+ *         this.lcp.set(Math.round(lcpEntry.startTime));
+ *       }
+ *     }, { entryTypes: ['largest-contentful-paint'] });
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Track long tasks
+ * performanceObserver(entries => {
+ *   entries.forEach(entry => {
+ *     console.log('Long task:', entry.duration);
+ *   });
+ * }, { entryTypes: ['longtask'] });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Using type (single entry type, legacy API)
+ * performanceObserver(entries => {
+ *   console.log('Navigation timing:', entries[0]);
+ * }, { type: 'navigation', buffered: true });
+ * ```
+ */
+export declare function performanceObserver(callback: PerformanceObserverCallback, options?: PerformanceObserverInitOptions): PerformanceObserverRef;

package/observers/resize-observer/index.d.ts

@@ -0,0 +1,40 @@
+import { type CreateEffectOptions } from '@angular/core';
+import type { MaybeElementSignal, MaybeSignal } from '@signality/core/types';
+export interface ResizeObserverInitOptions extends Omit<CreateEffectOptions, 'allowSignalWrites'> {
+    readonly box?: MaybeSignal<ResizeObserverBoxOptions>;
+}
+export interface ResizeObserverRef {
+    readonly destroy: () => void;
+}
+/**
+ * Low-level utility for observing element size changes using the [ResizeObserver API](https://developer.mozilla.org/en-US/docs/Web/API/ResizeObserver).
+ * Provides fine-grained control over the observation lifecycle.
+ *
+ * @param target - Element(s) to observe
+ * @param callback - Callback function called when element size changes
+ * @param options - Optional configuration (see {@link ResizeObserverInitOptions})
+ * @returns ResizeObserverRef with a `destroy()` method to stop observing the element(s)
+ *
+ * @example
+ * ```typescript
+ * @Component({
+ *   template: `
+ *     <div #resizable>
+ *       Size: {{ size().width }} × {{ size().height }}px
+ *     </div>
+ *   `
+ * })
+ * class ResizeComponent {
+ *   readonly resizable = viewChild<ElementRef>('resizable');
+ *   readonly size = signal({ width: 0, height: 0 });
+ *
+ *   constructor() {
+ *     resizeObserver(this.resizable, entries => {
+ *       const { width, height } = entries[0].contentRect;
+ *       this.size.set({ width, height });
+ *     });
+ *   }
+ * }
+ * ```
+ */
+export declare function resizeObserver(target: MaybeElementSignal<Element> | MaybeElementSignal<Element>[], callback: (entries: readonly ResizeObserverEntry[]) => void, options?: ResizeObserverInitOptions): ResizeObserverRef;