@egose/shadcn-theme-ng 0.0.28 → 0.2.0

package/kbd/README.md

@@ -1,11 +1,297 @@
-# Kbd
+# Kbd (`@egose/shadcn-theme-ng/kbd`)
 
-This project was generated using [Angular CLI](https://github.com/angular/angular-cli).
+Keyboard-keycap (`<kbd>`) styling for shortcut hints, ported from shadcn/ui `kbd`. There is no interactive primitive underneath — these are thin presentational directives that attach the shadcn keycap look (muted background, fixed `h-5` height, rounded, mono-adjacent `text-xs` label) plus a grouping row directive for multi-key chords such as `Ctrl + K`.
 
-## Building
+Ships as `@egose/shadcn-theme-ng/kbd` and `@egose/shadcn-theme-ng-tw/kbd` (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 kbd
+# 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) — `@angular/core`, `@angular/common`, `@spartan-ng/brain`, `rxjs`, `@ng-icons/core`). This subpath itself declares `@angular/common`, `@angular/core`, `@spartan-ng/brain` as peers plus a `tslib` runtime dependency. No extra install step is needed beyond the package install above.
+
+## Imports
+
+Real exported symbols (from `src/public-api.ts`):
+
+```ts
+import {
+  HlmKbd, // directive: kbd[hlmKbd]
+  HlmKbdGroup, // directive: kbd[hlmKbdGroup]
+  HlmKbdImports, // readonly [HlmKbd, HlmKbdGroup]
+  HlmKbdModule, // NgModule wrapping HlmKbdImports
+} from '@egose/shadcn-theme-ng/kbd';
+```
+
+Standalone usage:
+
+```ts
+import { Component } from '@angular/core';
+import { HlmKbdImports } from '@egose/shadcn-theme-ng/kbd';
+
+@Component({
+  selector: 'app-demo',
+  standalone: true,
+  imports: [...HlmKbdImports],
+  template: `<kbd hlmKbd>⌘</kbd>`,
+})
+export class DemoComponent {}
+```
+
+NgModule usage:
+
+```ts
+import { NgModule } from '@angular/core';
+import { HlmKbdModule } from '@egose/shadcn-theme-ng/kbd';
+
+@NgModule({ imports: [HlmKbdModule] })
+export class DemoModule {}
+```
+
+For the `tw:` build, swap the specifier to `@egose/shadcn-theme-ng-tw/kbd`. Symbol names are identical.
+
+## Anatomy / Structure
+
+```html
+<!-- Single key -->
+<kbd hlmKbd>Ctrl</kbd>
+
+<!-- Chord / sequence: outer kbd carries the group layout, inner kbds carry keycap styling -->
+<kbd hlmKbdGroup>
+  <kbd hlmKbd>Ctrl</kbd>
+  <span>+</span>
+  <kbd hlmKbd>K</kbd>
+</kbd hlmKbdGroup>
+```
+
+| Class         | Selector           | Element      | Role                                  |
+| ------------- | ------------------ | ------------ | ------------------------------------- |
+| `HlmKbd`      | `kbd[hlmKbd]`      | `<kbd>` only | Single keycap                         |
+| `HlmKbdGroup` | `kbd[hlmKbdGroup]` | `<kbd>` only | Inline-flex row that lays out a chord |
+
+Both selectors require a native `<kbd>` host. Applying `hlmKbd` to a `<span>` or `<div>` will not match and no styles are applied. Both set a `data-slot` host attribute (`kbd` / `kbd-group`) used by downstream tooltip overrides.
+
+## API reference
+
+Neither directive declares any `input()`, `output()`, method, or signal. They are pure styling directives: the constructor calls `classes(() => '…')` from `@egose/shadcn-theme-ng/utils`. All customization is via the host element itself (text content, `class`, `title`, `aria-*`).
+
+| Selector           | Inputs | Outputs | Notes                                                                                                                                                                                                                                                                                                                                                                                                   |
+| ------------------ | ------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `kbd[hlmKbd]`      | —      | —       | `data-slot="kbd"`. Fixed keycap treatment: `h-5 w-fit min-w-5`, `rounded-sm`, `bg-muted text-muted-foreground`, `pointer-events-none select-none`, inline-flex centered. Includes `in-data-[slot=tooltip-content]` overrides so keys stay legible inside tooltips (light and dark). Icon sizing rule `[&_ng-icon:not([class*='text-'])]:text-[length:--spacing(3)]` normalizes bare `ng-icon` children. |
+| `kbd[hlmKbdGroup]` | —      | —       | `data-slot="kbd-group"`. `inline-flex items-center gap-1`. Nest `HlmKbd` keycaps plus literal separators inside.                                                                                                                                                                                                                                                                                        |
+
+## Examples
+
+### 1. Basic single key
+
+A lone keycap next to an action label.
+
+```ts
+import { Component } from '@angular/core';
+import { HlmKbdImports } from '@egose/shadcn-theme-ng/kbd';
+
+@Component({
+  selector: 'app-kbd-basic',
+  standalone: true,
+  imports: [...HlmKbdImports],
+  template: ` <p>Press <kbd hlmKbd>Enter</kbd> to submit.</p> `,
+})
+export class KbdBasicComponent {}
+```
+
+```html
+<p>Press <kbd hlmKbd>Enter</kbd> to submit.</p>
+```
+
+### 2. Keyboard chord (Ctrl + K)
+
+The canonical command-palette hint. The outer `kbd[hlmKbdGroup]` provides the row; inner keycaps provide the boxes.
+
+```ts
+import { Component } from '@angular/core';
+import { HlmKbdImports } from '@egose/shadcn-theme-ng/kbd';
+
+@Component({
+  selector: 'app-kbd-chord',
+  standalone: true,
+  imports: [...HlmKbdImports],
+  template: `
+    <div class="tw:flex tw:items-center tw:gap-2 tw:text-sm tw:text-muted-foreground">
+      <span>Search</span>
+      <kbd hlmKbdGroup>
+        <kbd hlmKbd>Ctrl</kbd>
+        <span>+</span>
+        <kbd hlmKbd>K</kbd>
+      </kbd>
+    </div>
+  `,
+})
+export class KbdChordComponent {}
+```
+
+```html
+<div class="tw:flex tw:items-center tw:gap-2 tw:text-sm tw:text-muted-foreground">
+  <span>Search</span>
+  <kbd hlmKbdGroup>
+    <kbd hlmKbd>Ctrl</kbd>
+    <span>+</span>
+    <kbd hlmKbd>K</kbd>
+  </kbd>
+</div>
+```
+
+### 3. macOS-style symbols and sequences
+
+```ts
+import { Component } from '@angular/core';
+import { HlmKbdImports } from '@egose/shadcn-theme-ng/kbd';
+
+@Component({
+  selector: 'app-kbd-symbols',
+  standalone: true,
+  imports: [...HlmKbdImports],
+  template: `
+    <ul class="tw:flex tw:flex-col tw:gap-2 tw:text-sm">
+      <li class="tw:flex tw:items-center tw:gap-2">
+        <span class="tw:w-32">Copy</span>
+        <kbd hlmKbdGroup><kbd hlmKbd>⌘</kbd><span>+</span><kbd hlmKbd>C</kbd></kbd>
+      </li>
+      <li class="tw:flex tw:items-center tw:gap-2">
+        <span class="tw:w-32">Save</span>
+        <kbd hlmKbdGroup><kbd hlmKbd>⌘</kbd><span>+</span><kbd hlmKbd>S</kbd></kbd>
+      </li>
+      <li class="tw:flex tw:items-center tw:gap-2">
+        <span class="tw:w-32">Close window</span>
+        <kbd hlmKbdGroup>
+          <kbd hlmKbd>⌘</kbd><span>+</span><kbd hlmKbd>Shift</kbd><span>+</span><kbd hlmKbd>W</kbd>
+        </kbd>
+      </li>
+    </ul>
+  `,
+})
+export class KbdSymbolsComponent {}
+```
+
+### 4. Inside buttons, inputs, and menus
+
+Keycaps are `pointer-events-none`, so they compose safely inside interactive parents.
+
+```ts
+import { Component } from '@angular/core';
+import { HlmKbdImports } from '@egose/shadcn-theme-ng/kbd';
+import { HlmButtonImports } from '@egose/shadcn-theme-ng/button';
+import { HlmInput } from '@egose/shadcn-theme-ng/input';
+
+@Component({
+  selector: 'app-kbd-composed',
+  standalone: true,
+  imports: [...HlmKbdImports, ...HlmButtonImports, HlmInput],
+  template: `
+    <div class="tw:flex tw:flex-col tw:gap-3 tw:max-w-sm">
+      <button hlmButton variant="secondary" appearance="outline" type="button">
+        <span>Command palette</span>
+        <kbd hlmKbdGroup class="tw:ml-auto">
+          <kbd hlmKbd>Ctrl</kbd>
+          <span>+</span>
+          <kbd hlmKbd>K</kbd>
+        </kbd>
+      </button>
+
+      <label class="tw:flex tw:flex-col tw:gap-1 tw:text-sm">
+        <span class="tw:flex tw:items-center tw:gap-2"> Search <kbd hlmKbd>/</kbd> </span>
+        <input hlmInput placeholder="Type here, or press / to focus" />
+      </label>
+    </div>
+  `,
+})
+export class KbdComposedComponent {}
+```
+
+### 5. Shortcut legend / settings table
+
+```ts
+import { Component, signal } from '@angular/core';
+import { HlmKbdImports } from '@egose/shadcn-theme-ng/kbd';
+
+interface Shortcut {
+  action: string;
+  keys: string[];
+}
+
+@Component({
+  selector: 'app-kbd-legend',
+  standalone: true,
+  imports: [...HlmKbdImports],
+  template: `
+    <table class="tw:w-full tw:text-sm">
+      <tbody>
+        @for (s of shortcuts(); track s.action) {
+          <tr class="tw:border-b">
+            <td class="tw:py-2">{{ s.action }}</td>
+            <td class="tw:py-2 tw:text-right">
+              <kbd hlmKbdGroup class="tw:justify-end">
+                @for (k of s.keys; track k; let last = $last) {
+                  <kbd hlmKbd>{{ k }}</kbd>
+                  @if (!last) {
+                    <span>+</span>
+                  }
+                }
+              </kbd>
+            </td>
+          </tr>
+        }
+      </tbody>
+    </table>
+  `,
+})
+export class KbdLegendComponent {
+  readonly shortcuts = signal<Shortcut[]>([
+    { action: 'Undo', keys: ['Ctrl', 'Z'] },
+    { action: 'Redo', keys: ['Ctrl', 'Shift', 'Z'] },
+    { action: 'Toggle sidebar', keys: ['Ctrl', 'B'] },
+  ]);
+}
+```
+
+### 6. NgModule consumer
+
+```ts
+import { NgModule, Component } from '@angular/core';
+import { HlmKbdModule } from '@egose/shadcn-theme-ng/kbd';
+
+@Component({
+  selector: 'app-kbd-legacy',
+  template: `<kbd hlmKbd>Esc</kbd> to close.`,
+})
+export class KbdLegacyComponent {}
+
+@NgModule({
+  declarations: [KbdLegacyComponent],
+  imports: [HlmKbdModule],
+  exports: [KbdLegacyComponent],
+})
+export class KbdLegacyModule {}
+```
+
+## Accessibility notes
+
+- `<kbd>` is natively semantic ("keyboard input"). Keep the text content exactly what the user presses (`Ctrl`, not `Control` unless that is the label on the keyboard).
+- For chords, screen readers linearize the group content; the `+` separators are announced. If verbosity matters, add an `aria-label` on the group (e.g. `aria-label="Control plus K"`) — plain HTML, no library input needed.
+- Do not put interactive content inside a keycap: `HlmKbd` is `pointer-events-none` by design.
+- `title`/`aria-keyshortcuts` belong on the _action_ that the shortcut triggers (e.g. the button), not on the `<kbd>` itself.
+
+## Theming / CSS variables
+
+No component inputs. Styling keys off shadcn semantic tokens (`bg-muted`, `text-muted-foreground`, `bg-background` inside tooltip content) so dark mode and theme overrides flow through automatically. Add extra utilities via `class` on the host `<kbd>` (merged by the `classes()` helper).
+
+## Related subpaths
+
+- `@egose/shadcn-theme-ng/tooltip` — keycaps render legibly inside tooltip content via the built-in `in-data-[slot=tooltip-content]` overrides.
+- `@egose/shadcn-theme-ng/menu` (`HlmMenuShortcut`) — right-aligned shortcut column inside menus; use `kbd` keycaps inside it for key chords.
+- `@egose/shadcn-theme-ng/button`, `@egose/shadcn-theme-ng/input` — common parents for inline shortcut hints.

package/kbd/fesm2022/kbd.mjs

@@ -6,10 +6,10 @@ class HlmKbd {
     constructor() {
         classes(() => "bg-muted text-muted-foreground in-data-[slot=tooltip-content]:bg-background/20 in-data-[slot=tooltip-content]:text-background dark:in-data-[slot=tooltip-content]:bg-background/10 h-5 w-fit min-w-5 gap-1 rounded-sm px-1 font-sans text-xs font-medium [&_ng-icon:not([class*='text-'])]:text-[length:--spacing(3)] pointer-events-none inline-flex items-center justify-center select-none");
     }
-    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "22.0.7", ngImport: i0, type: HlmKbd, deps: [], target: i0.ɵɵFactoryTarget.Directive });
-    static ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "14.0.0", version: "22.0.7", type: HlmKbd, isStandalone: true, selector: "kbd[hlmKbd]", host: { attributes: { "data-slot": "kbd" } }, ngImport: i0 });
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "22.1.3", ngImport: i0, type: HlmKbd, deps: [], target: i0.ɵɵFactoryTarget.Directive });
+    static ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "14.0.0", version: "22.1.3", type: HlmKbd, isStandalone: true, selector: "kbd[hlmKbd]", host: { attributes: { "data-slot": "kbd" } }, ngImport: i0 });
 }
-i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.0.7", ngImport: i0, type: HlmKbd, decorators: [{
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.1.3", ngImport: i0, type: HlmKbd, decorators: [{
             type: Directive,
             args: [{
                     selector: 'kbd[hlmKbd]',
@@ -21,12 +21,12 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.0.7", ngImpor
 
 class HlmKbdGroup {
     constructor() {
-        classes(() => 'gap-1 inline-flex items-center');
+        classes(() => "gap-1 inline-flex items-center");
     }
-    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "22.0.7", ngImport: i0, type: HlmKbdGroup, deps: [], target: i0.ɵɵFactoryTarget.Directive });
-    static ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "14.0.0", version: "22.0.7", type: HlmKbdGroup, isStandalone: true, selector: "kbd[hlmKbdGroup]", host: { attributes: { "data-slot": "kbd-group" } }, ngImport: i0 });
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "22.1.3", ngImport: i0, type: HlmKbdGroup, deps: [], target: i0.ɵɵFactoryTarget.Directive });
+    static ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "14.0.0", version: "22.1.3", type: HlmKbdGroup, isStandalone: true, selector: "kbd[hlmKbdGroup]", host: { attributes: { "data-slot": "kbd-group" } }, ngImport: i0 });
 }
-i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.0.7", ngImport: i0, type: HlmKbdGroup, decorators: [{
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.1.3", ngImport: i0, type: HlmKbdGroup, decorators: [{
             type: Directive,
             args: [{
                     selector: 'kbd[hlmKbdGroup]',
@@ -41,11 +41,11 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.0.7", ngImpor
  */
 const HlmKbdImports = [HlmKbd, HlmKbdGroup];
 class HlmKbdModule {
-    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "22.0.7", ngImport: i0, type: HlmKbdModule, deps: [], target: i0.ɵɵFactoryTarget.NgModule });
-    static ɵmod = i0.ɵɵngDeclareNgModule({ minVersion: "14.0.0", version: "22.0.7", ngImport: i0, type: HlmKbdModule, imports: [HlmKbd, HlmKbdGroup], exports: [HlmKbd, HlmKbdGroup] });
-    static ɵinj = i0.ɵɵngDeclareInjector({ minVersion: "12.0.0", version: "22.0.7", ngImport: i0, type: HlmKbdModule });
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "22.1.3", ngImport: i0, type: HlmKbdModule, deps: [], target: i0.ɵɵFactoryTarget.NgModule });
+    static ɵmod = i0.ɵɵngDeclareNgModule({ minVersion: "14.0.0", version: "22.1.3", ngImport: i0, type: HlmKbdModule, imports: [HlmKbd, HlmKbdGroup], exports: [HlmKbd, HlmKbdGroup] });
+    static ɵinj = i0.ɵɵngDeclareInjector({ minVersion: "12.0.0", version: "22.1.3", ngImport: i0, type: HlmKbdModule });
 }
-i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.0.7", ngImport: i0, type: HlmKbdModule, decorators: [{
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.1.3", ngImport: i0, type: HlmKbdModule, decorators: [{
             type: NgModule,
             args: [{
                     imports: [...HlmKbdImports],
@@ -58,4 +58,4 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.0.7", ngImpor
  */
 
 export { HlmKbd, HlmKbdGroup, HlmKbdImports, HlmKbdModule };
-//# sourceMappingURL=kbd.mjs.map
+

package/label/README.md

@@ -1,64 +1,273 @@
-# Label
+# Label (`@egose/shadcn-theme-ng/label`)
 
-This project was generated using [Angular CLI](https://github.com/angular/angular-cli) version 20.2.0.
+Form-field label ported from shadcn/ui `label` (Radix Label equivalent). A thin directive wrapper around the spartan-ng `BrnLabel` brain primitive: it forwards label semantics/association (`id`, `for`) to `BrnLabel` via host directives and adds the shadcn label treatment (small medium-weight text plus disabled-state dimming that reacts to `peer`/`group`/`has-[[disabled]]` context).
 
-## Code scaffolding
+Ships as `@egose/shadcn-theme-ng/label` and `@egose/shadcn-theme-ng-tw/label` (tw: variant). See the [package README](../../README.md) for installation, peer dependencies, Tailwind setup, and testing. Do not publish this project directory independently.
 
-Angular CLI includes powerful code scaffolding tools. To generate a new component, run:
+## Installation
 
 ```bash
-ng generate component component-name
+# Plain Tailwind (no prefix):
+npm install @egose/shadcn-theme-ng
+
+# Or the tw:-prefixed variant:
+npm install @egose/shadcn-theme-ng-tw
 ```
 
-For a complete list of available schematics (such as `components`, `directives`, or `pipes`), run:
+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. No extra install step is needed beyond the package install above.
 
-```bash
-ng generate --help
+## Imports
+
+Real exported symbols (from `src/public-api.ts`):
+
+```ts
+import {
+  HlmLabel, // directive: [hlmLabel]
+  HlmLabelImports, // readonly [HlmLabel]
+  HlmLabelModule, // NgModule wrapping HlmLabelImports
+} from '@egose/shadcn-theme-ng/label';
 ```
 
-## Building
+Standalone usage:
 
-To build the library, run:
+```ts
+import { Component } from '@angular/core';
+import { HlmLabelImports } from '@egose/shadcn-theme-ng/label';
 
-```bash
-ng build label
+@Component({
+  selector: 'app-demo',
+  standalone: true,
+  imports: [...HlmLabelImports],
+  template: `<label hlmLabel for="email">Email</label>`,
+})
+export class DemoComponent {}
 ```
 
-This command will compile your project, and the build artifacts will be placed in the `dist/` directory.
+NgModule usage:
 
-### Publishing the Library
+```ts
+import { NgModule } from '@angular/core';
+import { HlmLabelModule } from '@egose/shadcn-theme-ng/label';
 
-Once the project is built, you can publish your library by following these steps:
+@NgModule({ imports: [HlmLabelModule] })
+export class DemoModule {}
+```
 
-1. Navigate to the `dist` directory:
+For the `tw:` build, swap the specifier to `@egose/shadcn-theme-ng-tw/label`. Symbol names are identical.
 
-   ```bash
-   cd dist/label
-   ```
+## Anatomy / Structure
 
-2. Run the `npm publish` command to publish your library to the npm registry:
-   ```bash
-   npm publish
-   ```
+```html
+<label hlmLabel for="email">Email address</label>
+<input hlmInput id="email" type="email" />
 
-## Running unit tests
+<!-- extra classes merge via class input -->
+<label hlmLabel for="bio" class="tw:mb-2">Bio</label>
+```
 
-To execute unit tests with the [Karma](https://karma-runner.github.io) test runner, use the following command:
+| Class      | Selector     | Element                                | Role                              |
+| ---------- | ------------ | -------------------------------------- | --------------------------------- |
+| `HlmLabel` | `[hlmLabel]` | any labelable host, normally `<label>` | Accessible label + shadcn styling |
 
-```bash
-ng test
+`HlmLabel` declares `hostDirectives: [{ directive: BrnLabel, inputs: ['id', 'for'] }]`, so the `id` and `for` bindings you write on the host are forwarded to the brain directive that owns label association.
+
+## API reference
+
+### `HlmLabel` (`[hlmLabel]`)
+
+| Member                | Kind                                  | Type / Default             | Notes                                                                                                                                                                                                                                                                                                                                                                                                  |
+| --------------------- | ------------------------------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `id`                  | input (via `BrnLabel` host directive) | `string`                   | Forwarded to `BrnLabel`. Rarely set on the label itself.                                                                                                                                                                                                                                                                                                                                               |
+| `for`                 | input (via `BrnLabel` host directive) | `string`                   | Forwarded to `BrnLabel`. Associates the label with the control whose `id` matches.                                                                                                                                                                                                                                                                                                                     |
+| `userClass` (`class`) | input                                 | `ClassValue`, default `''` | Extra Tailwind/classes merged after the base label classes via `hlm()`.                                                                                                                                                                                                                                                                                                                                |
+| `_computedClass`      | protected computed                    | `string`                   | Base: `flex select-none items-center gap-2 text-sm font-medium leading-none` plus disabled dimming: `peer-disabled:cursor-not-allowed peer-disabled:opacity-50`, `has-[[disabled]]:cursor-not-allowed has-[[disabled]]:opacity-50`, `group-data-[disabled=true]:pointer-events-none group-data-[disabled=true]:opacity-50`, `peer-data-[disabled]:cursor-not-allowed peer-data-[disabled]:opacity-50`. |
+
+No outputs, methods, or signals beyond the inputs above.
+
+## Examples
+
+### 1. Basic label + input
+
+```ts
+import { Component } from '@angular/core';
+import { HlmLabelImports } from '@egose/shadcn-theme-ng/label';
+import { HlmInput } from '@egose/shadcn-theme-ng/input';
+
+@Component({
+  selector: 'app-label-basic',
+  standalone: true,
+  imports: [...HlmLabelImports, HlmInput],
+  template: `
+    <div class="tw:grid tw:gap-1.5">
+      <label hlmLabel for="email">Email</label>
+      <input hlmInput id="email" type="email" placeholder="you@example.com" />
+    </div>
+  `,
+})
+export class LabelBasicComponent {}
 ```
 
-## Running end-to-end tests
+```html
+<div class="tw:grid tw:gap-1.5">
+  <label hlmLabel for="email">Email</label>
+  <input hlmInput id="email" type="email" placeholder="you@example.com" />
+</div>
+```
 
-For end-to-end (e2e) testing, run:
+### 2. Required marker and hint text
 
-```bash
-ng e2e
+```ts
+import { Component } from '@angular/core';
+import { HlmLabelImports } from '@egose/shadcn-theme-ng/label';
+import { HlmInput } from '@egose/shadcn-theme-ng/input';
+
+@Component({
+  selector: 'app-label-required',
+  standalone: true,
+  imports: [...HlmLabelImports, HlmInput],
+  template: `
+    <div class="tw:grid tw:gap-1.5">
+      <label hlmLabel for="username">
+        Username
+        <span aria-hidden="true" class="tw:text-destructive">*</span>
+        <span class="tw:sr-only">(required)</span>
+      </label>
+      <input hlmInput id="username" required minlength="3" placeholder="ada_lovelace" />
+      <p class="tw:text-xs tw:text-muted-foreground">Lowercase letters, numbers, underscores.</p>
+    </div>
+  `,
+})
+export class LabelRequiredComponent {}
+```
+
+### 3. Template-driven form
+
+```ts
+import { Component } from '@angular/core';
+import { FormsModule } from '@angular/forms';
+import { HlmLabelImports } from '@egose/shadcn-theme-ng/label';
+import { HlmInput } from '@egose/shadcn-theme-ng/input';
+
+@Component({
+  selector: 'app-label-template-driven',
+  standalone: true,
+  imports: [FormsModule, ...HlmLabelImports, HlmInput],
+  template: `
+    <form #f="ngForm" class="tw:grid tw:gap-4">
+      <div class="tw:grid tw:gap-1.5">
+        <label hlmLabel for="displayName">Display name</label>
+        <input hlmInput id="displayName" name="displayName" [(ngModel)]="name" required />
+      </div>
+      <p class="tw:text-sm tw:text-muted-foreground">Hello, {{ name || 'stranger' }}.</p>
+    </form>
+  `,
+})
+export class LabelTemplateDrivenComponent {
+  name = '';
+}
 ```
 
-Angular CLI does not come with an end-to-end testing framework by default. You can choose one that suits your needs.
+### 4. Reactive form with disabled state
+
+The label dims automatically when the associated control is a disabled `peer` (or inside a disabled group) thanks to the built-in `peer-disabled:` / `group-data-[disabled=true]:` rules.
+
+```ts
+import { Component } from '@angular/core';
+import { ReactiveFormsModule, FormControl, FormGroup } from '@angular/forms';
+import { HlmLabelImports } from '@egose/shadcn-theme-ng/label';
+import { HlmInput } from '@egose/shadcn-theme-ng/input';
+
+@Component({
+  selector: 'app-label-reactive',
+  standalone: true,
+  imports: [ReactiveFormsModule, ...HlmLabelImports, HlmInput],
+  template: `
+    <form [formGroup]="form" class="tw:grid tw:gap-4">
+      <div class="tw:grid tw:gap-1.5">
+        <label hlmLabel for="company">Company</label>
+        <input hlmInput id="company" class="tw:peer" formControlName="company" />
+      </div>
+      <label class="tw:flex tw:items-center tw:gap-2 tw:text-sm">
+        <input type="checkbox" (change)="toggleDisabled()" />
+        Disable company field
+      </label>
+    </form>
+  `,
+})
+export class LabelReactiveComponent {
+  readonly form = new FormGroup({
+    company: new FormControl({ value: 'Acme', disabled: false }),
+  });
+
+  toggleDisabled(): void {
+    const control = this.form.controls.company;
+    control.disabled ? control.enable() : control.disable();
+  }
+}
+```
+
+> Add `class="tw:peer"` to the input so the label's `peer-disabled:` rule can observe it. Without the `peer` class the label still dims via the `has-[[disabled]]` fallback when the control is nested in the same wrapper.
+
+### 5. Checkbox / switch labels and custom spacing
+
+```ts
+import { Component } from '@angular/core';
+import { HlmLabelImports } from '@egose/shadcn-theme-ng/label';
+import { HlmCheckbox } from '@egose/shadcn-theme-ng/checkbox';
+import { HlmSwitch } from '@egose/shadcn-theme-ng/switch';
+
+@Component({
+  selector: 'app-label-checks',
+  standalone: true,
+  imports: [...HlmLabelImports, HlmCheckbox, HlmSwitch],
+  template: `
+    <div class="tw:flex tw:flex-col tw:gap-4">
+      <div class="tw:flex tw:items-center tw:gap-2">
+        <hlm-checkbox id="marketing" />
+        <label hlmLabel for="marketing" class="tw:cursor-pointer">Email me product news</label>
+      </div>
+      <div class="tw:flex tw:items-center tw:gap-2">
+        <hlm-switch id="notifications" />
+        <label hlmLabel for="notifications">Push notifications</label>
+      </div>
+    </div>
+  `,
+})
+export class LabelChecksComponent {}
+```
+
+### 6. NgModule consumer
+
+```ts
+import { NgModule, Component } from '@angular/core';
+import { HlmLabelModule } from '@egose/shadcn-theme-ng/label';
+
+@Component({
+  selector: 'app-label-legacy',
+  template: `<label hlmLabel for="city">City</label>`,
+})
+export class LabelLegacyComponent {}
+
+@NgModule({
+  declarations: [LabelLegacyComponent],
+  imports: [HlmLabelModule],
+  exports: [LabelLegacyComponent],
+})
+export class LabelLegacyModule {}
+```
+
+## Accessibility notes
+
+- Always pair `for` with the control's `id` (or nest the control inside the `<label>`). The `for` binding is forwarded to `BrnLabel`, which owns the association semantics.
+- Keep label text visible and concise; use `aria-hidden` + `sr-only` for decorative markers like `*` (see example 2).
+- Do not use `placeholder` as a label substitute — the shadcn label treatment assumes a real `<label>` element.
+- The disabled dimming is visual only; disable the control itself (`disabled` attribute / `FormControl.disable()`) so assistive tech reports the state.
+
+## Theming / CSS variables
+
+No theming inputs. The label inherits `text-sm font-medium` and theme tokens automatically; pass extra utilities via `class` (merged by `hlm()` after the base classes, so yours win on conflict).
 
-## Additional Resources
+## Related subpaths
 
-For more information on using the Angular CLI, including detailed command references, visit the [Angular CLI Overview and Command Reference](https://angular.dev/tools/cli) page.
+- `@egose/shadcn-theme-ng/input`, `@egose/shadcn-theme-ng/textarea`, `@egose/shadcn-theme-ng/checkbox`, `@egose/shadcn-theme-ng/switch` — controls that `for`/`id` pairs target.
+- `@egose/shadcn-theme-ng/form-field`, `@egose/shadcn-theme-ng/form-field-simple` — higher-level field wrappers that compose labels with errors and hints.