@egose/shadcn-theme-ng 0.1.0 → 0.3.0

package/progress/README.md

@@ -1,11 +1,317 @@
-# Progress
+# Progress (`@egose/shadcn-theme-ng/progress`)
 
-This project was generated using [Angular CLI](https://github.com/angular/angular-cli).
+Determinate/indeterminate progress bar (shadcn/ui `progress` equivalent). Thin shadcn styling directives over the spartan-ng `BrnProgress` brain family: `hlm-progress` owns the track + value semantics (`value`, `max`, `getValueLabel`), and the inner `hlmProgressIndicator` bar positions itself from the brain value with RTL awareness and an indeterminate animation state.
 
-## Building
+Ships as `@egose/shadcn-theme-ng/progress` and `@egose/shadcn-theme-ng-tw/progress` (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 progress
+# 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 the indicator also reads Angular CDK `Directionality` for RTL. No extra install step is needed beyond the package install above.
+
+## Imports
+
+Real exported symbols (from `src/public-api.ts`):
+
+```ts
+import {
+  HlmProgress, // directive: hlm-progress,[hlmProgress]
+  HlmProgressIndicator, // directive: [hlmProgressIndicator],hlm-progress-indicator
+  HlmProgressImports, // readonly [HlmProgress, HlmProgressIndicator]
+  HlmProgressModule, // NgModule wrapping HlmProgressImports
+} from '@egose/shadcn-theme-ng/progress';
+```
+
+Standalone usage:
+
+```ts
+import { Component } from '@angular/core';
+import { HlmProgressImports } from '@egose/shadcn-theme-ng/progress';
+
+@Component({
+  selector: 'app-demo',
+  standalone: true,
+  imports: [...HlmProgressImports],
+  template: `
+    <hlm-progress [value]="40" [max]="100">
+      <hlm-progress-indicator hlmProgressIndicator />
+    </hlm-progress>
+  `,
+})
+export class DemoComponent {}
+```
+
+NgModule usage:
+
+```ts
+import { NgModule } from '@angular/core';
+import { HlmProgressModule } from '@egose/shadcn-theme-ng/progress';
+
+@NgModule({ imports: [HlmProgressModule] })
+export class DemoModule {}
+```
+
+For the `tw:` build, swap the specifier to `@egose/shadcn-theme-ng-tw/progress`. Symbol names are identical.
+
+## Anatomy / Structure
+
+```html
+<!-- determinate -->
+<hlm-progress [value]="value()" [max]="100">
+  <hlm-progress-indicator hlmProgressIndicator />
+</hlm-progress>
+
+<!-- attribute-selector form -->
+<div hlmProgress [value]="40" [max]="100">
+  <div hlmProgressIndicator></div>
+</div>
+
+<!-- indeterminate (no value) -->
+<hlm-progress>
+  <hlm-progress-indicator hlmProgressIndicator />
+</hlm-progress>
+```
+
+| Class                  | Selector                                        | Role                                                                                |
+| ---------------------- | ----------------------------------------------- | ----------------------------------------------------------------------------------- |
+| `HlmProgress`          | `hlm-progress,[hlmProgress]`                    | Track (`BrnProgress` host: `value`, `max`, `getValueLabel`); `data-slot="progress"` |
+| `HlmProgressIndicator` | `[hlmProgressIndicator],hlm-progress-indicator` | Fill bar (`BrnProgressIndicator` host); `data-slot="progress-indicator"`            |
+
+The indicator computes `translateX(-offset%)` from `100 - value` (defaulting `null`/`undefined` value to `100` for the offset math) and flips the sign in RTL via CDK `Directionality`. When the brain value is `null`/`undefined` it adds the `animate-indeterminate` class instead of a static fill.
+
+## API reference
+
+### `HlmProgress` (`hlm-progress,[hlmProgress]`)
+
+| Member          | Kind                      | Type                          | Notes                                                        |
+| --------------- | ------------------------- | ----------------------------- | ------------------------------------------------------------ |
+| `value`         | input (via `BrnProgress`) | `number \| null \| undefined` | Current value; `null`/`undefined` → indeterminate            |
+| `max`           | input (via `BrnProgress`) | `number`                      | Scale maximum (commonly `100`)                               |
+| `getValueLabel` | input (via `BrnProgress`) | `(value, max) => string`      | Accessible value-text factory (see brain docs for signature) |
+
+No shadcn inputs of its own. Track styling: `bg-muted h-1.5 rounded-full relative inline-flex w-full overflow-hidden`.
+
+### `HlmProgressIndicator` (`[hlmProgressIndicator],hlm-progress-indicator`)
+
+No public inputs/outputs/methods. Internals (protected, for understanding only): `_transform` (computed `translateX()`), `_indeterminate` (computed `value == null`). Fill styling: `bg-primary h-full w-full flex-1 transition-all`; indeterminate state toggles `animate-indeterminate`.
+
+## Examples
+
+### 1. Basic determinate bar
+
+```ts
+import { Component, signal } from '@angular/core';
+import { HlmProgressImports } from '@egose/shadcn-theme-ng/progress';
+
+@Component({
+  selector: 'app-progress-basic',
+  standalone: true,
+  imports: [...HlmProgressImports],
+  template: `
+    <hlm-progress [value]="value()" [max]="100">
+      <hlm-progress-indicator hlmProgressIndicator />
+    </hlm-progress>
+    <p class="tw:text-sm tw:text-muted-foreground">{{ value() }}%</p>
+    <button type="button" (click)="value.set(Math.min(100, value() + 10))">+10</button>
+  `,
+})
+export class ProgressBasicComponent {
+  readonly value = signal(40);
+  protected readonly Math = Math;
+}
+```
+
+### 2. Timer / simulated upload
+
+```ts
+import { Component, signal, OnDestroy } from '@angular/core';
+import { HlmProgressImports } from '@egose/shadcn-theme-ng/progress';
+
+@Component({
+  selector: 'app-progress-timer',
+  standalone: true,
+  imports: [...HlmProgressImports],
+  template: `
+    <hlm-progress [value]="progress()" [max]="100">
+      <hlm-progress-indicator hlmProgressIndicator />
+    </hlm-progress>
+    <div class="tw:flex tw:gap-2">
+      <button type="button" (click)="start()">Start</button>
+      <button type="button" (click)="reset()">Reset</button>
+    </div>
+  `,
+})
+export class ProgressTimerComponent implements OnDestroy {
+  readonly progress = signal(0);
+  private timer: ReturnType<typeof setInterval> | undefined;
+
+  start(): void {
+    this.stop();
+    this.timer = setInterval(() => {
+      this.progress.update((v) => (v >= 100 ? 100 : v + 2));
+      if (this.progress() >= 100) this.stop();
+    }, 100);
+  }
+
+  reset(): void {
+    this.stop();
+    this.progress.set(0);
+  }
+
+  ngOnDestroy(): void {
+    this.stop();
+  }
+
+  private stop(): void {
+    if (this.timer) clearInterval(this.timer);
+    this.timer = undefined;
+  }
+}
+```
+
+### 3. Indeterminate (unknown duration)
+
+Omit `value` entirely — the indicator switches to the `animate-indeterminate` treatment.
+
+```ts
+import { Component, signal } from '@angular/core';
+import { HlmProgressImports } from '@egose/shadcn-theme-ng/progress';
+
+@Component({
+  selector: 'app-progress-indeterminate',
+  standalone: true,
+  imports: [...HlmProgressImports],
+  template: `
+    <button type="button" (click)="load()">Fetch report</button>
+    @if (loading()) {
+      <hlm-progress aria-label="Loading report">
+        <hlm-progress-indicator hlmProgressIndicator />
+      </hlm-progress>
+    }
+  `,
+})
+export class ProgressIndeterminateComponent {
+  readonly loading = signal(false);
+
+  async load(): Promise<void> {
+    this.loading.set(true);
+    await new Promise((r) => setTimeout(r, 1500));
+    this.loading.set(false);
+  }
+}
 ```
+
+### 4. Custom scale (`max !== 100`) + accessible label
+
+```ts
+import { Component, signal } from '@angular/core';
+import { HlmProgressImports } from '@egose/shadcn-theme-ng/progress';
+
+@Component({
+  selector: 'app-progress-scale',
+  standalone: true,
+  imports: [...HlmProgressImports],
+  template: `
+    <hlm-progress [value]="done()" [max]="total()" [getValueLabel]="label" aria-label="Migration progress">
+      <hlm-progress-indicator hlmProgressIndicator />
+    </hlm-progress>
+    <p class="tw:text-sm">{{ done() }} of {{ total() }} rows migrated</p>
+  `,
+})
+export class ProgressScaleComponent {
+  readonly done = signal(37);
+  readonly total = signal(200);
+
+  readonly label = (value: number | null | undefined, max: number): string => `${value ?? 0} of ${max} rows`;
+}
+```
+
+> `getValueLabel` is the brain hook for the `aria-valuetext`; keep the visible text in sync (as above) so sighted and SR users agree.
+
+### 5. Multi-step wizard
+
+```ts
+import { Component, signal, computed } from '@angular/core';
+import { HlmProgressImports } from '@egose/shadcn-theme-ng/progress';
+
+@Component({
+  selector: 'app-progress-steps',
+  standalone: true,
+  imports: [...HlmProgressImports],
+  template: `
+    <hlm-progress [value]="step()" [max]="steps.length">
+      <hlm-progress-indicator hlmProgressIndicator />
+    </hlm-progress>
+    <p class="tw:text-sm">Step {{ step() }} of {{ steps.length }}: {{ steps[step() - 1] }}</p>
+    <div class="tw:flex tw:gap-2">
+      <button type="button" (click)="prev()" [disabled]="step() <= 1">Back</button>
+      <button type="button" (click)="next()" [disabled]="step() >= steps.length">Next</button>
+    </div>
+  `,
+})
+export class ProgressStepsComponent {
+  readonly steps = ['Account', 'Profile', 'Confirm'];
+  readonly step = signal(1);
+
+  prev(): void {
+    this.step.update((s) => Math.max(1, s - 1));
+  }
+  next(): void {
+    this.step.update((s) => Math.min(this.steps.length, s + 1));
+  }
+}
+```
+
+### 6. Error / complete states and NgModule form
+
+```ts
+import { NgModule, Component, signal, computed } from '@angular/core';
+import { HlmProgressImports, HlmProgressModule } from '@egose/shadcn-theme-ng/progress';
+
+@Component({
+  selector: 'app-progress-states',
+  standalone: true,
+  imports: [...HlmProgressImports],
+  template: `
+    <hlm-progress [value]="value()" [max]="100" [class]="barClass()">
+      <hlm-progress-indicator hlmProgressIndicator />
+    </hlm-progress>
+    <p class="tw:text-sm" [class.tw:text-destructive]="failed()">
+      {{ failed() ? 'Upload failed — retrying…' : value() >= 100 ? 'Complete' : 'Uploading…' }}
+    </p>
+  `,
+})
+export class ProgressStatesComponent {
+  readonly value = signal(75);
+  readonly failed = signal(false);
+  readonly barClass = computed(() => (this.failed() ? 'tw:[&>[data-slot=progress-indicator]]:tw:bg-destructive' : ''));
+}
+
+@NgModule({ imports: [HlmProgressModule] })
+export class ProgressLegacyModule {}
+```
+
+> There is no `state`/`variant` input — success/error tints are done with plain `class` overrides targeting the indicator (as above), since the indicator carries `data-slot="progress-indicator"`.
+
+## Accessibility notes
+
+- The brain `BrnProgress` exposes `role="progressbar"` with `aria-valuemin`/`max`/`now` (plus `aria-valuetext` via `getValueLabel`) — always provide `aria-label`/`aria-labelledby` unless surrounding text already names the bar.
+- Indeterminate bars (no `value`) must still be labelled ("Loading report") so SR users know what is pending; pair with status text or an `aria-live` region for completion.
+- Don't use progress as the _only_ conveyor of state — mirror percent/steps in text (examples 1/4/5).
+- Color overrides (example 6) are decorative; keep the text label as the source of truth for error/complete states.
+
+## Theming / CSS variables
+
+No theming inputs. Track is `bg-muted`, fill is `bg-primary`; both follow shadcn tokens automatically. Tint the fill per-instance with a `class` override on the track targeting `[data-slot=progress-indicator]`.
+
+## Related subpaths
+
+- `@egose/shadcn-theme-ng/skeleton`, `@egose/shadcn-theme-ng/spinner` — alternative loading indicators (skeleton screens, spinners) vs this determinate bar.
+- `@egose/shadcn-theme-ng/sonner` — toast completion notices to pair with a finished upload.

package/radio-group/README.md

@@ -1,3 +1,365 @@
-# Radio Group Subpath
+# Radio Group (`@egose/shadcn-theme-ng/radio-group`)
 
-This project ships only as `@egose/shadcn-theme-ng/radio-group` or `@egose/shadcn-theme-ng-tw/radio-group`. See the [package README](../../README.md) for installation, compatibility, Tailwind variant, test, and release guidance. Do not publish this project directory independently.
+A shadcn/ui-style **Radio Group** for Angular — a set of mutually exclusive options where exactly one can be selected. This is the Angular equivalent of shadcn/ui `RadioGroup` / `RadioGroupItem`.
+
+The primitives come from **spartan-ng/brain** (`BrnRadioGroup`, `BrnRadio`, `BrnFieldControlDescribedBy`): keyboard navigation (arrow keys), roving tabindex, and form integration are handled by `BrnRadioGroup`/`BrnRadio`, while this package adds the shadcn look (grid layout, circular indicator, focus ring, error styling).
+
+> **Ships as:** `@egose/shadcn-theme-ng/radio-group` and `@egose/shadcn-theme-ng-tw/radio-group` (the `tw:`-prefixed Tailwind variant — same API, class strings prefixed with `tw:`).
+> See the [package README](../../README.md) for installation, peer dependencies, and Tailwind setup. 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
+```
+
+Import from the subpath (not the package root):
+
+```ts
+import { HlmRadioGroupImports } from '@egose/shadcn-theme-ng/radio-group';
+// tw variant:
+// import { HlmRadioGroupImports } from '@egose/shadcn-theme-ng-tw/radio-group';
+```
+
+Peer dependencies (see [package README](../../README.md) for versions): `@angular/core`, `@angular/common`, `@spartan-ng/brain`. `@angular/cdk` is required transitively by `HlmRadio` (boolean coercion).
+
+## Imports
+
+Real exported symbols (from `src/public-api.ts`):
+
+| Symbol                 | Kind          | Description                                                       |
+| ---------------------- | ------------- | ----------------------------------------------------------------- |
+| `HlmRadioGroup`        | Directive     | Group container; forwards `BrnRadioGroup`                         |
+| `HlmRadio`             | Component     | Single radio item (`hlm-radio`), wraps `BrnRadio`                 |
+| `HlmRadioIndicator`    | Component     | Circular visual indicator dot                                     |
+| `HlmRadioGroupImports` | `const` array | `[HlmRadioGroup, HlmRadio, HlmRadioIndicator]` standalone imports |
+| `HlmRadioGroupModule`  | `NgModule`    | NgModule wrapper re-exporting the three above                     |
+
+Standalone usage:
+
+```ts
+import { Component } from '@angular/core';
+import { HlmRadioGroupImports } from '@egose/shadcn-theme-ng/radio-group';
+
+@Component({
+  selector: 'app-demo',
+  standalone: true,
+  imports: [HlmRadioGroupImports],
+  template: `...`,
+})
+export class DemoComponent {}
+```
+
+NgModule usage:
+
+```ts
+import { NgModule } from '@angular/core';
+import { HlmRadioGroupModule } from '@egose/shadcn-theme-ng/radio-group';
+
+@NgModule({ imports: [HlmRadioGroupModule] })
+export class DemoModule {}
+```
+
+You can also import the pieces individually (`import { HlmRadioGroup, HlmRadio, HlmRadioIndicator } from '...'`).
+
+## Anatomy / Structure
+
+```html
+<!-- Attribute form on a div -->
+<div hlmRadioGroup name="plan" [value]="plan()" (valueChange)="plan.set($event)">
+  <hlm-radio value="free" inputId="plan-free">
+    <hlm-radio-indicator />
+    Free
+  </hlm-radio>
+
+  <hlm-radio value="pro" inputId="plan-pro">
+    <hlm-radio-indicator />
+    Pro
+  </hlm-radio>
+</div>
+
+<!-- Element form also works -->
+<hlm-radio-group name="plan">
+  <hlm-radio value="free"><hlm-radio-indicator />Free</hlm-radio>
+</hlm-radio-group>
+```
+
+Real selectors:
+
+| Selector                             | Class               | Notes                                                                                                                                                    |
+| ------------------------------------ | ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `[hlmRadioGroup]`, `hlm-radio-group` | `HlmRadioGroup`     | Group host; `data-slot="radio-group"`                                                                                                                    |
+| `hlm-radio`                          | `HlmRadio<T>`       | Item host; `data-slot="radio-group-item"`; projects `[target],[indicator],hlm-radio-indicator` into the indicator slot, everything else as label content |
+| `hlm-radio-indicator`                | `HlmRadioIndicator` | Visual dot; `data-slot="radio-group-indicator"`                                                                                                          |
+
+## API reference
+
+### HlmRadioGroup (directive)
+
+Thin directive wrapper over `BrnRadioGroup` (plus `BrnFieldControlDescribedBy` for form-field `aria-describedby` wiring). Own inputs:
+
+| Input                 | Type         | Default | Description                                  |
+| --------------------- | ------------ | ------- | -------------------------------------------- |
+| `class` (`userClass`) | `ClassValue` | `''`    | Extra classes appended to `tw:grid tw:gap-3` |
+
+Forwarded `BrnRadioGroup` host-directive bindings:
+
+| Binding       | Kind   | Description                              |
+| ------------- | ------ | ---------------------------------------- |
+| `name`        | input  | Radio group name (native input grouping) |
+| `value`       | input  | Currently selected value                 |
+| `disabled`    | input  | Disables the whole group                 |
+| `required`    | input  | Marks the group as required              |
+| `valueChange` | output | Emits the newly selected value           |
+
+The host also reflects form state as attributes: `aria-invalid`/`data-invalid` when the bound control is invalid, plus `data-dirty` and `data-touched`.
+
+### HlmRadio\<T\> (component)
+
+| Input                                  | Type                  | Default      | Description                                                                                        |
+| -------------------------------------- | --------------------- | ------------ | -------------------------------------------------------------------------------------------------- |
+| `value`                                | `T`                   | **required** | The value this item represents                                                                     |
+| `inputId`                              | `string \| undefined` | `undefined`  | `id` placed on the underlying `brn-radio` element; also used to find an associated `<label [for]>` |
+| `aria-label` (`ariaLabel`)             | `string \| undefined` | `undefined`  | Accessible name when there is no visible label                                                     |
+| `aria-labelledby` (`ariaLabelledby`)   | `string \| undefined` | `undefined`  | Id(s) of labelling element(s)                                                                      |
+| `aria-describedby` (`ariaDescribedby`) | `string \| undefined` | `undefined`  | Id(s) of describing element(s)                                                                     |
+| `required`                             | `boolean`             | `false`      | Native required flag (boolean-coerced)                                                             |
+| `disabled`                             | `boolean`             | `false`      | Disables this item (boolean-coerced); mirrors `data-disabled` onto an associated `<label>`         |
+| `class` (`userClass`)                  | `ClassValue`          | `''`         | Extra classes                                                                                      |
+
+| Output   | Type                | Description                                    |
+| -------- | ------------------- | ---------------------------------------------- |
+| `change` | `BrnRadioChange<T>` | Emitted when this item's checked state changes |
+
+Label association detail: on init the component looks for `closest('label')`, falling back to `document.querySelector('label[for=inputId]')`, and mirrors `data-disabled="true"/"false"` onto that label so label styling follows the disabled state. IDs containing special characters (e.g. quotes/brackets) are matched safely via `htmlFor` comparison, not a CSS selector.
+
+### HlmRadioIndicator (component)
+
+No inputs/outputs. Renders the styled outer circle; the inner dot fills via `group-data-[checked=true]` when the parent `brn-radio` reports checked. Always place it inside `hlm-radio` (it matches the `hlm-radio-indicator` content slot).
+
+## Examples
+
+### 1. Basic usage
+
+```ts
+import { Component, signal } from '@angular/core';
+import { HlmRadioGroupImports } from '@egose/shadcn-theme-ng/radio-group';
+
+@Component({
+  selector: 'app-basic-radio',
+  standalone: true,
+  imports: [HlmRadioGroupImports],
+  template: `
+    <div hlmRadioGroup name="fruit" [value]="fruit()" (valueChange)="fruit.set($event)">
+      <hlm-radio value="apple" inputId="fruit-apple">
+        <hlm-radio-indicator />
+        Apple
+      </hlm-radio>
+      <hlm-radio value="banana" inputId="fruit-banana">
+        <hlm-radio-indicator />
+        Banana
+      </hlm-radio>
+      <hlm-radio value="orange" inputId="fruit-orange">
+        <hlm-radio-indicator />
+        Orange
+      </hlm-radio>
+    </div>
+    <p>Selected: {{ fruit() }}</p>
+  `,
+})
+export class BasicRadioComponent {
+  readonly fruit = signal('apple');
+}
+```
+
+### 2. Element selector form + external labels
+
+`hlm-radio-group` works as an element, and labels can live outside the item via `for`/`inputId`:
+
+```ts
+import { Component, signal } from '@angular/core';
+import { HlmRadioGroupImports } from '@egose/shadcn-theme-ng/radio-group';
+
+@Component({
+  selector: 'app-labelled-radio',
+  standalone: true,
+  imports: [HlmRadioGroupImports],
+  template: `
+    <hlm-radio-group name="contact">
+      <label for="c-email">Email me</label>
+      <hlm-radio value="email" inputId="c-email"><hlm-radio-indicator /></hlm-radio>
+
+      <label for="c-sms">Text me</label>
+      <hlm-radio value="sms" inputId="c-sms"><hlm-radio-indicator /></hlm-radio>
+    </hlm-radio-group>
+  `,
+})
+export class LabelledRadioComponent {}
+```
+
+Wrapping the item in a `<label>` also works — the item finds it with `closest('label')`:
+
+```html
+<hlm-radio-group name="contact">
+  <label>
+    <hlm-radio value="email"><hlm-radio-indicator /></hlm-radio>
+    Email me
+  </label>
+</hlm-radio-group>
+```
+
+### 3. Reactive forms
+
+`BrnRadioGroup` is a `ControlValueAccessor`, so `formControlName`/`formControl` bind on the group host:
+
+```ts
+import { Component } from '@angular/core';
+import { FormControl, FormGroup, ReactiveFormsModule, Validators } from '@angular/forms';
+import { HlmRadioGroupImports } from '@egose/shadcn-theme-ng/radio-group';
+
+@Component({
+  selector: 'app-reactive-radio',
+  standalone: true,
+  imports: [HlmRadioGroupImports, ReactiveFormsModule],
+  template: `
+    <form [formGroup]="form" (ngSubmit)="submit()">
+      <div hlmRadioGroup formControlName="plan">
+        <hlm-radio value="hobby"><hlm-radio-indicator />Hobby</hlm-radio>
+        <hlm-radio value="pro"><hlm-radio-indicator />Pro</hlm-radio>
+        <hlm-radio value="enterprise"><hlm-radio-indicator />Enterprise</hlm-radio>
+      </div>
+      @if (form.controls.plan.invalid && form.controls.plan.touched) {
+        <p class="tw:text-destructive tw:text-sm">Please pick a plan.</p>
+      }
+      <button type="submit">Continue</button>
+    </form>
+  `,
+})
+export class ReactiveRadioComponent {
+  readonly form = new FormGroup({
+    plan: new FormControl<string | null>(null, Validators.required),
+  });
+
+  submit(): void {
+    this.form.markAllAsTouched();
+    console.log(this.form.value);
+  }
+}
+```
+
+When the control is invalid + touched, the group automatically gets `data-invalid="true"` (and destructive text styling) via the forwarded control state — no manual class juggling needed.
+
+### 4. Disabled states (group vs item)
+
+```ts
+import { Component, signal } from '@angular/core';
+import { HlmRadioGroupImports } from '@egose/shadcn-theme-ng/radio-group';
+
+@Component({
+  selector: 'app-disabled-radio',
+  standalone: true,
+  imports: [HlmRadioGroupImports],
+  template: `
+    <!-- Whole group disabled -->
+    <div hlmRadioGroup name="a" value="one" disabled>
+      <hlm-radio value="one"><hlm-radio-indicator />One</hlm-radio>
+      <hlm-radio value="two"><hlm-radio-indicator />Two</hlm-radio>
+    </div>
+
+    <!-- Single item disabled; its <label> gets data-disabled="true" -->
+    <div hlmRadioGroup name="b" [value]="choice()" (valueChange)="choice.set($event)">
+      <label for="b-one">One (soon unavailable)</label>
+      <hlm-radio value="one" inputId="b-one" disabled><hlm-radio-indicator /></hlm-radio>
+      <label for="b-two">Two</label>
+      <hlm-radio value="two" inputId="b-two"><hlm-radio-indicator /></hlm-radio>
+    </div>
+  `,
+})
+export class DisabledRadioComponent {
+  readonly choice = signal('two');
+}
+```
+
+### 5. Per-item change events + typed values
+
+`HlmRadio` is generic — `value` can be any type, and `change` emits `BrnRadioChange<T>`:
+
+```ts
+import { Component, signal } from '@angular/core';
+import { HlmRadioGroupImports } from '@egose/shadcn-theme-ng/radio-group';
+import type { BrnRadioChange } from '@spartan-ng/brain/radio-group';
+
+interface Tier {
+  id: string;
+  price: number;
+}
+
+@Component({
+  selector: 'app-typed-radio',
+  standalone: true,
+  imports: [HlmRadioGroupImports],
+  template: `
+    <div hlmRadioGroup name="tier" (valueChange)="onGroupChange($event)">
+      @for (tier of tiers; track tier.id) {
+        <hlm-radio [value]="tier" (change)="onItemChange($event)">
+          <hlm-radio-indicator />
+          {{ tier.id }} — ${{ tier.price }}/mo
+        </hlm-radio>
+      }
+    </div>
+  `,
+})
+export class TypedRadioComponent {
+  readonly tiers: Tier[] = [
+    { id: 'starter', price: 0 },
+    { id: 'growth', price: 29 },
+  ];
+
+  onGroupChange(value: Tier): void {
+    console.log('group selected:', value.id);
+  }
+
+  onItemChange(event: BrnRadioChange<Tier>): void {
+    console.log('item checked:', event.value.id, event.checked);
+  }
+}
+```
+
+### 6. Custom indicator content (target slot)
+
+Anything projected with `[target]` or `[indicator]` goes into the indicator slot instead of the default label position:
+
+```html
+<div hlmRadioGroup name="layout">
+  <hlm-radio value="grid">
+    <span target class="tw:flex tw:items-center tw:gap-2">
+      <hlm-radio-indicator />
+      <strong>Grid</strong>
+    </span>
+    <span class="tw:text-muted-foreground tw:text-sm">Cards in a grid</span>
+  </hlm-radio>
+</div>
+```
+
+## Accessibility notes
+
+- The group uses the native `radiogroup` semantics from `BrnRadioGroup`, including arrow-key navigation and roving tabindex — keep all `hlm-radio` items inside one group container.
+- Always provide `name` so assistive tech (and native form serialization) treats the items as one group.
+- Prefer visible text content inside `hlm-radio`; use `aria-label`/`aria-labelledby` only when the item has no visible label.
+- Disabled items expose `data-disabled` (and the native disabled state on the inner input) and are skipped in keyboard navigation.
+- Invalid form state is announced via `aria-invalid="true"` on the group host.
+
+## Theming / CSS variables
+
+Styling is class-driven (no component-specific CSS variables). Override via the `class` input on any of the three pieces; the indicator's checked dot keys off `group-data-[checked=true]`, and the group invalid state off `data-[invalid=true]`.
+
+## Related subpaths
+
+- `@egose/shadcn-theme-ng/label` — labelling radio items and form rows
+- `@egose/shadcn-theme-ng/field` / `form-field` — form rows, descriptions, and error text wired via `BrnFieldControlDescribedBy`
+- `@egose/shadcn-theme-ng/checkbox` — multi-select counterpart
+- `@egose/shadcn-theme-ng/form-field-simple` — lightweight wrapper for reactive-form controls