@egose/shadcn-theme-ng-tw 0.1.0 → 0.3.0

package/native-select/README.md

@@ -1,11 +1,329 @@
-# NativeSelect
+# Native Select (`@egose/shadcn-theme-ng/native-select`)
 
-This project was generated using [Angular CLI](https://github.com/angular/angular-cli).
+Zero-dependency HTML `<select>` with shadcn styling (shadcn/ui `native-select` equivalent). No overlay, no CDK menu, no listbox emulation — a real `<select>` inside a positioning wrapper with a chevron icon, wired as an Angular `ControlValueAccessor` and a spartan-ng `BrnFieldControl`/`BrnLabelable` so it participates in `formControl`/`ngModel`, `hlm-label` association, and field error states.
 
-## Building
+Ships as `@egose/shadcn-theme-ng/native-select` and `@egose/shadcn-theme-ng-tw/native-select` (tw: variant). See the [package README](../../README.md) for installation, peer dependencies, Tailwind setup, and testing. Do not publish this project directory independently.
 
-To build the library, run:
+## Installation
 
 ```bash
-ng build native-select
+# Plain Tailwind (no prefix):
+npm install @egose/shadcn-theme-ng
+
+# Or the tw:-prefixed variant:
+npm install @egose/shadcn-theme-ng-tw
+```
+
+Peer dependencies are inherited from the package root (see [package README](../../README.md)). This subpath itself declares `@angular/common`, `@angular/core`, `@spartan-ng/brain` as peers plus a `tslib` runtime dependency; at runtime it also uses `@ng-icons/lucide` (`lucideChevronDown`), `@spartan-ng/brain/field`, and `@spartan-ng/brain/forms` types. No extra install step is needed beyond the package install above.
+
+## Imports
+
+Real exported symbols (from `src/public-api.ts`):
+
+```ts
+import {
+  HlmNativeSelect, // component: hlm-native-select (CVA)
+  HlmNativeSelectOption, // directive: option[hlmNativeSelectOption]
+  HlmNativeSelectOptGroup, // directive: optgroup[hlmNativeSelectOptGroup]
+  HLM_NATIVE_SELECT_VALUE_ACCESSOR, // NG_VALUE_ACCESSOR provider const
+  HlmNativeSelectImports, // readonly [HlmNativeSelect, HlmNativeSelectOption, HlmNativeSelectOptGroup]
+  HlmNativeSelectModule, // NgModule wrapping HlmNativeSelectImports
+} from '@egose/shadcn-theme-ng/native-select';
+```
+
+Standalone usage:
+
+```ts
+import { Component } from '@angular/core';
+import { HlmNativeSelectImports } from '@egose/shadcn-theme-ng/native-select';
+
+@Component({
+  selector: 'app-demo',
+  standalone: true,
+  imports: [...HlmNativeSelectImports],
+  template: `
+    <hlm-native-select>
+      <option hlmNativeSelectOption value="apple">Apple</option>
+    </hlm-native-select>
+  `,
+})
+export class DemoComponent {}
+```
+
+NgModule usage:
+
+```ts
+import { NgModule } from '@angular/core';
+import { HlmNativeSelectModule } from '@egose/shadcn-theme-ng/native-select';
+
+@NgModule({ imports: [HlmNativeSelectModule] })
+export class DemoModule {}
+```
+
+For the `tw:` build, swap the specifier to `@egose/shadcn-theme-ng-tw/native-select`. Symbol names are identical.
+
+## Anatomy / Structure
+
+```html
+<hlm-native-select>
+  <option hlmNativeSelectOption value="">Choose a fruit…</option>
+  <optgroup hlmNativeSelectOptGroup label="Citrus">
+    <option hlmNativeSelectOption value="orange">Orange</option>
+    <option hlmNativeSelectOption value="lemon">Lemon</option>
+  </optgroup>
+  <option hlmNativeSelectOption value="apple">Apple</option>
+</hlm-native-select>
+
+<!-- sizes + classes -->
+<hlm-native-select size="sm" selectClass="tw:w-48" selectIconClass="tw:text-primary">
+  <option hlmNativeSelectOption value="s">Small</option>
+</hlm-native-select>
+```
+
+Rendered DOM: the host (`data-slot="native-select-wrapper"`, `group/native-select relative w-fit`) projects your options into an inner native `<select data-slot="native-select">` plus an absolutely-positioned `lucideChevronDown` icon (`data-slot="native-select-icon"`). The inner select carries `data-size`, `data-invalid`, `data-dirty`, `data-touched`, and `data-matches-spartan-invalid` attributes for styling hooks.
+
+| Class                     | Selector                            | Role                                                                                       |
+| ------------------------- | ----------------------------------- | ------------------------------------------------------------------------------------------ |
+| `HlmNativeSelect`         | `hlm-native-select`                 | Wrapper + CVA + chevron                                                                    |
+| `HlmNativeSelectOption`   | `option[hlmNativeSelectOption]`     | Styled `<option>` (`bg-[Canvas] text-[CanvasText]` so dropdown lists stay native-readable) |
+| `HlmNativeSelectOptGroup` | `optgroup[hlmNativeSelectOptGroup]` | Styled `<optgroup>` (same Canvas treatment)                                                |
+
+## API reference
+
+### `HlmNativeSelect` (`hlm-native-select`, implements `ControlValueAccessor`)
+
+| Member                                           | Kind          | Type / Default                          | Notes                                                                                             |
+| ------------------------------------------------ | ------------- | --------------------------------------- | ------------------------------------------------------------------------------------------------- |
+| `selectId`                                       | input         | `string`, auto `hlm-native-select-${n}` | Applied as the inner `<select>`'s `id`; also exposed as `labelableId` for `hlm-label` association |
+| `selectClass`                                    | input         | `ClassValue`, `''`                      | Merged over the inner select classes                                                              |
+| `selectIconClass`                                | input         | `ClassValue`, `''`                      | Merged over the chevron icon classes                                                              |
+| `size`                                           | input         | `'sm' \| 'default'`, `'default'`        | Reflected as `data-size` on host + select; `sm` → `h-8` instead of `h-9`                          |
+| `disabled`                                       | input         | `boolean`, `false` (boolean coercion)   | Initial disabled; reactive forms override via `setDisabledState` into `_disabled` linked signal   |
+| `forceInvalid`                                   | input         | `boolean`, `false` (boolean coercion)   | Forces `data-matches-spartan-invalid` styling                                                     |
+| `ariaInvalidOverride` (alias `aria-invalid`)     | input         | `boolean \| undefined`, `undefined`     | Manual `aria-invalid`; defaults to the parent `BrnFieldControl.invalid` state                     |
+| `valueInput` (alias `value`)                     | input         | `string \| undefined \| null`, `''`     | One-way value; mirrored into the `value` linked signal                                            |
+| `value`                                          | linked signal | `string \| undefined \| null`           | Current value; bound to the select's `[value]`                                                    |
+| `valueChange`                                    | output        | `string \| undefined \| null`           | Emitted on native `change` alongside the CVA callback                                             |
+| `labelableId`                                    | property      | = `selectId`                            | `BrnLabelable` contract for label association                                                     |
+| `writeValue(v)`                                  | CVA method    |                                         | Sets `value`                                                                                      |
+| `registerOnChange(fn)` / `registerOnTouched(fn)` | CVA methods   |                                         | Stored as `_onChange` / `_onTouched`; invoked on `change` / `change`+`blur`                       |
+| `setDisabledState(isDisabled)`                   | CVA method    |                                         | Sets `_disabled`                                                                                  |
+
+Host directives: `BrnFieldControl` (provides `invalid`/`touched`/`dirty`/`spartanInvalid` read by the template). Providers: `NG_VALUE_ACCESSOR` (`HLM_NATIVE_SELECT_VALUE_ACCESSOR`), `provideIcons({ lucideChevronDown })`, `provideBrnLabelable(HlmNativeSelect)`.
+
+### `HlmNativeSelectOption` / `HlmNativeSelectOptGroup`
+
+No inputs/outputs/methods. Pure styling directives setting `data-slot` (`native-select-option` / `native-select-optgroup`).
+
+## Examples
+
+### 1. Basic uncontrolled select
+
+```ts
+import { Component } from '@angular/core';
+import { HlmNativeSelectImports } from '@egose/shadcn-theme-ng/native-select';
+
+@Component({
+  selector: 'app-native-basic',
+  standalone: true,
+  imports: [...HlmNativeSelectImports],
+  template: `
+    <hlm-native-select (valueChange)="onChange($event)">
+      <option hlmNativeSelectOption value="">Choose a fruit…</option>
+      <option hlmNativeSelectOption value="apple">Apple</option>
+      <option hlmNativeSelectOption value="banana">Banana</option>
+    </hlm-native-select>
+    <p class="tw:text-sm tw:text-muted-foreground">Picked: {{ picked ?? 'nothing' }}</p>
+  `,
+})
+export class NativeBasicComponent {
+  picked: string | null | undefined;
+
+  onChange(value: string | null | undefined): void {
+    this.picked = value;
+  }
+}
 ```
+
+### 2. Sizes and optgroups
+
+```ts
+import { Component } from '@angular/core';
+import { HlmNativeSelectImports } from '@egose/shadcn-theme-ng/native-select';
+
+@Component({
+  selector: 'app-native-groups',
+  standalone: true,
+  imports: [...HlmNativeSelectImports],
+  template: `
+    <div class="tw:flex tw:flex-col tw:gap-4 tw:max-w-xs">
+      <hlm-native-select size="sm">
+        <option hlmNativeSelectOption value="s">Small</option>
+        <option hlmNativeSelectOption value="m">Medium</option>
+      </hlm-native-select>
+
+      <hlm-native-select size="default">
+        <option hlmNativeSelectOption value="">Choose a citrus…</option>
+        <optgroup hlmNativeSelectOptGroup label="Citrus">
+          <option hlmNativeSelectOption value="orange">Orange</option>
+          <option hlmNativeSelectOption value="lemon">Lemon</option>
+        </optgroup>
+        <optgroup hlmNativeSelectOptGroup label="Berries">
+          <option hlmNativeSelectOption value="strawberry">Strawberry</option>
+          <option hlmNativeSelectOption value="blueberry">Blueberry</option>
+        </optgroup>
+      </hlm-native-select>
+    </div>
+  `,
+})
+export class NativeGroupsComponent {}
+```
+
+### 3. Reactive form + label
+
+```ts
+import { Component } from '@angular/core';
+import { ReactiveFormsModule, FormControl, FormGroup, Validators } from '@angular/forms';
+import { HlmNativeSelectImports } from '@egose/shadcn-theme-ng/native-select';
+import { HlmLabelImports } from '@egose/shadcn-theme-ng/label';
+
+@Component({
+  selector: 'app-native-reactive',
+  standalone: true,
+  imports: [ReactiveFormsModule, ...HlmNativeSelectImports, ...HlmLabelImports],
+  template: `
+    <form [formGroup]="form" class="tw:grid tw:gap-1.5 tw:max-w-xs">
+      <label hlmLabel for="country">Country</label>
+      <hlm-native-select selectId="country" formControlName="country">
+        <option hlmNativeSelectOption value="">Select…</option>
+        <option hlmNativeSelectOption value="de">Germany</option>
+        <option hlmNativeSelectOption value="fr">France</option>
+        <option hlmNativeSelectOption value="jp">Japan</option>
+      </hlm-native-select>
+      @if (form.controls.country.touched && form.controls.country.invalid) {
+        <p class="tw:text-sm tw:text-destructive">Country is required.</p>
+      }
+      <button type="button" (click)="disable()">Toggle disabled</button>
+    </form>
+  `,
+})
+export class NativeReactiveComponent {
+  readonly form = new FormGroup({
+    country: new FormControl('', { validators: [Validators.required], nonNullable: true }),
+  });
+
+  disable(): void {
+    const c = this.form.controls.country;
+    c.disabled ? c.enable() : c.disable();
+  }
+}
+```
+
+### 4. Template-driven (`ngModel`) + two-way `value`
+
+```ts
+import { Component } from '@angular/core';
+import { FormsModule } from '@angular/forms';
+import { HlmNativeSelectImports } from '@egose/shadcn-theme-ng/native-select';
+
+@Component({
+  selector: 'app-native-ngmodel',
+  standalone: true,
+  imports: [FormsModule, ...HlmNativeSelectImports],
+  template: `
+    <hlm-native-select [(ngModel)]="flavor">
+      <option hlmNativeSelectOption value="vanilla">Vanilla</option>
+      <option hlmNativeSelectOption value="chocolate">Chocolate</option>
+      <option hlmNativeSelectOption value="mint">Mint</option>
+    </hlm-native-select>
+    <p class="tw:text-sm">Flavor: {{ flavor }}</p>
+
+    <!-- one-way value input + valueChange output (no forms): -->
+    <hlm-native-select [value]="flavor" (valueChange)="flavor = $event ?? ''">
+      <option hlmNativeSelectOption value="vanilla">Vanilla</option>
+      <option hlmNativeSelectOption value="chocolate">Chocolate</option>
+    </hlm-native-select>
+  `,
+})
+export class NativeNgModelComponent {
+  flavor = 'vanilla';
+}
+```
+
+### 5. Async options, invalid, and disabled states
+
+```ts
+import { Component, signal, OnInit } from '@angular/core';
+import { HlmNativeSelectImports } from '@egose/shadcn-theme-ng/native-select';
+
+@Component({
+  selector: 'app-native-async',
+  standalone: true,
+  imports: [...HlmNativeSelectImports],
+  template: `
+    <div class="tw:grid tw:gap-4 tw:max-w-xs">
+      <hlm-native-select [value]="selected()" (valueChange)="selected.set($event ?? '')">
+        <option hlmNativeSelectOption value="">Loading…</option>
+        @for (c of cities(); track c) {
+          <option hlmNativeSelectOption [value]="c">{{ c }}</option>
+        }
+      </hlm-native-select>
+
+      <hlm-native-select [forceInvalid]="true" value="bad">
+        <option hlmNativeSelectOption value="bad">Forced invalid</option>
+        <option hlmNativeSelectOption value="good">Good</option>
+      </hlm-native-select>
+
+      <hlm-native-select [disabled]="true" value="locked">
+        <option hlmNativeSelectOption value="locked">Disabled</option>
+      </hlm-native-select>
+    </div>
+  `,
+})
+export class NativeAsyncComponent implements OnInit {
+  readonly cities = signal<string[]>([]);
+  readonly selected = signal('');
+
+  async ngOnInit(): Promise<void> {
+    await new Promise((r) => setTimeout(r, 300));
+    this.cities.set(['Berlin', 'Paris', 'Tokyo']);
+  }
+}
+```
+
+### 6. Custom widths and icon tint
+
+```ts
+import { Component } from '@angular/core';
+import { HlmNativeSelectImports } from '@egose/shadcn-theme-ng/native-select';
+
+@Component({
+  selector: 'app-native-styled',
+  standalone: true,
+  imports: [...HlmNativeSelectImports],
+  template: `
+    <hlm-native-select selectClass="tw:w-56" selectIconClass="tw:text-primary" size="sm">
+      <option hlmNativeSelectOption value="a">Compact tinted chevron</option>
+      <option hlmNativeSelectOption value="b">Option B</option>
+    </hlm-native-select>
+  `,
+})
+export class NativeStyledComponent {}
+```
+
+## Accessibility notes
+
+- A native `<select>` gives you listbox semantics, keyboard support (arrows/typeahead), and mobile pickers for free — prefer it over a custom dropdown when the option list is simple.
+- Associate with `<label hlmLabel for="…">` matching `selectId` (or nest contextually); invalid state flows to `aria-invalid` automatically via `BrnFieldControl` unless overridden with `aria-invalid`.
+- Keep the first `<option>` a real placeholder with `value=""` when a choice is required, and validate accordingly.
+- `forceInvalid` is visual + `data-*` styling; still set form errors so screen readers announce the problem.
+
+## Theming / CSS variables
+
+No theming inputs. The select uses `border-input`, `ring-ring`, `bg-muted`-adjacent tokens with dark-mode (`dark:bg-input/30`) and invalid (`border-destructive ring-destructive`) treatments. Extend via `selectClass` / `selectIconClass` (merged after base classes).
+
+## Related subpaths
+
+- `@egose/shadcn-theme-ng/select` — custom overlay select for searchable/rich options; use native-select when a plain `<select>` suffices.
+- `@egose/shadcn-theme-ng/label` — label association via `selectId`/`labelableId`.
+- `@egose/shadcn-theme-ng/form-field` — field wrapper with error display that reads the same `BrnFieldControl` state.

package/native-select/fesm2022/native-select.mjs

@@ -1,5 +1,5 @@
 import * as i0 from '@angular/core';
-import { forwardRef, inject, input, computed, booleanAttribute, linkedSignal, output, ChangeDetectionStrategy, Component, Directive, NgModule } from '@angular/core';
+import { forwardRef, inject, input, computed, booleanAttribute, signal, linkedSignal, output, ChangeDetectionStrategy, Component, Directive, NgModule } from '@angular/core';
 import { NG_VALUE_ACCESSOR } from '@angular/forms';
 import { NgIcon, provideIcons } from '@ng-icons/core';
 import { lucideChevronDown } from '@ng-icons/lucide';
@@ -17,9 +17,15 @@ class HlmNativeSelect {
     static _id = 0;
     selectId = input(`hlm-native-select-${HlmNativeSelect._id++}`, /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "selectId" }] : /* istanbul ignore next */ []));
+    /** Native `name` attribute forwarded to the inner `<select>`. */
+    name = input(undefined, /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "name" }] : /* istanbul ignore next */ []));
+    /** ID of the element describing the select (error/hint) for assistive tech. */
+    ariaDescribedby = input(null, /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "ariaDescribedby" }] : /* istanbul ignore next */ []));
     selectClass = input('', /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "selectClass" }] : /* istanbul ignore next */ []));
-    _computedSelectClass = computed(() => hlm('tw:border-input tw:placeholder:text-muted-foreground tw:selection:bg-primary tw:selection:text-primary-foreground tw:dark:bg-input/30 tw:dark:hover:bg-input/50 tw:focus-visible:border-ring tw:focus-visible:ring-ring/50 tw:data-[matches-spartan-invalid=true]:ring-destructive/20 tw:dark:data-[matches-spartan-invalid=true]:ring-destructive/40 tw:data-[matches-spartan-invalid=true]:border-destructive tw:dark:data-[matches-spartan-invalid=true]:border-destructive/50 tw:h-9 tw:w-full tw:min-w-0 tw:appearance-none tw:rounded-md tw:border tw:bg-transparent tw:py-1 tw:ps-2.5 tw:pe-8 tw:text-sm tw:shadow-xs tw:transition-[color,box-shadow] tw:select-none tw:focus-visible:ring-3 tw:data-[matches-spartan-invalid=true]:ring-3 tw:data-[size=sm]:h-8 tw:outline-none tw:disabled:pointer-events-none tw:disabled:cursor-not-allowed', this.selectClass()), /* @ts-ignore */
+    _computedSelectClass = computed(() => hlm('tw:border-input tw:placeholder:text-muted-foreground tw:selection:bg-primary tw:selection:text-primary-foreground tw:dark:bg-input/30 tw:dark:hover:bg-input/50 tw:focus-visible:border-ring tw:focus-visible:ring-ring/50 tw:data-[matches-spartan-invalid=true]:ring-destructive/20 tw:dark:data-[matches-spartan-invalid=true]:ring-destructive/40 tw:data-[matches-spartan-invalid=true]:border-destructive tw:dark:data-[matches-spartan-invalid=true]:border-destructive/50 tw:h-9 tw:w-full tw:min-w-0 tw:appearance-none tw:rounded-md tw:border tw:bg-transparent tw:py-1 tw:ps-2.5 tw:pe-8 tw:text-sm tw:text-foreground tw:shadow-xs tw:transition-[color,box-shadow] tw:select-none tw:focus-visible:ring-3 tw:data-[matches-spartan-invalid=true]:ring-3 tw:data-[size=sm]:h-8 tw:outline-none tw:disabled:pointer-events-none tw:disabled:cursor-not-allowed tw:[color-scheme:light] tw:dark:[color-scheme:dark]', this.selectClass()), /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "_computedSelectClass" }] : /* istanbul ignore next */ []));
     selectIconClass = input('', /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "selectIconClass" }] : /* istanbul ignore next */ []));
@@ -28,7 +34,9 @@ class HlmNativeSelect {
     size = input('default', /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "size" }] : /* istanbul ignore next */ []));
     disabled = input(false, { ...(ngDevMode ? { debugName: "disabled" } : /* istanbul ignore next */ {}), transform: booleanAttribute });
-    _disabled = linkedSignal(this.disabled, /* @ts-ignore */
+    _formDisabled = signal(false, /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "_formDisabled" }] : /* istanbul ignore next */ []));
+    _disabled = computed(() => this.disabled() || this._formDisabled(), /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "_disabled" }] : /* istanbul ignore next */ []));
     /** Whether to force the input into an invalid state. */
     forceInvalid = input(false, { ...(ngDevMode ? { debugName: "forceInvalid" } : /* istanbul ignore next */ {}), transform: booleanAttribute });
@@ -73,10 +81,10 @@ class HlmNativeSelect {
         this._onTouched = fn;
     }
     setDisabledState(isDisabled) {
-        this._disabled.set(isDisabled);
+        this._formDisabled.set(isDisabled);
     }
     static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "22.1.3", ngImport: i0, type: HlmNativeSelect, deps: [], target: i0.ɵɵFactoryTarget.Component });
-    static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.1.0", version: "22.1.3", type: HlmNativeSelect, isStandalone: true, selector: "hlm-native-select", inputs: { selectId: { classPropertyName: "selectId", publicName: "selectId", isSignal: true, isRequired: false, transformFunction: null }, selectClass: { classPropertyName: "selectClass", publicName: "selectClass", isSignal: true, isRequired: false, transformFunction: null }, selectIconClass: { classPropertyName: "selectIconClass", publicName: "selectIconClass", isSignal: true, isRequired: false, transformFunction: null }, size: { classPropertyName: "size", publicName: "size", isSignal: true, isRequired: false, transformFunction: null }, disabled: { classPropertyName: "disabled", publicName: "disabled", 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 }, valueInput: { classPropertyName: "valueInput", publicName: "value", isSignal: true, isRequired: false, transformFunction: null } }, outputs: { valueChange: "valueChange" }, host: { attributes: { "data-slot": "native-select-wrapper" }, properties: { "attr.data-size": "size()" } }, providers: [
+    static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.1.0", version: "22.1.3", type: HlmNativeSelect, isStandalone: true, selector: "hlm-native-select", inputs: { selectId: { classPropertyName: "selectId", publicName: "selectId", isSignal: true, isRequired: false, transformFunction: null }, name: { classPropertyName: "name", publicName: "name", isSignal: true, isRequired: false, transformFunction: null }, ariaDescribedby: { classPropertyName: "ariaDescribedby", publicName: "ariaDescribedby", isSignal: true, isRequired: false, transformFunction: null }, selectClass: { classPropertyName: "selectClass", publicName: "selectClass", isSignal: true, isRequired: false, transformFunction: null }, selectIconClass: { classPropertyName: "selectIconClass", publicName: "selectIconClass", isSignal: true, isRequired: false, transformFunction: null }, size: { classPropertyName: "size", publicName: "size", isSignal: true, isRequired: false, transformFunction: null }, disabled: { classPropertyName: "disabled", publicName: "disabled", 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 }, valueInput: { classPropertyName: "valueInput", publicName: "value", isSignal: true, isRequired: false, transformFunction: null } }, outputs: { valueChange: "valueChange" }, host: { attributes: { "data-slot": "native-select-wrapper" }, properties: { "attr.data-size": "size()" } }, providers: [
             HLM_NATIVE_SELECT_VALUE_ACCESSOR,
             provideIcons({ lucideChevronDown }),
             provideBrnLabelable(HlmNativeSelect),
@@ -84,6 +92,8 @@ class HlmNativeSelect {
     <select
       data-slot="native-select"
       [id]="selectId()"
+      [attr.name]="name()"
+      [attr.aria-describedby]="ariaDescribedby()"
       [class]="_computedSelectClass()"
       [attr.data-size]="size()"
       [attr.aria-invalid]="_ariaInvalid() ? 'true' : null"
@@ -127,6 +137,8 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.1.3", ngImpor
     <select
       data-slot="native-select"
       [id]="selectId()"
+      [attr.name]="name()"
+      [attr.aria-describedby]="ariaDescribedby()"
       [class]="_computedSelectClass()"
       [attr.data-size]="size()"
       [attr.aria-invalid]="_ariaInvalid() ? 'true' : null"
@@ -150,7 +162,7 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.1.3", ngImpor
     />
   `,
                 }]
-        }], ctorParameters: () => [], propDecorators: { selectId: [{ type: i0.Input, args: [{ isSignal: true, alias: "selectId", required: false }] }], selectClass: [{ type: i0.Input, args: [{ isSignal: true, alias: "selectClass", required: false }] }], selectIconClass: [{ type: i0.Input, args: [{ isSignal: true, alias: "selectIconClass", required: false }] }], size: [{ type: i0.Input, args: [{ isSignal: true, alias: "size", required: false }] }], disabled: [{ type: i0.Input, args: [{ isSignal: true, alias: "disabled", 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 }] }], valueInput: [{ type: i0.Input, args: [{ isSignal: true, alias: "value", required: false }] }], valueChange: [{ type: i0.Output, args: ["valueChange"] }] } });
+        }], ctorParameters: () => [], propDecorators: { selectId: [{ type: i0.Input, args: [{ isSignal: true, alias: "selectId", required: false }] }], name: [{ type: i0.Input, args: [{ isSignal: true, alias: "name", required: false }] }], ariaDescribedby: [{ type: i0.Input, args: [{ isSignal: true, alias: "ariaDescribedby", required: false }] }], selectClass: [{ type: i0.Input, args: [{ isSignal: true, alias: "selectClass", required: false }] }], selectIconClass: [{ type: i0.Input, args: [{ isSignal: true, alias: "selectIconClass", required: false }] }], size: [{ type: i0.Input, args: [{ isSignal: true, alias: "size", required: false }] }], disabled: [{ type: i0.Input, args: [{ isSignal: true, alias: "disabled", 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 }] }], valueInput: [{ type: i0.Input, args: [{ isSignal: true, alias: "value", required: false }] }], valueChange: [{ type: i0.Output, args: ["valueChange"] }] } });
 
 class HlmNativeSelectOptGroup {
     constructor() {

package/native-select/types/native-select.d.ts

@@ -14,13 +14,18 @@ declare class HlmNativeSelect implements ControlValueAccessor {
     private readonly _fieldControl;
     private static _id;
     readonly selectId: _angular_core.InputSignal<string>;
+    /** Native `name` attribute forwarded to the inner `<select>`. */
+    readonly name: _angular_core.InputSignal<string | undefined>;
+    /** ID of the element describing the select (error/hint) for assistive tech. */
+    readonly ariaDescribedby: _angular_core.InputSignal<string | null>;
     readonly selectClass: _angular_core.InputSignal<ClassValue>;
     protected readonly _computedSelectClass: _angular_core.Signal<string>;
     readonly selectIconClass: _angular_core.InputSignal<ClassValue>;
     protected readonly _computedSelectIconClass: _angular_core.Signal<string>;
     readonly size: _angular_core.InputSignal<"sm" | "default">;
     readonly disabled: _angular_core.InputSignalWithTransform<boolean, BooleanInput>;
-    protected readonly _disabled: _angular_core.WritableSignal<boolean>;
+    private readonly _formDisabled;
+    protected readonly _disabled: _angular_core.Signal<boolean>;
     /** Whether to force the input into an invalid state. */
     readonly forceInvalid: _angular_core.InputSignalWithTransform<boolean, BooleanInput>;
     /** Manual override for aria-invalid. When not set, auto-detects from the parent autocomplete error state. */
@@ -45,7 +50,7 @@ declare class HlmNativeSelect implements ControlValueAccessor {
     registerOnTouched(fn: TouchFn): void;
     setDisabledState(isDisabled: boolean): void;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<HlmNativeSelect, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<HlmNativeSelect, "hlm-native-select", never, { "selectId": { "alias": "selectId"; "required": false; "isSignal": true; }; "selectClass": { "alias": "selectClass"; "required": false; "isSignal": true; }; "selectIconClass": { "alias": "selectIconClass"; "required": false; "isSignal": true; }; "size": { "alias": "size"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "forceInvalid": { "alias": "forceInvalid"; "required": false; "isSignal": true; }; "ariaInvalidOverride": { "alias": "aria-invalid"; "required": false; "isSignal": true; }; "valueInput": { "alias": "value"; "required": false; "isSignal": true; }; }, { "valueChange": "valueChange"; }, never, ["*"], true, [{ directive: typeof i1.BrnFieldControl; inputs: {}; outputs: {}; }]>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<HlmNativeSelect, "hlm-native-select", never, { "selectId": { "alias": "selectId"; "required": false; "isSignal": true; }; "name": { "alias": "name"; "required": false; "isSignal": true; }; "ariaDescribedby": { "alias": "ariaDescribedby"; "required": false; "isSignal": true; }; "selectClass": { "alias": "selectClass"; "required": false; "isSignal": true; }; "selectIconClass": { "alias": "selectIconClass"; "required": false; "isSignal": true; }; "size": { "alias": "size"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "forceInvalid": { "alias": "forceInvalid"; "required": false; "isSignal": true; }; "ariaInvalidOverride": { "alias": "aria-invalid"; "required": false; "isSignal": true; }; "valueInput": { "alias": "value"; "required": false; "isSignal": true; }; }, { "valueChange": "valueChange"; }, never, ["*"], true, [{ directive: typeof i1.BrnFieldControl; inputs: {}; outputs: {}; }]>;
 }
 
 declare class HlmNativeSelectOptGroup {