@cdevhub/ngx-tw 0.2.0

package/types/cdevhub-ngx-tw-core.d.ts

@@ -0,0 +1,719 @@
+import * as i0 from '@angular/core';
+import { InjectionToken, Signal, ElementRef, ViewContainerRef, Injector, ComponentRef, EventEmitter } from '@angular/core';
+import { AbstractControl } from '@angular/forms';
+import { ConnectedPosition, Overlay, ScrollStrategy, OverlayRef } from '@angular/cdk/overlay';
+import { ComponentType } from '@angular/cdk/portal';
+import { Observable } from 'rxjs';
+import * as tailwind_variants from 'tailwind-variants';
+
+/** Semantic color palette used across all ngx-tw components. */
+type TwColor = 'primary' | 'secondary' | 'accent' | 'neutral' | 'info' | 'success' | 'warning' | 'error';
+/** Size scale used across all ngx-tw components. */
+type TwSize = 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+/** Layout axis used by oriented components (tabs, segmented-control, separator, etc.). */
+type TwOrientation = 'horizontal' | 'vertical';
+/** Tailwind-aligned breakpoint. Used by responsive component inputs. */
+type TwBreakpoint = 'sm' | 'md' | 'lg' | 'xl';
+/**
+ * Range-mode behavior knobs shared by `tw-calendar` (when `mode="range"`) and
+ * by overlay-bearing range pickers that forward to it. Consumer inputs accept
+ * `Partial<RangeBehaviorConfig>`; unset fields fall back to the documented
+ * defaults — `allowSingleDayRange` and `persistPartialRange` default to `true`
+ * because dropping either would surprise consumers (clicking the same cell
+ * twice and committing one day; an in-flight draft surviving navigation are
+ * the expected gestures). `allowBackwardRange` and
+ * `disableRangesCrossingDisabledDates` default to `false`.
+ */
+interface RangeBehaviorConfig {
+    /**
+     * When `true`, the calendar accepts ranges with `start > end` and skips
+     * the auto-swap path (§21.5). Default `false` — backward clicks normalize.
+     */
+    allowBackwardRange: boolean;
+    /**
+     * When `true`, clicking the same cell as `draft.start` commits a single-day
+     * range `{ start, end: start }`. When `false`, the click is rejected with
+     * `data-state-invalid-flash`. Default `true` — selecting one day twice in
+     * range mode is the expected user gesture.
+     */
+    allowSingleDayRange: boolean;
+    /**
+     * When `true`, the in-flight range draft survives across view navigation
+     * (next/prev month, drill-up/down). When `false`, navigation during
+     * SELECTING discards the draft and emits `selectionCleared`. Default
+     * `true` — losing a half-finished range on navigation is unexpected.
+     */
+    persistPartialRange: boolean;
+    /**
+     * When `true`, a range commit that would span any disabled date in its
+     * interior is rejected with `data-state-invalid-flash` and the committed
+     * value is left unchanged. Default `false`.
+     */
+    disableRangesCrossingDisabledDates: boolean;
+}
+
+/**
+ * Minimal contract for a parent form's "submitted" state. Both `NgForm` and
+ * `FormGroupDirective` satisfy this, so the matcher can work with either.
+ */
+interface TwFormSubmitted {
+    readonly submitted: boolean;
+}
+/**
+ * Strategy that decides when a form control should be rendered in the error
+ * state. Controls read the injected matcher (or accept a per-instance
+ * override) and combine the result with their own signals. Override at any
+ * injector level via {@link TW_ERROR_STATE_MATCHER}.
+ */
+interface ErrorStateMatcher {
+    /** Returns true when the control should display an error. */
+    isErrorState(control: AbstractControl | null, form: TwFormSubmitted | null): boolean;
+}
+/**
+ * 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.
+ */
+declare const defaultErrorStateMatcher: ErrorStateMatcher;
+/**
+ * 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.
+ */
+declare const TW_ERROR_STATE_MATCHER: InjectionToken<ErrorStateMatcher>;
+
+/**
+ * Read-only view of a sortable region's state.
+ *
+ * Components that render column headers (e.g., `<tw-table>`) consume this handle to
+ * project `aria-sort` onto the active column without taking a hard dependency on the
+ * sort implementation. The canonical provider is `SortDirective` (`[twSort]`).
+ */
+interface TwSortHandle {
+    /** Signal of the id of the currently active sort header, or `null` when no sort is active. */
+    readonly active: Signal<string | null>;
+    /** Signal of the active sort direction (`'asc'` / `'desc'`), or `null` when cleared. */
+    readonly direction: Signal<'asc' | 'desc' | null>;
+}
+/**
+ * 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.
+ */
+declare const TW_SORT_HANDLE: 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.
+ */
+declare function buildSelectLikePositions(offset?: number): ConnectedPosition[];
+
+/** Named scroll-strategy variants supported by select-like overlays. */
+type SelectScrollStrategyName = 'reposition' | 'close' | 'block';
+/**
+ * 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.
+ */
+declare function resolveSelectScrollStrategy(name: SelectScrollStrategyName, overlay: Overlay): ScrollStrategy;
+
+/**
+ * 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.
+ */
+declare function consumeOverlayEscape(overlayRef: OverlayRef, onEscape: (event: KeyboardEvent) => void): () => void;
+
+/**
+ * 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.
+ */
+declare 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.
+ */
+declare const PICKER_LEAVE_DURATION = 120;
+/** Configuration passed to {@link PickerOverlayCoordinator.open}. */
+interface PickerOpenConfig<TOverlay> {
+    /** Element used as the connected-overlay origin (typically the picker trigger). */
+    readonly origin: ElementRef<HTMLElement>;
+    /** Component type to render inside the overlay (e.g. `DatePickerOverlayComponent`). */
+    readonly portalComponent: ComponentType<TOverlay>;
+    /** View-container that hosts the embedded view; usually the picker's `ViewContainerRef`. */
+    readonly viewContainerRef: ViewContainerRef;
+    /** Optional injector forwarded to the portal so DI tokens resolve from the picker's tree. */
+    readonly injector?: Injector;
+    /** Connected-position list — typically the result of `buildSelectLikePositions(offset)`. */
+    readonly positions: ConnectedPosition[];
+    /** CDK scroll-strategy instance for the overlay. */
+    readonly scrollStrategy: ScrollStrategy;
+    /** CSS class applied to the CDK overlay-pane element (NOT the panel root). */
+    readonly panelClass: string;
+    /** Viewport margin forwarded to the CDK position-strategy. Defaults to `8`. */
+    readonly viewportMargin?: number;
+}
+/** Synchronous return shape of {@link PickerOverlayCoordinator.open}. */
+interface PickerOpenResult<TOverlay> {
+    /** The CDK `OverlayRef` driving the overlay — exposed for advanced consumers. */
+    readonly overlayRef: OverlayRef;
+    /** The Angular `ComponentRef` for the attached portal — exposed so consumers may run `detectChanges()` to flush an initial-config push synchronously. */
+    readonly componentRef: ComponentRef<TOverlay>;
+    /** The instance of the attached portal component. Equivalent to `componentRef.instance`. */
+    readonly instance: TOverlay;
+    /** Auto-generated id consumers may wire to `aria-controls` / dialog `id`. */
+    readonly panelId: string;
+}
+/**
+ * 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).
+ */
+declare class PickerOverlayCoordinator {
+    private readonly overlay;
+    private readonly focusTrapFactory;
+    private readonly destroyRef;
+    private readonly idGenerator;
+    private overlayRef;
+    private focusTrap;
+    private closeTimer;
+    private openedTimer;
+    private currentPanelId;
+    private currentClose$;
+    private openedSubject;
+    private readonly attachedSignal;
+    private readonly openedSignal;
+    /** Whether the overlay is currently attached (between `open()` and detach). */
+    readonly attached: Signal<boolean>;
+    /** Whether the enter animation has completed (`opened$` has fired). */
+    readonly opened: Signal<boolean>;
+    constructor();
+    /**
+     * 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<TOverlay>(config: PickerOpenConfig<TOverlay>): PickerOpenResult<TOverlay> | null;
+    /**
+     * 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?: () => void): void;
+    /**
+     * Stream of overlay-level backdrop clicks for the current open lifecycle.
+     * Completes when the overlay closes.
+     */
+    backdropClick$(): Observable<MouseEvent>;
+    /**
+     * Stream of overlay-level keydown events for the current open lifecycle.
+     * Completes when the overlay closes.
+     */
+    overlayKeydown$(): Observable<KeyboardEvent>;
+    /**
+     * 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$(): Observable<KeyboardEvent>;
+    /**
+     * 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$(): Observable<void>;
+    /** Exposes the live `OverlayRef` for advanced consumers (e.g. width sync). */
+    ref(): OverlayRef | null;
+    /**
+     * 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(): string | null;
+    /**
+     * 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.
+     */
+    private disposeImmediate;
+    private setupFocusTrap;
+    private destroyFocusTrap;
+    private scheduleOpenedEmission;
+    private clearCloseTimer;
+    private clearOpenedTimer;
+    private assertOpen;
+    static ɵfac: i0.ɵɵFactoryDeclaration<PickerOverlayCoordinator, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<PickerOverlayCoordinator>;
+}
+
+/**
+ * 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.
+ */
+declare 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.
+ */
+declare function coerceOverlayDuration(value: number | undefined, fallback: number): number;
+/**
+ * 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.
+ */
+declare function mergeOverlayPanelClass(internal: string, consumer: string | readonly string[] | undefined): string;
+/**
+ * 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.
+ */
+declare class AriaIdQueue {
+    private readonly ids;
+    /** Inserts an id at the tail. No-op if the id is already present. */
+    add(id: string): void;
+    /** Removes the given id. No-op if the id is not present. */
+    remove(id: string): void;
+    /** First registered id (or `null` if empty). Matches CDK's `_ariaLabelledByQueue[0]` semantics. */
+    first(): string | null;
+    /** Returns a fresh snapshot of all registered ids in insertion order. */
+    snapshot(): readonly string[];
+}
+
+/** Lifecycle states an overlay container passes through. Shared by dialog and sheet. */
+type OverlayContainerState = 'opening' | 'open' | 'closing' | 'closed';
+/** Event emitted on every overlay-container animation-state transition. */
+interface OverlayContainerAnimationEvent {
+    /** State that the container just transitioned into. */
+    state: OverlayContainerState;
+    /** Duration, in ms, of the transition that triggered the event. */
+    totalTime: number;
+}
+/**
+ * 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.
+ */
+declare class OverlayContainerCoordinator {
+    private readonly destroyRef;
+    private readonly stateSignal;
+    private readonly ariaDescribedByQueue;
+    private readonly queue;
+    private animationTimer;
+    private enterDuration;
+    private exitDuration;
+    /** Lifecycle state of the container's enter/exit animation. */
+    readonly state: Signal<OverlayContainerState>;
+    /** Live snapshot of the describedby id queue. */
+    readonly describedByIds: Signal<readonly string[]>;
+    /**
+     * 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.
+     */
+    readonly transitionDuration: Signal<number>;
+    /**
+     * Emits whenever the animation state transitions. The container's `Ref`
+     * (`TwDialogRef` / `SheetRef`) subscribes to drive its own lifecycle
+     * (`afterOpened`, `afterClosed`, exit-animation completion).
+     */
+    readonly animationStateChanged: EventEmitter<OverlayContainerAnimationEvent>;
+    constructor();
+    /**
+     * 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: number, exit: number): void;
+    /**
+     * 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(): void;
+    /**
+     * 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(): void;
+    /** Registers a description id with the `aria-describedby` queue. */
+    addAriaDescribedBy(id: string): void;
+    /** Removes a previously registered description id. */
+    removeAriaDescribedBy(id: string): void;
+    /** First-registered-wins resolution for the `aria-describedby` attribute. */
+    firstDescribedBy(): string | null;
+    private runAnimationTimer;
+    private clearAnimationTimer;
+    static ɵfac: i0.ɵɵFactoryDeclaration<OverlayContainerCoordinator, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<OverlayContainerCoordinator>;
+}
+
+/**
+ * Visual style shared by `tw-tabs` (`TabsVariant`) and `nav[twTabNav]` (`TabNavVariant`).
+ * Kept as a string-literal union so downstream consumers can narrow when needed.
+ */
+type TabTriggerVariant = 'underline' | 'enclosed' | 'pill';
+/**
+ * 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.
+ */
+declare const tabTriggerVariants: tailwind_variants.TVReturnType<{
+    variant: {
+        underline: {
+            trigger: string;
+        };
+        enclosed: {
+            trigger: string;
+        };
+        pill: {
+            trigger: string;
+        };
+    };
+    size: {
+        xs: {
+            trigger: string;
+        };
+        sm: {
+            trigger: string;
+        };
+        md: {
+            trigger: string;
+        };
+        lg: {
+            trigger: string;
+        };
+        xl: {
+            trigger: string;
+        };
+    };
+    fitted: {
+        true: {
+            trigger: string;
+        };
+        false: {};
+    };
+    color: {
+        primary: {};
+        secondary: {};
+        accent: {};
+        neutral: {};
+        info: {};
+        success: {};
+        warning: {};
+        error: {};
+    };
+}, {
+    trigger: string;
+}, undefined, {
+    twMerge: true;
+}, {
+    variant: {
+        underline: {
+            trigger: string;
+        };
+        enclosed: {
+            trigger: string;
+        };
+        pill: {
+            trigger: string;
+        };
+    };
+    size: {
+        xs: {
+            trigger: string;
+        };
+        sm: {
+            trigger: string;
+        };
+        md: {
+            trigger: string;
+        };
+        lg: {
+            trigger: string;
+        };
+        xl: {
+            trigger: string;
+        };
+    };
+    fitted: {
+        true: {
+            trigger: string;
+        };
+        false: {};
+    };
+    color: {
+        primary: {};
+        secondary: {};
+        accent: {};
+        neutral: {};
+        info: {};
+        success: {};
+        warning: {};
+        error: {};
+    };
+}, {
+    trigger: string;
+}, tailwind_variants.TVReturnType<{
+    variant: {
+        underline: {
+            trigger: string;
+        };
+        enclosed: {
+            trigger: string;
+        };
+        pill: {
+            trigger: string;
+        };
+    };
+    size: {
+        xs: {
+            trigger: string;
+        };
+        sm: {
+            trigger: string;
+        };
+        md: {
+            trigger: string;
+        };
+        lg: {
+            trigger: string;
+        };
+        xl: {
+            trigger: string;
+        };
+    };
+    fitted: {
+        true: {
+            trigger: string;
+        };
+        false: {};
+    };
+    color: {
+        primary: {};
+        secondary: {};
+        accent: {};
+        neutral: {};
+        info: {};
+        success: {};
+        warning: {};
+        error: {};
+    };
+}, {
+    trigger: string;
+}, undefined, {
+    twMerge: true;
+}, unknown, unknown, undefined>>;
+/** @internal Active trigger classes for horizontal underline variants, keyed by color. */
+declare const UNDERLINE_ACTIVE_HORIZONTAL: Record<TwColor, string>;
+/** @internal Active trigger classes for vertical underline variants, keyed by color. */
+declare const UNDERLINE_ACTIVE_VERTICAL: Record<TwColor, string>;
+/** @internal Active trigger classes for horizontal enclosed variants, keyed by color. */
+declare const ENCLOSED_ACTIVE_HORIZONTAL: Record<TwColor, string>;
+/** @internal Active trigger classes for vertical enclosed variants, keyed by color. */
+declare const ENCLOSED_ACTIVE_VERTICAL: Record<TwColor, string>;
+/** @internal Active trigger classes for pill variants, keyed by color. */
+declare const PILL_ACTIVE: Record<TwColor, string>;
+/** @internal Inactive trigger classes keyed by variant. */
+declare const INACTIVE_TRIGGER_CLASSES: Record<TabTriggerVariant, string>;
+/**
+ * Returns the active-state trigger class string for the given variant, color,
+ * and orientation. Tab-nav callers pass `'horizontal'` since it is horizontal-only.
+ */
+declare function getActiveTriggerClasses(variant: TabTriggerVariant, color: TwColor, orientation?: 'horizontal' | 'vertical'): string;
+/** Returns the inactive-state trigger class string for the given variant. */
+declare function getInactiveTriggerClasses(variant: TabTriggerVariant): string;
+
+/**
+ * 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.
+ */
+/** Supported time-picker formats. */
+type TimePickerFormat = '12h' | '24h';
+/** Meridiem used by the 12h format. */
+type TimePickerMeridiem = 'AM' | 'PM';
+/** Zero-pads a non-negative integer to exactly two digits. */
+declare function padTwo(value: number): string;
+/** Converts a 24h hour (0–23) to its 12h display value (1–12). */
+declare function to12h(hour24: number): number;
+/** Builds a canonical 0–23 hour from a 12h display hour and meridiem. */
+declare function from12h(hour12: number, meridiem: TimePickerMeridiem): number;
+/** Maximum allowed value for a field given the picker format. */
+declare function fieldMax(field: 'hour' | 'minute' | 'second', format: TimePickerFormat): number;
+/** Minimum allowed value for a field given the picker format. */
+declare function fieldMin(field: 'hour' | 'minute' | 'second', format: TimePickerFormat): number;
+/**
+ * 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.
+ */
+declare function appendDigit(current: string, digit: string, max: number): string;
+/**
+ * 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.
+ */
+declare function isTerminalDigit(current: string, digit: string, max: number): boolean;
+/**
+ * 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.
+ */
+declare function stepWithWrap(value: number, step: number, direction: 1 | -1, min: number, max: number): number;
+/** Clamps a number into `[min, max]` without wrapping. */
+declare function clamp(value: number, min: number, max: number): number;
+/** Parses a 1- or 2-digit text field; returns `null` if empty or non-numeric. */
+declare function parseField(text: string): number | null;
+/** Total seconds since midnight for a (h, m, s) tuple — useful for min/max compare. */
+declare function timeOfDaySeconds(hour: number, minute: number, second: number): number;
+
+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 };
+export type { ErrorStateMatcher, OverlayContainerAnimationEvent, OverlayContainerState, PickerOpenConfig, PickerOpenResult, RangeBehaviorConfig, SelectScrollStrategyName, TabTriggerVariant, TimePickerFormat, TimePickerMeridiem, TwBreakpoint, TwColor, TwFormSubmitted, TwOrientation, TwSize, TwSortHandle };