@kouji-ui/core 0.0.3 → 0.1.1

package/src/toast/toast.ts

@@ -1,8 +1,9 @@
 import {
-  DestroyRef, Directive, ElementRef, TemplateRef,
-  afterNextRender, computed, inject, input, signal,
+  ChangeDetectionStrategy, Component, DestroyRef, Directive, ElementRef, TemplateRef, ViewEncapsulation,
+  afterNextRender, booleanAttribute, computed, inject, input, signal,
 } from '@angular/core';
-import { KjToastContext, KjToastService, KjToastTemplateContext, KjToastVariant } from './toast.service';
+import { KjOverlayPanel } from '../primitives/overlay/panel';
+import { KjToastService, KjToastTemplateContext, KjToastVariant } from './toast.service';
 import { KJ_TOAST_STRATEGY } from './toast.strategy';
 import { KjToastPositionX, KjToastPositionY } from './toast.types';
 
@@ -38,7 +39,7 @@ export type { KjToastPositionX, KjToastPositionY } from './toast.types';
  *   </div>
  * </ng-template>
  * ```
- * @category Core/Overlays
+ * @doc-category Core/Overlay
  */
 @Directive({
   selector: '[kjToast]',
@@ -48,6 +49,7 @@ export type { KjToastPositionX, KjToastPositionY } from './toast.types';
     '[attr.aria-atomic]': '"true"',
     '[attr.data-variant]': 'kjToastVariant()',
     '[attr.data-front]': 'isFront()',
+    '[attr.data-toast-id]': 'kjToastId()',
     '[style.--kj-toast-index]': 'index()',
     '[style.--kj-toast-before]': 'before()',
     '[style.--kj-toast-after]': 'after()',
@@ -112,9 +114,12 @@ export class KjToast {
       const measure = () => this._height.set(Math.round(node.getBoundingClientRect().height));
       measure();
       // Use border-box geometry via getBoundingClientRect — contentRect strips padding.
-      const ro = new ResizeObserver(measure);
-      ro.observe(node);
-      this.destroyRef.onDestroy(() => ro.disconnect());
+      // Guard ResizeObserver for SSR / older test environments.
+      if (typeof ResizeObserver !== 'undefined') {
+        const ro = new ResizeObserver(measure);
+        ro.observe(node);
+        this.destroyRef.onDestroy(() => ro.disconnect());
+      }
     });
   }
 }
@@ -159,7 +164,7 @@ export interface KjToastRenderable<TData = unknown> {
  *   }
  * </ol>
  * ```
- * @category Core/Overlays
+ * @doc-category Core/Overlay
  */
 @Directive({
   selector: '[kjToastViewport]',
@@ -167,6 +172,7 @@ export interface KjToastRenderable<TData = unknown> {
   exportAs: 'kjToastViewport',
   host: {
     'role': 'region',
+    'tabindex': '-1',
     '[attr.aria-live]': '"polite"',
     '[attr.aria-atomic]': '"false"',
     '[attr.aria-relevant]': '"additions removals"',
@@ -177,10 +183,10 @@ export interface KjToastRenderable<TData = unknown> {
     '[style.--kj-toast-z-index]': 'kjToastBaseZIndex()',
     '[style.--kj-toasts-count]': 'renderable().length',
     '[style.--kj-toast-front-height]': 'frontHeightPx()',
-    '(mouseenter)': 'onHover(true)',
-    '(mouseleave)': 'onHover(false)',
-    '(focusin)':    'onHover(true)',
-    '(focusout)':   'onHover(false)',
+    '(mouseenter)': 'onPointerEnter()',
+    '(mouseleave)': 'onPointerLeave()',
+    '(focusin)':    'onFocusIn($event)',
+    '(focusout)':   'onFocusOut($event)',
   },
 })
 export class KjToastViewport {
@@ -214,7 +220,24 @@ export class KjToastViewport {
    */
   readonly kjToastExpand = input<boolean | undefined>(undefined);
 
+  /**
+   * When `true` (default), hover/focus on the viewport pauses every in-flight
+   * auto-dismiss timer via `KjToastService.pause('hover'|'focus')`. Required
+   * for WCAG 2.2.1 (AAA) and 1.4.13. Distinct from visual stacking expansion
+   * (`kjToastExpand` / `strategy.expandOnHover`). Defaults from the active
+   * `KjToastStrategy.pauseOnHover`.
+   */
+  readonly kjToastPauseOnHover = input<boolean, unknown>(this.strategy.pauseOnHover, {
+    transform: booleanAttribute,
+  });
+
   private readonly _hovered = signal(false);
+  /** Tracks pointer-driven pause state so resume() runs exactly once per enter/leave pair. */
+  private pointerPauseHeld = false;
+  /** Tracks focus-driven pause state — independent ref so blur after re-enter doesn't double-resume. */
+  private focusPauseHeld = false;
+  /** Element to restore focus to when F6/Escape leaves the viewport. */
+  private previouslyFocused: HTMLElement | null = null;
 
   /** Resolved expand state — explicit input wins; otherwise falls back to hover when the strategy enables it. */
   readonly expanded = computed(() => {
@@ -223,8 +246,72 @@ export class KjToastViewport {
     return this.strategy.expandOnHover && this._hovered();
   });
 
-  protected onHover(state: boolean): void {
-    if (this.strategy.expandOnHover) this._hovered.set(state);
+  protected onPointerEnter(): void {
+    if (this.strategy.expandOnHover) this._hovered.set(true);
+    if (this.kjToastPauseOnHover() && !this.pointerPauseHeld) {
+      this.pointerPauseHeld = true;
+      this.svc.pause('hover');
+    }
+  }
+
+  protected onPointerLeave(): void {
+    if (this.strategy.expandOnHover) this._hovered.set(false);
+    if (this.pointerPauseHeld) {
+      this.pointerPauseHeld = false;
+      this.svc.resume('hover');
+    }
+  }
+
+  protected onFocusIn(event: FocusEvent): void {
+    if (this.strategy.expandOnHover) this._hovered.set(true);
+    // Capture the *external* focus owner so F6/Escape can restore. Only the
+    // first focusin counts — subsequent focus moves *within* the viewport
+    // (e.g. Tab between toasts) must not overwrite the restore target.
+    if (!this.focusPauseHeld) {
+      const previous = event.relatedTarget as HTMLElement | null;
+      const root = this.el.nativeElement;
+      // relatedTarget can be null on programmatic focus; fall back to
+      // document.activeElement if it's outside the viewport.
+      if (previous && !root.contains(previous)) {
+        this.previouslyFocused = previous;
+      }
+    }
+    if (this.kjToastPauseOnHover() && !this.focusPauseHeld) {
+      this.focusPauseHeld = true;
+      this.svc.pause('focus');
+    }
+  }
+
+  protected onFocusOut(event: FocusEvent): void {
+    const root = this.el.nativeElement;
+    const next = event.relatedTarget as HTMLElement | null;
+    // focusout fires for every internal focus move; only count *real* exits
+    // — the new focus target is null or outside the viewport root.
+    if (next && root.contains(next)) return;
+    if (this.strategy.expandOnHover) this._hovered.set(false);
+    if (this.focusPauseHeld) {
+      this.focusPauseHeld = false;
+      this.svc.resume('focus');
+    }
+  }
+
+  private focusFrontToast(): void {
+    const root = this.el.nativeElement as HTMLElement;
+    // Front-most toast is the *last* in DOM order (newest). Prefer the first
+    // focusable inside it; fall back to the toast element itself.
+    const fronts = root.querySelectorAll('[kjToast][data-front="true"]');
+    const front = fronts.length > 0 ? (fronts[fronts.length - 1] as HTMLElement) : null;
+    if (!front) return;
+    const focusable = front.querySelector(
+      'button:not([disabled]), [href], input:not([disabled]), [tabindex]:not([tabindex="-1"])',
+    ) as HTMLElement | null;
+    (focusable ?? front).focus();
+  }
+
+  private restorePreviousFocus(): void {
+    const target = this.previouslyFocused;
+    this.previouslyFocused = null;
+    if (target && typeof target.focus === 'function') target.focus();
   }
 
   /** Live list of queued toasts (uncapped). */
@@ -259,6 +346,49 @@ export class KjToastViewport {
   });
 
   constructor() {
+    // Register the F6 / Escape document-level listener eagerly — registering
+    // from `afterNextRender` was too late for tests that dispatch immediately
+    // after `service.show()`. Sonner uses the same pattern of a long-lived
+    // top-level listener. Handles both directions of F6 (outside → in,
+    // inside → out) and Escape (dismiss focused toast + restore focus) so
+    // there is exactly one source of truth — host listeners would race the
+    // document listener over the same event.
+    const doc = (typeof document !== 'undefined' ? document : null);
+    if (doc) {
+      const onDocKeydown = (event: KeyboardEvent) => {
+        if (event.key !== 'F6' && event.key !== 'Escape') return;
+        if (this.svc.toasts().length === 0) return;
+        const root = this.el.nativeElement as HTMLElement;
+        const active = doc.activeElement as HTMLElement | null;
+        const inside = active != null && root.contains(active);
+        if (event.key === 'F6') {
+          if (inside) {
+            event.preventDefault();
+            this.restorePreviousFocus();
+            return;
+          }
+          event.preventDefault();
+          this.previouslyFocused = active;
+          this.focusFrontToast();
+          return;
+        }
+        // Escape: only act when focus is inside the viewport so we don't
+        // hijack the consumer's other Escape affordances.
+        if (event.key === 'Escape' && inside) {
+          event.preventDefault();
+          const target = event.target as HTMLElement | null;
+          const toastEl = (target?.closest('[kjToast]')) as HTMLElement | null;
+          const id = toastEl?.getAttribute('data-toast-id')
+            ?? this.svc.toasts().at(-1)?.id
+            ?? null;
+          this.restorePreviousFocus();
+          if (id) this.svc.dismiss(id);
+        }
+      };
+      doc.addEventListener('keydown', onDocKeydown);
+      this.destroyRef.onDestroy(() => doc.removeEventListener('keydown', onDocKeydown));
+    }
+
     afterNextRender(() => {
       const root = this.el.nativeElement as HTMLElement;
       const measure = () => {
@@ -267,13 +397,20 @@ export class KjToastViewport {
         this._frontHeight.set(Math.round(front.getBoundingClientRect().height));
       };
       measure();
-      const ro = new ResizeObserver(measure);
-      // Observe the viewport — children added/resized trigger remeasure.
-      ro.observe(root);
-      // MutationObserver picks up new children (data-front="true" added on a new toast).
-      const mo = new MutationObserver(measure);
-      mo.observe(root, { childList: true, subtree: true, attributes: true, attributeFilter: ['data-front'] });
-      this.destroyRef.onDestroy(() => { ro.disconnect(); mo.disconnect(); });
+      // Guard ResizeObserver / MutationObserver for SSR + older test envs.
+      let ro: ResizeObserver | undefined;
+      let mo: MutationObserver | undefined;
+      if (typeof ResizeObserver !== 'undefined') {
+        ro = new ResizeObserver(measure);
+        // Observe the viewport — children added/resized trigger remeasure.
+        ro.observe(root);
+      }
+      if (typeof MutationObserver !== 'undefined') {
+        // MutationObserver picks up new children (data-front="true" added on a new toast).
+        mo = new MutationObserver(measure);
+        mo.observe(root, { childList: true, subtree: true, attributes: true, attributeFilter: ['data-front'] });
+      }
+      this.destroyRef.onDestroy(() => { ro?.disconnect(); mo?.disconnect(); });
     });
   }
 }
@@ -287,12 +424,13 @@ export class KjToastViewport {
  * ```html
  * <button [kjToastClose]="toast.id" aria-label="Dismiss">×</button>
  * ```
- * @category Core/Overlays
+ * @doc-category Core/Overlay
  */
 @Directive({
   selector: '[kjToastClose]',
   standalone: true,
   host: {
+    'class': 'kj-toast-close',
     '(click)': 'dismiss()',
   },
 })
@@ -305,3 +443,21 @@ export class KjToastClose {
     this.svc.dismiss(this.kjToastClose());
   }
 }
+
+/**
+ * Service-launched toast panel. Composes `KjOverlayPanel` as a host directive
+ * so the overlay primitives wire role/state/aria management. The role is
+ * decided by the service via `KJ_OVERLAY_PANEL_ROLE` (`status` or `alert`).
+ *
+ * @doc-category Core/Overlay
+ */
+@Component({
+  selector: 'kj-toast',
+  standalone: true,
+  hostDirectives: [{ directive: KjOverlayPanel }],
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  encapsulation: ViewEncapsulation.None,
+  host: { class: 'kj-toast' },
+  template: `<ng-content />`,
+})
+export class KjToastPanel {}

package/src/toggle/toggle.ts

@@ -1,14 +1,22 @@
-import { Directive, inject, model } from '@angular/core';
+import { Directive, inject, model } from '@angular/core';
 import { KjDisabled, KjFocusRing, KjFormControl } from '../primitives';
 
 /**
  * Adds toggle (press) behavior with Angular forms integration.
  *
+ * Reflects `aria-pressed` and `data-pressed` and integrates with reactive and
+ * template-driven forms so the pressed state participates as a regular form
+ * value alongside other inputs.
+ *
  * @example
  * ```html
  * <button kjToggle [(kjPressed)]="isBold" aria-label="Bold">B</button>
  * ```
- * @category Core/Inputs
+ * @doc-category Core/Inputs
+ * @doc
+ * @doc-name toggle
+ * @doc-description Adds press/unpress toggle behaviour to any focusable element with Angular forms support.
+ * @doc-is-main
  */
 @Directive({
   selector: '[kjToggle]',

package/src/tooltip/_examples/index.ts

@@ -0,0 +1,6 @@
+// AUTO-GENERATED by scripts/migrate-examples.mjs
+// One barrel per component folder — used by the docs app as a lazy chunk.
+export { TooltipBasicExample } from './tooltip.example';
+export { TooltipFinanceExample } from './tooltip.finance.example';
+export { TooltipPlacementsExample } from './tooltip.placements.example';
+export { TooltipRetroExample } from './tooltip.retro.example';

package/src/tooltip/_examples/tooltip.example.ts

@@ -0,0 +1,82 @@
+import { Component, ChangeDetectionStrategy } from '@angular/core';
+import { KjTooltipTrigger, KjTooltipContent } from '../tooltip';
+import { KjButton } from '../../button/button';
+
+@Component({
+  selector: 'kj-example-tooltip-basic',
+  standalone: true,
+  imports: [KjTooltipTrigger, KjTooltipContent, KjButton],
+  styleUrls: ['../../styles/docs-themes.css'],
+  styles: [
+    `
+      :host {
+        display: flex;
+        align-items: center;
+        justify-content: center;
+        padding: 5rem 3rem;
+        background: var(--kj-bg);
+        font-family: var(--kj-font);
+        min-height: 180px;
+      }
+      .row {
+        display: flex;
+        gap: 1.5rem;
+        flex-wrap: wrap;
+        align-items: center;
+        justify-content: center;
+      }
+      button[kjButton] {
+        padding: 0.5rem 1.25rem;
+        font-family: var(--kj-font);
+        font-size: 0.875rem;
+        border: var(--kj-btn-border);
+        cursor: pointer;
+        transition: var(--kj-transition);
+      }
+      [data-variant='default'] {
+        background: var(--kj-accent);
+        color: var(--kj-accent-on);
+      }
+      [data-variant='link'] {
+        background: transparent;
+        color: var(--kj-accent);
+        border: none;
+        padding: 0.5rem 0.5rem;
+        text-decoration: none;
+        text-underline-offset: 4px;
+      }
+      [data-variant='link']:hover {
+        text-decoration: underline;
+      }
+      [data-variant='ghost'] {
+        background: transparent;
+        color: var(--kj-btn-ghost-color);
+      }
+      :global(kj-tooltip-content) {
+        background: var(--kj-accent);
+        color: var(--kj-accent-on);
+        padding: 0.25rem 0.625rem;
+        font-size: 0.75rem;
+        white-space: nowrap;
+        pointer-events: none;
+        transition: var(--kj-transition);
+      }
+    `,
+  ],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: `
+    <div class="row">
+      <button kjButton [kjVariant]="'default'" kjTooltipTrigger #t1="kjTooltipTrigger">
+        Default
+      </button>
+      <kj-tooltip-content [kjFor]="t1">Copy to clipboard</kj-tooltip-content>
+
+      <button kjButton [kjVariant]="'link'" kjTooltipTrigger #t2="kjTooltipTrigger">Link</button>
+      <kj-tooltip-content [kjFor]="t2" [kjSide]="'bottom'">Opens below</kj-tooltip-content>
+
+      <button kjButton [kjVariant]="'ghost'" kjTooltipTrigger #t3="kjTooltipTrigger">Ghost</button>
+      <kj-tooltip-content [kjFor]="t3" [kjSide]="'right'">Opens right</kj-tooltip-content>
+    </div>
+  `,
+})
+export class TooltipBasicExample {}

package/src/tooltip/_examples/tooltip.finance.example.ts

@@ -0,0 +1,97 @@
+import { Component, ChangeDetectionStrategy } from '@angular/core';
+import { KjTooltipTrigger, KjTooltipContent } from '../tooltip';
+import { KjButton } from '../../button/button';
+
+@Component({
+  selector: 'kj-example-tooltip-finance',
+  standalone: true,
+  imports: [KjTooltipTrigger, KjTooltipContent, KjButton],
+  styleUrls: ['../../styles/docs-themes.css'],
+  /* Closed-state `display:none` for portaled `kj-tooltip-content` comes from
+   * `packages/components/src/tooltip/tooltip.css` (docs app global styles) — not repeated here. */
+  styles: [
+    `
+      :host {
+        display: flex;
+        align-items: center;
+        justify-content: center;
+        padding: 5rem 3rem;
+        background: var(--kj-bg);
+        font-family: var(--kj-font);
+        min-height: 180px;
+        color: var(--kj-text);
+      }
+      .row {
+        display: flex;
+        gap: 1.5rem;
+        flex-wrap: wrap;
+        align-items: center;
+        justify-content: center;
+      }
+      button[kjButton] {
+        padding: 4px 15px;
+        font-family: var(--kj-font);
+        font-size: 14px;
+        font-weight: 400;
+        border: 1px solid transparent;
+        border-radius: 6px;
+        cursor: pointer;
+        transition: var(--kj-transition);
+        line-height: 1.5;
+      }
+      button[kjButton][data-variant='default'] {
+        background: var(--kj-accent);
+        color: var(--kj-accent-on);
+        border-color: var(--kj-accent);
+      }
+      button[kjButton][data-variant='default']:hover {
+        background: #4096ff;
+        border-color: #4096ff;
+      }
+      button[kjButton][data-variant='link'] {
+        background: transparent;
+        color: var(--kj-accent);
+        border-color: transparent;
+      }
+      button[kjButton][data-variant='link']:hover {
+        color: #4096ff;
+      }
+      button[kjButton][data-variant='ghost'] {
+        background: transparent;
+        color: var(--kj-text);
+        border: 1px solid var(--kj-text);
+      }
+      button[kjButton][data-variant='ghost']:hover {
+        color: var(--kj-accent);
+        border-color: var(--kj-accent);
+      }
+      :global(kj-tooltip-content) {
+        background: #1f2937;
+        color: #f9fafb;
+        padding: 0.3rem 0.625rem;
+        font-size: 0.75rem;
+        border-radius: var(--kj-radius-sm);
+        white-space: nowrap;
+        pointer-events: none;
+        box-shadow: var(--kj-shadow-sm);
+      }
+    `,
+  ],
+  host: { class: 'kj-theme-finance' },
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: `
+    <div class="row">
+      <button kjButton [kjVariant]="'default'" kjTooltipTrigger #t1="kjTooltipTrigger">
+        Default
+      </button>
+      <kj-tooltip-content [kjFor]="t1">Copy to clipboard</kj-tooltip-content>
+
+      <button kjButton [kjVariant]="'link'" kjTooltipTrigger #t2="kjTooltipTrigger">Link</button>
+      <kj-tooltip-content [kjFor]="t2" [kjSide]="'bottom'">Opens below</kj-tooltip-content>
+
+      <button kjButton [kjVariant]="'ghost'" kjTooltipTrigger #t3="kjTooltipTrigger">Ghost</button>
+      <kj-tooltip-content [kjFor]="t3" [kjSide]="'right'">Opens right</kj-tooltip-content>
+    </div>
+  `,
+})
+export class TooltipFinanceExample {}

package/src/tooltip/_examples/tooltip.placements.example.ts

@@ -0,0 +1,83 @@
+import { Component, ChangeDetectionStrategy } from '@angular/core';
+import { KjTooltipTrigger, KjTooltipContent } from '../tooltip';
+import { KjButton } from '../../button/button';
+
+@Component({
+  selector: 'kj-example-tooltip-placements',
+  standalone: true,
+  imports: [KjTooltipTrigger, KjTooltipContent, KjButton],
+  styleUrls: ['../../styles/docs-themes.css'],
+  styles: [
+    `
+      :host {
+        display: flex;
+        align-items: center;
+        justify-content: center;
+        padding: 5rem 4rem;
+        background: var(--kj-bg);
+        font-family: var(--kj-font);
+        min-height: 220px;
+      }
+      .grid {
+        display: grid;
+        grid-template-columns: 1fr 1fr 1fr;
+        grid-template-rows: auto auto auto;
+        gap: 0.75rem;
+        place-items: center;
+      }
+      button[kjButton] {
+        padding: 0.5rem 1.25rem;
+        font-family: var(--kj-font);
+        font-size: 0.875rem;
+        border: var(--kj-btn-border);
+        cursor: pointer;
+        transition: var(--kj-transition);
+      }
+      [data-variant='default'] {
+        background: var(--kj-accent);
+        color: var(--kj-accent-on);
+      }
+      .empty {
+        width: 80px;
+      }
+      :global(kj-tooltip-content) {
+        background: var(--kj-accent);
+        color: var(--kj-accent-on);
+        padding: 0.25rem 0.625rem;
+        font-size: 0.75rem;
+        white-space: nowrap;
+        pointer-events: none;
+        transition: var(--kj-transition);
+      }
+    `,
+  ],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: `
+    <div class="grid">
+      <div class="empty"></div>
+      <button kjButton [kjVariant]="'default'" kjTooltipTrigger #tTop="kjTooltipTrigger">
+        Top
+      </button>
+      <kj-tooltip-content [kjFor]="tTop" [kjSide]="'top'">Top tooltip</kj-tooltip-content>
+      <div class="empty"></div>
+
+      <button kjButton [kjVariant]="'default'" kjTooltipTrigger #tLeft="kjTooltipTrigger">
+        Left
+      </button>
+      <kj-tooltip-content [kjFor]="tLeft" [kjSide]="'left'">Left tooltip</kj-tooltip-content>
+      <div class="empty"></div>
+      <button kjButton [kjVariant]="'default'" kjTooltipTrigger #tRight="kjTooltipTrigger">
+        Right
+      </button>
+      <kj-tooltip-content [kjFor]="tRight" [kjSide]="'right'">Right tooltip</kj-tooltip-content>
+
+      <div class="empty"></div>
+      <button kjButton [kjVariant]="'default'" kjTooltipTrigger #tBot="kjTooltipTrigger">
+        Bottom
+      </button>
+      <kj-tooltip-content [kjFor]="tBot" [kjSide]="'bottom'">Bottom tooltip</kj-tooltip-content>
+      <div class="empty"></div>
+    </div>
+  `,
+})
+export class TooltipPlacementsExample {}