@egose/shadcn-theme-ng 0.0.28 → 0.2.0

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.

package/hover-card/fesm2022/hover-card.mjs

@@ -6,10 +6,10 @@ import { injectExposesStateProvider, injectExposedSideProvider } from '@spartan-
 import { classes } from '@egose/shadcn-theme-ng/utils';
 
 class HlmHoverCard {
-    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "22.0.7", ngImport: i0, type: HlmHoverCard, deps: [], target: i0.ɵɵFactoryTarget.Directive });
-    static ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "14.0.0", version: "22.0.7", type: HlmHoverCard, isStandalone: true, selector: "[hlmHoverCard],hlm-hover-card", host: { attributes: { "data-slot": "hover-card" } }, hostDirectives: [{ directive: i1.BrnHoverCard }], ngImport: i0 });
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "22.1.3", ngImport: i0, type: HlmHoverCard, deps: [], target: i0.ɵɵFactoryTarget.Directive });
+    static ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "14.0.0", version: "22.1.3", type: HlmHoverCard, isStandalone: true, selector: "[hlmHoverCard],hlm-hover-card", host: { attributes: { "data-slot": "hover-card" } }, hostDirectives: [{ directive: i1.BrnHoverCard }], ngImport: i0 });
 }
-i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.0.7", ngImport: i0, type: HlmHoverCard, decorators: [{
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.1.3", ngImport: i0, type: HlmHoverCard, decorators: [{
             type: Directive,
             args: [{
                     selector: '[hlmHoverCard],hlm-hover-card',
@@ -31,14 +31,14 @@ class HlmHoverCardContent {
             this._renderer.setAttribute(this._element.nativeElement, 'data-side', this.side());
         });
         classes(() => [
-            'data-open:animate-in data-closed:animate-out data-closed:fade-out-0 data-open:fade-in-0 data-closed:zoom-out-95 data-open:zoom-in-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 ring-foreground/10 bg-popover text-popover-foreground w-64 rounded-lg p-4 text-sm shadow-md ring-1 duration-100 z-50 outline-none',
-            'data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2',
+            "data-open:animate-in data-closed:animate-out data-closed:fade-out-0 data-open:fade-in-0 data-closed:zoom-out-95 data-open:zoom-in-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 ring-foreground/10 bg-popover text-popover-foreground w-64 rounded-lg p-4 text-sm shadow-md ring-1 duration-100 z-50 outline-none",
+            "data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2",
         ]);
     }
-    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "22.0.7", ngImport: i0, type: HlmHoverCardContent, deps: [], target: i0.ɵɵFactoryTarget.Directive });
-    static ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "14.0.0", version: "22.0.7", type: HlmHoverCardContent, isStandalone: true, selector: "[hlmHoverCardContent],hlm-hover-card-content", host: { attributes: { "data-slot": "hover-card-content" } }, ngImport: i0 });
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "22.1.3", ngImport: i0, type: HlmHoverCardContent, deps: [], target: i0.ɵɵFactoryTarget.Directive });
+    static ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "14.0.0", version: "22.1.3", type: HlmHoverCardContent, isStandalone: true, selector: "[hlmHoverCardContent],hlm-hover-card-content", host: { attributes: { "data-slot": "hover-card-content" } }, ngImport: i0 });
 }
-i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.0.7", ngImport: i0, type: HlmHoverCardContent, decorators: [{
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.1.3", ngImport: i0, type: HlmHoverCardContent, decorators: [{
             type: Directive,
             args: [{
                     selector: '[hlmHoverCardContent],hlm-hover-card-content',
@@ -49,10 +49,10 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.0.7", ngImpor
         }], ctorParameters: () => [] });
 
 class HlmHoverCardPortal {
-    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "22.0.7", ngImport: i0, type: HlmHoverCardPortal, deps: [], target: i0.ɵɵFactoryTarget.Directive });
-    static ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "14.0.0", version: "22.0.7", type: HlmHoverCardPortal, isStandalone: true, selector: "[hlmHoverCardPortal],hlm-hover-card-portal", hostDirectives: [{ directive: i1.BrnHoverCardContent }], ngImport: i0 });
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "22.1.3", ngImport: i0, type: HlmHoverCardPortal, deps: [], target: i0.ɵɵFactoryTarget.Directive });
+    static ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "14.0.0", version: "22.1.3", type: HlmHoverCardPortal, isStandalone: true, selector: "[hlmHoverCardPortal],hlm-hover-card-portal", hostDirectives: [{ directive: i1.BrnHoverCardContent }], ngImport: i0 });
 }
-i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.0.7", ngImport: i0, type: HlmHoverCardPortal, decorators: [{
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.1.3", ngImport: i0, type: HlmHoverCardPortal, decorators: [{
             type: Directive,
             args: [{
                     selector: '[hlmHoverCardPortal],hlm-hover-card-portal',
@@ -61,10 +61,10 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.0.7", ngImpor
         }] });
 
 class HlmHoverCardTrigger {
-    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "22.0.7", ngImport: i0, type: HlmHoverCardTrigger, deps: [], target: i0.ɵɵFactoryTarget.Directive });
-    static ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "14.0.0", version: "22.0.7", type: HlmHoverCardTrigger, isStandalone: true, selector: "[hlmHoverCardTrigger]", host: { attributes: { "data-slot": "hover-card-trigger" } }, hostDirectives: [{ directive: i1.BrnHoverCardTrigger, inputs: ["showDelay", "showDelay", "hideDelay", "hideDelay", "animationDelay", "animationDelay", "sideOffset", "sideOffset", "align", "align", "brnHoverCardTriggerFor", "hlmHoverCardTriggerFor"] }], ngImport: i0 });
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "22.1.3", ngImport: i0, type: HlmHoverCardTrigger, deps: [], target: i0.ɵɵFactoryTarget.Directive });
+    static ɵdir = i0.ɵɵngDeclareDirective({ minVersion: "14.0.0", version: "22.1.3", type: HlmHoverCardTrigger, isStandalone: true, selector: "[hlmHoverCardTrigger]", host: { attributes: { "data-slot": "hover-card-trigger" } }, hostDirectives: [{ directive: i1.BrnHoverCardTrigger, inputs: ["showDelay", "showDelay", "hideDelay", "hideDelay", "animationDelay", "animationDelay", "sideOffset", "sideOffset", "align", "align", "brnHoverCardTriggerFor", "hlmHoverCardTriggerFor"] }], ngImport: i0 });
 }
-i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.0.7", ngImport: i0, type: HlmHoverCardTrigger, decorators: [{
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.1.3", ngImport: i0, type: HlmHoverCardTrigger, decorators: [{
             type: Directive,
             args: [{
                     selector: '[hlmHoverCardTrigger]',
@@ -97,17 +97,17 @@ const HlmHoverCardImports = [
     HlmHoverCardTrigger,
 ];
 class HlmHoverCardModule {
-    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "22.0.7", ngImport: i0, type: HlmHoverCardModule, deps: [], target: i0.ɵɵFactoryTarget.NgModule });
-    static ɵmod = i0.ɵɵngDeclareNgModule({ minVersion: "14.0.0", version: "22.0.7", ngImport: i0, type: HlmHoverCardModule, imports: [HlmHoverCardContent,
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "22.1.3", ngImport: i0, type: HlmHoverCardModule, deps: [], target: i0.ɵɵFactoryTarget.NgModule });
+    static ɵmod = i0.ɵɵngDeclareNgModule({ minVersion: "14.0.0", version: "22.1.3", ngImport: i0, type: HlmHoverCardModule, imports: [HlmHoverCardContent,
             HlmHoverCardPortal,
             HlmHoverCard,
             HlmHoverCardTrigger], exports: [HlmHoverCardContent,
             HlmHoverCardPortal,
             HlmHoverCard,
             HlmHoverCardTrigger] });
-    static ɵinj = i0.ɵɵngDeclareInjector({ minVersion: "12.0.0", version: "22.0.7", ngImport: i0, type: HlmHoverCardModule });
+    static ɵinj = i0.ɵɵngDeclareInjector({ minVersion: "12.0.0", version: "22.1.3", ngImport: i0, type: HlmHoverCardModule });
 }
-i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.0.7", ngImport: i0, type: HlmHoverCardModule, decorators: [{
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.1.3", ngImport: i0, type: HlmHoverCardModule, decorators: [{
             type: NgModule,
             args: [{
                     imports: [...HlmHoverCardImports],
@@ -120,4 +120,4 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.0.7", ngImpor
  */
 
 export { HlmHoverCard, HlmHoverCardContent, HlmHoverCardImports, HlmHoverCardModule, HlmHoverCardPortal, HlmHoverCardTrigger };
-//# sourceMappingURL=hover-card.mjs.map
+

package/icon/README.md

@@ -1,64 +1,240 @@
-# Icon
+# Icon (`@egose/shadcn-theme-ng/icon`)
 
-This project was generated using [Angular CLI](https://github.com/angular/angular-cli) version 20.2.0.
+`HlmIcon` is a thin directive that sizes `@ng-icons/core` icons consistently with the shadcn theme. It applies to `ng-icon` elements (`selector: 'ng-icon[hlm]'`) and maps t-shirt sizes (`xs`–`xl`) to pixel values via the `--ng-icon__size` CSS variable — the shadcn/ui equivalent of the `size-*` icon convention. A global default size can be set once with `provideHlmIconConfig`.
 
-## Code scaffolding
+> **Ships as:** `@egose/shadcn-theme-ng/icon` (plain Tailwind) and `@egose/shadcn-theme-ng-tw/icon` (`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.
 
-Angular CLI includes powerful code scaffolding tools. To generate a new component, run:
+## Installation
 
 ```bash
-ng generate component component-name
+# Plain Tailwind (no prefix)
+npm install @egose/shadcn-theme-ng
+
+# Or the tw:-prefixed variant
+npm install @egose/shadcn-theme-ng-tw
 ```
 
-For a complete list of available schematics (such as `components`, `directives`, or `pipes`), run:
+Peer dependencies (Angular, `@ng-icons/core`, …) are documented in the [package README](../../README.md#peer-dependencies). You must also register the icons you use with `provideIcons` from `@ng-icons/core` (see examples).
 
-```bash
-ng generate --help
+```ts
+import { HlmIconImports } from '@egose/shadcn-theme-ng/icon';
+// tw variant:
+// import { HlmIconImports } from '@egose/shadcn-theme-ng-tw/icon';
 ```
 
-## Building
+## Imports
 
-To build the library, run:
+```ts
+// Standalone component — spread the imports array:
+import { HlmIconImports } from '@egose/shadcn-theme-ng/icon';
 
-```bash
-ng build icon
+@Component({
+  standalone: true,
+  imports: [NgIcon, ...HlmIconImports], // or just [NgIcon, HlmIcon]
+  providers: [provideIcons({ lucidePlus })],
+  template: `<ng-icon hlm name="lucidePlus" size="sm" />`,
+})
+export class MyComp {}
 ```
 
-This command will compile your project, and the build artifacts will be placed in the `dist/` directory.
+```ts
+// NgModule-based — import the module:
+import { HlmIconModule } from '@egose/shadcn-theme-ng/icon';
 
-### Publishing the Library
+@NgModule({ imports: [HlmIconModule] })
+export class MyModule {}
+```
 
-Once the project is built, you can publish your library by following these steps:
+Exported from `src/public-api.ts`: `HlmIcon`, `IconSize`, `HlmIconConfig`, `provideHlmIconConfig`, `injectHlmIconConfig`, plus `HlmIconImports` and `HlmIconModule`.
 
-1. Navigate to the `dist` directory:
+> Note: `HlmIcon` decorates `ng-icon` — you still import `NgIcon` itself from `@ng-icons/core` and register glyphs with `provideIcons`.
 
-   ```bash
-   cd dist/icon
-   ```
+## Anatomy / Structure
 
-2. Run the `npm publish` command to publish your library to the npm registry:
-   ```bash
-   npm publish
-   ```
+```html
+<!-- hlm attribute activates the sizing directive on any ng-icon -->
+<ng-icon hlm name="lucidePlus" size="sm" />
+```
 
-## Running unit tests
+The directive sets `[style.--ng-icon__size]` from the `size` input; named sizes resolve to pixels, anything else passes through verbatim as CSS.
 
-To execute unit tests with the [Karma](https://karma-runner.github.io) test runner, use the following command:
+## API reference
 
-```bash
-ng test
+### `ng-icon[hlm]` — `HlmIcon`
+
+| Input  | Type       | Default                 | Description                                                                                                                                              |
+| ------ | ---------- | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `size` | `IconSize` | config default (`base`) | `xs` → `12px`, `sm` → `16px`, `base` → `24px`, `lg` → `32px`, `xl` → `48px`, `none` → `none`, or any custom CSS size string (e.g. `'20px'`, `'1.5rem'`). |
+
+No outputs. `IconSize = 'xs' | 'sm' | 'base' | 'lg' | 'xl' | 'none' | (string & {})`.
+
+### Config — `HlmIconConfig` / `provideHlmIconConfig` / `injectHlmIconConfig`
+
+| API                                                    | Signature               | Description                                                                           |
+| ------------------------------------------------------ | ----------------------- | ------------------------------------------------------------------------------------- |
+| `HlmIconConfig`                                        | `{ size: IconSize }`    | Global icon config shape (default `{ size: 'base' }`).                                |
+| `provideHlmIconConfig(config: Partial<HlmIconConfig>)` | returns `ValueProvider` | Provide once (root or feature) to change the default `size` for every `ng-icon[hlm]`. |
+| `injectHlmIconConfig()`                                | returns `HlmIconConfig` | Reads the ambient config (falls back to defaults).                                    |
+
+## Examples
+
+### 1. Basic icon with registered glyph
+
+```ts
+import { Component } from '@angular/core';
+import { NgIcon, provideIcons } from '@ng-icons/core';
+import { lucidePlus } from '@ng-icons/lucide';
+import { HlmIcon } from '@egose/shadcn-theme-ng/icon';
+
+@Component({
+  standalone: true,
+  imports: [NgIcon, HlmIcon],
+  providers: [provideIcons({ lucidePlus })],
+  template: `<ng-icon hlm name="lucidePlus" />`,
+})
+export class BasicExample {}
 ```
 
-## Running end-to-end tests
+### 2. All named sizes
+
+```ts
+import { Component } from '@angular/core';
+import { NgIcon, provideIcons } from '@ng-icons/core';
+import { lucideSearch } from '@ng-icons/lucide';
+import { HlmIconImports } from '@egose/shadcn-theme-ng/icon';
+
+@Component({
+  standalone: true,
+  imports: [NgIcon, HlmIconImports],
+  providers: [provideIcons({ lucideSearch })],
+  template: `
+    <div class="tw:flex tw:items-center tw:gap-4">
+      <ng-icon hlm name="lucideSearch" size="xs" />
+      <ng-icon hlm name="lucideSearch" size="sm" />
+      <ng-icon hlm name="lucideSearch" size="base" />
+      <ng-icon hlm name="lucideSearch" size="lg" />
+      <ng-icon hlm name="lucideSearch" size="xl" />
+    </div>
+  `,
+})
+export class SizesExample {}
+```
 
-For end-to-end (e2e) testing, run:
+### 3. Custom CSS sizes (any string passes through)
+
+```ts
+import { Component } from '@angular/core';
+import { NgIcon, provideIcons } from '@ng-icons/core';
+import { lucideBell } from '@ng-icons/lucide';
+import { HlmIcon } from '@egose/shadcn-theme-ng/icon';
+
+@Component({
+  standalone: true,
+  imports: [NgIcon, HlmIcon],
+  providers: [provideIcons({ lucideBell })],
+  template: `
+    <div class="tw:flex tw:items-center tw:gap-4">
+      <ng-icon hlm name="lucideBell" size="20px" />
+      <ng-icon hlm name="lucideBell" size="1.5rem" />
+      <ng-icon hlm name="lucideBell" size="none" />
+    </div>
+  `,
+})
+export class CustomSizeExample {}
+```
 
-```bash
-ng e2e
+### 4. Global default via `provideHlmIconConfig`
+
+```ts
+import { Component } from '@angular/core';
+import { NgIcon, provideIcons } from '@ng-icons/core';
+import { lucideCheck, lucideX } from '@ng-icons/lucide';
+import { HlmIcon, provideHlmIconConfig } from '@egose/shadcn-theme-ng/icon';
+
+@Component({
+  standalone: true,
+  imports: [NgIcon, HlmIcon],
+  providers: [provideIcons({ lucideCheck, lucideX }), provideHlmIconConfig({ size: 'sm' })],
+  template: `
+    <!-- both inherit size="sm" unless overridden -->
+    <ng-icon hlm name="lucideCheck" />
+    <ng-icon hlm name="lucideX" size="lg" />
+  `,
+})
+export class ConfigExample {}
+```
+
+### 5. Icons inside buttons and inputs (composition)
+
+```ts
+import { Component } from '@angular/core';
+import { NgIcon, provideIcons } from '@ng-icons/core';
+import { lucideSearch, lucidePlus } from '@ng-icons/lucide';
+import { HlmIcon } from '@egose/shadcn-theme-ng/icon';
+import { HlmButton } from '@egose/shadcn-theme-ng/button';
+import { HlmInputGroupImports } from '@egose/shadcn-theme-ng/input-group';
+
+@Component({
+  standalone: true,
+  imports: [NgIcon, HlmIcon, HlmButton, HlmInputGroupImports],
+  providers: [provideIcons({ lucideSearch, lucidePlus })],
+  template: `
+    <button hlmBtn type="button"><ng-icon hlm name="lucidePlus" size="sm" /> New item</button>
+
+    <div hlmInputGroup>
+      <span hlmInputGroupText><ng-icon hlm name="lucideSearch" size="sm" /></span>
+      <input hlmInputGroupInput placeholder="Search…" aria-label="Search" />
+    </div>
+  `,
+})
+export class CompositionExample {}
+```
+
+> The input-group addon styles (`[&>ng-icon…]` hooks) assume icons sized through this directive — prefer `size="sm"` or smaller inside addons/buttons so text and glyph align.
+
+### 6. Dynamic icon + size with signals
+
+```ts
+import { Component, signal } from '@angular/core';
+import { NgIcon, provideIcons } from '@ng-icons/core';
+import { lucideLoaderCircle, lucideCheck } from '@ng-icons/lucide';
+import { HlmIcon, type IconSize } from '@egose/shadcn-theme-ng/icon';
+
+@Component({
+  standalone: true,
+  imports: [NgIcon, HlmIcon],
+  providers: [provideIcons({ lucideLoaderCircle, lucideCheck })],
+  template: `
+    <p>
+      <ng-icon hlm [name]="saving() ? 'lucideLoaderCircle' : 'lucideCheck'" [size]="iconSize()" />
+      {{ saving() ? 'Saving…' : 'Saved' }}
+    </p>
+    <button type="button" (click)="toggleSize()">Toggle size</button>
+  `,
+})
+export class DynamicExample {
+  readonly saving = signal(true);
+  readonly iconSize = signal<IconSize>('sm');
+
+  toggleSize() {
+    this.iconSize.update((s) => (s === 'sm' ? 'lg' : 'sm'));
+  }
+}
 ```
 
-Angular CLI does not come with an end-to-end testing framework by default. You can choose one that suits your needs.
+## Accessibility notes
+
+- `ng-icon` renders decorative SVG — screen readers ignore it by default. When an icon is the _only_ content of a button/link, put the accessible name on the control (`aria-label="Search"`), not on the icon.
+- Never convey status by icon alone (e.g. a lone red `x` for errors); pair it with text or an `role="status"` message.
+- Icon buttons need a visible focus indicator and at least a 24px (ideally 44px) hit area — use the button size variants rather than shrinking the control to the glyph.
+
+## Theming / CSS variables
+
+Sizing flows through the `--ng-icon__size` CSS variable set by the directive; color inherits `currentColor`, so icons follow surrounding text/foreground tokens automatically. No component-specific theme variables.
 
-## 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/button` — icon buttons and icon+label composition.
+- `@egose/shadcn-theme-ng/input-group` — addon slots with `ng-icon` styling hooks.
+- `@egose/shadcn-theme-ng/badge` — common icon+text pill composition.
+- `@egose/shadcn-theme-ng/spinner` — animated loading indicator alternative.