@ng-zen/cli 21.2.0 → 21.3.0-next.1

package/CHANGELOG.md

@@ -1,11 +1,13 @@
-## [21.2.0](https://github.com/kstepien3/ng-zen/compare/v21.1.1...v21.2.0) (2026-03-11)
+## [21.3.0-next.1](https://github.com/kstepien3/ng-zen/compare/v21.2.0...v21.3.0-next.1) (2026-06-12)
 
 ### 🚀 New Features
 
-* **dialog:** add reusable dialog component with service and tests ([#387](https://github.com/kstepien3/ng-zen/issues/387)) ([1cb90f6](https://github.com/kstepien3/ng-zen/commit/1cb90f6c5b89b63a461abe6d45da74869275ff12))
+* **button:** enhance component's sizes, variants, and styling updates ([#407](https://github.com/kstepien3/ng-zen/issues/407)) ([f32aad3](https://github.com/kstepien3/ng-zen/commit/f32aad35d5853f832f2eea0d8157884ca7f5cc3e))
+* **button:** migrate to dynamic CSS variables and refactor styles ([#411](https://github.com/kstepien3/ng-zen/issues/411)) ([e4464f7](https://github.com/kstepien3/ng-zen/commit/e4464f7580c91f0de30d9139177655915430fd43))
+* **popover:** improve popover styles, stories, docs ([#404](https://github.com/kstepien3/ng-zen/issues/404)) ([6515443](https://github.com/kstepien3/ng-zen/commit/65154436cde09f77909638ef84e2213b04f2862c))
 
 ### 📚 Documentation
 
-* **README:** update storybook tag ([#395](https://github.com/kstepien3/ng-zen/issues/395)) ([114dfdc](https://github.com/kstepien3/ng-zen/commit/114dfdc87614345784b264a6bde6be73b5e93aa7))
+* **README:** add DeepWiki link ([#409](https://github.com/kstepien3/ng-zen/issues/409)) ([7875347](https://github.com/kstepien3/ng-zen/commit/78753471c6e56036788c6371ce0f063ab06b524b))
 
 Development mode - changelog will be generated during build.

package/README.md

@@ -22,7 +22,13 @@
       <img src="https://img.shields.io/badge/-Repository-181818?style=flat&logo=github&logoColor=white" alt="Repository" />
     </a>
     <a href="https://kstepien3.github.io/ng-zen/">
-      <img src="https://img.shields.io/badge/-Storybook%20Demo-FF4785?style=flat&logo=storybook&logoColor=white" alt="Storybook" />
+      <img src="https://img.shields.io/badge/-Storybook-FF4785?style=flat&logo=storybook&logoColor=white" alt="Storybook" />
+    </a>
+  </p>
+
+  <p>
+    <a href="https://deepwiki.com/kstepien3/ng-zen">
+      <img src="https://deepwiki.com/badge.svg" alt="DeepWiki" />
     </a>
   </p>
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ng-zen/cli",
-  "version": "21.2.0",
+  "version": "21.3.0-next.1",
   "description": "Angular UI components generator – Zen UI Kit CLI for schematics-based creation of customizable components like avatar, button, checkbox, divider, form-control, icon, input, skeleton, switch, textarea with Storybook demos.",
   "license": "BSD-2-Clause",
   "private": false,
@@ -65,14 +65,11 @@
   },
   "schematics": "./schematics/collection.json",
   "packageManager": "pnpm@10.24.0",
-  "peerDependencies": {
-    "@angular/common": ">=20.0.0",
-    "@angular/core": ">=20.0.0"
-  },
+  "peerDependencies": {},
   "dependencies": {
-    "@angular-devkit/core": "^21.0.1",
-    "@angular-devkit/schematics": "^21.0.1",
-    "@angular/build": "21.0.1",
+    "@angular-devkit/core": "^22.0.1",
+    "@angular-devkit/schematics": "^22.0.1",
+    "@angular/build": "22.0.1",
     "tslib": "^2.8.1"
   }
 }

package/schematics/ui/files/button/button.scss

@@ -1,49 +1,185 @@
+@use 'sass:map';
+
 // Globals
-$transition-duration: var(--zen-transition-duration, 0.4s);
+$transition-duration: var(--zen-transition-duration, 0.2s);
 $outline: var(--zen-outline, 2px solid hsl(200deg 100% 50% / 50%));
 
 :host {
-  --zen-button-padding: 0.5rem 1rem;
-  --zen-button-bg-color: hsl(0deg 0% 0%);
-  --zen-button-bg-color-hover: hsl(0deg 0% 20%);
-  --zen-button-color: hsl(0deg 0% 100%);
   --zen-button-shadow: 0 2px 4px hsl(0deg 0% 0% / 10%);
+  --zen-button-neutral: var(--zen-neutral, hsl(30deg 5% 10%));
+  --zen-button-primary: var(--zen-primary, hsl(193deg 58% 34%));
+  --zen-button-success: var(--zen-success, hsl(142deg 38% 36%));
+  --zen-button-warning: var(--zen-warning, hsl(36deg 72% 46%));
+  --zen-button-danger: var(--zen-danger, hsl(348deg 52% 42%));
+  --zen-button-info: var(--zen-info, hsl(214deg 34% 46%));
 }
 
+$sizes: (
+  sm: (
+    padding: 0.35rem 0.625rem,
+    font-size: 0.75rem,
+    gap: 0.375rem,
+  ),
+  md: (
+    padding: 0.5rem 0.875rem,
+    font-size: 0.875rem,
+    gap: 0.5rem,
+  ),
+  lg: (
+    padding: 0.625rem 1rem,
+    font-size: 1rem,
+    gap: 0.5rem,
+  ),
+);
+$colors: (
+  primary: var(--zen-button-primary),
+  success: var(--zen-button-success),
+  warning: var(--zen-button-warning),
+  danger: var(--zen-button-danger),
+  info: var(--zen-button-info),
+);
+
+// Color mix percentages for filled variant states
+$filled-base-opacity: 8%;
+$filled-hover-opacity: 15%;
+$filled-active-opacity: 25%;
+
+// Ghost/Link variant opacity levels
+$ghost-hover-opacity: 10%;
+$ghost-active-opacity: 20%;
+
+// Outline variant opacity levels
+$outline-hover-opacity: 70%;
+$outline-active-bg-opacity: 20%;
+
+// Disabled state
+$disabled-opacity: 0.6;
+
+// Default state hover/active mixing ratios (oklch)
+$default-hover-mix: 85%;
+$default-active-mix: 75%;
+
 /* stylelint-disable-next-line no-duplicate-selectors -- separate variables and styles */
 :host {
-  padding: var(--zen-button-padding);
+  --zen-button-bg-color: var(--zen-button-neutral); // default
+
   background-color: var(--zen-button-bg-color);
-  color: var(--zen-button-color);
-  box-shadow: var(--zen-button-shadow);
-  display: inline-block;
-  font-size: 14px;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  line-height: 1;
   font-weight: bold;
   text-align: center;
+  text-decoration: none;
+  white-space: nowrap;
+  user-select: none;
   cursor: pointer;
   border: none;
-  border-radius: 99999px;
-  transition-property: background-color, opacity;
-  transition-duration: $transition-duration;
-  transition-timing-function: ease;
-  text-decoration: none;
-  overflow: hidden;
-  position: relative;
+  border-radius: 0.625rem;
+  box-shadow: var(--zen-button-shadow);
+  transition:
+    background-color $transition-duration ease,
+    transform $transition-duration ease,
+    color $transition-duration ease,
+    border-color $transition-duration ease;
+  color: var(--zen-button-color, contrast-color(var(--zen-button-bg-color)));
 }
 
-/* Hover state */
 :host:hover {
-  background-color: var(--zen-button-bg-color-hover);
+  background-color: color-mix(in oklch, var(--zen-button-bg-color) $default-hover-mix, var(--zen-button-color, white));
+}
+
+:host:active {
+  background-color: color-mix(in oklch, var(--zen-button-bg-color) $default-active-mix, var(--zen-button-color, white));
+  transform: translateY(1px);
 }
 
-/* Focus state */
 :host:focus-visible {
   outline: $outline;
+  outline-offset: 2px;
 }
 
-/* Disabled state */
-:host[aria-disabled]:not([aria-disabled='false']),
-:host[disabled]:not([disabled='false']) {
+:host([disabled]) {
   cursor: not-allowed;
-  opacity: 0.6;
+  opacity: $disabled-opacity;
+  pointer-events: none;
+}
+
+// --- SIZES ---
+@each $name, $config in $sizes {
+  :host([data-size='#{$name}']) {
+    padding: map.get($config, padding);
+    font-size: map.get($config, font-size);
+    gap: map.get($config, gap);
+  }
+}
+
+// --- COLORS ---
+@each $name, $bg-color in $colors {
+  :host([data-color='#{$name}']) {
+    --zen-button-bg-color: #{$bg-color};
+  }
+}
+
+// --- VARIANTS ---
+
+/* Outline variant */
+:host([data-variant='outline']) {
+  background-color: transparent;
+  color: var(--zen-button-bg-color);
+  border-width: 1px;
+  border-style: solid;
+  border-color: var(--zen-button-bg-color);
+  box-shadow: none;
+
+  &:hover {
+    color: color-mix(in oklch, var(--zen-button-bg-color) $outline-hover-opacity, transparent);
+    border-color: color-mix(in oklch, var(--zen-button-bg-color) $outline-hover-opacity, transparent);
+  }
+
+  &:active {
+    background-color: color-mix(in oklch, var(--zen-button-bg-color) $outline-active-bg-opacity, transparent);
+  }
+}
+
+/* Filled variant */
+:host([data-variant='filled']) {
+  background-color: color-mix(in oklch, var(--zen-button-bg-color) $filled-base-opacity, transparent);
+  color: var(--zen-button-bg-color);
+  box-shadow: none;
+
+  &:hover {
+    background-color: color-mix(in oklch, var(--zen-button-bg-color) $filled-hover-opacity, transparent);
+  }
+
+  &:active {
+    background-color: color-mix(in oklch, var(--zen-button-bg-color) $filled-active-opacity, transparent);
+  }
+}
+
+/* Ghost and Link variants */
+:host([data-variant='ghost']),
+:host([data-variant='link']) {
+  background-color: transparent;
+  color: var(--zen-button-bg-color);
+  box-shadow: none;
+
+  &:hover {
+    background-color: color-mix(in oklch, var(--zen-button-bg-color) $ghost-hover-opacity, transparent);
+  }
+
+  &:active {
+    background-color: color-mix(in oklch, var(--zen-button-bg-color) $ghost-active-opacity, transparent);
+  }
+}
+
+/* Link variant only */
+:host([data-variant='link']) {
+  text-decoration: underline;
+  text-underline-offset: 0.2em;
+  text-decoration-thickness: 1px;
+
+  &:hover {
+    text-decoration-thickness: 2px;
+  }
 }

package/schematics/ui/files/button/button.spec.ts

@@ -17,4 +17,73 @@ describe('ZenButton', () => {
     const component = fixture.componentInstance;
     expect(component).toBeTruthy();
   });
+
+  it('should have default size md', () => {
+    const fixture = TestBed.createComponent(ZenButton);
+    fixture.detectChanges();
+    const button = fixture.nativeElement as HTMLButtonElement;
+    expect(button.getAttribute('data-size')).toBe('md');
+  });
+
+  it('should have default color neutral', () => {
+    const fixture = TestBed.createComponent(ZenButton);
+    fixture.detectChanges();
+    const button = fixture.nativeElement as HTMLButtonElement;
+    expect(button.getAttribute('data-color')).toBe('neutral');
+  });
+
+  it('should have default variant solid', () => {
+    const fixture = TestBed.createComponent(ZenButton);
+    fixture.detectChanges();
+    const button = fixture.nativeElement as HTMLButtonElement;
+    expect(button.getAttribute('data-variant')).toBe('solid');
+  });
+
+  it('should apply size sm', () => {
+    const fixture = TestBed.createComponent(ZenButton);
+    fixture.componentRef.setInput('size', 'sm');
+    fixture.detectChanges();
+    const button = fixture.nativeElement as HTMLButtonElement;
+    expect(button.getAttribute('data-size')).toBe('sm');
+  });
+
+  it('should apply size lg', () => {
+    const fixture = TestBed.createComponent(ZenButton);
+    fixture.componentRef.setInput('size', 'lg');
+    fixture.detectChanges();
+    const button = fixture.nativeElement as HTMLButtonElement;
+    expect(button.getAttribute('data-size')).toBe('lg');
+  });
+
+  it('should apply color primary', () => {
+    const fixture = TestBed.createComponent(ZenButton);
+    fixture.componentRef.setInput('color', 'primary');
+    fixture.detectChanges();
+    const button = fixture.nativeElement as HTMLButtonElement;
+    expect(button.getAttribute('data-color')).toBe('primary');
+  });
+
+  it('should apply variant outline', () => {
+    const fixture = TestBed.createComponent(ZenButton);
+    fixture.componentRef.setInput('variant', 'outline');
+    fixture.detectChanges();
+    const button = fixture.nativeElement as HTMLButtonElement;
+    expect(button.getAttribute('data-variant')).toBe('outline');
+  });
+
+  it('should apply variant ghost', () => {
+    const fixture = TestBed.createComponent(ZenButton);
+    fixture.componentRef.setInput('variant', 'ghost');
+    fixture.detectChanges();
+    const button = fixture.nativeElement as HTMLButtonElement;
+    expect(button.getAttribute('data-variant')).toBe('ghost');
+  });
+
+  it('should apply variant link', () => {
+    const fixture = TestBed.createComponent(ZenButton);
+    fixture.componentRef.setInput('variant', 'link');
+    fixture.detectChanges();
+    const button = fixture.nativeElement as HTMLButtonElement;
+    expect(button.getAttribute('data-variant')).toBe('link');
+  });
 });

package/schematics/ui/files/button/button.stories.ts

@@ -1,9 +1,12 @@
-import type { Meta, StoryObj } from '@storybook/angular';
+import { FavouriteIcon } from '@hugeicons/core-free-icons';
+import { argsToTemplate, Meta, moduleMetadata, StoryObj } from '@storybook/angular';
 
+import { ZenIcon } from '../icon';
 import { ZenButton } from './button';
 
 interface StoryParams {
-  content: string;
+  color: 'neutral' | 'primary' | 'success' | 'warning' | 'danger' | 'info';
+  variant: 'solid' | 'filled' | 'outline' | 'ghost' | 'link';
   disabled: boolean;
 }
 
@@ -13,18 +16,23 @@ export default {
   title: 'Ui/Button',
   component: ZenButton,
   args: {
-    content: 'Test',
     disabled: false,
+    size: 'md',
+    color: 'neutral',
+    variant: 'solid',
   },
   argTypes: {
-    content: {
-      control: 'text',
-      table: {
-        category: 'story parameters',
-        type: {
-          summary: 'ng-content',
-        },
-      },
+    size: {
+      control: 'select',
+      options: ['sm', 'md', 'lg'],
+    },
+    color: {
+      control: 'select',
+      options: ['neutral', 'primary', 'success', 'warning', 'danger', 'info'],
+    },
+    variant: {
+      control: 'select',
+      options: ['solid', 'filled', 'outline', 'ghost', 'link'],
     },
     disabled: {
       control: 'boolean',
@@ -36,12 +44,110 @@ export default {
       },
     },
   },
-  render: ({ content, ...args }) => ({
+  render: ({ ...args }) => ({
     props: args,
-    template: `<button zen-btn ${args.disabled ? 'disabled' : ''}>${content}</button>`,
+    template: `<button zen-btn ${argsToTemplate(args)}>Button</button>`,
   }),
 } satisfies Meta<Options>;
 
 type Story = StoryObj<Options>;
 
 export const Default: Story = {};
+
+export const IconButton: Story = {
+  decorators: [moduleMetadata({ imports: [ZenIcon] })],
+  render: args => ({
+    props: { FavouriteIcon, ...args },
+    template: `<button zen-btn variant="ghost" ${argsToTemplate(args, { exclude: ['variant'] })}>
+    <zen-icon [icon]="FavouriteIcon" [size]="16" [strokeWidth]="3" />
+  </button>`,
+  }),
+};
+
+export const AllVariants: Story = {
+  render: () => ({
+    template: `
+      <div style="display: flex; gap: 0.5rem">
+        <button zen-button variant="solid">Solid</button>
+        <button zen-button variant="filled">Filled</button>
+        <button zen-button variant="outline">Outline</button>
+        <button zen-button variant="ghost">Ghost</button>
+        <button zen-button variant="link">Link</button>
+      </div>
+    `,
+  }),
+};
+
+export const AllSizes: Story = {
+  render: () => ({
+    template: `
+      <div style="display: flex; align-items: center; gap: 0.5rem">
+        <button zen-button size="sm">Small</button>
+        <button zen-button size="md">Medium</button>
+        <button zen-button size="lg">Large</button>
+      </div>
+    `,
+  }),
+};
+
+export const AllColorVariants: Story = {
+  render: () => ({
+    template: `
+      <div style="display: flex; flex-direction: column; gap: 1rem;">
+        <!-- Default (No color attribute) -->
+        <div style="display: flex; gap: 0.5rem;">
+          <button zen-button variant="solid">Solid</button>
+          <button zen-button variant="filled">Filled</button>
+          <button zen-button variant="outline">Outline</button>
+          <button zen-button variant="ghost">Ghost</button>
+          <button zen-button variant="link">Link</button>
+        </div>
+
+        <!-- Primary -->
+        <div style="display: flex; gap: 0.5rem;">
+          <button zen-button color="primary" variant="solid">Solid</button>
+          <button zen-button color="primary" variant="filled">Filled</button>
+          <button zen-button color="primary" variant="outline">Outline</button>
+          <button zen-button color="primary" variant="ghost">Ghost</button>
+          <button zen-button color="primary" variant="link">Link</button>
+        </div>
+
+        <!-- Success -->
+        <div style="display: flex; gap: 0.5rem;">
+          <button zen-button color="success" variant="solid">Solid</button>
+          <button zen-button color="success" variant="filled">Filled</button>
+          <button zen-button color="success" variant="outline">Outline</button>
+          <button zen-button color="success" variant="ghost">Ghost</button>
+          <button zen-button color="success" variant="link">Link</button>
+        </div>
+
+        <!-- Warning -->
+        <div style="display: flex; gap: 0.5rem;">
+          <button zen-button color="warning" variant="solid">Solid</button>
+          <button zen-button color="warning" variant="filled">Filled</button>
+          <button zen-button color="warning" variant="outline">Outline</button>
+          <button zen-button color="warning" variant="ghost">Ghost</button>
+          <button zen-button color="warning" variant="link">Link</button>
+        </div>
+
+        <!-- Danger -->
+        <div style="display: flex; gap: 0.5rem;">
+          <button zen-button color="danger" variant="solid">Solid</button>
+          <button zen-button color="danger" variant="filled">Filled</button>
+          <button zen-button color="danger" variant="outline">Outline</button>
+          <button zen-button color="danger" variant="ghost">Ghost</button>
+          <button zen-button color="danger" variant="link">Link</button>
+        </div>
+
+        <!-- Info -->
+        <div style="display: flex; gap: 0.5rem;">
+          <button zen-button color="info" variant="solid">Solid</button>
+          <button zen-button color="info" variant="filled">Filled</button>
+          <button zen-button color="info" variant="outline">Outline</button>
+          <button zen-button color="info" variant="ghost">Ghost</button>
+          <button zen-button color="info" variant="link">Link</button>
+        </div>
+      </div>
+    `,
+  }),
+};

package/schematics/ui/files/button/button.ts

@@ -1,13 +1,15 @@
-import { ChangeDetectionStrategy, Component } from '@angular/core';
+import { ChangeDetectionStrategy, Component, input } from '@angular/core';
 
 /**
  * ZenButton is a reusable button component designed to provide
  * a consistent and customizable button style across the application.
  * It can be used with both `<button>` and `<a>` HTML elements by applying
- * the `zen-button` attribute.
+ * the `zen-button` or `zen-btn` attribute.
  *
  * @example
+ * <button zen-button> ... </button>
  * <button zen-btn> ... </button>
+ * <a zen-button href="..."> ... </a>
  *
  * ### CSS Custom Properties
  *
@@ -15,11 +17,14 @@ import { ChangeDetectionStrategy, Component } from '@angular/core';
  *
  * ```css
  * :root {
- *   --zen-button-bg-color-hover: lightgrey;
- *   --zen-button-bg-color: grey;
- *   --zen-button-color: white;
- *   --zen-button-padding: 0.5rem 2rem;
+ *   --zen-button-radius: 0.625rem;
  *   --zen-button-shadow: 0 2px 4px hsl(0deg 0% 0% / 10%);
+ *   --zen-button-neutral: hsl(30deg 5% 10%);
+ *   --zen-button-primary: hsl(95deg 15% 50%);
+ *   --zen-button-success: hsl(105deg 20% 35%);
+ *   --zen-button-warning: hsl(40deg 45% 60%);
+ *   --zen-button-danger: hsl(5deg 50% 45%);
+ *   --zen-button-info: hsl(205deg 30% 40%);
  * }
  * ```
  *
@@ -35,5 +40,15 @@ import { ChangeDetectionStrategy, Component } from '@angular/core';
   `,
   styleUrl: './button.scss',
   changeDetection: ChangeDetectionStrategy.OnPush,
+  host: {
+    '[attr.type]': '"button"',
+    '[attr.data-size]': 'size()',
+    '[attr.data-variant]': 'variant()',
+    '[attr.data-color]': 'color()',
+  },
 })
-export class ZenButton {}
+export class ZenButton {
+  readonly size = input<'sm' | 'md' | 'lg'>('md');
+  readonly color = input<'neutral' | 'primary' | 'success' | 'warning' | 'danger' | 'info'>('neutral');
+  readonly variant = input<'solid' | 'outline' | 'filled' | 'ghost' | 'link'>('solid');
+}

package/schematics/ui/files/dialog/dialog.service.stories.ts

@@ -66,9 +66,9 @@ See [GitHub](https://github.com/kstepien3/ng-zen), [MDN Dialog Element](https://
 @Component({
   template: `
     <p>{{ message() }}</p>
-    <div style="display: flex; gap: 0.5rem; margin-top: 1rem;">
+    <div style="display: flex; gap: 0.5rem; margin-top: 1rem; justify-content: end">
+      <button (click)="cancel()" color="danger" variant="filled" zen-btn>Cancel</button>
       <button (click)="confirmClick.emit('confirmed!')" zen-btn>Confirm</button>
-      <button (click)="cancel()" zen-btn>Cancel</button>
     </div>
   `,
   standalone: true,

package/schematics/ui/files/dialog/dialog.stories.ts

@@ -56,7 +56,7 @@ export const Default: Story = {
 
       <dialog zen-dialog [(open)]="open" ${argsToTemplate(args)}>
         <p>This is the dialog content. You can put any content here.</p>
-        <button zen-btn (click)="open.set(false)">Close</button>
+        <button zen-btn (click)="open.set(false)" variant="filled" color="danger">Close</button>
       </dialog>
     `,
     };

package/schematics/ui/files/popover/host/popover-host.scss

@@ -1,5 +1,11 @@
 :host {
   --zen-popover-offset: 0.5rem;
+  --zen-popover-bg: white;
+  --zen-popover-border: 1px solid #ccc;
+  --zen-popover-border-radius: 8px;
+  --zen-popover-padding: 0.5rem;
+  --zen-popover-shadow: 0 4px 12px rgb(0 0 0 / 15%);
+  --zen-popover-max-width: 300px;
 }
 
 /* stylelint-disable-next-line no-duplicate-selectors -- separate variables and styles */
@@ -8,12 +14,12 @@
   inset: auto;
   margin: var(--zen-popover-offset);
   width: max-content;
-  max-width: 300px;
-  background: white;
-  border: 1px solid #ccc;
-  border-radius: 8px;
-  padding: 0.5rem;
-  box-shadow: 0 4px 12px rgb(0 0 0 / 15%);
+  max-width: var(--zen-popover-max-width);
+  background: var(--zen-popover-bg);
+  border: var(--zen-popover-border);
+  border-radius: var(--zen-popover-border-radius);
+  padding: var(--zen-popover-padding);
+  box-shadow: var(--zen-popover-shadow);
   overflow: visible;
 
   // Auto-reposition if the popover would overflow

package/schematics/ui/files/popover/index.ts

@@ -1 +1,2 @@
 export * from './popover';
+export * from './popover-positions.type';

package/schematics/ui/files/popover/popover.stories.ts

@@ -43,7 +43,7 @@ const meta = {
       },
     },
     id: { control: 'text', table: { defaultValue: { summary: 'zen-popover-*X*' } } },
-    content: { name: 'zenPopover', control: 'text' },
+    content: { name: 'zenPopover', control: 'text', table: { defaultValue: { summary: '' } } },
   },
   args: {
     placement: 'top',
@@ -64,3 +64,20 @@ export const Default: Story = {
     `,
   }),
 };
+
+export const WithTemplate: Story = {
+  render: ({ placement, content }) => ({
+    template: `
+      <ng-template #popoverContent>
+        <i>${content}</i>
+      </ng-template>
+      <button zen-btn [zenPopover]="popoverContent" [zenPopoverPlacement]="'${placement}'">
+        Template
+      </button>
+    `,
+  }),
+  args: {
+    id: 'zen-popover-template-story',
+    placement: 'top',
+  },
+};

package/schematics/ui/files/popover/popover.ts

@@ -14,6 +14,8 @@ import {
 import { ZenPopoverHost } from './host/popover-host';
 import { PopoverPlacement } from './popover-positions.type';
 
+type HostProperties = keyof ZenPopoverHost;
+
 /**
  * ZenPopover is a reusable popover directive built on the native Popover API.
  * It provides a consistent, themeable popover surface with CSS-based positioning,
@@ -21,25 +23,51 @@ import { PopoverPlacement } from './popover-positions.type';
  *
  * ### Limitations (arrow)
  * ZenPopover may use CSS fallback positioning (e.g. via `position-try-fallbacks`) to keep the
- * popover inside the viewport. Today CSS doesn’t provide a stable, cross-browser way to detect
- * which fallback placement was ultimately chosen, so an “arrow” implemented with `::before/::after`
- * can’t be reliably synchronized with the final placement without extra JavaScript.
+ * popover inside the viewport. Today CSS doesn't provide a stable, cross-browser way to detect
+ * which fallback placement was ultimately chosen, so an "arrow" implemented with `::before/::after`
+ * can't be reliably synchronized with the final placement without extra JavaScript.
  * A CSS-only solution becomes possible with Anchored Container Queries (e.g. `container-type: anchored`
  * and `@container anchored(fallback: ...)`) where supported.
  *
- * @see https://developer.chrome.com/blog/anchored-container-queries
+ * @see [Detect fallback positions with anchored container queries](https://developer.chrome.com/blog/anchored-container-queries)
+ *
+ * @example
+ *
+ * ```html
+ * <!-- String content -->
+ * <button [zenPopover]="'Hello World'" [zenPopoverPlacement]="'bottom'">
+ *   Trigger
+ * </button>
+ *
+ * <!-- TemplateRef content -->
+ * <button [zenPopover]="popoverContent" zenPopoverPlacement="right">
+ *   Trigger
+ * </button>
+ * <ng-template #popoverContent>
+ *   <div>Custom content</div>
+ * </ng-template>
+ * ```
  *
  * ### CSS Custom Properties
- * You can customize the popover using CSS custom properties (see component styles/docs).
+ *
+ * You can customize the component using CSS custom properties:
+ * ```css
+ * :root {
+ *   --zen-popover-offset: 0.5rem;
+ *   --zen-popover-bg: white;
+ *   --zen-popover-border: 1px solid #ccc;
+ *   --zen-popover-border-radius: 8px;
+ *   --zen-popover-padding: 0.5rem;
+ *   --zen-popover-shadow: 0 4px 12px rgb(0 0 0 / 15%);
+ *   --zen-popover-max-width: 300px;
+ * }
+ * ```
  *
  * @author Konrad Stępień
  * @license {@link https://github.com/kstepien3/ng-zen/blob/master/LICENSE|BSD-2-Clause}
  * @see [GitHub](https://github.com/kstepien3/ng-zen)
  * @see [MDN Popover API](https://developer.mozilla.org/en-US/docs/Web/API/Popover_API)
  */
-
-type HostProperties = keyof ZenPopoverHost;
-
 @Directive({
   selector: '[zenPopover]',
   standalone: true,