ng-primitives 0.122.0 → 0.123.0

package/fesm2022/ng-primitives-utils.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"ng-primitives-utils.mjs","sources":["../../../../packages/ng-primitives/utils/src/forms/providers.ts","../../../../packages/ng-primitives/utils/src/observables/take-until-destroyed.ts","../../../../packages/ng-primitives/utils/src/forms/status.ts","../../../../packages/ng-primitives/utils/src/helpers/attributes.ts","../../../../packages/ng-primitives/utils/src/helpers/disposables.ts","../../../../packages/ng-primitives/utils/src/helpers/unique-id.ts","../../../../packages/ng-primitives/utils/src/helpers/validators.ts","../../../../packages/ng-primitives/utils/src/signals/index.ts","../../../../packages/ng-primitives/utils/src/ng-primitives-utils.ts"],"sourcesContent":["import { ExistingProvider, Type } from '@angular/core';\nimport { NG_VALUE_ACCESSOR } from '@angular/forms';\n\n/**\n * A simple helper function to provide a value accessor for a given type.\n * @param type The type to provide the value accessor for\n */\nexport function provideValueAccessor<T>(type: Type<T>): ExistingProvider {\n  return { provide: NG_VALUE_ACCESSOR, useExisting: type, multi: true };\n}\n","/* eslint-disable @nx/workspace-take-until-destroyed */\nimport { DestroyRef } from '@angular/core';\nimport { takeUntilDestroyed } from '@angular/core/rxjs-interop';\nimport { EMPTY, MonoTypeOperatorFunction, NEVER, pipe } from 'rxjs';\nimport { catchError, defaultIfEmpty, takeUntil } from 'rxjs/operators';\n\n/**\n * The built-in `takeUntilDestroyed` operator does not handle the case when the component is destroyed before the source observable emits.\n * This operator ensures that the source observable completes gracefully without throwing an error.\n * https://github.com/angular/angular/issues/54527#issuecomment-2098254508\n *\n * @internal\n */\nexport function safeTakeUntilDestroyed<T>(destroyRef?: DestroyRef): MonoTypeOperatorFunction<T> {\n  return pipe(\n    takeUntil(\n      NEVER.pipe(\n        takeUntilDestroyed(destroyRef),\n        catchError(() => EMPTY),\n        defaultIfEmpty(null),\n      ),\n    ),\n  );\n}\n","import {\n  DestroyRef,\n  Injector,\n  Signal,\n  WritableSignal,\n  effect,\n  inject,\n  signal,\n  untracked,\n} from '@angular/core';\nimport { NgControl } from '@angular/forms';\nimport { onMount } from 'ng-primitives/state';\nimport { safeTakeUntilDestroyed } from '../observables/take-until-destroyed';\n\nexport interface NgpControlStatus {\n  valid: boolean | null;\n  invalid: boolean | null;\n  pristine: boolean | null;\n  dirty: boolean | null;\n  touched: boolean | null;\n  pending: boolean | null;\n  disabled: boolean | null;\n}\n\n/**\n * Detects an Angular signal-forms interop control without importing any of the new\n * signal-form types. Interop controls expose a `field()` method which returns the\n * underlying FieldState.\n */\nfunction isInteropControl(control: NgControl | null | undefined): boolean {\n  return !!control && typeof (control as any).field === 'function';\n}\n\n/**\n * Reads status from a control and updates the status signal.\n * Wrapped in try-catch to handle signal-forms interop controls where\n * the `field` input may not be available yet (throws NG0950).\n */\nfunction updateStatus(control: NgControl, status: WritableSignal<NgpControlStatus>): void {\n  try {\n    // For interop controls, read directly from the control (which has signal getters).\n    // For classic controls, read from the underlying AbstractControl.\n    const source = isInteropControl(control) ? control : ((control as any).control ?? control);\n\n    const newStatus: NgpControlStatus = {\n      valid: source.valid ?? null,\n      invalid: source.invalid ?? null,\n      pristine: source.pristine ?? null,\n      dirty: source.dirty ?? null,\n      touched: source.touched ?? null,\n      pending: source.pending ?? null,\n      disabled: source.disabled ?? null,\n    };\n\n    untracked(() => status.set(newStatus));\n  } catch {\n    // NG0950: Required input not available yet. The effect will re-run\n    // when the signal input becomes available.\n  }\n}\n\n/**\n * A utility function to get the status of an Angular form control as a reactive signal.\n * This function injects the NgControl and returns a signal that reflects the control's status.\n * It supports both classic reactive forms controls and signal-forms interop controls.\n * @internal\n */\n/**\n * Sets up event subscription for a given NgControl.\n * Only sets up the subscription - does not call updateStatus.\n */\nfunction setupEventSubscription(\n  ngControl: NgControl,\n  status: WritableSignal<NgpControlStatus>,\n  destroyRef: DestroyRef,\n): void {\n  // For classic controls, also subscribe to the events observable.\n  const underlyingControl = (ngControl as any).control;\n  if (underlyingControl?.events) {\n    underlyingControl.events\n      .pipe(safeTakeUntilDestroyed(destroyRef))\n      .subscribe(() => updateStatus(ngControl, status));\n  }\n}\n\nexport function controlStatus(): Signal<NgpControlStatus> {\n  const injector = inject(Injector);\n  const destroyRef = inject(DestroyRef);\n\n  const status = signal<NgpControlStatus>({\n    valid: null,\n    invalid: null,\n    pristine: null,\n    dirty: null,\n    touched: null,\n    pending: null,\n    disabled: null,\n  });\n\n  const control = signal<NgControl | null>(null);\n\n  onMount(() => {\n    // Try to inject NgControl immediately for initial state\n    control.set(inject(NgControl, { optional: true }));\n\n    // If we have a control immediately, update initial status\n    if (control()) {\n      updateStatus(control()!, status);\n    }\n\n    // Get the control (either from initial injection or from mount)\n    const mountControl = control() || inject(NgControl, { optional: true });\n\n    if (!mountControl) {\n      return;\n    }\n\n    // Update control signal if it wasn't set before\n    if (!control()) {\n      control.set(mountControl);\n    }\n\n    // Update status to ensure latest values\n    updateStatus(mountControl, status);\n\n    // Set up event subscription for reactive updates\n    setupEventSubscription(mountControl, status, destroyRef);\n  });\n\n  // Use an effect to reactively track status changes.\n  // For signal-forms interop controls, the status properties are signals.\n  // For classic controls, this will read the current values and establish\n  // no signal dependencies, but we also subscribe to events below.\n  effect(\n    () => {\n      const c = control();\n      if (c) {\n        updateStatus(c, status);\n      }\n    },\n    { injector },\n  );\n\n  return status;\n}\n","import { afterRenderEffect, Signal } from '@angular/core';\n\nexport function booleanAttributeBinding(\n  element: HTMLElement,\n  attribute: string,\n  value: Signal<boolean> | undefined,\n): void {\n  // eslint-disable-next-line @angular-eslint/no-uncalled-signals -- checking whether the optional signal was provided, not its value\n  if (value === undefined) {\n    return;\n  }\n\n  afterRenderEffect({\n    write: () =>\n      value() ? element.setAttribute(attribute, '') : element.removeAttribute(attribute),\n  });\n}\n","import { DestroyRef, inject } from '@angular/core';\n\n/**\n * Disposable functions are a way to manage timers, intervals, and event listeners\n * that should be cleared when a component is destroyed.\n *\n * This is heavily inspired by Headless UI disposables:\n * https://github.com/tailwindlabs/headlessui/blob/main/packages/%40headlessui-react/src/utils/disposables.ts\n */\nexport function injectDisposables() {\n  const destroyRef = inject(DestroyRef);\n  let isDestroyed = false;\n\n  destroyRef.onDestroy(() => (isDestroyed = true));\n\n  return {\n    /**\n     * Set a timeout that will be cleared when the component is destroyed.\n     * @param callback The callback to execute\n     * @param delay The delay before the callback is executed\n     * @returns A function to clear the timeout\n     */\n    setTimeout: (callback: () => void, delay: number) => {\n      if (isDestroyed) {\n        // eslint-disable-next-line @typescript-eslint/no-empty-function\n        return () => {};\n      }\n\n      const id = setTimeout(callback, delay);\n      const cleanup = () => clearTimeout(id);\n      destroyRef.onDestroy(cleanup);\n      return cleanup;\n    },\n    /**\n     * Set an interval that will be cleared when the component is destroyed.\n     * @param callback The callback to execute\n     * @param delay The delay before the callback is executed\n     * @param target\n     * @param type\n     * @param listener\n     * @param options\n     * @returns A function to clear the interval\n     */\n    addEventListener: <K extends keyof HTMLElementEventMap>(\n      target: EventTarget,\n      type: K,\n      // eslint-disable-next-line @typescript-eslint/no-explicit-any\n      listener: (this: HTMLElement, ev: HTMLElementEventMap[K]) => any,\n      options?: boolean | AddEventListenerOptions,\n    ) => {\n      if (isDestroyed) {\n        // eslint-disable-next-line @typescript-eslint/no-empty-function\n        return () => {};\n      }\n\n      target.addEventListener(type, listener as EventListenerOrEventListenerObject, options);\n      const cleanup = () =>\n        target.removeEventListener(type, listener as EventListenerOrEventListenerObject, options);\n      destroyRef.onDestroy(cleanup);\n      return cleanup;\n    },\n    /**\n     * Set an interval that will be cleared when the component is destroyed.\n     * @param callback The callback to execute\n     * @param delay The delay before the callback is executed\n     * @returns A function to clear the interval\n     */\n    setInterval: (callback: () => void, delay: number) => {\n      if (isDestroyed) {\n        // eslint-disable-next-line @typescript-eslint/no-empty-function\n        return () => {};\n      }\n\n      const id = setInterval(callback, delay);\n      const cleanup = () => clearInterval(id);\n      destroyRef.onDestroy(cleanup);\n      return cleanup;\n    },\n    /**\n     * Set a requestAnimationFrame that will be cleared when the component is destroyed.\n     * @param callback The callback to execute\n     * @returns A function to clear the requestAnimationFrame\n     */\n    requestAnimationFrame: (callback: FrameRequestCallback) => {\n      if (isDestroyed) {\n        // eslint-disable-next-line @typescript-eslint/no-empty-function\n        return () => {};\n      }\n\n      const id = requestAnimationFrame(callback);\n      const cleanup = () => cancelAnimationFrame(id);\n      destroyRef.onDestroy(cleanup);\n      return cleanup;\n    },\n  };\n}\n","/**\n * Store a map of unique ids for elements so that there are no collisions.\n */\nconst uniqueIdMap = new Map<string, number>();\n\n/**\n * Generate a unique id for an element\n * @param prefix - The prefix to use for the id\n * @returns The generated id\n */\nexport function uniqueId(prefix: string): string {\n  const id = uniqueIdMap.get(prefix) ?? 0;\n  uniqueIdMap.set(prefix, id + 1);\n  return `${prefix}-${id}`;\n}\n","/**\n * Type validation utilities\n */\n\n/**\n * Checks if a value is a string\n * @param value - The value to check\n * @returns true if the value is a string, false otherwise\n */\nexport function isString(value: unknown): value is string {\n  return typeof value === 'string';\n}\n\n/**\n * Checks if a value is a number\n * @param value - The value to check\n * @returns true if the value is a number, false otherwise\n */\nexport function isNumber(value: unknown): value is number {\n  return typeof value === 'number';\n}\n\n/**\n * Checks if a value is a boolean\n * @param value - The value to check\n * @returns true if the value is a boolean, false otherwise\n */\nexport function isBoolean(value: unknown): value is boolean {\n  return typeof value === 'boolean';\n}\n\n/**\n * Checks if a value is a function\n * @param value - The value to check\n * @returns true if the value is a function, false otherwise\n */\nexport function isFunction(value: unknown): value is CallableFunction {\n  return typeof value === 'function';\n}\n\n/**\n * Checks if a value is a plain object (but not null or array)\n * @param value - The value to check\n * @returns true if the value is a plain object, false otherwise\n */\nexport function isObject(value: unknown): value is Record<string, unknown> {\n  return !!value && typeof value === 'object' && !Array.isArray(value);\n}\n\n/**\n * Checks if a value is undefined\n * @param value - The value to check\n * @returns true if the value is undefined, false otherwise\n */\nexport function isUndefined(value: unknown): value is undefined {\n  return typeof value === 'undefined';\n}\n\n/**\n * Checks if a value is null or undefined\n * @param value - The value to check\n * @returns true if the value is null or undefined, false otherwise\n */\nexport function isNil(value: unknown): value is null | undefined {\n  return isUndefined(value) || value === null;\n}\n\n/**\n * Checks if a value is not null and not undefined\n * @param value - The value to check\n * @returns true if the value is not null and not undefined, false otherwise\n */\nexport function notNil<T>(value: T | null | undefined): value is T {\n  return !isNil(value);\n}\n","import { effect, Injector, Signal, signal, untracked } from '@angular/core';\n\n/**\n * Listen for changes to a signal and call a function when the signal changes.\n * @param source\n * @param fn\n * @param options\n * @param options.injector\n * @internal\n */\nexport function onChange<T>(\n  source: Signal<T>,\n  fn: (value: T, previousValue: T | null | undefined) => void,\n  options?: { injector: Injector },\n): void {\n  const previousValue = signal(source());\n\n  effect(\n    () => {\n      const value = source();\n      if (value !== previousValue()) {\n        untracked(() => fn(value, previousValue()));\n        previousValue.set(value);\n      }\n    },\n    { injector: options?.injector },\n  );\n\n  // call the fn with the initial value\n  fn(source(), null);\n}\n\n/**\n * Listen for changes to a boolean signal and call one of two functions when the signal changes.\n * @param source\n * @param onTrue\n * @param onFalse\n * @param options\n */\nexport function onBooleanChange(\n  source: Signal<boolean>,\n  onTrue?: () => void,\n  onFalse?: () => void,\n  options?: { injector: Injector },\n): void {\n  onChange(source, value => (value ? onTrue?.() : onFalse?.()), options);\n}\n","/**\n * Generated bundle index. Do not edit.\n */\n\nexport * from './index';\n"],"names":[],"mappings":";;;;;;;AAGA;;;AAGG;AACG,SAAU,oBAAoB,CAAI,IAAa,EAAA;AACnD,IAAA,OAAO,EAAE,OAAO,EAAE,iBAAiB,EAAE,WAAW,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE;AACvE;;ACHA;;;;;;AAMG;AACG,SAAU,sBAAsB,CAAI,UAAuB,EAAA;AAC/D,IAAA,OAAO,IAAI,CACT,SAAS,CACP,KAAK,CAAC,IAAI,CACR,kBAAkB,CAAC,UAAU,CAAC,EAC9B,UAAU,CAAC,MAAM,KAAK,CAAC,EACvB,cAAc,CAAC,IAAI,CAAC,CACrB,CACF,CACF;AACH;;ACCA;;;;AAIG;AACH,SAAS,gBAAgB,CAAC,OAAqC,EAAA;IAC7D,OAAO,CAAC,CAAC,OAAO,IAAI,OAAQ,OAAe,CAAC,KAAK,KAAK,UAAU;AAClE;AAEA;;;;AAIG;AACH,SAAS,YAAY,CAAC,OAAkB,EAAE,MAAwC,EAAA;AAChF,IAAA,IAAI;;;QAGF,MAAM,MAAM,GAAG,gBAAgB,CAAC,OAAO,CAAC,GAAG,OAAO,IAAK,OAAe,CAAC,OAAO,IAAI,OAAO,CAAC;AAE1F,QAAA,MAAM,SAAS,GAAqB;AAClC,YAAA,KAAK,EAAE,MAAM,CAAC,KAAK,IAAI,IAAI;AAC3B,YAAA,OAAO,EAAE,MAAM,CAAC,OAAO,IAAI,IAAI;AAC/B,YAAA,QAAQ,EAAE,MAAM,CAAC,QAAQ,IAAI,IAAI;AACjC,YAAA,KAAK,EAAE,MAAM,CAAC,KAAK,IAAI,IAAI;AAC3B,YAAA,OAAO,EAAE,MAAM,CAAC,OAAO,IAAI,IAAI;AAC/B,YAAA,OAAO,EAAE,MAAM,CAAC,OAAO,IAAI,IAAI;AAC/B,YAAA,QAAQ,EAAE,MAAM,CAAC,QAAQ,IAAI,IAAI;SAClC;QAED,SAAS,CAAC,MAAM,MAAM,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;IACxC;AAAE,IAAA,MAAM;;;IAGR;AACF;AAEA;;;;;AAKG;AACH;;;AAGG;AACH,SAAS,sBAAsB,CAC7B,SAAoB,EACpB,MAAwC,EACxC,UAAsB,EAAA;;AAGtB,IAAA,MAAM,iBAAiB,GAAI,SAAiB,CAAC,OAAO;AACpD,IAAA,IAAI,iBAAiB,EAAE,MAAM,EAAE;AAC7B,QAAA,iBAAiB,CAAC;AACf,aAAA,IAAI,CAAC,sBAAsB,CAAC,UAAU,CAAC;aACvC,SAAS,CAAC,MAAM,YAAY,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC;IACrD;AACF;SAEgB,aAAa,GAAA;AAC3B,IAAA,MAAM,QAAQ,GAAG,MAAM,CAAC,QAAQ,CAAC;AACjC,IAAA,MAAM,UAAU,GAAG,MAAM,CAAC,UAAU,CAAC;IAErC,MAAM,MAAM,GAAG,MAAM,CAAmB;AACtC,QAAA,KAAK,EAAE,IAAI;AACX,QAAA,OAAO,EAAE,IAAI;AACb,QAAA,QAAQ,EAAE,IAAI;AACd,QAAA,KAAK,EAAE,IAAI;AACX,QAAA,OAAO,EAAE,IAAI;AACb,QAAA,OAAO,EAAE,IAAI;AACb,QAAA,QAAQ,EAAE,IAAI;AACf,KAAA,EAAA,IAAA,SAAA,GAAA,CAAA,EAAA,SAAA,EAAA,QAAA,EAAA,CAAA,8BAAA,EAAA,CAAA,CAAC;AAEF,IAAA,MAAM,OAAO,GAAG,MAAM,CAAmB,IAAI,8EAAC;IAE9C,OAAO,CAAC,MAAK;;AAEX,QAAA,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,SAAS,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC;;QAGlD,IAAI,OAAO,EAAE,EAAE;AACb,YAAA,YAAY,CAAC,OAAO,EAAG,EAAE,MAAM,CAAC;QAClC;;AAGA,QAAA,MAAM,YAAY,GAAG,OAAO,EAAE,IAAI,MAAM,CAAC,SAAS,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;QAEvE,IAAI,CAAC,YAAY,EAAE;YACjB;QACF;;AAGA,QAAA,IAAI,CAAC,OAAO,EAAE,EAAE;AACd,YAAA,OAAO,CAAC,GAAG,CAAC,YAAY,CAAC;QAC3B;;AAGA,QAAA,YAAY,CAAC,YAAY,EAAE,MAAM,CAAC;;AAGlC,QAAA,sBAAsB,CAAC,YAAY,EAAE,MAAM,EAAE,UAAU,CAAC;AAC1D,IAAA,CAAC,CAAC;;;;;IAMF,MAAM,CACJ,MAAK;AACH,QAAA,MAAM,CAAC,GAAG,OAAO,EAAE;QACnB,IAAI,CAAC,EAAE;AACL,YAAA,YAAY,CAAC,CAAC,EAAE,MAAM,CAAC;QACzB;AACF,IAAA,CAAC,EACD,EAAE,QAAQ,EAAE,CACb;AAED,IAAA,OAAO,MAAM;AACf;;SC9IgB,uBAAuB,CACrC,OAAoB,EACpB,SAAiB,EACjB,KAAkC,EAAA;;AAGlC,IAAA,IAAI,KAAK,KAAK,SAAS,EAAE;QACvB;IACF;AAEA,IAAA,iBAAiB,CAAC;QAChB,KAAK,EAAE,MACL,KAAK,EAAE,GAAG,OAAO,CAAC,YAAY,CAAC,SAAS,EAAE,EAAE,CAAC,GAAG,OAAO,CAAC,eAAe,CAAC,SAAS,CAAC;AACrF,KAAA,CAAC;AACJ;;ACdA;;;;;;AAMG;SACa,iBAAiB,GAAA;AAC/B,IAAA,MAAM,UAAU,GAAG,MAAM,CAAC,UAAU,CAAC;IACrC,IAAI,WAAW,GAAG,KAAK;AAEvB,IAAA,UAAU,CAAC,SAAS,CAAC,OAAO,WAAW,GAAG,IAAI,CAAC,CAAC;IAEhD,OAAO;AACL;;;;;AAKG;AACH,QAAA,UAAU,EAAE,CAAC,QAAoB,EAAE,KAAa,KAAI;YAClD,IAAI,WAAW,EAAE;;AAEf,gBAAA,OAAO,MAAK,EAAE,CAAC;YACjB;YAEA,MAAM,EAAE,GAAG,UAAU,CAAC,QAAQ,EAAE,KAAK,CAAC;YACtC,MAAM,OAAO,GAAG,MAAM,YAAY,CAAC,EAAE,CAAC;AACtC,YAAA,UAAU,CAAC,SAAS,CAAC,OAAO,CAAC;AAC7B,YAAA,OAAO,OAAO;QAChB,CAAC;AACD;;;;;;;;;AASG;AACH,QAAA,gBAAgB,EAAE,CAChB,MAAmB,EACnB,IAAO;;QAEP,QAAgE,EAChE,OAA2C,KACzC;YACF,IAAI,WAAW,EAAE;;AAEf,gBAAA,OAAO,MAAK,EAAE,CAAC;YACjB;YAEA,MAAM,CAAC,gBAAgB,CAAC,IAAI,EAAE,QAA8C,EAAE,OAAO,CAAC;AACtF,YAAA,MAAM,OAAO,GAAG,MACd,MAAM,CAAC,mBAAmB,CAAC,IAAI,EAAE,QAA8C,EAAE,OAAO,CAAC;AAC3F,YAAA,UAAU,CAAC,SAAS,CAAC,OAAO,CAAC;AAC7B,YAAA,OAAO,OAAO;QAChB,CAAC;AACD;;;;;AAKG;AACH,QAAA,WAAW,EAAE,CAAC,QAAoB,EAAE,KAAa,KAAI;YACnD,IAAI,WAAW,EAAE;;AAEf,gBAAA,OAAO,MAAK,EAAE,CAAC;YACjB;YAEA,MAAM,EAAE,GAAG,WAAW,CAAC,QAAQ,EAAE,KAAK,CAAC;YACvC,MAAM,OAAO,GAAG,MAAM,aAAa,CAAC,EAAE,CAAC;AACvC,YAAA,UAAU,CAAC,SAAS,CAAC,OAAO,CAAC;AAC7B,YAAA,OAAO,OAAO;QAChB,CAAC;AACD;;;;AAIG;AACH,QAAA,qBAAqB,EAAE,CAAC,QAA8B,KAAI;YACxD,IAAI,WAAW,EAAE;;AAEf,gBAAA,OAAO,MAAK,EAAE,CAAC;YACjB;AAEA,YAAA,MAAM,EAAE,GAAG,qBAAqB,CAAC,QAAQ,CAAC;YAC1C,MAAM,OAAO,GAAG,MAAM,oBAAoB,CAAC,EAAE,CAAC;AAC9C,YAAA,UAAU,CAAC,SAAS,CAAC,OAAO,CAAC;AAC7B,YAAA,OAAO,OAAO;QAChB,CAAC;KACF;AACH;;AC/FA;;AAEG;AACH,MAAM,WAAW,GAAG,IAAI,GAAG,EAAkB;AAE7C;;;;AAIG;AACG,SAAU,QAAQ,CAAC,MAAc,EAAA;IACrC,MAAM,EAAE,GAAG,WAAW,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC;IACvC,WAAW,CAAC,GAAG,CAAC,MAAM,EAAE,EAAE,GAAG,CAAC,CAAC;AAC/B,IAAA,OAAO,CAAA,EAAG,MAAM,CAAA,CAAA,EAAI,EAAE,EAAE;AAC1B;;ACdA;;AAEG;AAEH;;;;AAIG;AACG,SAAU,QAAQ,CAAC,KAAc,EAAA;AACrC,IAAA,OAAO,OAAO,KAAK,KAAK,QAAQ;AAClC;AAEA;;;;AAIG;AACG,SAAU,QAAQ,CAAC,KAAc,EAAA;AACrC,IAAA,OAAO,OAAO,KAAK,KAAK,QAAQ;AAClC;AAEA;;;;AAIG;AACG,SAAU,SAAS,CAAC,KAAc,EAAA;AACtC,IAAA,OAAO,OAAO,KAAK,KAAK,SAAS;AACnC;AAEA;;;;AAIG;AACG,SAAU,UAAU,CAAC,KAAc,EAAA;AACvC,IAAA,OAAO,OAAO,KAAK,KAAK,UAAU;AACpC;AAEA;;;;AAIG;AACG,SAAU,QAAQ,CAAC,KAAc,EAAA;AACrC,IAAA,OAAO,CAAC,CAAC,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;AACtE;AAEA;;;;AAIG;AACG,SAAU,WAAW,CAAC,KAAc,EAAA;AACxC,IAAA,OAAO,OAAO,KAAK,KAAK,WAAW;AACrC;AAEA;;;;AAIG;AACG,SAAU,KAAK,CAAC,KAAc,EAAA;IAClC,OAAO,WAAW,CAAC,KAAK,CAAC,IAAI,KAAK,KAAK,IAAI;AAC7C;AAEA;;;;AAIG;AACG,SAAU,MAAM,CAAI,KAA2B,EAAA;AACnD,IAAA,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC;AACtB;;ACxEA;;;;;;;AAOG;SACa,QAAQ,CACtB,MAAiB,EACjB,EAA2D,EAC3D,OAAgC,EAAA;AAEhC,IAAA,MAAM,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,oFAAC;IAEtC,MAAM,CACJ,MAAK;AACH,QAAA,MAAM,KAAK,GAAG,MAAM,EAAE;AACtB,QAAA,IAAI,KAAK,KAAK,aAAa,EAAE,EAAE;AAC7B,YAAA,SAAS,CAAC,MAAM,EAAE,CAAC,KAAK,EAAE,aAAa,EAAE,CAAC,CAAC;AAC3C,YAAA,aAAa,CAAC,GAAG,CAAC,KAAK,CAAC;QAC1B;IACF,CAAC,EACD,EAAE,QAAQ,EAAE,OAAO,EAAE,QAAQ,EAAE,CAChC;;AAGD,IAAA,EAAE,CAAC,MAAM,EAAE,EAAE,IAAI,CAAC;AACpB;AAEA;;;;;;AAMG;AACG,SAAU,eAAe,CAC7B,MAAuB,EACvB,MAAmB,EACnB,OAAoB,EACpB,OAAgC,EAAA;IAEhC,QAAQ,CAAC,MAAM,EAAE,KAAK,KAAK,KAAK,GAAG,MAAM,IAAI,GAAG,OAAO,IAAI,CAAC,EAAE,OAAO,CAAC;AACxE;;AC9CA;;AAEG;;;;"}
+{"version":3,"file":"ng-primitives-utils.mjs","sources":["../../../../packages/ng-primitives/utils/src/forms/providers.ts","../../../../packages/ng-primitives/utils/src/observables/take-until-destroyed.ts","../../../../packages/ng-primitives/utils/src/forms/status.ts","../../../../packages/ng-primitives/utils/src/helpers/attributes.ts","../../../../packages/ng-primitives/utils/src/helpers/disposables.ts","../../../../packages/ng-primitives/utils/src/helpers/unique-id.ts","../../../../packages/ng-primitives/utils/src/helpers/validators.ts","../../../../packages/ng-primitives/utils/src/signals/index.ts","../../../../packages/ng-primitives/utils/src/ng-primitives-utils.ts"],"sourcesContent":["import { ExistingProvider, Type } from '@angular/core';\nimport { NG_VALUE_ACCESSOR } from '@angular/forms';\n\n/**\n * A simple helper function to provide a value accessor for a given type.\n * @param type The type to provide the value accessor for\n */\nexport function provideValueAccessor<T>(type: Type<T>): ExistingProvider {\n  return { provide: NG_VALUE_ACCESSOR, useExisting: type, multi: true };\n}\n","/* eslint-disable @nx/workspace-take-until-destroyed */\nimport { DestroyRef } from '@angular/core';\nimport { takeUntilDestroyed } from '@angular/core/rxjs-interop';\nimport { EMPTY, MonoTypeOperatorFunction, NEVER, pipe } from 'rxjs';\nimport { catchError, defaultIfEmpty, takeUntil } from 'rxjs/operators';\n\n/**\n * The built-in `takeUntilDestroyed` operator does not handle the case when the component is destroyed before the source observable emits.\n * This operator ensures that the source observable completes gracefully without throwing an error.\n * https://github.com/angular/angular/issues/54527#issuecomment-2098254508\n *\n * @internal\n */\nexport function safeTakeUntilDestroyed<T>(destroyRef?: DestroyRef): MonoTypeOperatorFunction<T> {\n  return pipe(\n    takeUntil(\n      NEVER.pipe(\n        takeUntilDestroyed(destroyRef),\n        catchError(() => EMPTY),\n        defaultIfEmpty(null),\n      ),\n    ),\n  );\n}\n","import {\n  DestroyRef,\n  Injector,\n  Signal,\n  WritableSignal,\n  effect,\n  inject,\n  signal,\n  untracked,\n} from '@angular/core';\nimport { NgControl } from '@angular/forms';\nimport { onMount } from 'ng-primitives/state';\nimport { safeTakeUntilDestroyed } from '../observables/take-until-destroyed';\n\nexport interface NgpControlStatus {\n  valid: boolean | null;\n  invalid: boolean | null;\n  pristine: boolean | null;\n  dirty: boolean | null;\n  touched: boolean | null;\n  pending: boolean | null;\n  disabled: boolean | null;\n}\n\n/**\n * Detects an Angular signal-forms interop control without importing any of the new\n * signal-form types. Interop controls expose a `field()` method which returns the\n * underlying FieldState.\n */\nfunction isInteropControl(control: NgControl | null | undefined): boolean {\n  return !!control && typeof (control as any).field === 'function';\n}\n\n/**\n * Reads status from a control and updates the status signal.\n * Wrapped in try-catch to handle signal-forms interop controls where\n * the `field` input may not be available yet (throws NG0950).\n */\nfunction updateStatus(control: NgControl, status: WritableSignal<NgpControlStatus>): void {\n  try {\n    // For interop controls, read directly from the control (which has signal getters).\n    // For classic controls, read from the underlying AbstractControl.\n    const source = isInteropControl(control) ? control : ((control as any).control ?? control);\n\n    const newStatus: NgpControlStatus = {\n      valid: source.valid ?? null,\n      invalid: source.invalid ?? null,\n      pristine: source.pristine ?? null,\n      dirty: source.dirty ?? null,\n      touched: source.touched ?? null,\n      pending: source.pending ?? null,\n      disabled: source.disabled ?? null,\n    };\n\n    untracked(() => status.set(newStatus));\n  } catch {\n    // NG0950: Required input not available yet. The effect will re-run\n    // when the signal input becomes available.\n  }\n}\n\n/**\n * A utility function to get the status of an Angular form control as a reactive signal.\n * This function injects the NgControl and returns a signal that reflects the control's status.\n * It supports both classic reactive forms controls and signal-forms interop controls.\n * @internal\n */\n/**\n * Sets up event subscription for a given NgControl.\n * Only sets up the subscription - does not call updateStatus.\n */\nfunction setupEventSubscription(\n  ngControl: NgControl,\n  status: WritableSignal<NgpControlStatus>,\n  destroyRef: DestroyRef,\n): void {\n  // For classic controls, also subscribe to the events observable.\n  const underlyingControl = (ngControl as any).control;\n  if (underlyingControl?.events) {\n    underlyingControl.events\n      .pipe(safeTakeUntilDestroyed(destroyRef))\n      .subscribe(() => updateStatus(ngControl, status));\n  }\n}\n\nexport function controlStatus(): Signal<NgpControlStatus> {\n  const injector = inject(Injector);\n  const destroyRef = inject(DestroyRef);\n\n  const status = signal<NgpControlStatus>({\n    valid: null,\n    invalid: null,\n    pristine: null,\n    dirty: null,\n    touched: null,\n    pending: null,\n    disabled: null,\n  });\n\n  const control = signal<NgControl | null>(null);\n\n  onMount(() => {\n    // Try to inject NgControl immediately for initial state\n    control.set(inject(NgControl, { optional: true }));\n\n    // If we have a control immediately, update initial status\n    if (control()) {\n      updateStatus(control()!, status);\n    }\n\n    // Get the control (either from initial injection or from mount)\n    const mountControl = control() || inject(NgControl, { optional: true });\n\n    if (!mountControl) {\n      return;\n    }\n\n    // Update control signal if it wasn't set before\n    if (!control()) {\n      control.set(mountControl);\n    }\n\n    // Update status to ensure latest values\n    updateStatus(mountControl, status);\n\n    // Set up event subscription for reactive updates\n    setupEventSubscription(mountControl, status, destroyRef);\n  });\n\n  // Use an effect to reactively track status changes.\n  // For signal-forms interop controls, the status properties are signals.\n  // For classic controls, this will read the current values and establish\n  // no signal dependencies, but we also subscribe to events below.\n  effect(\n    () => {\n      const c = control();\n      if (c) {\n        updateStatus(c, status);\n      }\n    },\n    { injector },\n  );\n\n  return status;\n}\n","import { afterRenderEffect, Signal } from '@angular/core';\n\nexport function booleanAttributeBinding(\n  element: HTMLElement,\n  attribute: string,\n  value: Signal<boolean> | undefined,\n): void {\n  // eslint-disable-next-line @angular-eslint/no-uncalled-signals -- checking whether the optional signal was provided, not its value\n  if (value === undefined) {\n    return;\n  }\n\n  afterRenderEffect({\n    write: () =>\n      value() ? element.setAttribute(attribute, '') : element.removeAttribute(attribute),\n  });\n}\n","import { DestroyRef, inject } from '@angular/core';\n\n/**\n * Disposable functions are a way to manage timers, intervals, and event listeners\n * that should be cleared when a component is destroyed.\n *\n * Each disposable releases its DestroyRef registration as soon as the resource\n * is gone (the timer fires or the returned cleanup runs), so repeated calls -\n * e.g. rescheduling a timeout on every pointermove - don't accumulate destroy\n * callbacks for the lifetime of the host.\n *\n * This is heavily inspired by Headless UI disposables:\n * https://github.com/tailwindlabs/headlessui/blob/main/packages/%40headlessui-react/src/utils/disposables.ts\n */\nexport function injectDisposables() {\n  const destroyRef = inject(DestroyRef);\n  let isDestroyed = false;\n\n  destroyRef.onDestroy(() => (isDestroyed = true));\n\n  return {\n    /**\n     * Set a timeout that will be cleared when the component is destroyed.\n     * @param callback The callback to execute\n     * @param delay The delay before the callback is executed\n     * @returns A function to clear the timeout\n     */\n    setTimeout: (callback: () => void, delay: number) => {\n      if (isDestroyed) {\n        // eslint-disable-next-line @typescript-eslint/no-empty-function\n        return () => {};\n      }\n\n      const id = setTimeout(() => {\n        unregister();\n        callback();\n      }, delay);\n      const unregister = destroyRef.onDestroy(() => clearTimeout(id));\n      return () => {\n        clearTimeout(id);\n        unregister();\n      };\n    },\n    /**\n     * Add an event listener that will be removed when the component is destroyed.\n     * @param target The event target\n     * @param type The event type\n     * @param listener The event listener\n     * @param options The event listener options\n     * @returns A function to remove the event listener\n     */\n    addEventListener: <K extends keyof HTMLElementEventMap>(\n      target: EventTarget,\n      type: K,\n      // eslint-disable-next-line @typescript-eslint/no-explicit-any\n      listener: (this: HTMLElement, ev: HTMLElementEventMap[K]) => any,\n      options?: boolean | AddEventListenerOptions,\n    ) => {\n      if (isDestroyed) {\n        // eslint-disable-next-line @typescript-eslint/no-empty-function\n        return () => {};\n      }\n\n      target.addEventListener(type, listener as EventListenerOrEventListenerObject, options);\n      const unregister = destroyRef.onDestroy(() =>\n        target.removeEventListener(type, listener as EventListenerOrEventListenerObject, options),\n      );\n      return () => {\n        target.removeEventListener(type, listener as EventListenerOrEventListenerObject, options);\n        unregister();\n      };\n    },\n    /**\n     * Set an interval that will be cleared when the component is destroyed.\n     * @param callback The callback to execute\n     * @param delay The delay between executions\n     * @returns A function to clear the interval\n     */\n    setInterval: (callback: () => void, delay: number) => {\n      if (isDestroyed) {\n        // eslint-disable-next-line @typescript-eslint/no-empty-function\n        return () => {};\n      }\n\n      const id = setInterval(callback, delay);\n      const unregister = destroyRef.onDestroy(() => clearInterval(id));\n      return () => {\n        clearInterval(id);\n        unregister();\n      };\n    },\n    /**\n     * Set a requestAnimationFrame that will be cleared when the component is destroyed.\n     * @param callback The callback to execute\n     * @returns A function to clear the requestAnimationFrame\n     */\n    requestAnimationFrame: (callback: FrameRequestCallback) => {\n      if (isDestroyed) {\n        // eslint-disable-next-line @typescript-eslint/no-empty-function\n        return () => {};\n      }\n\n      const id = requestAnimationFrame(time => {\n        unregister();\n        callback(time);\n      });\n      const unregister = destroyRef.onDestroy(() => cancelAnimationFrame(id));\n      return () => {\n        cancelAnimationFrame(id);\n        unregister();\n      };\n    },\n  };\n}\n","/**\n * Store a map of unique ids for elements so that there are no collisions.\n */\nconst uniqueIdMap = new Map<string, number>();\n\n/**\n * Generate a unique id for an element\n * @param prefix - The prefix to use for the id\n * @returns The generated id\n */\nexport function uniqueId(prefix: string): string {\n  const id = uniqueIdMap.get(prefix) ?? 0;\n  uniqueIdMap.set(prefix, id + 1);\n  return `${prefix}-${id}`;\n}\n","/**\n * Type validation utilities\n */\n\n/**\n * Checks if a value is a string\n * @param value - The value to check\n * @returns true if the value is a string, false otherwise\n */\nexport function isString(value: unknown): value is string {\n  return typeof value === 'string';\n}\n\n/**\n * Checks if a value is a number\n * @param value - The value to check\n * @returns true if the value is a number, false otherwise\n */\nexport function isNumber(value: unknown): value is number {\n  return typeof value === 'number';\n}\n\n/**\n * Checks if a value is a boolean\n * @param value - The value to check\n * @returns true if the value is a boolean, false otherwise\n */\nexport function isBoolean(value: unknown): value is boolean {\n  return typeof value === 'boolean';\n}\n\n/**\n * Checks if a value is a function\n * @param value - The value to check\n * @returns true if the value is a function, false otherwise\n */\nexport function isFunction(value: unknown): value is CallableFunction {\n  return typeof value === 'function';\n}\n\n/**\n * Checks if a value is a plain object (but not null or array)\n * @param value - The value to check\n * @returns true if the value is a plain object, false otherwise\n */\nexport function isObject(value: unknown): value is Record<string, unknown> {\n  return !!value && typeof value === 'object' && !Array.isArray(value);\n}\n\n/**\n * Checks if a value is undefined\n * @param value - The value to check\n * @returns true if the value is undefined, false otherwise\n */\nexport function isUndefined(value: unknown): value is undefined {\n  return typeof value === 'undefined';\n}\n\n/**\n * Checks if a value is null or undefined\n * @param value - The value to check\n * @returns true if the value is null or undefined, false otherwise\n */\nexport function isNil(value: unknown): value is null | undefined {\n  return isUndefined(value) || value === null;\n}\n\n/**\n * Checks if a value is not null and not undefined\n * @param value - The value to check\n * @returns true if the value is not null and not undefined, false otherwise\n */\nexport function notNil<T>(value: T | null | undefined): value is T {\n  return !isNil(value);\n}\n","import { effect, Injector, Signal, signal, untracked } from '@angular/core';\n\n/**\n * Listen for changes to a signal and call a function when the signal changes.\n * @param source\n * @param fn\n * @param options\n * @param options.injector\n * @internal\n */\nexport function onChange<T>(\n  source: Signal<T>,\n  fn: (value: T, previousValue: T | null | undefined) => void,\n  options?: { injector: Injector },\n): void {\n  const previousValue = signal(source());\n\n  effect(\n    () => {\n      const value = source();\n      if (value !== previousValue()) {\n        untracked(() => fn(value, previousValue()));\n        previousValue.set(value);\n      }\n    },\n    { injector: options?.injector },\n  );\n\n  // call the fn with the initial value\n  fn(source(), null);\n}\n\n/**\n * Listen for changes to a boolean signal and call one of two functions when the signal changes.\n * @param source\n * @param onTrue\n * @param onFalse\n * @param options\n */\nexport function onBooleanChange(\n  source: Signal<boolean>,\n  onTrue?: () => void,\n  onFalse?: () => void,\n  options?: { injector: Injector },\n): void {\n  onChange(source, value => (value ? onTrue?.() : onFalse?.()), options);\n}\n","/**\n * Generated bundle index. Do not edit.\n */\n\nexport * from './index';\n"],"names":[],"mappings":";;;;;;;AAGA;;;AAGG;AACG,SAAU,oBAAoB,CAAI,IAAa,EAAA;AACnD,IAAA,OAAO,EAAE,OAAO,EAAE,iBAAiB,EAAE,WAAW,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE;AACvE;;ACHA;;;;;;AAMG;AACG,SAAU,sBAAsB,CAAI,UAAuB,EAAA;AAC/D,IAAA,OAAO,IAAI,CACT,SAAS,CACP,KAAK,CAAC,IAAI,CACR,kBAAkB,CAAC,UAAU,CAAC,EAC9B,UAAU,CAAC,MAAM,KAAK,CAAC,EACvB,cAAc,CAAC,IAAI,CAAC,CACrB,CACF,CACF;AACH;;ACCA;;;;AAIG;AACH,SAAS,gBAAgB,CAAC,OAAqC,EAAA;IAC7D,OAAO,CAAC,CAAC,OAAO,IAAI,OAAQ,OAAe,CAAC,KAAK,KAAK,UAAU;AAClE;AAEA;;;;AAIG;AACH,SAAS,YAAY,CAAC,OAAkB,EAAE,MAAwC,EAAA;AAChF,IAAA,IAAI;;;QAGF,MAAM,MAAM,GAAG,gBAAgB,CAAC,OAAO,CAAC,GAAG,OAAO,IAAK,OAAe,CAAC,OAAO,IAAI,OAAO,CAAC;AAE1F,QAAA,MAAM,SAAS,GAAqB;AAClC,YAAA,KAAK,EAAE,MAAM,CAAC,KAAK,IAAI,IAAI;AAC3B,YAAA,OAAO,EAAE,MAAM,CAAC,OAAO,IAAI,IAAI;AAC/B,YAAA,QAAQ,EAAE,MAAM,CAAC,QAAQ,IAAI,IAAI;AACjC,YAAA,KAAK,EAAE,MAAM,CAAC,KAAK,IAAI,IAAI;AAC3B,YAAA,OAAO,EAAE,MAAM,CAAC,OAAO,IAAI,IAAI;AAC/B,YAAA,OAAO,EAAE,MAAM,CAAC,OAAO,IAAI,IAAI;AAC/B,YAAA,QAAQ,EAAE,MAAM,CAAC,QAAQ,IAAI,IAAI;SAClC;QAED,SAAS,CAAC,MAAM,MAAM,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;IACxC;AAAE,IAAA,MAAM;;;IAGR;AACF;AAEA;;;;;AAKG;AACH;;;AAGG;AACH,SAAS,sBAAsB,CAC7B,SAAoB,EACpB,MAAwC,EACxC,UAAsB,EAAA;;AAGtB,IAAA,MAAM,iBAAiB,GAAI,SAAiB,CAAC,OAAO;AACpD,IAAA,IAAI,iBAAiB,EAAE,MAAM,EAAE;AAC7B,QAAA,iBAAiB,CAAC;AACf,aAAA,IAAI,CAAC,sBAAsB,CAAC,UAAU,CAAC;aACvC,SAAS,CAAC,MAAM,YAAY,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC;IACrD;AACF;SAEgB,aAAa,GAAA;AAC3B,IAAA,MAAM,QAAQ,GAAG,MAAM,CAAC,QAAQ,CAAC;AACjC,IAAA,MAAM,UAAU,GAAG,MAAM,CAAC,UAAU,CAAC;IAErC,MAAM,MAAM,GAAG,MAAM,CAAmB;AACtC,QAAA,KAAK,EAAE,IAAI;AACX,QAAA,OAAO,EAAE,IAAI;AACb,QAAA,QAAQ,EAAE,IAAI;AACd,QAAA,KAAK,EAAE,IAAI;AACX,QAAA,OAAO,EAAE,IAAI;AACb,QAAA,OAAO,EAAE,IAAI;AACb,QAAA,QAAQ,EAAE,IAAI;AACf,KAAA,EAAA,IAAA,SAAA,GAAA,CAAA,EAAA,SAAA,EAAA,QAAA,EAAA,CAAA,8BAAA,EAAA,CAAA,CAAC;AAEF,IAAA,MAAM,OAAO,GAAG,MAAM,CAAmB,IAAI,8EAAC;IAE9C,OAAO,CAAC,MAAK;;AAEX,QAAA,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,SAAS,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC;;QAGlD,IAAI,OAAO,EAAE,EAAE;AACb,YAAA,YAAY,CAAC,OAAO,EAAG,EAAE,MAAM,CAAC;QAClC;;AAGA,QAAA,MAAM,YAAY,GAAG,OAAO,EAAE,IAAI,MAAM,CAAC,SAAS,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;QAEvE,IAAI,CAAC,YAAY,EAAE;YACjB;QACF;;AAGA,QAAA,IAAI,CAAC,OAAO,EAAE,EAAE;AACd,YAAA,OAAO,CAAC,GAAG,CAAC,YAAY,CAAC;QAC3B;;AAGA,QAAA,YAAY,CAAC,YAAY,EAAE,MAAM,CAAC;;AAGlC,QAAA,sBAAsB,CAAC,YAAY,EAAE,MAAM,EAAE,UAAU,CAAC;AAC1D,IAAA,CAAC,CAAC;;;;;IAMF,MAAM,CACJ,MAAK;AACH,QAAA,MAAM,CAAC,GAAG,OAAO,EAAE;QACnB,IAAI,CAAC,EAAE;AACL,YAAA,YAAY,CAAC,CAAC,EAAE,MAAM,CAAC;QACzB;AACF,IAAA,CAAC,EACD,EAAE,QAAQ,EAAE,CACb;AAED,IAAA,OAAO,MAAM;AACf;;SC9IgB,uBAAuB,CACrC,OAAoB,EACpB,SAAiB,EACjB,KAAkC,EAAA;;AAGlC,IAAA,IAAI,KAAK,KAAK,SAAS,EAAE;QACvB;IACF;AAEA,IAAA,iBAAiB,CAAC;QAChB,KAAK,EAAE,MACL,KAAK,EAAE,GAAG,OAAO,CAAC,YAAY,CAAC,SAAS,EAAE,EAAE,CAAC,GAAG,OAAO,CAAC,eAAe,CAAC,SAAS,CAAC;AACrF,KAAA,CAAC;AACJ;;ACdA;;;;;;;;;;;AAWG;SACa,iBAAiB,GAAA;AAC/B,IAAA,MAAM,UAAU,GAAG,MAAM,CAAC,UAAU,CAAC;IACrC,IAAI,WAAW,GAAG,KAAK;AAEvB,IAAA,UAAU,CAAC,SAAS,CAAC,OAAO,WAAW,GAAG,IAAI,CAAC,CAAC;IAEhD,OAAO;AACL;;;;;AAKG;AACH,QAAA,UAAU,EAAE,CAAC,QAAoB,EAAE,KAAa,KAAI;YAClD,IAAI,WAAW,EAAE;;AAEf,gBAAA,OAAO,MAAK,EAAE,CAAC;YACjB;AAEA,YAAA,MAAM,EAAE,GAAG,UAAU,CAAC,MAAK;AACzB,gBAAA,UAAU,EAAE;AACZ,gBAAA,QAAQ,EAAE;YACZ,CAAC,EAAE,KAAK,CAAC;AACT,YAAA,MAAM,UAAU,GAAG,UAAU,CAAC,SAAS,CAAC,MAAM,YAAY,CAAC,EAAE,CAAC,CAAC;AAC/D,YAAA,OAAO,MAAK;gBACV,YAAY,CAAC,EAAE,CAAC;AAChB,gBAAA,UAAU,EAAE;AACd,YAAA,CAAC;QACH,CAAC;AACD;;;;;;;AAOG;AACH,QAAA,gBAAgB,EAAE,CAChB,MAAmB,EACnB,IAAO;;QAEP,QAAgE,EAChE,OAA2C,KACzC;YACF,IAAI,WAAW,EAAE;;AAEf,gBAAA,OAAO,MAAK,EAAE,CAAC;YACjB;YAEA,MAAM,CAAC,gBAAgB,CAAC,IAAI,EAAE,QAA8C,EAAE,OAAO,CAAC;YACtF,MAAM,UAAU,GAAG,UAAU,CAAC,SAAS,CAAC,MACtC,MAAM,CAAC,mBAAmB,CAAC,IAAI,EAAE,QAA8C,EAAE,OAAO,CAAC,CAC1F;AACD,YAAA,OAAO,MAAK;gBACV,MAAM,CAAC,mBAAmB,CAAC,IAAI,EAAE,QAA8C,EAAE,OAAO,CAAC;AACzF,gBAAA,UAAU,EAAE;AACd,YAAA,CAAC;QACH,CAAC;AACD;;;;;AAKG;AACH,QAAA,WAAW,EAAE,CAAC,QAAoB,EAAE,KAAa,KAAI;YACnD,IAAI,WAAW,EAAE;;AAEf,gBAAA,OAAO,MAAK,EAAE,CAAC;YACjB;YAEA,MAAM,EAAE,GAAG,WAAW,CAAC,QAAQ,EAAE,KAAK,CAAC;AACvC,YAAA,MAAM,UAAU,GAAG,UAAU,CAAC,SAAS,CAAC,MAAM,aAAa,CAAC,EAAE,CAAC,CAAC;AAChE,YAAA,OAAO,MAAK;gBACV,aAAa,CAAC,EAAE,CAAC;AACjB,gBAAA,UAAU,EAAE;AACd,YAAA,CAAC;QACH,CAAC;AACD;;;;AAIG;AACH,QAAA,qBAAqB,EAAE,CAAC,QAA8B,KAAI;YACxD,IAAI,WAAW,EAAE;;AAEf,gBAAA,OAAO,MAAK,EAAE,CAAC;YACjB;AAEA,YAAA,MAAM,EAAE,GAAG,qBAAqB,CAAC,IAAI,IAAG;AACtC,gBAAA,UAAU,EAAE;gBACZ,QAAQ,CAAC,IAAI,CAAC;AAChB,YAAA,CAAC,CAAC;AACF,YAAA,MAAM,UAAU,GAAG,UAAU,CAAC,SAAS,CAAC,MAAM,oBAAoB,CAAC,EAAE,CAAC,CAAC;AACvE,YAAA,OAAO,MAAK;gBACV,oBAAoB,CAAC,EAAE,CAAC;AACxB,gBAAA,UAAU,EAAE;AACd,YAAA,CAAC;QACH,CAAC;KACF;AACH;;ACjHA;;AAEG;AACH,MAAM,WAAW,GAAG,IAAI,GAAG,EAAkB;AAE7C;;;;AAIG;AACG,SAAU,QAAQ,CAAC,MAAc,EAAA;IACrC,MAAM,EAAE,GAAG,WAAW,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC;IACvC,WAAW,CAAC,GAAG,CAAC,MAAM,EAAE,EAAE,GAAG,CAAC,CAAC;AAC/B,IAAA,OAAO,CAAA,EAAG,MAAM,CAAA,CAAA,EAAI,EAAE,EAAE;AAC1B;;ACdA;;AAEG;AAEH;;;;AAIG;AACG,SAAU,QAAQ,CAAC,KAAc,EAAA;AACrC,IAAA,OAAO,OAAO,KAAK,KAAK,QAAQ;AAClC;AAEA;;;;AAIG;AACG,SAAU,QAAQ,CAAC,KAAc,EAAA;AACrC,IAAA,OAAO,OAAO,KAAK,KAAK,QAAQ;AAClC;AAEA;;;;AAIG;AACG,SAAU,SAAS,CAAC,KAAc,EAAA;AACtC,IAAA,OAAO,OAAO,KAAK,KAAK,SAAS;AACnC;AAEA;;;;AAIG;AACG,SAAU,UAAU,CAAC,KAAc,EAAA;AACvC,IAAA,OAAO,OAAO,KAAK,KAAK,UAAU;AACpC;AAEA;;;;AAIG;AACG,SAAU,QAAQ,CAAC,KAAc,EAAA;AACrC,IAAA,OAAO,CAAC,CAAC,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;AACtE;AAEA;;;;AAIG;AACG,SAAU,WAAW,CAAC,KAAc,EAAA;AACxC,IAAA,OAAO,OAAO,KAAK,KAAK,WAAW;AACrC;AAEA;;;;AAIG;AACG,SAAU,KAAK,CAAC,KAAc,EAAA;IAClC,OAAO,WAAW,CAAC,KAAK,CAAC,IAAI,KAAK,KAAK,IAAI;AAC7C;AAEA;;;;AAIG;AACG,SAAU,MAAM,CAAI,KAA2B,EAAA;AACnD,IAAA,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC;AACtB;;ACxEA;;;;;;;AAOG;SACa,QAAQ,CACtB,MAAiB,EACjB,EAA2D,EAC3D,OAAgC,EAAA;AAEhC,IAAA,MAAM,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,oFAAC;IAEtC,MAAM,CACJ,MAAK;AACH,QAAA,MAAM,KAAK,GAAG,MAAM,EAAE;AACtB,QAAA,IAAI,KAAK,KAAK,aAAa,EAAE,EAAE;AAC7B,YAAA,SAAS,CAAC,MAAM,EAAE,CAAC,KAAK,EAAE,aAAa,EAAE,CAAC,CAAC;AAC3C,YAAA,aAAa,CAAC,GAAG,CAAC,KAAK,CAAC;QAC1B;IACF,CAAC,EACD,EAAE,QAAQ,EAAE,OAAO,EAAE,QAAQ,EAAE,CAChC;;AAGD,IAAA,EAAE,CAAC,MAAM,EAAE,EAAE,IAAI,CAAC;AACpB;AAEA;;;;;;AAMG;AACG,SAAU,eAAe,CAC7B,MAAuB,EACvB,MAAmB,EACnB,OAAoB,EACpB,OAAgC,EAAA;IAEhC,QAAQ,CAAC,MAAM,EAAE,KAAK,KAAK,KAAK,GAAG,MAAM,IAAI,GAAG,OAAO,IAAI,CAAC,EAAE,OAAO,CAAC;AACxE;;AC9CA;;AAEG;;;;"}

package/package.json

@@ -2,7 +2,7 @@
   "name": "ng-primitives",
   "description": "Angular Primitives is a low-level headless UI component library with a focus on accessibility, customization, and developer experience. ",
   "license": "Apache-2.0",
-  "version": "0.122.0",
+  "version": "0.123.0",
   "keywords": [
     "angular",
     "primitives",

package/schematics/ng-generate/templates/toggle-group/toggle-group.__fileSuffix@dasherize__.ts.template

@@ -57,8 +57,8 @@ export class ToggleGroup<%= componentSuffix %> implements ControlValueAccessor {
   }
 
   /** Write a new value to the toggle group. */
-  writeValue(value: string[]): void {
-    this.toggleGroup().setValue(value, { emit: false });
+  writeValue(value: string[] | null): void {
+    this.toggleGroup().setValue(value ?? [], { emit: false });
   }
 
   /** Register a callback function to be called when the value changes. */

package/types/ng-primitives-internal.d.ts

@@ -1,5 +1,5 @@
 import * as i0 from '@angular/core';
-import { OnDestroy, ClassProvider, EffectCleanupRegisterFn, CreateEffectOptions, EffectRef, ElementRef, Signal, Injector } from '@angular/core';
+import { OnDestroy, ClassProvider, Signal, EffectCleanupRegisterFn, CreateEffectOptions, EffectRef, ElementRef, Injector } from '@angular/core';
 import { Observable } from 'rxjs';
 
 declare class NgpExitAnimation implements OnDestroy {
@@ -45,6 +45,98 @@ declare class NgpExitAnimationManager {
 declare function provideExitAnimationManager(): ClassProvider;
 declare function injectExitAnimationManager(): NgpExitAnimationManager;
 
+/**
+ * Fallback timeout (ms) after which an idle hover bridge closes the overlay.
+ * Shared so tooltip, menu and submenu hover-intent behaviour stay in sync.
+ */
+declare const HOVER_BRIDGE_TIMEOUT_MS = 150;
+/**
+ * Pointer movement below this magnitude (px) on the intent axis is treated as
+ * jitter, not a reversal, so a tiny backward twitch doesn't collapse the bridge.
+ */
+declare const HOVER_BRIDGE_DIRECTION_TOLERANCE_PX = 2;
+interface HoverBridgePoint {
+    x: number;
+    y: number;
+}
+/**
+ * The dominant axis and sign pointing from the trigger toward the target. Used
+ * to reject pointer movement heading away from the target while inside the corridor.
+ */
+interface HoverBridgeDirection {
+    axis: 'x' | 'y';
+    sign: 1 | -1;
+}
+interface CreateHoverBridgePolygonOptions {
+    triggerRect: DOMRect | null;
+    targetRect: DOMRect | null;
+    exitPoint: HoverBridgePoint;
+    corridorHalfSize?: number;
+}
+/**
+ * Computes the dominant axis and sign from the trigger toward the target - i.e.
+ * which way the pointer must travel to reach the panel. Returns null if either
+ * rect is missing.
+ */
+declare function getHoverBridgeDirection(triggerRect: DOMRect | null, targetRect: DOMRect | null): HoverBridgeDirection | null;
+/**
+ * Builds a pointer grace polygon between the trigger exit point and the target overlay.
+ * The polygon is intentionally directional so moving away from the target exits quickly.
+ */
+declare function createHoverBridgePolygon({ triggerRect, targetRect, exitPoint, corridorHalfSize, }: CreateHoverBridgePolygonOptions): HoverBridgePoint[] | null;
+/**
+ * Returns true when the point lies inside the provided polygon.
+ */
+declare function isPointInHoverBridgePolygon(point: HoverBridgePoint, polygon: HoverBridgePoint[]): boolean;
+
+interface HoverBridgeOptions {
+    /** Whether the pointer is currently over the trigger or the panel (the "safe" area). */
+    isPointerInAnchor: () => boolean;
+    /** Close the overlay - called when the pointer leaves the corridor or the idle timer fires. */
+    close: () => void;
+    /**
+     * Require the pointer to keep heading toward the panel. When true, reversing
+     * away along the corridor's dominant axis closes the overlay (menu/submenu).
+     * Tooltips leave this off. Defaults to false.
+     */
+    requireForwardMovement?: boolean;
+    /**
+     * Reset the idle-fallback timer on valid in-corridor movement, so it only
+     * fires after the pointer genuinely stops. When false the timer is a fixed cap
+     * from the moment the corridor is built (tooltip's original semantics).
+     * Defaults to true.
+     */
+    resetFallbackOnMove?: boolean;
+    /** Idle-fallback timeout in ms. Defaults to HOVER_BRIDGE_TIMEOUT_MS. */
+    timeoutMs?: number;
+}
+interface HoverBridgeTrackOptions {
+    triggerRect: DOMRect | null;
+    targetRect: DOMRect | null;
+    exitPoint: HoverBridgePoint;
+}
+interface HoverBridgeController {
+    /** The active corridor polygon, or null when no bridge is in progress. */
+    readonly polygon: Signal<HoverBridgePoint[] | null>;
+    /** Whether a corridor is currently active. */
+    isActive(): boolean;
+    /**
+     * Build a corridor from the exit point toward the panel and start tracking the
+     * pointer. Returns false (and does nothing) when a polygon can't be built, so
+     * the caller can apply its own fallback.
+     */
+    track(options: HoverBridgeTrackOptions): boolean;
+    /** Tear down the corridor and its global listener/timer. */
+    clear(): void;
+}
+/**
+ * Shared safe-polygon hover-intent state machine used by the menu, submenu and
+ * tooltip triggers. While the pointer travels inside the corridor toward the
+ * panel the overlay stays open; it closes when the pointer leaves the corridor,
+ * reverses away (when requireForwardMovement is set) or idles past the timeout.
+ */
+declare function createHoverBridge({ isPointerInAnchor, close, requireForwardMovement, resetFallbackOnMove, timeoutMs, }: HoverBridgeOptions): HoverBridgeController;
+
 /**
  * This implementation is heavily inspired by the great work on ngextension!
  * https://github.com/ngxtension/ngxtension-platform/blob/main/libs/ngxtension/explicit-effect/src/explicit-effect.ts
@@ -210,5 +302,5 @@ declare function injectDimensions(): Signal<Dimensions>;
 
 declare function scrollIntoViewIfNeeded(element: HTMLElement): void;
 
-export { NgpExitAnimation, NgpExitAnimationManager, StyleInjector, domSort, explicitEffect, fromMutationObserver, fromResizeEvent, injectDimensions, injectElementRef, injectExitAnimationManager, injectStyleInjector, observeResize, onDomRemoval, provideExitAnimationManager, scrollIntoViewIfNeeded, setupExitAnimation, setupOverflowListener };
-export type { Dimensions, NgpExitAnimationRef };
+export { HOVER_BRIDGE_DIRECTION_TOLERANCE_PX, HOVER_BRIDGE_TIMEOUT_MS, NgpExitAnimation, NgpExitAnimationManager, StyleInjector, createHoverBridge, createHoverBridgePolygon, domSort, explicitEffect, fromMutationObserver, fromResizeEvent, getHoverBridgeDirection, injectDimensions, injectElementRef, injectExitAnimationManager, injectStyleInjector, isPointInHoverBridgePolygon, observeResize, onDomRemoval, provideExitAnimationManager, scrollIntoViewIfNeeded, setupExitAnimation, setupOverflowListener };
+export type { Dimensions, HoverBridgeController, HoverBridgeDirection, HoverBridgeOptions, HoverBridgePoint, HoverBridgeTrackOptions, NgpExitAnimationRef };

package/types/ng-primitives-menu.d.ts

@@ -653,6 +653,11 @@ declare class NgpSubmenuTrigger<T = unknown> {
      * @default true
      */
     readonly flip: _angular_core.InputSignalWithTransform<NgpFlip, NgpFlipInput>;
+    /**
+     * Define the container in which the menu should be attached.
+     * @default document.body
+     */
+    readonly container: _angular_core.InputSignal<string | HTMLElement | null>;
     /**
      * Access the menu trigger state.
      */
@@ -676,7 +681,7 @@ declare class NgpSubmenuTrigger<T = unknown> {
      */
     focus(origin?: FocusOrigin): void;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<NgpSubmenuTrigger<any>, never>;
-    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<NgpSubmenuTrigger<any>, "[ngpSubmenuTrigger]", ["ngpSubmenuTrigger"], { "menu": { "alias": "ngpSubmenuTrigger"; "required": false; "isSignal": true; }; "disabled": { "alias": "ngpSubmenuTriggerDisabled"; "required": false; "isSignal": true; }; "placement": { "alias": "ngpSubmenuTriggerPlacement"; "required": false; "isSignal": true; }; "offset": { "alias": "ngpSubmenuTriggerOffset"; "required": false; "isSignal": true; }; "flip": { "alias": "ngpSubmenuTriggerFlip"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<NgpSubmenuTrigger<any>, "[ngpSubmenuTrigger]", ["ngpSubmenuTrigger"], { "menu": { "alias": "ngpSubmenuTrigger"; "required": false; "isSignal": true; }; "disabled": { "alias": "ngpSubmenuTriggerDisabled"; "required": false; "isSignal": true; }; "placement": { "alias": "ngpSubmenuTriggerPlacement"; "required": false; "isSignal": true; }; "offset": { "alias": "ngpSubmenuTriggerOffset"; "required": false; "isSignal": true; }; "flip": { "alias": "ngpSubmenuTriggerFlip"; "required": false; "isSignal": true; }; "container": { "alias": "ngpSubmenuTriggerContainer"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
 }
 
 interface NgpSubmenuTriggerState {
@@ -704,6 +709,11 @@ interface NgpSubmenuTriggerState {
      * Whether the menu should flip when there is not enough space.
      */
     readonly flip: WritableSignal<NgpFlip>;
+    /**
+     * The container in which the menu should be attached.
+     * @default document.body
+     */
+    readonly container: WritableSignal<HTMLElement | string | null>;
     /**
      * The focus origin used to open the submenu.
      * Used by the submenu's focus trap for :focus-visible styling.
@@ -750,14 +760,20 @@ interface NgpSubmenuTriggerState {
      * @param shouldFlip - Whether the menu should flip
      */
     setFlip(shouldFlip: NgpFlip): void;
+    /**
+     * Set the container in which the menu should be attached. Takes effect the
+     * next time the menu is opened; it does not move a menu that is already open.
+     * @param container - The new container
+     */
+    setContainer(container: HTMLElement | string | null): void;
     /**
      * Focus the trigger element.
      * @param origin - The focus origin
      */
     focus(origin: FocusOrigin): void;
     /**
-     * Set whether the pointer is over the menu content.
-     * For submenus, this is a no-op as hover is handled via showSubmenuOnHover.
+     * Set whether the pointer is over the submenu content. Entering the submenu
+     * tears down the hover bridge (the pointer arrived safely).
      * @param isOver - Whether the pointer is over the content
      * @internal
      */
@@ -784,6 +800,10 @@ interface NgpSubmenuTriggerProps<T = unknown> {
      * Whether the menu should flip when there is not enough space.
      */
     readonly flip?: Signal<NgpFlip>;
+    /**
+     * The container in which the menu should be attached.
+     */
+    readonly container?: Signal<HTMLElement | string | null>;
 }
 declare const NgpSubmenuTriggerStateToken: _angular_core.InjectionToken<WritableSignal<{
     placement: WritableSignal<NgpMenuPlacement>;
@@ -801,10 +821,12 @@ declare const NgpSubmenuTriggerStateToken: _angular_core.InjectionToken<Writable
     setFlip: (shouldFlip: NgpFlip) => void;
     setPlacement: (newPlacement: NgpMenuPlacement) => void;
     setOffset: (newOffset: NgpOffset) => void;
+    setContainer: (newContainer: HTMLElement | string | null) => void;
     focus: (origin: FocusOrigin) => void;
-    setPointerOverContent: (_isOver: boolean) => void;
+    setPointerOverContent: (isOver: boolean) => void;
+    container: WritableSignal<string | HTMLElement | null>;
 }>>;
-declare const ngpSubmenuTrigger: <T>({ disabled: _disabled, menu: _menu, placement: _placement, offset: _offset, flip: _flip, }: NgpSubmenuTriggerProps<T>) => {
+declare const ngpSubmenuTrigger: <T>({ disabled: _disabled, menu: _menu, placement: _placement, offset: _offset, flip: _flip, container: _container, }: NgpSubmenuTriggerProps<T>) => {
     placement: WritableSignal<NgpMenuPlacement>;
     offset: WritableSignal<NgpOffset>;
     disabled: WritableSignal<boolean>;
@@ -820,8 +842,10 @@ declare const ngpSubmenuTrigger: <T>({ disabled: _disabled, menu: _menu, placeme
     setFlip: (shouldFlip: NgpFlip) => void;
     setPlacement: (newPlacement: NgpMenuPlacement) => void;
     setOffset: (newOffset: NgpOffset) => void;
+    setContainer: (newContainer: HTMLElement | string | null) => void;
     focus: (origin: FocusOrigin) => void;
-    setPointerOverContent: (_isOver: boolean) => void;
+    setPointerOverContent: (isOver: boolean) => void;
+    container: WritableSignal<string | HTMLElement | null>;
 };
 declare const injectSubmenuTriggerState: {
     (): Signal<{
@@ -840,8 +864,10 @@ declare const injectSubmenuTriggerState: {
         setFlip: (shouldFlip: NgpFlip) => void;
         setPlacement: (newPlacement: NgpMenuPlacement) => void;
         setOffset: (newOffset: NgpOffset) => void;
+        setContainer: (newContainer: HTMLElement | string | null) => void;
         focus: (origin: FocusOrigin) => void;
-        setPointerOverContent: (_isOver: boolean) => void;
+        setPointerOverContent: (isOver: boolean) => void;
+        container: WritableSignal<string | HTMLElement | null>;
     }>;
     (options: ng_primitives_state.StateInjectionOptions): Signal<{
         placement: WritableSignal<NgpMenuPlacement>;
@@ -859,8 +885,10 @@ declare const injectSubmenuTriggerState: {
         setFlip: (shouldFlip: NgpFlip) => void;
         setPlacement: (newPlacement: NgpMenuPlacement) => void;
         setOffset: (newOffset: NgpOffset) => void;
+        setContainer: (newContainer: HTMLElement | string | null) => void;
         focus: (origin: FocusOrigin) => void;
-        setPointerOverContent: (_isOver: boolean) => void;
+        setPointerOverContent: (isOver: boolean) => void;
+        container: WritableSignal<string | HTMLElement | null>;
     } | null>;
     (options?: ng_primitives_state.StateInjectionOptions): Signal<{
         placement: WritableSignal<NgpMenuPlacement>;
@@ -878,8 +906,10 @@ declare const injectSubmenuTriggerState: {
         setFlip: (shouldFlip: NgpFlip) => void;
         setPlacement: (newPlacement: NgpMenuPlacement) => void;
         setOffset: (newOffset: NgpOffset) => void;
+        setContainer: (newContainer: HTMLElement | string | null) => void;
         focus: (origin: FocusOrigin) => void;
-        setPointerOverContent: (_isOver: boolean) => void;
+        setPointerOverContent: (isOver: boolean) => void;
+        container: WritableSignal<string | HTMLElement | null>;
     }> | Signal<{
         placement: WritableSignal<NgpMenuPlacement>;
         offset: WritableSignal<NgpOffset>;
@@ -896,8 +926,10 @@ declare const injectSubmenuTriggerState: {
         setFlip: (shouldFlip: NgpFlip) => void;
         setPlacement: (newPlacement: NgpMenuPlacement) => void;
         setOffset: (newOffset: NgpOffset) => void;
+        setContainer: (newContainer: HTMLElement | string | null) => void;
         focus: (origin: FocusOrigin) => void;
-        setPointerOverContent: (_isOver: boolean) => void;
+        setPointerOverContent: (isOver: boolean) => void;
+        container: WritableSignal<string | HTMLElement | null>;
     } | null>;
 };
 declare const provideSubmenuTriggerState: (opts?: {

package/types/ng-primitives-portal.d.ts

@@ -102,6 +102,12 @@ interface CooldownOverlay {
     hideImmediate(): void;
     /** Optional signal to mark the transition as instant due to cooldown */
     instantTransition?: WritableSignal<boolean>;
+    /**
+     * Optional check for whether this overlay is a descendant of the given overlay
+     * (i.e. its trigger is rendered within the other overlay's content). Used to
+     * keep an ancestor open when a nested overlay of the same type is activated.
+     */
+    isDescendantOf?(other: CooldownOverlay): boolean;
 }
 /**
  * Singleton service that tracks close timestamps and active overlays per overlay type.
@@ -112,6 +118,13 @@ interface CooldownOverlay {
  */
 declare class NgpOverlayCooldownManager {
     private readonly lastCloseTimestamps;
+    /**
+     * Active overlays per type, stored as a stack ordered oldest-first / topmost-last.
+     * Most types only ever hold a single overlay, but when an overlay is nested inside
+     * another of the same type (e.g. a popover whose trigger lives inside another
+     * popover) the child is pushed on top of its ancestor instead of evicting it.
+     * Closing the child then restores the ancestor as the active overlay.
+     */
     private readonly activeOverlays;
     /**
      * Record the close timestamp for an overlay type.
@@ -127,7 +140,14 @@ declare class NgpOverlayCooldownManager {
     isWithinCooldown(overlayType: string, duration: number): boolean;
     /**
      * Register an overlay as active for its type.
-     * Any existing overlay of the same type will be closed immediately.
+     *
+     * Any existing overlay of the same type is closed immediately so that only one
+     * overlay of each type is open at a time - *unless* it is an ancestor of the
+     * overlay being registered. A nested overlay (its trigger rendered inside an
+     * ancestor overlay's content) is stacked on top of its ancestor instead of
+     * evicting it, allowing legitimate nesting to coexist while sibling overlays
+     * still replace one another.
+     *
      * @param overlayType The type identifier for the overlay group
      * @param overlay The overlay instance
      * @param cooldown The cooldown duration - if > 0, enables instant transitions
@@ -629,6 +649,16 @@ declare class NgpOverlay<T = unknown> implements CooldownOverlay {
      * @internal
      */
     unregisterChildOverlay(child: NgpOverlay): void;
+    /**
+     * Determine whether this overlay is a descendant of the given overlay - i.e.
+     * its trigger is rendered within the other overlay's content. Walks the parent
+     * overlay chain established through dependency injection.
+     *
+     * Used by the cooldown manager to avoid evicting an ancestor overlay when a
+     * nested overlay of the same type is activated.
+     * @internal
+     */
+    isDescendantOf(other: CooldownOverlay): boolean;
     /**
      * Check if the event path includes any child overlay elements (recursively).
      * @internal

package/types/ng-primitives-tooltip.d.ts

@@ -7,6 +7,8 @@ import { Placement } from '@floating-ui/dom';
 import { NumberInput, BooleanInput } from '@angular/cdk/coercion';
 import * as ng_primitives_state from 'ng-primitives/state';
 import { StateInjectionOptions } from 'ng-primitives/state';
+import * as ng_primitives_internal from 'ng-primitives/internal';
+import { HoverBridgePoint } from 'ng-primitives/internal';
 
 interface NgpTooltipConfig {
     /**
@@ -115,11 +117,6 @@ declare const provideTooltipArrowState: (opts?: {
     inherit?: boolean;
 }) => _angular_core.FactoryProvider;
 
-interface TooltipHoverBridgePoint {
-    x: number;
-    y: number;
-}
-
 interface NgpTooltipTriggerState<T> {
     /** Access the tooltip template ref. */
     readonly tooltip: WritableSignal<NgpOverlayContent<T> | string | null>;
@@ -240,7 +237,7 @@ interface NgpTooltipTriggerState<T> {
     /**
      * Current pointer grace polygon used while crossing trigger -> tooltip.
      */
-    readonly hoverBridgePolygon: Signal<TooltipHoverBridgePoint[] | null>;
+    readonly hoverBridgePolygon: Signal<HoverBridgePoint[] | null>;
     /**
      * Show the tooltip programmatically (skips cooldown so multiple tooltips can coexist).
      */
@@ -392,7 +389,7 @@ declare const NgpTooltipTriggerStateToken: _angular_core.InjectionToken<Writable
     open: Signal<boolean>;
     hasOverflow: Signal<boolean>;
     contentHovered: WritableSignal<boolean>;
-    hoverBridgePolygon: WritableSignal<TooltipHoverBridgePoint[] | null>;
+    hoverBridgePolygon: Signal<HoverBridgePoint[] | null>;
     show: () => void;
     hide: () => void;
     setTooltipId: (id: string) => void;
@@ -425,7 +422,7 @@ declare const ngpTooltipTrigger: <T>({ tooltip: _tooltip, disabled, placement, o
     open: Signal<boolean>;
     hasOverflow: Signal<boolean>;
     contentHovered: WritableSignal<boolean>;
-    hoverBridgePolygon: WritableSignal<TooltipHoverBridgePoint[] | null>;
+    hoverBridgePolygon: Signal<HoverBridgePoint[] | null>;
     show: () => void;
     hide: () => void;
     setTooltipId: (id: string) => void;
@@ -569,7 +566,7 @@ declare class NgpTooltipTrigger<T = null> implements OnDestroy {
         open: _angular_core.Signal<boolean>;
         hasOverflow: _angular_core.Signal<boolean>;
         contentHovered: _angular_core.WritableSignal<boolean>;
-        hoverBridgePolygon: _angular_core.WritableSignal<TooltipHoverBridgePoint[] | null>;
+        hoverBridgePolygon: _angular_core.Signal<ng_primitives_internal.HoverBridgePoint[] | null>;
         show: () => void;
         hide: () => void;
         setTooltipId: (id: string) => void;

package/types/ng-primitives-utils.d.ts

@@ -33,6 +33,11 @@ declare function booleanAttributeBinding(element: HTMLElement, attribute: string
  * Disposable functions are a way to manage timers, intervals, and event listeners
  * that should be cleared when a component is destroyed.
  *
+ * Each disposable releases its DestroyRef registration as soon as the resource
+ * is gone (the timer fires or the returned cleanup runs), so repeated calls -
+ * e.g. rescheduling a timeout on every pointermove - don't accumulate destroy
+ * callbacks for the lifetime of the host.
+ *
  * This is heavily inspired by Headless UI disposables:
  * https://github.com/tailwindlabs/headlessui/blob/main/packages/%40headlessui-react/src/utils/disposables.ts
  */
@@ -45,20 +50,18 @@ declare function injectDisposables(): {
      */
     setTimeout: (callback: () => void, delay: number) => () => void;
     /**
-     * Set an interval that will be cleared when the component is destroyed.
-     * @param callback The callback to execute
-     * @param delay The delay before the callback is executed
-     * @param target
-     * @param type
-     * @param listener
-     * @param options
-     * @returns A function to clear the interval
+     * Add an event listener that will be removed when the component is destroyed.
+     * @param target The event target
+     * @param type The event type
+     * @param listener The event listener
+     * @param options The event listener options
+     * @returns A function to remove the event listener
      */
     addEventListener: <K extends keyof HTMLElementEventMap>(target: EventTarget, type: K, listener: (this: HTMLElement, ev: HTMLElementEventMap[K]) => any, options?: boolean | AddEventListenerOptions) => () => void;
     /**
      * Set an interval that will be cleared when the component is destroyed.
      * @param callback The callback to execute
-     * @param delay The delay before the callback is executed
+     * @param delay The delay between executions
      * @returns A function to clear the interval
      */
     setInterval: (callback: () => void, delay: number) => () => void;