@egose/shadcn-theme-ng 0.1.0 → 0.3.0

package/form-toggle-group/fesm2022/form-toggle-group.mjs

@@ -0,0 +1,116 @@
+import * as i0 from '@angular/core';
+import { InjectionToken, inject, input, computed, Component } from '@angular/core';
+import * as i1 from '@angular/forms';
+import { FormGroupDirective, ReactiveFormsModule, ControlContainer } from '@angular/forms';
+import { HlmFormIdGenerator, HlmError, HlmHint } from '@egose/shadcn-theme-ng/form-field';
+import { EgFormField } from '@egose/shadcn-theme-ng/form-field-simple';
+import { HlmLabel } from '@egose/shadcn-theme-ng/label';
+import { HlmToggleGroup, HlmToggleGroupItem } from '@egose/shadcn-theme-ng/toggle-group';
+import { hlm } from '@egose/shadcn-theme-ng/utils';
+
+const EgFormToggleGroupConfigToken = new InjectionToken('EgFormToggleGroupConfig');
+function provideEgFormToggleGroupConfig(config) {
+    return { provide: EgFormToggleGroupConfigToken, useValue: { ...config } };
+}
+function injectEgFormToggleGroupConfig() {
+    return inject(EgFormToggleGroupConfigToken, { optional: true }) ?? {};
+}
+
+class EgFormToggleGroup {
+    formGroupDirective = inject(FormGroupDirective);
+    generatedId = inject(HlmFormIdGenerator).generate('eg-form-toggle-group');
+    _config = injectEgFormToggleGroupConfig();
+    label = input(undefined, /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "label" }] : /* istanbul ignore next */ []));
+    controlId = input(undefined, /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "controlId" }] : /* istanbul ignore next */ []));
+    controlName = input('', /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "controlName" }] : /* istanbul ignore next */ []));
+    error = input(undefined, /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "error" }] : /* istanbul ignore next */ []));
+    hint = input(undefined, /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "hint" }] : /* istanbul ignore next */ []));
+    id = input(undefined, /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "id" }] : /* istanbul ignore next */ []));
+    type = input('single', /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "type" }] : /* istanbul ignore next */ []));
+    disabled = input(false, /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "disabled" }] : /* istanbul ignore next */ []));
+    required = input(false, /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "required" }] : /* istanbul ignore next */ []));
+    variant = input('default', /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "variant" }] : /* istanbul ignore next */ []));
+    size = input('default', /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "size" }] : /* istanbul ignore next */ []));
+    options = input([], /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "options" }] : /* istanbul ignore next */ []));
+    effectiveId = computed(() => this.controlId() || this.id() || this.generatedId, /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "effectiveId" }] : /* istanbul ignore next */ []));
+    errorId = computed(() => `${this.effectiveId()}-error`, /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "errorId" }] : /* istanbul ignore next */ []));
+    hintId = computed(() => `${this.effectiveId()}-hint`, /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "hintId" }] : /* istanbul ignore next */ []));
+    /**
+     * Combined lock for the brain `linkedSignal`-based disabled state: the raw
+     * input write always carries the resolved value, so a same-pass
+     * wrapper-toggle + `control.disable()` cannot clobber CVA state.
+     */
+    effectiveDisabled() {
+        return this.disabled() || !!this.formGroupDirective.form.get(this.controlName())?.disabled;
+    }
+    describedBy() {
+        const control = this.formGroupDirective.form.get(this.controlName());
+        return this.error() && control?.invalid && (control.dirty || control.touched)
+            ? this.errorId()
+            : this.hint()
+                ? this.hintId()
+                : null;
+    }
+    // Styling
+    userClass = input('', { ...(ngDevMode ? { debugName: "userClass" } : /* istanbul ignore next */ {}), alias: 'class' });
+    labelClass = input('', /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "labelClass" }] : /* istanbul ignore next */ []));
+    groupClass = input('', /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "groupClass" }] : /* istanbul ignore next */ []));
+    errorClass = input('', /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "errorClass" }] : /* istanbul ignore next */ []));
+    hintClass = input('', /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "hintClass" }] : /* istanbul ignore next */ []));
+    // Computed classes (library base < global config < per-instance)
+    $userClass = computed(() => hlm("w-full", this.userClass()), /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "$userClass" }] : /* istanbul ignore next */ []));
+    $labelClass = computed(() => hlm("mb-1", this._config.labelClass, this.labelClass()), /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "$labelClass" }] : /* istanbul ignore next */ []));
+    $groupClass = computed(() => hlm(this._config.groupClass, this.groupClass()), /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "$groupClass" }] : /* istanbul ignore next */ []));
+    $errorClass = computed(() => hlm("mt-0", this._config.errorClass, this.errorClass()), /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "$errorClass" }] : /* istanbul ignore next */ []));
+    $hintClass = computed(() => hlm("mt-0", this._config.hintClass, this.hintClass()), /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "$hintClass" }] : /* istanbul ignore next */ []));
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "22.1.3", ngImport: i0, type: EgFormToggleGroup, deps: [], target: i0.ɵɵFactoryTarget.Component });
+    static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.0.0", version: "22.1.3", type: EgFormToggleGroup, isStandalone: true, selector: "eg-form-toggle-group", inputs: { label: { classPropertyName: "label", publicName: "label", isSignal: true, isRequired: false, transformFunction: null }, controlId: { classPropertyName: "controlId", publicName: "controlId", isSignal: true, isRequired: false, transformFunction: null }, controlName: { classPropertyName: "controlName", publicName: "controlName", isSignal: true, isRequired: false, transformFunction: null }, error: { classPropertyName: "error", publicName: "error", isSignal: true, isRequired: false, transformFunction: null }, hint: { classPropertyName: "hint", publicName: "hint", isSignal: true, isRequired: false, transformFunction: null }, id: { classPropertyName: "id", publicName: "id", isSignal: true, isRequired: false, transformFunction: null }, type: { classPropertyName: "type", publicName: "type", isSignal: true, isRequired: false, transformFunction: null }, disabled: { classPropertyName: "disabled", publicName: "disabled", isSignal: true, isRequired: false, transformFunction: null }, required: { classPropertyName: "required", publicName: "required", isSignal: true, isRequired: false, transformFunction: null }, variant: { classPropertyName: "variant", publicName: "variant", isSignal: true, isRequired: false, transformFunction: null }, size: { classPropertyName: "size", publicName: "size", isSignal: true, isRequired: false, transformFunction: null }, options: { classPropertyName: "options", publicName: "options", isSignal: true, isRequired: false, transformFunction: null }, userClass: { classPropertyName: "userClass", publicName: "class", isSignal: true, isRequired: false, transformFunction: null }, labelClass: { classPropertyName: "labelClass", publicName: "labelClass", isSignal: true, isRequired: false, transformFunction: null }, groupClass: { classPropertyName: "groupClass", publicName: "groupClass", isSignal: true, isRequired: false, transformFunction: null }, errorClass: { classPropertyName: "errorClass", publicName: "errorClass", isSignal: true, isRequired: false, transformFunction: null }, hintClass: { classPropertyName: "hintClass", publicName: "hintClass", isSignal: true, isRequired: false, transformFunction: null } }, host: { properties: { "class": "$userClass()" } }, providers: [{ provide: ControlContainer, useExisting: FormGroupDirective }], ngImport: i0, template: "\n    @let lbl = label();\n    @let cnm = controlName();\n    @let err = error();\n    @let hnt = hint();\n    @let rqrd = required();\n\n    <eg-form-field>\n      @if (lbl) {\n        <span hlmLabel [class]=\"$labelClass()\"\n          >{{ lbl }}\n          @if (rqrd) {\n            <span class=\"text-red-500\">*</span>\n          }\n        </span>\n      }\n\n      <hlm-toggle-group\n        [formControlName]=\"cnm\"\n        [type]=\"type()\"\n        [disabled]=\"effectiveDisabled()\"\n        [variant]=\"variant()\"\n        [size]=\"size()\"\n        [class]=\"$groupClass()\"\n      >\n        @for (option of options(); track option.value) {\n          <button\n            hlmToggleGroupItem\n            type=\"button\"\n            [value]=\"option.value\"\n            [disabled]=\"option.disabled ?? false\"\n            [attr.aria-describedby]=\"describedBy()\"\n          >\n            {{ option.label }}\n          </button>\n        }\n      </hlm-toggle-group>\n\n      @if (err) {\n        <hlm-error [id]=\"errorId()\" [class]=\"$errorClass()\">\n          {{ err }}\n        </hlm-error>\n      }\n\n      @if (hnt) {\n        <hlm-hint [id]=\"hintId()\" [class]=\"$hintClass()\">\n          {{ hnt }}\n        </hlm-hint>\n      }\n    </eg-form-field>\n  ", isInline: true, dependencies: [{ kind: "ngmodule", type: ReactiveFormsModule }, { kind: "directive", type: i1.NgControlStatus, selector: "[formControlName],[ngModel],[formControl]" }, { kind: "directive", type: i1.FormControlName, selector: "[formControlName]", inputs: ["formControlName", "disabled", "ngModel"], outputs: ["ngModelChange"] }, { kind: "directive", type: HlmError, selector: "hlm-error", inputs: ["class"] }, { kind: "directive", type: HlmHint, selector: "hlm-hint", inputs: ["class"] }, { kind: "directive", type: HlmLabel, selector: "[hlmLabel]", inputs: ["class"] }, { kind: "directive", type: HlmToggleGroup, selector: "[hlmToggleGroup],hlm-toggle-group", inputs: ["variant", "size", "spacing", "orientation"] }, { kind: "directive", type: HlmToggleGroupItem, selector: "button[hlmToggleGroupItem]", inputs: ["variant", "size"] }, { kind: "component", type: EgFormField, selector: "eg-form-field", inputs: ["class"] }] });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.1.3", ngImport: i0, type: EgFormToggleGroup, decorators: [{
+            type: Component,
+            args: [{
+                    selector: 'eg-form-toggle-group',
+                    standalone: true,
+                    host: {
+                        '[class]': '$userClass()',
+                    },
+                    imports: [ReactiveFormsModule, HlmError, HlmHint, HlmLabel, HlmToggleGroup, HlmToggleGroupItem, EgFormField],
+                    providers: [{ provide: ControlContainer, useExisting: FormGroupDirective }],
+                    template: "\n    @let lbl = label();\n    @let cnm = controlName();\n    @let err = error();\n    @let hnt = hint();\n    @let rqrd = required();\n\n    <eg-form-field>\n      @if (lbl) {\n        <span hlmLabel [class]=\"$labelClass()\"\n          >{{ lbl }}\n          @if (rqrd) {\n            <span class=\"text-red-500\">*</span>\n          }\n        </span>\n      }\n\n      <hlm-toggle-group\n        [formControlName]=\"cnm\"\n        [type]=\"type()\"\n        [disabled]=\"effectiveDisabled()\"\n        [variant]=\"variant()\"\n        [size]=\"size()\"\n        [class]=\"$groupClass()\"\n      >\n        @for (option of options(); track option.value) {\n          <button\n            hlmToggleGroupItem\n            type=\"button\"\n            [value]=\"option.value\"\n            [disabled]=\"option.disabled ?? false\"\n            [attr.aria-describedby]=\"describedBy()\"\n          >\n            {{ option.label }}\n          </button>\n        }\n      </hlm-toggle-group>\n\n      @if (err) {\n        <hlm-error [id]=\"errorId()\" [class]=\"$errorClass()\">\n          {{ err }}\n        </hlm-error>\n      }\n\n      @if (hnt) {\n        <hlm-hint [id]=\"hintId()\" [class]=\"$hintClass()\">\n          {{ hnt }}\n        </hlm-hint>\n      }\n    </eg-form-field>\n  ",
+                }]
+        }], propDecorators: { label: [{ type: i0.Input, args: [{ isSignal: true, alias: "label", required: false }] }], controlId: [{ type: i0.Input, args: [{ isSignal: true, alias: "controlId", required: false }] }], controlName: [{ type: i0.Input, args: [{ isSignal: true, alias: "controlName", required: false }] }], error: [{ type: i0.Input, args: [{ isSignal: true, alias: "error", required: false }] }], hint: [{ type: i0.Input, args: [{ isSignal: true, alias: "hint", required: false }] }], id: [{ type: i0.Input, args: [{ isSignal: true, alias: "id", required: false }] }], type: [{ type: i0.Input, args: [{ isSignal: true, alias: "type", required: false }] }], disabled: [{ type: i0.Input, args: [{ isSignal: true, alias: "disabled", required: false }] }], required: [{ type: i0.Input, args: [{ isSignal: true, alias: "required", required: false }] }], variant: [{ type: i0.Input, args: [{ isSignal: true, alias: "variant", required: false }] }], size: [{ type: i0.Input, args: [{ isSignal: true, alias: "size", required: false }] }], options: [{ type: i0.Input, args: [{ isSignal: true, alias: "options", required: false }] }], userClass: [{ type: i0.Input, args: [{ isSignal: true, alias: "class", required: false }] }], labelClass: [{ type: i0.Input, args: [{ isSignal: true, alias: "labelClass", required: false }] }], groupClass: [{ type: i0.Input, args: [{ isSignal: true, alias: "groupClass", required: false }] }], errorClass: [{ type: i0.Input, args: [{ isSignal: true, alias: "errorClass", required: false }] }], hintClass: [{ type: i0.Input, args: [{ isSignal: true, alias: "hintClass", required: false }] }] } });
+
+/*
+ * Public API Surface of form-toggle-group
+ */
+
+/**
+ * Generated bundle index. Do not edit.
+ */
+
+export { EgFormToggleGroup, injectEgFormToggleGroupConfig, provideEgFormToggleGroupConfig };
+

package/form-toggle-group/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "form-toggle-group",
+  "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/form-toggle-group.mjs",
+  "typings": "types/form-toggle-group.d.ts",
+  "exports": {
+    "./package.json": {
+      "default": "./package.json"
+    },
+    ".": {
+      "types": "./types/form-toggle-group.d.ts",
+      "default": "./fesm2022/form-toggle-group.mjs"
+    }
+  },
+  "type": "module"
+}

package/form-toggle-group/types/form-toggle-group.d.ts

@@ -0,0 +1,65 @@
+import * as _angular_core from '@angular/core';
+import { ValueProvider } from '@angular/core';
+import { ClassValue } from 'clsx';
+
+interface ToggleGroupOption {
+    value: string;
+    label: string;
+    disabled?: boolean;
+}
+declare class EgFormToggleGroup {
+    private readonly formGroupDirective;
+    private readonly generatedId;
+    private readonly _config;
+    label: _angular_core.InputSignal<string | undefined>;
+    controlId: _angular_core.InputSignal<string | undefined>;
+    controlName: _angular_core.InputSignal<string>;
+    error: _angular_core.InputSignal<string | undefined>;
+    hint: _angular_core.InputSignal<string | undefined>;
+    id: _angular_core.InputSignal<string | undefined>;
+    type: _angular_core.InputSignal<"single" | "multiple">;
+    disabled: _angular_core.InputSignal<boolean>;
+    required: _angular_core.InputSignal<boolean>;
+    variant: _angular_core.InputSignal<"default" | "outline" | null | undefined>;
+    size: _angular_core.InputSignal<"default" | "sm" | "lg" | null | undefined>;
+    options: _angular_core.InputSignal<ToggleGroupOption[]>;
+    readonly effectiveId: _angular_core.Signal<string>;
+    readonly errorId: _angular_core.Signal<string>;
+    readonly hintId: _angular_core.Signal<string>;
+    /**
+     * Combined lock for the brain `linkedSignal`-based disabled state: the raw
+     * input write always carries the resolved value, so a same-pass
+     * wrapper-toggle + `control.disable()` cannot clobber CVA state.
+     */
+    effectiveDisabled(): boolean;
+    describedBy(): string | null;
+    userClass: _angular_core.InputSignal<ClassValue>;
+    labelClass: _angular_core.InputSignal<string>;
+    groupClass: _angular_core.InputSignal<string>;
+    errorClass: _angular_core.InputSignal<string>;
+    hintClass: _angular_core.InputSignal<string>;
+    $userClass: _angular_core.Signal<string>;
+    $labelClass: _angular_core.Signal<string>;
+    $groupClass: _angular_core.Signal<string>;
+    $errorClass: _angular_core.Signal<string>;
+    $hintClass: _angular_core.Signal<string>;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<EgFormToggleGroup, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<EgFormToggleGroup, "eg-form-toggle-group", never, { "label": { "alias": "label"; "required": false; "isSignal": true; }; "controlId": { "alias": "controlId"; "required": false; "isSignal": true; }; "controlName": { "alias": "controlName"; "required": false; "isSignal": true; }; "error": { "alias": "error"; "required": false; "isSignal": true; }; "hint": { "alias": "hint"; "required": false; "isSignal": true; }; "id": { "alias": "id"; "required": false; "isSignal": true; }; "type": { "alias": "type"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "required": { "alias": "required"; "required": false; "isSignal": true; }; "variant": { "alias": "variant"; "required": false; "isSignal": true; }; "size": { "alias": "size"; "required": false; "isSignal": true; }; "options": { "alias": "options"; "required": false; "isSignal": true; }; "userClass": { "alias": "class"; "required": false; "isSignal": true; }; "labelClass": { "alias": "labelClass"; "required": false; "isSignal": true; }; "groupClass": { "alias": "groupClass"; "required": false; "isSignal": true; }; "errorClass": { "alias": "errorClass"; "required": false; "isSignal": true; }; "hintClass": { "alias": "hintClass"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
+interface EgFormToggleGroupConfig {
+    /**
+     * Global class defaults for `eg-form-toggle-group` styling slots.
+     * Each is merged under the matching per-instance `*Class` input
+     * (library base < global config < per-instance).
+     */
+    labelClass?: string;
+    groupClass?: string;
+    errorClass?: string;
+    hintClass?: string;
+}
+declare function provideEgFormToggleGroupConfig(config: Partial<EgFormToggleGroupConfig>): ValueProvider;
+declare function injectEgFormToggleGroupConfig(): EgFormToggleGroupConfig;
+
+export { EgFormToggleGroup, injectEgFormToggleGroupConfig, provideEgFormToggleGroupConfig };
+export type { EgFormToggleGroupConfig };

package/hover-card/README.md

@@ -1,11 +1,262 @@
-# HoverCard
+# Hover Card (`@egose/shadcn-theme-ng/hover-card`)
 
-This project was generated using [Angular CLI](https://github.com/angular/angular-cli).
+The hover card shows a rich preview panel when the user hovers (or focuses) a trigger — the shadcn/ui _HoverCard_ equivalent (docs link with an author preview, usercard on an `@mention`, product peek on hover). Behavior comes from spartan-ng's `BrnHoverCard` family (CDK overlay under the hood); this subpath adds the shadcn styling and `data-slot` hooks.
 
-## Building
+> **Ships as:** `@egose/shadcn-theme-ng/hover-card` (plain Tailwind) and `@egose/shadcn-theme-ng-tw/hover-card` (`tw:`-prefixed variant). See the [package README](../../README.md) for installation, peer dependencies, and the Tailwind-variant contract. Do not publish this project directory independently.
 
-To build the library, run:
+## Installation
 
 ```bash
-ng build hover-card
+# Plain Tailwind (no prefix)
+npm install @egose/shadcn-theme-ng
+
+# Or the tw:-prefixed variant
+npm install @egose/shadcn-theme-ng-tw
+```
+
+Peer dependencies (Angular, CDK, `@spartan-ng/brain`, `rxjs`) are documented in the [package README](../../README.md#peer-dependencies).
+
+```ts
+import { HlmHoverCardImports } from '@egose/shadcn-theme-ng/hover-card';
+// tw variant:
+// import { HlmHoverCardImports } from '@egose/shadcn-theme-ng-tw/hover-card';
+```
+
+## Imports
+
+```ts
+// Standalone component — spread the imports array:
+import { HlmHoverCardImports } from '@egose/shadcn-theme-ng/hover-card';
+
+@Component({
+  standalone: true,
+  imports: [HlmHoverCardImports],
+  template: `…`,
+})
+export class MyComp {}
+```
+
+```ts
+// NgModule-based — import the module:
+import { HlmHoverCardModule } from '@egose/shadcn-theme-ng/hover-card';
+
+@NgModule({ imports: [HlmHoverCardModule] })
+export class MyModule {}
+```
+
+Individual symbols (all exported from `src/public-api.ts`): `HlmHoverCard`, `HlmHoverCardTrigger`, `HlmHoverCardContent`, `HlmHoverCardPortal`, plus `HlmHoverCardImports` and `HlmHoverCardModule`.
+
+## Anatomy / Structure
+
+```html
+<div hlmHoverCard>
+  <a href="https://example.com" hlmHoverCardTrigger>Hover me</a>
+
+  <!-- structural portal directive + styling directive on the same element -->
+  <hlm-hover-card-content *hlmHoverCardPortal>
+    <p class="tw:font-semibold">@example</p>
+    <p class="tw:text-sm tw:text-gray-500">Preview content goes here.</p>
+  </hlm-hover-card-content>
+</div>
 ```
+
+Real selectors: `[hlmHoverCard]` / `hlm-hover-card` (root, `hostDirectives: [BrnHoverCard]`), `[hlmHoverCardTrigger]` (trigger, `hostDirectives: [BrnHoverCardTrigger]`), `[hlmHoverCardPortal]` / `hlm-hover-card-portal` (structural overlay portal, `hostDirectives: [BrnHoverCardContent]` — used as `*hlmHoverCardPortal`), `[hlmHoverCardContent]` / `hlm-hover-card-content` (styling shell: popover colors, `w-64`, rounded, shadow, open/close animations; mirrors `data-state`/`data-side` attributes).
+
+## API reference
+
+### `hlmHoverCard` / `hlm-hover-card` — `HlmHoverCard`
+
+Thin directive wrapper: `hostDirectives: [BrnHoverCard]`, `data-slot="hover-card"`. No inputs/outputs of its own — it owns the open state shared by trigger and portal.
+
+### `[hlmHoverCardTrigger]` — `HlmHoverCardTrigger`
+
+Thin directive wrapper forwarding these inputs to `BrnHoverCardTrigger` (plus `data-slot="hover-card-trigger"`):
+
+| Input                    | Type    | Description                                                                         |
+| ------------------------ | ------- | ----------------------------------------------------------------------------------- |
+| `showDelay`              | (brain) | Delay before the card opens on hover.                                               |
+| `hideDelay`              | (brain) | Delay before the card closes after pointer leave.                                   |
+| `animationDelay`         | (brain) | Delay applied to the open/close animation.                                          |
+| `sideOffset`             | (brain) | Pixel offset between trigger and card.                                              |
+| `align`                  | (brain) | Overlay alignment (`start` / `center` / `end`).                                     |
+| `hlmHoverCardTriggerFor` | (brain) | Explicit content reference (`brnHoverCardTriggerFor` alias) for non-default wiring. |
+
+### `[hlmHoverCardPortal]` / `hlm-hover-card-portal` — `HlmHoverCardPortal`
+
+Structural directive (`hostDirectives: [BrnHoverCardContent]`). Apply as `*hlmHoverCardPortal` on the content element so the card renders in the CDK overlay. No inputs of its own.
+
+### `[hlmHoverCardContent]` / `hlm-hover-card-content` — `HlmHoverCardContent`
+
+Styling directive for the panel. No inputs/outputs; it reads the overlay `state` (`open`/`closed`) and `side` (`top`/`bottom`/`left`/`right`) signals from the brain providers and reflects them as `data-state` / `data-side` attributes for the animation classes. Default width is `tw:w-64` — override with `class`.
+
+## Examples
+
+### 1. Basic link preview
+
+```ts
+import { Component } from '@angular/core';
+import { HlmHoverCardImports } from '@egose/shadcn-theme-ng/hover-card';
+
+@Component({
+  standalone: true,
+  imports: [HlmHoverCardImports],
+  template: `
+    <div hlmHoverCard>
+      <a href="https://angular.dev" hlmHoverCardTrigger class="tw:cursor-pointer tw:underline tw:text-blue-600">
+        Angular
+      </a>
+      <hlm-hover-card-content *hlmHoverCardPortal>
+        <p class="tw:font-semibold">Angular</p>
+        <p class="tw:text-sm tw:text-gray-500">The web development framework for the modern web.</p>
+      </hlm-hover-card-content>
+    </div>
+  `,
+})
+export class BasicExample {}
+```
+
+### 2. Open/close delays
+
+```ts
+import { Component } from '@angular/core';
+import { HlmHoverCardImports } from '@egose/shadcn-theme-ng/hover-card';
+
+@Component({
+  standalone: true,
+  imports: [HlmHoverCardImports],
+  template: `
+    <div hlmHoverCard>
+      <button hlmHoverCardTrigger type="button" [showDelay]="400" [hideDelay]="200">Hover (opens after 400ms)</button>
+      <hlm-hover-card-content *hlmHoverCardPortal>
+        <p class="tw:text-sm">Delays keep accidental hovers from flashing the card.</p>
+      </hlm-hover-card-content>
+    </div>
+  `,
+})
+export class DelaysExample {}
+```
+
+### 3. Placement: side, align, offset
+
+```ts
+import { Component } from '@angular/core';
+import { HlmHoverCardImports } from '@egose/shadcn-theme-ng/hover-card';
+
+@Component({
+  standalone: true,
+  imports: [HlmHoverCardImports],
+  template: `
+    <div hlmHoverCard>
+      <span hlmHoverCardTrigger [sideOffset]="12" align="start"> Hover for right-side card </span>
+      <hlm-hover-card-content *hlmHoverCardPortal class="tw:w-72">
+        <p class="tw:text-sm">Offset by 12px, aligned to the trigger start edge.</p>
+      </hlm-hover-card-content>
+    </div>
+  `,
+})
+export class PlacementExample {}
+```
+
+> `side` itself is owned by the brain content directive — set alignment/offset on the trigger; the `data-side` attribute on the content element reflects the resolved side for animations.
+
+### 4. User card with avatar + stats
+
+```ts
+import { Component } from '@angular/core';
+import { HlmHoverCardImports } from '@egose/shadcn-theme-ng/hover-card';
+import { HlmAvatarImports } from '@egose/shadcn-theme-ng/avatar';
+
+@Component({
+  standalone: true,
+  imports: [HlmHoverCardImports, HlmAvatarImports],
+  template: `
+    <div hlmHoverCard>
+      <span hlmHoverCardTrigger class="tw:cursor-pointer tw:font-medium tw:underline">@jane</span>
+      <hlm-hover-card-content *hlmHoverCardPortal class="tw:w-80">
+        <div class="tw:flex tw:gap-4">
+          <hlm-avatar size="sm">
+            <img hlmAvatarImage src="https://github.com/jane.png" alt="Jane's avatar" />
+            <span hlmAvatarFallback>JA</span>
+          </hlm-avatar>
+          <div>
+            <p class="tw:font-semibold">@jane</p>
+            <p class="tw:text-sm tw:text-gray-500">Design engineer. Ships accessible UI.</p>
+            <p class="tw:mt-2 tw:text-xs tw:text-gray-500">1.2k followers · 84 following</p>
+          </div>
+        </div>
+      </hlm-hover-card-content>
+    </div>
+  `,
+})
+export class UserCardExample {}
+```
+
+### 5. Wide content (override the default `w-64`)
+
+```ts
+import { Component } from '@angular/core';
+import { HlmHoverCardImports } from '@egose/shadcn-theme-ng/hover-card';
+
+@Component({
+  standalone: true,
+  imports: [HlmHoverCardImports],
+  template: `
+    <div hlmHoverCard>
+      <button hlmHoverCardTrigger type="button">Product peek</button>
+      <hlm-hover-card-content *hlmHoverCardPortal class="tw:w-96">
+        <div class="tw:grid tw:grid-cols-[64px_1fr] tw:gap-3">
+          <div class="tw:h-16 tw:w-16 tw:rounded-md tw:bg-slate-200"></div>
+          <div>
+            <p class="tw:font-semibold">Ergonomic keyboard</p>
+            <p class="tw:text-sm tw:text-gray-500">Silent switches · $149 · In stock</p>
+          </div>
+        </div>
+      </hlm-hover-card-content>
+    </div>
+  `,
+})
+export class WideExample {}
+```
+
+### 6. NgModule usage + keyboard-focusable trigger
+
+Hover cards also open on keyboard focus, so a natively focusable trigger keeps them reachable without a mouse:
+
+```ts
+import { NgModule, Component } from '@angular/core';
+import { HlmHoverCardModule } from '@egose/shadcn-theme-ng/hover-card';
+
+@Component({
+  selector: 'app-hover-demo',
+  template: `
+    <div hlmHoverCard>
+      <button hlmHoverCardTrigger type="button">Focus me with Tab, then hover away</button>
+      <hlm-hover-card-content *hlmHoverCardPortal>
+        <p class="tw:text-sm">Focus opens the card too — no mouse required.</p>
+      </hlm-hover-card-content>
+    </div>
+  `,
+})
+export class HoverDemoComponent {}
+
+@NgModule({ declarations: [HoverDemoComponent], imports: [HlmHoverCardModule] })
+export class HoverDemoModule {}
+```
+
+## Accessibility notes
+
+- Use a natively focusable trigger (`<a href>`, `<button>`) — the card opens on focus as well as hover, which keeps keyboard users in the loop.
+- Keep the card content supplementary: never put the _only_ copy of critical information (or interactive controls) inside a hover-only panel, since touch users and keyboard users may dismiss it easily.
+- The brain layer handles overlay dismissal (Escape / outside pointer). Avoid `showDelay`s so long that keyboard focus has already moved on.
+- If the trigger is an icon or avatar without text, give it an `aria-label` describing what the preview shows.
+
+## Theming / CSS variables
+
+No component-specific CSS variables; the panel uses the shared `--popover` / `--popover-foreground` / `--ring` tokens. Widen with `class="tw:w-…"`, or restyle padding via `class` overrides.
+
+## Related subpaths
+
+- `@egose/shadcn-theme-ng/popover` — click-triggered counterpart (same portal/content pattern).
+- `@egose/shadcn-theme-ng/tooltip` — lightweight text-only hover hints.
+- `@egose/shadcn-theme-ng/avatar` — typical media inside user preview cards.
+- `@egose/shadcn-theme-ng/dialog` — modal alternative when the content needs interaction.