@kouji-ui/core 0.0.4 → 0.1.1

package/src/primitives/overlay/builder.ts

@@ -0,0 +1,151 @@
+import {
+  ApplicationRef,
+  ComponentRef,
+  EnvironmentInjector,
+  Injectable,
+  Injector,
+  Type,
+  createComponent,
+  inject,
+} from '@angular/core';
+import { KjOverlayController, type KjOverlayStrategies } from './controller';
+import { KjOverlayWrapper } from './wrapper';
+import { KjBackdrop } from './backdrop';
+import { getOverlayContainer } from './container';
+import {
+  KJ_OVERLAY_MOUNT_STRATEGY,
+  KJ_OVERLAY_POSITION_STRATEGY,
+  KJ_OVERLAY_BACKDROP_STRATEGY,
+  KJ_OVERLAY_FOCUS_TRAP_STRATEGY,
+  KJ_OVERLAY_SCROLL_LOCK_STRATEGY,
+  KJ_OVERLAY_LIVE_ANNOUNCER_STRATEGY,
+  KJ_OVERLAY_TRIGGER_EVENT_STRATEGY,
+  KJ_OVERLAY_PANEL_ROLE,
+} from './tokens';
+import type { KjPanelRole } from './types';
+
+export interface KjOverlayBuilderConfig extends KjOverlayStrategies {
+  panelRole: KjPanelRole;
+  closeOnEsc?: boolean;
+  closeOnOutside?: boolean;
+}
+
+export interface KjAttachOptions<D = unknown> {
+  data?: D;
+  providers?: Array<{ provide: unknown; useValue?: unknown }>;
+}
+
+/**
+ * Per-overlay handle returned by {@link KjOverlayBuilder.create}. Owns the
+ * controller, the per-overlay element injector, and the wrapper component.
+ * Callers dispose the entire overlay (DOM, child views, strategy detach
+ * chain) by calling {@link destroy} — Angular's component destroy cascade
+ * does the work; no manual ref tracking needed.
+ *
+ * @doc-category Core/Overlay
+ * @doc
+ * @doc-name overlay-handle
+ * @doc-description Disposable handle for a single open overlay with controller, injector, and destroy access.
+ */
+export class KjOverlayHandle {
+  constructor(
+    readonly controller: KjOverlayController,
+    readonly injector: Injector,
+    readonly config: KjOverlayBuilderConfig,
+    private readonly wrapperRef: ComponentRef<KjOverlayWrapper>,
+  ) {}
+
+  get wrapper(): KjOverlayWrapper { return this.wrapperRef.instance; }
+
+  destroy(): void {
+    if (this.wrapperRef.hostView.destroyed) return;
+    const host = this.wrapperRef.location.nativeElement as HTMLElement;
+    this.wrapperRef.destroy();
+    // createComponent + manual appendChild → manual removal on destroy.
+    host.parentElement?.removeChild(host);
+  }
+}
+
+/**
+ * Service that constructs per-overlay controllers + wrapper components from
+ * a strategy bundle. Wires up the per-overlay element injector, appends the
+ * wrapper to the singleton overlay container, and returns a
+ * {@link KjOverlayHandle} for service-launched overlays (dialog, drawer,
+ * toast, etc.).
+ *
+ * @doc-category Core/Overlay
+ * @doc
+ * @doc-name overlay-builder
+ * @doc-is-main
+ * @doc-description Builds and opens a service-launched overlay (dialog, drawer, toast) and returns a disposable handle.
+ */
+@Injectable({ providedIn: 'root' })
+export class KjOverlayBuilder {
+  private readonly appRef = inject(ApplicationRef);
+  private readonly env    = inject(EnvironmentInjector);
+
+  /**
+   * Creates a per-overlay controller + wrapper component. The wrapper is
+   * appended to the singleton `.kj-overlay-container` and is the host for
+   * the backdrop and panel views. Strategies are attached eagerly so the
+   * controller is ready for `open()` immediately after this call returns.
+   */
+  create(config: KjOverlayBuilderConfig): KjOverlayHandle {
+    const injector = Injector.create({
+      providers: [
+        KjOverlayController,
+        { provide: KJ_OVERLAY_MOUNT_STRATEGY,            useValue: config.mount },
+        { provide: KJ_OVERLAY_POSITION_STRATEGY,         useValue: config.position },
+        { provide: KJ_OVERLAY_BACKDROP_STRATEGY,         useValue: config.backdrop ?? null },
+        { provide: KJ_OVERLAY_FOCUS_TRAP_STRATEGY,       useValue: config.focusTrap ?? null },
+        { provide: KJ_OVERLAY_SCROLL_LOCK_STRATEGY,      useValue: config.scrollLock ?? null },
+        { provide: KJ_OVERLAY_LIVE_ANNOUNCER_STRATEGY,   useValue: config.liveAnnouncer ?? null },
+        { provide: KJ_OVERLAY_TRIGGER_EVENT_STRATEGY,    useValue: config.trigger ?? null },
+        { provide: KJ_OVERLAY_PANEL_ROLE,                useValue: config.panelRole },
+      ],
+      parent: this.env,
+    });
+    const controller = injector.get(KjOverlayController);
+    controller.attachStrategies(config);
+
+    const wrapperRef = createComponent(KjOverlayWrapper, {
+      environmentInjector: this.env,
+      elementInjector: injector,
+    });
+    this.appRef.attachView(wrapperRef.hostView);
+    // Sync CD so viewChild() anchors resolve before attachComponent runs.
+    wrapperRef.changeDetectorRef.detectChanges();
+    getOverlayContainer()?.appendChild(wrapperRef.location.nativeElement);
+
+    return new KjOverlayHandle(controller, injector, config, wrapperRef);
+  }
+
+  /**
+   * Mounts the user's component into the wrapper's panel slot, plus the
+   * styled `<kj-backdrop>` into the backdrop slot when a backdrop strategy
+   * is configured. Both views are owned by the wrapper component so
+   * `handle.destroy()` tears them down in one cascade.
+   */
+  attachComponent<T>(
+    handle: KjOverlayHandle,
+    component: Type<T>,
+    opts: KjAttachOptions = {},
+  ): ComponentRef<T> {
+    const wrapper = handle.wrapper;
+
+    if (handle.config.backdrop) {
+      wrapper.backdropAnchor().createComponent(KjBackdrop, { injector: handle.injector });
+    }
+
+    const childInjector = Injector.create({
+      providers: opts.providers as never[] ?? [],
+      parent: handle.injector,
+    });
+    const ref = wrapper.panelAnchor().createComponent(component, { injector: childInjector });
+    // Pointer-events isolation: container is `pointer-events: none` so app
+    // content stays clickable; each panel re-enables.
+    (ref.location.nativeElement as HTMLElement).style.pointerEvents = 'auto';
+    handle.controller.bindPanel(ref.location.nativeElement);
+    return ref;
+  }
+}

package/src/primitives/overlay/container.ts

@@ -0,0 +1,42 @@
+/**
+ * Module-level lazy singleton root for every overlay (dialogs, drawers,
+ * popovers, tooltips, dropdowns, toasts). The first call appends a single
+ * `<div class="kj-overlay-container">` to `document.body`; subsequent calls
+ * return the same element. SSR-safe (returns `null` when `document` is
+ * unavailable).
+ *
+ * Per-overlay code MUST go through {@link getOverlayContainer} +
+ * {@link createOverlayWrapper} instead of reaching for `document.body`
+ * directly — a single positioned root owns z-stacking, pointer-events
+ * isolation, and cleanup ordering across the whole overlay system.
+ *
+ * @doc-category Core/Overlay
+ * @doc
+ * @doc-name overlay-container
+ * @doc-is-main
+ * @doc-description Lazily creates the shared body-level root element where every overlay mounts.
+ */
+let _root: HTMLElement | null = null;
+
+export function getOverlayContainer(): HTMLElement | null {
+  if (typeof document === 'undefined') return null;
+  if (_root && _root.isConnected) return _root;
+  _root = document.createElement('div');
+  _root.className = 'kj-overlay-container';
+  document.body.appendChild(_root);
+  return _root;
+}
+
+/**
+ * Creates a per-overlay wrapper inside the singleton container. The wrapper
+ * owns its overlay's backdrop + panel as siblings so DOM teardown is atomic
+ * and stacking among siblings follows insertion order.
+ */
+export function createOverlayWrapper(): HTMLElement | null {
+  const root = getOverlayContainer();
+  if (!root || typeof document === 'undefined') return null;
+  const wrapper = document.createElement('div');
+  wrapper.className = 'kj-overlay-wrapper';
+  root.appendChild(wrapper);
+  return wrapper;
+}

package/src/primitives/overlay/context.ts

@@ -0,0 +1,14 @@
+import type { Signal } from '@angular/core';
+import type { KjOverlayState, KjCloseReason } from './types';
+import type { KjOverlayStack } from './stack';
+
+/** Runtime context every strategy receives via `attach(ctx)`. */
+export interface KjOverlayContext {
+  readonly state: Signal<KjOverlayState>;
+  readonly isOpen: Signal<boolean>;
+  readonly triggerEl: Signal<HTMLElement | null>;
+  readonly panelEl: Signal<HTMLElement | null>;
+  readonly stack: KjOverlayStack;
+  readonly platform: { isBrowser: boolean };
+  requestClose(reason: KjCloseReason): void;
+}

package/src/primitives/overlay/controller.spec.ts

@@ -0,0 +1,86 @@
+import { TestBed } from '@angular/core/testing';
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { KjOverlayController } from './controller';
+import type { KjOverlayStrategies } from './controller';
+
+function makeStub() {
+  const calls: string[] = [];
+  const strat = (name: string) => ({
+    attach: vi.fn(() => calls.push(`${name}:attach`)),
+    onOpen: vi.fn(() => calls.push(`${name}:onOpen`)),
+    onClose: vi.fn(() => calls.push(`${name}:onClose`)),
+    detach: vi.fn(() => calls.push(`${name}:detach`)),
+  });
+  const mount = { ...strat('mount'), portalled: false, resolveContainer: () => document.body };
+  const position = { ...strat('position'), update: vi.fn() };
+  const trigger  = { ...strat('trigger'), ariaHasPopup: null, bindToggle: vi.fn() };
+  return { calls, strategies: { mount, position, trigger } as unknown as KjOverlayStrategies };
+}
+
+describe('KjOverlayController', () => {
+  let ctrl: KjOverlayController;
+  beforeEach(() => {
+    TestBed.configureTestingModule({ providers: [KjOverlayController] });
+    ctrl = TestBed.inject(KjOverlayController);
+  });
+
+  it('starts closed', () => {
+    expect(ctrl.state()).toBe('closed');
+    expect(ctrl.isOpen()).toBe(false);
+  });
+
+  it('attachStrategies calls attach in order: mount, position, trigger', () => {
+    const { calls, strategies } = makeStub();
+    ctrl.attachStrategies(strategies);
+    const attaches = calls.filter(c => c.endsWith(':attach'));
+    expect(attaches[0]).toBe('mount:attach');
+    expect(attaches[1]).toBe('position:attach');
+    expect(attaches[attaches.length - 1]).toBe('trigger:attach');
+  });
+
+  it('open() with no panel transitions to open synchronously via rAF', async () => {
+    const { strategies } = makeStub();
+    ctrl.attachStrategies(strategies);
+    ctrl.open();
+    expect(ctrl.state()).toBe('opening');
+    // No panel attached → runTransition uses rAF fallback
+    await new Promise(r => requestAnimationFrame(() => r(undefined)));
+    await new Promise(r => requestAnimationFrame(() => r(undefined)));
+    expect(['open', 'opening']).toContain(ctrl.state());
+  }, 5000);
+
+  it('open while open is no-op', () => {
+    const { strategies } = makeStub();
+    ctrl.attachStrategies(strategies);
+    ctrl.open();
+    const stateBefore = ctrl.state();
+    ctrl.open();
+    expect(ctrl.state()).toBe(stateBefore);
+  });
+
+  it('close() from open transitions through closing', async () => {
+    const { strategies } = makeStub();
+    ctrl.attachStrategies(strategies);
+    // Force state to 'open' by calling open() and waiting a tick
+    ctrl.open();
+    await new Promise(r => requestAnimationFrame(() => r(undefined)));
+    await new Promise(r => requestAnimationFrame(() => r(undefined)));
+    if (ctrl.state() === 'open') {
+      ctrl.close();
+      expect(ctrl.state()).toBe('closing');
+    } else {
+      // Open didn't complete in jsdom — at least assert no throw
+      expect(['opening', 'open', 'closed']).toContain(ctrl.state());
+    }
+  }, 5000);
+
+  it('dispose calls detach on each strategy in reverse order', () => {
+    const { calls, strategies } = makeStub();
+    ctrl.attachStrategies(strategies);
+    calls.length = 0;
+    ctrl.dispose();
+    const detaches = calls.filter(c => c.endsWith(':detach'));
+    expect(detaches[0]).toBe('trigger:detach');
+    expect(detaches[detaches.length - 1]).toBe('mount:detach');
+  });
+});

package/src/primitives/overlay/controller.ts

@@ -0,0 +1,190 @@
+import { Injectable, computed, inject, signal, PLATFORM_ID } from '@angular/core';
+import { isPlatformBrowser } from '@angular/common';
+import type { KjOverlayContext } from './context';
+import type {
+  KjMountStrategy, KjPositionStrategy, KjBackdropStrategy,
+  KjFocusTrapStrategy, KjScrollLockStrategy, KjLiveAnnouncerStrategy,
+  KjTriggerEventStrategy, KjStrategy,
+} from './tokens';
+import type { KjOverlayState, KjCloseReason } from './types';
+import { KjOverlayStack, type KjOverlayStackHandle } from './stack';
+import { KjId } from './id';
+
+export interface KjOverlayStrategies {
+  mount: KjMountStrategy;
+  position: KjPositionStrategy;
+  trigger?: KjTriggerEventStrategy | null;
+  backdrop?: KjBackdropStrategy | null;
+  focusTrap?: KjFocusTrapStrategy | null;
+  scrollLock?: KjScrollLockStrategy | null;
+  liveAnnouncer?: KjLiveAnnouncerStrategy | null;
+}
+
+/**
+ * Owns the overlay's open/closed state machine plus the rAF/transition
+ * orchestration. Strategies (mount/position/backdrop/focus-trap/scroll-lock/
+ * trigger-event) attach to it; the panel + trigger directives bind to it via DI.
+ *
+ * @doc-category Core/Overlay
+ * @doc
+ * @doc-name overlay-controller
+ * @doc-is-main
+ * @doc-description Owns one overlay's open/close state and keeps its panel, trigger, and backdrop in sync.
+ */
+@Injectable()
+export class KjOverlayController {
+  private readonly platformId = inject(PLATFORM_ID);
+  private readonly isBrowser  = isPlatformBrowser(this.platformId);
+  private readonly stack      = inject(KjOverlayStack);
+  private readonly idSvc      = inject(KjId);
+  readonly id = this.idSvc.mint('overlay');
+
+  private readonly _state     = signal<KjOverlayState>('closed');
+  private readonly _trigger   = signal<HTMLElement | null>(null);
+  private readonly _panel     = signal<HTMLElement | null>(null);
+  readonly state              = this._state.asReadonly();
+  readonly isOpen             = computed(() => this._state() === 'open' || this._state() === 'opening');
+  readonly triggerEl          = this._trigger.asReadonly();
+  readonly panelEl            = this._panel.asReadonly();
+
+  readonly context: KjOverlayContext = {
+    state: this.state,
+    isOpen: this.isOpen,
+    triggerEl: this.triggerEl,
+    panelEl: this.panelEl,
+    stack: this.stack,
+    platform: { isBrowser: this.isBrowser },
+    requestClose: (r) => this.close(r),
+  };
+
+  /**
+   * Public read-only access to the attached strategy bundle. Builder, panel
+   * directive, and tests all need to inspect strategies without reaching
+   * for a private field via casts.
+   */
+  strategies: KjOverlayStrategies | null = null;
+  private stackHandle: KjOverlayStackHandle | null = null;
+  private transitionDeadline = 0;
+  private rafId = 0;
+  private transitionListener: ((e: Event) => void) | null = null;
+
+  bindTrigger(el: HTMLElement | null) { this._trigger.set(el); }
+  bindPanel(el: HTMLElement | null)   { this._panel.set(el); }
+
+  attachStrategies(s: KjOverlayStrategies): void {
+    this.strategies = s;
+    const order: (KjStrategy | null | undefined)[] = [
+      s.mount, s.position, s.backdrop, s.scrollLock, s.focusTrap, s.liveAnnouncer, s.trigger,
+    ];
+    for (const strat of order) strat?.attach(this.context);
+  }
+
+  open(): void {
+    const cur = this._state();
+    if (cur === 'open' || cur === 'opening') return;
+    if (cur === 'closing') this.cancelTransition();
+    this._state.set('opening');
+    this.beginOpen();
+  }
+
+  close(reason?: KjCloseReason): void {
+    const cur = this._state();
+    if (cur === 'closed' || cur === 'closing') return;
+    if (cur === 'opening') this.cancelTransition();
+    this._state.set('closing');
+    this.beginClose(reason);
+  }
+
+  toggle(): void {
+    if (this._state() === 'closed') this.open();
+    else this.close('programmatic');
+  }
+
+  dispose(): void {
+    if (this._state() !== 'closed') this.close('programmatic');
+    if (!this.strategies) return;
+    const s = this.strategies;
+    const order: (KjStrategy | null | undefined)[] = [
+      s.trigger, s.liveAnnouncer, s.focusTrap, s.scrollLock, s.backdrop, s.position, s.mount,
+    ];
+    for (const strat of order) strat?.detach();
+    this.strategies = null;
+  }
+
+  private beginOpen(): void {
+    if (!this.strategies) return;
+    const s = this.strategies;
+    s.mount.onOpen?.();
+    s.position.onOpen?.();
+    s.position.update();
+    s.backdrop?.onOpen?.();
+    s.scrollLock?.onOpen?.();
+    this.stackHandle = this.stack.register(this.id, { onClose: () => this.close('esc') });
+    if (this._panel()) this.stack.markContentEl(this.id, this._panel());
+    this.runTransition('open', () => {
+      this._state.set('open');
+      s.focusTrap?.focusFirst();
+    });
+  }
+
+  private beginClose(_reason?: KjCloseReason): void {
+    if (!this.strategies) return;
+    const s = this.strategies;
+    this.runTransition('close', () => {
+      s.focusTrap?.restoreFocus();
+      this.stackHandle?.unregister();
+      this.stackHandle = null;
+      s.scrollLock?.onClose?.();
+      s.backdrop?.onClose?.();
+      // Hide the panel synchronously before strategy cleanup so the brief
+      // moment between position.onClose clearing inline styles and Angular
+      // CD applying [hidden] never paints the panel at its default flow
+      // position. The host binding re-affirms this value via CD.
+      const panel = this._panel();
+      if (panel) panel.setAttribute('hidden', '');
+      s.position.onClose?.();
+      s.mount.onClose?.();
+      this._state.set('closed');
+    });
+  }
+
+  private runTransition(_kind: 'open' | 'close', done: () => void): void {
+    if (!this.isBrowser) { done(); return; }
+    const panel = this._panel();
+    const reduce = typeof matchMedia === 'function' ? matchMedia('(prefers-reduced-motion: reduce)').matches : false;
+    const cs = panel ? getComputedStyle(panel) : null;
+    const transitionMs = cs ? parseFloat(cs.transitionDuration) * 1000 : 0;
+    const animationMs  = cs ? parseFloat(cs.animationDuration)  * 1000 : 0;
+    const longest = Math.max(transitionMs, animationMs);
+    if (reduce || longest === 0 || !panel) {
+      this.rafId = requestAnimationFrame(done);
+      return;
+    }
+    let fired = false;
+    const listener = (e: Event) => {
+      if (e.target !== panel) return;
+      if (fired) return; fired = true;
+      panel.removeEventListener('transitionend', listener);
+      panel.removeEventListener('animationend', listener);
+      done();
+    };
+    this.transitionListener = listener;
+    panel.addEventListener('transitionend', listener);
+    panel.addEventListener('animationend', listener);
+    // Safety: if event never fires within longest+50ms, force done.
+    this.transitionDeadline = window.setTimeout(() => {
+      if (!fired) { fired = true; panel.removeEventListener('transitionend', listener); panel.removeEventListener('animationend', listener); done(); }
+    }, longest + 50);
+  }
+
+  private cancelTransition(): void {
+    if (this.rafId) { cancelAnimationFrame(this.rafId); this.rafId = 0; }
+    if (this.transitionDeadline) { clearTimeout(this.transitionDeadline); this.transitionDeadline = 0; }
+    if (this.transitionListener && this._panel()) {
+      const p = this._panel()!;
+      p.removeEventListener('transitionend', this.transitionListener);
+      p.removeEventListener('animationend', this.transitionListener);
+      this.transitionListener = null;
+    }
+  }
+}

package/src/primitives/overlay/id.spec.ts

@@ -0,0 +1,24 @@
+import { TestBed } from '@angular/core/testing';
+import { describe, it, expect } from 'vitest';
+import { KjId } from './id';
+
+describe('KjId', () => {
+  it('mints unique ids with default prefix', () => {
+    const svc = TestBed.inject(KjId);
+    expect(svc.mint()).not.toBe(svc.mint());
+  });
+
+  it('honours custom prefix', () => {
+    const svc = TestBed.inject(KjId);
+    expect(svc.mint('panel')).toMatch(/^kj-panel-\d+$/);
+  });
+
+  it('produces deterministic sequence within an injector', () => {
+    const svc = TestBed.inject(KjId);
+    const a = svc.mint('x');
+    const b = svc.mint('x');
+    const aN = Number(a.split('-').at(-1));
+    const bN = Number(b.split('-').at(-1));
+    expect(bN).toBe(aN + 1);
+  });
+});

package/src/primitives/overlay/id.ts

@@ -0,0 +1,17 @@
+import { Injectable } from '@angular/core';
+
+/**
+ * Stable id minter. Used by overlay panels, form fields, and any other
+ * primitive that needs deterministic ids (including across SSR boundaries).
+ *
+ * Counter is per-application; pair an app-level provider override with a
+ * deterministic seed if you need cross-render stability beyond a single render.
+ */
+@Injectable({ providedIn: 'root' })
+export class KjId {
+  private _counter = 0;
+  mint(prefix = ''): string {
+    const id = ++this._counter;
+    return prefix ? `kj-${prefix}-${id}` : `kj-${id}`;
+  }
+}

package/src/primitives/overlay/index.ts

@@ -1 +1,18 @@
-export { KjOverlayService, KjOverlayRef } from './overlay';
+export * from './types';
+export * from './tokens';
+export * from './context';
+export { KjId } from './id';
+export { KjOverlayStack } from './stack';
+export type { KjOverlayRegistration, KjOverlayStackHandle } from './stack';
+export type { KjLivePoliteness as KjOverlayLivePoliteness } from './strategies/live-announcer/_announce';
+
+export { KjOverlayController } from './controller';
+export type { KjOverlayStrategies } from './controller';
+export { KjOverlayBuilder, KjOverlayHandle } from './builder';
+export type { KjOverlayBuilderConfig, KjAttachOptions } from './builder';
+export { KjOverlayWrapper } from './wrapper';
+export { KjOverlayTrigger } from './trigger';
+export { KjOverlayPanel } from './panel';
+export type { KjOverlayTriggerLike } from './panel';
+export { KjBackdrop } from './backdrop';
+export * from './strategies/index';

package/src/primitives/overlay/overlay.css

@@ -0,0 +1,42 @@
+/* ─────────────────────────────────────────────────────────────
+   @kouji-ui/core — overlay primitive base styles
+   --------------------------------------------------------------
+   Ships the structural CSS for the singleton overlay container
+   created by `getOverlayContainer()` and per-overlay wrappers
+   created by `createOverlayWrapper()`, plus the default visual
+   for `kj-backdrop` (the `solidBackdrop()` strategy's class).
+
+   The themed overlay-family components (popover, tooltip,
+   dropdown-menu, dialog, drawer, toast, confirm-popup) live in
+   `@kouji-ui/components` and re-export this file plus their own
+   stylesheets via `packages/components/src/overlay/overlay.css`.
+   Consumers register that single aggregator — no need to list
+   each overlay component CSS in `angular.json`.
+   ──────────────────────────────────────────────────────────── */
+
+@layer kj.component {
+  .kj-overlay-container {
+    position: fixed;
+    inset: 0;
+    z-index: var(--kj-overlay-z-index, 1000);
+    pointer-events: none;
+  }
+
+  .kj-overlay-wrapper {
+    position: absolute;
+    inset: 0;
+    pointer-events: none;
+  }
+
+  .kj-overlay-wrapper > * {
+    pointer-events: auto;
+  }
+
+  .kj-backdrop,
+  .kj-overlay-backdrop {
+    position: absolute;
+    inset: 0;
+    background: var(--kj-backdrop-bg, rgb(0 0 0 / 0.5));
+    pointer-events: auto;
+  }
+}

package/src/primitives/overlay/panel.spec.ts

@@ -0,0 +1,52 @@
+import { Component, inject, ChangeDetectionStrategy } from '@angular/core';
+import { render } from '@testing-library/angular';
+import { describe, it, expect } from 'vitest';
+import { KjOverlayPanel } from './panel';
+import { KjOverlayController } from './controller';
+import {
+  KJ_OVERLAY_MOUNT_STRATEGY,
+  KJ_OVERLAY_POSITION_STRATEGY,
+  KJ_OVERLAY_TRIGGER_EVENT_STRATEGY,
+  KJ_OVERLAY_PANEL_ROLE,
+} from './tokens';
+import { bodyPortal } from './strategies/mount/body-portal';
+import { viewportCentered } from './strategies/position/viewport-centered';
+import { programmatic } from './strategies/trigger-event/programmatic';
+
+@Component({
+  selector: 'kj-panel-host',
+  standalone: true,
+  hostDirectives: [KjOverlayPanel],
+  providers: [
+    KjOverlayController,
+    { provide: KJ_OVERLAY_MOUNT_STRATEGY, useFactory: () => bodyPortal() },
+    { provide: KJ_OVERLAY_POSITION_STRATEGY, useFactory: () => viewportCentered() },
+    { provide: KJ_OVERLAY_TRIGGER_EVENT_STRATEGY, useFactory: () => programmatic() },
+    { provide: KJ_OVERLAY_PANEL_ROLE, useValue: 'dialog' as const },
+  ],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: '',
+})
+class PanelHost {
+  readonly _ = inject(KjOverlayPanel);
+}
+
+describe('KjOverlayPanel', () => {
+  it('host emits role + data-state="closed" + hidden initially', async () => {
+    const { fixture } = await render(PanelHost);
+    const el = fixture.nativeElement as HTMLElement;
+    expect(el.getAttribute('role')).toBe('dialog');
+    expect(el.getAttribute('data-state')).toBe('closed');
+    expect(el.hasAttribute('hidden')).toBe(true);
+  });
+
+  it('host has an id (minted via KjId)', async () => {
+    const { fixture } = await render(PanelHost);
+    const el = fixture.nativeElement as HTMLElement;
+    expect(el.id).toMatch(/^kj-panel-\d+$/);
+  });
+
+  it('exports as kjOverlayPanel', () => {
+    expect(KjOverlayPanel).toBeTruthy();
+  });
+});