@egose/shadcn-theme-ng 0.1.0 → 0.2.0

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

package/radio-group/fesm2022/radio-group.mjs

@@ -136,7 +136,11 @@ class HlmRadioGroup {
     _errorState = computed(() => this._brnRadioGroup.controlState?.()?.spartanInvalid, /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "_errorState" }] : /* istanbul ignore next */ []));
     constructor() {
-        classes(() => ["grid gap-3", this.userClass(), this._errorState() ? "data-[invalid=true]:text-destructive" : '']);
+        classes(() => [
+            "grid gap-3",
+            this.userClass(),
+            this._errorState() ? "data-[invalid=true]:text-destructive" : '',
+        ]);
     }
     static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "22.1.3", ngImport: i0, type: HlmRadioGroup, deps: [], target: i0.ɵɵFactoryTarget.Directive });
     static ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "17.1.0", version: "22.1.3", type: HlmRadioGroup, isStandalone: true, selector: "[hlmRadioGroup],hlm-radio-group", inputs: { userClass: { classPropertyName: "userClass", publicName: "class", isSignal: true, isRequired: false, transformFunction: null } }, host: { attributes: { "data-slot": "radio-group" }, properties: { "attr.aria-invalid": "_ariaInvalid() ? \"true\" : null", "attr.data-invalid": "_ariaInvalid() ? \"true\" : null", "attr.data-dirty": "_dirty() ? \"true\" : null", "attr.data-touched": "_touched() ? \"true\" : null" } }, hostDirectives: [{ directive: i1.BrnRadioGroup, inputs: ["name", "name", "value", "value", "disabled", "disabled", "required", "required"], outputs: ["valueChange", "valueChange"] }, { directive: i2.BrnFieldControlDescribedBy }], ngImport: i0 });

package/radio-group/types/radio-group.d.ts

@@ -15,7 +15,7 @@ declare class HlmRadio<T = unknown> {
     protected readonly _touched: _angular_core.Signal<boolean | undefined>;
     protected readonly _dirty: _angular_core.Signal<boolean | undefined>;
     protected readonly _groupSpartanInvalid: _angular_core.Signal<boolean | undefined>;
-    protected readonly _errorStateClass: _angular_core.Signal<"text-destructive" | "">;
+    protected readonly _errorStateClass: _angular_core.Signal<"" | "text-destructive">;
     readonly userClass: _angular_core.InputSignal<ClassValue>;
     protected readonly _computedClass: _angular_core.Signal<string>;
     /** Used to set the id on the underlying brn element. */

package/resizable/README.md

@@ -1,11 +1,275 @@
-# Resizable
+# Resizable (`@egose/shadcn-theme-ng/resizable`)
 
-This project was generated using [Angular CLI](https://github.com/angular/angular-cli).
+A shadcn/ui-style **Resizable** panel layout — draggable split views (side-by-side or stacked) with collapsible panels. This is the Angular equivalent of shadcn/ui `ResizablePanelGroup` / `ResizablePanel` / `ResizableHandle`.
 
-## Building
+The behavior comes from **spartan-ng/brain** (`BrnResizableGroup`, `BrnResizablePanel`, `BrnResizableHandle`): pointer-drag resizing, panel size constraints, and layout events. This package is a thin styling/directive layer — a flex group container, constraint-forwarding panel directive with a `setSize` helper, and a handle with an optional grip pill.
 
-To build the library, run:
+> **Ships as:** `@egose/shadcn-theme-ng/resizable` and `@egose/shadcn-theme-ng-tw/resizable` (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
-ng build resizable
+# Plain Tailwind (no prefix)
+npm install @egose/shadcn-theme-ng
+
+# Or the tw:-prefixed variant
+npm install @egose/shadcn-theme-ng-tw
+```
+
+```ts
+import { HlmResizableImports } from '@egose/shadcn-theme-ng/resizable';
+// tw variant:
+// import { HlmResizableImports } from '@egose/shadcn-theme-ng-tw/resizable';
+```
+
+Peer dependencies (see [package README](../../README.md) for versions): `@angular/core`, `@angular/common`, `@spartan-ng/brain`.
+
+## Imports
+
+Real exported symbols (from `src/public-api.ts`):
+
+| Symbol                | Kind          | Description                                                                           |
+| --------------------- | ------------- | ------------------------------------------------------------------------------------- |
+| `HlmResizableGroup`   | Directive     | Flex row/column container; forwards `BrnResizableGroup`                               |
+| `HlmResizablePanel`   | Directive     | Size-constrained panel; forwards `BrnResizablePanel`, `exportAs: 'hlmResizablePanel'` |
+| `HlmResizableHandle`  | Component     | Drag handle with optional grip pill; `exportAs: 'hlmResizableHandle'`                 |
+| `HlmResizableImports` | `const` array | `[HlmResizableGroup, HlmResizablePanel, HlmResizableHandle]` standalone imports       |
+| `HlmResizableModule`  | `NgModule`    | NgModule wrapper re-exporting the three above                                         |
+
+Standalone usage:
+
+```ts
+import { Component } from '@angular/core';
+import { HlmResizableImports } from '@egose/shadcn-theme-ng/resizable';
+
+@Component({
+  selector: 'app-demo',
+  standalone: true,
+  imports: [HlmResizableImports],
+  template: `...`,
+})
+export class DemoComponent {}
+```
+
+NgModule usage:
+
+```ts
+import { NgModule } from '@angular/core';
+import { HlmResizableModule } from '@egose/shadcn-theme-ng/resizable';
+
+@NgModule({ imports: [HlmResizableModule] })
+export class DemoModule {}
+```
+
+## Anatomy / Structure
+
+```html
+<div hlmResizableGroup direction="horizontal">
+  <div hlmResizablePanel defaultSize="25">Sidebar</div>
+
+  <hlm-resizable-handle withHandle />
+
+  <div hlmResizablePanel defaultSize="75">Main content</div>
+</div>
+```
+
+Real selectors:
+
+| Selector                                     | Class                | Notes                                                                                            |
+| -------------------------------------------- | -------------------- | ------------------------------------------------------------------------------------------------ |
+| `[hlmResizableGroup]`, `hlm-resizable-group` | `HlmResizableGroup`  | `data-slot="resizable-group"`; row by default, column when the panel-group direction is vertical |
+| `[hlmResizablePanel]`, `hlm-resizable-panel` | `HlmResizablePanel`  | `data-slot="resizable-panel"`                                                                    |
+| `hlm-resizable-handle`                       | `HlmResizableHandle` | `data-slot="resizable-handle"`; renders a grip `<div>` only when `withHandle` is true            |
+
+## API reference
+
+### HlmResizableGroup (directive)
+
+Thin directive wrapper — no own inputs. Forwarded `BrnResizableGroup` bindings:
+
+| Binding        | Kind   | Description                                   |
+| -------------- | ------ | --------------------------------------------- |
+| `direction`    | input  | `'horizontal' \| 'vertical'` layout direction |
+| `layout`       | input  | Controlled panel layout (sizes)               |
+| `dragStart`    | output | Emitted when a drag resize starts             |
+| `dragEnd`      | output | Emitted when a drag resize ends               |
+| `layoutChange` | output | Emitted when the panel layout changes         |
+
+### HlmResizablePanel (directive)
+
+Thin directive wrapper plus one helper method. No own inputs. Forwarded `BrnResizablePanel` inputs:
+
+| Input         | Description                                      |
+| ------------- | ------------------------------------------------ |
+| `defaultSize` | Initial size (percentage of the group)           |
+| `id`          | Panel id (used for persisted/controlled layouts) |
+| `collapsible` | Whether the panel can collapse to zero           |
+| `minSize`     | Minimum size (percentage)                        |
+| `maxSize`     | Maximum size (percentage)                        |
+
+| Method    | Signature                     | Description                                                                 |
+| --------- | ----------------------------- | --------------------------------------------------------------------------- |
+| `setSize` | `setSize(size: number): void` | Programmatically resize the panel; delegates to `BrnResizablePanel.setSize` |
+
+Because the directive is `exportAs: 'hlmResizablePanel'`, grab it with a template reference: `<div hlmResizablePanel #panel="hlmResizablePanel">` then call `panel.setSize(50)`.
+
+### HlmResizableHandle (component)
+
+| Input (forwarded to `BrnResizableHandle`) | Description                          |
+| ----------------------------------------- | ------------------------------------ |
+| `withHandle`                              | Show the grip pill inside the handle |
+| `disabled`                                | Disable dragging on this handle      |
+
+When `withHandle` is true the component renders a short rounded pill (`<div class="...">`) centered in the handle; otherwise the handle is just the thin hover/drag strip. Hover cursors adapt to direction (`ew-resize` horizontal, `ns-resize` vertical).
+
+## Examples
+
+### 1. Basic horizontal split
+
+```ts
+import { Component } from '@angular/core';
+import { HlmResizableImports } from '@egose/shadcn-theme-ng/resizable';
+
+@Component({
+  selector: 'app-basic-resizable',
+  standalone: true,
+  imports: [HlmResizableImports],
+  template: `
+    <div hlmResizableGroup direction="horizontal" class="tw:h-64 tw:rounded-lg tw:border">
+      <div hlmResizablePanel defaultSize="30" class="tw:p-4">Nav</div>
+      <hlm-resizable-handle />
+      <div hlmResizablePanel defaultSize="70" class="tw:p-4">Content</div>
+    </div>
+  `,
+})
+export class BasicResizableComponent {}
+```
+
+### 2. Handle with grip pill
+
+```html
+<div hlmResizableGroup direction="horizontal" class="tw:h-64 tw:rounded-lg tw:border">
+  <div hlmResizablePanel defaultSize="25" class="tw:p-4">Files</div>
+
+  <hlm-resizable-handle withHandle />
+
+  <div hlmResizablePanel defaultSize="75" class="tw:p-4">Editor</div>
+</div>
+```
+
+### 3. Vertical stacking
+
+```ts
+import { Component } from '@angular/core';
+import { HlmResizableImports } from '@egose/shadcn-theme-ng/resizable';
+
+@Component({
+  selector: 'app-vertical-resizable',
+  standalone: true,
+  imports: [HlmResizableImports],
+  template: `
+    <div hlmResizableGroup direction="vertical" class="tw:h-96 tw:rounded-lg tw:border">
+      <div hlmResizablePanel defaultSize="40" class="tw:p-4">Preview</div>
+      <hlm-resizable-handle withHandle />
+      <div hlmResizablePanel defaultSize="60" class="tw:p-4">Console</div>
+    </div>
+  `,
+})
+export class VerticalResizableComponent {}
+```
+
+The group flips to `flex-col` automatically for vertical direction, and the handle renders horizontally with an `ns-resize` cursor.
+
+### 4. Constrained + collapsible panels
+
+```html
+<div hlmResizableGroup direction="horizontal" class="tw:h-64 tw:rounded-lg tw:border">
+  <div hlmResizablePanel defaultSize="20" minSize="10" maxSize="40" collapsible class="tw:p-4">
+    Collapsible sidebar (10–40%)
+  </div>
+  <hlm-resizable-handle withHandle />
+  <div hlmResizablePanel defaultSize="80" minSize="30" class="tw:p-4">Main (≥30%)</div>
+</div>
 ```
+
+### 5. Programmatic control via `setSize`
+
+```ts
+import { Component } from '@angular/core';
+import { HlmResizableImports } from '@egose/shadcn-theme-ng/resizable';
+
+@Component({
+  selector: 'app-controlled-resizable',
+  standalone: true,
+  imports: [HlmResizableImports],
+  template: `
+    <div class="tw:mb-2 tw:flex tw:gap-2">
+      <button type="button" (click)="left.setSize(20)">Sidebar 20%</button>
+      <button type="button" (click)="left.setSize(50)">Split 50/50</button>
+    </div>
+    <div hlmResizableGroup direction="horizontal" class="tw:h-64 tw:rounded-lg tw:border">
+      <div hlmResizablePanel #left="hlmResizablePanel" defaultSize="30" class="tw:p-4">Nav</div>
+      <hlm-resizable-handle withHandle />
+      <div hlmResizablePanel defaultSize="70" class="tw:p-4">Content</div>
+    </div>
+  `,
+})
+export class ControlledResizableComponent {}
+```
+
+### 6. Layout events + three-pane IDE layout
+
+```ts
+import { Component, signal } from '@angular/core';
+import { HlmResizableImports } from '@egose/shadcn-theme-ng/resizable';
+
+@Component({
+  selector: 'app-ide-resizable',
+  standalone: true,
+  imports: [HlmResizableImports],
+  template: `
+    <div
+      hlmResizableGroup
+      direction="horizontal"
+      class="tw:h-96 tw:rounded-lg tw:border"
+      (dragStart)="dragging.set(true)"
+      (dragEnd)="dragging.set(false)"
+      (layoutChange)="onLayout($event)"
+    >
+      <div hlmResizablePanel defaultSize="20" minSize="12" collapsible class="tw:p-4">Explorer</div>
+      <hlm-resizable-handle withHandle />
+      <div hlmResizablePanel defaultSize="55" minSize="30" class="tw:p-4">Editor</div>
+      <hlm-resizable-handle />
+      <div hlmResizablePanel defaultSize="25" minSize="15" collapsible class="tw:p-4">Outline</div>
+    </div>
+    @if (dragging()) {
+      <p class="tw:text-muted-foreground tw:text-sm">Resizing…</p>
+    }
+  `,
+})
+export class IdeResizableComponent {
+  readonly dragging = signal(false);
+
+  onLayout(layout: unknown): void {
+    console.log('panel layout:', layout);
+  }
+}
+```
+
+## Accessibility notes
+
+- The drag handle is keyboard-focusable via the underlying `BrnResizableHandle` — ensure handles remain in the tab order (do not set `tabindex="-1"` on them).
+- A handle without `withHandle` is only a 1px strip visually; prefer `withHandle` when pointer users need a bigger grab target, and keep `disabled` handles out of confusing layouts (they still occupy space).
+- Give each region a landmark or label (`role="region"` + `aria-label`, or headings) so screen-reader users understand the pane structure, since drag-to-resize itself is pointer/keyboard driven on the handle.
+
+## Theming / CSS variables
+
+Class-driven only (flex direction, borders, cursors). Size the group with your own height/width utilities — panels size themselves as percentages of it.
+
+## Related subpaths
+
+- `@egose/shadcn-theme-ng/card` — paneled content inside resizable regions
+- `@egose/shadcn-theme-ng/scroll-area` — scrollable overflow inside fixed-size panels
+- `@egose/shadcn-theme-ng/sidebar` — app-level collapsible navigation (alternative to a resizable nav pane)
+- `@egose/shadcn-theme-ng/separator` — static visual dividers where resizing is not needed