@egose/shadcn-theme-ng 0.1.0 → 0.2.0

package/confirmation-dialog/README.md

@@ -1,3 +1,302 @@
-# Confirmation Dialog Subpath
+# Confirmation Dialog (`@egose/shadcn-theme-ng/confirmation-dialog`)
 
-This project ships only as `@egose/shadcn-theme-ng/confirmation-dialog` or `@egose/shadcn-theme-ng-tw/confirmation-dialog`. See the [package README](../../README.md) for installation, compatibility, Tailwind variant, test, and release guidance. Do not publish this project directory independently.
+A promise-based "Are you sure?" modal — the Angular equivalent of a shadcn/ui `AlertDialog` confirmation shortcut. Instead of composing dialog primitives by hand, you call `EgConfirmationDialogService.showConfirmationDialog({ title, description })` and `await` a `Promise<boolean>` (`true` = Confirm, `false` = Cancel/dismiss). The rendered `EgConfirmationDialog` component itself (warning icon + title + description + Cancel/Confirm footer) is opened through `HlmDialogService` from `@egose/shadcn-theme-ng/dialog` with a `BrnDialogRef<boolean>` result. There is no `*Imports` array and no `*Module` — the public surface is the component, the service, and a deprecated misspelled alias.
+
+Ships as `@egose/shadcn-theme-ng/confirmation-dialog` and `@egose/shadcn-theme-ng-tw/confirmation-dialog` (the `tw:`-prefixed variant). See the [package README](../../README.md) for install, peer dependencies, and Tailwind setup. Do not publish this project directory independently — it is consumed via the published subpath only.
+
+## Installation
+
+```bash
+# Plain Tailwind (no prefix):
+npm install @egose/shadcn-theme-ng
+
+# Or the tw:-prefixed variant:
+npm install @egose/shadcn-theme-ng-tw
+```
+
+Peers are listed in the [package README](../../README.md). This subpath declares `@angular/common` and `@angular/core` as peers (see `projects/confirmation-dialog/package.json`); at runtime it uses `@egose/shadcn-theme-ng/dialog`, `button`, `alert`, and `icon`, so install the whole package.
+
+## Imports
+
+The public API (`projects/confirmation-dialog/src/public-api.ts`) exports exactly:
+
+```ts
+import {
+  EgConfirmationDialog,
+  EgConfirmationDialogService,
+  // Deprecated misspelled alias (type + const) — do not use in new code:
+  EgConfirmationDiaglog,
+} from '@egose/shadcn-theme-ng/confirmation-dialog';
+// tw variant:
+// import { ... } from '@egose/shadcn-theme-ng-tw/confirmation-dialog';
+```
+
+There is no `EgConfirmationDialogImports` and no `EgConfirmationDialogModule`. The service is `@Injectable({ providedIn: 'root' })` — just inject it:
+
+```ts
+import { Component, inject } from '@angular/core';
+import { EgConfirmationDialogService } from '@egose/shadcn-theme-ng/confirmation-dialog';
+
+@Component({ selector: 'app-demo', standalone: true, template: `...` })
+export class DemoComponent {
+  private readonly confirm = inject(EgConfirmationDialogService);
+}
+```
+
+> `EgConfirmationDiaglog` (missing the second `a`) is a deprecated type+const alias for `EgConfirmationDialog` kept for back-compat. It will be removed in the next major release — use the correctly spelled name.
+
+## Anatomy / Structure
+
+You never write the dialog markup yourself — the service opens this fixed template:
+
+```html
+<!-- Rendered by EgConfirmationDialog (fixed internal template) -->
+<hlm-dialog-header>
+  <div class="tw:flex tw:items-center tw:gap-1">
+    <ng-icon hlm hlmAlertIcon name="lucideTriangleAlert" size="base" />
+    <h3 hlmDialogTitle>{{ title }}</h3>
+  </div>
+  <p hlmDialogDescription>{{ description }}</p>
+</hlm-dialog-header>
+
+<hlm-dialog-footer>
+  <button hlmButton variant="secondary" appearance="outline">Cancel</button>
+  <button hlmButton variant="danger">Confirm</button>
+</hlm-dialog-footer>
+```
+
+- `EgConfirmationDialog` has **no selector** — it is instantiated by `HlmDialogService.open<boolean>(EgConfirmationDialog, { context: { title, description } })`.
+- Title/description fall back to `'Are you absolutely sure?'` / `'This action cannot be undone.'` when the context omits them.
+- `close(confirm: boolean)` closes the `BrnDialogRef<boolean>` with the result; Cancel resolves `false`, Confirm resolves `true`, and dismissing (X / backdrop / Escape) resolves `false` via `closed$ ?? false`.
+
+## API reference
+
+### `EgConfirmationDialogService`
+
+`@Injectable({ providedIn: 'root' })`, constructor-injects `HlmDialogService`.
+
+| Method                   | Signature                                                                              | Description                                                                                        |
+| ------------------------ | -------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
+| `showConfirmationDialog` | `({ title, description }: { title: string; description: string }) => Promise<boolean>` | Opens the modal with the given copy; resolves `true` on Confirm, `false` on Cancel or any dismiss. |
+
+Implementation detail: subscribes to `dialogRef.closed$` once per call and resolves `confirm ?? false`.
+
+### `EgConfirmationDialog`
+
+Standalone component (no selector), opened via the dialog service.
+
+| Member  | Type                         | Description                                                                                 |
+| ------- | ---------------------------- | ------------------------------------------------------------------------------------------- |
+| `close` | `(confirm: boolean) => void` | Closes the dialog with the boolean result. Wired to the two footer buttons in the template. |
+
+Reads `{ title, description }` from `injectBrnDialogContext()`.
+
+## Examples
+
+### 1. Basic delete confirmation (`async/await`)
+
+```ts
+import { Component, inject } from '@angular/core';
+import { EgConfirmationDialogService } from '@egose/shadcn-theme-ng/confirmation-dialog';
+
+@Component({
+  selector: 'app-delete-button',
+  standalone: true,
+  template: `<button type="button" (click)="onDelete()">Delete project</button>`,
+})
+export class DeleteButtonComponent {
+  private readonly confirm = inject(EgConfirmationDialogService);
+
+  async onDelete() {
+    const ok = await this.confirm.showConfirmationDialog({
+      title: 'Delete project?',
+      description: 'This will permanently delete the project and all of its data.',
+    });
+    if (ok) {
+      console.log('deleting…');
+    }
+  }
+}
+```
+
+### 2. Promise-chain style (no `async`)
+
+```ts
+import { Component, inject } from '@angular/core';
+import { EgConfirmationDialogService } from '@egose/shadcn-theme-ng/confirmation-dialog';
+
+@Component({
+  selector: 'app-leave-page',
+  standalone: true,
+  template: `<button type="button" (click)="leave()">Discard changes</button>`,
+})
+export class LeavePageComponent {
+  private readonly confirm = inject(EgConfirmationDialogService);
+
+  leave() {
+    this.confirm
+      .showConfirmationDialog({
+        title: 'Discard unsaved changes?',
+        description: 'Your edits will be lost if you leave this page.',
+      })
+      .then((ok) => {
+        if (ok) console.log('navigating away…');
+      });
+  }
+}
+```
+
+### 3. Destructive row action in a table
+
+Each row awaits its own confirmation before mutating the list.
+
+```ts
+import { Component, inject, signal } from '@angular/core';
+import { EgConfirmationDialogService } from '@egose/shadcn-theme-ng/confirmation-dialog';
+
+interface Member {
+  id: number;
+  name: string;
+}
+
+@Component({
+  selector: 'app-members-table',
+  standalone: true,
+  template: `
+    <ul>
+      @for (m of members(); track m.id) {
+        <li class="flex items-center justify-between py-1">
+          <span>{{ m.name }}</span>
+          <button type="button" (click)="remove(m)">Remove</button>
+        </li>
+      }
+    </ul>
+  `,
+})
+export class MembersTableComponent {
+  private readonly confirm = inject(EgConfirmationDialogService);
+  readonly members = signal<Member[]>([
+    { id: 1, name: 'Ada' },
+    { id: 2, name: 'Grace' },
+  ]);
+
+  async remove(m: Member) {
+    const ok = await this.confirm.showConfirmationDialog({
+      title: `Remove ${m.name}?`,
+      description: `${m.name} will lose access immediately. You can re-invite them later.`,
+    });
+    if (ok) this.members.update((ms) => ms.filter((x) => x.id !== m.id));
+  }
+}
+```
+
+### 4. Guarding a reactive form reset
+
+```ts
+import { Component, inject } from '@angular/core';
+import { FormControl, FormGroup, ReactiveFormsModule } from '@angular/forms';
+import { EgConfirmationDialogService } from '@egose/shadcn-theme-ng/confirmation-dialog';
+
+@Component({
+  selector: 'app-settings-form',
+  standalone: true,
+  imports: [ReactiveFormsModule],
+  template: `
+    <form [formGroup]="form">
+      <input formControlName="name" placeholder="Workspace name" />
+      <button type="button" (click)="reset()">Reset to defaults</button>
+    </form>
+  `,
+})
+export class SettingsFormComponent {
+  private readonly confirm = inject(EgConfirmationDialogService);
+  readonly form = new FormGroup({ name: new FormControl('acme') });
+
+  async reset() {
+    if (this.form.pristine) return;
+    const ok = await this.confirm.showConfirmationDialog({
+      title: 'Reset settings?',
+      description: 'All fields return to their default values.',
+    });
+    if (ok) this.form.reset({ name: 'acme' });
+  }
+}
+```
+
+### 5. Sequential confirmations (two-step destructive flow)
+
+Await twice — e.g. confirm scope, then confirm irreversibility.
+
+```ts
+import { Component, inject } from '@angular/core';
+import { EgConfirmationDialogService } from '@egose/shadcn-theme-ng/confirmation-dialog';
+
+@Component({
+  selector: 'app-purge-flow',
+  standalone: true,
+  template: `<button type="button" (click)="purge()">Purge organization</button>`,
+})
+export class PurgeFlowComponent {
+  private readonly confirm = inject(EgConfirmationDialogService);
+
+  async purge() {
+    const step1 = await this.confirm.showConfirmationDialog({
+      title: 'Purge all data?',
+      description: 'This affects every project in the organization.',
+    });
+    if (!step1) return;
+
+    const step2 = await this.confirm.showConfirmationDialog({
+      title: 'Are you absolutely sure?',
+      description: 'This action cannot be undone. Backups are deleted too.',
+    });
+    if (step2) console.log('purging…');
+  }
+}
+```
+
+### 6. Opening the component directly (custom dialog options)
+
+If you need non-default dialog chrome (different `contentClass`, close behavior), bypass the service and use `HlmDialogService` with `EgConfirmationDialog` directly.
+
+```ts
+import { Component, inject } from '@angular/core';
+import { EgConfirmationDialog } from '@egose/shadcn-theme-ng/confirmation-dialog';
+import { HlmDialogService } from '@egose/shadcn-theme-ng/dialog';
+
+@Component({
+  selector: 'app-custom-open',
+  standalone: true,
+  template: `<button type="button" (click)="open()">Review defaults</button>`,
+})
+export class CustomOpenComponent {
+  private readonly dialogs = inject(HlmDialogService);
+
+  open() {
+    // No title/description → component falls back to its default copy.
+    const ref = this.dialogs.open<boolean>(EgConfirmationDialog, {
+      context: { title: '', description: '' },
+      contentClass: 'sm:max-w-md',
+    });
+    ref.closed$.subscribe((ok) => console.log('result:', ok ?? false));
+  }
+}
+```
+
+## Accessibility notes
+
+- The dialog uses the standard `hlm-dialog` primitives (`hlmDialogTitle` + `hlmDialogDescription`), so screen readers announce title/description on open and focus is trapped/moved per the dialog service.
+- Confirm is styled `variant="danger"` and Cancel `variant="secondary" appearance="outline"` — the safe action is visually distinct; keyboard order is Cancel → Confirm.
+- Dismiss (Escape/backdrop/X) resolves `false` — the destructive path always requires an explicit Confirm click.
+- Keep `title`/`description` specific ("Delete 'Q3 report'?") rather than generic so SR users hear the consequence without surrounding context.
+
+## Theming / CSS variables
+
+No component-specific CSS variables. The icon uses `hlmAlertIcon` (warning treatment), the title is `text-xl`, the description `text-base text-gray-700`, and the footer is `mt-4`. Buttons follow the shared `hlmButton` `secondary`/`danger` variants in both themes.
+
+## Related subpaths
+
+- `@egose/shadcn-theme-ng/dialog` — `HlmDialogService.open`, title/description/footer primitives behind this shortcut.
+- `@egose/shadcn-theme-ng/alert-dialog` — fully custom alert dialogs when you need your own buttons/copy/layout.
+- `@egose/shadcn-theme-ng/button` — `secondary`/`danger` variants used by the footer.
+- `@egose/shadcn-theme-ng/alert` — `HlmAlertIcon` warning treatment for the header icon.

package/context-menu/README.md

@@ -1,11 +1,372 @@
-# ContextMenu
+# Context Menu (`@egose/shadcn-theme-ng/context-menu`)
 
-This project was generated using [Angular CLI](https://github.com/angular/angular-cli).
+A right-click menu trigger — the Angular port of shadcn/ui `Context Menu`. The entire subpath is one thin directive, `HlmContextMenuTrigger` (`[hlmContextMenuTrigger]`), which wraps the CDK `CdkContextMenuTrigger` and positions a shared menu panel via `@spartan-ng/brain/core` (`createMenuPosition`, `MENU_SIDE`). The visible menu content itself is **not** in this package — you render it with `@egose/shadcn-theme-ng/dropdown-menu` (or `menu`) primitives; this directive only owns the right-click anchoring, `align`/`side` placement, `disabled` locking, and open/close outputs.
 
-## Building
+Ships as `@egose/shadcn-theme-ng/context-menu` and `@egose/shadcn-theme-ng-tw/context-menu` (the `tw:`-prefixed variant). See the [package README](../../README.md) for install, peer dependencies, and Tailwind setup. Do not publish this project directory independently — it is consumed via the published subpath only.
 
-To build the library, run:
+## Installation
 
 ```bash
-ng build context-menu
+# Plain Tailwind (no prefix):
+npm install @egose/shadcn-theme-ng
+
+# Or the tw:-prefixed variant:
+npm install @egose/shadcn-theme-ng-tw
+```
+
+Peers are listed in the [package README](../../README.md). This subpath declares `@angular/common`, `@angular/core`, and `@spartan-ng/brain` as peers (see `projects/context-menu/package.json`); at runtime it also needs `@angular/cdk/menu` and a menu-content package (`dropdown-menu`).
+
+## Imports
+
+```ts
+import {
+  HlmContextMenuTrigger,
+  HlmContextMenuImports,
+  HlmContextMenuModule,
+  HlmContextMenuConfig,
+  provideHlmContextMenuConfig,
+  injectHlmContextMenuConfig,
+} from '@egose/shadcn-theme-ng/context-menu';
+// tw variant:
+// import { ... } from '@egose/shadcn-theme-ng-tw/context-menu';
+```
+
+Standalone:
+
+```ts
+import { Component } from '@angular/core';
+import { HlmContextMenuImports } from '@egose/shadcn-theme-ng/context-menu';
+
+@Component({
+  selector: 'app-demo',
+  standalone: true,
+  imports: [...HlmContextMenuImports],
+  template: `...`,
+})
+export class DemoComponent {}
+```
+
+NgModule:
+
+```ts
+import { NgModule } from '@angular/core';
+import { HlmContextMenuModule } from '@egose/shadcn-theme-ng/context-menu';
+
+@NgModule({ imports: [HlmContextMenuModule] })
+export class DemoModule {}
+```
+
+## Anatomy / Structure
+
+```html
+<!-- Trigger area: right-click anywhere inside the div -->
+<div
+  [hlmContextMenuTrigger]="menu"
+  [hlmContextMenuTriggerData]="{ id: file.id }"
+  (hlmContextMenuOpened)="onOpen()"
+  (hlmContextMenuClosed)="onClose()"
+>
+  Right-click me
+</div>
+
+<!-- Shared menu content (dropdown-menu subpath) -->
+<ng-template #menu let-id="id">
+  <hlm-dropdown-menu>
+    <hlm-dropdown-menu-group>
+      <button hlmDropdownMenuItem (click)="open(id)">Open</button>
+      <button hlmDropdownMenuItem (click)="rename(id)">Rename</button>
+      <hlm-dropdown-menu-separator></hlm-dropdown-menu-separator>
+      <button hlmDropdownMenuItem variant="destructive" (click)="remove(id)">Delete</button>
+    </hlm-dropdown-menu-group>
+  </hlm-dropdown-menu>
+</ng-template>
+```
+
+> Exact `hlm-dropdown-menu` selectors/composition live in that subpath's README — the sketch above shows intent. What this package guarantees: `[hlmContextMenuTrigger]` anchors whatever `Menu` template you pass, sets `transformOriginSelector` so the panel animates from the click corner, and derives `data-side` from the resolved position.
+
+Real selector: `[hlmContextMenuTrigger]` (attribute only, on any element). Host carries `data-slot="context-menu-trigger"`, `data-disabled` when locked, and `tw:select-none`.
+
+## API reference
+
+### `HlmContextMenuTrigger` (`[hlmContextMenuTrigger]`)
+
+Host-directive mapping to `CdkContextMenuTrigger`:
+
+| CDK input (aliased)         | Directive-facing name       | Description                                           |
+| --------------------------- | --------------------------- | ----------------------------------------------------- |
+| `cdkContextMenuTriggerFor`  | `hlmContextMenuTrigger`     | The `<ng-template>` menu panel to open. **Required.** |
+| `cdkContextMenuTriggerData` | `hlmContextMenuTriggerData` | Data passed to the menu template (`let-*` bindings).  |
+| `cdkContextMenuDisabled`    | `disabled`                  | Locks right-click opening.                            |
+
+| CDK output (aliased)   | Payload | Description                                             |
+| ---------------------- | ------- | ------------------------------------------------------- |
+| `cdkContextMenuOpened` | —       | Emitted as `hlmContextMenuOpened` when the menu opens.  |
+| `cdkContextMenuClosed` | —       | Emitted as `hlmContextMenuClosed` when the menu closes. |
+
+Own inputs (placement, defaulting from injected config):
+
+| Input      | Type        | Default                     | Description                                                                                                                                          |
+| ---------- | ----------- | --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `disabled` | `boolean`   | CDK trigger's current value | Locks the menu (boolean-coerced). Reflected as `data-disabled`.                                                                                      |
+| `align`    | `MenuAlign` | `'start'` (or configured)   | Cross-axis alignment of the panel.                                                                                                                   |
+| `side`     | `MenuSide`  | `'bottom'` (or configured)  | Preferred side relative to the click point. Combined via `createMenuPosition(align, side)` and assigned to `cdkTrigger.menuPosition` in an `effect`. |
+
+### Config token (`hlm-context-menu-token.ts`)
+
+| Member                        | Type                                                       | Description                                                                                                    |
+| ----------------------------- | ---------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
+| `HlmContextMenuConfig`        | `{ align: MenuAlign; side: MenuSide }`                     | Shape of the global default.                                                                                   |
+| `provideHlmContextMenuConfig` | `(config: Partial<HlmContextMenuConfig>) => ValueProvider` | Provide app- or route-level defaults (`{ side: 'right' }`, …). Defaults: `{ align: 'start', side: 'bottom' }`. |
+| `injectHlmContextMenuConfig`  | `() => HlmContextMenuConfig`                               | Reads the configured (or default) config — used internally by the trigger.                                     |
+
+## Examples
+
+### 1. Basic right-click area + dropdown menu
+
+```ts
+import { Component } from '@angular/core';
+import { HlmContextMenuImports } from '@egose/shadcn-theme-ng/context-menu';
+import { HlmDropdownMenuImports } from '@egose/shadcn-theme-ng/dropdown-menu';
+
+@Component({
+  selector: 'app-basic-context-menu',
+  standalone: true,
+  imports: [...HlmContextMenuImports, ...HlmDropdownMenuImports],
+  template: `
+    <div
+      [hlmContextMenuTrigger]="menu"
+      class="border-border flex h-40 items-center justify-center rounded-lg border border-dashed text-sm"
+    >
+      Right-click here
+    </div>
+
+    <ng-template #menu>
+      <hlm-dropdown-menu>
+        <hlm-dropdown-menu-group>
+          <button hlmDropdownMenuItem (click)="action('cut')">Cut</button>
+          <button hlmDropdownMenuItem (click)="action('copy')">Copy</button>
+          <button hlmDropdownMenuItem (click)="action('paste')">Paste</button>
+        </hlm-dropdown-menu-group>
+      </hlm-dropdown-menu>
+    </ng-template>
+  `,
+})
+export class BasicContextMenuComponent {
+  action(a: string) {
+    console.log(a);
+  }
+}
 ```
+
+### 2. Per-row data (`hlmContextMenuTriggerData`)
+
+Pass the row into the template with `let-*` bindings.
+
+```ts
+import { Component, signal } from '@angular/core';
+import { HlmContextMenuImports } from '@egose/shadcn-theme-ng/context-menu';
+import { HlmDropdownMenuImports } from '@egose/shadcn-theme-ng/dropdown-menu';
+
+interface File {
+  id: string;
+  name: string;
+}
+
+@Component({
+  selector: 'app-row-context-menu',
+  standalone: true,
+  imports: [...HlmContextMenuImports, ...HlmDropdownMenuImports],
+  template: `
+    @for (f of files(); track f.id) {
+      <div
+        [hlmContextMenuTrigger]="menu"
+        [hlmContextMenuTriggerData]="{ file: f }"
+        class="rounded px-3 py-2 text-sm hover:bg-muted"
+      >
+        {{ f.name }}
+      </div>
+    }
+
+    <ng-template #menu let-file="file">
+      <hlm-dropdown-menu>
+        <button hlmDropdownMenuItem (click)="open(file)">Open "{{ file.name }}"</button>
+        <button hlmDropdownMenuItem (click)="rename(file)">Rename</button>
+        <hlm-dropdown-menu-separator></hlm-dropdown-menu-separator>
+        <button hlmDropdownMenuItem variant="destructive" (click)="remove(file)">Delete</button>
+      </hlm-dropdown-menu>
+    </ng-template>
+  `,
+})
+export class RowContextMenuComponent {
+  readonly files = signal<File[]>([
+    { id: '1', name: 'report.pdf' },
+    { id: '2', name: 'photo.png' },
+  ]);
+  open(f: File) {
+    console.log('open', f);
+  }
+  rename(f: File) {
+    console.log('rename', f);
+  }
+  remove(f: File) {
+    this.files.update((fs) => fs.filter((x) => x.id !== f.id));
+  }
+}
+```
+
+### 3. Placement (`align` / `side`) + global config
+
+```ts
+import { Component } from '@angular/core';
+import { HlmContextMenuImports, provideHlmContextMenuConfig } from '@egose/shadcn-theme-ng/context-menu';
+import { HlmDropdownMenuImports } from '@egose/shadcn-theme-ng/dropdown-menu';
+
+@Component({
+  selector: 'app-placement-context-menu',
+  standalone: true,
+  imports: [...HlmContextMenuImports, ...HlmDropdownMenuImports],
+  // Open to the right of the click everywhere in this subtree by default:
+  providers: [provideHlmContextMenuConfig({ side: 'right', align: 'start' })],
+  template: `
+    <!-- Override per trigger when needed: -->
+    <div [hlmContextMenuTrigger]="menu" side="bottom" align="center" class="rounded border p-8 text-sm">
+      Right-click (bottom-center panel)
+    </div>
+
+    <ng-template #menu>
+      <hlm-dropdown-menu>
+        <button hlmDropdownMenuItem>Item one</button>
+        <button hlmDropdownMenuItem>Item two</button>
+      </hlm-dropdown-menu>
+    </ng-template>
+  `,
+})
+export class PlacementContextMenuComponent {}
+```
+
+### 4. Disabled state + open/close tracking
+
+```ts
+import { Component, signal } from '@angular/core';
+import { HlmContextMenuImports } from '@egose/shadcn-theme-ng/context-menu';
+import { HlmDropdownMenuImports } from '@egose/shadcn-theme-ng/dropdown-menu';
+
+@Component({
+  selector: 'app-disabled-context-menu',
+  standalone: true,
+  imports: [...HlmContextMenuImports, ...HlmDropdownMenuImports],
+  template: `
+    <label class="mb-2 flex items-center gap-2 text-sm">
+      <input type="checkbox" [checked]="locked()" (change)="locked.set(!locked())" /> Disable menu
+    </label>
+    <div
+      [hlmContextMenuTrigger]="menu"
+      [disabled]="locked()"
+      (hlmContextMenuOpened)="status.set('open')"
+      (hlmContextMenuClosed)="status.set('closed')"
+      class="rounded border p-8 text-sm"
+    >
+      Right-click (status: {{ status() }})
+    </div>
+
+    <ng-template #menu>
+      <hlm-dropdown-menu>
+        <button hlmDropdownMenuItem>Action</button>
+      </hlm-dropdown-menu>
+    </ng-template>
+  `,
+})
+export class DisabledContextMenuComponent {
+  readonly locked = signal(false);
+  readonly status = signal('closed');
+}
+```
+
+### 5. Card / list with per-item menus (composition)
+
+```ts
+import { Component } from '@angular/core';
+import { HlmContextMenuImports } from '@egose/shadcn-theme-ng/context-menu';
+import { HlmCardImports } from '@egose/shadcn-theme-ng/card';
+import { HlmDropdownMenuImports } from '@egose/shadcn-theme-ng/dropdown-menu';
+
+@Component({
+  selector: 'app-card-context-menu',
+  standalone: true,
+  imports: [...HlmContextMenuImports, ...HlmCardImports, ...HlmDropdownMenuImports],
+  template: `
+    <div hlmCard class="w-80" [hlmContextMenuTrigger]="menu">
+      <div hlmCardHeader>
+        <h3 hlmCardTitle>Q3 report.pdf</h3>
+        <p hlmCardDescription>Right-click for file actions.</p>
+      </div>
+      <div hlmCardContent class="text-sm">2.4 MB · Modified yesterday</div>
+    </div>
+
+    <ng-template #menu>
+      <hlm-dropdown-menu>
+        <button hlmDropdownMenuItem>Preview</button>
+        <button hlmDropdownMenuItem>Download</button>
+        <button hlmDropdownMenuItem>Share…</button>
+      </hlm-dropdown-menu>
+    </ng-template>
+  `,
+})
+export class CardContextMenuComponent {}
+```
+
+### 6. Full custom menu content (icons + shortcuts + submenu hints)
+
+```ts
+import { Component } from '@angular/core';
+import { HlmContextMenuImports } from '@egose/shadcn-theme-ng/context-menu';
+import { HlmDropdownMenuImports } from '@egose/shadcn-theme-ng/dropdown-menu';
+import { NgIcon, provideIcons } from '@ng-icons/core';
+import { lucideCopy, lucideScissors, lucideClipboardPaste } from '@ng-icons/lucide';
+
+@Component({
+  selector: 'app-rich-context-menu',
+  standalone: true,
+  imports: [...HlmContextMenuImports, ...HlmDropdownMenuImports, NgIcon],
+  providers: [provideIcons({ lucideCopy, lucideScissors, lucideClipboardPaste })],
+  template: `
+    <div [hlmContextMenuTrigger]="menu" class="bg-muted rounded-lg p-10 text-sm">Right-click for a rich menu</div>
+
+    <ng-template #menu>
+      <hlm-dropdown-menu class="w-56">
+        <hlm-dropdown-menu-label>Clipboard</hlm-dropdown-menu-label>
+        <hlm-dropdown-menu-group>
+          <button hlmDropdownMenuItem>
+            <ng-icon name="lucideScissors" /> Cut <span hlmDropdownMenuShortcut>⌘X</span>
+          </button>
+          <button hlmDropdownMenuItem>
+            <ng-icon name="lucideCopy" /> Copy <span hlmDropdownMenuShortcut>⌘C</span>
+          </button>
+          <button hlmDropdownMenuItem>
+            <ng-icon name="lucideClipboardPaste" /> Paste <span hlmDropdownMenuShortcut>⌘V</span>
+          </button>
+        </hlm-dropdown-menu-group>
+      </hlm-dropdown-menu>
+    </ng-template>
+  `,
+})
+export class RichContextMenuComponent {}
+```
+
+## Accessibility notes
+
+- Right-click is pointer-only: always provide a keyboard-accessible equivalent (a `…` button opening the same menu template via `hlm-dropdown-menu-trigger`, or visible action buttons) — otherwise keyboard/SR users lose the actions entirely.
+- The trigger area keeps `select-none` but remains focusable content; do not set `disabled` without explaining why (adjacent hint or tooltip).
+- Menu content comes from `dropdown-menu`/`menu` primitives with roving-focus, Escape-to-close, and arrow-key navigation — keep those behaviors; do not trap focus in the trigger.
+- `hlmContextMenuOpened/Closed` let you mirror state (e.g. highlight the trigger area while open) so sighted keyboard users get the same context.
+
+## Theming / CSS variables
+
+No component-specific CSS variables in this subpath. The trigger only adds `select-none`; all panel styling (surface, animations from the click corner via `transformOriginSelector`, `data-side` variants) lives in the `dropdown-menu`/`menu` content components.
+
+## Related subpaths
+
+- `@egose/shadcn-theme-ng/dropdown-menu` — the menu panel content (`hlm-dropdown-menu`, items, separators, shortcuts).
+- `@egose/shadcn-theme-ng/menu` — lower-level menu primitives if you build custom panels.
+- `@egose/shadcn-theme-ng/popover` — click-triggered floating panels (vs right-click here).
+- `@egose/shadcn-theme-ng/tooltip` — hints for the keyboard-accessible equivalents of context actions.