@egose/shadcn-theme-ng-tw 0.6.0 → 0.6.1

package/README.md

@@ -167,9 +167,46 @@ export class DemoComponent {
 }
 ```
 
+## Searchable multiselect
+
+`EgSearchableMultiselect` provides local, case-insensitive label search, named removable chips, and a `string[]` CVA. Import it directly from its public subpath:
+
+```ts
+import { Component, signal } from '@angular/core';
+import { EgSearchableMultiselect } from '@egose/shadcn-theme-ng/searchable-multiselect';
+
+@Component({
+  selector: 'app-assignees',
+  imports: [EgSearchableMultiselect],
+  template: `
+    <eg-searchable-multiselect
+      [options]="people"
+      [(value)]="selected"
+      ariaLabel="Assignees"
+      searchLabel="Find people"
+      searchPlaceholder="Type a name…"
+      emptyMessage="No people match"
+    />
+  `,
+})
+export class AssigneesComponent {
+  readonly people = [
+    { value: 'ada', label: 'Ada Lovelace' },
+    { value: 'grace', label: 'Grace Hopper' },
+  ];
+  readonly selected = signal<string[]>(['ada']);
+}
+```
+
+Use `@egose/shadcn-theme-ng-tw/searchable-multiselect` for the prefixed variant. Pass the complete options list: the trimmed query filters labels in source order without changing selected IDs or chip labels. Clearing the query restores choices. Async option replacements update labels and results; unresolved selections retain their IDs. Search is local to supplied options, with no remote requests or virtualization. The query persists across closing/reopening and external value resets.
+
+The native search is visibly labeled, empty results use a polite status region, and chip buttons are named `Remove <label>` (raw ID when unresolved). Customize names with `[removeLabel]="formatter"`, where `formatter: (option: SelectOption) => string` is pure and `SelectOption` comes from the same subpath. Search edits neither emit selection changes nor touch forms. Input/wrapper/form disabled flags block search and selection edits. With default popover focus settings, opening focuses search; Tab reaches checkbox buttons, Space/Enter toggles them, and Escape closes and restores trigger focus. Enter in search does not submit a form.
+
+For reactive or template-driven forms, import `ReactiveFormsModule` or `FormsModule` and bind `formControl`/`formControlName` or `ngModel` instead of `value`. CVA writes own selection after the first write; null/empty arrays clear it without user emissions. Standalone new `[value]` arrays replace local edits; `[(value)]` synchronizes the parent. Supply unique IDs and immutable array/option updates. `EgFormSearchableMultiselect` from `@egose/shadcn-theme-ng/form-searchable-multiselect` adds the form label/hint/error layout and forwards `searchLabel`, `searchPlaceholder`, `emptyMessage`, and `removeLabel`.
+
 ## Date picker values
 
-`hlm-date-picker` emits a native JS `Date` (or `null` when cleared) via the `dateChange` output. Read it in the
+By default, `hlm-date-picker` emits a native JS `Date` (or `null` when cleared) via the `dateChange` output. Read it in the
 controller with `(dateChange)`, a template ref (`picker.value()`), or a form binding (`ngModel`/`formControlName`,
 the picker is a `ControlValueAccessor`):
 
@@ -216,6 +253,87 @@ export class MyComponent {}
 then always sees local-midnight dates. Related: the picker stays open after selection by default; add the
 `autoCloseOnSelect` attribute (or set it in the same config) to close it on select.
 
+### Typed commits and constraints (single, range, multi)
+
+Text commits on blur or Enter. Both the parsed value and the configured transform result must satisfy
+`min`/`max`, inclusive of the adapter's entire boundary days. Comparisons and validity (`getTime` must be
+finite) use Spartan's configured date adapter; custom date types also need matching parse/format/transform
+config callbacks. A range's transformed endpoints must be ordered; a custom transform may sort them.
+The default range parser accepts a single date as a same-day range, but rejects an explicitly unparseable
+second endpoint.
+
+Multi-date commits cannot exceed `maxSelection`. Consistent with calendar selection, `minSelection` is a
+**deselection floor**: reducing the current count below it is rejected, but growing a selection from empty
+is allowed. Counts apply to the supplied arrays before and after transformation. Supply unique dates.
+At the calendar's maximum, its proposed reset to one new date is accepted only if the floor permits it.
+
+Rejected text remains editable across blur, Enter and refocus, with native `aria-invalid="true"` and invalid
+styling. It does **not** change the committed value or emit `dateChange`/CVA `onChange`; the interaction
+marks the control touched. `inputInvalid()` on the text-input component exposes this local state. It does
+not add Angular validation errors: validators still inspect the last committed form value. Use
+`ariaDescribedby` for application-specific guidance, and include `inputInvalid()` in submission eligibility
+if an unresolved draft should block submission. Existing `forceInvalid` is combined with this state.
+
+A successful text/calendar commit clears the local invalid state. Empty text or the clear button explicitly
+clears (`null` for single/range, `[]` for multi), bypassing transforms and the selection floor. Whitespace is
+passed to the configured parser. Enter retains the edit format so later blur can parse it; blur uses the
+display format. Rejected calendar selections restore the prior selection without emitting a replacement.
+
+`updateDate(value)` is the user-commit boundary and returns `false` on rejection/disabled, `true` on success.
+Programmatic CVA `writeValue` (including form `setValue`/reset) instead applies the transform **without**
+user-constraint enforcement or user emissions, and replaces rejected text even for repeated values/null.
+Standalone `[date]` updates retain their direct, untransformed input contract; they are not user commits.
+`reset()` remains an explicit programmatic clear that emits. Parse/transform callbacks should be pure and
+return values compatible with the configured adapter; parsing failure is represented by `null`.
+
+## Validation descriptions on composed fields
+
+`EgFormAutocomplete`, `EgFormInputOtp`, `EgFormSlider`, and `EgFormCombobox` connect the
+displayed hint or validation error to their actual native input, slider thumbs, or combobox
+trigger/search input. Errors replace hints when invalid and touched, dirty, or submitted;
+correction and form reset restore the appropriate hint. `HlmError` is styled text, not a live region.
+
+Use `[aria-describedby]="'external-help-id'"` on these wrappers to add external descriptions.
+The wrapper normalizes/deduplicates IDs and appends its current message ID. Keep consumer-owned
+description elements mounted, and reserve `<effectiveId>-error` / `-hint` for wrapper messages.
+`[attr.aria-describedby]` only targets the custom host and is not this forwarding contract.
+
+For primitive compositions, `HlmAutocompleteInput`, `HlmComboboxInput`, `HlmComboboxTrigger`,
+`HlmSlider`, and `HlmInputOtpControl` accept `[aria-describedby]` and merge it with descriptions
+registered by the enclosing Spartan field. Import `HlmInputOtpControl` (selector `hlm-input-otp`)
+or `HlmInputOtpImports` from `@egose/shadcn-theme-ng/input-otp`; it retains the brain OTP CVA and
+editing behavior while adding native-input descriptions, required and invalid state. Existing
+`brn-input-otp hlmInputOtp` compositions remain available.
+
+Single combobox mode labels its trigger with `<effectiveId>` and uses `<effectiveId>-search`
+for its separately labeled popup search. Required/invalid selection state stays on the trigger;
+the popup search filters options. Slider thumbs retain their labels and invalid state; the slider
+role has no `aria-required`. Configure Angular validators independently of wrapper `required`.
+Verification is rendered browser DOM/focus coverage, not screen-reader testing.
+
+## Numbered pagination
+
+Import `HlmNumberedPagination` or `HlmNumberedPaginationQueryParams` from
+`@egose/shadcn-theme-ng/pagination` (or the `-tw` package), then bind
+`[(currentPage)]`, `[(itemsPerPage)]` and `[totalItems]`.
+
+Both pagers floor/clamp the current page when totals, size or page inputs change.
+Empty/non-finite/non-positive totals or sizes produce one page with no previous/next;
+invalid sizes are not rewritten. Non-finite pages become 1. A correction emits
+`currentPageChange` once. Positive fractional totals/sizes use ceil division, with
+page counts capped at `Number.MAX_SAFE_INTEGER`. `maxSize` budgets window entries,
+including ellipses: finite positive values are floored/clamped to 1–100, otherwise 7.
+Ranges below 5 show a contiguous active-page window. Helpers `createPageArray` and
+`outOfBoundCorrection` use the same policy without side effects or allocation based
+on an unbounded page count.
+
+The query-params pager builds bounded `?page=` links using `queryParamsHandling="merge"`,
+preserving unrelated query parameters. The parent owns reading route changes and
+any URL synchronization: model corrections and size changes do not navigate. Handle
+`currentPageChange` in the parent if corrected URLs should be replaced, merging other
+parameters. Keep the previous total during loading if temporary zero results should
+not reset the page.
+
 ## Working example
 
 A complete Angular consumer app lives at [`@examples/standard`](https://github.com/egose/shadcn-theme/tree/main/packages/angular/@examples/standard) — see its `src/app/...` for real usage of `@egose/shadcn-theme-ng/button`, `.../layout-simple`, `.../form-text-input`, `.../autocomplete`, `.../select`, `.../form-checkbox`, `.../sheet`, etc.

package/autocomplete/fesm2022/autocomplete.mjs

@@ -9,6 +9,7 @@ import { NgIcon, provideIcons } from '@ng-icons/core';
 import { lucideX, lucideSearch, lucideCheck } from '@ng-icons/lucide';
 import * as i2$1 from '@egose/shadcn-theme-ng-tw/input-group';
 import { HlmInputGroup, HlmInputGroupImports } from '@egose/shadcn-theme-ng-tw/input-group';
+import { BrnFieldControlDescribedBy } from '@spartan-ng/brain/field';
 
 class HlmAutocomplete {
     constructor() {
@@ -103,6 +104,9 @@ class HlmAutocompleteInput {
     ...(ngDevMode ? [{ debugName: "inputId" }] : /* istanbul ignore next */ []));
     placeholder = input('', /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "placeholder" }] : /* istanbul ignore next */ []));
+    /** Native input description IDs, merged with enclosing Spartan field descriptions. */
+    ariaDescribedBy = input(null, { ...(ngDevMode ? { debugName: "ariaDescribedBy" } : /* istanbul ignore next */ {}), alias: 'aria-describedby' });
+    required = input(false, { ...(ngDevMode ? { debugName: "required" } : /* istanbul ignore next */ {}), transform: booleanAttribute });
     showSearch = input(true, { ...(ngDevMode ? { debugName: "showSearch" } : /* istanbul ignore next */ {}), transform: booleanAttribute });
     showClear = input(false, { ...(ngDevMode ? { debugName: "showClear" } : /* istanbul ignore next */ {}), transform: booleanAttribute });
     /** Forces the invalid state visually, regardless of form control state. */
@@ -114,13 +118,16 @@ class HlmAutocompleteInput {
         classes(() => 'tw:w-auto');
     }
     static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "22.1.3", ngImport: i0, type: HlmAutocompleteInput, deps: [], target: i0.ɵɵFactoryTarget.Component });
-    static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.0.0", version: "22.1.3", type: HlmAutocompleteInput, isStandalone: true, selector: "hlm-autocomplete-input", inputs: { inputId: { classPropertyName: "inputId", publicName: "inputId", isSignal: true, isRequired: false, transformFunction: null }, placeholder: { classPropertyName: "placeholder", publicName: "placeholder", isSignal: true, isRequired: false, transformFunction: null }, showSearch: { classPropertyName: "showSearch", publicName: "showSearch", isSignal: true, isRequired: false, transformFunction: null }, showClear: { classPropertyName: "showClear", publicName: "showClear", isSignal: true, isRequired: false, transformFunction: null }, forceInvalid: { classPropertyName: "forceInvalid", publicName: "forceInvalid", isSignal: true, isRequired: false, transformFunction: null }, ariaInvalidOverride: { classPropertyName: "ariaInvalidOverride", publicName: "aria-invalid", isSignal: true, isRequired: false, transformFunction: null } }, providers: [provideIcons({ lucideSearch, lucideX })], hostDirectives: [{ directive: i1.BrnAutocompleteAnchor }, { directive: i2$1.HlmInputGroup }], ngImport: i0, template: `
+    static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.0.0", version: "22.1.3", type: HlmAutocompleteInput, isStandalone: true, selector: "hlm-autocomplete-input", inputs: { inputId: { classPropertyName: "inputId", publicName: "inputId", isSignal: true, isRequired: false, transformFunction: null }, placeholder: { classPropertyName: "placeholder", publicName: "placeholder", isSignal: true, isRequired: false, transformFunction: null }, ariaDescribedBy: { classPropertyName: "ariaDescribedBy", publicName: "aria-describedby", isSignal: true, isRequired: false, transformFunction: null }, required: { classPropertyName: "required", publicName: "required", isSignal: true, isRequired: false, transformFunction: null }, showSearch: { classPropertyName: "showSearch", publicName: "showSearch", isSignal: true, isRequired: false, transformFunction: null }, showClear: { classPropertyName: "showClear", publicName: "showClear", isSignal: true, isRequired: false, transformFunction: null }, forceInvalid: { classPropertyName: "forceInvalid", publicName: "forceInvalid", isSignal: true, isRequired: false, transformFunction: null }, ariaInvalidOverride: { classPropertyName: "ariaInvalidOverride", publicName: "aria-invalid", isSignal: true, isRequired: false, transformFunction: null } }, providers: [provideIcons({ lucideSearch, lucideX })], hostDirectives: [{ directive: i1.BrnAutocompleteAnchor }, { directive: i2$1.HlmInputGroup }], ngImport: i0, template: `
     <input
       brnAutocompleteInput
       #autocompleteInput="brnAutocompleteInput"
       hlmInputGroupInput
       [id]="inputId()"
       [placeholder]="placeholder()"
+      brnFieldControlDescribedBy
+      [aria-describedby]="ariaDescribedBy()"
+      [attr.aria-required]="required() || null"
       [aria-invalid]="ariaInvalidOverride()"
       [forceInvalid]="forceInvalid()"
     />
@@ -146,13 +153,13 @@ class HlmAutocompleteInput {
       </hlm-input-group-addon>
     }
     <ng-content />
-  `, isInline: true, dependencies: [{ kind: "directive", type: i2$1.HlmInputGroupAddon, selector: "[hlmInputGroupAddon],hlm-input-group-addon", inputs: ["align"] }, { kind: "directive", type: i2$1.HlmInputGroupButton, selector: "button[hlmInputGroupButton]", inputs: ["size", "type", "class"] }, { kind: "directive", type: i2$1.HlmInputGroupInput, selector: "input[hlmInputGroupInput]" }, { kind: "component", type: NgIcon, selector: "ng-icon", inputs: ["name", "svg", "size", "strokeWidth", "color"] }, { kind: "directive", type: BrnAutocompleteClear, selector: "[brnAutocompleteClear]" }, { kind: "directive", type: BrnAutocompleteInput, selector: "input[brnAutocompleteInput]", inputs: ["id", "aria-invalid", "forceInvalid"], exportAs: ["brnAutocompleteInput"] }], changeDetection: i0.ChangeDetectionStrategy.OnPush });
+  `, isInline: true, dependencies: [{ kind: "directive", type: i2$1.HlmInputGroupAddon, selector: "[hlmInputGroupAddon],hlm-input-group-addon", inputs: ["align"] }, { kind: "directive", type: i2$1.HlmInputGroupButton, selector: "button[hlmInputGroupButton]", inputs: ["size", "type", "class"] }, { kind: "directive", type: i2$1.HlmInputGroupInput, selector: "input[hlmInputGroupInput]" }, { kind: "component", type: NgIcon, selector: "ng-icon", inputs: ["name", "svg", "size", "strokeWidth", "color"] }, { kind: "directive", type: BrnAutocompleteClear, selector: "[brnAutocompleteClear]" }, { kind: "directive", type: BrnAutocompleteInput, selector: "input[brnAutocompleteInput]", inputs: ["id", "aria-invalid", "forceInvalid"], exportAs: ["brnAutocompleteInput"] }, { kind: "directive", type: BrnFieldControlDescribedBy, selector: "[brnFieldControlDescribedBy]", inputs: ["aria-describedby"] }], changeDetection: i0.ChangeDetectionStrategy.OnPush });
 }
 i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.1.3", ngImport: i0, type: HlmAutocompleteInput, decorators: [{
             type: Component,
             args: [{
                     selector: 'hlm-autocomplete-input',
-                    imports: [HlmInputGroupImports, NgIcon, BrnAutocompleteClear, BrnAutocompleteInput],
+                    imports: [HlmInputGroupImports, NgIcon, BrnAutocompleteClear, BrnAutocompleteInput, BrnFieldControlDescribedBy],
                     providers: [provideIcons({ lucideSearch, lucideX })],
                     changeDetection: ChangeDetectionStrategy.OnPush,
                     hostDirectives: [BrnAutocompleteAnchor, HlmInputGroup],
@@ -163,6 +170,9 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.1.3", ngImpor
       hlmInputGroupInput
       [id]="inputId()"
       [placeholder]="placeholder()"
+      brnFieldControlDescribedBy
+      [aria-describedby]="ariaDescribedBy()"
+      [attr.aria-required]="required() || null"
       [aria-invalid]="ariaInvalidOverride()"
       [forceInvalid]="forceInvalid()"
     />
@@ -190,7 +200,7 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.1.3", ngImpor
     <ng-content />
   `,
                 }]
-        }], ctorParameters: () => [], propDecorators: { inputId: [{ type: i0.Input, args: [{ isSignal: true, alias: "inputId", required: false }] }], placeholder: [{ type: i0.Input, args: [{ isSignal: true, alias: "placeholder", required: false }] }], showSearch: [{ type: i0.Input, args: [{ isSignal: true, alias: "showSearch", required: false }] }], showClear: [{ type: i0.Input, args: [{ isSignal: true, alias: "showClear", required: false }] }], forceInvalid: [{ type: i0.Input, args: [{ isSignal: true, alias: "forceInvalid", required: false }] }], ariaInvalidOverride: [{ type: i0.Input, args: [{ isSignal: true, alias: "aria-invalid", required: false }] }] } });
+        }], ctorParameters: () => [], propDecorators: { inputId: [{ type: i0.Input, args: [{ isSignal: true, alias: "inputId", required: false }] }], placeholder: [{ type: i0.Input, args: [{ isSignal: true, alias: "placeholder", required: false }] }], ariaDescribedBy: [{ type: i0.Input, args: [{ isSignal: true, alias: "aria-describedby", required: false }] }], required: [{ type: i0.Input, args: [{ isSignal: true, alias: "required", required: false }] }], showSearch: [{ type: i0.Input, args: [{ isSignal: true, alias: "showSearch", required: false }] }], showClear: [{ type: i0.Input, args: [{ isSignal: true, alias: "showClear", required: false }] }], forceInvalid: [{ type: i0.Input, args: [{ isSignal: true, alias: "forceInvalid", required: false }] }], ariaInvalidOverride: [{ type: i0.Input, args: [{ isSignal: true, alias: "aria-invalid", required: false }] }] } });
 
 class HlmAutocompleteItem {
     _brnAutocompleteItem = inject(BrnAutocompleteItem);

package/autocomplete/types/autocomplete.d.ts

@@ -32,6 +32,9 @@ declare class HlmAutocompleteInput {
     private static _id;
     readonly inputId: i0.InputSignal<string>;
     readonly placeholder: i0.InputSignal<string>;
+    /** Native input description IDs, merged with enclosing Spartan field descriptions. */
+    readonly ariaDescribedBy: i0.InputSignal<string | null>;
+    readonly required: i0.InputSignalWithTransform<boolean, BooleanInput>;
     readonly showSearch: i0.InputSignalWithTransform<boolean, BooleanInput>;
     readonly showClear: i0.InputSignalWithTransform<boolean, BooleanInput>;
     /** Forces the invalid state visually, regardless of form control state. */
@@ -40,7 +43,7 @@ declare class HlmAutocompleteInput {
     readonly ariaInvalidOverride: i0.InputSignalWithTransform<boolean | undefined, BooleanInput>;
     constructor();
     static ɵfac: i0.ɵɵFactoryDeclaration<HlmAutocompleteInput, never>;
-    static ɵcmp: i0.ɵɵComponentDeclaration<HlmAutocompleteInput, "hlm-autocomplete-input", never, { "inputId": { "alias": "inputId"; "required": false; "isSignal": true; }; "placeholder": { "alias": "placeholder"; "required": false; "isSignal": true; }; "showSearch": { "alias": "showSearch"; "required": false; "isSignal": true; }; "showClear": { "alias": "showClear"; "required": false; "isSignal": true; }; "forceInvalid": { "alias": "forceInvalid"; "required": false; "isSignal": true; }; "ariaInvalidOverride": { "alias": "aria-invalid"; "required": false; "isSignal": true; }; }, {}, never, ["*"], true, [{ directive: typeof i1.BrnAutocompleteAnchor; inputs: {}; outputs: {}; }, { directive: typeof i2$1.HlmInputGroup; inputs: {}; outputs: {}; }]>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<HlmAutocompleteInput, "hlm-autocomplete-input", never, { "inputId": { "alias": "inputId"; "required": false; "isSignal": true; }; "placeholder": { "alias": "placeholder"; "required": false; "isSignal": true; }; "ariaDescribedBy": { "alias": "aria-describedby"; "required": false; "isSignal": true; }; "required": { "alias": "required"; "required": false; "isSignal": true; }; "showSearch": { "alias": "showSearch"; "required": false; "isSignal": true; }; "showClear": { "alias": "showClear"; "required": false; "isSignal": true; }; "forceInvalid": { "alias": "forceInvalid"; "required": false; "isSignal": true; }; "ariaInvalidOverride": { "alias": "aria-invalid"; "required": false; "isSignal": true; }; }, {}, never, ["*"], true, [{ directive: typeof i1.BrnAutocompleteAnchor; inputs: {}; outputs: {}; }, { directive: typeof i2$1.HlmInputGroup; inputs: {}; outputs: {}; }]>;
 }
 
 declare class HlmAutocompleteItem {

package/checkbox/README.md

@@ -75,6 +75,8 @@ export class DemoModule {}
 
 Real selector: `hlm-checkbox` (element only). The host renders `class="contents peer"` so sibling label/description selectors (`peer-*`) keep working; `id` / `aria-*` attributes are nulled on the host and forwarded to the inner `brn-checkbox` instead. Set a visible label with a native `<label for>` — the component does not render label text itself.
 
+Omitted/null IDs use `HlmFormIdGenerator` from `@egose/shadcn-theme-ng/form-field`: `hlm-checkbox-${APP_ID}-${sequence}`. The fallback is allocated once per instance from the application-scoped service, so separate applications restart their sequence and matching server/client `APP_ID` plus component creation order reproduce IDs. Explicit IDs are preserved on the focusable button; reverting to null restores that instance's fallback. Supply distinct `APP_ID` values for multiple applications on one page and unique explicit IDs. Checkboxes nested inside separate native labels each receive their own generated label association through Spartan; existing label IDs are retained.
+
 ## API reference
 
 ### `HlmCheckbox` (`hlm-checkbox`)
@@ -83,7 +85,7 @@ Real selector: `hlm-checkbox` (element only). The host renders `class="contents
 | -------------------------------------- | ----------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `checked`                              | `model<boolean \| 'indeterminate'>` | `false` | Checked state. Two-way bindable (`[(checked)]`). `'indeterminate'` renders the checked icon; clicking it resolves to `true`.                       |
 | `class` (`userClass`)                  | `ClassValue`                        | `''`    | Extra classes merged into the box.                                                                                                                 |
-| `id`                                   | `string \| null`                    | `null`  | Forwarded to inner `brn-checkbox`. Pair with `<label for>`.                                                                                        |
+| `id`                                   | `string \| null`                    | `null`  | Explicit native button ID, or application-scoped fallback when null. Pair explicit IDs with `<label for>`.                                         |
 | `aria-label` (`ariaLabel`)             | `string \| null`                    | `null`  | Forwarded aria-label.                                                                                                                              |
 | `aria-labelledby` (`ariaLabelledby`)   | `string \| null`                    | `null`  | Forwarded aria-labelledby.                                                                                                                         |
 | `aria-describedby` (`ariaDescribedby`) | `string \| null`                    | `null`  | Forwarded aria-describedby.                                                                                                                        |
@@ -102,6 +104,8 @@ Real selector: `hlm-checkbox` (element only). The host renders `class="contents
 
 ControlValueAccessor: `writeValue(value)`, `registerOnChange`, `registerOnTouched`, `setDisabledState(isDisabled)` (writes `formDisabled`, hence `disabledState`). `HLM_CHECKBOX_VALUE_ACCESSOR` (`NG_VALUE_ACCESSOR`, `forwardRef(HlmCheckbox)`, `multi: true`) is provided on the component.
 
+Both `[checked]` and CVA writes preserve `'indeterminate'`. The primitive forwards boolean checked and indeterminate separately to Spartan: the actual `button[role="checkbox"]` exposes `aria-checked="mixed"` and `data-state="indeterminate"`. An enabled click resolves mixed to `true`, then subsequent clicks toggle true/false; `changed` and CVA `onChange` emit the resulting boolean once. Thus clicking a partially selected table header selects its displayed page. Programmatic CVA writes do not call `changed`/`onChange` or touch the control; null resets to false. Any active input, wrapper, or form disabled lock blocks user toggles without discarding mixed state.
+
 ## Examples
 
 ### 1. Basic with label
@@ -307,7 +311,7 @@ export class ChangedCheckboxComponent {
 - The component renders a native-checkbox-equivalent `brn-checkbox` with `aria-label`/`labelledby`/`describedby` forwarding — always provide one: visible `<label for>` preferred, `aria-label` for icon-only rows.
 - `disabledState` adds `data-disabled`, `cursor-not-allowed`, and `opacity-50`; disabled boxes are skipped correctly because clicks early-return.
 - The check glyph is decorative (`lucideCheck` icon, no text) — state is exposed via `data-[state]` / native semantics, not the icon.
-- Tri-state: `'indeterminate'` is a visual/model state, not `aria-checked="mixed"` — if you need mixed semantics for a tree, add `aria-checked` handling at your own level and test with a screen reader.
+- Tri-state: `'indeterminate'` exposes `aria-checked="mixed"` on the focusable checkbox button. State and nested-label associations are covered by rendered browser DOM tests; screen-reader announcement behavior is not asserted by those tests.
 
 ## Theming / CSS variables
 

package/checkbox/fesm2022/checkbox.mjs

@@ -1,9 +1,10 @@
 import * as i0 from '@angular/core';
-import { forwardRef, input, computed, model, booleanAttribute, signal, output, ChangeDetectionStrategy, Component, NgModule } from '@angular/core';
+import { forwardRef, input, computed, inject, model, booleanAttribute, signal, output, ChangeDetectionStrategy, Component, NgModule } from '@angular/core';
 import { NG_VALUE_ACCESSOR } from '@angular/forms';
 import { provideIcons, NgIcon } from '@ng-icons/core';
 import { lucideCheck } from '@ng-icons/lucide';
 import { BrnCheckbox } from '@spartan-ng/brain/checkbox';
+import { HlmFormIdGenerator } from '@egose/shadcn-theme-ng-tw/form-field';
 import { HlmIcon } from '@egose/shadcn-theme-ng-tw/icon';
 import { hlm } from '@egose/shadcn-theme-ng-tw/utils';
 
@@ -16,16 +17,19 @@ class HlmCheckbox {
     userClass = input('', { ...(ngDevMode ? { debugName: "userClass" } : /* istanbul ignore next */ {}), alias: 'class' });
     _computedClass = computed(() => hlm('tw:border-input tw:dark:bg-input/30 tw:data-[state=checked]:bg-primary tw:data-[state=checked]:text-primary-foreground tw:dark:data-[state=checked]:bg-primary tw:data-[state=checked]:border-primary tw:focus-visible:border-ring tw:focus-visible:ring-ring/50 tw:aria-invalid:ring-destructive/20 tw:dark:aria-invalid:ring-destructive/40 tw:aria-invalid:border-destructive tw:shadow-xs tw:peer tw:size-4 tw:shrink-0 tw:cursor-default tw:rounded-[4px] tw:border tw:outline-none tw:transition-shadow tw:focus-visible:ring-[3px] tw:disabled:cursor-not-allowed tw:disabled:opacity-50', this.userClass(), this.disabledState() ? 'tw:cursor-not-allowed tw:opacity-50' : ''), /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "_computedClass" }] : /* istanbul ignore next */ []));
-    /** Used to set the id on the underlying brn element. */
+    /** Native checkbox ID. Null uses a stable application-scoped fallback; explicit IDs are preserved. */
     id = input(null, /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "id" }] : /* istanbul ignore next */ []));
+    _generatedId = inject(HlmFormIdGenerator).generate('hlm-checkbox');
+    _id = computed(() => this.id() ?? this._generatedId, /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "_id" }] : /* istanbul ignore next */ []));
     /** Used to set the aria-label attribute on the underlying brn element. */
     ariaLabel = input(null, { ...(ngDevMode ? { debugName: "ariaLabel" } : /* istanbul ignore next */ {}), alias: 'aria-label' });
     /** Used to set the aria-labelledby attribute on the underlying brn element. */
     ariaLabelledby = input(null, { ...(ngDevMode ? { debugName: "ariaLabelledby" } : /* istanbul ignore next */ {}), alias: 'aria-labelledby' });
     /** Used to set the aria-describedby attribute on the underlying brn element. */
     ariaDescribedby = input(null, { ...(ngDevMode ? { debugName: "ariaDescribedby" } : /* istanbul ignore next */ {}), alias: 'aria-describedby' });
-    /** The checked state of the checkbox. */
+    /** Tri-state model. Indeterminate exposes native aria-checked="mixed"; clicking it selects (true). */
     checked = model(false, /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "checked" }] : /* istanbul ignore next */ []));
     /** The name attribute of the checkbox. */
@@ -51,9 +55,9 @@ class HlmCheckbox {
         this._onChange?.(checked);
         this.changed.emit(checked);
     }
-    /** CONTROL VALUE ACCESSOR */
+    /** Programmatic writes preserve indeterminate; null resets to false without changed/onChange notifications. */
     writeValue(value) {
-        this.checked.set(!!value);
+        this.checked.set(value === 'indeterminate' ? value : !!value);
     }
     registerOnChange(fn) {
         this._onChange = fn;
@@ -67,10 +71,11 @@ class HlmCheckbox {
     static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "22.1.3", ngImport: i0, type: HlmCheckbox, deps: [], target: i0.ɵɵFactoryTarget.Component });
     static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.0.0", version: "22.1.3", type: HlmCheckbox, isStandalone: true, selector: "hlm-checkbox", inputs: { userClass: { classPropertyName: "userClass", publicName: "class", isSignal: true, isRequired: false, transformFunction: null }, id: { classPropertyName: "id", publicName: "id", isSignal: true, isRequired: false, transformFunction: null }, ariaLabel: { classPropertyName: "ariaLabel", publicName: "aria-label", isSignal: true, isRequired: false, transformFunction: null }, ariaLabelledby: { classPropertyName: "ariaLabelledby", publicName: "aria-labelledby", isSignal: true, isRequired: false, transformFunction: null }, ariaDescribedby: { classPropertyName: "ariaDescribedby", publicName: "aria-describedby", isSignal: true, isRequired: false, transformFunction: null }, checked: { classPropertyName: "checked", publicName: "checked", isSignal: true, isRequired: false, transformFunction: null }, name: { classPropertyName: "name", publicName: "name", isSignal: true, isRequired: false, transformFunction: null }, required: { classPropertyName: "required", publicName: "required", isSignal: true, isRequired: false, transformFunction: null }, disabled: { classPropertyName: "disabled", publicName: "disabled", isSignal: true, isRequired: false, transformFunction: null }, wrapperDisabled: { classPropertyName: "wrapperDisabled", publicName: "wrapperDisabled", isSignal: true, isRequired: false, transformFunction: null } }, outputs: { checked: "checkedChange", changed: "changed" }, host: { properties: { "attr.id": "null", "attr.aria-label": "null", "attr.aria-labelledby": "null", "attr.aria-describedby": "null", "attr.data-disabled": "disabledState() ? \"\" : null" }, classAttribute: "contents peer" }, providers: [HLM_CHECKBOX_VALUE_ACCESSOR], ngImport: i0, template: `
     <brn-checkbox
-      [id]="id()"
+      [id]="_id()"
       [name]="name()"
       [class]="_computedClass()"
-      [checked]="checked()"
+      [checked]="checked() === true"
+      [indeterminate]="checked() === 'indeterminate'"
       [disabled]="disabledState()"
       [required]="required()"
       [aria-label]="ariaLabel()"
@@ -94,10 +99,11 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.1.3", ngImpor
                     imports: [BrnCheckbox, NgIcon, HlmIcon],
                     template: `
     <brn-checkbox
-      [id]="id()"
+      [id]="_id()"
       [name]="name()"
       [class]="_computedClass()"
-      [checked]="checked()"
+      [checked]="checked() === true"
+      [indeterminate]="checked() === 'indeterminate'"
       [disabled]="disabledState()"
       [required]="required()"
       [aria-label]="ariaLabel()"

package/checkbox/types/checkbox.d.ts

@@ -12,15 +12,17 @@ declare const HLM_CHECKBOX_VALUE_ACCESSOR: {
 declare class HlmCheckbox implements ControlValueAccessor {
     readonly userClass: _angular_core.InputSignal<ClassValue>;
     protected readonly _computedClass: _angular_core.Signal<string>;
-    /** Used to set the id on the underlying brn element. */
+    /** Native checkbox ID. Null uses a stable application-scoped fallback; explicit IDs are preserved. */
     readonly id: _angular_core.InputSignal<string | null>;
+    private readonly _generatedId;
+    protected readonly _id: _angular_core.Signal<string>;
     /** Used to set the aria-label attribute on the underlying brn element. */
     readonly ariaLabel: _angular_core.InputSignal<string | null>;
     /** Used to set the aria-labelledby attribute on the underlying brn element. */
     readonly ariaLabelledby: _angular_core.InputSignal<string | null>;
     /** Used to set the aria-describedby attribute on the underlying brn element. */
     readonly ariaDescribedby: _angular_core.InputSignal<string | null>;
-    /** The checked state of the checkbox. */
+    /** Tri-state model. Indeterminate exposes native aria-checked="mixed"; clicking it selects (true). */
     readonly checked: _angular_core.ModelSignal<CheckboxValue>;
     /** The name attribute of the checkbox. */
     readonly name: _angular_core.InputSignal<string | null>;
@@ -36,8 +38,8 @@ declare class HlmCheckbox implements ControlValueAccessor {
     protected _onChange?: ChangeFn<CheckboxValue>;
     protected _onTouched?: TouchFn;
     protected _handleCheckedChange(checked: boolean): void;
-    /** CONTROL VALUE ACCESSOR */
-    writeValue(value: CheckboxValue): void;
+    /** Programmatic writes preserve indeterminate; null resets to false without changed/onChange notifications. */
+    writeValue(value: CheckboxValue | null): void;
     registerOnChange(fn: ChangeFn<CheckboxValue>): void;
     registerOnTouched(fn: TouchFn): void;
     setDisabledState(isDisabled: boolean): void;

package/combobox/fesm2022/combobox.mjs

@@ -211,6 +211,9 @@ class HlmComboboxInput {
     ...(ngDevMode ? [{ debugName: "inputId" }] : /* istanbul ignore next */ []));
     placeholder = input('', /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "placeholder" }] : /* istanbul ignore next */ []));
+    /** Native input description IDs, merged with enclosing Spartan field descriptions. */
+    ariaDescribedBy = input(null, { ...(ngDevMode ? { debugName: "ariaDescribedBy" } : /* istanbul ignore next */ {}), alias: 'aria-describedby' });
+    ariaLabelledBy = input(null, { ...(ngDevMode ? { debugName: "ariaLabelledBy" } : /* istanbul ignore next */ {}), alias: 'aria-labelledby' });
     showTrigger = input(true, { ...(ngDevMode ? { debugName: "showTrigger" } : /* istanbul ignore next */ {}), transform: booleanAttribute });
     showClear = input(false, { ...(ngDevMode ? { debugName: "showClear" } : /* istanbul ignore next */ {}), transform: booleanAttribute });
     forceInvalid = input(false, { ...(ngDevMode ? { debugName: "forceInvalid" } : /* istanbul ignore next */ {}), transform: booleanAttribute });
@@ -221,7 +224,7 @@ class HlmComboboxInput {
         classes(() => 'tw:w-auto');
     }
     static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "22.1.3", ngImport: i0, type: HlmComboboxInput, deps: [], target: i0.ɵɵFactoryTarget.Component });
-    static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.0.0", version: "22.1.3", type: HlmComboboxInput, isStandalone: true, selector: "hlm-combobox-input", inputs: { inputId: { classPropertyName: "inputId", publicName: "inputId", isSignal: true, isRequired: false, transformFunction: null }, placeholder: { classPropertyName: "placeholder", publicName: "placeholder", isSignal: true, isRequired: false, transformFunction: null }, showTrigger: { classPropertyName: "showTrigger", publicName: "showTrigger", isSignal: true, isRequired: false, transformFunction: null }, showClear: { classPropertyName: "showClear", publicName: "showClear", isSignal: true, isRequired: false, transformFunction: null }, forceInvalid: { classPropertyName: "forceInvalid", publicName: "forceInvalid", isSignal: true, isRequired: false, transformFunction: null }, ariaInvalidOverride: { classPropertyName: "ariaInvalidOverride", publicName: "aria-invalid", isSignal: true, isRequired: false, transformFunction: null } }, providers: [provideIcons({ lucideChevronDown, lucideX })], hostDirectives: [{ directive: i1.BrnComboboxAnchor }, { directive: i2$1.HlmInputGroup }], ngImport: i0, template: `
+    static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.0.0", version: "22.1.3", type: HlmComboboxInput, isStandalone: true, selector: "hlm-combobox-input", inputs: { inputId: { classPropertyName: "inputId", publicName: "inputId", isSignal: true, isRequired: false, transformFunction: null }, placeholder: { classPropertyName: "placeholder", publicName: "placeholder", isSignal: true, isRequired: false, transformFunction: null }, ariaDescribedBy: { classPropertyName: "ariaDescribedBy", publicName: "aria-describedby", isSignal: true, isRequired: false, transformFunction: null }, ariaLabelledBy: { classPropertyName: "ariaLabelledBy", publicName: "aria-labelledby", isSignal: true, isRequired: false, transformFunction: null }, showTrigger: { classPropertyName: "showTrigger", publicName: "showTrigger", isSignal: true, isRequired: false, transformFunction: null }, showClear: { classPropertyName: "showClear", publicName: "showClear", isSignal: true, isRequired: false, transformFunction: null }, forceInvalid: { classPropertyName: "forceInvalid", publicName: "forceInvalid", isSignal: true, isRequired: false, transformFunction: null }, ariaInvalidOverride: { classPropertyName: "ariaInvalidOverride", publicName: "aria-invalid", isSignal: true, isRequired: false, transformFunction: null } }, providers: [provideIcons({ lucideChevronDown, lucideX })], hostDirectives: [{ directive: i1.BrnComboboxAnchor }, { directive: i2$1.HlmInputGroup }], ngImport: i0, template: `
     <input
       brnComboboxInput
       #comboboxInput="brnComboboxInput"
@@ -230,6 +233,9 @@ class HlmComboboxInput {
       hlmInputGroupInput
       [id]="inputId()"
       [placeholder]="placeholder()"
+      brnFieldControlDescribedBy
+      [aria-describedby]="ariaDescribedBy()"
+      [attr.aria-labelledby]="ariaLabelledBy()"
       [forceInvalid]="forceInvalid()"
       [aria-invalid]="ariaInvalidOverride()"
     />
@@ -264,13 +270,13 @@ class HlmComboboxInput {
     </hlm-input-group-addon>
 
     <ng-content />
-  `, isInline: true, dependencies: [{ kind: "directive", type: i2$1.HlmInputGroupAddon, selector: "[hlmInputGroupAddon],hlm-input-group-addon", inputs: ["align"] }, { kind: "directive", type: i2$1.HlmInputGroupButton, selector: "button[hlmInputGroupButton]", inputs: ["size", "type", "class"] }, { kind: "directive", type: i2$1.HlmInputGroupInput, selector: "input[hlmInputGroupInput]" }, { kind: "component", type: NgIcon, selector: "ng-icon", inputs: ["name", "svg", "size", "strokeWidth", "color"] }, { kind: "directive", type: i1.BrnComboboxClear, selector: "[brnComboboxClear]" }, { kind: "directive", type: i1.BrnComboboxInput, selector: "input[brnComboboxInput]", inputs: ["id", "aria-invalid", "forceInvalid"], exportAs: ["brnComboboxInput"] }, { kind: "directive", type: i1.BrnComboboxPopoverTrigger, selector: "[brnComboboxPopoverTrigger]", inputs: ["closeOnTriggerClick"] }], changeDetection: i0.ChangeDetectionStrategy.OnPush });
+  `, isInline: true, dependencies: [{ kind: "directive", type: i2$1.HlmInputGroupAddon, selector: "[hlmInputGroupAddon],hlm-input-group-addon", inputs: ["align"] }, { kind: "directive", type: i2$1.HlmInputGroupButton, selector: "button[hlmInputGroupButton]", inputs: ["size", "type", "class"] }, { kind: "directive", type: i2$1.HlmInputGroupInput, selector: "input[hlmInputGroupInput]" }, { kind: "component", type: NgIcon, selector: "ng-icon", inputs: ["name", "svg", "size", "strokeWidth", "color"] }, { kind: "directive", type: i1.BrnComboboxClear, selector: "[brnComboboxClear]" }, { kind: "directive", type: i1.BrnComboboxInput, selector: "input[brnComboboxInput]", inputs: ["id", "aria-invalid", "forceInvalid"], exportAs: ["brnComboboxInput"] }, { kind: "directive", type: i1.BrnComboboxPopoverTrigger, selector: "[brnComboboxPopoverTrigger]", inputs: ["closeOnTriggerClick"] }, { kind: "directive", type: BrnFieldControlDescribedBy, selector: "[brnFieldControlDescribedBy]", inputs: ["aria-describedby"] }], changeDetection: i0.ChangeDetectionStrategy.OnPush });
 }
 i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.1.3", ngImport: i0, type: HlmComboboxInput, decorators: [{
             type: Component,
             args: [{
                     selector: 'hlm-combobox-input',
-                    imports: [HlmInputGroupImports, NgIcon, BrnComboboxImports, BrnComboboxPopoverTrigger],
+                    imports: [HlmInputGroupImports, NgIcon, BrnComboboxImports, BrnComboboxPopoverTrigger, BrnFieldControlDescribedBy],
                     providers: [provideIcons({ lucideChevronDown, lucideX })],
                     changeDetection: ChangeDetectionStrategy.OnPush,
                     hostDirectives: [BrnComboboxAnchor, HlmInputGroup],
@@ -283,6 +289,9 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.1.3", ngImpor
       hlmInputGroupInput
       [id]="inputId()"
       [placeholder]="placeholder()"
+      brnFieldControlDescribedBy
+      [aria-describedby]="ariaDescribedBy()"
+      [attr.aria-labelledby]="ariaLabelledBy()"
       [forceInvalid]="forceInvalid()"
       [aria-invalid]="ariaInvalidOverride()"
     />
@@ -319,7 +328,7 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.1.3", ngImpor
     <ng-content />
   `,
                 }]
-        }], ctorParameters: () => [], propDecorators: { inputId: [{ type: i0.Input, args: [{ isSignal: true, alias: "inputId", required: false }] }], placeholder: [{ type: i0.Input, args: [{ isSignal: true, alias: "placeholder", required: false }] }], showTrigger: [{ type: i0.Input, args: [{ isSignal: true, alias: "showTrigger", required: false }] }], showClear: [{ type: i0.Input, args: [{ isSignal: true, alias: "showClear", required: false }] }], forceInvalid: [{ type: i0.Input, args: [{ isSignal: true, alias: "forceInvalid", required: false }] }], ariaInvalidOverride: [{ type: i0.Input, args: [{ isSignal: true, alias: "aria-invalid", required: false }] }] } });
+        }], ctorParameters: () => [], propDecorators: { inputId: [{ type: i0.Input, args: [{ isSignal: true, alias: "inputId", required: false }] }], placeholder: [{ type: i0.Input, args: [{ isSignal: true, alias: "placeholder", required: false }] }], ariaDescribedBy: [{ type: i0.Input, args: [{ isSignal: true, alias: "aria-describedby", required: false }] }], ariaLabelledBy: [{ type: i0.Input, args: [{ isSignal: true, alias: "aria-labelledby", required: false }] }], showTrigger: [{ type: i0.Input, args: [{ isSignal: true, alias: "showTrigger", required: false }] }], showClear: [{ type: i0.Input, args: [{ isSignal: true, alias: "showClear", required: false }] }], forceInvalid: [{ type: i0.Input, args: [{ isSignal: true, alias: "forceInvalid", required: false }] }], ariaInvalidOverride: [{ type: i0.Input, args: [{ isSignal: true, alias: "aria-invalid", required: false }] }] } });
 
 class HlmComboboxItem {
     _brnComboboxItem = inject(BrnComboboxItem);
@@ -509,11 +518,14 @@ class HlmComboboxTrigger {
     ...(ngDevMode ? [{ debugName: "_computedClass" }] : /* istanbul ignore next */ []));
     buttonId = input(`hlm-combobox-trigger-${HlmComboboxTrigger._id++}`, /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "buttonId" }] : /* istanbul ignore next */ []));
+    /** Native button description IDs, merged with enclosing Spartan field descriptions. */
+    ariaDescribedBy = input(null, { ...(ngDevMode ? { debugName: "ariaDescribedBy" } : /* istanbul ignore next */ {}), alias: 'aria-describedby' });
+    required = input(false, { ...(ngDevMode ? { debugName: "required" } : /* istanbul ignore next */ {}), transform: booleanAttribute });
     variant = input('outline', /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "variant" }] : /* istanbul ignore next */ []));
     forceInvalid = input(false, { ...(ngDevMode ? { debugName: "forceInvalid" } : /* istanbul ignore next */ {}), transform: booleanAttribute });
     static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "22.1.3", ngImport: i0, type: HlmComboboxTrigger, deps: [], target: i0.ɵɵFactoryTarget.Component });
-    static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.1.0", version: "22.1.3", type: HlmComboboxTrigger, isStandalone: true, selector: "hlm-combobox-trigger", inputs: { userClass: { classPropertyName: "userClass", publicName: "class", isSignal: true, isRequired: false, transformFunction: null }, buttonId: { classPropertyName: "buttonId", publicName: "buttonId", isSignal: true, isRequired: false, transformFunction: null }, variant: { classPropertyName: "variant", publicName: "variant", isSignal: true, isRequired: false, transformFunction: null }, forceInvalid: { classPropertyName: "forceInvalid", publicName: "forceInvalid", isSignal: true, isRequired: false, transformFunction: null } }, providers: [provideIcons({ lucideChevronDown })], ngImport: i0, template: `
+    static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.1.0", version: "22.1.3", type: HlmComboboxTrigger, isStandalone: true, selector: "hlm-combobox-trigger", inputs: { userClass: { classPropertyName: "userClass", publicName: "class", isSignal: true, isRequired: false, transformFunction: null }, buttonId: { classPropertyName: "buttonId", publicName: "buttonId", isSignal: true, isRequired: false, transformFunction: null }, ariaDescribedBy: { classPropertyName: "ariaDescribedBy", publicName: "aria-describedby", isSignal: true, isRequired: false, transformFunction: null }, required: { classPropertyName: "required", publicName: "required", isSignal: true, isRequired: false, transformFunction: null }, variant: { classPropertyName: "variant", publicName: "variant", isSignal: true, isRequired: false, transformFunction: null }, forceInvalid: { classPropertyName: "forceInvalid", publicName: "forceInvalid", isSignal: true, isRequired: false, transformFunction: null } }, providers: [provideIcons({ lucideChevronDown })], ngImport: i0, template: `
     <button
       brnComboboxTrigger
       brnComboboxAnchor
@@ -522,6 +534,8 @@ class HlmComboboxTrigger {
       hlmBtn
       data-slot="combobox-trigger"
       [id]="buttonId()"
+      [aria-describedby]="ariaDescribedBy()"
+      [attr.aria-required]="required() || null"
       [class]="_computedClass()"
       [variant]="variant()"
       [forceInvalid]="forceInvalid()"
@@ -554,6 +568,8 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.1.3", ngImpor
       hlmBtn
       data-slot="combobox-trigger"
       [id]="buttonId()"
+      [aria-describedby]="ariaDescribedBy()"
+      [attr.aria-required]="required() || null"
       [class]="_computedClass()"
       [variant]="variant()"
       [forceInvalid]="forceInvalid()"
@@ -563,7 +579,7 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.1.3", ngImpor
     </button>
   `,
                 }]
-        }], propDecorators: { userClass: [{ type: i0.Input, args: [{ isSignal: true, alias: "class", required: false }] }], buttonId: [{ type: i0.Input, args: [{ isSignal: true, alias: "buttonId", required: false }] }], variant: [{ type: i0.Input, args: [{ isSignal: true, alias: "variant", required: false }] }], forceInvalid: [{ type: i0.Input, args: [{ isSignal: true, alias: "forceInvalid", required: false }] }] } });
+        }], propDecorators: { userClass: [{ type: i0.Input, args: [{ isSignal: true, alias: "class", required: false }] }], buttonId: [{ type: i0.Input, args: [{ isSignal: true, alias: "buttonId", required: false }] }], ariaDescribedBy: [{ type: i0.Input, args: [{ isSignal: true, alias: "aria-describedby", required: false }] }], required: [{ type: i0.Input, args: [{ isSignal: true, alias: "required", required: false }] }], variant: [{ type: i0.Input, args: [{ isSignal: true, alias: "variant", required: false }] }], forceInvalid: [{ type: i0.Input, args: [{ isSignal: true, alias: "forceInvalid", required: false }] }] } });
 
 class HlmComboboxValue {
     constructor() {

package/combobox/types/combobox.d.ts

@@ -55,6 +55,9 @@ declare class HlmComboboxInput {
     private static _id;
     readonly inputId: i0.InputSignal<string>;
     readonly placeholder: i0.InputSignal<string>;
+    /** Native input description IDs, merged with enclosing Spartan field descriptions. */
+    readonly ariaDescribedBy: i0.InputSignal<string | null>;
+    readonly ariaLabelledBy: i0.InputSignal<string | null>;
     readonly showTrigger: i0.InputSignalWithTransform<boolean, BooleanInput>;
     readonly showClear: i0.InputSignalWithTransform<boolean, BooleanInput>;
     readonly forceInvalid: i0.InputSignalWithTransform<boolean, BooleanInput>;
@@ -62,7 +65,7 @@ declare class HlmComboboxInput {
     readonly ariaInvalidOverride: i0.InputSignalWithTransform<boolean | undefined, BooleanInput>;
     constructor();
     static ɵfac: i0.ɵɵFactoryDeclaration<HlmComboboxInput, never>;
-    static ɵcmp: i0.ɵɵComponentDeclaration<HlmComboboxInput, "hlm-combobox-input", never, { "inputId": { "alias": "inputId"; "required": false; "isSignal": true; }; "placeholder": { "alias": "placeholder"; "required": false; "isSignal": true; }; "showTrigger": { "alias": "showTrigger"; "required": false; "isSignal": true; }; "showClear": { "alias": "showClear"; "required": false; "isSignal": true; }; "forceInvalid": { "alias": "forceInvalid"; "required": false; "isSignal": true; }; "ariaInvalidOverride": { "alias": "aria-invalid"; "required": false; "isSignal": true; }; }, {}, never, ["*"], true, [{ directive: typeof i1.BrnComboboxAnchor; inputs: {}; outputs: {}; }, { directive: typeof i2$1.HlmInputGroup; inputs: {}; outputs: {}; }]>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<HlmComboboxInput, "hlm-combobox-input", never, { "inputId": { "alias": "inputId"; "required": false; "isSignal": true; }; "placeholder": { "alias": "placeholder"; "required": false; "isSignal": true; }; "ariaDescribedBy": { "alias": "aria-describedby"; "required": false; "isSignal": true; }; "ariaLabelledBy": { "alias": "aria-labelledby"; "required": false; "isSignal": true; }; "showTrigger": { "alias": "showTrigger"; "required": false; "isSignal": true; }; "showClear": { "alias": "showClear"; "required": false; "isSignal": true; }; "forceInvalid": { "alias": "forceInvalid"; "required": false; "isSignal": true; }; "ariaInvalidOverride": { "alias": "aria-invalid"; "required": false; "isSignal": true; }; }, {}, never, ["*"], true, [{ directive: typeof i1.BrnComboboxAnchor; inputs: {}; outputs: {}; }, { directive: typeof i2$1.HlmInputGroup; inputs: {}; outputs: {}; }]>;
 }
 
 declare class HlmComboboxItem {
@@ -119,10 +122,13 @@ declare class HlmComboboxTrigger {
     readonly userClass: i0.InputSignal<ClassValue>;
     protected readonly _computedClass: i0.Signal<string>;
     readonly buttonId: i0.InputSignal<string>;
+    /** Native button description IDs, merged with enclosing Spartan field descriptions. */
+    readonly ariaDescribedBy: i0.InputSignal<string | null>;
+    readonly required: i0.InputSignalWithTransform<boolean, BooleanInput>;
     readonly variant: i0.InputSignal<"default" | "primary" | "secondary" | "success" | "warning" | "danger" | "info" | "light" | "dark" | "accent" | "destructive" | "muted" | "outline" | "link" | "ghost" | null | undefined>;
     readonly forceInvalid: i0.InputSignalWithTransform<boolean, BooleanInput>;
     static ɵfac: i0.ɵɵFactoryDeclaration<HlmComboboxTrigger, never>;
-    static ɵcmp: i0.ɵɵComponentDeclaration<HlmComboboxTrigger, "hlm-combobox-trigger", never, { "userClass": { "alias": "class"; "required": false; "isSignal": true; }; "buttonId": { "alias": "buttonId"; "required": false; "isSignal": true; }; "variant": { "alias": "variant"; "required": false; "isSignal": true; }; "forceInvalid": { "alias": "forceInvalid"; "required": false; "isSignal": true; }; }, {}, never, ["*"], true, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<HlmComboboxTrigger, "hlm-combobox-trigger", never, { "userClass": { "alias": "class"; "required": false; "isSignal": true; }; "buttonId": { "alias": "buttonId"; "required": false; "isSignal": true; }; "ariaDescribedBy": { "alias": "aria-describedby"; "required": false; "isSignal": true; }; "required": { "alias": "required"; "required": false; "isSignal": true; }; "variant": { "alias": "variant"; "required": false; "isSignal": true; }; "forceInvalid": { "alias": "forceInvalid"; "required": false; "isSignal": true; }; }, {}, never, ["*"], true, never>;
 }
 
 declare class HlmComboboxValue {

package/data-table/README.md

@@ -108,12 +108,14 @@ export class ServerPaymentsComponent {
   [gridColumns]="gridColumns"
   [data]="payments()"
   [enableSelection]="true"
+  [getRowId]="paymentId"
   [(layout)]="layout"
   (selectionChange)="onSelect($event)"
 />
 ```
 
 - `enableSelection` auto-prepends a checkbox column; `selectionChange` emits the selected rows.
+- Define `readonly paymentId = (payment: Payment): string => payment.id` on the host. `getRowId` is a pure callback returning a unique, stable string per entity; keep the callback reference stable.
 - `[(layout)]` toggles `'table' | 'grid'` (grid requires `gridColumns`). Column `meta: { hideInTable: true }` hides a column in table layout; `meta: { thumbnail: true }` renders it as the card banner.
 - Sortable plain-string headers get an inline sort button; richer headers should use `EgDataTableColumnHeader` via `flexRenderComponent` (no type arguments needed — its `column` input accepts any TanStack column through the `EgSortableColumn` structural type):
 
@@ -126,6 +128,14 @@ helper.accessor('email', {
 });
 ```
 
+### Selection identity and scope
+
+- **Stable IDs:** supply `getRowId` whenever rows can be refreshed, reordered, or fetched from a server. Selection follows IDs still present in the supplied rows, and refreshes emit the current objects, not stale snapshots. Removed IDs are discarded and are not selected if they later return. Changing the callback clears selection.
+- **Server pages:** selection is scoped to the loaded slice, not an accumulated cross-page bulk-action set. Replacing a page keeps only selected IDs also in the new slice. Refreshing the same slice preserves selection when IDs match. Passing `null` or an empty slice clears it; keep the current slice and set `isLoading` if selection should survive loading a refresh.
+- **Client filtering/paging:** `filterRows` defines the available selection scope; removing a row there discards its selection. Built-in column filters and client pagination only hide rows: hidden selections remain in `selectionChange`. Header selection toggles only the displayed page; table and grid share selection. The footer selection count describes the filtered subset.
+- **Without `getRowId`:** existing positional `initialRowSelection` keys (`'0'`, `'1'`, etc.) remain supported for the initial rows. Replacing the source array (including a same-record refresh) or changing the `filterRows` result array clears selection rather than transferring an index to a different entity. Built-in sorting/filtering/paging with the same source array preserves it. This intentionally tightens the former unsafe positional behavior.
+- **Updates and outputs:** update row arrays/objects immutably; in-place mutations are not tracked. `initialRowSelection` seeds only IDs present on initialization; later seed changes are ignored. `selectionChange` fires once on initialization, then when the selected objects or their source order change, including removal and refreshed object references. Unchanged selections do not re-emit for sorting, layout, or other unrelated state changes. IDs must be unique and must not be reused for different entities.
+
 ## API reference
 
 | Symbol                                               | Kind                                                                                                       |