@cdevhub/ngx-tw 0.5.0 → 0.6.1

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

@@ -143,13 +143,13 @@ declare class SelectFooterTemplateDirective {
 declare class SelectComponent<T = unknown> implements ControlValueAccessor, FormFieldControl<T | readonly T[]>, OnInit {
     /** Array of options to render in the panel. Accepts either `TwSelectOption<T>` objects or arbitrary records read via the accessor inputs. Defaults to an empty array. */
     readonly options: _angular_core.InputSignal<readonly unknown[]>;
-    /** Accessor returning the visible label for an option. Override when passing arbitrary objects. */
+    /** Accessor returning the visible label for an option. Override when passing arbitrary objects. Defaults to reading `.label`, falling back to `String(.value)`. */
     readonly optionLabel: _angular_core.InputSignal<(option: unknown) => string>;
-    /** Accessor returning the value for an option. The result is what `value` / `valueChange` emit. */
+    /** Accessor returning the value for an option. The result is what `value` / `valueChange` emit. Defaults to reading `.value`. */
     readonly optionValue: _angular_core.InputSignal<(option: unknown) => T>;
     /** Accessor returning the disabled state for an option. Defaults to reading `.disabled`. */
     readonly optionDisabled: _angular_core.InputSignal<(option: unknown) => boolean>;
-    /** Accessor returning the group name for an option. Options sharing a group render under a labelled `role="group"` region. */
+    /** Accessor returning the group name for an option. Options sharing a group render under a labelled `role="group"` region. Defaults to reading `.group`. */
     readonly optionGroup: _angular_core.InputSignal<(option: unknown) => string | undefined>;
     /** When true, enables multi-selection. The `value` model becomes a `T[]` and the panel renders checkable options. Defaults to `false`. */
     readonly multiple: _angular_core.InputSignal<boolean>;
@@ -157,11 +157,11 @@ declare class SelectComponent<T = unknown> implements ControlValueAccessor, Form
     readonly searchable: _angular_core.InputSignal<boolean>;
     /** Custom filter function for the search input. Defaults to a case-insensitive substring match on the option label. */
     readonly filterPredicate: _angular_core.InputSignal<(option: unknown, search: string) => boolean>;
-    /** Placeholder text shown in the trigger when no value is selected. */
+    /** Placeholder text shown in the trigger when no value is selected. Defaults to `undefined`. */
     readonly placeholder: _angular_core.InputSignal<string | undefined>;
-    /** When true, the trigger cannot be activated and the panel cannot open. Defaults to `false`. */
+    /** When true, the trigger cannot be activated and the panel cannot open. Defaults to `false`. Alias: `disabled`. */
     readonly disabledInput: _angular_core.InputSignal<boolean>;
-    /** When true, exposes `aria-required="true"` on the trigger. Defaults to `false`. */
+    /** When true, exposes `aria-required="true"` on the trigger and the `*` marker on a wrapping `tw-form-field`. 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>;
     /** Controls trigger padding, font size, and panel option density. Defaults to `'md'`. */
     readonly size: _angular_core.InputSignal<TwSize>;
@@ -171,7 +171,7 @@ declare class SelectComponent<T = unknown> implements ControlValueAccessor, Form
     readonly variant: _angular_core.InputSignal<SelectVariant | undefined>;
     /** Overlay panel width. `'trigger'` matches the trigger's measured width; `'auto'` lets content decide; a number is applied as pixels; a string is passed through as a CSS length. Defaults to `'trigger'`. */
     readonly panelWidth: _angular_core.InputSignal<string | number>;
-    /** Extra class(es) applied to the overlay panel element. */
+    /** Extra class(es) applied to the overlay panel element. Defaults to an empty string. */
     readonly panelClass: _angular_core.InputSignal<string | readonly string[]>;
     /** Maximum height of the listbox scroll region in pixels. Defaults to `256`. */
     readonly panelMaxHeight: _angular_core.InputSignal<number>;
@@ -181,27 +181,27 @@ declare class SelectComponent<T = unknown> implements ControlValueAccessor, Form
     readonly scrollStrategy: _angular_core.InputSignal<"reposition" | "close" | "block">;
     /** Pixel distance between trigger and panel. Defaults to `4`. */
     readonly offset: _angular_core.InputSignal<number>;
-    /** Fallback message rendered when the filter yields no options and no `*twSelectEmpty` template is provided. */
+    /** Fallback message rendered when the filter yields no options and no `*twSelectEmpty` template is provided. Defaults to `'No results'`. */
     readonly emptyMessage: _angular_core.InputSignal<string>;
-    /** Accessible name for the combobox trigger. */
+    /** Accessible name for the combobox trigger. Defaults to `undefined`. Alias: `aria-label`. */
     readonly ariaLabel: _angular_core.InputSignal<string | undefined>;
-    /** ID of an external element that labels the combobox. */
+    /** ID of an external element that labels the combobox. Defaults to `undefined`. Alias: `aria-labelledby`. */
     readonly ariaLabelledby: _angular_core.InputSignal<string | undefined>;
-    /** ID of an external element that describes the combobox. */
+    /** ID of an external element that describes the combobox. Defaults to `undefined`. Alias: `aria-describedby`. */
     readonly ariaDescribedby: _angular_core.InputSignal<string | undefined>;
     /** Per-instance override of the {@link ErrorStateMatcher}. When omitted, the select uses the `TW_ERROR_STATE_MATCHER` token's value. */
     readonly errorStateMatcher: _angular_core.InputSignal<ErrorStateMatcher | undefined>;
     /** Equality comparator for option values. Defaults to `Object.is`. */
     readonly compareWith: _angular_core.InputSignal<(a: T, b: T) => boolean>;
-    /** Two-way bound selected value(s). Single-select: `T | null`. Multi-select: `T[]`. */
+    /** Two-way bound selected value(s). Single-select: `T | null`. Multi-select: `T[]`. Defaults to `null`. */
     readonly value: _angular_core.ModelSignal<T | readonly T[] | null>;
-    /** Two-way bound open state of the panel. */
+    /** Two-way bound open state of the panel. Defaults to `false`. */
     readonly open: _angular_core.ModelSignal<boolean>;
-    /** Fires when the panel's visibility finishes changing. */
+    /** Fires when the panel's visibility finishes changing. Payload carries the new `open` state and the trigger element the overlay is anchored to. */
     readonly openedChange: _angular_core.OutputEmitterRef<TwSelectOpenedEvent>;
     /** Fires after any selection change, with `added`, `removed`, `previousValue`, and a `source` discriminator. */
     readonly selectionChange: _angular_core.OutputEmitterRef<TwSelectSelectionChangeEvent<T>>;
-    /** Fires whenever the search input changes (only when `searchable` is true). */
+    /** Fires whenever the search input changes (only when `searchable` is true). Payload carries the raw, untrimmed query and the post-filter `visibleCount`. Emitted immediately, not debounced. */
     readonly searchChange: _angular_core.OutputEmitterRef<TwSelectSearchEvent>;
     /** @internal */
     readonly triggerTemplateChild: Signal<SelectTriggerTemplateDirective<any, any> | undefined>;
@@ -213,7 +213,10 @@ declare class SelectComponent<T = unknown> implements ControlValueAccessor, Form
     readonly headerTemplateChild: Signal<SelectHeaderTemplateDirective | undefined>;
     /** @internal */
     readonly footerTemplateChild: Signal<SelectFooterTemplateDirective | undefined>;
+    /** @internal The combobox trigger — focus target after the clear control unmounts. */
+    private readonly triggerButtonRef;
     private readonly overlayService;
+    private readonly coordinator;
     private readonly elementRef;
     private readonly viewContainerRef;
     private readonly injector;
@@ -223,9 +226,6 @@ declare class SelectComponent<T = unknown> implements ControlValueAccessor, Form
     private readonly platform;
     private readonly formField;
     private readonly ngControl;
-    private readonly parentForm;
-    private readonly parentFormGroup;
-    private readonly defaultMatcher;
     private readonly uid;
     /** @internal */
     readonly hostId: string;
@@ -244,19 +244,22 @@ declare class SelectComponent<T = unknown> implements ControlValueAccessor, Form
     /** @internal */
     readonly focusedSignal: _angular_core.WritableSignal<boolean>;
     private readonly cvaDisabled;
-    private readonly _ngControlRev;
-    private readonly _formSubmitRev;
+    /** @internal Shared `errorState` / `required` / `errors` derivation — see `wireErrorState`. */
+    private readonly errorWiring;
     private readonly describedByIdsSignal;
     private readonly labelledByIdsSignal;
-    private readonly closingSignal;
     private onChange;
     private onTouched;
-    private overlayRef;
-    private readonly overlayInstanceSignal;
-    private perOpenSubs;
-    private closeTimer;
+    /**
+     * Watches the host for size changes so `panelWidth="trigger"` keeps tracking
+     * while the panel is up. Minted per open and disconnected on close, because
+     * the `OverlayRef` it feeds is disposed on close (see `openOverlay`).
+     */
     private resizeObserver;
-    private get overlayInstance();
+    private overlayInstance;
+    private closing;
+    /** Flips true once the overlay component is attached; the sole trigger for the state-push effect. */
+    private readonly isAttached;
     /** @internal */
     readonly isDisabled: Signal<boolean>;
     /** @internal Effective variant — auto-naked when wrapped in tw-form-field. */
@@ -275,6 +278,16 @@ declare class SelectComponent<T = unknown> implements ControlValueAccessor, Form
     readonly showClearButton: Signal<boolean>;
     /** @internal */
     readonly activeDescendantId: Signal<string | null>;
+    /**
+     * @internal `aria-activedescendant` for the trigger button.
+     *
+     * Null while a searchable panel is open: `openOverlay()` moves DOM focus to
+     * the overlay's search input, and `aria-activedescendant` is only honoured
+     * on the element that actually holds focus. Leaving it on the blurred
+     * trigger made arrow-key navigation silent to assistive tech. The overlay's
+     * search input carries it instead in that mode.
+     */
+    readonly triggerActiveDescendantId: Signal<string | null>;
     /** @internal */
     readonly describedBy: Signal<string>;
     /** @internal Merged `aria-labelledby`: form-field-pushed label ids + consumer-supplied `aria-labelledby`. */
@@ -295,7 +308,9 @@ declare class SelectComponent<T = unknown> implements ControlValueAccessor, Form
     /** @internal */
     readonly clearButtonClasses: Signal<string>;
     /** @internal */
-    readonly optionSizeClass: Signal<"px-3 py-1.5 text-sm" | "px-2 py-1 text-xs gap-1.5" | "px-3 py-2 text-sm" | "px-4 py-2.5 text-base" | "px-4 py-3 text-base">;
+    readonly clearSpacerClasses: Signal<string>;
+    /** @internal */
+    readonly optionSizeClass: Signal<"px-2 py-1 text-xs gap-1.5" | "px-3 py-1.5 text-sm" | "px-3 py-2 text-sm" | "px-4 py-2.5 text-base" | "px-4 py-3 text-base">;
     /** @internal */
     readonly checkmarkColorClass: Signal<string>;
     /** @internal Class string applied to each option row. */
@@ -308,8 +323,18 @@ declare class SelectComponent<T = unknown> implements ControlValueAccessor, Form
     readonly empty: Signal<boolean>;
     /** @internal */
     readonly disabled: Signal<boolean>;
-    /** @internal */
+    /**
+     * @internal Resolved required state: the `required` input OR'd with
+     * `Validators.required` on a bound `NgControl`. Without the validator arm the
+     * form-field `*` marker (`FormFieldComponent.isRequired`) and the trigger's
+     * `aria-required` silently vanish under reactive/template-driven forms, while
+     * signal forms shows them — `cvaControlCreate` writes the `required` *input*
+     * directly from the field state and never consults validators. The OR keeps
+     * both branches true at once.
+     */
     readonly required: Signal<boolean>;
+    /** @internal Active validation errors map from the bound `NgControl`. Drives `[twError match="…"]` inside a wrapping `tw-form-field`; without it the form-field's key set is permanently empty and every `match`ed error stays hidden. */
+    readonly errors: Signal<Record<string, unknown> | null>;
     /** @internal Error-state per the configured `ErrorStateMatcher`. Reads the bound `NgControl.invalid` through the matcher. */
     readonly errorState: Signal<boolean>;
     /** @internal */
@@ -336,10 +361,38 @@ declare class SelectComponent<T = unknown> implements ControlValueAccessor, Form
     selectByVisibleIndex(index: number, source?: TwSelectSelectionSource): void;
     /** @internal */
     onTriggerClick(): void;
-    /** @internal */
+    /**
+     * @internal
+     *
+     * `stopPropagation` + `preventDefault` are load-bearing even now that the
+     * control is a sibling of the trigger rather than nested inside it: inside a
+     * `tw-form-field` the click still bubbles to the field's control wrapper,
+     * which calls `onContainerClick()` and would open the panel on a clear.
+     */
     onClearClick(event: MouseEvent): void;
-    /** @internal */
+    /**
+     * @internal
+     *
+     * A native `button` already activates on Enter and Space in a browser, so
+     * this looks redundant — it is not. `preventDefault()` here suppresses that
+     * native activation, so the two paths cannot both fire, and jsdom never
+     * synthesises a click from a key event at all, which makes this the only
+     * keyboard path a unit spec can exercise.
+     */
     onClearKeydown(event: KeyboardEvent): void;
+    /**
+     * Clearing removes the clear control from the DOM (`showClearButton()` goes
+     * false), so whatever had focus is destroyed under the user. Hand focus back
+     * to the trigger rather than letting it fall to `<body>` (SC 2.4.3).
+     *
+     * The disabled guard is not redundant. `[disabled]` on a native button makes
+     * `.focus()` a silent no-op (the same trap `calendar-cell` hit), and today
+     * the only reason the path cannot be reached is that `showClearButton()`
+     * happens to include `!isDisabled()`. That is ordering, not a guarantee: a
+     * `setDisabledState(true)` landing between the keydown and this call would
+     * drop focus to `<body>` with nothing to show for it.
+     */
+    private focusTrigger;
     /** @internal */
     onTriggerKeydown(event: KeyboardEvent): void;
     /** @internal Handles keyboard events from the trigger AND the search input inside the overlay. */
@@ -354,15 +407,33 @@ declare class SelectComponent<T = unknown> implements ControlValueAccessor, Form
     initActiveIndexOnOpen(): void;
     private scrollActiveIntoView;
     private commitSelection;
+    /**
+     * Builds and attaches the panel through {@link PickerOverlayCoordinator}.
+     *
+     * The coordinator disposes the `OverlayRef` on close, so every value read
+     * here — `offset`, `scrollStrategy`, `panelClass`, and the position
+     * strategy's origin — is re-read on each open rather than frozen at the
+     * first one. That replaces the previous `refreshPositionConfig()` /
+     * `applyScrollStrategy()` pair, which could only refresh the two inputs it
+     * knew about on a reused ref.
+     *
+     * `focusTrap: false` is load-bearing: this is an `aria-activedescendant`
+     * listbox, so DOM focus stays on the trigger (or the panel's search input)
+     * and a trap's anchor elements would inject tab stops around the panel.
+     */
     private openOverlay;
     private closeOverlay;
-    private ensureOverlay;
     private installResizeObserver;
     private updateOverlaySize;
-    private attachOverlayComponent;
+    /**
+     * Registers the backdrop-click and Escape listeners for one open.
+     *
+     * Both streams come from the coordinator, which completes them when the
+     * overlay closes — so there is no per-open `Subscription` aggregate to keep
+     * and no way for listeners to accumulate across opens.
+     */
     private subscribePerOpen;
     private resolvePanelClass;
-    private clearCloseTimer;
     /** @internal */
     buildTriggerContext(): TwSelectTriggerContext<T>;
     writeValue(value: T | readonly T[] | null): void;

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

@@ -0,0 +1,104 @@
+import { ComponentHarness, BaseHarnessFilters, HarnessPredicate } from '@angular/cdk/testing';
+import { SheetSide } from '@cdevhub/ngx-tw/sheet';
+
+/** Filters accepted by `SheetHarness.with`. */
+interface SheetHarnessFilters extends BaseHarnessFilters {
+    /** Match by the sheet's id — the same value as `SheetRef.id`. */
+    id?: string | RegExp;
+    /** Match by the text of the projected `[twSheetTitle]` element. */
+    title?: string | RegExp;
+    /** Match by the edge the sheet is anchored to. */
+    side?: SheetSide;
+}
+/**
+ * Harness for a sheet opened with `Sheet.open()`.
+ *
+ * ## Loading it
+ *
+ * A sheet is **service-opened**, not template-declared: nothing in the test
+ * fixture's own DOM represents it, and the container renders into the CDK
+ * overlay container on `document.body`. This harness's host *is* that container,
+ * so it must be loaded from
+ * `TestbedHarnessEnvironment.documentRootLoader(fixture)` — the ordinary
+ * `loader(fixture)` searches inside `fixture.nativeElement` and will never find
+ * it. Overlay panels belonging to template-declared components (`tw-select`,
+ * `tw-popover-overlay`, `tw-menu`) are the opposite case: those harnesses host
+ * on the in-fixture trigger and reach their panel internally, so the plain
+ * fixture loader is correct there.
+ *
+ * ## Waiting for it
+ *
+ * `Sheet` loads its render layer through a dynamic `import()`, so the container
+ * does **not** exist synchronously after `open()`. Await the ref's public
+ * {@link SheetRef.whenComponentReady} before asking for the harness — it
+ * resolves once the chunk has landed and the overlay is attached, for template
+ * sheets (with `null`) as well as component sheets.
+ *
+ * @example
+ * ```ts
+ * const ref = sheet.open(FiltersSheet, { side: 'left' });
+ * await ref.whenComponentReady();
+ * const rootLoader = TestbedHarnessEnvironment.documentRootLoader(fixture);
+ * const harness = await rootLoader.getHarness(SheetHarness);
+ * expect(await harness.getSide()).toBe('left');
+ * ```
+ */
+declare class SheetHarness extends ComponentHarness {
+    static hostSelector: string;
+    private readonly title;
+    private readonly content;
+    /** Any descendant of the container that currently holds DOM focus. */
+    private readonly focusedDescendant;
+    /**
+     * Overlay backdrops, which are siblings of the sheet's overlay pane rather
+     * than descendants of the container — hence the document-root lookup.
+     */
+    private readonly backdrops;
+    /** Predicate for `locatorFor` / `locatorForAll`. */
+    static with(options?: SheetHarnessFilters): HarnessPredicate<SheetHarness>;
+    /** The sheet's id. Matches the `id` on the `SheetRef` returned by `open()`. */
+    getId(): Promise<string | null>;
+    /** The sheet's ARIA role — `'dialog'`, or `'alertdialog'` when so configured. */
+    getRole(): Promise<string | null>;
+    /**
+     * The edge the sheet is anchored to, read from the container's `data-side`
+     * attribute. This is the one axis a sheet has that a dialog does not.
+     */
+    getSide(): Promise<SheetSide | null>;
+    /**
+     * Text of the projected `[twSheetTitle]` element, trimmed, or `null` when the
+     * sheet's content does not use the title directive.
+     */
+    getTitleText(): Promise<string | null>;
+    /**
+     * Text of the projected `[twSheetContent]` region, trimmed, or `null` when
+     * the sheet's content does not use the content directive.
+     */
+    getContentText(): Promise<string | null>;
+    /**
+     * Whether DOM focus currently sits on the sheet container or anywhere inside
+     * it — the observable consequence of the CDK focus trap. CDK moves focus
+     * asynchronously, so let the fixture settle after opening before asserting.
+     */
+    containsFocus(): Promise<boolean>;
+    /** Whether the sheet rendered a backdrop. */
+    hasBackdrop(): Promise<boolean>;
+    /**
+     * Clicks the backdrop — the pointer dismiss gesture. Does nothing observable
+     * when the sheet was opened with `disableClose: true` or
+     * `closeOnBackdropClick: false`, which is how a test asserts those flags.
+     *
+     * Throws when no backdrop is rendered. With several overlays stacked, the
+     * last backdrop in the overlay container is used, i.e. the topmost one.
+     */
+    clickBackdrop(): Promise<void>;
+    /**
+     * Sends Escape to the sheet — the keyboard dismiss gesture. Deliberately a
+     * no-op when the sheet was opened with `disableClose: true` or
+     * `closeOnEscape: false`.
+     */
+    pressEscape(): Promise<void>;
+}
+
+export { SheetHarness };
+export type { SheetHarnessFilters };

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

@@ -83,8 +83,24 @@ declare class SheetConfig<D = unknown, R = unknown> extends DialogConfig<D, R> {
     restoreFocus?: SheetRestoreFocus;
 }
 /** Injection token carrying the `data` value passed via {@link SheetConfig.data}. */
-declare const SHEET_DATA: InjectionToken<unknown>;
+declare const TW_SHEET_DATA: InjectionToken<unknown>;
 /** Injection token for application-wide default sheet options. Set via `provideSheet()`. */
+declare const TW_SHEET_DEFAULT_OPTIONS: InjectionToken<Partial<SheetConfig<unknown, unknown>>>;
+/**
+ * @deprecated Renamed to {@link TW_SHEET_DATA} for consistency with every other
+ * ngx-tw injection token — and with `TW_DIALOG_DATA`, its direct counterpart.
+ * 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 SHEET_DATA: InjectionToken<unknown>;
+/**
+ * @deprecated Renamed to {@link TW_SHEET_DEFAULT_OPTIONS} for consistency with
+ * every other ngx-tw injection token — and with `TW_DIALOG_DEFAULT_OPTIONS`,
+ * its direct counterpart. 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 SHEET_DEFAULT_OPTIONS: InjectionToken<Partial<SheetConfig<unknown, unknown>>>;
 
 /** Lifecycle states a sheet passes through. */
@@ -380,7 +396,7 @@ declare class SheetActionsDirective {
  * `[twSheetClose]` value to pass a result to `afterClosed()` subscribers.
  */
 declare class SheetCloseDirective {
-    /** Value passed to `afterClosed()` when the button is clicked. */
+    /** Value passed to `afterClosed()` when the button is clicked. Defaults to `undefined`. */
     readonly twSheetClose: i0.InputSignal<unknown>;
     /** Native button `type`. Defaults to `'button'` to avoid accidental form submission. */
     readonly type: i0.InputSignal<"button" | "submit" | "reset">;
@@ -390,5 +406,5 @@ declare class SheetCloseDirective {
     static ɵdir: i0.ɵɵDirectiveDeclaration<SheetCloseDirective, "[twSheetClose]", never, { "twSheetClose": { "alias": "twSheetClose"; "required": false; "isSignal": true; }; "type": { "alias": "type"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
 }
 
-export { SHEET_DATA, SHEET_DEFAULT_OPTIONS, Sheet, SheetActionsDirective, SheetCloseDirective, SheetConfig, SheetContentDirective, SheetDescriptionDirective, SheetHeaderDirective, SheetIconDirective, SheetRef, SheetSubtitleDirective, SheetTitleDirective, provideSheet };
+export { SHEET_DATA, SHEET_DEFAULT_OPTIONS, Sheet, SheetActionsDirective, SheetCloseDirective, SheetConfig, SheetContainer, SheetContentDirective, SheetDescriptionDirective, SheetHeaderDirective, SheetIconDirective, SheetRef, SheetSubtitleDirective, SheetTitleDirective, TW_SHEET_DATA, TW_SHEET_DEFAULT_OPTIONS, provideSheet };
 export type { SheetActionsAlign, SheetAnimationEvent, SheetAutoFocus, SheetRestoreFocus, SheetRole, SheetScrollStrategy, SheetSide, SheetSize, SheetState };

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

@@ -16,8 +16,14 @@ interface SliderMark {
 }
 /** Format function for the value displayed in the value bubble, min/max labels, and `aria-valuetext`. */
 type SliderValueFormatter = (value: number) => string;
-/** Identifies which thumb is the interaction target in range mode. */
-type ThumbId = 'single' | 'start' | 'end';
+/**
+ * Identifies which thumb is the interaction target. `'single'` in single-value
+ * mode; `'start'` (lower) and `'end'` (upper) in range mode. Named in the
+ * public signatures of {@link SliderComponent.onThumbPointerDown} and
+ * {@link SliderComponent.onThumbKeyDown}, so it is exported for consumers that
+ * script those handlers directly.
+ */
+type SliderThumbId = 'single' | 'start' | 'end';
 /**
  * Select a single value or a numeric range from a scale.
  *
@@ -29,10 +35,26 @@ type ThumbId = 'single' | 'start' | 'end';
  * ```
  */
 declare class SliderComponent implements ControlValueAccessor, OnInit {
-    /** Lower bound of the slider scale. Defaults to `0`. */
-    readonly min: _angular_core.InputSignal<number>;
-    /** Upper bound of the slider scale. Defaults to `100`. */
-    readonly max: _angular_core.InputSignal<number>;
+    /**
+     * Lower bound of the slider scale. Defaults to `0`.
+     *
+     * Accepts `undefined` so `[formField]` type-checks under `strictTemplates`:
+     * signal forms writes the `min` control binding from the field's own
+     * `min()` state, which is `number | undefined`. `undefined` resolves back to
+     * the documented default through {@link min}.
+     */
+    readonly minInput: _angular_core.InputSignal<number | undefined>;
+    /**
+     * Upper bound of the slider scale. Defaults to `100`.
+     *
+     * Accepts `undefined` for the same reason as {@link minInput}; `undefined`
+     * resolves back to the documented default through {@link max}.
+     */
+    readonly maxInput: _angular_core.InputSignal<number | undefined>;
+    /** @internal Resolved lower bound — the `min` input with its documented `0` default restored when the binding resolves to `undefined`. Every internal reader goes through this, never through the raw input. */
+    readonly min: Signal<number>;
+    /** @internal Resolved upper bound — the `max` input with its documented `100` default restored when the binding resolves to `undefined`. */
+    readonly max: Signal<number>;
     /** Step increment used for snapping, keyboard nav, and auto-generated marks. Pass `null` for continuous values. Defaults to `1`. */
     readonly step: _angular_core.InputSignal<number | null>;
     /** Semantic color for the filled portion and thumb border. Defaults to `'primary'`. */
@@ -43,8 +65,19 @@ declare class SliderComponent implements ControlValueAccessor, OnInit {
     readonly variant: _angular_core.InputSignal<SliderVariant>;
     /** When true, prevents interaction and applies muted styling. Defaults to `false`. */
     readonly disabled: _angular_core.InputSignal<boolean>;
-    /** When true, sets `aria-required="true"` on the thumb for assistive tech. Defaults to `false`. */
-    readonly required: _angular_core.InputSignal<boolean>;
+    /** When true, sets `aria-required="true"` on the thumb 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>;
     /** When true, the slider selects a `[start, end]` range and renders two thumbs. Defaults to `false`. */
     readonly range: _angular_core.InputSignal<boolean>;
     /** Tick marks: `true` auto-generates one mark per step, an array supplies custom marks, `false` renders no marks. Defaults to `false`. */
@@ -63,21 +96,47 @@ declare class SliderComponent implements ControlValueAccessor, OnInit {
     readonly valueFormatter: _angular_core.InputSignal<SliderValueFormatter | undefined>;
     /** Optional form name attribute. Purely informational — the component does not render a native input. */
     readonly name: _angular_core.InputSignal<string | undefined>;
-    /** Accessible name for the single-value thumb when no visible label is provided. */
+    /** Accessible name for the single-value thumb when no visible label is provided. Defaults to `undefined`. Alias: `aria-label`. */
     readonly ariaLabel: _angular_core.InputSignal<string | undefined>;
-    /** ID of an external element labelling the single-value thumb. */
+    /** ID of an external element labelling the single-value thumb. Defaults to `undefined`. Alias: `aria-labelledby`. */
     readonly ariaLabelledby: _angular_core.InputSignal<string | undefined>;
-    /** ID of an external element describing the slider. */
+    /** ID of an external element describing the slider. Defaults to `undefined`. Alias: `aria-describedby`. */
     readonly ariaDescribedby: _angular_core.InputSignal<string | undefined>;
     /** Accessible name for the start (lower) thumb in range mode. Defaults to `"Minimum"`. */
     readonly ariaLabelStart: _angular_core.InputSignal<string>;
     /** Accessible name for the end (upper) thumb in range mode. Defaults to `"Maximum"`. */
     readonly ariaLabelEnd: _angular_core.InputSignal<string>;
-    /** Two-way bound slider value. A `number` for single mode, or `[start, end]` for range mode. Updates on every interaction. */
+    /**
+     * Two-way bound slider value. A `number` for single mode, or `[start, end]`
+     * for range mode. Updates on every interaction. Defaults to `0`.
+     *
+     * The two-way binding mints a `valueChange` output, which fires on every
+     * value mutation the user causes — each drag move and each key step, plus the
+     * commit. Note the slider differs from `tw-checkbox` / `tw-switch` /
+     * `tw-radio-group`, where the minted output is the *any-change* channel:
+     * here, a programmatic write from a bound form (`FormControl.setValue`,
+     * `ngModel`) reaches the rendered value through the CVA path without passing
+     * through this model, so it does **not** emit `valueChange`. To observe
+     * programmatic writes, use the form control's own `valueChanges`.
+     *
+     * For the two user-gesture channels, prefer `(input)` for live feedback and
+     * `(change)` for commit — see their docs below.
+     */
     readonly value: _angular_core.ModelSignal<SliderValue>;
-    /** Fires continuously while the user drags or holds a key. Payload matches the current `value`. Template event name is `input` — the TS-side identifier is `valueInput` to avoid shadowing the imported `input` factory. */
+    /**
+     * Fires continuously while the user drags or holds a key — the *live* channel,
+     * for previewing a value that is not yet committed. Payload matches the
+     * current `value`. Template event name is `input` — the TS-side identifier is
+     * `valueInput` to avoid shadowing the imported `input` factory. Never fires
+     * for a programmatic write.
+     */
     readonly valueInput: _angular_core.OutputEmitterRef<SliderValue>;
-    /** Fires when the user commits a change (pointer release, key release, or blur after keyboard change). Payload matches the current `value`. */
+    /**
+     * Fires when the user commits a change (pointer release, key release, or blur
+     * after keyboard change) — the *commit* channel, for saving or querying on a
+     * settled value. Payload matches the current `value`. Never fires for a
+     * programmatic write; use `(input)` if you need every intermediate value.
+     */
     readonly change: _angular_core.OutputEmitterRef<SliderValue>;
     /** Per-instance override of the {@link ErrorStateMatcher}. When omitted, the component uses the `TW_ERROR_STATE_MATCHER` token's value. */
     readonly errorStateMatcher: _angular_core.InputSignal<ErrorStateMatcher | undefined>;
@@ -86,11 +145,6 @@ declare class SliderComponent implements ControlValueAccessor, OnInit {
     private readonly destroyRef;
     private readonly directionality;
     private readonly ngControl;
-    private readonly parentForm;
-    private readonly parentFormGroup;
-    private readonly defaultMatcher;
-    private readonly _ngControlRev;
-    private readonly _formSubmitRev;
     /** Whether the form control is in an error state per the configured `ErrorStateMatcher`. */
     readonly errorState: Signal<boolean>;
     private readonly region;
@@ -117,7 +171,7 @@ declare class SliderComponent implements ControlValueAccessor, OnInit {
     private readonly internalEnd;
     private readonly internalSingle;
     /** @internal Which thumb currently has an active pointer gesture (or null). Bound in the template to drive the pressed-thumb styling. */
-    readonly activeThumb: _angular_core.WritableSignal<ThumbId | null>;
+    readonly activeThumb: _angular_core.WritableSignal<SliderThumbId | null>;
     /** @internal Which thumb is focused (for bubble visibility). */
     private readonly focusedThumb;
     /** @internal Set of pointer IDs currently captured per-thumb for release tracking. */
@@ -205,7 +259,7 @@ declare class SliderComponent implements ControlValueAccessor, OnInit {
      */
     private readonly bubbleClassMap;
     /** @internal Bubble visibility depends on drag / focus / hover state. */
-    bubbleClassFor(thumb: ThumbId): string;
+    bubbleClassFor(thumb: SliderThumbId): string;
     /** @internal */
     readonly resolvedAriaDescribedby: Signal<string | null>;
     /** @internal */
@@ -223,12 +277,12 @@ declare class SliderComponent implements ControlValueAccessor, OnInit {
     /** Track click: move the nearest thumb to the clicked position and begin a drag. */
     onTrackPointerDown(event: PointerEvent): void;
     /** Thumb press: capture pointer and begin a drag gesture. */
-    onThumbPointerDown(event: PointerEvent, thumb: ThumbId): void;
+    onThumbPointerDown(event: PointerEvent, thumb: SliderThumbId): void;
     private beginDrag;
     private readonly onPointerMove;
     private readonly onPointerUp;
     /** Keyboard navigation: arrows for step, PageUp/Down for 10% jumps, Home/End for extremes. */
-    onThumbKeyDown(event: KeyboardEvent, thumb: ThumbId): void;
+    onThumbKeyDown(event: KeyboardEvent, thumb: SliderThumbId): void;
     /** @internal */
     onThumbBlur(): void;
     /** @internal Clamp to min/max and snap to step. Returns a finite number. */
@@ -251,8 +305,8 @@ declare class SliderComponent implements ControlValueAccessor, OnInit {
     setDisabledState(isDisabled: boolean): void;
     ngOnInit(): void;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<SliderComponent, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<SliderComponent, "tw-slider", never, { "min": { "alias": "min"; "required": false; "isSignal": true; }; "max": { "alias": "max"; "required": false; "isSignal": true; }; "step": { "alias": "step"; "required": false; "isSignal": true; }; "color": { "alias": "color"; "required": false; "isSignal": true; }; "size": { "alias": "size"; "required": false; "isSignal": true; }; "variant": { "alias": "variant"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "required": { "alias": "required"; "required": false; "isSignal": true; }; "range": { "alias": "range"; "required": false; "isSignal": true; }; "marks": { "alias": "marks"; "required": false; "isSignal": true; }; "showMarkLabels": { "alias": "showMarkLabels"; "required": false; "isSignal": true; }; "showMinMax": { "alias": "showMinMax"; "required": false; "isSignal": true; }; "showValue": { "alias": "showValue"; "required": false; "isSignal": true; }; "label": { "alias": "label"; "required": false; "isSignal": true; }; "description": { "alias": "description"; "required": false; "isSignal": true; }; "valueFormatter": { "alias": "valueFormatter"; "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; }; "ariaLabelStart": { "alias": "ariaLabelStart"; "required": false; "isSignal": true; }; "ariaLabelEnd": { "alias": "ariaLabelEnd"; "required": false; "isSignal": true; }; "value": { "alias": "value"; "required": false; "isSignal": true; }; "errorStateMatcher": { "alias": "errorStateMatcher"; "required": false; "isSignal": true; }; }, { "value": "valueChange"; "valueInput": "input"; "change": "change"; }, never, never, true, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<SliderComponent, "tw-slider", never, { "minInput": { "alias": "min"; "required": false; "isSignal": true; }; "maxInput": { "alias": "max"; "required": false; "isSignal": true; }; "step": { "alias": "step"; "required": false; "isSignal": true; }; "color": { "alias": "color"; "required": false; "isSignal": true; }; "size": { "alias": "size"; "required": false; "isSignal": true; }; "variant": { "alias": "variant"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "requiredInput": { "alias": "required"; "required": false; "isSignal": true; }; "range": { "alias": "range"; "required": false; "isSignal": true; }; "marks": { "alias": "marks"; "required": false; "isSignal": true; }; "showMarkLabels": { "alias": "showMarkLabels"; "required": false; "isSignal": true; }; "showMinMax": { "alias": "showMinMax"; "required": false; "isSignal": true; }; "showValue": { "alias": "showValue"; "required": false; "isSignal": true; }; "label": { "alias": "label"; "required": false; "isSignal": true; }; "description": { "alias": "description"; "required": false; "isSignal": true; }; "valueFormatter": { "alias": "valueFormatter"; "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; }; "ariaLabelStart": { "alias": "ariaLabelStart"; "required": false; "isSignal": true; }; "ariaLabelEnd": { "alias": "ariaLabelEnd"; "required": false; "isSignal": true; }; "value": { "alias": "value"; "required": false; "isSignal": true; }; "errorStateMatcher": { "alias": "errorStateMatcher"; "required": false; "isSignal": true; }; }, { "value": "valueChange"; "valueInput": "input"; "change": "change"; }, never, never, true, never>;
 }
 
 export { SliderComponent };
-export type { SliderMark, SliderValue, SliderValueFormatter, SliderVariant };
+export type { SliderMark, SliderThumbId, SliderValue, SliderValueFormatter, SliderVariant };