@cdevhub/ngx-tw 0.4.0 → 0.6.0

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 };

package/types/cdevhub-ngx-tw-progress-bar.d.ts

@@ -42,7 +42,7 @@ interface ProgressBarOptions {
  * ```
  */
 declare class ProgressBarComponent {
-    /** Current progress value. When null or undefined, the bar renders indeterminate. Values outside `[options.min, options.max]` are clamped. */
+    /** Current progress value. When null or undefined, the bar renders indeterminate. Values outside `[options.min, options.max]` are clamped. Defaults to `null`. */
     readonly value: _angular_core.InputSignal<number | null | undefined>;
     /** Visual style of the bar. `'linear'` renders a single fill; `'segmented'` splits the rail into discrete steps. Defaults to `'linear'`. */
     readonly variant: _angular_core.InputSignal<ProgressBarVariant>;

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

@@ -10,7 +10,7 @@ type RadioOrientation = 'horizontal' | 'vertical';
 /** Position of the label relative to the radio control. */
 type RadioLabelPosition = 'before' | 'after';
 declare class RadioComponent implements ControlValueAccessor, OnInit {
-    /** The value this radio contributes when selected inside a `tw-radio-group`. Required when nested in a group; ignored when used standalone. */
+    /** The value this radio contributes when selected inside a `tw-radio-group`. Required when nested in a group; ignored when used standalone. Defaults to `undefined`. */
     readonly value: _angular_core.InputSignal<unknown>;
     /** Overrides the parent group's color for this radio. When undefined, inherits from the group (or defaults to `'primary'` standalone). */
     readonly color: _angular_core.InputSignal<TwColor | undefined>;
@@ -28,31 +28,51 @@ declare class RadioComponent implements ControlValueAccessor, OnInit {
     readonly labelPosition: _angular_core.InputSignal<RadioLabelPosition>;
     /** Optional name attribute for standalone use. Ignored when the parent group provides a name. */
     readonly name: _angular_core.InputSignal<string | undefined>;
-    /** Accessible name when no visible label is provided. Mirrored to `aria-label`. */
+    /** Accessible name when no visible label is provided. Mirrored to `aria-label`. Defaults to `undefined`. */
     readonly ariaLabel: _angular_core.InputSignal<string | undefined>;
-    /** ID of an external element that labels the radio. Mirrored to `aria-labelledby`. */
+    /** ID of an external element that labels the radio. Mirrored to `aria-labelledby`. Defaults to `undefined`. */
     readonly ariaLabelledby: _angular_core.InputSignal<string | undefined>;
-    /** ID of an external element that describes the radio. Mirrored to `aria-describedby`. */
+    /** ID of an external element that describes the radio. Mirrored to `aria-describedby`. Defaults to `undefined`. */
     readonly ariaDescribedby: _angular_core.InputSignal<string | undefined>;
-    /** Two-way bound checked state. Authoritative only in standalone mode; when inside a `tw-radio-group`, this model reflects group selection but does NOT drive it. */
+    /**
+     * Two-way bound checked state. Authoritative only in standalone mode.
+     * Defaults to `false`.
+     *
+     * Standalone, the minted `checkedChange` output is the *any-change* channel:
+     * it fires both when the user selects this radio and when a bound form writes
+     * into it (`FormControl.setValue`, `ngModel`, `writeValue`). `(change)` is the
+     * *user-gesture-only* channel — bind that one for analytics or a confirmation
+     * prompt, where a programmatic write must not count as a click.
+     *
+     * Inside a `tw-radio-group` this model is inert: the group owns selection,
+     * the rendered state comes from the group's `value`, and the component never
+     * writes `checked` — so `(checkedChange)` never fires on a grouped radio.
+     * `(change)` still fires when this radio becomes the selected one. Bind the
+     * group's `[(value)]` / `(change)` instead.
+     */
     readonly checked: _angular_core.ModelSignal<boolean>;
     /** Per-instance override of the {@link ErrorStateMatcher}. When omitted, the radio uses the `TW_ERROR_STATE_MATCHER` token's value. */
     readonly errorStateMatcher: _angular_core.InputSignal<ErrorStateMatcher | undefined>;
-    /** Fires after the checked state changes from a user interaction on this radio. In grouped mode only fires when this radio becomes the selected one. Does not fire when selection is updated programmatically. */
+    /**
+     * Fires after the checked state changes from a user interaction on this
+     * radio. In grouped mode only fires when this radio becomes the selected one.
+     * Does **not** fire when selection is updated programmatically via
+     * `writeValue` / `FormControl.setValue` / `ngModel` — standalone, bind the
+     * two-way binding's `(checkedChange)` for that, which fires on any change.
+     * (Grouped, `(checkedChange)` never fires at all; use the group's
+     * `[(value)]`.)
+     */
     readonly change: _angular_core.OutputEmitterRef<boolean>;
     private readonly focusMonitor;
     readonly elementRef: ElementRef<any>;
     private readonly destroyRef;
     private readonly parent;
     private readonly ngControl;
-    private readonly parentForm;
-    private readonly parentFormGroup;
-    private readonly defaultMatcher;
     private onChange;
     private onTouched;
     private readonly cvaDisabled;
-    private readonly _ngControlRev;
-    private readonly _formSubmitRev;
+    /** @internal Shared `errorState` derivation — see `wireErrorState`. */
+    private readonly errorWiring;
     private readonly uid;
     readonly hostId: string;
     readonly labelId: string;
@@ -110,25 +130,52 @@ declare class RadioGroupComponent<T = unknown> implements ControlValueAccessor,
     readonly size: _angular_core.InputSignal<TwSize>;
     /** Visual style of the selected indicator. `'solid'` fills the dot with the color against a colored ring; `'outline'` keeps a transparent fill with a colored ring and colored dot. Propagated to children unless a child overrides it. Defaults to `'solid'`. */
     readonly variant: _angular_core.InputSignal<RadioVariant>;
-    /** Layout direction of the group. Drives `aria-orientation` and the arrow-key model. Defaults to `'vertical'`. */
+    /** Layout direction of the group. Sets `aria-orientation` and the visual axis; both arrow-key pairs navigate in either orientation, per WAI-ARIA APG. Defaults to `'vertical'`. */
     readonly orientation: _angular_core.InputSignal<RadioOrientation>;
     /** When true, disables every radio in the group and blocks keyboard interaction. Defaults to `false`. */
     readonly disabled: _angular_core.InputSignal<boolean>;
-    /** When true, sets `aria-required="true"` on the group for assistive tech. Defaults to `false`. */
-    readonly required: _angular_core.InputSignal<boolean>;
+    /** When true, sets `aria-required="true"` on the group for assistive tech. Also inferred from `Validators.required` on a bound control, so a reactive/template-driven form does not have to state it twice. Defaults to `false`. */
+    readonly requiredInput: _angular_core.InputSignal<boolean>;
+    /**
+     * @internal Shared `errorState` / `required` / `errors` derivation — see
+     * `wireErrorState`. Declared here, above `required`, because class field
+     * initializers run in declaration order.
+     */
+    private readonly errorWiring;
+    /**
+     * @internal Resolved required state: the `required` input OR'd with
+     * `Validators.required` on a bound `NgControl`.
+     */
+    readonly required: Signal<boolean>;
     /** Optional form-association name. Propagated to each child radio's host `name` attribute so standard HTML form semantics still apply. */
     readonly name: _angular_core.InputSignal<string | undefined>;
-    /** Accessible name for the group when no visible label is provided. Mirrored to `aria-label`. */
+    /** Accessible name for the group when no visible label is provided. Mirrored to `aria-label`. Defaults to `undefined`. */
     readonly ariaLabel: _angular_core.InputSignal<string | undefined>;
-    /** ID of an external element that labels the group. Mirrored to `aria-labelledby`. */
+    /** ID of an external element that labels the group. Mirrored to `aria-labelledby`. Defaults to `undefined`. */
     readonly ariaLabelledby: _angular_core.InputSignal<string | undefined>;
-    /** ID of an external element that describes the group. Mirrored to `aria-describedby`. */
+    /** ID of an external element that describes the group. Mirrored to `aria-describedby`. Defaults to `undefined`. */
     readonly ariaDescribedby: _angular_core.InputSignal<string | undefined>;
-    /** Two-way bound selected value. Updates when the user picks a radio; fires `valueChange`. `null` means no selection. */
+    /**
+     * Two-way bound selected value. `null` means no selection. Defaults to
+     * `null`.
+     *
+     * The two-way binding mints a `valueChange` output. That output is the
+     * *any-change* channel: it fires when the user picks a radio **and** when a
+     * bound form writes into the group (`FormControl.setValue`, `ngModel`,
+     * `writeValue`). `(change)` is the *user-gesture-only* channel — bind that
+     * one for analytics or a confirmation prompt, where a programmatic write must
+     * not count as a click. Writing back into the same form from a
+     * `(valueChange)` handler will echo.
+     */
     readonly value: _angular_core.ModelSignal<T | null>;
     /** Per-instance override of the {@link ErrorStateMatcher}. When omitted, the group uses the `TW_ERROR_STATE_MATCHER` token's value. */
     readonly errorStateMatcher: _angular_core.InputSignal<ErrorStateMatcher | undefined>;
-    /** Fires after the selected value changes from a user interaction. Does not fire when the value is updated programmatically via `writeValue`. */
+    /**
+     * Fires after the selected value changes from a user interaction. Does
+     * **not** fire when the value is updated programmatically via `writeValue` /
+     * `FormControl.setValue` / `ngModel` — for those, bind the two-way binding's
+     * `(valueChange)` instead, which fires on any change.
+     */
     readonly change: _angular_core.OutputEmitterRef<T | null>;
     /** @internal Child radios discovered via content projection. */
     readonly radios: Signal<readonly RadioComponent[]>;
@@ -136,15 +183,10 @@ declare class RadioGroupComponent<T = unknown> implements ControlValueAccessor,
     private readonly elementRef;
     private readonly destroyRef;
     private readonly ngControl;
-    private readonly parentForm;
-    private readonly parentFormGroup;
-    private readonly defaultMatcher;
     readonly hostId: string;
     private onChange;
     private onTouched;
     private readonly cvaDisabled;
-    private readonly _ngControlRev;
-    private readonly _formSubmitRev;
     /** Effective disabled state — input OR CVA disabled. */
     readonly isDisabled: Signal<boolean>;
     /** Group-level error state per the configured `ErrorStateMatcher`. Reads the bound `NgControl.invalid` through the matcher; child radios inherit from this when wrapped in the group. */
@@ -157,6 +199,7 @@ declare class RadioGroupComponent<T = unknown> implements ControlValueAccessor,
     selectValue(next: unknown): void;
     /** @internal Called by child radios on blur — propagates to CVA onTouched and bumps the errorState revision so a blur on a child radio refreshes the group's `aria-invalid`. */
     notifyTouched(): void;
+    /** @internal Handles roving-focus keyboard navigation (Arrow keys, Space) across the radios in the group. */
     onKeydown(event: KeyboardEvent): void;
     private findNextEnabledIndex;
     private firstEnabledIndex;
@@ -167,7 +210,7 @@ declare class RadioGroupComponent<T = unknown> implements ControlValueAccessor,
     setDisabledState(isDisabled: boolean): void;
     ngOnInit(): void;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<RadioGroupComponent<any>, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<RadioGroupComponent<any>, "tw-radio-group", never, { "color": { "alias": "color"; "required": false; "isSignal": true; }; "size": { "alias": "size"; "required": false; "isSignal": true; }; "variant": { "alias": "variant"; "required": false; "isSignal": true; }; "orientation": { "alias": "orientation"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "required": { "alias": "required"; "required": false; "isSignal": true; }; "name": { "alias": "name"; "required": false; "isSignal": true; }; "ariaLabel": { "alias": "aria-label"; "required": false; "isSignal": true; }; "ariaLabelledby": { "alias": "aria-labelledby"; "required": false; "isSignal": true; }; "ariaDescribedby": { "alias": "aria-describedby"; "required": false; "isSignal": true; }; "value": { "alias": "value"; "required": false; "isSignal": true; }; "errorStateMatcher": { "alias": "errorStateMatcher"; "required": false; "isSignal": true; }; }, { "value": "valueChange"; "change": "change"; }, ["radios"], ["*"], true, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<RadioGroupComponent<any>, "tw-radio-group", never, { "color": { "alias": "color"; "required": false; "isSignal": true; }; "size": { "alias": "size"; "required": false; "isSignal": true; }; "variant": { "alias": "variant"; "required": false; "isSignal": true; }; "orientation": { "alias": "orientation"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "requiredInput": { "alias": "required"; "required": false; "isSignal": true; }; "name": { "alias": "name"; "required": false; "isSignal": true; }; "ariaLabel": { "alias": "aria-label"; "required": false; "isSignal": true; }; "ariaLabelledby": { "alias": "aria-labelledby"; "required": false; "isSignal": true; }; "ariaDescribedby": { "alias": "aria-describedby"; "required": false; "isSignal": true; }; "value": { "alias": "value"; "required": false; "isSignal": true; }; "errorStateMatcher": { "alias": "errorStateMatcher"; "required": false; "isSignal": true; }; }, { "value": "valueChange"; "change": "change"; }, ["radios"], ["*"], true, never>;
 }
 
 export { RadioComponent, RadioGroupComponent };

package/types/cdevhub-ngx-tw-segmented-control.d.ts

@@ -1,10 +1,19 @@
 import * as _angular_core from '@angular/core';
-import { ElementRef } from '@angular/core';
+import { OnInit, Signal, ElementRef } from '@angular/core';
 import { ControlValueAccessor } from '@angular/forms';
-import { TwColor, TwSize, TwOrientation } from '@cdevhub/ngx-tw/core';
+import { TwColor, TwSize, TwOrientation, ErrorStateMatcher } from '@cdevhub/ngx-tw/core';
 
 /** Visual style of the active indicator. */
-type SegmentedControlVariant = 'surface' | 'filled' | 'outline';
+type SegmentedControlVariant = 'surface' | 'solid' | 'outline' | SegmentedControlVariantLegacy;
+/**
+ * Legacy `variant` spellings, kept so existing templates keep compiling.
+ *
+ * @deprecated `'filled'` is an alias for `'solid'`; it will be removed in the next
+ * major. Prefer `'solid'`.
+ */
+type SegmentedControlVariantLegacy = 'filled';
+/** Canonical `variant` spellings — the set `tv()` actually keys on. */
+type SegmentedControlVariantCanonical = Exclude<SegmentedControlVariant, SegmentedControlVariantLegacy>;
 /** Border-radius shape of the container and options. */
 type SegmentedControlRounded = 'pill' | 'md';
 declare class SegmentedControlOptionComponent {
@@ -16,17 +25,19 @@ declare class SegmentedControlOptionComponent {
     private readonly parent;
     readonly id: string;
     constructor();
-    readonly isActive: _angular_core.Signal<boolean>;
-    readonly isDisabled: _angular_core.Signal<boolean>;
-    readonly isFocusable: _angular_core.Signal<boolean>;
-    readonly classes: _angular_core.Signal<string>;
+    readonly isActive: Signal<boolean>;
+    readonly isDisabled: Signal<boolean>;
+    readonly isFocusable: Signal<boolean>;
+    readonly classes: Signal<string>;
+    /** Selects this option in the parent segmented control. No-op when the option is disabled. */
     select(): void;
+    /** Moves DOM focus to this option's element. Called by the parent group's arrow-key handler, which moves focus and selection together (selection-follows-focus, as WAI-ARIA APG specifies for a radiogroup). */
     focus(): void;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<SegmentedControlOptionComponent, never>;
     static ɵcmp: _angular_core.ɵɵComponentDeclaration<SegmentedControlOptionComponent, "tw-segmented-option", never, { "value": { "alias": "value"; "required": true; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; }, {}, never, ["*"], true, never>;
 }
-declare class SegmentedControlComponent implements ControlValueAccessor {
-    /** Controls the active indicator style. `'surface'` shows a raised white pill; `'filled'` shows a solid colored background; `'outline'` shows a colored ring border. Defaults to `'surface'`. */
+declare class SegmentedControlComponent implements ControlValueAccessor, OnInit {
+    /** Controls the active indicator style. `'surface'` shows a raised white pill; `'solid'` shows a solid colored background; `'outline'` shows a colored ring border. Defaults to `'surface'`. `'filled'` is a deprecated alias for `'solid'`. */
     readonly variant: _angular_core.InputSignal<SegmentedControlVariant>;
     /** Sets the semantic color for the active option indicator. Defaults to `'primary'`. */
     readonly color: _angular_core.InputSignal<TwColor>;
@@ -38,29 +49,81 @@ declare class SegmentedControlComponent implements ControlValueAccessor {
     readonly rounded: _angular_core.InputSignal<SegmentedControlRounded>;
     /** When true, prevents all interaction and applies muted styling. Defaults to `false`. */
     readonly disabled: _angular_core.InputSignal<boolean>;
-    /** The value of the currently selected option. Two-way bound. Updates on user selection. */
+    /** When true, sets `aria-required="true"` on the radiogroup so assistive tech announces a choice is mandatory. Also inferred from `Validators.required` on a bound control, so a reactive/template-driven form does not have to state it twice. Defaults to `false`. */
+    readonly requiredInput: _angular_core.InputSignal<boolean>;
+    /** Per-instance override of the {@link ErrorStateMatcher}. When omitted, the control uses the `TW_ERROR_STATE_MATCHER` token's value. */
+    readonly errorStateMatcher: _angular_core.InputSignal<ErrorStateMatcher | undefined>;
+    /**
+     * The value of the currently selected option. Two-way bound. Defaults to
+     * `null`.
+     *
+     * The two-way binding mints a `valueChange` output, and it is the
+     * *any-change* channel: it fires on user selection **and** on a programmatic
+     * write from a bound form (`FormControl.setValue`, `ngModel`, `writeValue`).
+     * Unlike `tw-checkbox` / `tw-switch` / `tw-radio-group`, this control ships no
+     * separate gesture-only `change` output, so writing back into the same form
+     * from a `(valueChange)` handler will echo. To act on user selection alone,
+     * compare against the value you last wrote, or listen on the form control.
+     */
     readonly value: _angular_core.ModelSignal<string | null>;
     /** @internal */
-    readonly options: _angular_core.Signal<readonly SegmentedControlOptionComponent[]>;
+    readonly options: Signal<readonly SegmentedControlOptionComponent[]>;
+    private readonly elementRef;
+    private readonly ngControl;
+    /**
+     * Optional so a consumer that never imports `BidiModule` still gets a working
+     * control — arrow navigation falls back to LTR when the token is absent. Read
+     * imperatively inside the keydown handler; nothing here needs to re-render on
+     * a direction change.
+     */
+    private readonly directionality;
     private onChange;
     private onTouched;
     private readonly cvaDisabled;
-    readonly isDisabled: _angular_core.Signal<boolean>;
+    /** @internal Shared `errorState` / `required` / `errors` derivation — see `wireErrorState`. */
+    private readonly errorWiring;
+    constructor();
+    readonly isDisabled: Signal<boolean>;
+    /**
+     * @internal Resolved required state: the `required` input OR'd with
+     * `Validators.required` on a bound `NgControl`. The OR (rather than a
+     * validator-only read) is what keeps signal forms working — `cvaControlCreate`
+     * writes the `required` *input* directly from the field state and never
+     * consults validators, so the input arm carries that branch while the
+     * validator arm carries reactive/template-driven forms.
+     */
+    readonly required: Signal<boolean>;
+    /** @internal Whether the control is in an error state per the configured `ErrorStateMatcher`. Reads the bound `NgControl.invalid` through the matcher and drives `aria-invalid` on the radiogroup host. */
+    readonly errorState: Signal<boolean>;
     readonly activeValue: _angular_core.WritableSignal<string | null>;
     /** @internal Read by `SegmentedControlOptionComponent.classes` to resolve the option's tv() bucket. Vertical orientation forces `'md'` regardless of input. */
-    readonly effectiveRounded: _angular_core.Signal<SegmentedControlRounded>;
+    readonly effectiveRounded: Signal<SegmentedControlRounded>;
+    /** @internal Canonical variant with legacy spellings folded in. Read by `SegmentedControlOptionComponent.classes` to resolve the option's tv() bucket. */
+    readonly resolvedVariant: Signal<SegmentedControlVariantCanonical>;
     private readonly variantResult;
-    readonly rootClasses: _angular_core.Signal<string>;
+    readonly rootClasses: Signal<string>;
+    /** Selects the option with the given value, updating the two-way bound `value` and notifying the registered `ControlValueAccessor` callbacks. No-op when the control is disabled. */
     selectOption(val: string): void;
+    /**
+     * @internal Blur notification for the CVA contract. Fires `onTouched` only
+     * when focus leaves the radiogroup entirely — roving focus moves between
+     * option elements inside the group, and each of those hops raises `focusout`
+     * on the host too. Without this the control is only ever marked `touched` by
+     * a selection, so a user who tabs through without choosing never surfaces the
+     * `required` error.
+     */
+    onFocusOut(event: FocusEvent): void;
+    /** @internal Handles roving-focus keyboard navigation (Arrow keys, Home, End) and Space / Enter activation across the option group. */
     onKeydown(event: KeyboardEvent): void;
     private findNextEnabledIndex;
     writeValue(val: string | null): void;
     registerOnChange(fn: (value: string | null) => void): void;
     registerOnTouched(fn: () => void): void;
     setDisabledState(isDisabled: boolean): void;
+    ngOnInit(): void;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<SegmentedControlComponent, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<SegmentedControlComponent, "tw-segmented-control", never, { "variant": { "alias": "variant"; "required": false; "isSignal": true; }; "color": { "alias": "color"; "required": false; "isSignal": true; }; "size": { "alias": "size"; "required": false; "isSignal": true; }; "orientation": { "alias": "orientation"; "required": false; "isSignal": true; }; "rounded": { "alias": "rounded"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "value": { "alias": "value"; "required": false; "isSignal": true; }; }, { "value": "valueChange"; }, ["options"], ["*"], true, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<SegmentedControlComponent, "tw-segmented-control", never, { "variant": { "alias": "variant"; "required": false; "isSignal": true; }; "color": { "alias": "color"; "required": false; "isSignal": true; }; "size": { "alias": "size"; "required": false; "isSignal": true; }; "orientation": { "alias": "orientation"; "required": false; "isSignal": true; }; "rounded": { "alias": "rounded"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "requiredInput": { "alias": "required"; "required": false; "isSignal": true; }; "errorStateMatcher": { "alias": "errorStateMatcher"; "required": false; "isSignal": true; }; "value": { "alias": "value"; "required": false; "isSignal": true; }; }, { "value": "valueChange"; }, ["options"], ["*"], true, never>;
 }
 
 export { SegmentedControlComponent, SegmentedControlOptionComponent };
-export type { SegmentedControlRounded, SegmentedControlVariant };
+export type { SegmentedControlRounded, SegmentedControlVariant, SegmentedControlVariantLegacy };