@cdevhub/ngx-tw 0.5.0 → 0.6.0

package/types/cdevhub-ngx-tw-flip-card.d.ts

@@ -1,7 +1,13 @@
 import * as _angular_core from '@angular/core';
 
 /** Visual style of the flip card chrome. Mirrors `tw-card`. */
-type FlipCardVariant = 'outlined' | 'elevated' | 'ghost';
+type FlipCardVariant = 'outline' | 'elevated' | 'ghost' | FlipCardVariantLegacy;
+/**
+ * Legacy `variant` spellings, kept so existing templates keep compiling.
+ * @deprecated `'outlined'` is an alias for `'outline'` and renders identically.
+ * It will be removed in the next major — prefer `'outline'`.
+ */
+type FlipCardVariantLegacy = 'outlined';
 /** Axis of rotation for the flip animation. */
 type FlipCardDirection = 'horizontal' | 'vertical';
 /** Which user interaction flips the card. */
@@ -22,8 +28,9 @@ type FlipCardTrigger = 'hover' | 'click' | 'manual' | 'both';
 declare class FlipCardComponent {
     /**
      * Visual style of the card chrome. Mirrors `tw-card`'s variant vocabulary.
-     * Defaults to `'outlined'` (vs `tw-card`'s `'elevated'` default) so the flip
+     * Defaults to `'outline'` (vs `tw-card`'s `'elevated'` default) so the flip
      * animation reads more clearly without a baseline shadow underneath.
+     * `'outlined'` is a deprecated alias for `'outline'` and renders identically.
      */
     readonly variant: _angular_core.InputSignal<FlipCardVariant>;
     /** Axis of rotation. `'horizontal'` rotates around the Y axis (left/right flip); `'vertical'` rotates around the X axis (top/bottom flip). Defaults to `'horizontal'`. */
@@ -35,12 +42,12 @@ declare class FlipCardComponent {
     /** Whether the back face is currently visible. Two-way bindable via `[(flipped)]`. Defaults to `false`. The `flippedChange` event fires on every toggle. */
     readonly flipped: _angular_core.ModelSignal<boolean>;
     /**
-     * Accessible name for the host element. Required when `trigger` is
-     * `'manual'` (the host renders as `role="region"`, which AXE requires to
-     * have an accessible name); a default of `'Flip card'` is used in that
-     * mode if no value is provided. In interactive modes the host's accessible
-     * name is normally derived from the visible face's content — set this
-     * input to override.
+     * Accessible name for the host element, mirrored to `aria-label`. Required
+     * when `trigger` is `'manual'` (the host renders as `role="region"`, which
+     * AXE requires to have an accessible name); a default of `'Flip card'` is
+     * used in that mode if no value is provided. In interactive modes the host's
+     * accessible name is normally derived from the visible face's content — set
+     * this input to override. Defaults to `undefined`.
      */
     readonly ariaLabel: _angular_core.InputSignal<string | undefined>;
     private readonly liveAnnouncer;
@@ -58,8 +65,6 @@ declare class FlipCardComponent {
     /** @internal */
     readonly ariaPressed: _angular_core.Signal<string | null>;
     /** @internal */
-    readonly ariaLive: _angular_core.Signal<"polite" | null>;
-    /** @internal */
     readonly ariaDisabled: _angular_core.Signal<"true" | null>;
     /** @internal */
     readonly hostAriaLabel: _angular_core.Signal<string | null>;
@@ -71,6 +76,8 @@ declare class FlipCardComponent {
     readonly frontInert: _angular_core.Signal<"" | null>;
     /** @internal */
     readonly backInert: _angular_core.Signal<"" | null>;
+    /** @internal Canonical variant with legacy spellings folded in. */
+    private readonly resolvedVariant;
     private readonly variantResult;
     readonly rootClasses: _angular_core.Signal<string>;
     readonly innerClasses: _angular_core.Signal<string>;
@@ -88,7 +95,7 @@ declare class FlipCardComponent {
     private toggle;
     private setFlipped;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<FlipCardComponent, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<FlipCardComponent, "tw-flip-card", never, { "variant": { "alias": "variant"; "required": false; "isSignal": true; }; "direction": { "alias": "direction"; "required": false; "isSignal": true; }; "trigger": { "alias": "trigger"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "flipped": { "alias": "flipped"; "required": false; "isSignal": true; }; "ariaLabel": { "alias": "ariaLabel"; "required": false; "isSignal": true; }; }, { "flipped": "flippedChange"; }, never, ["[slot='front']", "[slot='back']"], true, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<FlipCardComponent, "tw-flip-card", never, { "variant": { "alias": "variant"; "required": false; "isSignal": true; }; "direction": { "alias": "direction"; "required": false; "isSignal": true; }; "trigger": { "alias": "trigger"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "flipped": { "alias": "flipped"; "required": false; "isSignal": true; }; "ariaLabel": { "alias": "aria-label"; "required": false; "isSignal": true; }; }, { "flipped": "flippedChange"; }, never, ["[slot='front']", "[slot='back']"], true, never>;
 }
 
 export { FlipCardComponent };

package/types/cdevhub-ngx-tw-form-field.d.ts

@@ -28,7 +28,24 @@ declare abstract class FormFieldControl<T = unknown> {
     abstract readonly required: Signal<boolean>;
     /** Whether the control should be rendered as invalid. Usually derived from `NgControl.invalid` combined with `touched`/`submitted`. */
     abstract readonly errorState: Signal<boolean>;
-    /** Active validation errors map keyed by validator name (e.g. `{ required: true, email: true }`). Returns `null` when the control has no validation errors. Drives `[twError match="…"]` filtering inside the form-field. Optional — controls without a backing `NgControl` may omit it. */
+    /**
+     * Active validation errors map keyed by validator name (e.g. `{ required: true, email: true }`).
+     * Returns `null` when the control has no validation errors.
+     *
+     * This is the *only* source the form-field consults for `[twError match="…"]` filtering: it
+     * feeds `FormFieldComponent.activeErrorKeys`, and an error with a `match` renders only while
+     * that key is present. A control that leaves this undefined therefore reports an empty key set,
+     * and **every `match`-targeted message under it is permanently hidden** — in all three form
+     * strategies, with no warning. Unmatched `[twError]` messages are unaffected; they follow
+     * `errorState` alone.
+     *
+     * Optional only so the member can be added to existing controls without a breaking change. Any
+     * control that resolves an `NgControl` should implement it — typically as
+     * `computed(() => ngControl?.control?.errors ?? null)`, reading whatever revision signal the
+     * control already uses to invalidate `errorState`, so the map tracks validator transitions that
+     * do not flip `VALID`/`INVALID`. Omit it only for a control that genuinely has no validation
+     * errors to report.
+     */
     readonly errors?: Signal<Record<string, unknown> | null>;
     /** Optional control-type identifier (e.g. `'input'`, `'select'`). When set, the form-field appends `tw-form-field-type-{controlType}` to its host for styling hooks. */
     abstract readonly controlType?: string;
@@ -141,7 +158,7 @@ declare class SuffixIconDirective extends SuffixDirective {
 declare class FormFieldComponent implements AfterContentInit, TwFormFieldParent {
     /** Visual appearance of the field container. `'outline'` draws a full border around the control; `'filled'` uses a filled surface with a bottom border. Defaults to `'outline'`. */
     readonly appearance: i0.InputSignal<FormFieldAppearance>;
-    /** Density of the field container. Maps to the inline-padding scale (`px-2 py-1` xs … `px-5 py-3` xl) and the floating-label font scale. Defaults to `'md'`. */
+    /** Density of the field container. Maps to the inline-padding scale (`px-2 py-1` xs … `px-5 py-3` xl), the control-row font scale (`text-xs` xs, `text-sm` sm/md, `text-base` lg/xl — inherited by the nested control and by prefix/suffix adornments), the label font scale, and a `min-h-*` floor on the control row from the control-height scale (24/32/36/44/48px). The floor is a minimum, not a fixed height: the row grows for a textarea or any other multi-line control. Defaults to `'md'`. */
     readonly size: i0.InputSignal<TwSize>;
     /** Floating label behavior. `'auto'` floats when focused or non-empty; `'always'` stays floated; `'never'` disables floating entirely (the label wrapper is not rendered and the wrapped control's placeholder is always visible). Defaults to `'auto'`. */
     readonly floatLabel: i0.InputSignal<FloatLabel>;

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

@@ -38,7 +38,7 @@ interface TwIconSvgConfig {
  * ```html
  * <tw-icon name="star" />
  * <tw-icon name="check" color="success" size="lg" />
- * <tw-icon name="alert-triangle" color="warning" ariaLabel="Warning" />
+ * <tw-icon name="alert-triangle" color="warning" aria-label="Warning" />
  * <tw-icon name="star" [svg]="{ strokeWidth: 1.5, absoluteStrokeWidth: true }" />
  * ```
  */
@@ -56,7 +56,7 @@ declare class IconComponent {
     readonly color: _angular_core.InputSignal<TwIconColor>;
     /** Icon size. Defaults to `'md'` (20px). */
     readonly size: _angular_core.InputSignal<TwSize>;
-    /** Accessible label. When set, removes `aria-hidden` and applies `aria-label` to the SVG. Defaults to `undefined` (icon is decorative, `aria-hidden="true"`). */
+    /** Accessible label, supplied as the plain `aria-label` attribute. When set, the generated SVG takes `role="img"` plus the label instead of `aria-hidden="true"`. Defaults to `undefined` (icon is decorative, `aria-hidden="true"`). */
     readonly ariaLabel: _angular_core.InputSignal<string | undefined>;
     /**
      * SVG-author configuration: `strokeWidth`, `absoluteStrokeWidth`, `viewBox`.
@@ -82,7 +82,7 @@ declare class IconComponent {
     constructor();
     private renderSvg;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<IconComponent, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<IconComponent, "tw-icon", never, { "name": { "alias": "name"; "required": false; "isSignal": true; }; "img": { "alias": "img"; "required": false; "isSignal": true; }; "color": { "alias": "color"; "required": false; "isSignal": true; }; "size": { "alias": "size"; "required": false; "isSignal": true; }; "ariaLabel": { "alias": "ariaLabel"; "required": false; "isSignal": true; }; "svg": { "alias": "svg"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<IconComponent, "tw-icon", never, { "name": { "alias": "name"; "required": false; "isSignal": true; }; "img": { "alias": "img"; "required": false; "isSignal": true; }; "color": { "alias": "color"; "required": false; "isSignal": true; }; "size": { "alias": "size"; "required": false; "isSignal": true; }; "ariaLabel": { "alias": "aria-label"; "required": false; "isSignal": true; }; "svg": { "alias": "svg"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
 }
 
 /**

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

@@ -23,7 +23,7 @@ declare const TW_INPUT_VALUE_ACCESSOR: InjectionToken<{
  *   and provide under `TW_FORM_FIELD_CONTROL`.
  * - Swap value storage for an existing `<input twInput>` (masked input,
  *   date parser, etc.) → provide {@link TW_INPUT_VALUE_ACCESSOR}.
- * - Change when errors show → override {@link TW_ERROR_STATE_MATCHER} at any
+ * - Change when errors show → override `TW_ERROR_STATE_MATCHER` at any
  *   injector level, or pass `errorStateMatcher` per instance.
  *
  * Forms integration is inherited: Angular's native value accessors attach to
@@ -38,9 +38,6 @@ declare class InputDirective extends FormFieldControl<string> implements OnInit
     private readonly destroyRef;
     private readonly formField;
     private readonly ngControl;
-    private readonly parentForm;
-    private readonly parentFormGroup;
-    private readonly defaultMatcher;
     private readonly valueAccessor;
     /** @internal */
     readonly _isTextarea: boolean;
@@ -51,7 +48,7 @@ declare class InputDirective extends FormFieldControl<string> implements OnInit
     readonly idInput: _angular_core.InputSignal<string | undefined>;
     /** Native HTML input `type`. Defaults to `'text'`. Dev-mode throws on unsupported values (`checkbox`, `radio`, `submit`, etc.) — use the dedicated component instead. Ignored on `<textarea>`. */
     readonly type: _angular_core.InputSignal<string>;
-    /** Density of a standalone field. Maps to the inline-padding scale (`px-2 py-1` xs … `px-6 py-3` xl) and font scale (`text-xs` xs, `text-sm` sm/md, `text-base` lg/xl). Ignored inside a `<tw-form-field>` — the wrapper's `size` carries density. Defaults to `'md'`. */
+    /** Density of a standalone field. Maps to the pinned control-height scale (24/32/36/44/48px, `h-6` xs … `h-12` xl), the horizontal-padding scale (`px-2` xs … `px-6` xl), and the font scale (`text-xs` xs, `text-sm` sm/md, `text-base` lg/xl). On a `<textarea>` the height becomes a `min-h-*` floor and the vertical padding is retained. Ignored inside a `<tw-form-field>` — the wrapper's `size` carries density. Defaults to `'md'`. */
     readonly size: _angular_core.InputSignal<TwSize>;
     /** Disables the control. Also reflects `ngControl.disabled` when the element is bound to a reactive form. Defaults to `false`. */
     readonly disabledInput: _angular_core.InputSignalWithTransform<boolean, unknown>;
@@ -68,8 +65,8 @@ declare class InputDirective extends FormFieldControl<string> implements OnInit
     private readonly _value;
     private readonly _focused;
     private readonly _autofilled;
-    private readonly _ngControlRev;
-    private readonly _formSubmitRev;
+    /** @internal Shared `errorState` / `required` / `errors` derivation — see `wireErrorState`. */
+    private readonly errorWiring;
     /** @internal */
     readonly id: Signal<string>;
     /** @internal */
@@ -84,7 +81,7 @@ declare class InputDirective extends FormFieldControl<string> implements OnInit
     readonly required: Signal<boolean>;
     /** @internal */
     readonly errorState: Signal<boolean>;
-    /** @internal Active validation errors map from the bound `NgControl` (or `null` when the control reports none / is unbound). Recomputes on every `_ngControlRev` tick so `[twError match="…"]` reacts to validator transitions, including rules that fire/clear without flipping `VALID`/`INVALID`. */
+    /** @internal Active validation errors map from the bound `NgControl`, for `[twError match="…"]` filtering. */
     readonly errors: Signal<Record<string, unknown> | null>;
     /** @internal */
     readonly classes: Signal<string>;

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

@@ -36,7 +36,9 @@ declare class ItemComponent implements OnInit {
     readonly descriptionClasses: _angular_core.Signal<string>;
     readonly trailingClasses: _angular_core.Signal<string>;
     ngOnInit(): void;
+    /** @internal Emits `selected` on click when the item is interactive and enabled. */
     onActivate(event: Event): void;
+    /** @internal Emits `selected` on Enter/Space when the item is interactive and enabled. */
     onKeydown(event: KeyboardEvent): void;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<ItemComponent, never>;
     static ɵcmp: _angular_core.ɵɵComponentDeclaration<ItemComponent, "tw-item", never, { "size": { "alias": "size"; "required": false; "isSignal": true; }; "align": { "alias": "align"; "required": false; "isSignal": true; }; "interactive": { "alias": "interactive"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "current": { "alias": "current"; "required": false; "isSignal": true; }; }, { "selected": "selected"; }, never, ["[twItemLeading]", "[twItemTitle]", "[twItemDescription]", "[twItemTrailing]"], true, never>;

package/types/cdevhub-ngx-tw-menu-testing.d.ts

@@ -0,0 +1,131 @@
+import { BaseHarnessFilters, ComponentHarness, HarnessPredicate } from '@angular/cdk/testing';
+
+/** Filters accepted by `MenuItemHarness.with`. */
+interface MenuItemHarnessFilters extends BaseHarnessFilters {
+    /** Match by the item's visible text. */
+    text?: string | RegExp;
+    /** Match disabled / enabled items. */
+    disabled?: boolean;
+    /** Match checked / unchecked checkbox and radio items. Never matches a plain item. */
+    checked?: boolean;
+}
+/**
+ * Harness for a single item inside an open `tw-menu` panel.
+ *
+ * Hosts on the ARIA role rather than on the `twMenuItem*` attribute selectors,
+ * so one harness covers plain items, checkbox items and radio items — the roles
+ * are contributed by the CDK directives `tw-menu` composes and are the same
+ * thing assistive technology reads.
+ *
+ * Items render into the CDK overlay, not inside the trigger, so they are reached
+ * through {@link MenuHarness} rather than located directly against a fixture.
+ */
+declare class MenuItemHarness extends ComponentHarness {
+    static hostSelector: string;
+    /** Predicate for `locatorFor` / `locatorForAll`. */
+    static with(options?: MenuItemHarnessFilters): HarnessPredicate<MenuItemHarness>;
+    /** The item's rendered text, trimmed. Includes any projected description or shortcut text. */
+    getText(): Promise<string>;
+    /**
+     * The item's ARIA role — `'menuitem'`, `'menuitemcheckbox'` or
+     * `'menuitemradio'`. Lets a test tell the three kinds apart.
+     */
+    getRole(): Promise<string | null>;
+    /** Whether the item reports `aria-disabled="true"`. */
+    isDisabled(): Promise<boolean>;
+    /**
+     * Checked state of a checkbox or radio item, or `null` for a plain item,
+     * which carries no `aria-checked` at all.
+     */
+    isChecked(): Promise<boolean | null>;
+    /** Clicks the item. A disabled item ignores the click, as in the browser. */
+    click(): Promise<void>;
+}
+
+/** Filters accepted by `MenuHarness.with`. */
+interface MenuHarnessFilters extends BaseHarnessFilters {
+    /** Match by the text rendered in the trigger. */
+    triggerText?: string | RegExp;
+}
+/**
+ * Harness for a `[twMenuTrigger]` and the `tw-menu` panel it opens.
+ *
+ * ## Why this is a parallel harness and not a delegating one
+ *
+ * `tw-menu` composes `CdkMenu` / `CdkMenuItem` through `hostDirectives`, so a
+ * thin harness delegating to a CDK one would be preferable — except that
+ * `@angular/cdk` ships **no component harnesses at all**. Its only testing
+ * entry points are `@angular/cdk/testing`, `@angular/cdk/testing/testbed` and
+ * `@angular/cdk/testing/selenium-webdriver`, all of which are harness
+ * *infrastructure*; the component harnesses live in `@angular/material/*\/testing`,
+ * and `@angular/material` is not a dependency of this library. There is nothing
+ * to delegate to. What composition does buy us is that the locators below are
+ * ARIA roles and attributes CDK guarantees (`role="menuitem"`,
+ * `aria-expanded`, `aria-controls`), not ngx-tw class names.
+ *
+ * ## Why the host selector is not `[twMenuTrigger]`
+ *
+ * `twMenuTrigger` takes a required `TemplateRef`, so it is always written as a
+ * property binding — `[twMenuTrigger]="menu"` — and Angular renders **no
+ * attribute** for a bound input. `[twMenuTrigger]` therefore matches nothing in
+ * the DOM. `MenuTriggerDirective` adds no host class or attribute of its own
+ * (contrast Material, whose `MatMenuTrigger` adds `.mat-mdc-menu-trigger`
+ * precisely so its harness can find it), so the only durable marker is the one
+ * CDK contributes: `aria-haspopup="menu"`, bound unconditionally by
+ * `CdkMenuTrigger` whenever it has a template. Nothing else in ngx-tw renders
+ * that value — `[twContextMenuTrigger]` deliberately renders none — so the match
+ * is exact today. If `MenuTriggerDirective` ever grows a host marker, widening
+ * this selector to it is a non-breaking change.
+ *
+ * ## Loading it
+ *
+ * The host is the trigger, which lives in the fixture, so the ordinary
+ * `TestbedHarnessEnvironment.loader(fixture)` is correct. The panel renders into
+ * the CDK overlay container outside the fixture, and this harness resolves it
+ * internally via `documentRootLocatorFactory()` — a consumer never needs
+ * `documentRootLoader`.
+ *
+ * The panel is located by the id in the trigger's `aria-controls`, so a fixture
+ * holding several menus (or an open submenu) still resolves each trigger to its
+ * own panel.
+ *
+ * Only `[twMenuTrigger]` is covered. `[twContextMenuTrigger]` opens on a
+ * `contextmenu` event at pointer coordinates and exposes neither `aria-expanded`
+ * nor `aria-haspopup`; it is deliberately out of scope.
+ */
+declare class MenuHarness extends ComponentHarness {
+    static hostSelector: string;
+    /** Predicate for `locatorFor` / `locatorForAll`. */
+    static with(options?: MenuHarnessFilters): HarnessPredicate<MenuHarness>;
+    /** The text currently rendered in the trigger, trimmed. */
+    getTriggerText(): Promise<string>;
+    /** Whether the menu is open, read from the trigger's `aria-expanded`. */
+    isOpen(): Promise<boolean>;
+    /** Opens the menu by clicking the trigger. No-op when already open. */
+    open(): Promise<void>;
+    /** Closes the menu by clicking the trigger again. No-op when already closed. */
+    close(): Promise<void>;
+    /**
+     * Every item in the open panel — plain, checkbox and radio alike. Returns an
+     * empty array when the menu is closed, because CDK removes the panel from the
+     * DOM rather than hiding it.
+     */
+    getItems(filters?: MenuItemHarnessFilters): Promise<MenuItemHarness[]>;
+    /**
+     * Opens the menu if needed and clicks the first item whose text matches.
+     * Throws when nothing matches, rather than failing silently.
+     *
+     * CDK closes the menu when an item is activated, so a `getItems()` chained
+     * after this returns an empty array — call {@link open} again before
+     * re-reading item state.
+     */
+    clickItem(text: string | RegExp): Promise<void>;
+    /**
+     * A loader rooted at this trigger's own panel, or `null` when the menu is
+     * closed. Scoping by `aria-controls` keeps sibling menus and submenus apart.
+     */
+    private getPanelLoader;
+}
+
+export { MenuHarness, MenuItemHarness };
+export type { MenuHarnessFilters, MenuItemHarnessFilters };

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

@@ -6,9 +6,9 @@ import { TwSize, TwColor } from '@cdevhub/ngx-tw/core';
 declare class MenuComponent {
     /** Controls item density and padding. Defaults to `'md'`. */
     readonly size: i0.InputSignal<TwSize>;
-    /** Accessible label for the menu panel. Use when no visible heading describes the menu (e.g. a kebab-icon trigger). */
+    /** Accessible label for the menu panel. Use when no visible heading describes the menu (e.g. a kebab-icon trigger). Defaults to `undefined`. Alias: `aria-label`. */
     readonly ariaLabel: i0.InputSignal<string | undefined>;
-    /** ID of an element that labels the menu panel. Ignored when `ariaLabel` is set. */
+    /** ID of an element that labels the menu panel. Ignored when `ariaLabel` is set. Defaults to `undefined`. Alias: `aria-labelledby`. */
     readonly ariaLabelledBy: i0.InputSignal<string | undefined>;
     readonly classes: i0.Signal<string>;
     static ɵfac: i0.ɵɵFactoryDeclaration<MenuComponent, never>;

package/types/cdevhub-ngx-tw-number-input.d.ts

@@ -42,6 +42,26 @@ declare class NumberInputDirective implements ControlValueAccessor {
     readonly disabled: _angular_core.Signal<boolean>;
     /** True when the host input carries the `readonly` attribute (static / declarative, seeded after render). A runtime toggle of the bare `readonly` attribute is not reactively tracked (v2). Read by the companion stepper so its buttons disable in lock-step. */
     readonly readonly: _angular_core.Signal<boolean>;
+    /**
+     * @internal `aria-disabled` for the host `<input>`.
+     *
+     * Derived from the CVA disabled state ALONE, deliberately not from
+     * {@link disabled}. Three reasons, in order of weight:
+     *
+     * 1. It is the only case that needs the attribute. When the element is
+     *    natively disabled (`el.disabled`, whether from a static attribute or
+     *    from the sibling `InputDirective`'s `[disabled]` binding) assistive tech
+     *    already has the state. The gap is `setDisabledState(true)` on a
+     *    standalone `input[twNumberInput]` — no sibling directive, so nothing
+     *    writes the native property and the spinbutton looked enabled.
+     * 2. `disabled` reads the non-reactive `el.disabled`. Read from a host
+     *    binding it would memoize during the host-binding phase, so its value
+     *    would depend on which of the two directives on the element runs first —
+     *    and could latch a stale `true` across a `control.enable()`.
+     * 3. `[disabled]` itself is not an option: `InputDirective` already binds it,
+     *    and this directive's `disabled` reads the very property it would write.
+     */
+    readonly ariaDisabled: _angular_core.Signal<"true" | null>;
     /** @internal Mobile-keyboard hint: `'numeric'` for integer-only formats, else `'decimal'`. */
     readonly inputMode: _angular_core.Signal<"numeric" | "decimal">;
     /** @internal Locale group / decimal separators, memoized per `locale()`. */

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

@@ -11,36 +11,44 @@ type TwPaginatorLayout = 'compact' | 'spread';
 type TwPaginatorResponsive = 'auto' | 'off';
 /** Named slot accepted by `*twPaginatorLabel`. */
 type TwPaginatorLabelSlot = 'pageInfo' | 'previous' | 'next' | 'first' | 'last' | 'pageSizeLabel';
-/** String labels used throughout the paginator. All are optional on the `labels` input — unset keys fall back to the English defaults. */
+/**
+ * String labels used throughout the paginator.
+ *
+ * Every member is optional. This interface only ever reaches consumers through
+ * `input<Partial<TwPaginatorLabels>>`, and unset keys fall back to the English
+ * defaults — so a consumer holding an i18n bundle typed as `TwPaginatorLabels`
+ * must not be forced to restate all fourteen keys, and adding a label in a
+ * future minor must not break them on a non-major release.
+ */
 interface TwPaginatorLabels {
     /** Accessible name for the `<nav>` landmark. */
-    ariaLabel: string;
+    ariaLabel?: string;
     /** Label on the Previous button. */
-    previous: string;
+    previous?: string;
     /** Label on the Next button. */
-    next: string;
+    next?: string;
     /** Label on the First-page button. */
-    first: string;
+    first?: string;
     /** Label on the Last-page button. */
-    last: string;
+    last?: string;
     /** Visible label before the current-page indicator. Used as `"{pageInfo} {page}{pageInfoSeparator}{totalPages}"`. */
-    pageInfo: string;
+    pageInfo?: string;
     /** Text that joins the current page and total. */
-    pageInfoSeparator: string;
+    pageInfoSeparator?: string;
     /** Range-style page info template. Variables: `{start}`, `{end}`, `{total}`. */
-    pageRange: string;
+    pageRange?: string;
     /** Visible label next to the page-size selector. */
-    pageSizeLabel: string;
+    pageSizeLabel?: string;
     /** `LiveAnnouncer` template used on every page change. Variables: `{page}`, `{totalPages}`, `{start}`, `{end}`, `{total}`. */
-    announcement: string;
+    announcement?: string;
     /** Accessible label per numbered page button. Variable: `{page}`. */
-    pageButtonAriaLabel: string;
+    pageButtonAriaLabel?: string;
     /** Accessible label for the current numbered page button. Variable: `{page}`. */
-    currentPageAriaLabel: string;
+    currentPageAriaLabel?: string;
     /** Accessible label applied to ellipsis items. */
-    ellipsis: string;
+    ellipsis?: string;
     /** Rendered when `hideOnEmpty` is `false` and `totalItems === 0`. */
-    empty: string;
+    empty?: string;
 }
 /** Emitted by `pageChange`. */
 interface TwPaginatorPageChangeEvent {
@@ -143,7 +151,7 @@ declare class PaginatorPageSizeSelectorDirective {
  */
 declare class PaginatorFocusableDirective implements FocusableOption {
     readonly elementRef: ElementRef<any>;
-    /** When true, the element is skipped by `FocusKeyManager` roving focus. */
+    /** When true, the element is skipped by `FocusKeyManager` roving focus. Defaults to `false`. */
     readonly isDisabled: _angular_core.InputSignal<boolean>;
     focus(): void;
     /**
@@ -158,9 +166,9 @@ declare class PaginatorFocusableDirective implements FocusableOption {
 declare class PaginatorComponent {
     /** Total number of items across all pages. Defaults to `0`. */
     readonly totalItems: _angular_core.InputSignal<number>;
-    /** Items per page. Two-way bindable via `[(pageSize)]`. Defaults to `10`. */
+    /** Items per page. Two-way bindable via `[(pageSize)]`; writes back when the user picks a different size in the page-size selector. Defaults to `10`. */
     readonly pageSize: _angular_core.ModelSignal<number>;
-    /** 1-based current page. Two-way bindable via `[(page)]`. Clamped internally. Defaults to `1`. */
+    /** 1-based current page. Two-way bindable via `[(page)]`; writes back when the user navigates, and whenever the value is clamped into the valid `1…totalPages` range. Defaults to `1`. */
     readonly page: _angular_core.ModelSignal<number>;
     /** Rendering type. Defaults to `'numbered'`. */
     readonly type: _angular_core.InputSignal<TwPaginatorType>;
@@ -174,15 +182,15 @@ declare class PaginatorComponent {
     readonly siblingCount: _angular_core.InputSignal<number>;
     /** How many pages to always show at the start and end boundaries. Defaults to `1`. */
     readonly boundaryCount: _angular_core.InputSignal<number>;
-    /** When true, renders jump-to-first and jump-to-last buttons. Defaults to `true`. */
+    /** When true, renders jump-to-first and jump-to-last buttons. Defaults to `true` — first/last jumps are the standard pagination affordance for any list large enough to need a paginator; the special case is a compact paginator that opts out. */
     readonly showFirstLastButtons: _angular_core.InputSignal<boolean>;
     /** When true, renders the page-size selector region. Defaults to `false`. */
     readonly showPageSizeSelector: _angular_core.InputSignal<boolean>;
     /** Options for the default page-size selector. Ignored when `*twPaginatorPageSizeSelector` is projected. Defaults to `[10, 25, 50, 100]`. */
     readonly pageSizeOptions: _angular_core.InputSignal<readonly number[]>;
-    /** When true, renders the page-info text region. Defaults to `true`. */
+    /** When true, renders the page-info text region. Defaults to `true` — showing "X–Y of Z" is the expected pagination context; the special case is an ultra-compact paginator in tight UI that opts out. */
     readonly showPageInfo: _angular_core.InputSignal<boolean>;
-    /** When true, renders nothing when `totalItems === 0`. Defaults to `true`. */
+    /** When true, renders nothing when `totalItems === 0`. Defaults to `true` — hiding the paginator on empty data is the expected UX; the special case is a layout that opts out to reserve the paginator's vertical space. */
     readonly hideOnEmpty: _angular_core.InputSignal<boolean>;
     /** When true, renders nothing when `totalPages <= 1`. Defaults to `false`. */
     readonly hideOnSinglePage: _angular_core.InputSignal<boolean>;
@@ -194,7 +202,16 @@ declare class PaginatorComponent {
     readonly labels: _angular_core.InputSignal<Partial<TwPaginatorLabels>>;
     /** When provided, buttons render as anchor links using the returned `href`. Defaults to `undefined` (renders as buttons). */
     readonly linkFactory: _angular_core.InputSignal<((page: number) => string) | undefined>;
-    /** Overrides `labels.ariaLabel` for the root `<nav>` element. */
+    /**
+     * Overrides `labels.ariaLabel` for the root `<nav>` element. Bound as `aria-label`.
+     * Defaults to `undefined` (the resolved `labels.ariaLabel` is used).
+     *
+     * The host renders as a `navigation` landmark, so a page showing more than one
+     * paginator (the common "controls above and below a table" shape) MUST give each
+     * one a distinct name here — two landmarks of the same role sharing an accessible
+     * name are indistinguishable to a screen-reader landmark list (axe:
+     * `landmark-unique`).
+     */
     readonly customAriaLabel: _angular_core.InputSignal<string | undefined>;
     /** Fires when `page` or `pageSize` changes. Payload includes derived helpers (`start`, `end`, `totalPages`, `source`). Use `[(page)]` / `[(pageSize)]` for two-way binding; subscribe to this for the rich event payload. */
     readonly paginated: _angular_core.OutputEmitterRef<TwPaginatorPageChangeEvent>;
@@ -206,6 +223,11 @@ declare class PaginatorComponent {
     readonly pageSizeSelectorDirective: _angular_core.Signal<PaginatorPageSizeSelectorDirective | undefined>;
     private readonly _liveAnnouncer;
     private readonly _elementRef;
+    /**
+     * Optional so a consumer that never imports `BidiModule` still gets a working
+     * paginator — the key manager falls back to `'ltr'` when the token is absent.
+     */
+    private readonly _directionality;
     /** @internal All nav-group focusables (first/prev/page/next/last) for `FocusKeyManager`. */
     readonly focusableItems: _angular_core.Signal<readonly PaginatorFocusableDirective[]>;
     private readonly _componentId;
@@ -223,8 +245,20 @@ declare class PaginatorComponent {
     readonly endItem: _angular_core.Signal<number>;
     /** @internal Visible page range for the numbered type. */
     readonly range: _angular_core.Signal<PaginationRangeItem[]>;
-    /** @internal Merged labels. */
-    readonly resolvedLabels: _angular_core.Signal<TwPaginatorLabels>;
+    /**
+     * @internal Merged labels.
+     *
+     * Explicitly-undefined keys are dropped before merging. Root `tsconfig.json`
+     * does not set `exactOptionalPropertyTypes`, so
+     * `[labels]="{ pageButtonAriaLabel: i18n.pageBtn }"` type-checks even when
+     * the i18n bundle has no such key — and a plain spread would then overwrite
+     * the default with `undefined`, which reaches `formatLabel()` and throws
+     * `Cannot read properties of undefined (reading 'replace')` inside a
+     * `computed`, taking the whole page down on first render. Same filter
+     * `table.ts` and `timeline.ts` already use; `Required<>` then guarantees the
+     * template a string for every label.
+     */
+    readonly resolvedLabels: _angular_core.Signal<Required<TwPaginatorLabels>>;
     /** @internal Resolved aria-label for the root. */
     readonly resolvedAriaLabel: _angular_core.Signal<string>;
     /** @internal `container-name` for the CSS container query (set only when responsive="auto"). */

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

@@ -19,8 +19,22 @@ interface PopoverRef {
     _removeAriaLabelledBy?: (id: string) => void;
 }
 /** Injection token providing arbitrary data to popover component content. */
-declare const POPOVER_DATA: InjectionToken<unknown>;
+declare const TW_POPOVER_DATA: InjectionToken<unknown>;
 /** Injection token providing a `PopoverRef` to popover component content. */
+declare const TW_POPOVER_REF: InjectionToken<PopoverRef>;
+/**
+ * @deprecated Renamed to {@link TW_POPOVER_DATA} for consistency with every
+ * other ngx-tw injection token. This is the *same token instance*, not a copy —
+ * providing under either name and injecting under the other resolves — so the
+ * rename is safe to adopt incrementally. Removed in the next major.
+ */
+declare const POPOVER_DATA: InjectionToken<unknown>;
+/**
+ * @deprecated Renamed to {@link TW_POPOVER_REF} for consistency with every
+ * other ngx-tw injection token. This is the *same token instance*, not a copy —
+ * providing under either name and injecting under the other resolves — so the
+ * rename is safe to adopt incrementally. Removed in the next major.
+ */
 declare const POPOVER_REF: InjectionToken<PopoverRef>;
 
 /** Placement position of the popover relative to its trigger element. */
@@ -40,31 +54,31 @@ declare class PopoverDirective {
     readonly twPopoverTriggerOn: _angular_core.InputSignal<PopoverTrigger>;
     /** When true, all trigger interactions are suppressed. Defaults to `false`. */
     readonly twPopoverDisabled: _angular_core.InputSignal<boolean>;
-    /** Two-way bindable open state. Setting to `true` opens the popover; the popover sets it to `false` on close. */
+    /** Two-way bindable open state. Setting to `true` opens the popover; the popover sets it to `false` on close. Defaults to `false`. */
     readonly twPopoverOpen: _angular_core.ModelSignal<boolean>;
     /** Controls panel padding using the standard spacing scale. Defaults to `'md'`. */
     readonly twPopoverSize: _angular_core.InputSignal<TwSize>;
     /** Pixel distance between trigger and panel edge. Defaults to `8`. */
     readonly twPopoverOffset: _angular_core.InputSignal<number>;
-    /** Whether to render a directional arrow pointing at the trigger. Defaults to `true`. */
+    /** Whether to render a directional arrow pointing at the trigger. Defaults to `true` — the arrow is the visual anchor tying the panel to its trigger; the special case is a compact iconic trigger where the arrow would crowd the layout. */
     readonly twPopoverArrow: _angular_core.InputSignal<boolean>;
     /** Backdrop behavior. `'transparent'` catches outside clicks invisibly. `'dimmed'` adds a semi-transparent overlay. `'none'` disables the backdrop. Defaults to `'transparent'`. */
     readonly twPopoverBackdrop: _angular_core.InputSignal<PopoverBackdrop>;
-    /** Whether clicking outside the panel closes the popover. Only relevant when backdrop is `'none'`. Defaults to `true`. */
+    /** Whether clicking outside the panel closes the popover. Only relevant when backdrop is `'none'`. Defaults to `true` — clicking away is the universal dismiss gesture for floating panels; the special case is a popover owning a multi-step flow the user must complete. */
     readonly twPopoverCloseOnOutside: _angular_core.InputSignal<boolean>;
-    /** Whether pressing Escape closes the popover. Defaults to `true`. */
+    /** Whether pressing Escape closes the popover. Defaults to `true` — the WAI-ARIA dialog pattern mandates that Escape closes; the special case is a popover owning a child layer (nested dialog or menu) that should consume Escape first. */
     readonly twPopoverCloseOnEscape: _angular_core.InputSignal<boolean>;
     /** CDK scroll strategy for the overlay. Defaults to `'reposition'`. */
     readonly twPopoverScrollStrategy: _angular_core.InputSignal<PopoverScrollStrategy>;
-    /** Whether to trap focus inside the popover panel using CDK FocusTrapFactory. Defaults to `true`. */
+    /** Whether to trap focus inside the popover panel using CDK FocusTrapFactory. Defaults to `true` — it matches the `role="dialog"` baseline, where a focus-trapped panel announces itself as modal; the special case is an inline popover acting as an informational tooltip. */
     readonly twPopoverTrapFocus: _angular_core.InputSignal<boolean>;
-    /** Arbitrary data passed to template context or component via `POPOVER_DATA` token. */
+    /** Arbitrary data passed to template context or component via `TW_POPOVER_DATA` token. Defaults to `undefined`. */
     readonly twPopoverData: _angular_core.InputSignal<unknown>;
-    /** Additional CSS classes applied to the overlay panel for consumer customization. */
+    /** Additional CSS classes applied to the overlay panel for consumer customization. Defaults to an empty string. */
     readonly twPopoverPanelClass: _angular_core.InputSignal<string | string[]>;
     /** Optional semantic color. When set, adds a colored top border accent to the panel. */
     readonly twPopoverColor: _angular_core.InputSignal<TwColor | undefined>;
-    /** Explicit `aria-label` for the dialog panel. */
+    /** Explicit `aria-label` for the dialog panel. Defaults to `undefined`. */
     readonly twPopoverAriaLabel: _angular_core.InputSignal<string | undefined>;
     /** Fires after the popover becomes visible. */
     readonly twPopoverOpened: _angular_core.OutputEmitterRef<void>;
@@ -80,6 +94,10 @@ declare class PopoverDirective {
     private popoverInstance;
     private focusTrap;
     private perOpenSubs;
+    /** The `twPopoverBackdrop` value baked into the current `overlayRef`. */
+    private appliedBackdrop;
+    /** The `twPopoverScrollStrategy` value baked into the current `overlayRef`. */
+    private appliedScrollStrategy;
     private closing;
     private closeTimer;
     /** Tracked focus-blur close timer; cleared on destroy so it can't fire post-teardown. */
@@ -104,6 +122,19 @@ declare class PopoverDirective {
     private closePopover;
     private currentPositionStrategy;
     private buildPositionStrategy;
+    /**
+     * Ensures an `OverlayRef` exists whose creation-time configuration matches the
+     * current inputs. Returns `true` when a fresh ref was built.
+     *
+     * `hasBackdrop` / `backdropClass` are read by CDK inside `OverlayRef.attach()`
+     * straight off the config object handed to `Overlay.create()`, and there is no
+     * public setter that re-renders them. Since closing only detaches, a ref built
+     * on the first open would otherwise keep the first open's backdrop for the
+     * directive's whole lifetime — while `subscribePerOpen` re-reads
+     * `twPopoverBackdrop` every open to decide whether backdrop-click closes, so
+     * the two reads of one input disagreed. Rebuilding only when a creation-time
+     * input actually changed keeps the common reopen path on the same ref.
+     */
     private ensureOverlay;
     private updatePositionStrategy;
     private subscribePerOpen;
@@ -161,5 +192,5 @@ declare class PopoverTitleDirective implements OnInit, OnDestroy {
     static ɵdir: _angular_core.ɵɵDirectiveDeclaration<PopoverTitleDirective, "[twPopoverTitle], tw-popover-title", never, { "id": { "alias": "id"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
 }
 
-export { POPOVER_DATA, POPOVER_REF, PopoverCloseDirective, PopoverDirective, PopoverTitleDirective };
+export { POPOVER_DATA, POPOVER_REF, PopoverCloseDirective, PopoverDirective, PopoverTitleDirective, TW_POPOVER_DATA, TW_POPOVER_REF };
 export type { PopoverBackdrop, PopoverPosition, PopoverRef, PopoverScrollStrategy, PopoverTemplateContext, PopoverTrigger };