@radix-ng/primitives 0.51.0 → 1.0.0-beta.1

package/types/radix-ng-primitives-core.d.ts

@@ -1,10 +1,39 @@
 import * as i0 from '@angular/core';
-import { Type, Provider, ElementRef, Injector, InjectionToken, InputSignal, WritableSignal, ModelSignal, Signal, EffectRef, EffectCleanupRegisterFn, CreateEffectOptions } from '@angular/core';
-import { BooleanInput } from '@angular/cdk/coercion';
-import { ControlValueAccessor, FormControlDirective, FormControlName, NgModel } from '@angular/forms';
-import { DateValue, DayOfWeek, CalendarDateTime, ZonedDateTime, Time } from '@internationalized/date';
-import { ConnectionPositionPair, ConnectedPosition } from '@angular/cdk/overlay';
-import { Direction } from '@angular/cdk/bidi';
+import { Type, Provider, InputSignal, WritableSignal, ModelSignal, Signal, InjectionToken, InputSignalWithTransform, OutputRef, ElementRef, Injector, EffectRef, EffectCleanupRegisterFn, CreateEffectOptions } from '@angular/core';
+import { ControlValueAccessor } from '@angular/forms';
+import { DateValue, Time, CalendarDateTime, ZonedDateTime } from '@internationalized/date';
+
+type DataOrientation = 'vertical' | 'horizontal';
+/** Layout direction for bidirectional text. */
+type Direction = 'ltr' | 'rtl';
+/**
+ * Nullable from `Type` adds `null` and `undefined`
+ *
+ * @example ```ts
+ *  // Expect: string | number | undefined | null
+ *  type Value = Nulling<string | number>;
+ * ```
+ */
+type Nullable<Type> = null | Type | undefined;
+/**
+ * SafeFunction is a type for functions that accept any number of arguments of unknown types
+ * and return a value of an unknown type. This is useful when you want to define a function
+ * without being strict about the input or output types, maintaining flexibility.
+ *
+ * @example ```ts
+ *  const safeFn: SafeFunction = (...args) => {
+ *    return args.length > 0 ? args[0] : null;
+ *  };
+ *
+ *  const result = safeFn(1, 'hello'); // result: 1
+ * ```
+ */
+type SafeFunction = (...args: unknown[]) => unknown;
+type AcceptableValue = string | number | bigint | Record<string, any> | null;
+/** Type describing the allowed values for a boolean `input()` using `booleanAttribute` coercion. */
+type BooleanInput = string | boolean | null | undefined;
+/** Type describing the allowed values for a number `input()` using `numberAttribute` coercion. */
+type NumberInput = string | number | null | undefined;
 
 /**
  * A reusable ControlValueAccessor implementation for form controls
@@ -83,20 +112,6 @@ declare function injectControlValueAccessor<T>(): RdxControlValueAccessor<T>;
  */
 declare function provideValueAccessor<T>(type: Type<T>): Provider;
 
-declare class RdxAutoFocusDirective {
-    #private;
-    private _autoSelect;
-    /**
-     * @default false
-     */
-    set autoFocus(value: boolean);
-    set autoSelect(value: boolean);
-    static ɵfac: i0.ɵɵFactoryDeclaration<RdxAutoFocusDirective, never>;
-    static ɵdir: i0.ɵɵDirectiveDeclaration<RdxAutoFocusDirective, "[rdxAutoFocus]", never, { "autoFocus": { "alias": "rdxAutoFocus"; "required": false; }; "autoSelect": { "alias": "autoSelect"; "required": false; }; }, {}, never, never, true, never>;
-    static ngAcceptInputType_autoFocus: unknown;
-    static ngAcceptInputType_autoSelect: unknown;
-}
-
 /**
  * The `clamp` function restricts a number within a specified range by returning the value itself if it
  * falls within the range, or the closest boundary value if it exceeds the range.
@@ -136,141 +151,17 @@ declare function roundToStepPrecision(value: number, step: number): number;
  */
 declare function snapValueToStep(value: number, min: number | undefined, max: number | undefined, step: number): number;
 
-declare function injectDocument(): Document;
-
-declare function elementSize({ elementRef, injector }: {
-    elementRef: ElementRef<HTMLElement>;
-    injector: Injector;
-}): i0.Signal<{
-    width: number;
-    height: number;
-}>;
-
-declare class RdxFocusInitialDirective {
-    /** @ignore */
-    private readonly nativeElement;
-    /** @ignore */
-    focus(): void;
-    static ɵfac: i0.ɵɵFactoryDeclaration<RdxFocusInitialDirective, never>;
-    static ɵdir: i0.ɵɵDirectiveDeclaration<RdxFocusInitialDirective, "[rdxFocusInitial]", never, {}, {}, never, never, true, never>;
-}
-
-declare function getActiveElement(): Element | null;
-
-/** Service that generates unique IDs for DOM nodes. */
-declare class _IdGenerator {
-    private readonly _appId;
-    /**
-     * Generates a unique ID with a specific prefix.
-     * @param prefix Prefix to add to the ID.
-     */
-    getId(prefix: string): string;
-    static ɵfac: i0.ɵɵFactoryDeclaration<_IdGenerator, never>;
-    static ɵprov: i0.ɵɵInjectableDeclaration<_IdGenerator>;
-}
-
-declare function injectNgControl(params: {
-    optional: true;
-}): FormControlDirective | FormControlName | NgModel | undefined;
-declare function injectNgControl(params: {
-    optional: false;
-}): FormControlDirective | FormControlName | NgModel;
-declare function injectNgControl(): FormControlDirective | FormControlName | NgModel;
-
-declare function injectIsClient(): boolean;
-
-/**
- * Compare two objects using reference equality and stable deep hashing.
- * @param {any} object1 First object
- * @param {any} object2 Second object
- * @return {boolean} true if equal and false if not
- */
-declare function isEqual(object1: any, object2: any): boolean;
-
-declare function isInsideForm(el: ElementRef<HTMLElement> | null): boolean;
-
-declare function isNullish(value: any): value is null | undefined;
-
-declare const isNumber: (v: any) => v is number;
-
-/**
- * The function `isValueEqualOrExist` checks if a value is equal to or exists in another value or
- * array.
- * @param {T | T[] | undefined} base - It represents the base value that you want to compare with the `current` value.
- * @param {T | T[] | undefined} current - The `current` parameter represents the current value that you want to compare with the `base` value or values.
- * @returns The `isValueEqualOrExist` function returns a boolean value. It checks if the `base` value
- * is equal to the `current` value or if the `current` value exists within the `base` value. The
- * function handles cases where `base` can be a single value, an array of values, or undefined.
- */
-declare function isValueEqualOrExist<T>(base: T | T[] | undefined, current: T | T[] | undefined): boolean;
-
-declare const ALT = "Alt";
-declare const ARROW_DOWN = "ArrowDown";
-declare const ARROW_LEFT = "ArrowLeft";
-declare const ARROW_RIGHT = "ArrowRight";
-declare const ARROW_UP = "ArrowUp";
-declare const BACKSPACE = "Backspace";
-declare const CAPS_LOCK = "CapsLock";
-declare const CONTROL = "Control";
-declare const DELETE = "Delete";
-declare const END = "End";
-declare const ENTER = "Enter";
-declare const ESCAPE = "Escape";
-declare const F1 = "F1";
-declare const F10 = "F10";
-declare const F11 = "F11";
-declare const F12 = "F12";
-declare const F2 = "F2";
-declare const F3 = "F3";
-declare const F4 = "F4";
-declare const F5 = "F5";
-declare const F6 = "F6";
-declare const F7 = "F7";
-declare const F8 = "F8";
-declare const F9 = "F9";
-declare const HOME = "Home";
-declare const META = "Meta";
-declare const PAGE_DOWN = "PageDown";
-declare const PAGE_UP = "PageUp";
-declare const SHIFT = "Shift";
-declare const SPACE = " ";
-declare const TAB = "Tab";
-declare const CTRL = "Control";
-declare const ASTERISK = "*";
-declare const a = "a";
-declare const P = "P";
-declare const A = "A";
-declare const p = "p";
-declare const n = "n";
-declare const j = "j";
-declare const k = "k";
-declare const SPACE_CODE = "Space";
-
 /**
- * Creates an Angular provider that binds the given token to the existing instance
- * of the specified class. This is especially useful when you want multiple
- * tokens (or interfaces) to resolve to the same directive/component instance.
- *
- * @template T - The type associated with the injection token.
- * @param token - The InjectionToken or abstract type you want to provide.
- * @param type  - The class type whose existing instance will be used for this token.
- * @returns A Provider configuration object for Angular's DI system.
- *
- * @example
- *
- * @Directive({
- *   providers: [
- *     provideToken(RdxToggleGroupToken, RdxToggleGroupDirective),
- *     provideValueAccessor(RdxToggleGroupDirective)
- *   ]
- * })
- * export class RdxToggleGroupDirective {}
+ * Retrieves the context value from Angular's dependency injection.
+ * Overloaded so the non-optional call returns a non-nullable `T` (no `!` needed),
+ * while the optional call may return `null`.
  */
-declare function provideToken<T>(token: InjectionToken<T>, type: Type<unknown>): Provider;
-
-declare const WINDOW: InjectionToken<Window & typeof globalThis>;
-declare function injectWindow(): Window & typeof globalThis;
-
+interface InjectContext<T> {
+    (): T;
+    (optional: false): T;
+    (optional: true): T | null;
+    (optional?: boolean): T | null;
+}
 /**
  * Creates a context with injector and provider functions for a given type
  * @template T The type of the context value
@@ -279,7 +170,7 @@ declare function injectWindow(): Window & typeof globalThis;
  *   - injectContext: Function to retrieve the context value
  *   - provideContext: Function to create a provider for the context
  */
-declare function createContext<T>(description: string): readonly [injectContext: (optional?: boolean) => T | null, provideContext: (useFactory: () => T) => Provider];
+declare function createContext<T>(description: string): readonly [injectContext: InjectContext<T>, provideContext: (useFactory: () => T) => Provider];
 
 declare const DATE_SEGMENT_PARTS: readonly ["day", "month", "year"];
 declare const TIME_SEGMENT_PARTS: readonly ["hour", "minute", "second", "dayPeriod"];
@@ -343,6 +234,7 @@ type DateAndTimeSegmentObj = DateSegmentObj & TimeSegmentObj;
 type SegmentValueObj = DateSegmentObj | DateAndTimeSegmentObj;
 type SegmentContentObj = Record<EditableSegmentPart, string>;
 
+type DayOfWeek = 'sun' | 'mon' | 'tue' | 'wed' | 'thu' | 'fri' | 'sat';
 type CreateMonthProps = {
     /**
      * The date object representing the month's date (usually the first day of the month).
@@ -697,87 +589,237 @@ declare function handleAndDispatchCustomEvent<E extends CustomEvent, OriginalEve
     originalEvent: OriginalEvent;
 } & (E extends CustomEvent<infer D> ? D : never)): void;
 
-declare enum RdxPositionSide {
-    Top = "top",
-    Right = "right",
-    Bottom = "bottom",
-    Left = "left"
+/**
+ * Generates unique, SSR-stable IDs for DOM nodes.
+ *
+ * IDs are deterministic per prefix (a monotonic counter) so the server and the client produce the
+ * same sequence and hydration does not mismatch. The application's `APP_ID` is folded into the
+ * prefix so multiple Angular apps on one page don't collide; the default `ng` app id is omitted to
+ * keep IDs short for the common single-app case.
+ *
+ * Prefer the {@link injectId} hook at call sites; inject this service directly only when you need to
+ * generate IDs lazily outside an injection context.
+ */
+declare class RdxIdGenerator {
+    private readonly appId;
+    /** Generates a unique ID with the given prefix. */
+    getId(prefix: string): string;
+    static ɵfac: i0.ɵɵFactoryDeclaration<RdxIdGenerator, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<RdxIdGenerator>;
 }
-declare enum RdxPositionAlign {
-    Start = "start",
-    Center = "center",
-    End = "end"
+/**
+ * Returns a unique, SSR-stable ID for the given prefix — the Angular counterpart of React's
+ * `useId`. Must be called in an injection context (e.g. a field initializer or constructor).
+ *
+ * @example
+ * readonly contentId = injectId('rdx-dialog-content-');
+ */
+declare function injectId(prefix: string): string;
+
+declare const ALT = "Alt";
+declare const ARROW_DOWN = "ArrowDown";
+declare const ARROW_LEFT = "ArrowLeft";
+declare const ARROW_RIGHT = "ArrowRight";
+declare const ARROW_UP = "ArrowUp";
+declare const BACKSPACE = "Backspace";
+declare const CAPS_LOCK = "CapsLock";
+declare const CONTROL = "Control";
+declare const DELETE = "Delete";
+declare const END = "End";
+declare const ENTER = "Enter";
+declare const ESCAPE = "Escape";
+declare const F1 = "F1";
+declare const F10 = "F10";
+declare const F11 = "F11";
+declare const F12 = "F12";
+declare const F2 = "F2";
+declare const F3 = "F3";
+declare const F4 = "F4";
+declare const F5 = "F5";
+declare const F6 = "F6";
+declare const F7 = "F7";
+declare const F8 = "F8";
+declare const F9 = "F9";
+declare const HOME = "Home";
+declare const META = "Meta";
+declare const PAGE_DOWN = "PageDown";
+declare const PAGE_UP = "PageUp";
+declare const SHIFT = "Shift";
+declare const SPACE = " ";
+declare const TAB = "Tab";
+declare const CTRL = "Control";
+declare const ASTERISK = "*";
+declare const a = "a";
+declare const P = "P";
+declare const A = "A";
+declare const p = "p";
+declare const n = "n";
+declare const j = "j";
+declare const k = "k";
+declare const SPACE_CODE = "Space";
+
+type AriaLivePoliteness = 'off' | 'polite' | 'assertive';
+/**
+ * Announces messages to screen readers through an `aria-live` region, without moving focus.
+ *
+ * Own replacement for CDK's `LiveAnnouncer` — lazily appends a visually hidden live region to
+ * the document body and writes messages into it. No-op on the server.
+ */
+declare class RdxLiveAnnouncer {
+    private readonly document;
+    private readonly isBrowser;
+    private liveElement;
+    private previousTimeout;
+    constructor();
+    /**
+     * Announces a message to screen readers.
+     *
+     * @param message The message to announce.
+     * @param politeness The politeness of the announcer element (defaults to `'polite'`).
+     * @param duration If provided, the message is cleared after this many milliseconds.
+     */
+    announce(message: string, politeness?: AriaLivePoliteness, duration?: number): void;
+    /** Clears the current announcement. */
+    clear(): void;
+    private getLiveElement;
+    static ɵfac: i0.ɵɵFactoryDeclaration<RdxLiveAnnouncer, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<RdxLiveAnnouncer>;
 }
-type RdxPositionSideAndAlign = {
-    side: RdxPositionSide;
-    align: RdxPositionAlign;
-};
-type RdxPositionSideAndAlignOffsets = {
-    sideOffset: number;
-    alignOffset: number;
-};
-type RdxPositions = Readonly<{
-    [key in RdxPositionSide]: Readonly<{
-        [key in RdxPositionAlign]: Readonly<ConnectionPositionPair>;
-    }>;
-}>;
-type RdxPositioningDefaults = Readonly<{
-    offsets: Readonly<{
-        side: number;
-        align: number;
-    }>;
-    arrow: Readonly<{
-        width: number;
-        height: number;
-    }>;
-}>;
-type RdxAllPossibleConnectedPositions = ReadonlyMap<`${RdxPositionSide}|${RdxPositionAlign}`, ConnectionPositionPair>;
-type RdxArrowPositionParams = {
-    top: string;
-    left: string;
-    transform: string;
-    transformOrigin: string;
-};
 
-declare const RDX_POSITIONS: RdxPositions;
-declare const RDX_POSITIONING_DEFAULTS: RdxPositioningDefaults;
+/** Narrows to `null | undefined`. */
+declare function isNullish(value: any): value is null | undefined;
+/**
+ * Structural equality for the value shapes a primitive can hold: primitives (incl. `NaN`), arrays,
+ * plain objects, and the common built-ins `Date`, `RegExp`, `Map`, and `Set`. Reference cycles are
+ * handled. Other opaque objects (e.g. class instances with no own enumerable properties) fall back
+ * to per-key comparison and so only match when they expose equal enumerable state.
+ */
+declare function isEqual(a: any, b: any): boolean;
 
-declare function getContentPosition(sideAndAlignWithOffsets: RdxPositionSideAndAlign & RdxPositionSideAndAlignOffsets): ConnectedPosition;
-declare function getAllPossibleConnectedPositions(): RdxAllPossibleConnectedPositions;
-declare function getSideAndAlignFromAllPossibleConnectedPositions(position: ConnectionPositionPair): RdxPositionSideAndAlign;
-declare function getArrowPositionParams(sideAndAlign: RdxPositionSideAndAlign, arrowWidthAndHeight: {
-    width: number;
-    height: number;
-}, triggerWidthAndHeight: {
+/**
+ * Creates an Angular provider that binds the given token to the existing instance
+ * of the specified class. This is especially useful when you want multiple
+ * tokens (or interfaces) to resolve to the same directive/component instance.
+ *
+ * @template T - The type associated with the injection token.
+ * @param token - The InjectionToken or abstract type you want to provide.
+ * @param type  - The class type whose existing instance will be used for this token.
+ * @returns A Provider configuration object for Angular's DI system.
+ *
+ * @example
+ *
+ * @Directive({
+ *   providers: [
+ *     provideToken(RdxFooToken, RdxFooDirective),
+ *     provideValueAccessor(RdxFooDirective)
+ *   ]
+ * })
+ * export class RdxFooDirective {}
+ */
+declare function provideToken<T>(token: InjectionToken<T>, type: Type<unknown>): Provider;
+
+/**
+ * Local mirror of Angular Signal Forms' control contracts
+ * (`@angular/forms/signals`, stable in Angular 22).
+ *
+ * These interfaces intentionally do **not** import from `@angular/forms/signals`
+ * so primitives can declare `implements RdxFormValueControl<T>` /
+ * `implements RdxFormCheckboxControl` while the library baseline is still on
+ * Angular 21, where the real API is experimental. They mirror Angular's contract
+ * closely enough to lock the public surface (the required `value` / `checked`
+ * signal) and catch naming regressions on CI — e.g. a rewrite renaming
+ * `value` → `modelValue` (as the slider once had) would no longer type-check.
+ *
+ * Optional state types are widened only where Radix NG controls legitimately
+ * differ from Angular's exact types (e.g. `input<string>()` produces
+ * `string | undefined`, and boolean inputs carry a coercion transform).
+ *
+ * Replace with the real imports once the baseline moves to Angular 22.
+ * See `.claude/skills/project-knowledge/references/signal-forms-readiness.md`.
+ */
+/** An optional control-state member exposed as an Angular input signal (with or without a coercion transform). */
+type RdxFormStateInput<T> = InputSignal<T> | InputSignalWithTransform<T, any>;
+/**
+ * Minimal stand-in for Angular's `ValidationError`. The real type is a tagged
+ * union (`RequiredValidationError`, `PatternValidationError`, …); this keeps a
+ * shared shape until the v22 type is available.
+ */
+interface RdxValidationError {
+    readonly kind: string;
+    readonly message?: string;
+}
+/** Optional state shared by value and checkbox controls (mirror of Angular's `FormUiControl`). */
+interface RdxFormUiControl {
+    readonly disabled?: RdxFormStateInput<boolean>;
+    readonly readonly?: RdxFormStateInput<boolean>;
+    readonly required?: RdxFormStateInput<boolean>;
+    readonly invalid?: RdxFormStateInput<boolean>;
+    readonly hidden?: RdxFormStateInput<boolean>;
+    readonly pending?: RdxFormStateInput<boolean>;
+    readonly touched?: RdxFormStateInput<boolean>;
+    readonly dirty?: RdxFormStateInput<boolean>;
+    readonly name?: RdxFormStateInput<string | undefined>;
+    readonly errors?: RdxFormStateInput<readonly RdxValidationError[]>;
+    readonly minLength?: RdxFormStateInput<number | undefined>;
+    readonly maxLength?: RdxFormStateInput<number | undefined>;
+    readonly pattern?: RdxFormStateInput<readonly RegExp[]>;
+    /** Notifies the form that the control was touched (mirror of Angular's `touch` output). */
+    readonly touch?: OutputRef<void>;
+}
+/**
+ * Mirror of `FormValueControl<TValue>` — a control that edits a single value via
+ * `value = model<TValue>()`. It must **not** expose `checked`.
+ */
+interface RdxFormValueControl<TValue> extends RdxFormUiControl {
+    readonly value: ModelSignal<TValue>;
+    readonly checked?: undefined;
+    readonly min?: RdxFormStateInput<NonNullable<TValue> | undefined>;
+    readonly max?: RdxFormStateInput<NonNullable<TValue> | undefined>;
+}
+/**
+ * Mirror of `FormCheckboxControl` — a control that toggles via
+ * `checked = model<boolean>()`. It must **not** expose `value`.
+ */
+interface RdxFormCheckboxControl extends RdxFormUiControl {
+    readonly checked: ModelSignal<boolean>;
+    readonly value?: undefined;
+}
+
+declare function injectDocument(): Document;
+
+declare function elementSize({ elementRef, injector }: {
+    elementRef: ElementRef<HTMLElement>;
+    injector: Injector;
+}): i0.Signal<{
     width: number;
     height: number;
-}): RdxArrowPositionParams;
+}>;
+
+declare function getActiveElement(): Element | null;
 
-type DataOrientation = 'vertical' | 'horizontal';
 /**
- * Nullable from `Type` adds `null` and `undefined`
+ * Creates a resize observer effect for element
  *
- * @example ```ts
- *  // Expect: string | number | undefined | null
- *  type Value = Nulling<string | number>;
- * ```
+ * @param options Configuration options
+ * @param options.injector Angular injector
+ * @param options.element Signal returning the element to observe
+ * @param options.onResize Callback when element is resized
+ * @returns EffectRef that can be destroyed when needed
  */
-type Nullable<Type> = null | Type | undefined;
+declare function resizeEffect(options: {
+    injector: Injector;
+    element: Signal<ElementRef | HTMLElement | null | undefined>;
+    onResize: ResizeObserverCallback;
+}): EffectRef;
+
 /**
- * SafeFunction is a type for functions that accept any number of arguments of unknown types
- * and return a value of an unknown type. This is useful when you want to define a function
- * without being strict about the input or output types, maintaining flexibility.
- *
- * @example ```ts
- *  const safeFn: SafeFunction = (...args) => {
- *    return args.length > 0 ? args[0] : null;
- *  };
+ * Locks `document.body` scrolling while `active()` is `true`, and restores the original overflow
+ * when it becomes `false` or the calling context is destroyed.
  *
- *  const result = safeFn(1, 'hello'); // result: 1
- * ```
+ * Lock ownership is shared across all callers via a single module-level counter, so nested or
+ * concurrent overlays compose correctly. Must be called in an injection context.
  */
-type SafeFunction = (...args: unknown[]) => unknown;
-type AcceptableValue = string | number | bigint | Record<string, any> | null;
+declare function useScrollLock(active: Signal<boolean>): void;
 
 type ArrowKeyOptions = 'horizontal' | 'vertical' | 'both';
 interface ArrowNavigationOptions {
@@ -844,19 +886,75 @@ interface ArrowNavigationOptions {
 declare function useArrowNavigation(e: KeyboardEvent, currentElement: HTMLElement, parentElement: HTMLElement | undefined, options?: ArrowNavigationOptions): HTMLElement | null;
 
 /**
- * Creates a resize observer effect for element
+ * Keeps hover content open while the pointer crosses the gap between a trigger and a popup.
+ */
+declare function useGraceArea(triggerEl: Signal<HTMLElement | null | undefined>, containerEl: Signal<HTMLElement | null | undefined>, resetMs?: number): {
+    isPointerInTransit: Signal<boolean>;
+    onPointerExit: (callback: (value: void) => void) => () => void;
+};
+
+interface RdxPointerDragHandlers {
+    /** Whether a press may begin a drag (e.g. enabled, not on an opt-out element, at a scroll edge). */
+    canStart: (event: PointerEvent) => boolean;
+    /** A drag actually began (the pointer moved past the start threshold). */
+    onStart: (event: PointerEvent) => void;
+    /** Pointer moved during a drag. Return `false` to end the gesture early (treated as not committed). */
+    onMove: (event: PointerEvent) => void | boolean;
+    /** The drag ended. `committed` is true only for a normal `pointerup`, false for cancel/lost-capture/early-stop. */
+    onEnd: (event: PointerEvent, committed: boolean) => void;
+}
+/**
+ * Shared pointer-drag lifecycle for gesture primitives (drawer swipe, toast swipe, etc.).
  *
- * @param options Configuration options
- * @param options.injector Angular injector
- * @param options.element Signal returning the element to observe
- * @param options.onResize Callback when element is resized
- * @returns EffectRef that can be destroyed when needed
+ * A press only becomes a drag once the pointer moves past {@link DRAG_THRESHOLD}; until then it is a
+ * plain tap, so clicks on buttons inside the element keep working (the gesture never captures the
+ * pointer for a tap). Once dragging, the pointer is captured so a drag that leaves the element still
+ * completes, and `lostpointercapture` / `pointercancel` count as a non-committed end — a swallowed
+ * `pointerup` (native context menu, OS gesture, tab switch) can never wedge the gesture. Only the
+ * primary pointer is tracked, so a second finger can't start a parallel gesture. No-op outside the
+ * browser, keeping SSR safe.
+ *
+ * `onEnd` is NOT called if the host is destroyed mid-drag — callers that pair `onStart`/`onEnd`
+ * (e.g. to pause/resume timers) should balance that case in their own `DestroyRef` cleanup.
+ *
+ * Must be called from an injection context (a directive/component constructor).
  */
-declare function resizeEffect(options: {
-    injector: Injector;
-    element: Signal<ElementRef | HTMLElement | null | undefined>;
-    onResize: ResizeObserverCallback;
-}): EffectRef;
+declare function usePointerDrag(handlers: RdxPointerDragHandlers): void;
+
+/**
+ * Lifecycle phase of an open/close transition.
+ *
+ * - `'starting'` — the part has just mounted/opened; the enter animation is about to run.
+ * - `'ending'`   — the part is closing; the exit animation is running.
+ * - `undefined`  — settled (no transition in progress).
+ */
+type RdxTransitionStatus = 'starting' | 'ending' | undefined;
+interface RdxTransitionStatusRef {
+    /** Reactive transition phase, intended for `data-starting-style` / `data-ending-style` bindings. */
+    readonly status: Signal<RdxTransitionStatus>;
+    /**
+     * Registers the element whose CSS transition/animation duration determines when the close
+     * transition is considered complete. Returns a cleanup that unregisters it.
+     */
+    registerElement: (element: HTMLElement) => () => void;
+    /** Drives a new transition for the given open state. Cancels any in-flight transition. */
+    start: (open: boolean) => void;
+}
+/**
+ * Shared open/close transition state machine used by overlay primitives (dialog, popover, …).
+ *
+ * On `start(open)` it flips `status` to `'starting'`/`'ending'`, then — after the next render and
+ * (for opening) one animation frame — clears it and waits for the registered element's running CSS
+ * animations/transitions to finish (via the Web Animations API) before invoking `onComplete(open)`.
+ * Completing on the real `animationend` rather than a duration timer keeps it from firing a frame
+ * late. A duration-based timer remains as a safety net, and if no element is registered or it has no
+ * animation (also SSR / jsdom, where computed durations are `0`) completion is synchronous.
+ *
+ * Must be called in an injection context (uses {@link Injector} and {@link DestroyRef}).
+ */
+declare function useTransitionStatus(onComplete: (open: boolean) => void): RdxTransitionStatusRef;
+/** Longest of an element's CSS transition / animation durations (including delays), in milliseconds. */
+declare function getMaxTransitionDuration(element: HTMLElement): number;
 
 /**
  * We want to have the Tuple in order to use the types in the function signature
@@ -898,5 +996,17 @@ declare interface CreateExplicitEffectOptions extends CreateEffectOptions {
  */
 declare function watch<Input extends readonly unknown[], Params = Input>(deps: readonly [...ExplicitEffectValues<Input>], fn: (deps: Params, onCleanup: EffectCleanupRegisterFn) => void, options?: CreateExplicitEffectOptions | undefined): EffectRef;
 
-export { A, ALT, ARROW_DOWN, ARROW_LEFT, ARROW_RIGHT, ARROW_UP, ASTERISK, BACKSPACE, CAPS_LOCK, CONTROL, CTRL, DELETE, END, ENTER, ESCAPE, F1, F10, F11, F12, F2, F3, F4, F5, F6, F7, F8, F9, HOME, META, P, PAGE_DOWN, PAGE_UP, RDX_POSITIONING_DEFAULTS, RDX_POSITIONS, RdxAutoFocusDirective, RdxControlValueAccessor, RdxFocusInitialDirective, RdxPositionAlign, RdxPositionSide, SHIFT, SPACE, SPACE_CODE, TAB, WINDOW, _IdGenerator, a, areAllDaysBetweenValid, clamp, createContent, createContext, createFormatter, createMonth, createMonths, elementSize, getActiveElement, getAllPossibleConnectedPositions, getArrowPositionParams, getContentPosition, getDaysBetween, getDaysInMonth, getDefaultDate, getDefaultTime, getLastFirstDayOfWeek, getNextLastDayOfWeek, getOptsByGranularity, getPlaceholder, getSegmentElements, getSideAndAlignFromAllPossibleConnectedPositions, getWeekNumber, handleAndDispatchCustomEvent, handleCalendarInitialFocus, hasTime, initializeSegmentValues, injectControlValueAccessor, injectDocument, injectIsClient, injectNgControl, injectWindow, isAcceptableSegmentKey, isAfter, isAfterOrSame, isBefore, isBeforeOrSame, isBetween, isBetweenInclusive, isCalendarDateTime, isEqual, isInsideForm, isNullish, isNumber, isNumberString, isSegmentNavigationKey, isValueEqualOrExist, isZonedDateTime, j, k, n, normalizeDateStep, normalizeHour12, normalizeHourCycle, p, provideToken, provideValueAccessor, resizeEffect, roundToStepPrecision, segmentBuilders, snapValueToStep, syncSegmentValues, syncTimeSegmentValues, toDate, useArrowNavigation, useDateField, watch };
-export type { AcceptableValue, AnyExceptLiteral, CreateMonthProps, DataOrientation, DateAndTimeSegmentObj, DateFormatterOptions, DateMatcher, DateRange, DateSegmentObj, DateSegmentPart, DateStep, DayPeriod, EditableSegmentPart, Formatter, Granularity, HourCycle, Month, NonEditableSegmentPart, Nullable, PlaceholderMap, RdxAllPossibleConnectedPositions, RdxArrowPositionParams, RdxPositionSideAndAlign, RdxPositionSideAndAlignOffsets, RdxPositioningDefaults, RdxPositions, SafeFunction, SegmentContentObj, SegmentPart, SegmentValueObj, TimeGranularity, TimeSegmentObj, TimeSegmentPart, TimeValue, UseDateFieldProps };
+declare enum RdxPositionSide {
+    Top = "top",
+    Right = "right",
+    Bottom = "bottom",
+    Left = "left"
+}
+declare enum RdxPositionAlign {
+    Start = "start",
+    Center = "center",
+    End = "end"
+}
+
+export { A, ALT, ARROW_DOWN, ARROW_LEFT, ARROW_RIGHT, ARROW_UP, ASTERISK, BACKSPACE, CAPS_LOCK, CONTROL, CTRL, DELETE, END, ENTER, ESCAPE, F1, F10, F11, F12, F2, F3, F4, F5, F6, F7, F8, F9, HOME, META, P, PAGE_DOWN, PAGE_UP, RdxControlValueAccessor, RdxIdGenerator, RdxLiveAnnouncer, RdxPositionAlign, RdxPositionSide, SHIFT, SPACE, SPACE_CODE, TAB, a, areAllDaysBetweenValid, clamp, createContent, createContext, createFormatter, createMonth, createMonths, elementSize, getActiveElement, getDaysBetween, getDaysInMonth, getDefaultDate, getDefaultTime, getLastFirstDayOfWeek, getMaxTransitionDuration, getNextLastDayOfWeek, getOptsByGranularity, getPlaceholder, getSegmentElements, getWeekNumber, handleAndDispatchCustomEvent, handleCalendarInitialFocus, hasTime, initializeSegmentValues, injectControlValueAccessor, injectDocument, injectId, isAcceptableSegmentKey, isAfter, isAfterOrSame, isBefore, isBeforeOrSame, isBetween, isBetweenInclusive, isCalendarDateTime, isEqual, isNullish, isNumberString, isSegmentNavigationKey, isZonedDateTime, j, k, n, normalizeDateStep, normalizeHour12, normalizeHourCycle, p, provideToken, provideValueAccessor, resizeEffect, roundToStepPrecision, segmentBuilders, snapValueToStep, syncSegmentValues, syncTimeSegmentValues, toDate, useArrowNavigation, useDateField, useGraceArea, usePointerDrag, useScrollLock, useTransitionStatus, watch };
+export type { AcceptableValue, AnyExceptLiteral, AriaLivePoliteness, BooleanInput, CreateMonthProps, DataOrientation, DateAndTimeSegmentObj, DateFormatterOptions, DateMatcher, DateRange, DateSegmentObj, DateSegmentPart, DateStep, DayPeriod, Direction, EditableSegmentPart, Formatter, Granularity, HourCycle, InjectContext, Month, NonEditableSegmentPart, Nullable, NumberInput, PlaceholderMap, RdxFormCheckboxControl, RdxFormStateInput, RdxFormUiControl, RdxFormValueControl, RdxPointerDragHandlers, RdxTransitionStatus, RdxTransitionStatusRef, RdxValidationError, SafeFunction, SegmentContentObj, SegmentPart, SegmentValueObj, TimeGranularity, TimeSegmentObj, TimeSegmentPart, TimeValue, UseDateFieldProps };