@cdevhub/ngx-tw 0.2.0

package/fesm2022/cdevhub-ngx-tw-core.mjs

@@ -0,0 +1,861 @@
+import * as i0 from '@angular/core';
+import { InjectionToken, inject, DestroyRef, signal, Injectable, computed, EventEmitter } from '@angular/core';
+import { filter, takeUntil } from 'rxjs/operators';
+import { FocusTrapFactory, _IdGenerator } from '@angular/cdk/a11y';
+import { Overlay } from '@angular/cdk/overlay';
+import { ComponentPortal } from '@angular/cdk/portal';
+import { Subject } from 'rxjs';
+import { tv } from 'tailwind-variants';
+
+/**
+ * Default error-state strategy: errored when the control is `invalid` and
+ * either has been interacted with (`dirty` or `touched`) or its parent form
+ * has been submitted. Matches Material's default behavior.
+ */
+const defaultErrorStateMatcher = {
+    isErrorState(control, form) {
+        if (!control) {
+            return false;
+        }
+        const interacted = control.dirty || control.touched;
+        return !!control.invalid && (interacted || !!form?.submitted);
+    },
+};
+/**
+ * Injection token carrying the {@link ErrorStateMatcher} used by every ngx-tw
+ * form control. Defaults to {@link defaultErrorStateMatcher}; provide a
+ * different matcher at root to change global error-display policy, or at any
+ * descendant injector to scope the change.
+ */
+const TW_ERROR_STATE_MATCHER = new InjectionToken('TW_ERROR_STATE_MATCHER', {
+    providedIn: 'root',
+    factory: () => defaultErrorStateMatcher,
+});
+
+/**
+ * DI token through which sort containers expose their state to consumers. Provided by
+ * `SortDirective` (`[twSort]`). Inject with `{ optional: true }` — components that need
+ * aria-sort plumbing should degrade gracefully when no sort directive is present.
+ */
+const TW_SORT_HANDLE = new InjectionToken('TwSortHandle');
+
+/**
+ * Connected-overlay position list for "select-like" overlays — overlays whose
+ * panel attaches directly under (or above) a trigger element and falls back to
+ * the opposite vertical side when there is not enough room. Returns four
+ * fallback positions: below-start, below-end, above-start, above-end.
+ *
+ * Used by `SelectComponent`, `ComboboxComponent`, `DatePickerComponent`, and
+ * `DateRangePickerComponent` — any overlay-bearing form control that anchors
+ * a listbox / menu / calendar panel to its trigger. The shape is identical for
+ * all four; the historical "select-like" name refers to the original consumer.
+ *
+ * @param offset Vertical offset in pixels applied between the trigger edge and
+ *   the panel edge. Below-positions use `+offset`; above-positions use
+ *   `-offset` so the panel pulls away from the trigger consistently.
+ */
+function buildSelectLikePositions(offset = 0) {
+    return [
+        { originX: 'start', originY: 'bottom', overlayX: 'start', overlayY: 'top', offsetY: offset },
+        { originX: 'end', originY: 'bottom', overlayX: 'end', overlayY: 'top', offsetY: offset },
+        { originX: 'start', originY: 'top', overlayX: 'start', overlayY: 'bottom', offsetY: -offset },
+        { originX: 'end', originY: 'top', overlayX: 'end', overlayY: 'bottom', offsetY: -offset },
+    ];
+}
+
+/**
+ * Maps a named scroll-strategy variant to the corresponding CDK
+ * `ScrollStrategy` instance. `'reposition'` is the default for select-like
+ * overlays; `'close'` dismisses the panel on scroll; `'block'` locks page
+ * scrolling while the panel is open.
+ *
+ * Used by `SelectComponent`, `ComboboxComponent`, `DatePickerComponent`, and
+ * `DateRangePickerComponent` — any overlay-bearing form control that exposes
+ * the same three-option scroll-strategy input.
+ */
+function resolveSelectScrollStrategy(name, overlay) {
+    switch (name) {
+        case 'close':
+            return overlay.scrollStrategies.close();
+        case 'block':
+            return overlay.scrollStrategies.block();
+        default:
+            return overlay.scrollStrategies.reposition();
+    }
+}
+
+/**
+ * Subscribes to overlay-level `Escape` keydown events and invokes `onEscape`
+ * for each one. Returns an unsubscribe function so callers can scope teardown
+ * to the open lifecycle of the overlay (typically tied into a `Subscription`
+ * aggregate or a `takeUntilDestroyed` flow).
+ *
+ * Listens via `OverlayRef.keydownEvents()` so the handler fires for any
+ * keystroke originating inside the overlay, regardless of which element holds
+ * DOM focus — useful for select-style overlays whose search/listbox children
+ * may receive focus apart from the trigger.
+ *
+ * Callers remain responsible for calling `event.preventDefault()` /
+ * `stopPropagation()` inside `onEscape` if they want to short-circuit further
+ * key handling.
+ */
+function consumeOverlayEscape(overlayRef, onEscape) {
+    const subscription = overlayRef
+        .keydownEvents()
+        .pipe(filter((event) => event.key === 'Escape'))
+        .subscribe((event) => onEscape(event));
+    return () => subscription.unsubscribe();
+}
+
+/**
+ * Enter-animation duration for date-picker / date-range-picker overlays.
+ * Matches `theme/_base.css` `.scale-in 140ms` — the keyframe the picker
+ * overlays apply via `animate.enter="scale-in"`. The coordinator delays
+ * `opened$` emission by this duration so consumers can hook the moment the
+ * panel has fully appeared instead of the moment `open()` was called.
+ */
+const PICKER_ENTER_DURATION = 140;
+/**
+ * Leave-animation duration for date-picker / date-range-picker overlays.
+ * Matches `theme/_base.css` `.scale-out 120ms` — the keyframe the picker
+ * overlays apply via `animate.leave="scale-out"`. The coordinator delays
+ * overlay detach by this duration so the leave animation can play through.
+ */
+const PICKER_LEAVE_DURATION = 120;
+/**
+ * Coordinator that owns the CDK `OverlayRef`, focus trap, panel-id, and
+ * animation timing for an overlay-bearing form control. Consumed by
+ * `DatePickerComponent` and `DateRangePickerComponent`; both pickers register
+ * the coordinator at the component level (`providers: [PickerOverlayCoordinator]`)
+ * so each picker instance owns its own coordinator state.
+ *
+ * Per the library "no `providedIn: 'root'` for services" rule (see
+ * `.claude/CLAUDE.md` → "What NOT To Do"): the coordinator holds per-overlay
+ * `OverlayRef` / `FocusTrap` state and MUST be component-scoped.
+ *
+ * Scope of responsibility:
+ * - Create / dispose the CDK `OverlayRef`.
+ * - Attach a `ComponentPortal` and return the instance.
+ * - Set up / tear down a `FocusTrap` around the overlay element.
+ * - Emit `opened$` after the enter animation completes (closes the
+ *   synchronous-emit bug previously present in both pickers).
+ * - Expose `backdropClick$` / `overlayKeydown$` / `escape$` streams scoped
+ *   to the current open lifecycle.
+ * - Run a leave-animation timer with an `isAttached` guard so close races
+ *   never touch a detached `OverlayRef` (mirrors the S14 command-palette
+ *   pattern).
+ *
+ * Out of scope (stays in the consuming picker):
+ * - "Restore previous value on close" — semantics differ per picker.
+ * - Per-picker portal callbacks (calendar selection, action-bar buttons).
+ * - View-mode change-detection nudges (the range-picker calls
+ *   `changeDetectorRef.detectChanges()` after pushing its initial overlay
+ *   config; the date-picker does not).
+ */
+class PickerOverlayCoordinator {
+    overlay = inject(Overlay);
+    focusTrapFactory = inject(FocusTrapFactory);
+    destroyRef = inject(DestroyRef);
+    idGenerator = inject(_IdGenerator);
+    overlayRef = null;
+    focusTrap = null;
+    closeTimer = null;
+    openedTimer = null;
+    currentPanelId = null;
+    currentClose$ = null;
+    openedSubject = null;
+    attachedSignal = signal(false, ...(ngDevMode ? [{ debugName: "attachedSignal" }] : /* istanbul ignore next */ []));
+    openedSignal = signal(false, ...(ngDevMode ? [{ debugName: "openedSignal" }] : /* istanbul ignore next */ []));
+    /** Whether the overlay is currently attached (between `open()` and detach). */
+    attached = this.attachedSignal.asReadonly();
+    /** Whether the enter animation has completed (`opened$` has fired). */
+    opened = this.openedSignal.asReadonly();
+    constructor() {
+        this.destroyRef.onDestroy(() => this.disposeImmediate());
+    }
+    /**
+     * Creates and attaches the overlay. Returns the live overlay metadata
+     * synchronously; callers should subscribe to {@link opened$} to observe the
+     * moment the enter animation completes. Returns `null` if an overlay is
+     * already attached.
+     */
+    open(config) {
+        if (this.overlayRef)
+            return null;
+        const positionStrategy = this.overlay
+            .position()
+            .flexibleConnectedTo(config.origin)
+            .withPositions(config.positions)
+            .withFlexibleDimensions(false)
+            .withPush(false)
+            .withViewportMargin(config.viewportMargin ?? 8);
+        this.overlayRef = this.overlay.create({
+            positionStrategy,
+            scrollStrategy: config.scrollStrategy,
+            hasBackdrop: true,
+            backdropClass: 'cdk-overlay-transparent-backdrop',
+            panelClass: config.panelClass,
+        });
+        const portal = new ComponentPortal(config.portalComponent, config.viewContainerRef, config.injector);
+        const ref = this.overlayRef.attach(portal);
+        const instance = ref.instance;
+        this.currentPanelId = this.idGenerator.getId('tw-picker-overlay-');
+        this.currentClose$ = new Subject();
+        this.openedSubject = new Subject();
+        this.attachedSignal.set(true);
+        this.openedSignal.set(false);
+        this.setupFocusTrap();
+        this.scheduleOpenedEmission();
+        return {
+            overlayRef: this.overlayRef,
+            componentRef: ref,
+            instance,
+            panelId: this.currentPanelId,
+        };
+    }
+    /**
+     * Starts the close sequence — destroys the focus trap immediately so focus
+     * can return to the trigger, then detaches the overlay after the leave
+     * animation runs ({@link PICKER_LEAVE_DURATION}). Invokes `onAfterClose`
+     * once the overlay is fully detached. No-op if no overlay is open or a
+     * close is already in flight.
+     *
+     * Mirrors the S14 command-palette `isAttached`-guarded close pattern:
+     * after the timer fires we re-check `attachedSignal` before touching the
+     * overlay so a race (programmatic dispose, double-close) cannot touch a
+     * destroyed instance.
+     */
+    close(onAfterClose = () => { }) {
+        if (!this.overlayRef || this.closeTimer !== null)
+            return;
+        this.destroyFocusTrap();
+        this.clearOpenedTimer();
+        this.closeTimer = setTimeout(() => {
+            this.closeTimer = null;
+            if (!this.attachedSignal()) {
+                // Lost race with disposeImmediate / destroyRef.onDestroy.
+                return;
+            }
+            if (this.overlayRef?.hasAttached()) {
+                this.overlayRef.detach();
+            }
+            // Dispose the OverlayRef so the next open() builds a fresh one with the
+            // current inputs (offset, scrollStrategy, panelClass). Without this the
+            // `if (this.overlayRef) return null;` guard at the top of open() would
+            // permanently block re-opens after the first close.
+            this.overlayRef?.dispose();
+            this.overlayRef = null;
+            this.currentClose$?.next();
+            this.currentClose$?.complete();
+            this.currentClose$ = null;
+            this.openedSubject?.complete();
+            this.openedSubject = null;
+            this.attachedSignal.set(false);
+            this.openedSignal.set(false);
+            this.currentPanelId = null;
+            onAfterClose();
+        }, PICKER_LEAVE_DURATION);
+    }
+    /**
+     * Stream of overlay-level backdrop clicks for the current open lifecycle.
+     * Completes when the overlay closes.
+     */
+    backdropClick$() {
+        this.assertOpen('backdropClick$');
+        return this.overlayRef.backdropClick().pipe(takeUntil(this.currentClose$));
+    }
+    /**
+     * Stream of overlay-level keydown events for the current open lifecycle.
+     * Completes when the overlay closes.
+     */
+    overlayKeydown$() {
+        this.assertOpen('overlayKeydown$');
+        return this.overlayRef.keydownEvents().pipe(takeUntil(this.currentClose$));
+    }
+    /**
+     * Stream filtered to `Escape` keydowns inside the overlay for the current
+     * open lifecycle. Equivalent to `overlayKeydown$().pipe(filter(e => e.key === 'Escape'))`
+     * but spelled out so consumers don't import RxJS operators just for the
+     * common case.
+     */
+    escape$() {
+        return this.overlayKeydown$().pipe(filter((e) => e.key === 'Escape'));
+    }
+    /**
+     * Emits exactly once after the enter animation completes
+     * ({@link PICKER_ENTER_DURATION}ms after `open()`). Used by consumers to
+     * fire their `opened` output at the moment the overlay panel is actually
+     * visible — closes the synchronous-emit bug the pickers carried before
+     * this coordinator existed.
+     *
+     * Completes when the overlay closes.
+     */
+    opened$() {
+        this.assertOpen('opened$');
+        return this.openedSubject.asObservable().pipe(takeUntil(this.currentClose$));
+    }
+    /** Exposes the live `OverlayRef` for advanced consumers (e.g. width sync). */
+    ref() {
+        return this.overlayRef;
+    }
+    /**
+     * Exposes the current panel id (auto-generated via CDK `_IdGenerator`,
+     * stable for the open lifecycle, reset to `null` on close). Neither
+     * consuming picker uses this today — both keep their own
+     * `${hostId}-dialog` id for `aria-controls` wiring — but the helper is
+     * exposed for future consumers (e.g. a picker wrapper that wants its
+     * panel id auto-managed).
+     */
+    panelId() {
+        return this.currentPanelId;
+    }
+    /**
+     * Immediately disposes the overlay and tears down the focus trap without
+     * running the leave animation. Called from {@link DestroyRef.onDestroy};
+     * consumers should NOT call this — use {@link close} for the user-visible
+     * close path.
+     */
+    disposeImmediate() {
+        this.clearCloseTimer();
+        this.clearOpenedTimer();
+        this.destroyFocusTrap();
+        if (this.currentClose$) {
+            this.currentClose$.next();
+            this.currentClose$.complete();
+            this.currentClose$ = null;
+        }
+        this.openedSubject?.complete();
+        this.openedSubject = null;
+        this.overlayRef?.dispose();
+        this.overlayRef = null;
+        this.attachedSignal.set(false);
+        this.openedSignal.set(false);
+        this.currentPanelId = null;
+    }
+    setupFocusTrap() {
+        if (!this.overlayRef)
+            return;
+        this.focusTrap = this.focusTrapFactory.create(this.overlayRef.overlayElement);
+    }
+    destroyFocusTrap() {
+        this.focusTrap?.destroy();
+        this.focusTrap = null;
+    }
+    scheduleOpenedEmission() {
+        this.clearOpenedTimer();
+        if (!this.overlayRef || !this.overlayRef.hasAttached())
+            return;
+        this.openedTimer = setTimeout(() => {
+            this.openedTimer = null;
+            if (!this.attachedSignal())
+                return;
+            this.openedSignal.set(true);
+            this.openedSubject?.next();
+        }, PICKER_ENTER_DURATION);
+    }
+    clearCloseTimer() {
+        if (this.closeTimer !== null) {
+            clearTimeout(this.closeTimer);
+            this.closeTimer = null;
+        }
+    }
+    clearOpenedTimer() {
+        if (this.openedTimer !== null) {
+            clearTimeout(this.openedTimer);
+            this.openedTimer = null;
+        }
+    }
+    assertOpen(method) {
+        if (!this.overlayRef || !this.currentClose$ || !this.openedSubject) {
+            throw new Error(`PickerOverlayCoordinator.${method}() called before open() — no overlay attached.`);
+        }
+    }
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.14", ngImport: i0, type: PickerOverlayCoordinator, deps: [], target: i0.ɵɵFactoryTarget.Injectable });
+    static ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "21.2.14", ngImport: i0, type: PickerOverlayCoordinator });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.14", ngImport: i0, type: PickerOverlayCoordinator, decorators: [{
+            type: Injectable
+        }], ctorParameters: () => [] });
+
+/**
+ * Pure helpers shared by `DialogContainer` and `SheetContainer` (both live
+ * under `projects/ngx-tw/{dialog,sheet}/`) — and consumable by any future
+ * `CdkDialogContainer` subclass that needs the same plumbing.
+ *
+ * No DOM, no Angular DI. The DI-bound state lives in
+ * {@link OverlayContainerCoordinator}; this file is the data-only layer.
+ */
+/**
+ * Fallback padding (ms) added on top of an enter/exit animation duration when
+ * scheduling the `transitionend` fallback timer. The browser SHOULD fire
+ * `transitionend` at the configured duration, but transitions can be
+ * swallowed (focus changes during the animation, interrupted transitions,
+ * etc.) — the padding gives the browser a small grace period before our
+ * fallback runs.
+ *
+ * Both dialog and sheet containers used the same constant — extracted here so
+ * a future tweak applies to both at once.
+ */
+const OVERLAY_ANIMATION_FALLBACK_PADDING = 50;
+/**
+ * Coerces a user-supplied animation duration to a safe positive integer, or
+ * falls back to a default if the input is `null`, `undefined`, negative, or
+ * non-finite (`NaN`, `Infinity`). Dialog and sheet containers both used this
+ * same standalone function; centralised here.
+ */
+function coerceOverlayDuration(value, fallback) {
+    if (value == null || value < 0 || !Number.isFinite(value))
+        return fallback;
+    return value;
+}
+/**
+ * Merges a consumer-supplied `panelClass` (single class, list, or
+ * `undefined`) with the container's internal class string. Returns a single
+ * space-separated class string suitable for `[class]` host binding.
+ *
+ * `consumer` always wins ordering (appended after `internal`) so consumer
+ * overrides resolve correctly through `tailwind-merge` upstream.
+ */
+function mergeOverlayPanelClass(internal, consumer) {
+    if (!consumer)
+        return internal;
+    return Array.isArray(consumer) ? [internal, ...consumer].join(' ') : `${internal} ${consumer}`;
+}
+/**
+ * Append-only id list with idempotent insertion, used for the
+ * `aria-describedby` queue both `DialogContainer` and `SheetContainer`
+ * maintain (the matching `aria-labelledby` queue lives in CDK's
+ * `CdkDialogContainer`).
+ *
+ * Pure data structure — no DOM, no Angular signals. Consumers wrap an
+ * instance in their own change-detection mechanism (the
+ * {@link OverlayContainerCoordinator} keeps the live snapshot in a signal so
+ * the container's `[attr.aria-describedby]` binding refreshes via OnPush
+ * without a manual `markForCheck()`).
+ *
+ * First-registered-wins semantics for `first()` mirror CDK's
+ * `_ariaLabelledByQueue[0]` host binding — describing the dialog by the
+ * earliest registered description prevents a late-mounted nested directive
+ * from silently re-aiming the description target.
+ */
+class AriaIdQueue {
+    ids = [];
+    /** Inserts an id at the tail. No-op if the id is already present. */
+    add(id) {
+        if (this.ids.includes(id))
+            return;
+        this.ids.push(id);
+    }
+    /** Removes the given id. No-op if the id is not present. */
+    remove(id) {
+        const index = this.ids.indexOf(id);
+        if (index >= 0)
+            this.ids.splice(index, 1);
+    }
+    /** First registered id (or `null` if empty). Matches CDK's `_ariaLabelledByQueue[0]` semantics. */
+    first() {
+        return this.ids[0] ?? null;
+    }
+    /** Returns a fresh snapshot of all registered ids in insertion order. */
+    snapshot() {
+        return [...this.ids];
+    }
+}
+
+/**
+ * Component-scoped coordinator that owns the enter/exit animation state
+ * machine, ARIA-describedby id queue, and panel-class merge for an overlay
+ * container that subclasses `@angular/cdk/dialog`'s `CdkDialogContainer`.
+ *
+ * Consumed by `DialogContainer` and `SheetContainer`; both register the
+ * coordinator at the component level (`providers: [OverlayContainerCoordinator]`)
+ * so each container instance owns its own animation state and queue.
+ *
+ * Per the library "no `providedIn: 'root'` for services" rule (see
+ * `.claude/CLAUDE.md` → "What NOT To Do"): the coordinator holds per-overlay
+ * state (the current animation timer, the describedby queue, the lifecycle
+ * signal) and MUST be component-scoped.
+ *
+ * Scope of responsibility:
+ * - Animation state signal (`state`) and `transitionDuration` computed.
+ * - Enter/exit animation timing (`startEnterAnimation`, `startExitAnimation`)
+ *   with a `transitionend`-fallback timer.
+ * - `animationStateChanged` EventEmitter forwarded to the consuming `Ref`.
+ * - ARIA-describedby id queue (the matching labelledby queue is already
+ *   owned by CDK's `CdkDialogContainer._ariaLabelledByQueue`).
+ *
+ * Out of scope (stays on the container subclass):
+ * - The `CdkDialogContainer` contract — focus trap, escape key, backdrop
+ *   click, overlay attach/detach. The container subclass keeps inheriting
+ *   `CdkDialogContainer` directly; this coordinator layers on top.
+ * - Tailwind class resolution (`tv()` variant slots) — that's per-container.
+ * - Host bindings on the container element — that's per-container.
+ */
+class OverlayContainerCoordinator {
+    destroyRef = inject(DestroyRef);
+    stateSignal = signal('opening', ...(ngDevMode ? [{ debugName: "stateSignal" }] : /* istanbul ignore next */ []));
+    ariaDescribedByQueue = signal([], ...(ngDevMode ? [{ debugName: "ariaDescribedByQueue" }] : /* istanbul ignore next */ []));
+    queue = new AriaIdQueue();
+    animationTimer = null;
+    enterDuration = 0;
+    exitDuration = 0;
+    /** Lifecycle state of the container's enter/exit animation. */
+    state = this.stateSignal.asReadonly();
+    /** Live snapshot of the describedby id queue. */
+    describedByIds = this.ariaDescribedByQueue.asReadonly();
+    /**
+     * Active transition duration for the current state — the enter duration for
+     * `opening` / `open`, the exit duration for `closing`, and 0 once `closed`.
+     * Drives the container's `[style.transition-duration.ms]` host binding so a
+     * one-line `data-[state]` transition rule can run with per-call timing.
+     */
+    transitionDuration = computed(() => {
+        const current = this.stateSignal();
+        if (current === 'opening' || current === 'open')
+            return this.enterDuration;
+        if (current === 'closing')
+            return this.exitDuration;
+        return 0;
+    }, ...(ngDevMode ? [{ debugName: "transitionDuration" }] : /* istanbul ignore next */ []));
+    /**
+     * Emits whenever the animation state transitions. The container's `Ref`
+     * (`TwDialogRef` / `SheetRef`) subscribes to drive its own lifecycle
+     * (`afterOpened`, `afterClosed`, exit-animation completion).
+     */
+    animationStateChanged = new EventEmitter();
+    constructor() {
+        this.destroyRef.onDestroy(() => {
+            this.clearAnimationTimer();
+            this.animationStateChanged.complete();
+        });
+    }
+    /**
+     * Records the resolved enter/exit durations for the open lifecycle.
+     * Called once from the container constructor with values coerced via
+     * `coerceOverlayDuration`. Stored on the coordinator so
+     * `transitionDuration()` and the timer-driven state transitions read from
+     * a single source.
+     */
+    setDurations(enter, exit) {
+        this.enterDuration = enter;
+        this.exitDuration = exit;
+    }
+    /**
+     * Drives the enter animation: emits `opening` immediately, then defers the
+     * state flip to `open` by one frame so the browser applies the initial
+     * (hidden / off-screen) styles before transitioning. If `enter` is `0`
+     * everything resolves synchronously (no animation).
+     */
+    startEnterAnimation() {
+        this.animationStateChanged.emit({ state: 'opening', totalTime: this.enterDuration });
+        if (this.enterDuration === 0) {
+            this.stateSignal.set('open');
+            this.animationStateChanged.emit({ state: 'open', totalTime: 0 });
+            return;
+        }
+        requestAnimationFrame(() => {
+            this.stateSignal.set('open');
+            this.runAnimationTimer(this.enterDuration, () => {
+                this.animationStateChanged.emit({
+                    state: 'open',
+                    totalTime: this.enterDuration,
+                });
+            });
+        });
+    }
+    /**
+     * Drives the exit animation: emits `closing` synchronously and schedules
+     * the `closed` emission for after the exit duration (+ a small fallback
+     * padding) elapses. The consuming `Ref` listens for the `closed` emission
+     * to detach the CDK overlay.
+     */
+    startExitAnimation() {
+        this.stateSignal.set('closing');
+        this.animationStateChanged.emit({ state: 'closing', totalTime: this.exitDuration });
+        this.runAnimationTimer(this.exitDuration, () => {
+            this.stateSignal.set('closed');
+            this.animationStateChanged.emit({ state: 'closed', totalTime: this.exitDuration });
+        });
+    }
+    /** Registers a description id with the `aria-describedby` queue. */
+    addAriaDescribedBy(id) {
+        this.queue.add(id);
+        this.ariaDescribedByQueue.set(this.queue.snapshot());
+    }
+    /** Removes a previously registered description id. */
+    removeAriaDescribedBy(id) {
+        this.queue.remove(id);
+        this.ariaDescribedByQueue.set(this.queue.snapshot());
+    }
+    /** First-registered-wins resolution for the `aria-describedby` attribute. */
+    firstDescribedBy() {
+        return this.queue.first();
+    }
+    runAnimationTimer(duration, callback) {
+        this.clearAnimationTimer();
+        if (duration === 0) {
+            callback();
+            return;
+        }
+        this.animationTimer = setTimeout(callback, duration + OVERLAY_ANIMATION_FALLBACK_PADDING);
+    }
+    clearAnimationTimer() {
+        if (this.animationTimer !== null) {
+            clearTimeout(this.animationTimer);
+            this.animationTimer = null;
+        }
+    }
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.14", ngImport: i0, type: OverlayContainerCoordinator, deps: [], target: i0.ɵɵFactoryTarget.Injectable });
+    static ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "21.2.14", ngImport: i0, type: OverlayContainerCoordinator });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.14", ngImport: i0, type: OverlayContainerCoordinator, decorators: [{
+            type: Injectable
+        }], ctorParameters: () => [] });
+
+/**
+ * Trigger-only tailwind-variants config shared by tabs and tab-nav.
+ *
+ * Both components own additional component-local slots (tablist/list/panel/nav,
+ * etc.) — only the trigger shape is canonical enough to share here. The
+ * resulting class string is merged with each component's local trigger
+ * additions (e.g. tab-nav prepends `no-underline` because anchor elements need
+ * to override the default underline; tabs adds nothing extra at the base).
+ *
+ * Active and inactive trigger state is applied separately via
+ * {@link getActiveTriggerClasses} / {@link getInactiveTriggerClasses} so the
+ * `Record<TwColor, string>` lookups stay statically scannable by the Tailwind
+ * v4 content scanner.
+ */
+const tabTriggerVariants = tv({
+    slots: {
+        trigger: 'inline-flex items-center gap-1.5 font-medium whitespace-nowrap cursor-pointer transition-colors duration-normal motion-reduce:transition-none focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-primary-500',
+    },
+    variants: {
+        variant: {
+            underline: {
+                trigger: 'border-b-2 border-transparent -mb-px text-fg-muted hover:text-fg',
+            },
+            enclosed: {
+                trigger: 'border border-transparent bg-surface-muted text-fg-muted hover:text-fg -mb-px',
+            },
+            pill: {
+                trigger: 'rounded-md text-fg-muted hover:text-fg',
+            },
+        },
+        size: {
+            xs: { trigger: 'px-2 py-1 text-xs' },
+            sm: { trigger: 'px-3 py-1.5 text-sm' },
+            md: { trigger: 'px-4 py-2 text-sm' },
+            lg: { trigger: 'px-5 py-2.5 text-base' },
+            xl: { trigger: 'px-6 py-3 text-base' },
+        },
+        fitted: {
+            true: { trigger: 'flex-1 justify-center' },
+            false: {},
+        },
+        color: {
+            primary: {},
+            secondary: {},
+            accent: {},
+            neutral: {},
+            info: {},
+            success: {},
+            warning: {},
+            error: {},
+        },
+    },
+    defaultVariants: {
+        variant: 'underline',
+        color: 'primary',
+        size: 'md',
+        fitted: false,
+    },
+}, { twMerge: true });
+// ── Active-state class lookups ──
+// Slot tokens own light/dark contrast — no `dark:`, no shade picks. Classes
+// stay statically written so the Tailwind v4 scanner sees them. The neutral
+// rows use surface/fg/border tokens which already auto-adapt to dark mode.
+/** @internal Active trigger classes for horizontal underline variants, keyed by color. */
+const UNDERLINE_ACTIVE_HORIZONTAL = {
+    primary: 'border-b-2 border-primary-border-strong text-primary-fg',
+    secondary: 'border-b-2 border-secondary-border-strong text-secondary-fg',
+    accent: 'border-b-2 border-accent-border-strong text-accent-fg',
+    neutral: 'border-b-2 border-border-strong text-fg',
+    info: 'border-b-2 border-info-border-strong text-info-fg',
+    success: 'border-b-2 border-success-border-strong text-success-fg',
+    warning: 'border-b-2 border-warning-border-strong text-warning-fg',
+    error: 'border-b-2 border-error-border-strong text-error-fg',
+};
+/** @internal Active trigger classes for vertical underline variants, keyed by color. */
+const UNDERLINE_ACTIVE_VERTICAL = {
+    primary: 'border-r-2 border-primary-border-strong text-primary-fg',
+    secondary: 'border-r-2 border-secondary-border-strong text-secondary-fg',
+    accent: 'border-r-2 border-accent-border-strong text-accent-fg',
+    neutral: 'border-r-2 border-border-strong text-fg',
+    info: 'border-r-2 border-info-border-strong text-info-fg',
+    success: 'border-r-2 border-success-border-strong text-success-fg',
+    warning: 'border-r-2 border-warning-border-strong text-warning-fg',
+    error: 'border-r-2 border-error-border-strong text-error-fg',
+};
+/** @internal Active trigger classes for horizontal enclosed variants, keyed by color. */
+const ENCLOSED_ACTIVE_HORIZONTAL = {
+    primary: 'bg-surface border border-border border-b-transparent text-primary-fg',
+    secondary: 'bg-surface border border-border border-b-transparent text-secondary-fg',
+    accent: 'bg-surface border border-border border-b-transparent text-accent-fg',
+    neutral: 'bg-surface border border-border border-b-transparent text-fg',
+    info: 'bg-surface border border-border border-b-transparent text-info-fg',
+    success: 'bg-surface border border-border border-b-transparent text-success-fg',
+    warning: 'bg-surface border border-border border-b-transparent text-warning-fg',
+    error: 'bg-surface border border-border border-b-transparent text-error-fg',
+};
+/** @internal Active trigger classes for vertical enclosed variants, keyed by color. */
+const ENCLOSED_ACTIVE_VERTICAL = {
+    primary: 'bg-surface border border-border border-r-transparent text-primary-fg',
+    secondary: 'bg-surface border border-border border-r-transparent text-secondary-fg',
+    accent: 'bg-surface border border-border border-r-transparent text-accent-fg',
+    neutral: 'bg-surface border border-border border-r-transparent text-fg',
+    info: 'bg-surface border border-border border-r-transparent text-info-fg',
+    success: 'bg-surface border border-border border-r-transparent text-success-fg',
+    warning: 'bg-surface border border-border border-r-transparent text-warning-fg',
+    error: 'bg-surface border border-border border-r-transparent text-error-fg',
+};
+/** @internal Active trigger classes for pill variants, keyed by color. */
+const PILL_ACTIVE = {
+    primary: 'bg-surface shadow-sm text-primary-fg',
+    secondary: 'bg-surface shadow-sm text-secondary-fg',
+    accent: 'bg-surface shadow-sm text-accent-fg',
+    neutral: 'bg-surface shadow-sm text-fg',
+    info: 'bg-surface shadow-sm text-info-fg',
+    success: 'bg-surface shadow-sm text-success-fg',
+    warning: 'bg-surface shadow-sm text-warning-fg',
+    error: 'bg-surface shadow-sm text-error-fg',
+};
+/** @internal Inactive trigger classes keyed by variant. */
+const INACTIVE_TRIGGER_CLASSES = {
+    underline: 'border-transparent',
+    enclosed: 'border-transparent bg-surface-muted',
+    pill: '',
+};
+/**
+ * Returns the active-state trigger class string for the given variant, color,
+ * and orientation. Tab-nav callers pass `'horizontal'` since it is horizontal-only.
+ */
+function getActiveTriggerClasses(variant, color, orientation = 'horizontal') {
+    switch (variant) {
+        case 'underline':
+            return orientation === 'vertical'
+                ? UNDERLINE_ACTIVE_VERTICAL[color]
+                : UNDERLINE_ACTIVE_HORIZONTAL[color];
+        case 'enclosed':
+            return orientation === 'vertical'
+                ? ENCLOSED_ACTIVE_VERTICAL[color]
+                : ENCLOSED_ACTIVE_HORIZONTAL[color];
+        case 'pill':
+            return PILL_ACTIVE[color];
+    }
+}
+/** Returns the inactive-state trigger class string for the given variant. */
+function getInactiveTriggerClasses(variant) {
+    return INACTIVE_TRIGGER_CLASSES[variant];
+}
+
+/**
+ * Pure helpers shared by `tw-time-picker` and `tw-calendar`'s `withTime`
+ * controls. No Angular / CDK imports — safe to drop into either package
+ * without pulling a circular dependency.
+ */
+/** Zero-pads a non-negative integer to exactly two digits. */
+function padTwo(value) {
+    return value < 10 ? `0${value}` : `${value}`;
+}
+/** Converts a 24h hour (0–23) to its 12h display value (1–12). */
+function to12h(hour24) {
+    const modded = hour24 % 12;
+    return modded === 0 ? 12 : modded;
+}
+/** Builds a canonical 0–23 hour from a 12h display hour and meridiem. */
+function from12h(hour12, meridiem) {
+    if (hour12 === 12)
+        return meridiem === 'AM' ? 0 : 12;
+    return meridiem === 'AM' ? hour12 : hour12 + 12;
+}
+/** Maximum allowed value for a field given the picker format. */
+function fieldMax(field, format) {
+    if (field === 'hour')
+        return format === '12h' ? 12 : 23;
+    return 59;
+}
+/** Minimum allowed value for a field given the picker format. */
+function fieldMin(field, format) {
+    return field === 'hour' && format === '12h' ? 1 : 0;
+}
+/**
+ * Buffers a typed digit onto the current field text, matching the standard
+ * two-digit time-field behaviour:
+ *   - empty + 'x'       → 'x'
+ *   - 'x' + 'y'         → 'xy' (if value stays in range)
+ *   - 'xy' + 'z'        → 'z' (overflow → reset)
+ *   - any combo that would exceed `max` resets to the new digit alone.
+ */
+function appendDigit(current, digit, max) {
+    if (!/^\d$/.test(digit))
+        return current;
+    if (current.length >= 2)
+        return digit;
+    const candidate = current + digit;
+    const numeric = Number(candidate);
+    if (numeric > max)
+        return digit;
+    return candidate;
+}
+/**
+ * Reports whether `current` + `digit` unambiguously fills the field — either
+ * because the buffer reaches two chars or because the first digit alone
+ * already excludes a valid second digit (e.g., `'6'` for minutes, `'3'` for 24h
+ * hour). Used to auto-advance focus to the next field.
+ */
+function isTerminalDigit(current, digit, max) {
+    if (current.length === 1)
+        return true;
+    if (!/^\d$/.test(digit))
+        return false;
+    const maxFirst = Math.floor(max / 10);
+    return Number(digit) > maxFirst;
+}
+/**
+ * Steps a numeric value by `step`, wrapping inside `[min, max]`. Works for
+ * arbitrary step sizes; a step of 0 behaves as 1 to protect against mis-configs.
+ */
+function stepWithWrap(value, step, direction, min, max) {
+    const safeStep = Math.max(1, Math.abs(step));
+    const range = max - min + 1;
+    const delta = safeStep * direction;
+    return ((((value - min + delta) % range) + range) % range) + min;
+}
+/** Clamps a number into `[min, max]` without wrapping. */
+function clamp(value, min, max) {
+    if (value < min)
+        return min;
+    if (value > max)
+        return max;
+    return value;
+}
+/** Parses a 1- or 2-digit text field; returns `null` if empty or non-numeric. */
+function parseField(text) {
+    if (!text)
+        return null;
+    if (!/^\d{1,2}$/.test(text))
+        return null;
+    return Number(text);
+}
+/** Total seconds since midnight for a (h, m, s) tuple — useful for min/max compare. */
+function timeOfDaySeconds(hour, minute, second) {
+    return hour * 3600 + minute * 60 + second;
+}
+
+/**
+ * Generated bundle index. Do not edit.
+ */
+
+export { AriaIdQueue, ENCLOSED_ACTIVE_HORIZONTAL, ENCLOSED_ACTIVE_VERTICAL, INACTIVE_TRIGGER_CLASSES, OVERLAY_ANIMATION_FALLBACK_PADDING, OverlayContainerCoordinator, PICKER_ENTER_DURATION, PICKER_LEAVE_DURATION, PILL_ACTIVE, PickerOverlayCoordinator, TW_ERROR_STATE_MATCHER, TW_SORT_HANDLE, UNDERLINE_ACTIVE_HORIZONTAL, UNDERLINE_ACTIVE_VERTICAL, appendDigit, buildSelectLikePositions, clamp, coerceOverlayDuration, consumeOverlayEscape, defaultErrorStateMatcher, fieldMax, fieldMin, from12h, getActiveTriggerClasses, getInactiveTriggerClasses, isTerminalDigit, mergeOverlayPanelClass, padTwo, parseField, resolveSelectScrollStrategy, stepWithWrap, tabTriggerVariants, timeOfDaySeconds, to12h };
+//# sourceMappingURL=cdevhub-ngx-tw-core.mjs.map