@egose/shadcn-theme-ng 0.0.28 → 0.2.0

package/separator/README.md

@@ -1,64 +1,223 @@
-# Separator
+# Separator (`@egose/shadcn-theme-ng/separator`)
 
-This project was generated using [Angular CLI](https://github.com/angular/angular-cli) version 20.3.0.
+A shadcn/ui-style **Separator** — a thin horizontal or vertical divider line between content. This is the Angular equivalent of shadcn/ui `Separator`.
 
-## Code scaffolding
+It is a thin directive wrapper over `BrnSeparator` from **spartan-ng/brain** (which supplies the `separator` role semantics, orientation handling, and the `decorative` flag). Styling is a 1px `bg-border` line that stretches horizontally or vertically based on `data-[orientation]`-style state attributes.
 
-Angular CLI includes powerful code scaffolding tools. To generate a new component, run:
+> **Ships as:** `@egose/shadcn-theme-ng/separator` and `@egose/shadcn-theme-ng-tw/separator` (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 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:
+```ts
+import { HlmSeparatorImports } from '@egose/shadcn-theme-ng/separator';
+// tw variant:
+// import { HlmSeparatorImports } from '@egose/shadcn-theme-ng-tw/separator';
+```
 
-```bash
-ng generate --help
+Peer dependencies (see [package README](../../README.md) for versions): `@angular/core`, `@angular/common`.
+
+## Imports
+
+Real exported symbols (from `src/public-api.ts` plus `lib/hlm-separator.ts`):
+
+| Symbol                | Kind           | Description                                                                 |
+| --------------------- | -------------- | --------------------------------------------------------------------------- |
+| `HlmSeparator`        | Directive      | The divider; selector `[hlmSeparator],hlm-separator`                        |
+| `hlmSeparatorClass`   | `const string` | The raw class string the directive applies — reuse it for custom separators |
+| `HlmSeparatorImports` | `const` array  | `[HlmSeparator]` standalone imports                                         |
+| `HlmSeparatorModule`  | `NgModule`     | NgModule wrapper re-exporting `HlmSeparator`                                |
+
+Standalone usage:
+
+```ts
+import { Component } from '@angular/core';
+import { HlmSeparatorImports } from '@egose/shadcn-theme-ng/separator';
+
+@Component({
+  selector: 'app-demo',
+  standalone: true,
+  imports: [HlmSeparatorImports],
+  template: `
+    <p>Above</p>
+    <hlm-separator />
+    <p>Below</p>
+  `,
+})
+export class DemoComponent {}
 ```
 
-## Building
+NgModule usage:
 
-To build the library, run:
+```ts
+import { NgModule } from '@angular/core';
+import { HlmSeparatorModule } from '@egose/shadcn-theme-ng/separator';
 
-```bash
-ng build separator
+@NgModule({ imports: [HlmSeparatorModule] })
+export class DemoModule {}
 ```
 
-This command will compile your project, and the build artifacts will be placed in the `dist/` directory.
+## Anatomy / Structure
 
-### Publishing the Library
+```html
+<div>
+  <h4>Account</h4>
+  <p class="tw:text-muted-foreground tw:text-sm">Manage your settings.</p>
+</div>
 
-Once the project is built, you can publish your library by following these steps:
+<hlm-separator class="tw:my-4" />
 
-1. Navigate to the `dist` directory:
+<div>
+  <h4>Notifications</h4>
+</div>
+```
 
-   ```bash
-   cd dist/separator
-   ```
+Real selectors:
 
-2. Run the `npm publish` command to publish your library to the npm registry:
-   ```bash
-   npm publish
-   ```
+| Selector                       | Class          | Notes                                                                |
+| ------------------------------ | -------------- | -------------------------------------------------------------------- |
+| `[hlmSeparator],hlm-separator` | `HlmSeparator` | `data-slot="separator"`; inline-flex 1px line, horizontal by default |
 
-## Running unit tests
+## API reference
 
-To execute unit tests with the [Karma](https://karma-runner.github.io) test runner, use the following command:
+### HlmSeparator (directive)
 
-```bash
-ng test
+Thin wrapper — no own inputs. Forwarded `BrnSeparator` bindings:
+
+| Binding       | Kind  | Description                                                                              |
+| ------------- | ----- | ---------------------------------------------------------------------------------------- |
+| `orientation` | input | `'horizontal' \| 'vertical'` — line direction (default horizontal)                       |
+| `decorative`  | input | When true, the separator is presentational (`aria-hidden`) instead of `role="separator"` |
+
+The applied classes: `inline-flex shrink-0 bg-border`, full-width 1px height when horizontal, full-stretch 1px width when vertical. Add spacing (e.g. `tw:my-4` / `tw:mx-2`) via the `class` attribute — the directive has no `class` input of its own, it merges host classes.
+
+## Examples
+
+### 1. Basic horizontal divider
+
+```ts
+import { Component } from '@angular/core';
+import { HlmSeparatorImports } from '@egose/shadcn-theme-ng/separator';
+
+@Component({
+  selector: 'app-basic-separator',
+  standalone: true,
+  imports: [HlmSeparatorImports],
+  template: `
+    <div class="tw:space-y-1">
+      <h4 class="tw:font-medium">shadcn-theme</h4>
+      <p class="tw:text-muted-foreground tw:text-sm">An Angular shadcn/ui port.</p>
+    </div>
+    <hlm-separator class="tw:my-4" />
+    <div class="tw:flex tw:h-5 tw:items-center tw:gap-4 tw:text-sm">
+      <span>Docs</span>
+      <hlm-separator orientation="vertical" />
+      <span>API</span>
+    </div>
+  `,
+})
+export class BasicSeparatorComponent {}
 ```
 
-## Running end-to-end tests
+### 2. Attribute form on a plain div
 
-For end-to-end (e2e) testing, run:
+```html
+<section>
+  <h2>Profile</h2>
+  <div hlmSeparator class="tw:my-4"></div>
+  <h2>Security</h2>
+</section>
+```
 
-```bash
-ng e2e
+### 3. Vertical separator in a toolbar / breadcrumb row
+
+```ts
+import { Component } from '@angular/core';
+import { HlmSeparatorImports } from '@egose/shadcn-theme-ng/separator';
+
+@Component({
+  selector: 'app-toolbar-separator',
+  standalone: true,
+  imports: [HlmSeparatorImports],
+  template: `
+    <div class="tw:flex tw:h-8 tw:items-center tw:gap-2 tw:rounded-md tw:border tw:px-2">
+      <button type="button">Bold</button>
+      <hlm-separator orientation="vertical" class="tw:h-4" />
+      <button type="button">Italic</button>
+      <hlm-separator orientation="vertical" class="tw:h-4" />
+      <button type="button">Underline</button>
+    </div>
+  `,
+})
+export class ToolbarSeparatorComponent {}
+```
+
+Constrain the height (`tw:h-4`) so the vertical line doesn't stretch the whole toolbar.
+
+### 4. Decorative vs semantic
+
+```html
+<!-- Purely visual: hidden from assistive tech -->
+<hlm-separator decorative class="tw:my-6" />
+
+<!-- Meaningful section break: exposed as role="separator" -->
+<hlm-separator orientation="horizontal" class="tw:my-6" />
 ```
 
-Angular CLI does not come with an end-to-end testing framework by default. You can choose one that suits your needs.
+### 5. Sidebar / menu dividers
+
+```html
+<nav class="tw:flex tw:flex-col tw:gap-1">
+  <a href="/dashboard">Dashboard</a>
+  <a href="/settings">Settings</a>
+  <hlm-separator class="tw:my-2" />
+  <a href="/logout">Log out</a>
+</nav>
+```
+
+(For the app-sidebar layout, `hlm-sidebar-separator` from the `sidebar` subpath already wraps this directive with sidebar tokens — prefer it there.)
+
+### 6. Reusing `hlmSeparatorClass` in a custom component
+
+```ts
+import { Component } from '@angular/core';
+import { hlmSeparatorClass } from '@egose/shadcn-theme-ng/separator';
+import { hlm } from '@egose/shadcn-theme-ng/utils';
+
+@Component({
+  selector: 'app-fancy-divider',
+  standalone: true,
+  template: `<div role="separator" [class]="dividerClass">✦</div>`,
+})
+export class FancyDividerComponent {
+  protected readonly dividerClass = hlm(
+    hlmSeparatorClass,
+    'tw:my-6 tw:items-center tw:justify-center tw:gap-2 tw:bg-transparent',
+  );
+}
+```
+
+## Accessibility notes
+
+- By default the separator exposes `role="separator"` with the correct orientation — use it for real section breaks.
+- Pass `decorative` when the line is purely visual (repeated card dividers, toolbar ticks) so screen readers skip it.
+- Never put content _inside_ the separator and never make it focusable — it is a boundary, not a control.
+
+## Theming / CSS variables
+
+One token: `bg-border` for the line color (follows light/dark theme automatically). Thickness/spacing come from utilities you add via `class`.
 
-## 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/sidebar` — `hlm-sidebar-separator` (sidebar-token variant of this divider)
+- `@egose/shadcn-theme-ng/select` — `hlm-select-separator` (dropdown-section divider)
+- `@egose/shadcn-theme-ng/card` — sectioned containers where separators commonly appear
+- `@egose/shadcn-theme-ng/breadcrumb` — inline navigation that often uses vertical separators

package/separator/fesm2022/separator.mjs

@@ -4,15 +4,15 @@ import * as i1 from '@spartan-ng/brain/separator';
 import { BrnSeparator } from '@spartan-ng/brain/separator';
 import { classes } from '@egose/shadcn-theme-ng/utils';
 
-const hlmSeparatorClass = 'inline-flex shrink-0 bg-border data-horizontal:h-px data-horizontal:w-full data-vertical:w-px data-vertical:self-stretch';
+const hlmSeparatorClass = "inline-flex shrink-0 bg-border data-horizontal:h-px data-horizontal:w-full data-vertical:w-px data-vertical:self-stretch";
 class HlmSeparator {
     constructor() {
         classes(() => hlmSeparatorClass);
     }
-    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "22.0.7", ngImport: i0, type: HlmSeparator, deps: [], target: i0.ɵɵFactoryTarget.Directive });
-    static ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "14.0.0", version: "22.0.7", type: HlmSeparator, isStandalone: true, selector: "[hlmSeparator],hlm-separator", host: { attributes: { "data-slot": "separator" } }, hostDirectives: [{ directive: i1.BrnSeparator, inputs: ["orientation", "orientation", "decorative", "decorative"] }], ngImport: i0 });
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "22.1.3", ngImport: i0, type: HlmSeparator, deps: [], target: i0.ɵɵFactoryTarget.Directive });
+    static ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "14.0.0", version: "22.1.3", type: HlmSeparator, isStandalone: true, selector: "[hlmSeparator],hlm-separator", host: { attributes: { "data-slot": "separator" } }, hostDirectives: [{ directive: i1.BrnSeparator, inputs: ["orientation", "orientation", "decorative", "decorative"] }], ngImport: i0 });
 }
-i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.0.7", ngImport: i0, type: HlmSeparator, decorators: [{
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.1.3", ngImport: i0, type: HlmSeparator, decorators: [{
             type: Directive,
             args: [{
                     selector: '[hlmSeparator],hlm-separator',
@@ -28,11 +28,11 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.0.7", ngImpor
  */
 const HlmSeparatorImports = [HlmSeparator];
 class HlmSeparatorModule {
-    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "22.0.7", ngImport: i0, type: HlmSeparatorModule, deps: [], target: i0.ɵɵFactoryTarget.NgModule });
-    static ɵmod = i0.ɵɵngDeclareNgModule({ minVersion: "14.0.0", version: "22.0.7", ngImport: i0, type: HlmSeparatorModule, imports: [HlmSeparator], exports: [HlmSeparator] });
-    static ɵinj = i0.ɵɵngDeclareInjector({ minVersion: "12.0.0", version: "22.0.7", ngImport: i0, type: HlmSeparatorModule });
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "22.1.3", ngImport: i0, type: HlmSeparatorModule, deps: [], target: i0.ɵɵFactoryTarget.NgModule });
+    static ɵmod = i0.ɵɵngDeclareNgModule({ minVersion: "14.0.0", version: "22.1.3", ngImport: i0, type: HlmSeparatorModule, imports: [HlmSeparator], exports: [HlmSeparator] });
+    static ɵinj = i0.ɵɵngDeclareInjector({ minVersion: "12.0.0", version: "22.1.3", ngImport: i0, type: HlmSeparatorModule });
 }
-i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.0.7", ngImport: i0, type: HlmSeparatorModule, decorators: [{
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.1.3", ngImport: i0, type: HlmSeparatorModule, decorators: [{
             type: NgModule,
             args: [{
                     imports: [...HlmSeparatorImports],
@@ -45,4 +45,4 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.0.7", ngImpor
  */
 
 export { HlmSeparator, HlmSeparatorImports, HlmSeparatorModule, hlmSeparatorClass };
-//# sourceMappingURL=separator.mjs.map
+

package/separator/types/separator.d.ts

@@ -1,7 +1,7 @@
 import * as i0 from '@angular/core';
 import * as i1 from '@spartan-ng/brain/separator';
 
-declare const hlmSeparatorClass = "inline-flex shrink-0 bg-border data-horizontal:h-px data-horizontal:w-full data-vertical:w-px data-vertical:self-stretch";
+declare const hlmSeparatorClass = "tw:inline-flex tw:shrink-0 tw:bg-border tw:data-horizontal:h-px tw:data-horizontal:w-full tw:data-vertical:w-px tw:data-vertical:self-stretch";
 declare class HlmSeparator {
     constructor();
     static ɵfac: i0.ɵɵFactoryDeclaration<HlmSeparator, never>;

package/sheet/README.md

@@ -1,64 +1,312 @@
-# Sheet
+# Sheet (`@egose/shadcn-theme-ng/sheet`)
 
-This project was generated using [Angular CLI](https://github.com/angular/angular-cli) version 20.3.0.
+A shadcn/ui-style **Sheet** — a slide-over panel (dialog) anchored to any screen edge. This is the Angular equivalent of shadcn/ui `Sheet` (`SheetTrigger`, `SheetContent`, `SheetHeader`, `SheetFooter`, `SheetTitle`, `SheetDescription`, `SheetClose`).
 
-## Code scaffolding
+The overlay/focus-trap/dialog mechanics come from **spartan-ng/brain** (`BrnSheet`, `BrnSheetOverlay`, `BrnSheetClose`, `BrnSheetTitle`, `BrnSheetDescription`, `BrnDialog`). This package adds the shadcn shell: `HlmSheet` root (extends `BrnSheet`, renders the overlay + content outlet), `HlmSheetContent` with `side` variants (top/bottom/left/right, default right) plus a built-in close button, header/footer/title/description layout pieces, and overlay/close styling directives.
 
-Angular CLI includes powerful code scaffolding tools. To generate a new component, run:
+> **Ships as:** `@egose/shadcn-theme-ng/sheet` and `@egose/shadcn-theme-ng-tw/sheet` (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 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:
+```ts
+import { HlmSheetImports } from '@egose/shadcn-theme-ng/sheet';
+// tw variant:
+// import { HlmSheetImports } from '@egose/shadcn-theme-ng-tw/sheet';
+```
 
-```bash
-ng generate --help
+Peer dependencies (see [package README](../../README.md) for versions): `@angular/core`, `@angular/common`. Icons use `@ng-icons/lucide` (`lucideX` for the built-in close button), installed transitively.
+
+## Imports
+
+Real exported symbols (from `src/public-api.ts`):
+
+| Symbol                | Kind                           | Selector                                                                       |
+| --------------------- | ------------------------------ | ------------------------------------------------------------------------------ |
+| `HlmSheet`            | Component (extends `BrnSheet`) | `hlm-sheet` (`exportAs: 'hlmSheet'`)                                           |
+| `HlmSheetContent`     | Component                      | `hlm-sheet-content`                                                            |
+| `HlmSheetHeader`      | Component                      | `hlm-sheet-header`                                                             |
+| `HlmSheetFooter`      | Component                      | `hlm-sheet-footer`                                                             |
+| `HlmSheetTitle`       | Directive                      | `[hlmSheetTitle]`                                                              |
+| `HlmSheetDescription` | Directive                      | `[hlmSheetDescription]`                                                        |
+| `HlmSheetOverlay`     | Directive                      | `[hlmSheetOverlay],brn-sheet-overlay[hlm]`                                     |
+| `HlmSheetClose`       | Directive                      | `[hlmSheetClose],[brnSheetClose][hlm]`                                         |
+| `sheetVariants`       | `cva`                          | Side-variant class builder (`top \| bottom \| left \| right`, default `right`) |
+| `HlmSheetImports`     | `const` array                  | All components/directives above, for standalone `imports`                      |
+| `HlmSheetModule`      | `NgModule`                     | NgModule wrapper re-exporting all of the above                                 |
+
+Standalone usage:
+
+```ts
+import { Component } from '@angular/core';
+import { HlmSheetImports } from '@egose/shadcn-theme-ng/sheet';
+
+@Component({
+  selector: 'app-demo',
+  standalone: true,
+  imports: [HlmSheetImports],
+  template: `...`,
+})
+export class DemoComponent {}
 ```
 
-## Building
+NgModule usage:
 
-To build the library, run:
+```ts
+import { NgModule } from '@angular/core';
+import { HlmSheetModule } from '@egose/shadcn-theme-ng/sheet';
 
-```bash
-ng build sheet
+@NgModule({ imports: [HlmSheetModule] })
+export class DemoModule {}
 ```
 
-This command will compile your project, and the build artifacts will be placed in the `dist/` directory.
+## Anatomy / Structure
 
-### Publishing the Library
+The `HlmSheet` root renders `<brn-sheet-overlay hlm />` plus your projected content. `HlmSheetContent` must be projected with the brain structural directive `*brnSheetContent` so it opens/closes with dialog state; the trigger uses `*brnSheetTrigger`:
 
-Once the project is built, you can publish your library by following these steps:
+```html
+<hlm-sheet>
+  <button hlmButton *brnSheetTrigger>Edit profile</button>
 
-1. Navigate to the `dist` directory:
+  <hlm-sheet-content *brnSheetContent="let ctx">
+    <hlm-sheet-header>
+      <h2 hlmSheetTitle>Edit profile</h2>
+      <p hlmSheetDescription>Update your details. Click save when done.</p>
+    </hlm-sheet-header>
 
-   ```bash
-   cd dist/sheet
-   ```
+    <div class="tw:px-4">...form fields...</div>
 
-2. Run the `npm publish` command to publish your library to the npm registry:
-   ```bash
-   npm publish
-   ```
+    <hlm-sheet-footer>
+      <button hlmButton brnSheetClose hlmSheetClose>Save</button>
+      <button hlmButton variant="outline" brnSheetClose hlmSheetClose>Cancel</button>
+    </hlm-sheet-footer>
+  </hlm-sheet-content>
+</hlm-sheet>
+```
 
-## Running unit tests
+Real selectors:
 
-To execute unit tests with the [Karma](https://karma-runner.github.io) test runner, use the following command:
+| Selector                                   | Class                 | Notes                                                                                        |
+| ------------------------------------------ | --------------------- | -------------------------------------------------------------------------------------------- |
+| `hlm-sheet`                                | `HlmSheet`            | Root; template = overlay + `<ng-content />`; provides itself as `BrnDialog`/`BrnSheet`       |
+| `hlm-sheet-content`                        | `HlmSheetContent`     | Sliding panel; auto close (X) button; `data-state` reflects open/closed                      |
+| `hlm-sheet-header`                         | `HlmSheetHeader`      | Column layout, padded                                                                        |
+| `hlm-sheet-footer`                         | `HlmSheetFooter`      | Bottom-pinned column (`mt-auto`), padded                                                     |
+| `[hlmSheetTitle]`                          | `HlmSheetTitle`       | Semibold title; forwards `BrnSheetTitle` (accessible dialog name)                            |
+| `[hlmSheetDescription]`                    | `HlmSheetDescription` | Muted small description; forwards `BrnSheetDescription`                                      |
+| `[hlmSheetOverlay],brn-sheet-overlay[hlm]` | `HlmSheetOverlay`     | Dimmed backdrop with fade animations                                                         |
+| `[hlmSheetClose],[brnSheetClose][hlm]`     | `HlmSheetClose`       | Close-button styling (absolute top-right); apply on an element that also has `brnSheetClose` |
 
-```bash
-ng test
+## API reference
+
+### HlmSheet (component)
+
+Extends `BrnSheet`, so every `BrnSheet`/`BrnDialog` input/output (e.g. `state`, `stateChanged`, `side` where supported) is available on the host. Own template: `<brn-sheet-overlay hlm />` + content outlet. `exportAs: 'hlmSheet'` for `#sheet="hlmSheet"` references.
+
+### HlmSheetContent (component)
+
+| Input                 | Type         | Default | Description                                                           |
+| --------------------- | ------------ | ------- | --------------------------------------------------------------------- |
+| `class` (`userClass`) | `ClassValue` | `''`    | Extra classes appended to the `sheetVariants({ side })` panel classes |
+
+The `side` comes from the exposed-side provider of the enclosing brain sheet context (`injectExposedSideProvider`); the open state comes from `injectExposesStateProvider` and is mirrored to `data-state`. Side classes via the exported `sheetVariants` cva:
+
+| `side`            | Placement                                                          |
+| ----------------- | ------------------------------------------------------------------ |
+| `right` (default) | Right edge, full height, `w-3/4 sm:max-w-sm`, slides in from right |
+| `left`            | Left edge, mirrored                                                |
+| `top`             | Top edge, full width, auto height, bottom border                   |
+| `bottom`          | Bottom edge, full width, auto height, top border                   |
+
+The built-in close button (`<button brnSheetClose hlm>` with `lucideX` icon + sr-only "Close") is always rendered — add `class="...hidden"` overrides or your own close controls as needed; you cannot remove it via input.
+
+### HlmSheetHeader / HlmSheetFooter / HlmSheetTitle / HlmSheetDescription
+
+Layout-only (header: `flex flex-col gap-1.5 p-4`; footer: `mt-auto flex flex-col gap-2 p-4`) plus a `class` (`userClass`) input each. Title forwards `BrnSheetTitle`, description forwards `BrnSheetDescription` — always include a title so the dialog has an accessible name.
+
+### HlmSheetOverlay / HlmSheetClose (directives)
+
+Styling-only, each with a `class` (`userClass`) input. `HlmSheetOverlay` pushes its computed class into a custom-class-settable host when present (brain overlay interop). `HlmSheetClose` positions the button absolutely top-right with the subtle-opacity hover treatment — it must sit on an element that also closes the sheet (`brnSheetClose`).
+
+## Examples
+
+### 1. Basic right-side sheet
+
+```ts
+import { Component } from '@angular/core';
+import { BrnSheetImports } from '@spartan-ng/brain/sheet';
+import { HlmButtonImports } from '@egose/shadcn-theme-ng/button';
+import { HlmSheetImports } from '@egose/shadcn-theme-ng/sheet';
+
+@Component({
+  selector: 'app-basic-sheet',
+  standalone: true,
+  imports: [BrnSheetImports, HlmButtonImports, HlmSheetImports],
+  template: `
+    <hlm-sheet>
+      <button hlmButton variant="outline" *brnSheetTrigger>Open sheet</button>
+
+      <hlm-sheet-content *brnSheetContent="let ctx">
+        <hlm-sheet-header>
+          <h2 hlmSheetTitle>Notifications</h2>
+          <p hlmSheetDescription>You have 3 unread messages.</p>
+        </hlm-sheet-header>
+        <div class="tw:px-4 tw:text-sm">Sheet body…</div>
+        <hlm-sheet-footer>
+          <button hlmButton brnSheetClose hlmSheetClose>Done</button>
+        </hlm-sheet-footer>
+      </hlm-sheet-content>
+    </hlm-sheet>
+  `,
+})
+export class BasicSheetComponent {}
 ```
 
-## Running end-to-end tests
+(`*brnSheetTrigger` / `*brnSheetContent` come from `BrnSheetImports` — import that alongside `HlmSheetImports`.)
 
-For end-to-end (e2e) testing, run:
+### 2. All four sides
 
-```bash
-ng e2e
+```html
+<hlm-sheet [side]="'left'">
+  <button hlmButton *brnSheetTrigger>Left nav</button>
+  <hlm-sheet-content *brnSheetContent="let ctx">
+    <hlm-sheet-header>
+      <h2 hlmSheetTitle>Menu</h2>
+    </hlm-sheet-header>
+  </hlm-sheet-content>
+</hlm-sheet>
+
+<!-- side="top" | side="bottom" work the same; omit for the default right -->
 ```
 
-Angular CLI does not come with an end-to-end testing framework by default. You can choose one that suits your needs.
+`side` is read by `HlmSheetContent` through the exposed-side provider, and `sheetVariants({ side })` drives the slide animation direction.
+
+### 3. Form sheet with footer actions
+
+```ts
+import { Component } from '@angular/core';
+import { FormsModule } from '@angular/forms';
+import { BrnSheetImports } from '@spartan-ng/brain/sheet';
+import { HlmButtonImports } from '@egose/shadcn-theme-ng/button';
+import { HlmInputImports } from '@egose/shadcn-theme-ng/input';
+import { HlmLabelImports } from '@egose/shadcn-theme-ng/label';
+import { HlmSheetImports } from '@egose/shadcn-theme-ng/sheet';
+
+@Component({
+  selector: 'app-form-sheet',
+  standalone: true,
+  imports: [BrnSheetImports, FormsModule, HlmButtonImports, HlmInputImports, HlmLabelImports, HlmSheetImports],
+  template: `
+    <hlm-sheet>
+      <button hlmButton *brnSheetTrigger>Edit profile</button>
+      <hlm-sheet-content *brnSheetContent="let ctx">
+        <hlm-sheet-header>
+          <h2 hlmSheetTitle>Edit profile</h2>
+          <p hlmSheetDescription>Changes save when you click Save.</p>
+        </hlm-sheet-header>
+
+        <div class="tw:grid tw:gap-4 tw:px-4">
+          <div class="tw:grid tw:gap-2">
+            <label hlmLabel for="sheet-name">Name</label>
+            <input hlmInput id="sheet-name" [(ngModel)]="name" name="name" />
+          </div>
+        </div>
+
+        <hlm-sheet-footer>
+          <button hlmButton (click)="save(ctx)">Save</button>
+          <button hlmButton variant="outline" brnSheetClose hlmSheetClose>Cancel</button>
+        </hlm-sheet-footer>
+      </hlm-sheet-content>
+    </hlm-sheet>
+  `,
+})
+export class FormSheetComponent {
+  name = 'Ada';
+
+  save(ctx: { close: () => void }): void {
+    console.log('saving', this.name);
+    ctx.close();
+  }
+}
+```
+
+### 4. Programmatic open/close via exportAs
+
+```html
+<hlm-sheet #sheet="hlmSheet" [state]="state">
+  <hlm-sheet-content *brnSheetContent="let ctx">
+    <hlm-sheet-header>
+      <h2 hlmSheetTitle>Controlled</h2>
+      <p hlmSheetDescription>Opened from code.</p>
+    </hlm-sheet-header>
+    <hlm-sheet-footer>
+      <button hlmButton (click)="state = 'closed'">Close from code</button>
+    </hlm-sheet-footer>
+  </hlm-sheet-content>
+</hlm-sheet>
+
+<button hlmButton (click)="state = 'open'">Open from code</button>
+```
+
+### 5. Custom close affordances with `hlmSheetClose`
+
+```html
+<hlm-sheet-content *brnSheetContent="let ctx">
+  <hlm-sheet-header>
+    <h2 hlmSheetTitle>Confirm delete</h2>
+    <p hlmSheetDescription>This action cannot be undone.</p>
+  </hlm-sheet-header>
+
+  <hlm-sheet-footer>
+    <button hlmButton variant="destructive" brnSheetClose hlmSheetClose>Delete</button>
+    <button hlmButton variant="ghost" brnSheetClose hlmSheetClose>Keep it</button>
+  </hlm-sheet-footer>
+</hlm-sheet-content>
+```
+
+`brnSheetClose` does the closing; `hlmSheetClose` only styles. You can also put `hlmSheetClose` on any absolutely-positioned custom close button.
+
+### 6. Wide / custom-sized content with `sheetVariants`
+
+```ts
+import { Component } from '@angular/core';
+import { sheetVariants } from '@egose/shadcn-theme-ng/sheet';
+
+@Component({ selector: 'app-wide-sheet', template: '' })
+export class WideSheetComponent {
+  // Reuse the exact variant builder for a custom panel:
+  protected readonly panelClass = sheetVariants({ side: 'right' });
+}
+```
+
+```html
+<hlm-sheet-content *brnSheetContent="let ctx" class="tw:sm:max-w-lg"> ... </hlm-sheet-content>
+```
+
+`userClass` merges after the variant classes, so `tw:sm:max-w-lg` widens the default `sm:max-w-sm` panel.
+
+## Accessibility notes
+
+- Always include `hlmSheetTitle` — it forwards `BrnSheetTitle` and gives the dialog its accessible name. Add `hlmSheetDescription` for context.
+- Focus is trapped inside the open sheet and returned to the trigger on close (brain dialog behavior); keep the trigger in the DOM and don't unmount the sheet while open.
+- The overlay click + `Escape` dismiss via brain defaults; destructive flows should still require an explicit footer confirmation, not overlay dismissal alone.
+- The built-in X button has an sr-only "Close" label — if you hide it, provide another labelled close control.
+
+## Theming / CSS variables
+
+Class-driven (`bg-background` panel, `bg-black/50` overlay, border tokens). Animate via the `data-[state=open|closed]` attributes if you customize transitions. Dark mode follows the theme tokens.
 
-## 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/dialog` — centered modal counterpart
+- `@egose/shadcn-theme-ng/drawer` — bottom-anchored mobile-style panel counterpart
+- `@egose/shadcn-theme-ng/sidebar` — persistent app navigation (uses `hlm-sheet` internally on mobile)
+- `@egose/shadcn-theme-ng/button` — triggers and footer actions