@egose/shadcn-theme-ng 0.1.0 → 0.3.0

package/phone-input/fesm2022/phone-input.mjs

@@ -0,0 +1,191 @@
+import * as i0 from '@angular/core';
+import { forwardRef, input, booleanAttribute, computed, signal, ChangeDetectionStrategy, Component } from '@angular/core';
+import { NG_VALUE_ACCESSOR } from '@angular/forms';
+import * as i1 from '@spartan-ng/brain/field';
+import { BrnFieldControl } from '@spartan-ng/brain/field';
+import { HlmInput } from '@egose/shadcn-theme-ng/input';
+import { hlm } from '@egose/shadcn-theme-ng/utils';
+
+const HLM_PHONE_INPUT_VALUE_ACCESSOR = {
+    provide: NG_VALUE_ACCESSOR,
+    useExisting: forwardRef(() => HlmPhoneInput),
+    multi: true,
+};
+function formatNanpPhoneNumber(digits) {
+    const d = digits.replace(/\D/g, '').slice(0, 10);
+    if (d.length === 0)
+        return '';
+    if (d.length <= 3)
+        return `(${d}`;
+    if (d.length <= 6)
+        return `(${d.slice(0, 3)}) ${d.slice(3)}`;
+    return `(${d.slice(0, 3)}) ${d.slice(3, 6)}-${d.slice(6)}`;
+}
+/**
+ * A masked phone input. The form model holds raw digits (`"4155552671"`);
+ * the visible text is formatted (`"(415) 555-2671"`). Caret position is
+ * preserved across mask characters while typing or deleting.
+ */
+class HlmPhoneInput {
+    static _id = 0;
+    inputId = input(`hlm-phone-input-${HlmPhoneInput._id++}`, /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "inputId" }] : /* istanbul ignore next */ []));
+    name = input(undefined, /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "name" }] : /* istanbul ignore next */ []));
+    ariaLabel = input(undefined, /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "ariaLabel" }] : /* istanbul ignore next */ []));
+    ariaDescribedby = input(null, /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "ariaDescribedby" }] : /* istanbul ignore next */ []));
+    placeholder = input('', /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "placeholder" }] : /* istanbul ignore next */ []));
+    autocomplete = input('tel', /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "autocomplete" }] : /* istanbul ignore next */ []));
+    readonly = input(false, { ...(ngDevMode ? { debugName: "readonly" } : /* istanbul ignore next */ {}), transform: booleanAttribute });
+    disabled = input(false, { ...(ngDevMode ? { debugName: "disabled" } : /* istanbul ignore next */ {}), transform: booleanAttribute });
+    forceInvalid = input(false, { ...(ngDevMode ? { debugName: "forceInvalid" } : /* istanbul ignore next */ {}), transform: booleanAttribute });
+    /** Maximum digit count kept in the model. Defaults to 10 (NANP). */
+    maxDigits = input(10, /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "maxDigits" }] : /* istanbul ignore next */ []));
+    /**
+     * Shape of the form model: raw digits (`"4155552671"`, the default —
+     * validator- and storage-friendly) or formatted display text
+     * (`"(415) 555-2671"`).
+     */
+    modelFormat = input('digits', /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "modelFormat" }] : /* istanbul ignore next */ []));
+    /** Display formatter. Receives raw digits, returns display text. */
+    formatPhoneNumber = input(formatNanpPhoneNumber, /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "formatPhoneNumber" }] : /* istanbul ignore next */ []));
+    /** Extra classes merged onto the inner `<input>` (over the `HlmInput` base). */
+    userClass = input('', { ...(ngDevMode ? { debugName: "userClass" } : /* istanbul ignore next */ {}), alias: 'class' });
+    inputClass = input('', /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "inputClass" }] : /* istanbul ignore next */ []));
+    $inputClass = computed(() => hlm(this.userClass(), this.inputClass()), /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "$inputClass" }] : /* istanbul ignore next */ []));
+    _formDisabled = signal(false, /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "_formDisabled" }] : /* istanbul ignore next */ []));
+    disabledState = computed(() => this.disabled() || this._formDisabled(), /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "disabledState" }] : /* istanbul ignore next */ []));
+    /** Raw digits held in the form model. */
+    _digits = signal('', /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "_digits" }] : /* istanbul ignore next */ []));
+    /** Formatted text shown in the input. */
+    _display = computed(() => this.formatPhoneNumber()(this._digits()), /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "_display" }] : /* istanbul ignore next */ []));
+    _onChange;
+    _onTouched;
+    _emitModel(digits) {
+        if (digits === this._digits())
+            return;
+        this._digits.set(digits);
+        if (digits === '') {
+            this._onChange?.(null);
+        }
+        else if (this.modelFormat() === 'formatted') {
+            this._onChange?.(this.formatPhoneNumber()(digits));
+        }
+        else {
+            this._onChange?.(digits);
+        }
+    }
+    _handleInput(event) {
+        const element = event.target;
+        const caret = element.selectionStart ?? element.value.length;
+        const digitsBeforeCaret = element.value.slice(0, caret).replace(/\D/g, '').length;
+        const digits = element.value.replace(/\D/g, '').slice(0, Math.max(0, this.maxDigits()));
+        const formatted = this.formatPhoneNumber()(digits);
+        const target = Math.min(digitsBeforeCaret, digits.length);
+        let position = 0;
+        let seen = 0;
+        while (position < formatted.length && seen < target) {
+            if (/\d/.test(formatted[position]))
+                seen++;
+            position++;
+        }
+        element.value = formatted;
+        element.setSelectionRange(position, position);
+        this._emitModel(digits);
+    }
+    _handleBlur() {
+        this._onTouched?.();
+    }
+    /** CONTROL VALUE ACCESSOR */
+    writeValue(value) {
+        this._digits.set(String(value ?? '')
+            .replace(/\D/g, '')
+            .slice(0, Math.max(0, this.maxDigits())));
+    }
+    registerOnChange(fn) {
+        this._onChange = fn;
+    }
+    registerOnTouched(fn) {
+        this._onTouched = fn;
+    }
+    setDisabledState(isDisabled) {
+        this._formDisabled.set(isDisabled);
+    }
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "22.1.3", ngImport: i0, type: HlmPhoneInput, deps: [], target: i0.ɵɵFactoryTarget.Component });
+    static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.1.0", version: "22.1.3", type: HlmPhoneInput, isStandalone: true, selector: "hlm-phone-input", inputs: { inputId: { classPropertyName: "inputId", publicName: "inputId", isSignal: true, isRequired: false, transformFunction: null }, name: { classPropertyName: "name", publicName: "name", isSignal: true, isRequired: false, transformFunction: null }, ariaLabel: { classPropertyName: "ariaLabel", publicName: "ariaLabel", isSignal: true, isRequired: false, transformFunction: null }, ariaDescribedby: { classPropertyName: "ariaDescribedby", publicName: "ariaDescribedby", isSignal: true, isRequired: false, transformFunction: null }, placeholder: { classPropertyName: "placeholder", publicName: "placeholder", isSignal: true, isRequired: false, transformFunction: null }, autocomplete: { classPropertyName: "autocomplete", publicName: "autocomplete", isSignal: true, isRequired: false, transformFunction: null }, readonly: { classPropertyName: "readonly", publicName: "readonly", isSignal: true, isRequired: false, transformFunction: null }, disabled: { classPropertyName: "disabled", publicName: "disabled", isSignal: true, isRequired: false, transformFunction: null }, forceInvalid: { classPropertyName: "forceInvalid", publicName: "forceInvalid", isSignal: true, isRequired: false, transformFunction: null }, maxDigits: { classPropertyName: "maxDigits", publicName: "maxDigits", isSignal: true, isRequired: false, transformFunction: null }, modelFormat: { classPropertyName: "modelFormat", publicName: "modelFormat", isSignal: true, isRequired: false, transformFunction: null }, formatPhoneNumber: { classPropertyName: "formatPhoneNumber", publicName: "formatPhoneNumber", isSignal: true, isRequired: false, transformFunction: null }, userClass: { classPropertyName: "userClass", publicName: "class", isSignal: true, isRequired: false, transformFunction: null }, inputClass: { classPropertyName: "inputClass", publicName: "inputClass", isSignal: true, isRequired: false, transformFunction: null } }, host: { properties: { "attr.data-disabled": "disabledState() ? \"\" : null" }, classAttribute: "block w-full min-w-0" }, providers: [HLM_PHONE_INPUT_VALUE_ACCESSOR], hostDirectives: [{ directive: i1.BrnFieldControl }], ngImport: i0, template: `
+    <input
+      #input
+      hlmInput
+      [id]="inputId()"
+      [attr.name]="name()"
+      [attr.aria-label]="ariaLabel()"
+      [attr.aria-describedby]="ariaDescribedby()"
+      [placeholder]="placeholder()"
+      [autocomplete]="autocomplete()"
+      [readonly]="readonly()"
+      [disabled]="disabledState()"
+      [forceInvalid]="forceInvalid()"
+      [class]="$inputClass()"
+      [value]="_display()"
+      (input)="_handleInput($event)"
+      (blur)="_handleBlur()"
+    />
+  `, isInline: true, dependencies: [{ kind: "directive", type: HlmInput, selector: "[hlmInput]", inputs: ["ariaDescribedby"] }], changeDetection: i0.ChangeDetectionStrategy.OnPush });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.1.3", ngImport: i0, type: HlmPhoneInput, decorators: [{
+            type: Component,
+            args: [{
+                    selector: 'hlm-phone-input',
+                    imports: [HlmInput],
+                    providers: [HLM_PHONE_INPUT_VALUE_ACCESSOR],
+                    changeDetection: ChangeDetectionStrategy.OnPush,
+                    hostDirectives: [BrnFieldControl],
+                    host: {
+                        class: "block w-full min-w-0",
+                        '[attr.data-disabled]': 'disabledState() ? "" : null',
+                    },
+                    template: `
+    <input
+      #input
+      hlmInput
+      [id]="inputId()"
+      [attr.name]="name()"
+      [attr.aria-label]="ariaLabel()"
+      [attr.aria-describedby]="ariaDescribedby()"
+      [placeholder]="placeholder()"
+      [autocomplete]="autocomplete()"
+      [readonly]="readonly()"
+      [disabled]="disabledState()"
+      [forceInvalid]="forceInvalid()"
+      [class]="$inputClass()"
+      [value]="_display()"
+      (input)="_handleInput($event)"
+      (blur)="_handleBlur()"
+    />
+  `,
+                }]
+        }], propDecorators: { inputId: [{ type: i0.Input, args: [{ isSignal: true, alias: "inputId", required: false }] }], name: [{ type: i0.Input, args: [{ isSignal: true, alias: "name", required: false }] }], ariaLabel: [{ type: i0.Input, args: [{ isSignal: true, alias: "ariaLabel", required: false }] }], ariaDescribedby: [{ type: i0.Input, args: [{ isSignal: true, alias: "ariaDescribedby", required: false }] }], placeholder: [{ type: i0.Input, args: [{ isSignal: true, alias: "placeholder", required: false }] }], autocomplete: [{ type: i0.Input, args: [{ isSignal: true, alias: "autocomplete", required: false }] }], readonly: [{ type: i0.Input, args: [{ isSignal: true, alias: "readonly", required: false }] }], disabled: [{ type: i0.Input, args: [{ isSignal: true, alias: "disabled", required: false }] }], forceInvalid: [{ type: i0.Input, args: [{ isSignal: true, alias: "forceInvalid", required: false }] }], maxDigits: [{ type: i0.Input, args: [{ isSignal: true, alias: "maxDigits", required: false }] }], modelFormat: [{ type: i0.Input, args: [{ isSignal: true, alias: "modelFormat", required: false }] }], formatPhoneNumber: [{ type: i0.Input, args: [{ isSignal: true, alias: "formatPhoneNumber", required: false }] }], userClass: [{ type: i0.Input, args: [{ isSignal: true, alias: "class", required: false }] }], inputClass: [{ type: i0.Input, args: [{ isSignal: true, alias: "inputClass", required: false }] }] } });
+
+/*
+ * Public API Surface of phone-input
+ */
+
+/**
+ * Generated bundle index. Do not edit.
+ */
+
+export { HLM_PHONE_INPUT_VALUE_ACCESSOR, HlmPhoneInput, formatNanpPhoneNumber };
+

package/phone-input/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "phone-input",
+  "version": "0.0.1",
+  "peerDependencies": {
+    "@angular/common": "^20.3.0 || ^22.0.0",
+    "@angular/core": "^20.3.0 || ^22.0.0"
+  },
+  "dependencies": {
+    "tslib": "^2.3.0"
+  },
+  "sideEffects": false,
+  "module": "fesm2022/phone-input.mjs",
+  "typings": "types/phone-input.d.ts",
+  "exports": {
+    "./package.json": {
+      "default": "./package.json"
+    },
+    ".": {
+      "types": "./types/phone-input.d.ts",
+      "default": "./fesm2022/phone-input.mjs"
+    }
+  },
+  "type": "module"
+}

package/phone-input/types/phone-input.d.ts

@@ -0,0 +1,67 @@
+import * as _angular_core from '@angular/core';
+import { ControlValueAccessor } from '@angular/forms';
+import { BooleanInput } from '@angular/cdk/coercion';
+import { ClassValue } from 'clsx';
+import { ChangeFn, TouchFn } from '@spartan-ng/brain/forms';
+import * as i1 from '@spartan-ng/brain/field';
+
+declare const HLM_PHONE_INPUT_VALUE_ACCESSOR: {
+    provide: _angular_core.InjectionToken<readonly ControlValueAccessor[]>;
+    useExisting: _angular_core.Type<any>;
+    multi: boolean;
+};
+/** Formats digit strings for display. Defaults to NANP `(XXX) XXX-XXXX` with an open paren while typing. */
+type PhoneNumberFormatter = (digits: string) => string;
+declare function formatNanpPhoneNumber(digits: string): string;
+/**
+ * A masked phone input. The form model holds raw digits (`"4155552671"`);
+ * the visible text is formatted (`"(415) 555-2671"`). Caret position is
+ * preserved across mask characters while typing or deleting.
+ */
+declare class HlmPhoneInput implements ControlValueAccessor {
+    private static _id;
+    readonly inputId: _angular_core.InputSignal<string>;
+    readonly name: _angular_core.InputSignal<string | undefined>;
+    readonly ariaLabel: _angular_core.InputSignal<string | undefined>;
+    readonly ariaDescribedby: _angular_core.InputSignal<string | null>;
+    readonly placeholder: _angular_core.InputSignal<string>;
+    readonly autocomplete: _angular_core.InputSignal<string>;
+    readonly readonly: _angular_core.InputSignalWithTransform<boolean, BooleanInput>;
+    readonly disabled: _angular_core.InputSignalWithTransform<boolean, BooleanInput>;
+    readonly forceInvalid: _angular_core.InputSignalWithTransform<boolean, BooleanInput>;
+    /** Maximum digit count kept in the model. Defaults to 10 (NANP). */
+    readonly maxDigits: _angular_core.InputSignal<number>;
+    /**
+     * Shape of the form model: raw digits (`"4155552671"`, the default —
+     * validator- and storage-friendly) or formatted display text
+     * (`"(415) 555-2671"`).
+     */
+    readonly modelFormat: _angular_core.InputSignal<"digits" | "formatted">;
+    /** Display formatter. Receives raw digits, returns display text. */
+    readonly formatPhoneNumber: _angular_core.InputSignal<PhoneNumberFormatter>;
+    /** Extra classes merged onto the inner `<input>` (over the `HlmInput` base). */
+    readonly userClass: _angular_core.InputSignal<ClassValue>;
+    readonly inputClass: _angular_core.InputSignal<ClassValue>;
+    protected readonly $inputClass: _angular_core.Signal<string>;
+    private readonly _formDisabled;
+    protected readonly disabledState: _angular_core.Signal<boolean>;
+    /** Raw digits held in the form model. */
+    protected readonly _digits: _angular_core.WritableSignal<string>;
+    /** Formatted text shown in the input. */
+    protected readonly _display: _angular_core.Signal<string>;
+    protected _onChange?: ChangeFn<string | null>;
+    protected _onTouched?: TouchFn;
+    private _emitModel;
+    protected _handleInput(event: Event): void;
+    protected _handleBlur(): void;
+    /** CONTROL VALUE ACCESSOR */
+    writeValue(value: string | null | undefined): void;
+    registerOnChange(fn: ChangeFn<string | null>): void;
+    registerOnTouched(fn: TouchFn): void;
+    setDisabledState(isDisabled: boolean): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<HlmPhoneInput, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<HlmPhoneInput, "hlm-phone-input", never, { "inputId": { "alias": "inputId"; "required": false; "isSignal": true; }; "name": { "alias": "name"; "required": false; "isSignal": true; }; "ariaLabel": { "alias": "ariaLabel"; "required": false; "isSignal": true; }; "ariaDescribedby": { "alias": "ariaDescribedby"; "required": false; "isSignal": true; }; "placeholder": { "alias": "placeholder"; "required": false; "isSignal": true; }; "autocomplete": { "alias": "autocomplete"; "required": false; "isSignal": true; }; "readonly": { "alias": "readonly"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "forceInvalid": { "alias": "forceInvalid"; "required": false; "isSignal": true; }; "maxDigits": { "alias": "maxDigits"; "required": false; "isSignal": true; }; "modelFormat": { "alias": "modelFormat"; "required": false; "isSignal": true; }; "formatPhoneNumber": { "alias": "formatPhoneNumber"; "required": false; "isSignal": true; }; "userClass": { "alias": "class"; "required": false; "isSignal": true; }; "inputClass": { "alias": "inputClass"; "required": false; "isSignal": true; }; }, {}, never, never, true, [{ directive: typeof i1.BrnFieldControl; inputs: {}; outputs: {}; }]>;
+}
+
+export { HLM_PHONE_INPUT_VALUE_ACCESSOR, HlmPhoneInput, formatNanpPhoneNumber };
+export type { PhoneNumberFormatter };

package/popover/README.md

@@ -1,3 +1,332 @@
-# Popover Subpath
+# Popover (`@egose/shadcn-theme-ng/popover`)
 
-This project ships only as `@egose/shadcn-theme-ng/popover` or `@egose/shadcn-theme-ng-tw/popover`. See the [package README](../../README.md) for installation, compatibility, Tailwind variant, test, and release guidance. Do not publish this project directory independently.
+Floating panel anchored to a button (shadcn/ui `popover` equivalent). Thin shadcn styling directives over the spartan-ng `BrnPopover` brain family: a stateful `hlm-popover` root, a `button[hlmPopoverTrigger]` opener, portal/content pieces for the floating panel, and header/title/description typography helpers.
+
+Ships as `@egose/shadcn-theme-ng/popover` and `@egose/shadcn-theme-ng-tw/popover` (tw: variant). See the [package README](../../README.md) for installation, peer dependencies, Tailwind setup, and testing. 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
+```
+
+Peer dependencies are inherited from the package root (see [package README](../../README.md)). This subpath itself declares `@angular/common`, `@angular/core` as peers plus a `tslib` runtime dependency; at runtime it uses `@spartan-ng/brain/popover` and `@spartan-ng/brain/core`. No extra install step is needed beyond the package install above.
+
+## Imports
+
+Real exported symbols (from `src/public-api.ts`):
+
+```ts
+import {
+  HlmPopover, // directive: [hlmPopover],hlm-popover
+  HlmPopoverTrigger, // directive: button[hlmPopoverTrigger],button[hlmPopoverTriggerFor]
+  HlmPopoverPortal, // directive: [hlmPopoverPortal]
+  HlmPopoverContent, // directive: [hlmPopoverContent],hlm-popover-content
+  HlmPopoverHeader, // directive: [hlmPopoverHeader],hlm-popover-header
+  HlmPopoverTitle, // directive: [hlmPopoverTitle]
+  HlmPopoverDescription, // directive: [hlmPopoverDescription]
+  HlmPopoverImports, // all seven above
+  HlmPopoverModule, // NgModule wrapping HlmPopoverImports
+} from '@egose/shadcn-theme-ng/popover';
+```
+
+Standalone usage:
+
+```ts
+import { Component } from '@angular/core';
+import { HlmPopoverImports } from '@egose/shadcn-theme-ng/popover';
+
+@Component({
+  selector: 'app-demo',
+  standalone: true,
+  imports: [...HlmPopoverImports],
+  template: `
+    <hlm-popover>
+      <button hlmPopoverTrigger type="button">Open</button>
+      <hlm-popover-content *hlmPopoverPortal>
+        <p>Hello</p>
+      </hlm-popover-content>
+    </hlm-popover>
+  `,
+})
+export class DemoComponent {}
+```
+
+NgModule usage:
+
+```ts
+import { NgModule } from '@angular/core';
+import { HlmPopoverModule } from '@egose/shadcn-theme-ng/popover';
+
+@NgModule({ imports: [HlmPopoverModule] })
+export class DemoModule {}
+```
+
+For the `tw:` build, swap the specifier to `@egose/shadcn-theme-ng-tw/popover`. Symbol names are identical.
+
+## Anatomy / Structure
+
+```html
+<hlm-popover>
+  <!-- opener (must be a <button>) -->
+  <button hlmPopoverTrigger type="button">Settings</button>
+
+  <!-- floating panel: content styling + portal projection -->
+  <hlm-popover-content *hlmPopoverPortal class="tw:w-80">
+    <div hlmPopoverHeader>
+      <h4 hlmPopoverTitle>Dimensions</h4>
+      <p hlmPopoverDescription>Set the size of the layer.</p>
+    </div>
+    <!-- panel body -->
+  </hlm-popover-content>
+</hlm-popover>
+```
+
+The two-directive split on the panel is load-bearing: `hlmPopoverContent` paints the panel (fixed `w-72`, animations, `data-state` reflection), while `*hlmPopoverPortal` (a `BrnPopoverContent` host) projects it into the overlay at the anchored position. Always use them together as `hlm-popover-content *hlmPopoverPortal`.
+
+| Class                   | Selector                                                 | Role                                                  |
+| ----------------------- | -------------------------------------------------------- | ----------------------------------------------------- |
+| `HlmPopover`            | `[hlmPopover],hlm-popover`                               | Stateful root (`BrnPopover` host)                     |
+| `HlmPopoverTrigger`     | `button[hlmPopoverTrigger],button[hlmPopoverTriggerFor]` | Opener (`BrnPopoverTrigger` host; must be `<button>`) |
+| `HlmPopoverPortal`      | `[hlmPopoverPortal]`                                     | Overlay projection (`BrnPopoverContent` host)         |
+| `HlmPopoverContent`     | `[hlmPopoverContent],hlm-popover-content`                | Panel styling + `data-state` mirror                   |
+| `HlmPopoverHeader`      | `[hlmPopoverHeader],hlm-popover-header`                  | Header stack (`flex flex-col gap-1 text-sm`)          |
+| `HlmPopoverTitle`       | `[hlmPopoverTitle]`                                      | Title (`font-medium`)                                 |
+| `HlmPopoverDescription` | `[hlmPopoverDescription]`                                | Subtitle (`text-muted-foreground`)                    |
+
+## API reference
+
+| Selector                                                               | Inputs (incl. host passthroughs)                                                                                         | Outputs                                     | Notes                                                                                                                                                       |
+| ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `[hlmPopover],hlm-popover` (`HlmPopover`)                              | `align`, `attachTo`, `autoFocus`, `closeOnOutsidePointerEvents`, `offsetX`, `sideOffset`, `state` (all via `BrnPopover`) | `stateChanged`, `closed` (via `BrnPopover`) | No shadcn inputs of its own; `data-slot="popover"`                                                                                                          |
+| `button[hlmPopoverTrigger]` (`HlmPopoverTrigger`)                      | `id`, `hlmPopoverTriggerFor` (→ `brnPopoverTriggerFor`), `type` (all via `BrnPopoverTrigger`)                            | —                                           | `data-slot="popover-trigger"`. `hlmPopoverTriggerFor` targets an explicit popover when the trigger lives outside the root                                   |
+| `[hlmPopoverPortal]` (`HlmPopoverPortal`)                              | `context`, `class` (via `BrnPopoverContent`)                                                                             | —                                           | Structural directive (`*hlmPopoverPortal`); `class` merges onto the overlay panel                                                                           |
+| `[hlmPopoverContent]` (`HlmPopoverContent`)                            | —                                                                                                                        | —                                           | Exposes `state` (brain state signal, default `signal('closed')`); mirrors it to `data-state` via `Renderer2` for the `data-open:`/`data-closed:` animations |
+| `[hlmPopoverHeader]` / `[hlmPopoverTitle]` / `[hlmPopoverDescription]` | —                                                                                                                        | —                                           | Typography only                                                                                                                                             |
+
+Panel styling (`HlmPopoverContent`): `bg-popover text-popover-foreground rounded-md p-4 text-sm shadow-md ring-1 ring-foreground/10 relative flex w-72 flex-col gap-4 outline-none` plus open/close zoom+fade animations keyed off `data-state`/`data-side`.
+
+## Examples
+
+### 1. Basic popover with header
+
+```ts
+import { Component } from '@angular/core';
+import { HlmPopoverImports } from '@egose/shadcn-theme-ng/popover';
+import { HlmButton } from '@egose/shadcn-theme-ng/button';
+
+@Component({
+  selector: 'app-popover-basic',
+  standalone: true,
+  imports: [...HlmPopoverImports, HlmButton],
+  template: `
+    <hlm-popover>
+      <button hlmPopoverTrigger hlmButton variant="secondary" appearance="outline" type="button">Open settings</button>
+      <hlm-popover-content *hlmPopoverPortal>
+        <div hlmPopoverHeader>
+          <h4 hlmPopoverTitle>Dimensions</h4>
+          <p hlmPopoverDescription>Set the size of the layer.</p>
+        </div>
+        <div class="tw:grid tw:gap-2 tw:text-sm">
+          <label class="tw:grid tw:gap-1"
+            >Width <input class="tw:border tw:rounded tw:px-2 tw:py-1" value="100%"
+          /></label>
+          <label class="tw:grid tw:gap-1"
+            >Height <input class="tw:border tw:rounded tw:px-2 tw:py-1" value="24px"
+          /></label>
+        </div>
+      </hlm-popover-content>
+    </hlm-popover>
+  `,
+})
+export class PopoverBasicComponent {}
+```
+
+### 2. Placement, offsets, and state events
+
+```ts
+import { Component, signal } from '@angular/core';
+import { HlmPopoverImports } from '@egose/shadcn-theme-ng/popover';
+
+@Component({
+  selector: 'app-popover-placement',
+  standalone: true,
+  imports: [...HlmPopoverImports],
+  template: `
+    <hlm-popover
+      align="start"
+      [sideOffset]="8"
+      [closeOnOutsidePointerEvents]="true"
+      (stateChanged)="open.set($event === 'open')"
+      (closed)="open.set(false)"
+    >
+      <button hlmPopoverTrigger type="button">Aligned start, offset 8</button>
+      <hlm-popover-content *hlmPopoverPortal>
+        <p class="tw:text-sm">Panel state: {{ open() ? 'open' : 'closed' }}.</p>
+      </hlm-popover-content>
+    </hlm-popover>
+  `,
+})
+export class PopoverPlacementComponent {
+  readonly open = signal(false);
+}
+```
+
+`align`, `sideOffset`, `closeOnOutsidePointerEvents` are brain inputs on `HlmPopover`; `stateChanged`/`closed` are its outputs.
+
+### 3. Form inside a popover (template-driven)
+
+```ts
+import { Component } from '@angular/core';
+import { FormsModule } from '@angular/forms';
+import { HlmPopoverImports } from '@egose/shadcn-theme-ng/popover';
+import { HlmInput } from '@egose/shadcn-theme-ng/input';
+import { HlmLabelImports } from '@egose/shadcn-theme-ng/label';
+
+@Component({
+  selector: 'app-popover-form',
+  standalone: true,
+  imports: [FormsModule, ...HlmPopoverImports, HlmInput, ...HlmLabelImports],
+  template: `
+    <hlm-popover>
+      <button hlmPopoverTrigger type="button">Invite member</button>
+      <hlm-popover-content *hlmPopoverPortal class="tw:w-80">
+        <div hlmPopoverHeader>
+          <h4 hlmPopoverTitle>Invite</h4>
+          <p hlmPopoverDescription>They receive an email invitation.</p>
+        </div>
+        <div class="tw:grid tw:gap-1.5">
+          <label hlmLabel for="invite-email">Email</label>
+          <input hlmInput id="invite-email" [(ngModel)]="email" type="email" placeholder="ada@example.com" />
+          <button type="button" (click)="invite()">Send invite</button>
+        </div>
+      </hlm-popover-content>
+    </hlm-popover>
+  `,
+})
+export class PopoverFormComponent {
+  email = '';
+
+  invite(): void {
+    console.log('invite', this.email);
+  }
+}
+```
+
+### 4. Custom panel width via portal `class`
+
+The portal's `class` input lands on the overlay host; the content directive keeps its own `w-72` unless you override it on the element as well.
+
+```ts
+import { Component } from '@angular/core';
+import { HlmPopoverImports } from '@egose/shadcn-theme-ng/popover';
+
+@Component({
+  selector: 'app-popover-wide',
+  standalone: true,
+  imports: [...HlmPopoverImports],
+  template: `
+    <hlm-popover>
+      <button hlmPopoverTrigger type="button">Wide panel</button>
+      <hlm-popover-content *hlmPopoverPortal class="tw:w-96">
+        <div hlmPopoverHeader>
+          <h4 hlmPopoverTitle>Preview</h4>
+          <p hlmPopoverDescription>A wider panel for rich content.</p>
+        </div>
+        <div class="tw:grid tw:grid-cols-2 tw:gap-2 tw:text-sm">
+          <div class="tw:rounded tw:bg-muted tw:p-2">Column A</div>
+          <div class="tw:rounded tw:bg-muted tw:p-2">Column B</div>
+        </div>
+      </hlm-popover-content>
+    </hlm-popover>
+  `,
+})
+export class PopoverWideComponent {}
+```
+
+### 5. External trigger (`hlmPopoverTriggerFor`)
+
+```ts
+import { Component } from '@angular/core';
+import { HlmPopoverImports } from '@egose/shadcn-theme-ng/popover';
+
+@Component({
+  selector: 'app-popover-external',
+  standalone: true,
+  imports: [...HlmPopoverImports],
+  template: `
+    <hlm-popover #pop="hlmPopover">
+      <hlm-popover-content *hlmPopoverPortal>
+        <p class="tw:text-sm">Triggered from outside the root.</p>
+      </hlm-popover-content>
+    </hlm-popover>
+
+    <button hlmPopoverTriggerFor [hlmPopoverTriggerFor]="pop" type="button">Open from here</button>
+  `,
+})
+export class PopoverExternalComponent {}
+```
+
+> The exact template-ref export name follows the brain `BrnPopover` directive (`#pop="…"`) — verify against your installed `@spartan-ng/brain` version if the alias differs.
+
+### 6. Async content + loading state
+
+```ts
+import { Component, signal } from '@angular/core';
+import { HlmPopoverImports } from '@egose/shadcn-theme-ng/popover';
+
+@Component({
+  selector: 'app-popover-async',
+  standalone: true,
+  imports: [...HlmPopoverImports],
+  template: `
+    <hlm-popover (stateChanged)="onState($event)">
+      <button hlmPopoverTrigger type="button">Recent activity</button>
+      <hlm-popover-content *hlmPopoverPortal>
+        <div hlmPopoverHeader>
+          <h4 hlmPopoverTitle>Activity</h4>
+          <p hlmPopoverDescription>{{ loading() ? 'Loading…' : 'Last 3 events.' }}</p>
+        </div>
+        @for (e of events(); track e) {
+          <p class="tw:text-sm">{{ e }}</p>
+        } @empty {
+          <p class="tw:text-sm tw:text-muted-foreground">Nothing yet.</p>
+        }
+      </hlm-popover-content>
+    </hlm-popover>
+  `,
+})
+export class PopoverAsyncComponent {
+  readonly events = signal<string[]>([]);
+  readonly loading = signal(false);
+
+  async onState(state: string): Promise<void> {
+    if (state !== 'open' || this.events().length) return;
+    this.loading.set(true);
+    await new Promise((r) => setTimeout(r, 400));
+    this.events.set(['Deploy succeeded', 'Review requested', 'Comment added']);
+    this.loading.set(false);
+  }
+}
+```
+
+## Accessibility notes
+
+- Triggers must be `<button>` (both selector variants require it) with a text label; the brain layer wires `aria-expanded`, `aria-controls`, and focus return.
+- Keep a heading (`hlmPopoverTitle`) as the first element when the panel conveys a topic — screen-reader users land inside the panel on open.
+- `autoFocus` (brain input) controls initial focus; form panels should focus the first field, read-only panels should keep focus on the trigger side and let users tab in.
+- `Escape`/outside-pointer close comes from the brain defaults (`closeOnOutsidePointerEvents` is configurable); don't trap focus manually.
+
+## Theming / CSS variables
+
+No theming inputs. The panel uses `bg-popover text-popover-foreground ring-foreground/10`; header/title/description use text tokens. Widen via portal `class` (example 4); state-driven animations read the mirrored `data-state`.
+
+## Related subpaths
+
+- `@egose/shadcn-theme-ng/tooltip` — hover hint vs this component's click-anchored panel.
+- `@egose/shadcn-theme-ng/dropdown-menu`, `@egose/shadcn-theme-ng/select` — menu/select overlays built on the same brain overlay concepts.
+- `@egose/shadcn-theme-ng/input`, `@egose/shadcn-theme-ng/label` — form controls commonly hosted inside popover panels.