@cdevhub/ngx-tw 0.4.0 → 0.6.0

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

@@ -4,6 +4,17 @@ import * as _angular_core from '@angular/core';
 import { Signal, ElementRef } from '@angular/core';
 import { TwOrientation, TwSize, TwColor } from '@cdevhub/ngx-tw/core';
 
+/**
+ * Carousel public types.
+ *
+ * This file is the leaf of the carousel entry point's import graph: it holds
+ * only type declarations and imports nothing, so every other file in the
+ * directory can read from it without creating a cycle. Concretely,
+ * `carousel-labels.ts` needs `TwCarouselLabels` while `carousel.ts` needs
+ * `DEFAULT_CAROUSEL_LABELS` back from it — with both declared in `carousel.ts`
+ * that pair is a genuine import cycle. Mirrors the `calendar/calendar.types.ts`
+ * precedent.
+ */
 /** Visual style of the indicators row rendered by `<tw-carousel-indicators>`. */
 type TwCarouselIndicatorVariant = 'dots' | 'lines' | 'numbers';
 /** Where the indicators sit relative to the carousel viewport. */
@@ -21,25 +32,32 @@ interface TwCarouselSlideChangeEvent {
 }
 /** Reason emitted when autoplay transitions running → paused. */
 type TwCarouselAutoplayReason = 'hover' | 'focus' | 'interaction' | 'visibility' | 'manual';
-/** Localizable strings for the carousel. */
+/**
+ * Localizable strings for the carousel.
+ *
+ * Every member is optional. This interface only ever reaches consumers through
+ * `input<Partial<TwCarouselLabels>>`, and unset keys fall back to
+ * {@link DEFAULT_CAROUSEL_LABELS} — so a consumer holding an i18n bundle typed
+ * as `TwCarouselLabels` must not be forced to restate every key, and adding a
+ * label in a future minor must not break them on a non-major release.
+ */
 interface TwCarouselLabels {
     /** Accessible label for the Previous-slide directive host. Default: `'Previous slide'`. */
-    previous: string;
+    previous?: string;
     /** Accessible label for the Next-slide directive host. Default: `'Next slide'`. */
-    next: string;
+    next?: string;
     /** Accessible label for the autoplay pause control. Default: `'Pause autoplay'`. */
-    pauseAutoplay: string;
+    pauseAutoplay?: string;
     /** Accessible label for the autoplay resume control. Default: `'Resume autoplay'`. */
-    resumeAutoplay: string;
+    resumeAutoplay?: string;
     /** Template for indicator-button accessible names. Variable: `{page}` (1-based). Default: `'Go to slide {page}'`. */
-    indicator: string;
+    indicator?: string;
     /** Template for per-slide accessible names with a custom label. Variables: `{index}` (1-based), `{total}`, `{label}`. Default: `'{index} of {total}: {label}'`. */
-    slideOfWithLabel: string;
+    slideOfWithLabel?: string;
     /** Template for per-slide accessible names without a custom label. Variables: `{index}` (1-based), `{total}`. Default: `'{index} of {total}'`. */
-    slideOf: string;
+    slideOf?: string;
 }
-/** Default English labels used when consumers do not override via the `labels` input. */
-declare const DEFAULT_CAROUSEL_LABELS: Readonly<TwCarouselLabels>;
+
 /**
  * A single slide inside a `<tw-carousel>`. Projects arbitrary content via its
  * default slot. Reports its visibility back to the carousel container via a
@@ -105,9 +123,9 @@ declare class CarouselComponent {
     readonly snapAlign: _angular_core.InputSignal<"start" | "center" | "end">;
     /** Two-way bound 0-based index of the first visible slide in the current page. Setting from the parent scrolls the viewport smoothly to align that slide; reading reflects user-driven scroll position after `scrollend`. Defaults to `0`. */
     readonly activeIndex: _angular_core.ModelSignal<number>;
-    /** Accessible name for the carousel region. If both this and `ariaLabelledBy` are `null`, a one-time dev-mode `console.warn` is logged (production builds never log). Defaults to `null`. */
+    /** Accessible name for the carousel region. Mirrored to `aria-label`. If both this and `aria-labelledby` are `null`, a one-time dev-mode `console.warn` is logged (production builds never log). Defaults to `null`. */
     readonly ariaLabel: _angular_core.InputSignal<string | null>;
-    /** ID of an element labeling the carousel. Either `ariaLabel` or `ariaLabelledBy` SHOULD be provided. Defaults to `null`. */
+    /** ID of an element labeling the carousel. Mirrored to `aria-labelledby`. Either `aria-label` or `aria-labelledby` SHOULD be provided. Defaults to `null`. */
     readonly ariaLabelledBy: _angular_core.InputSignal<string | null>;
     /** Localizable strings for prev/next/pause/resume/indicator/slide-of templates. Unset keys fall back to the English defaults in `DEFAULT_CAROUSEL_LABELS`. Defaults to `{}`. */
     readonly labels: _angular_core.InputSignal<Partial<TwCarouselLabels>>;
@@ -122,8 +140,19 @@ declare class CarouselComponent {
     readonly _viewportRef: Signal<ElementRef<HTMLDivElement>>;
     /** @internal Projected slides in DOM order. */
     readonly slides: Signal<readonly CarouselSlideComponent[]>;
-    /** @internal Resolved label record with English defaults filled in. */
-    readonly resolvedLabels: Signal<TwCarouselLabels>;
+    /**
+     * @internal Resolved label record with English defaults filled in.
+     *
+     * Explicitly-undefined keys are dropped before merging. Root `tsconfig.json`
+     * does not set `exactOptionalPropertyTypes`, so `[labels]="{ indicator:
+     * t('carousel.indicator') }"` type-checks even when `t()` returns
+     * `string | undefined` — 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 render down. Same filter `table.ts` and
+     * `timeline.ts` already use; `Required<>` then guarantees a string per key.
+     */
+    readonly resolvedLabels: Signal<Required<TwCarouselLabels>>;
     /** @internal Effective `slidesPerView` clamped to `[0.5, slideCount]`. */
     readonly _effectiveSlidesPerView: Signal<number>;
     /** @internal Effective `slidesToScroll` floored to a positive integer. Read by child indicators directive (`CarouselIndicatorsComponent._onClick`) as a signal. */
@@ -185,6 +214,14 @@ declare class CarouselComponent {
             gap?: "xs" | "sm" | "md" | "lg" | "xl" | undefined;
             snapAlign?: "start" | "center" | "end" | undefined;
         } & tailwind_variants.ClassProp<tailwind_merge.ClassNameValue>) | undefined) => string;
+        indicatorTarget: (slotProps?: ({
+            variant?: "dots" | "lines" | "numbers" | undefined;
+            size?: "xs" | "sm" | "md" | "lg" | "xl" | undefined;
+            orientation?: "horizontal" | "vertical" | undefined;
+            position?: "overlay" | "below" | undefined;
+            gap?: "xs" | "sm" | "md" | "lg" | "xl" | undefined;
+            snapAlign?: "start" | "center" | "end" | undefined;
+        } & tailwind_variants.ClassProp<tailwind_merge.ClassNameValue>) | undefined) => string;
         indicator: (slotProps?: ({
             variant?: "dots" | "lines" | "numbers" | undefined;
             size?: "xs" | "sm" | "md" | "lg" | "xl" | undefined;
@@ -234,6 +271,14 @@ declare class CarouselComponent {
             gap?: "xs" | "sm" | "md" | "lg" | "xl" | undefined;
             snapAlign?: "start" | "center" | "end" | undefined;
         } & tailwind_variants.ClassProp<tailwind_merge.ClassNameValue>) | undefined) => string;
+        indicatorTarget: (slotProps?: ({
+            variant?: "dots" | "lines" | "numbers" | undefined;
+            size?: "xs" | "sm" | "md" | "lg" | "xl" | undefined;
+            orientation?: "horizontal" | "vertical" | undefined;
+            position?: "overlay" | "below" | undefined;
+            gap?: "xs" | "sm" | "md" | "lg" | "xl" | undefined;
+            snapAlign?: "start" | "center" | "end" | undefined;
+        } & tailwind_variants.ClassProp<tailwind_merge.ClassNameValue>) | undefined) => string;
         indicator: (slotProps?: ({
             variant?: "dots" | "lines" | "numbers" | undefined;
             size?: "xs" | "sm" | "md" | "lg" | "xl" | undefined;
@@ -276,6 +321,8 @@ declare class CarouselComponent {
     private _onScrollEndBound;
     private _onScrollDebouncedBound;
     private _scrollDebounceTimer;
+    /** Handle for the post-interaction autoplay-pause expiry (see `_onPointerUp`). */
+    private _postInteractionPauseTimer;
     private _onVisibilityChangeBound;
     private _setupViewport;
     private _teardownViewport;
@@ -321,8 +368,9 @@ declare class CarouselComponent {
     _onKeydown(event: KeyboardEvent): void;
     _togglePauseControl(): void;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<CarouselComponent, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<CarouselComponent, "tw-carousel", never, { "orientation": { "alias": "orientation"; "required": false; "isSignal": true; }; "slidesPerView": { "alias": "slidesPerView"; "required": false; "isSignal": true; }; "slidesToScroll": { "alias": "slidesToScroll"; "required": false; "isSignal": true; }; "gap": { "alias": "gap"; "required": false; "isSignal": true; }; "loop": { "alias": "loop"; "required": false; "isSignal": true; }; "autoplay": { "alias": "autoplay"; "required": false; "isSignal": true; }; "autoplayInterval": { "alias": "autoplayInterval"; "required": false; "isSignal": true; }; "pauseOnHover": { "alias": "pauseOnHover"; "required": false; "isSignal": true; }; "pauseOnFocusIn": { "alias": "pauseOnFocusIn"; "required": false; "isSignal": true; }; "draggable": { "alias": "draggable"; "required": false; "isSignal": true; }; "keyboard": { "alias": "keyboard"; "required": false; "isSignal": true; }; "snapAlign": { "alias": "snapAlign"; "required": false; "isSignal": true; }; "activeIndex": { "alias": "activeIndex"; "required": false; "isSignal": true; }; "ariaLabel": { "alias": "ariaLabel"; "required": false; "isSignal": true; }; "ariaLabelledBy": { "alias": "ariaLabelledBy"; "required": false; "isSignal": true; }; "labels": { "alias": "labels"; "required": false; "isSignal": true; }; }, { "activeIndex": "activeIndexChange"; "slideChange": "slideChange"; "autoplayPaused": "autoplayPaused"; "autoplayResumed": "autoplayResumed"; }, ["slides"], ["tw-carousel-slide", "[twCarouselPrev], [twCarouselNext], tw-carousel-indicators", "*"], true, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<CarouselComponent, "tw-carousel", never, { "orientation": { "alias": "orientation"; "required": false; "isSignal": true; }; "slidesPerView": { "alias": "slidesPerView"; "required": false; "isSignal": true; }; "slidesToScroll": { "alias": "slidesToScroll"; "required": false; "isSignal": true; }; "gap": { "alias": "gap"; "required": false; "isSignal": true; }; "loop": { "alias": "loop"; "required": false; "isSignal": true; }; "autoplay": { "alias": "autoplay"; "required": false; "isSignal": true; }; "autoplayInterval": { "alias": "autoplayInterval"; "required": false; "isSignal": true; }; "pauseOnHover": { "alias": "pauseOnHover"; "required": false; "isSignal": true; }; "pauseOnFocusIn": { "alias": "pauseOnFocusIn"; "required": false; "isSignal": true; }; "draggable": { "alias": "draggable"; "required": false; "isSignal": true; }; "keyboard": { "alias": "keyboard"; "required": false; "isSignal": true; }; "snapAlign": { "alias": "snapAlign"; "required": false; "isSignal": true; }; "activeIndex": { "alias": "activeIndex"; "required": false; "isSignal": true; }; "ariaLabel": { "alias": "aria-label"; "required": false; "isSignal": true; }; "ariaLabelledBy": { "alias": "aria-labelledby"; "required": false; "isSignal": true; }; "labels": { "alias": "labels"; "required": false; "isSignal": true; }; }, { "activeIndex": "activeIndexChange"; "slideChange": "slideChange"; "autoplayPaused": "autoplayPaused"; "autoplayResumed": "autoplayResumed"; }, ["slides"], ["tw-carousel-slide", "[twCarouselPrev], [twCarouselNext], tw-carousel-indicators", "*"], true, never>;
 }
+
 /**
  * Renders one button per **page** (not per slide) inside a `<tw-carousel>`.
  * The active button is marked with `aria-current="true"` and a distinguishing
@@ -340,7 +388,7 @@ declare class CarouselIndicatorsComponent {
     /** @internal Direct parent carousel. */
     readonly carousel: CarouselComponent;
     private readonly _variantResult;
-    readonly rootClasses: Signal<string>;
+    readonly rootClasses: _angular_core.Signal<string>;
     /**
      * @internal Sequence of page indices to render. Returns `[]` when the
      * parent carousel's `slidesPerView` is not `1` — a single dot can never
@@ -350,14 +398,18 @@ declare class CarouselIndicatorsComponent {
      * `slidesPerView` back to `1` — the buttons reappear at that point without
      * a remount.
      */
-    readonly _pages: Signal<number[]>;
+    readonly _pages: _angular_core.Signal<number[]>;
     constructor();
-    _buttonClasses(page: number): string;
+    /** @internal Classes for the indicator `<button>` — the 24x24-floored hit target (SC 2.5.8). Identical for every page, so it is a computed rather than a per-page call. */
+    readonly _buttonClasses: _angular_core.Signal<string>;
+    /** @internal Classes for the painted mark inside the target: geometry from the `variant` × `size` compound variants, fill from the active/inactive lookup. */
+    _indicatorClasses(page: number): string;
     _buttonLabel(page: number): string;
     _onClick(page: number): void;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<CarouselIndicatorsComponent, never>;
     static ɵcmp: _angular_core.ɵɵComponentDeclaration<CarouselIndicatorsComponent, "tw-carousel-indicators", never, { "variant": { "alias": "variant"; "required": false; "isSignal": true; }; "color": { "alias": "color"; "required": false; "isSignal": true; }; "size": { "alias": "size"; "required": false; "isSignal": true; }; "position": { "alias": "position"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
 }
+
 /**
  * Apply to any focusable element (typically `<button>`) inside a `<tw-carousel>`
  * to navigate to the previous page. Auto-disables at the first slide when the
@@ -372,7 +424,7 @@ declare class CarouselPrevDirective {
     private readonly _hasLabelledBy;
     private readonly _isButton;
     /** @internal True when prev is unavailable (at start and !loop). */
-    readonly _isDisabled: Signal<boolean>;
+    readonly _isDisabled: _angular_core.Signal<boolean>;
     _ariaLabel(): string | null;
     _isButtonDisabled(): string | null;
     _isTabindex(): string | null;
@@ -393,7 +445,7 @@ declare class CarouselNextDirective {
     private readonly _consumerLabel;
     private readonly _hasLabelledBy;
     private readonly _isButton;
-    readonly _isDisabled: Signal<boolean>;
+    readonly _isDisabled: _angular_core.Signal<boolean>;
     _ariaLabel(): string | null;
     _isButtonDisabled(): string | null;
     _isTabindex(): string | null;
@@ -402,5 +454,22 @@ declare class CarouselNextDirective {
     static ɵdir: _angular_core.ɵɵDirectiveDeclaration<CarouselNextDirective, "[twCarouselNext]", never, {}, {}, never, never, true, never>;
 }
 
+/**
+ * Carousel label resolution — the English defaults and the `{placeholder}`
+ * interpolation both `CarouselSlideComponent` (per-slide `aria-label`) and
+ * `CarouselIndicatorsComponent` (per-page `aria-label`) read.
+ *
+ * `formatLabel` is exported so those two files can share one implementation;
+ * it is deliberately **not** re-exported from `index.ts` and carries no
+ * compatibility promise.
+ */
+
+/**
+ * Default English labels used when consumers do not override via the `labels`
+ * input. Typed `Required<TwCarouselLabels>` so readers keep a non-optional
+ * `string` for every key even though the interface itself is all-optional.
+ */
+declare const DEFAULT_CAROUSEL_LABELS: Readonly<Required<TwCarouselLabels>>;
+
 export { CarouselComponent, CarouselIndicatorsComponent, CarouselNextDirective, CarouselPrevDirective, CarouselSlideComponent, DEFAULT_CAROUSEL_LABELS };
 export type { TwCarouselAutoplayReason, TwCarouselIndicatorPosition, TwCarouselIndicatorVariant, TwCarouselLabels, TwCarouselSlideChangeEvent, TwCarouselSlideChangeTrigger };

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

@@ -27,36 +27,58 @@ declare class CheckboxComponent extends FormFieldControl<boolean> implements Con
     readonly labelPosition: _angular_core.InputSignal<CheckboxLabelPosition>;
     /** Optional name attribute, applied to the hidden native `<input type="checkbox">` so native form submission includes the control. */
     readonly name: _angular_core.InputSignal<string | undefined>;
-    /** Id on the host element. Auto-generated as `tw-checkbox-N` when not provided. Used by the form-field's `<label for>` attribute. */
+    /** Id on the host element. Auto-generated as `tw-checkbox-N` when not provided. Anchors the derived label/description ids; the accessible name inside a `<tw-form-field>` comes from `aria-labelledby`, not from the field's `<label for>` (the host is a custom element, which `for` cannot target). */
     readonly idInput: _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 checkbox. Mirrored to `aria-labelledby`. */
+    /** ID of an external element that labels the checkbox. Mirrored to `aria-labelledby`. Defaults to `undefined`. */
     readonly ariaLabelledby: _angular_core.InputSignal<string | undefined>;
-    /** ID of an external element that describes the checkbox. Mirrored to `aria-describedby`. Form-field merges its hint/error ids alongside. */
+    /** ID of an external element that describes the checkbox. Mirrored to `aria-describedby`. Form-field merges its hint/error ids alongside. Defaults to `undefined`. */
     readonly ariaDescribedby: _angular_core.InputSignal<string | undefined>;
     /** Per-instance override of the {@link ErrorStateMatcher}. When omitted, the directive uses the `TW_ERROR_STATE_MATCHER` token's value. */
     readonly errorStateMatcher: _angular_core.InputSignal<ErrorStateMatcher | undefined>;
-    /** Two-way bound checked state. Updates when the user toggles via click or Space. */
+    /**
+     * Two-way bound checked state. Updates when the user toggles via click or
+     * Space, **and** when a bound form writes into the control
+     * (`FormControl.setValue`, `ngModel`, `writeValue`). Defaults to `false`.
+     *
+     * The two-way binding mints a `checkedChange` output. That output is the
+     * *any-change* channel: it fires on programmatic writes as well as user
+     * gestures. `(change)` is the *user-gesture-only* channel. Bind
+     * `(checkedChange)` to mirror state; bind `(change)` for analytics or a
+     * confirmation prompt, where a programmatic write must not count as a click.
+     * Writing back into the same form from a `(checkedChange)` handler will echo.
+     */
     readonly checked: _angular_core.ModelSignal<boolean>;
-    /** Two-way bound indeterminate state. When true, the box shows a dash and the host exposes `aria-checked="mixed"`. Any user toggle clears indeterminate and sets `checked` to `true`. */
+    /**
+     * Two-way bound indeterminate state. When true, the box shows a dash and the
+     * host exposes `aria-checked="mixed"`. Any user toggle clears indeterminate
+     * and sets `checked` to `true`. Defaults to `false`.
+     *
+     * Its minted `indeterminateChange` output follows the same rule as
+     * `checkedChange`: it also fires when `writeValue` clears the state, so it is
+     * an any-change channel, not a gesture channel.
+     */
     readonly indeterminate: _angular_core.ModelSignal<boolean>;
-    /** Fires after the checked state changes from a user interaction. Does not fire when the value is updated programmatically via `writeValue`. */
+    /**
+     * Fires after the checked state changes from a user interaction (click or
+     * Space). Does **not** fire when the value is updated programmatically via
+     * `writeValue` / `FormControl.setValue` / `ngModel` — for those, bind the
+     * two-way binding's `(checkedChange)` instead, which fires on any change.
+     */
     readonly change: _angular_core.OutputEmitterRef<boolean>;
     private readonly focusMonitor;
     private readonly elementRef;
     private readonly destroyRef;
     private readonly ngControl;
-    private readonly parentForm;
-    private readonly parentFormGroup;
-    private readonly defaultMatcher;
     private onChange;
     private onTouched;
     private readonly cvaDisabled;
     private readonly _focused;
-    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 uid;
     /** @internal Fallback id used when the consumer does not set `[id]`. */
     readonly hostId: string;
@@ -99,10 +121,14 @@ declare class CheckboxComponent extends FormFieldControl<boolean> implements Con
     readonly required: Signal<boolean>;
     /** @internal */
     readonly errorState: 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 */
     readonly controlType = "checkbox";
     /** @internal */
     readonly userAriaDescribedBy: Signal<string | undefined>;
+    /** @internal Consumer-supplied `aria-labelledby`, surfaced so the wrapping form-field merges it into the ids it pushes back rather than replacing it. */
+    readonly userAriaLabelledby: Signal<string | undefined>;
     private readonly variantResult;
     readonly rootClasses: Signal<string>;
     readonly boxWrapClasses: Signal<string>;
@@ -124,6 +150,8 @@ declare class CheckboxComponent extends FormFieldControl<boolean> implements Con
     setDisabledState(isDisabled: boolean): void;
     /** @internal Called by the form-field once it has computed the merged describedby ids. */
     setDescribedByIds(ids: string[]): void;
+    /** @internal Receives the merged `aria-labelledby` ids from the wrapping form-field. Required because the host is a custom element rather than a labelable control, so the field's `<label for>` never reaches it. */
+    setLabelledByIds(ids: string[]): void;
     /** @internal Called when the form-field container is clicked — focus the host without toggling. */
     onContainerClick(event: MouseEvent): void;
     ngOnInit(): void;

package/types/cdevhub-ngx-tw-code-block.d.ts

@@ -1,7 +1,14 @@
 import * as _angular_core from '@angular/core';
 
 /** Visual style of the code block container. */
-type CodeBlockVariant = 'filled' | 'outlined';
+type CodeBlockVariant = 'solid' | 'outline' | CodeBlockVariantLegacy;
+/**
+ * Legacy `variant` spellings, kept so existing templates keep compiling.
+ * @deprecated `'filled'` is an alias for `'solid'` and `'outlined'` an alias
+ * for `'outline'`; both render identically to their replacements and will be
+ * removed in the next major. Prefer `'solid'` / `'outline'`.
+ */
+type CodeBlockVariantLegacy = 'filled' | 'outlined';
 /**
  * Localizable strings used by the code block. Provide a partial override —
  * any missing fields fall back to English defaults.
@@ -51,7 +58,7 @@ declare class CodeBlockComponent {
     readonly code: _angular_core.InputSignal<string>;
     /** Optional language label displayed in the header (e.g. `'TypeScript'`, `'HTML'`). */
     readonly language: _angular_core.InputSignal<string | undefined>;
-    /** Visual style of the container. Defaults to `'filled'`. */
+    /** Visual style of the container. Defaults to `'solid'`. `'filled'` and `'outlined'` are deprecated aliases for `'solid'` and `'outline'` and render identically. */
     readonly variant: _angular_core.InputSignal<CodeBlockVariant>;
     /** When true, wraps long lines instead of horizontal scrolling. Defaults to `false`. */
     readonly wrap: _angular_core.InputSignalWithTransform<boolean, unknown>;
@@ -76,6 +83,8 @@ declare class CodeBlockComponent {
         copied: string;
         announcement: string;
     }>;
+    /** @internal Canonical variant with legacy spellings folded in. */
+    private readonly resolvedVariant;
     private readonly variantResult;
     protected readonly rootClasses: _angular_core.Signal<string>;
     protected readonly headerClasses: _angular_core.Signal<string>;

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

@@ -4,16 +4,34 @@ import { FocusableOption } from '@angular/cdk/a11y';
 import { TwColor, TwSize } from '@cdevhub/ngx-tw/core';
 
 /** Visual style of the collapsible container. */
-type CollapsibleVariant = 'default' | 'bordered' | 'ghost' | 'filled';
+type CollapsibleVariant = 'default' | 'outline' | 'ghost' | 'solid' | CollapsibleVariantLegacy;
+/**
+ * Legacy `variant` spellings, kept so existing templates keep compiling.
+ * @deprecated `'bordered'` aliases `'outline'` and `'filled'` aliases
+ * `'solid'`. Both render identically to their replacements and will be
+ * removed in the next major.
+ */
+type CollapsibleVariantLegacy = 'bordered' | 'filled';
+/** Canonical `variant` spellings — the set `tv()` actually keys on. */
+type CollapsibleVariantCanonical = Exclude<CollapsibleVariant, CollapsibleVariantLegacy>;
 /** Decorative axes bundled into a single collapsible input. */
 interface CollapsibleDisplay {
     /** Visual style of the panel container. Defaults to `'default'`. */
     variant?: CollapsibleVariant;
-    /** Semantic color; applies to the `bordered` and `filled` variants. Defaults to `'neutral'`. */
+    /** Semantic color; applies to the `outline` and `solid` variants. Defaults to `'neutral'`. */
     color?: TwColor;
     /** Padding scale for the trigger and content sections. Defaults to `'md'`. */
     size?: TwSize;
 }
+/**
+ * `CollapsibleDisplay` after defaults are filled in and legacy `variant`
+ * spellings are normalised. Module-private on purpose: narrowing `variant`
+ * to the canonical set is what makes the compiler prove the normalisation
+ * happened before `tv()` is called, and it is not consumer API.
+ */
+type ResolvedCollapsibleDisplay = Required<Omit<CollapsibleDisplay, 'variant'>> & {
+    variant: CollapsibleVariantCanonical;
+};
 declare class CollapsibleIconDirective {
     private readonly collapsible;
     /** @internal */
@@ -34,8 +52,11 @@ declare class CollapsibleTriggerDirective implements FocusableOption {
     readonly classes: _angular_core.Signal<string>;
     /** @internal */
     readonly iconClasses: _angular_core.Signal<string>;
+    /** @internal Toggles the parent collapsible when the trigger is clicked. */
     onClick(): void;
+    /** @internal Toggles on Enter/Space and delegates arrow-key navigation to the enclosing group. */
     onKeydown(event: KeyboardEvent): void;
+    /** Moves DOM focus to the trigger element. Called by `FocusKeyManager` during arrow-key navigation. */
     focus(): void;
     /** @internal FocusableOption: lets FocusKeyManager skip disabled triggers. */
     get disabled(): boolean;
@@ -45,7 +66,7 @@ declare class CollapsibleTriggerDirective implements FocusableOption {
     static ɵcmp: _angular_core.ɵɵComponentDeclaration<CollapsibleTriggerDirective, "[twCollapsibleTrigger]", never, {}, {}, never, ["*"], true, never>;
 }
 declare class CollapsibleComponent {
-    /** Unique identifier for this panel. Required when used inside a group. */
+    /** Unique identifier for this panel. Required when used inside a group. Defaults to an empty string. */
     readonly value: _angular_core.InputSignal<string>;
     /** Bundles decorative axes: `variant`, `color`, `size`. Accepts a partial; unset keys fall back to the defaults (`{ variant: 'default', color: 'neutral', size: 'md' }`). */
     readonly display: _angular_core.InputSignal<CollapsibleDisplay>;
@@ -73,8 +94,14 @@ declare class CollapsibleComponent {
      * lives next to the source — `activated()` reads cleanly as "derived from open".
      */
     readonly activated: _angular_core.WritableSignal<boolean>;
-    /** @internal Resolved decorative configuration. */
-    readonly resolvedDisplay: _angular_core.Signal<Required<CollapsibleDisplay>>;
+    /**
+     * @internal Resolved decorative configuration: defaults filled in, then
+     * legacy `variant` spellings folded onto their canonical replacements. The
+     * narrowed return type is the guard — `tv()` silently returns *base classes
+     * only* for a variant value it does not know, so an un-normalised legacy
+     * string would render an unstyled panel with no error anywhere.
+     */
+    readonly resolvedDisplay: _angular_core.Signal<ResolvedCollapsibleDisplay>;
     private readonly variantResult;
     readonly rootClasses: _angular_core.Signal<string>;
     readonly triggerClasses: _angular_core.Signal<string>;

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

@@ -0,0 +1,157 @@
+import { BaseHarnessFilters, ComponentHarness, HarnessPredicate } from '@angular/cdk/testing';
+
+/** Filters accepted by `ComboboxOptionHarness.with`. */
+interface ComboboxOptionHarnessFilters extends BaseHarnessFilters {
+    /** Match by the option's visible text. */
+    text?: string | RegExp;
+    /** Match selected / unselected options. */
+    selected?: boolean;
+    /** Match disabled / enabled options. */
+    disabled?: boolean;
+}
+/**
+ * Harness for a single option inside an open `tw-combobox` panel.
+ *
+ * Options render into the CDK overlay, not inside `tw-combobox`, so they are
+ * reached through {@link ComboboxHarness} rather than located directly against
+ * a fixture.
+ *
+ * `tw-combobox` is an `aria-activedescendant` listbox: DOM focus never leaves
+ * the input, so an option is never the active element. Keyboard highlight is
+ * expressed on the input's `aria-activedescendant`, not on the option, and is
+ * therefore not exposed here.
+ */
+declare class ComboboxOptionHarness extends ComponentHarness {
+    static hostSelector: string;
+    /** Predicate for `locatorFor` / `locatorForAll`. */
+    static with(options?: ComboboxOptionHarnessFilters): HarnessPredicate<ComboboxOptionHarness>;
+    /**
+     * The option's rendered text, trimmed. An option carrying a `description`
+     * renders label and description as sibling block spans, so this returns both
+     * concatenated with no separator.
+     */
+    getText(): Promise<string>;
+    /** Whether the option reports `aria-selected="true"`. */
+    isSelected(): Promise<boolean>;
+    /** Whether the option reports `aria-disabled="true"`. */
+    isDisabled(): Promise<boolean>;
+    /** Clicks the option. A disabled option ignores the click, as in the browser. */
+    click(): Promise<void>;
+}
+
+/** Filters accepted by `ComboboxHarness.with`. */
+interface ComboboxHarnessFilters extends BaseHarnessFilters {
+    /** Match by the input's accessible name. */
+    label?: string | RegExp;
+    /** Match by the text currently typed into (or displayed in) the input. */
+    inputValue?: string | RegExp;
+    /** Match disabled / enabled comboboxes. */
+    disabled?: boolean;
+}
+/**
+ * Harness for `tw-combobox`.
+ *
+ * The options panel renders into the CDK overlay container, outside the
+ * `tw-combobox` host, so this harness resolves it through
+ * `documentRootLocatorFactory()`. A consumer can therefore load this harness
+ * from the ordinary fixture loader and still reach the options — no
+ * `documentRootLoader` ceremony required.
+ *
+ * The panel is *disposed* on close rather than merely detached, so option
+ * harnesses must be re-read after each `open()`. Do not cache them across a
+ * close.
+ */
+declare class ComboboxHarness extends ComponentHarness {
+    static hostSelector: string;
+    private readonly input;
+    /**
+     * The inline clear (×) control. Its `aria-label` is a template literal in
+     * `combobox.ts` — not a consumer input — so matching on it is stable.
+     */
+    private readonly clearButton;
+    /** Resolves the overlay panel, which lives outside this harness's host. */
+    private readonly panel;
+    /** Predicate for `locatorFor` / `locatorForAll`. */
+    static with(options?: ComboboxHarnessFilters): HarnessPredicate<ComboboxHarness>;
+    /** The input's accessible name, from `aria-label` when one is set. */
+    getLabel(): Promise<string | null>;
+    /**
+     * The text currently in the input — the typed query while the user is
+     * filtering, the committed option's label afterwards. Empty string when the
+     * combobox holds nothing (the placeholder is not part of the value).
+     */
+    getInputValue(): Promise<string>;
+    /** The input's `placeholder`, or `null` when none is set. */
+    getPlaceholder(): Promise<string | null>;
+    /**
+     * Replaces the input text and lets the component filter against it — the
+     * harness equivalent of selecting all and typing a query.
+     *
+     * Does NOT commit a value: `tw-combobox` commits on option pick, Enter, blur
+     * or Tab. Follow with `selectOption(...)` to pick from the filtered list.
+     */
+    setInputValue(value: string): Promise<void>;
+    /** Whether the panel is open, read from the input's `aria-expanded`. */
+    isOpen(): Promise<boolean>;
+    /** Whether the input reports `aria-disabled="true"`. */
+    isDisabled(): Promise<boolean>;
+    /** Whether the input reports `aria-invalid="true"`. */
+    isInvalid(): Promise<boolean>;
+    /**
+     * Whether the input reports `aria-required="true"`. Reflects the `required`
+     * input *and* a `Validators.required` on a bound control.
+     */
+    isRequired(): Promise<boolean>;
+    /**
+     * Opens the panel with `Alt+ArrowDown`. No-op when already open.
+     *
+     * Deliberately not a click: `openOnFocus` defaults to `true` but can be
+     * turned off, whereas `Alt+ArrowDown` is the APG force-open gesture and works
+     * either way. A disabled combobox ignores it, as it does in the browser.
+     */
+    open(): Promise<void>;
+    /**
+     * Closes the panel with `Alt+ArrowUp`. No-op when already closed.
+     *
+     * Deliberately not Escape: Escape *also* reverts the input text to the last
+     * committed label, which would make `close()` silently destroy a typed query.
+     *
+     * The overlay runs a leave animation before it detaches, so `isOpen()` flips
+     * to `false` immediately while the panel element lingers for a few more
+     * frames. Two consequences worth knowing:
+     *
+     * - Do not assert `getOptions()` is empty on the tick after a close; the
+     *   old panel is still mounted.
+     * - An `open()` inside that window does **not** attach a fresh panel — the
+     *   component sees an overlay ref it has not disposed yet and silently
+     *   keeps the outgoing one. Let the animation finish before reopening.
+     */
+    close(): Promise<void>;
+    /**
+     * Every option in the open panel, in render order and already filtered by
+     * whatever query the input holds. Returns an empty array when the panel has
+     * never been opened, because the overlay is disposed rather than hidden.
+     */
+    getOptions(filters?: ComboboxOptionHarnessFilters): Promise<ComboboxOptionHarness[]>;
+    /**
+     * The text of every option currently rendered in the open panel. Opens the
+     * panel if needed — this is how a consumer reads the result of a filter
+     * query.
+     */
+    getOptionTexts(): Promise<string[]>;
+    /**
+     * Opens the panel if needed and clicks the first option whose text matches.
+     * Throws when nothing matches, rather than failing silently.
+     */
+    selectOption(text: string | RegExp): Promise<void>;
+    /**
+     * Whether the inline clear control is rendered. It appears only while
+     * `clearable` is on, the combobox is enabled, and the input is non-empty.
+     */
+    hasClearButton(): Promise<boolean>;
+    /** Clicks the clear control. Throws when none is rendered. */
+    clear(): Promise<void>;
+}
+
+export { ComboboxHarness, ComboboxOptionHarness };
+export type { ComboboxHarnessFilters, ComboboxOptionHarnessFilters };