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

package/input/README.md

@@ -1,3 +1,270 @@
-# Input Subpath
+# Input (`@egose/shadcn-theme-ng/input`)
 
-This project ships only as `@egose/shadcn-theme-ng/input` or `@egose/shadcn-theme-ng-tw/input`. See the [package README](../../README.md) for installation, compatibility, Tailwind variant, test, and release guidance. Do not publish this project directory independently.
+`HlmInput` is a thin styling directive that gives any native `<input>` (or `<textarea>`) the shadcn/ui _Input_ look — the Angular counterpart of shadcn/ui's `<Input />`. Behavior comes from spartan-ng's `BrnInput` (plus field `aria-describedby` propagation); this directive adds the theme classes, `data-slot="input"`, invalid-state rings, and disabled/file styles.
+
+> **Ships as:** `@egose/shadcn-theme-ng/input` (plain Tailwind) and `@egose/shadcn-theme-ng-tw/input` (`tw:`-prefixed variant). See the [package README](../../README.md) for installation, peer dependencies, and the Tailwind-variant contract. Do not publish this project directory independently.
+
+## Installation
+
+```bash
+# Plain Tailwind (no prefix)
+npm install @egose/shadcn-theme-ng
+
+# Or the tw:-prefixed variant
+npm install @egose/shadcn-theme-ng-tw
+```
+
+Peer dependencies (Angular, `@angular/forms`, CDK, `@spartan-ng/brain`, `rxjs`) are documented in the [package README](../../README.md#peer-dependencies).
+
+```ts
+import { HlmInputImports } from '@egose/shadcn-theme-ng/input';
+// tw variant:
+// import { HlmInputImports } from '@egose/shadcn-theme-ng-tw/input';
+```
+
+## Imports
+
+```ts
+// Standalone component — spread the imports array:
+import { HlmInputImports } from '@egose/shadcn-theme-ng/input';
+
+@Component({
+  standalone: true,
+  imports: [ReactiveFormsModule, HlmInputImports],
+  template: `<input hlmInput formControlName="email" type="email" />`,
+})
+export class MyComp {}
+```
+
+```ts
+// NgModule-based — import the module:
+import { HlmInputModule } from '@egose/shadcn-theme-ng/input';
+
+@NgModule({ imports: [HlmInputModule] })
+export class MyModule {}
+```
+
+Exported from `src/public-api.ts`: `HlmInput`, plus `HlmInputImports` and `HlmInputModule`. Import the directive class directly (`import { HlmInput } from '…'`) when you only need the one symbol.
+
+## Anatomy / Structure
+
+```html
+<label for="email">Email</label> <input hlmInput id="email" type="email" placeholder="you@example.com" />
+```
+
+The directive matches `input[hlmInput]` usage in practice (selector `[hlmInput]`), sets `data-slot="input"`, binds `[attr.aria-describedby]` from its own input, and composes `BrnInput` (`id`, `forceInvalid`) + `BrnFieldControlDescribedBy` via `hostDirectives`. It is also the class hook reused by `textarea[hlmInput]` (see `form-textarea`) and by `input[hlmInputGroupInput]`.
+
+## API reference
+
+### `[hlmInput]` — `HlmInput`
+
+| Input             | Type             | Default | Description                                                                                                         |
+| ----------------- | ---------------- | ------- | ------------------------------------------------------------------------------------------------------------------- |
+| `ariaDescribedby` | `string \| null` | `null`  | Bound to `aria-describedby`. Combine with `<hlm-error>`/`<hlm-hint>` ids (the form wrappers do this automatically). |
+| `id`              | (via `BrnInput`) | —       | Forwarded to the `BrnInput` host directive.                                                                         |
+| `forceInvalid`    | (via `BrnInput`) | —       | Forwarded to the `BrnInput` host directive; forces the `data-matches-spartan-invalid` error styles.                 |
+
+No outputs. Visual states are attribute-driven: `data-matches-spartan-invalid=true` switches the border/ring to destructive; `disabled` applies `pointer-events-none`, `cursor-not-allowed`, `opacity-50`. Base geometry: `h-9`, `rounded-md`, `text-base` (`md:text-sm`), full width.
+
+## Examples
+
+### 1. Basic text + reactive form
+
+```ts
+import { Component } from '@angular/core';
+import { FormControl, FormGroup, ReactiveFormsModule } from '@angular/forms';
+import { HlmInputImports } from '@egose/shadcn-theme-ng/input';
+
+@Component({
+  standalone: true,
+  imports: [ReactiveFormsModule, HlmInputImports],
+  template: `
+    <form [formGroup]="form">
+      <label for="username">Username</label>
+      <input hlmInput id="username" formControlName="username" placeholder="jane_doe" />
+    </form>
+  `,
+})
+export class BasicExample {
+  readonly form = new FormGroup({
+    username: new FormControl<string>('', { nonNullable: true }),
+  });
+}
+```
+
+### 2. Template-driven with `ngModel`
+
+```ts
+import { Component } from '@angular/core';
+import { FormsModule } from '@angular/forms';
+import { HlmInput } from '@egose/shadcn-theme-ng/input';
+
+@Component({
+  standalone: true,
+  imports: [FormsModule, HlmInput],
+  template: `
+    <label for="nickname">Nickname</label>
+    <input hlmInput id="nickname" name="nickname" [(ngModel)]="nickname" placeholder="janey" />
+    <p>Hello, {{ nickname || 'stranger' }}!</p>
+  `,
+})
+export class NgModelExample {
+  nickname = '';
+}
+```
+
+### 3. Types: email, password, number, search, file
+
+```ts
+import { Component } from '@angular/core';
+import { HlmInputImports } from '@egose/shadcn-theme-ng/input';
+
+@Component({
+  standalone: true,
+  imports: [HlmInputImports],
+  template: `
+    <div class="tw:grid tw:gap-3">
+      <input hlmInput type="email" placeholder="Email" aria-label="Email" autocomplete="email" />
+      <input hlmInput type="password" placeholder="Password" aria-label="Password" autocomplete="current-password" />
+      <input hlmInput type="number" placeholder="0" aria-label="Amount" min="0" />
+      <input hlmInput type="search" placeholder="Search…" aria-label="Search" />
+      <input hlmInput type="file" aria-label="Upload avatar" />
+    </div>
+  `,
+})
+export class TypesExample {}
+```
+
+> File inputs inherit the directive's `file:` styles (sized button text, transparent track) — no extra markup needed.
+
+### 4. Disabled + invalid states
+
+```ts
+import { Component, signal } from '@angular/core';
+import { FormControl, FormGroup, ReactiveFormsModule, Validators } from '@angular/forms';
+import { HlmInput } from '@egose/shadcn-theme-ng/input';
+
+@Component({
+  standalone: true,
+  imports: [ReactiveFormsModule, HlmInput],
+  template: `
+    <form [formGroup]="form">
+      <input hlmInput formControlName="email" type="email" placeholder="you@example.com" aria-label="Email" />
+      @if (form.controls.email.invalid && form.controls.email.touched) {
+        <p class="tw:text-sm tw:text-red-600">Enter a valid email.</p>
+      }
+      <input hlmInput placeholder="Disabled field" aria-label="Disabled field" [disabled]="true" />
+      <!-- force the error ring regardless of touch state -->
+      <input hlmInput placeholder="Forced invalid" aria-label="Forced invalid" [forceInvalid]="true" />
+    </form>
+  `,
+})
+export class StatesExample {
+  readonly form = new FormGroup({
+    email: new FormControl<string>('', { nonNullable: true, validators: [Validators.email] }),
+  });
+}
+```
+
+### 5. Manual `aria-describedby` with hint + error (no form wrapper)
+
+```ts
+import { Component } from '@angular/core';
+import { FormControl, FormGroup, ReactiveFormsModule, Validators } from '@angular/forms';
+import { HlmInput } from '@egose/shadcn-theme-ng/input';
+import { HlmError, HlmHint } from '@egose/shadcn-theme-ng/form-field';
+
+@Component({
+  standalone: true,
+  imports: [ReactiveFormsModule, HlmInput, HlmError, HlmHint],
+  template: `
+    <form [formGroup]="form">
+      <label for="handle">Handle</label>
+      <input
+        hlmInput
+        id="handle"
+        formControlName="handle"
+        placeholder="@jane"
+        [ariaDescribedby]="describedBy()"
+      />
+      @if (showError()) {
+        <hlm-error id="handle-error">Use 3+ lowercase letters.</hlm-error>
+      } @else {
+        <hlm-hint id="handle-hint">Your public @name.</hlm-hint>
+      }
+    </form>
+  `,
+})
+export class DescribedByExample {
+  readonly form = new FormGroup({
+    handle: new FormControl<string>('', {
+      nonNullable: true,
+      validators: [Validators.minLength(3), Validators.pattern(/^[a-z]+$/)],
+    }),
+  });
+
+  showError(): boolean {
+    const c = this.form.controls.handle;
+    return c.invalid && (c.dirty || c.touched);
+  }
+
+  describedBy(): string {
+    return this.showError() ? 'handle-error' : 'handle-hint';
+  }
+}
+```
+
+### 6. Composition: search row with button (input + button)
+
+```ts
+import { Component, signal } from '@angular/core';
+import { HlmInput } from '@egose/shadcn-theme-ng/input';
+import { HlmButton } from '@egose/shadcn-theme-ng/button';
+
+@Component({
+  standalone: true,
+  imports: [HlmInput, HlmButton],
+  template: `
+    <div class="tw:flex tw:gap-2">
+      <input
+        hlmInput
+        aria-label="Search docs"
+        placeholder="Search docs…"
+        [value]="query()"
+        (input)="query.set($any($event.target).value)"
+        (keydown.enter)="search()"
+      />
+      <button hlmBtn type="button" (click)="search()">Search</button>
+    </div>
+    @if (searched()) {
+      <p role="status" class="tw:text-sm">Searching for “{{ query() }}”…</p>
+    }
+  `,
+})
+export class SearchRowExample {
+  readonly query = signal('');
+  readonly searched = signal(false);
+
+  search() {
+    this.searched.set(true);
+  }
+}
+```
+
+## Accessibility notes
+
+- Always pair the input with a `<label for>` (or `aria-label`/`aria-labelledby` when the design is label-less). The directive does not generate labels.
+- Wire `ariaDescribedby` to hint/error ids so screen readers announce help and validation together with the field. The `eg-form-*` wrappers automate this — copy their pattern when hand-rolling.
+- Invalid styling is visual only until you expose the message text (e.g. `<hlm-error>` or `role="alert"`); use `forceInvalid` sparingly and only alongside a message.
+- Keep native semantics: correct `type`, `autocomplete`, `required`, and `disabled` (not `aria-disabled` + click-guard) so AT and password managers behave.
+
+## Theming / CSS variables
+
+No component-specific CSS variables; colors/spacing come from the shared theme tokens (`--input`, `--ring`, `--destructive`, `--radius`, …). Taller fields: add `tw:h-11`; monospace/code looks: add `tw:font-mono`.
+
+## Related subpaths
+
+- `@egose/shadcn-theme-ng/form-text-input` — labeled + validated reactive-forms wrapper (prefer for forms).
+- `@egose/shadcn-theme-ng/form-textarea` — multiline sibling reusing the same class hook.
+- `@egose/shadcn-theme-ng/input-group` — joined prefix/input/suffix compositions.
+- `@egose/shadcn-theme-ng/label` — `HlmLabel` for the `<label>` side.

package/input-group/README.md

@@ -1,11 +1,341 @@
-# InputGroup
+# Input Group (`@egose/shadcn-theme-ng/input-group`)
 
-This project was generated using [Angular CLI](https://github.com/angular/angular-cli).
+The input group joins an input (or textarea) with prefixes, suffixes, and inline action buttons into a single bordered control — the shadcn/ui _InputGroup_ equivalent (currency prefix + amount + Apply, URL slug builder, message composer with block add-ons). The outer directive owns the border/focus ring; the inner pieces are borderless so the group reads as one field.
 
-## Building
+> **Ships as:** `@egose/shadcn-theme-ng/input-group` (plain Tailwind) and `@egose/shadcn-theme-ng-tw/input-group` (`tw:`-prefixed variant). See the [package README](../../README.md) for installation, peer dependencies, and the Tailwind-variant contract. Do not publish this project directory independently.
 
-To build the library, run:
+## Installation
 
 ```bash
-ng build input-group
+# Plain Tailwind (no prefix)
+npm install @egose/shadcn-theme-ng
+
+# Or the tw:-prefixed variant
+npm install @egose/shadcn-theme-ng-tw
+```
+
+Peer dependencies (Angular, CDK, `@spartan-ng/brain`, `rxjs`) are documented in the [package README](../../README.md#peer-dependencies).
+
+```ts
+import { HlmInputGroupImports } from '@egose/shadcn-theme-ng/input-group';
+// tw variant:
+// import { HlmInputGroupImports } from '@egose/shadcn-theme-ng-tw/input-group';
+```
+
+## Imports
+
+```ts
+// Standalone component — spread the imports array:
+import { HlmInputGroupImports } from '@egose/shadcn-theme-ng/input-group';
+
+@Component({
+  standalone: true,
+  imports: [HlmInputGroupImports],
+  template: `
+    <div hlmInputGroup>
+      <span hlmInputGroupText>$</span>
+      <input hlmInputGroupInput placeholder="0.00" aria-label="Amount in dollars" />
+    </div>
+  `,
+})
+export class MyComp {}
+```
+
+```ts
+// NgModule-based — import the module:
+import { HlmInputGroupModule } from '@egose/shadcn-theme-ng/input-group';
+
+@NgModule({ imports: [HlmInputGroupModule] })
+export class MyModule {}
+```
+
+Exported from `src/public-api.ts`: `HlmInputGroup`, `HlmInputGroupAddon`, `HlmInputGroupButton`, `HlmInputGroupInput`, `HlmInputGroupText`, `HlmInputGroupTextarea`, plus `HlmInputGroupImports` and `HlmInputGroupModule`.
+
+## Anatomy / Structure
+
+```html
+<div hlmInputGroup>
+  <!-- inline prefix -->
+  <span hlmInputGroupText>$</span>
+
+  <!-- the actual control (borderless, flex-1) -->
+  <input hlmInputGroupInput placeholder="Monthly budget" aria-label="Monthly budget" />
+
+  <!-- inline action -->
+  <button hlmInputGroupButton type="button">Apply</button>
+</div>
+
+<!-- block layout for composers -->
+<div hlmInputGroup>
+  <div hlmInputGroupAddon align="block-start">Message to #general</div>
+  <textarea hlmInputGroupTextarea rows="3" aria-label="Message"></textarea>
+  <div hlmInputGroupAddon align="block-end">…</div>
+</div>
 ```
+
+Real selectors: `[hlmInputGroup]` / `hlm-input-group` (container, `role="group"`); `input[hlmInputGroupInput]` (input, `hostDirectives: [HlmInput]`, `data-slot="input-group-control"`); `textarea[hlmInputGroupTextarea]` (`hostDirectives: [HlmTextarea]`, same control slot); `[hlmInputGroupAddon]` / `hlm-input-group-addon` (alignable addon, `align` = `inline-start` | `inline-end` | `block-start` | `block-end`, default `inline-start`); `[hlmInputGroupText]` / `hlm-input-group-text` (plain inline text); `button[hlmInputGroupButton]` (action button, ghost variant preset, `hostDirectives: [HlmBtn]`).
+
+## API reference
+
+### `[hlmInputGroup]` — `HlmInputGroup`
+
+Container. No inputs/outputs. `role="group"`, `data-slot="input-group"`. Carries the border, `h-9` height, shadow, and the `:focus-visible` / invalid ring logic that reacts to the inner `[data-slot=input-group-control]` and disabled state (`group-data-[disabled=true]/input-group` dims addons).
+
+### `input[hlmInputGroupInput]` — `HlmInputGroupInput`
+
+Borderless input (`hostDirectives: [HlmInput]`). No inputs of its own — all native input attributes and `HlmInput` inputs (`ariaDescribedby`, `id`, `forceInvalid`) apply directly on the element.
+
+### `textarea[hlmInputGroupTextarea]` — `HlmInputGroupTextarea`
+
+Borderless textarea (`hostDirectives: [HlmTextarea]`, `resize-none`). No inputs of its own; native textarea attributes apply directly.
+
+### `[hlmInputGroupAddon]` — `HlmInputGroupAddon`
+
+| Input   | Type                                                             | Default          | Description                                                                               |
+| ------- | ---------------------------------------------------------------- | ---------------- | ----------------------------------------------------------------------------------------- |
+| `align` | `'inline-start' \| 'inline-end' \| 'block-start' \| 'block-end'` | `'inline-start'` | Placement: inline prefixes/suffixes vs full-width block rows (reflected as `data-align`). |
+
+Inline addons order themselves first/last automatically; block addons stack the group vertically (`flex-col`).
+
+### `[hlmInputGroupText]` — `HlmInputGroupText`
+
+Static inline text (currency symbols, units, URL fragments). No inputs/outputs.
+
+### `button[hlmInputGroupButton]` — `HlmInputGroupButton`
+
+| Input     | Type                                     | Default    | Description                                                                                     |
+| --------- | ---------------------------------------- | ---------- | ----------------------------------------------------------------------------------------------- |
+| `size`    | `'xs' \| 'sm' \| 'icon-xs' \| 'icon-sm'` | `'xs'`     | Button density; `icon-*` variants are square for glyph-only buttons (reflected as `data-size`). |
+| `variant` | (via `HlmBtn`)                           | `'ghost'`  | Forwarded to `HlmBtn`; the group presets the brain button config to `ghost`.                    |
+| `type`    | `'button' \| 'submit' \| 'reset'`        | `'button'` | Native button type (bound as `[type]`).                                                         |
+
+## Examples
+
+### 1. Currency prefix + action button
+
+```ts
+import { Component, signal } from '@angular/core';
+import { HlmInputGroupImports } from '@egose/shadcn-theme-ng/input-group';
+
+@Component({
+  standalone: true,
+  imports: [HlmInputGroupImports],
+  template: `
+    <div hlmInputGroup>
+      <span hlmInputGroupText>$</span>
+      <input hlmInputGroupInput type="number" placeholder="Monthly budget" aria-label="Monthly budget" />
+      <button hlmInputGroupButton type="button" (click)="apply()">Apply</button>
+    </div>
+    @if (message()) {
+      <p role="status" class="tw:mt-2 tw:text-sm">{{ message() }}</p>
+    }
+  `,
+})
+export class CurrencyExample {
+  readonly message = signal<string | null>(null);
+
+  apply() {
+    this.message.set('Budget applied.');
+  }
+}
+```
+
+### 2. URL slug builder (prefix + input + suffix)
+
+```ts
+import { Component } from '@angular/core';
+import { FormsModule } from '@angular/forms';
+import { HlmInputGroupImports } from '@egose/shadcn-theme-ng/input-group';
+
+@Component({
+  standalone: true,
+  imports: [FormsModule, HlmInputGroupImports],
+  template: `
+    <div hlmInputGroup>
+      <span hlmInputGroupText>https://egose.dev/</span>
+      <input
+        hlmInputGroupInput
+        [(ngModel)]="slug"
+        name="slug"
+        placeholder="campaign-spring"
+        aria-label="Campaign slug"
+      />
+      <span hlmInputGroupText>.html</span>
+    </div>
+    <p class="tw:mt-2 tw:text-sm tw:text-slate-500">Preview: https://egose.dev/{{ slug || '…' }}.html</p>
+  `,
+})
+export class SlugExample {
+  slug = 'angular-standard';
+}
+```
+
+### 3. Search with icon addon + keyboard shortcut hint
+
+```ts
+import { Component } from '@angular/core';
+import { NgIcon, provideIcons } from '@ng-icons/core';
+import { lucideSearch } from '@ng-icons/lucide';
+import { HlmIcon } from '@egose/shadcn-theme-ng/icon';
+import { HlmInputGroupImports } from '@egose/shadcn-theme-ng/input-group';
+import { HlmKbd } from '@egose/shadcn-theme-ng/kbd';
+
+@Component({
+  standalone: true,
+  imports: [NgIcon, HlmIcon, HlmInputGroupImports, HlmKbd],
+  providers: [provideIcons({ lucideSearch })],
+  template: `
+    <div hlmInputGroup>
+      <span hlmInputGroupText><ng-icon hlm name="lucideSearch" size="sm" /></span>
+      <input hlmInputGroupInput placeholder="Search docs…" aria-label="Search docs" />
+      <div hlmInputGroupAddon align="inline-end"><kbd hlmKbd>⌘K</kbd></div>
+    </div>
+  `,
+})
+export class SearchExample {}
+```
+
+### 4. Icon-only buttons (`icon-xs` / `icon-sm`)
+
+```ts
+import { Component, signal } from '@angular/core';
+import { NgIcon, provideIcons } from '@ng-icons/core';
+import { lucideCopy, lucideCheck } from '@ng-icons/lucide';
+import { HlmIcon } from '@egose/shadcn-theme-ng/icon';
+import { HlmInputGroupImports } from '@egose/shadcn-theme-ng/input-group';
+
+@Component({
+  standalone: true,
+  imports: [NgIcon, HlmIcon, HlmInputGroupImports],
+  providers: [provideIcons({ lucideCopy, lucideCheck })],
+  template: `
+    <div hlmInputGroup>
+      <input hlmInputGroupInput [value]="token()" readonly aria-label="API token" />
+      <button
+        hlmInputGroupButton
+        size="icon-xs"
+        type="button"
+        (click)="copy()"
+        [attr.aria-label]="copied() ? 'Copied' : 'Copy token'"
+      >
+        <ng-icon hlm [name]="copied() ? 'lucideCheck' : 'lucideCopy'" size="sm" />
+      </button>
+    </div>
+  `,
+})
+export class CopyExample {
+  readonly token = signal('sk-live-abc123');
+  readonly copied = signal(false);
+
+  async copy() {
+    await navigator.clipboard.writeText(this.token());
+    this.copied.set(true);
+    setTimeout(() => this.copied.set(false), 1500);
+  }
+}
+```
+
+### 5. Block composer (textarea + block addons)
+
+```ts
+import { Component, signal } from '@angular/core';
+import { FormsModule } from '@angular/forms';
+import { HlmInputGroupImports } from '@egose/shadcn-theme-ng/input-group';
+
+@Component({
+  standalone: true,
+  imports: [FormsModule, HlmInputGroupImports],
+  template: `
+    <div hlmInputGroup>
+      <div hlmInputGroupAddon align="block-start">Message to #design-review</div>
+      <textarea
+        hlmInputGroupTextarea
+        rows="4"
+        [(ngModel)]="draft"
+        name="draft"
+        aria-label="Message to the design-review channel"
+        placeholder="Describe the behavior you want to change…"
+      ></textarea>
+      <div hlmInputGroupAddon align="block-end" class="tw:flex tw:items-center tw:justify-between">
+        <span role="status">{{ status() }}</span>
+        <button hlmInputGroupButton type="button" (click)="send()">Send</button>
+      </div>
+    </div>
+  `,
+})
+export class ComposerExample {
+  draft = '';
+  readonly status = signal('Draft autosaved just now');
+
+  send() {
+    this.status.set('Message sent just now.');
+    this.draft = '';
+  }
+}
+```
+
+### 6. Reactive form + validation (forceInvalid + error text)
+
+```ts
+import { Component } from '@angular/core';
+import { FormControl, FormGroup, ReactiveFormsModule, Validators } from '@angular/forms';
+import { HlmInputGroupImports } from '@egose/shadcn-theme-ng/input-group';
+import { HlmError } from '@egose/shadcn-theme-ng/form-field';
+
+@Component({
+  standalone: true,
+  imports: [ReactiveFormsModule, HlmInputGroupImports, HlmError],
+  template: `
+    <form [formGroup]="form" (ngSubmit)="submit()">
+      <div hlmInputGroup>
+        <span hlmInputGroupText>€</span>
+        <input
+          hlmInputGroupInput
+          type="number"
+          formControlName="price"
+          placeholder="0.00"
+          aria-label="Price in euros"
+          aria-describedby="price-error"
+          [forceInvalid]="showError()"
+        />
+      </div>
+      @if (showError()) {
+        <hlm-error id="price-error">Enter a price greater than 0.</hlm-error>
+      }
+      <button type="submit">Save</button>
+    </form>
+  `,
+})
+export class ValidationExample {
+  readonly form = new FormGroup({
+    price: new FormControl<number | null>(null, { validators: [Validators.required, Validators.min(0.01)] }),
+  });
+
+  showError(): boolean {
+    const c = this.form.controls.price;
+    return c.invalid && (c.dirty || c.touched);
+  }
+
+  submit() {
+    if (this.form.invalid) this.form.markAllAsTouched();
+  }
+}
+```
+
+## Accessibility notes
+
+- The container has `role="group"` — give the inner control an `aria-label` (or visible `<label>`) since add-on text is not automatically associated.
+- Add-on text (`$`, `https://…`) is visual context; repeat the essential unit in the input's accessible name (`aria-label="Monthly budget in dollars"`), not just the placeholder.
+- Icon-only `hlmInputGroupButton`s need an `aria-label` (`Copy token`, `Send`).
+- Validation messages live outside the group — link them with `aria-describedby` + `forceInvalid` as in example 6 so the error ring and announcement stay in sync.
+
+## Theming / CSS variables
+
+No component-specific CSS variables; borders, rings, and muted text come from the shared tokens (`--input`, `--ring`, `--muted-foreground`, `--destructive`, `--radius`). Width/height adapt to content — constrain with `tw:max-w-*` on the group.
+
+## Related subpaths
+
+- `@egose/shadcn-theme-ng/input` — standalone `HlmInput` (what the group input extends).
+- `@egose/shadcn-theme-ng/textarea` — `HlmTextarea` (what the group textarea extends).
+- `@egose/shadcn-theme-ng/button` — `HlmBtn` variants behind the group button.
+- `@egose/shadcn-theme-ng/kbd` — shortcut hints inside addons.