@kouji-ui/core 0.0.4 → 0.1.1

package/src/primitives/overlay/strategies/trigger-event/on-focus-or-input.spec.ts

@@ -0,0 +1,35 @@
+import { signal } from '@angular/core';
+import { describe, it, expect, vi } from 'vitest';
+import { onFocusOrInput } from './on-focus-or-input';
+import type { KjOverlayContext } from '../../context';
+
+describe('onFocusOrInput', () => {
+  it('opens on focusin and on input event', () => {
+    const trigger = document.createElement('input');
+    document.body.appendChild(trigger);
+    const isOpen = signal(false);
+    const ctx: KjOverlayContext = {
+      state: signal('closed'), isOpen,
+      triggerEl: signal(trigger), panelEl: signal(null),
+      stack: {} as never, platform: { isBrowser: true },
+      requestClose: () => {},
+    };
+    const toggle = vi.fn(() => isOpen.set(!isOpen()));
+    const s = onFocusOrInput();
+    s.attach(ctx);
+    s.bindToggle(toggle);
+
+    trigger.dispatchEvent(new Event('focusin'));
+    expect(toggle).toHaveBeenCalledTimes(1);
+
+    isOpen.set(false);
+    trigger.dispatchEvent(new Event('input'));
+    expect(toggle).toHaveBeenCalledTimes(2);
+
+    s.detach(); trigger.remove();
+  });
+
+  it('ariaHasPopup is "listbox"', () => {
+    expect(onFocusOrInput().ariaHasPopup).toBe('listbox');
+  });
+});

package/src/primitives/overlay/strategies/trigger-event/on-focus-or-input.ts

@@ -0,0 +1,34 @@
+import type { KjOverlayContext } from '../../context';
+import type { KjTriggerEventStrategy } from '../../tokens';
+
+export function onFocusOrInput(): KjTriggerEventStrategy {
+  let ctx: KjOverlayContext | null = null;
+  let toggle: (() => void) | null = null;
+  let onFocusIn: ((e: Event) => void) | null = null;
+  let onInput: ((e: Event) => void) | null = null;
+
+  const wire = () => {
+    if (!ctx?.platform.isBrowser) return;
+    const trigger = ctx.triggerEl();
+    if (!trigger || onFocusIn) return;
+    onFocusIn = () => { if (!ctx?.isOpen()) toggle?.(); };
+    onInput = () => { if (!ctx?.isOpen()) toggle?.(); };
+    trigger.addEventListener('focusin', onFocusIn);
+    trigger.addEventListener('input', onInput);
+  };
+
+  return {
+    ariaHasPopup: 'listbox',
+    attach(c) { ctx = c; wire(); },
+    bindToggle(t) { toggle = t; wire(); },
+    onOpen() {}, onClose() {},
+    detach() {
+      const trigger = ctx?.triggerEl();
+      if (trigger) {
+        if (onFocusIn) trigger.removeEventListener('focusin', onFocusIn);
+        if (onInput) trigger.removeEventListener('input', onInput);
+      }
+      onFocusIn = onInput = null; toggle = null; ctx = null;
+    },
+  };
+}

package/src/primitives/overlay/strategies/trigger-event/on-focus.spec.ts

@@ -0,0 +1,64 @@
+import { signal } from '@angular/core';
+import { describe, it, expect, vi } from 'vitest';
+import { onFocus } from './on-focus';
+import type { KjOverlayContext } from '../../context';
+
+function makeCtx(trigger: HTMLElement, isOpenSig = signal(false), panel: HTMLElement | null = null): KjOverlayContext {
+  return {
+    state: signal('closed'), isOpen: isOpenSig,
+    triggerEl: signal(trigger), panelEl: signal(panel),
+    stack: {} as never, platform: { isBrowser: true },
+    requestClose: () => {},
+  };
+}
+
+describe('onFocus', () => {
+  it('focusin opens (when closed)', () => {
+    const trigger = document.createElement('button');
+    document.body.appendChild(trigger);
+    const isOpen = signal(false);
+    const ctx = makeCtx(trigger, isOpen);
+    const toggle = vi.fn(() => isOpen.set(!isOpen()));
+    const s = onFocus();
+    s.attach(ctx);
+    s.bindToggle(toggle);
+    trigger.dispatchEvent(new FocusEvent('focusin'));
+    expect(toggle).toHaveBeenCalledTimes(1);
+    s.detach();
+    trigger.remove();
+  });
+
+  it('focusout closes (open) when relatedTarget outside panel', () => {
+    const trigger = document.createElement('button');
+    const panel = document.createElement('div');
+    document.body.append(trigger, panel);
+    const isOpen = signal(true);
+    const ctx = makeCtx(trigger, isOpen, panel);
+    const toggle = vi.fn(() => isOpen.set(!isOpen()));
+    const s = onFocus();
+    s.attach(ctx);
+    s.bindToggle(toggle);
+    const out = new FocusEvent('focusout', { relatedTarget: document.body });
+    trigger.dispatchEvent(out);
+    expect(toggle).toHaveBeenCalledTimes(1);
+    s.detach(); trigger.remove(); panel.remove();
+  });
+
+  it('focusout to inside panel does NOT close', () => {
+    const trigger = document.createElement('button');
+    const panel = document.createElement('div');
+    const inner = document.createElement('button');
+    panel.appendChild(inner);
+    document.body.append(trigger, panel);
+    const isOpen = signal(true);
+    const ctx = makeCtx(trigger, isOpen, panel);
+    const toggle = vi.fn(() => isOpen.set(!isOpen()));
+    const s = onFocus();
+    s.attach(ctx);
+    s.bindToggle(toggle);
+    const out = new FocusEvent('focusout', { relatedTarget: inner });
+    trigger.dispatchEvent(out);
+    expect(toggle).not.toHaveBeenCalled();
+    s.detach(); trigger.remove(); panel.remove();
+  });
+});

package/src/primitives/overlay/strategies/trigger-event/on-focus.ts

@@ -0,0 +1,37 @@
+import type { KjOverlayContext } from '../../context';
+import type { KjTriggerEventStrategy } from '../../tokens';
+
+export function onFocus(): KjTriggerEventStrategy {
+  let ctx: KjOverlayContext | null = null;
+  let toggle: (() => void) | null = null;
+  let onIn: ((e: FocusEvent) => void) | null = null;
+  let onOut: ((e: FocusEvent) => void) | null = null;
+
+  const wire = () => {
+    if (!ctx?.platform.isBrowser) return;
+    const trigger = ctx.triggerEl();
+    if (!trigger || onIn) return;
+    onIn = () => { if (!ctx?.isOpen()) toggle?.(); };
+    onOut = (e: FocusEvent) => {
+      const related = e.relatedTarget as Node | null;
+      const panel = ctx?.panelEl();
+      if (panel && related && panel.contains(related)) return;
+      if (ctx?.isOpen()) toggle?.();
+    };
+    trigger.addEventListener('focusin', onIn);
+    trigger.addEventListener('focusout', onOut);
+  };
+
+  return {
+    ariaHasPopup: null,
+    attach(c) { ctx = c; wire(); },
+    bindToggle(t) { toggle = t; wire(); },
+    onOpen() {}, onClose() {},
+    detach() {
+      const trigger = ctx?.triggerEl();
+      if (trigger && onIn) trigger.removeEventListener('focusin', onIn);
+      if (trigger && onOut) trigger.removeEventListener('focusout', onOut);
+      onIn = onOut = null; toggle = null; ctx = null;
+    },
+  };
+}

package/src/primitives/overlay/strategies/trigger-event/on-hotkey.spec.ts

@@ -0,0 +1,37 @@
+import { describe, it, expect, vi } from 'vitest';
+import { onHotkey } from './on-hotkey';
+
+describe('onHotkey', () => {
+  it('matches mod+k as ctrl+k on non-Mac and triggers toggle', () => {
+    const isMac = /Mac|iPhone|iPad|iPod/.test(navigator.platform);
+    const toggle = vi.fn();
+    const s = onHotkey('mod+k');
+    s.attach({} as never);
+    s.bindToggle(toggle);
+
+    const e = new KeyboardEvent('keydown', {
+      key: 'k',
+      ctrlKey: !isMac,
+      metaKey: isMac,
+      cancelable: true,
+    });
+    document.dispatchEvent(e);
+    expect(toggle).toHaveBeenCalledTimes(1);
+    expect(e.defaultPrevented).toBe(true);
+    s.detach();
+  });
+
+  it('does not match without modifiers', () => {
+    const toggle = vi.fn();
+    const s = onHotkey('mod+k');
+    s.attach({} as never);
+    s.bindToggle(toggle);
+    document.dispatchEvent(new KeyboardEvent('keydown', { key: 'k' }));
+    expect(toggle).not.toHaveBeenCalled();
+    s.detach();
+  });
+
+  it('ariaHasPopup is null', () => {
+    expect(onHotkey('mod+k').ariaHasPopup).toBeNull();
+  });
+});

package/src/primitives/overlay/strategies/trigger-event/on-hotkey.ts

@@ -0,0 +1,59 @@
+import type { KjTriggerEventStrategy } from '../../tokens';
+
+interface ParsedChord { mod: boolean; ctrl: boolean; alt: boolean; shift: boolean; key: string; }
+
+function parseChord(chord: string): ParsedChord {
+  const parts = chord.toLowerCase().split('+').map(p => p.trim());
+  const out: ParsedChord = { mod: false, ctrl: false, alt: false, shift: false, key: '' };
+  for (const p of parts) {
+    if (p === 'mod') out.mod = true;
+    else if (p === 'ctrl' || p === 'control') out.ctrl = true;
+    else if (p === 'alt' || p === 'option') out.alt = true;
+    else if (p === 'shift') out.shift = true;
+    else out.key = p;
+  }
+  return out;
+}
+
+function isMac(): boolean {
+  if (typeof navigator === 'undefined') return false;
+  return /Mac|iPhone|iPad|iPod/.test(navigator.platform);
+}
+
+function matches(e: KeyboardEvent, parsed: ParsedChord): boolean {
+  if (e.key.toLowerCase() !== parsed.key) return false;
+  const wantMeta = parsed.mod && isMac();
+  const wantCtrl = parsed.ctrl || (parsed.mod && !isMac());
+  if (!!e.metaKey !== wantMeta) return false;
+  if (!!e.ctrlKey !== wantCtrl) return false;
+  if (!!e.altKey !== parsed.alt) return false;
+  if (!!e.shiftKey !== parsed.shift) return false;
+  return true;
+}
+
+export function onHotkey(chord: string): KjTriggerEventStrategy {
+  const parsed = parseChord(chord);
+  let toggle: (() => void) | null = null;
+  let listener: ((e: KeyboardEvent) => void) | null = null;
+  let installed = false;
+
+  const install = () => {
+    if (installed || typeof document === 'undefined') return;
+    listener = (e: KeyboardEvent) => {
+      if (matches(e, parsed)) { e.preventDefault(); toggle?.(); }
+    };
+    document.addEventListener('keydown', listener);
+    installed = true;
+  };
+
+  return {
+    ariaHasPopup: null,
+    attach() { install(); },
+    bindToggle(t) { toggle = t; install(); },
+    onOpen() {}, onClose() {},
+    detach() {
+      if (listener) document.removeEventListener('keydown', listener);
+      listener = null; toggle = null; installed = false;
+    },
+  };
+}

package/src/primitives/overlay/strategies/trigger-event/on-hover.spec.ts

@@ -0,0 +1,34 @@
+import { signal } from '@angular/core';
+import { describe, it, expect } from 'vitest';
+import { onHover } from './on-hover';
+import type { KjOverlayContext } from '../../context';
+
+describe('onHover', () => {
+  it('ariaHasPopup is null and strategy has lifecycle methods', () => {
+    const s = onHover();
+    expect(s.ariaHasPopup).toBeNull();
+    expect(typeof s.attach).toBe('function');
+    expect(typeof s.bindToggle).toBe('function');
+    expect(typeof s.detach).toBe('function');
+  });
+
+  it('pointerenter with openDelay=0 triggers toggle synchronously after microtask', async () => {
+    const trigger = document.createElement('button');
+    const isOpen = signal(false);
+    const ctx: KjOverlayContext = {
+      state: signal('closed'), isOpen,
+      triggerEl: signal(trigger), panelEl: signal(null),
+      stack: {} as never, platform: { isBrowser: true },
+      requestClose: () => {},
+    };
+    let called = 0;
+    const toggle = () => { called++; };
+    const s = onHover({ openDelay: 0 });
+    s.attach(ctx);
+    s.bindToggle(toggle);
+    trigger.dispatchEvent(new Event('pointerenter'));
+    await new Promise(r => setTimeout(r, 5));
+    expect(called).toBe(1);
+    s.detach();
+  });
+});

package/src/primitives/overlay/strategies/trigger-event/on-hover.ts

@@ -0,0 +1,86 @@
+import { isSignal, type Signal } from '@angular/core';
+import type { KjOverlayContext } from '../../context';
+import type { KjTriggerEventStrategy } from '../../tokens';
+
+type Reactive<T> = T | Signal<T> | (() => T);
+const read = <T>(v: Reactive<T> | undefined, fallback: T): T => {
+  if (v === undefined) return fallback;
+  if (isSignal(v)) return v();
+  if (typeof v === 'function') return (v as () => T)();
+  return v;
+};
+
+export interface KjOnHoverOpts {
+  openDelay?: Reactive<number>;
+  closeDelay?: Reactive<number>;
+}
+
+export type KjOnHoverStrategy = KjTriggerEventStrategy & {
+  configure(opts: Partial<KjOnHoverOpts>): void;
+};
+
+/**
+ * Returns the effective hover-listening target. `pointerenter`/`pointerleave`
+ * do not bubble, and elements with `display: contents` (e.g. `<kj-button>`)
+ * never receive these events because they have no rendered box. Walk to the
+ * first descendant with a layout box.
+ */
+const effectiveHoverTarget = (el: HTMLElement): HTMLElement => {
+  if (typeof window === 'undefined') return el;
+  const r = el.getBoundingClientRect();
+  if (r.width > 0 || r.height > 0) return el;
+  let cur: HTMLElement | null = el;
+  while (cur) {
+    const child = cur.firstElementChild as HTMLElement | null;
+    if (!child) break;
+    const cr = child.getBoundingClientRect();
+    if (cr.width > 0 || cr.height > 0) return child;
+    cur = child;
+  }
+  return el;
+};
+
+export function onHover(initialOpts: Partial<KjOnHoverOpts> = {}): KjOnHoverStrategy {
+  let opts: Partial<KjOnHoverOpts> = { ...initialOpts };
+  let ctx: KjOverlayContext | null = null;
+  let toggle: (() => void) | null = null;
+  let openTimer = 0, closeTimer = 0;
+  let onEnter: ((e: Event) => void) | null = null;
+  let onLeave: ((e: Event) => void) | null = null;
+  let listenTarget: HTMLElement | null = null;
+
+  const wire = () => {
+    if (!ctx?.platform.isBrowser) return;
+    const trigger = ctx.triggerEl();
+    if (!trigger || onEnter) return;
+    listenTarget = effectiveHoverTarget(trigger);
+    onEnter = () => {
+      if (closeTimer) { clearTimeout(closeTimer); closeTimer = 0; }
+      if (ctx?.isOpen()) return;
+      openTimer = setTimeout(() => { toggle?.(); openTimer = 0; }, read(opts.openDelay, 0)) as unknown as number;
+    };
+    onLeave = () => {
+      if (openTimer) { clearTimeout(openTimer); openTimer = 0; }
+      if (!ctx?.isOpen()) return;
+      closeTimer = setTimeout(() => { toggle?.(); closeTimer = 0; }, read(opts.closeDelay, 0)) as unknown as number;
+    };
+    listenTarget.addEventListener('pointerenter', onEnter);
+    listenTarget.addEventListener('pointerleave', onLeave);
+  };
+
+  return {
+    ariaHasPopup: null,
+    attach(c) { ctx = c; wire(); },
+    bindToggle(t) { toggle = t; wire(); },
+    onOpen() {}, onClose() {},
+    detach() {
+      if (listenTarget && onEnter) listenTarget.removeEventListener('pointerenter', onEnter);
+      if (listenTarget && onLeave) listenTarget.removeEventListener('pointerleave', onLeave);
+      if (openTimer) clearTimeout(openTimer);
+      if (closeTimer) clearTimeout(closeTimer);
+      onEnter = onLeave = null; listenTarget = null; openTimer = closeTimer = 0;
+      toggle = null; ctx = null;
+    },
+    configure(newOpts) { opts = { ...opts, ...newOpts }; },
+  };
+}

package/src/primitives/overlay/strategies/trigger-event/programmatic.spec.ts

@@ -0,0 +1,16 @@
+import { describe, it, expect, vi } from 'vitest';
+import { programmatic } from './programmatic';
+
+describe('programmatic', () => {
+  it('never invokes toggle from DOM events', () => {
+    const toggle = vi.fn();
+    const s = programmatic();
+    s.attach({} as never);
+    s.bindToggle(toggle);
+    expect(toggle).not.toHaveBeenCalled();
+  });
+
+  it('ariaHasPopup is null', () => {
+    expect(programmatic().ariaHasPopup).toBeNull();
+  });
+});

package/src/primitives/overlay/strategies/trigger-event/programmatic.ts

@@ -0,0 +1,12 @@
+import type { KjTriggerEventStrategy } from '../../tokens';
+
+export function programmatic(): KjTriggerEventStrategy {
+  let _toggle: (() => void) | null = null;
+  return {
+    ariaHasPopup: null,
+    attach() {},
+    bindToggle(t) { _toggle = t; },
+    onOpen() {}, onClose() {},
+    detach() { _toggle = null; },
+  };
+}

package/src/primitives/overlay/tokens.ts

@@ -0,0 +1,54 @@
+import { InjectionToken, type Signal } from '@angular/core';
+import type { KjOverlayContext } from './context';
+import type { KjPanelRole, KjPlacement } from './types';
+
+/** Common shape for every overlay strategy. */
+export interface KjStrategy {
+  attach(ctx: KjOverlayContext): void;
+  onOpen?(): void;
+  onClose?(): void;
+  detach(): void;
+}
+
+export interface KjMountStrategy extends KjStrategy {
+  resolveContainer(): HTMLElement;
+  readonly portalled: boolean;
+}
+
+export interface KjPositionStrategy extends KjStrategy {
+  update(): void;
+  readonly placement?: Signal<KjPlacement | null>;
+}
+
+export interface KjBackdropStrategy extends KjStrategy {
+  readonly inertSiblings: boolean;
+  readonly closeOnClick: boolean;
+}
+
+export interface KjFocusTrapStrategy extends KjStrategy {
+  focusFirst(): void;
+  restoreFocus(): void;
+}
+
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type
+export interface KjScrollLockStrategy extends KjStrategy {}
+
+export interface KjLiveAnnouncerStrategy extends KjStrategy {
+  announce(message: string): void;
+}
+
+export type KjAriaHasPopup = 'menu' | 'listbox' | 'tree' | 'grid' | 'dialog' | null;
+
+export interface KjTriggerEventStrategy extends KjStrategy {
+  readonly ariaHasPopup: KjAriaHasPopup;
+  bindToggle(toggle: () => void): void;
+}
+
+export const KJ_OVERLAY_MOUNT_STRATEGY          = new InjectionToken<KjMountStrategy>('KJ_OVERLAY_MOUNT_STRATEGY');
+export const KJ_OVERLAY_POSITION_STRATEGY       = new InjectionToken<KjPositionStrategy>('KJ_OVERLAY_POSITION_STRATEGY');
+export const KJ_OVERLAY_BACKDROP_STRATEGY       = new InjectionToken<KjBackdropStrategy | null>('KJ_OVERLAY_BACKDROP_STRATEGY');
+export const KJ_OVERLAY_FOCUS_TRAP_STRATEGY     = new InjectionToken<KjFocusTrapStrategy>('KJ_OVERLAY_FOCUS_TRAP_STRATEGY');
+export const KJ_OVERLAY_SCROLL_LOCK_STRATEGY    = new InjectionToken<KjScrollLockStrategy>('KJ_OVERLAY_SCROLL_LOCK_STRATEGY');
+export const KJ_OVERLAY_LIVE_ANNOUNCER_STRATEGY = new InjectionToken<KjLiveAnnouncerStrategy>('KJ_OVERLAY_LIVE_ANNOUNCER_STRATEGY');
+export const KJ_OVERLAY_TRIGGER_EVENT_STRATEGY  = new InjectionToken<KjTriggerEventStrategy>('KJ_OVERLAY_TRIGGER_EVENT_STRATEGY');
+export const KJ_OVERLAY_PANEL_ROLE              = new InjectionToken<KjPanelRole>('KJ_OVERLAY_PANEL_ROLE');

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

@@ -0,0 +1,103 @@
+import { Component, inject, ChangeDetectionStrategy } from '@angular/core';
+import { render } from '@testing-library/angular';
+import { describe, it, expect } from 'vitest';
+import { KjOverlayTrigger } from './trigger';
+import { KjOverlayController } from './controller';
+import { KJ_OVERLAY_TRIGGER_EVENT_STRATEGY } from './tokens';
+import { onClick } from './strategies/trigger-event/on-click';
+import { bodyPortal } from './strategies/mount/body-portal';
+import { viewportCentered } from './strategies/position/viewport-centered';
+
+@Component({
+  selector: 'kj-trig-host',
+  standalone: true,
+  hostDirectives: [KjOverlayTrigger],
+  providers: [
+    KjOverlayController,
+    { provide: KJ_OVERLAY_TRIGGER_EVENT_STRATEGY, useFactory: () => onClick() },
+  ],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: '',
+})
+class TrigHost {
+  private readonly ctrl = inject(KjOverlayController);
+  constructor() {
+    this.ctrl.attachStrategies({
+      mount: bodyPortal(),
+      position: viewportCentered(),
+      trigger: inject(KJ_OVERLAY_TRIGGER_EVENT_STRATEGY),
+    });
+  }
+}
+
+@Component({
+  selector: 'kj-trig-menu-host',
+  standalone: true,
+  hostDirectives: [KjOverlayTrigger],
+  providers: [
+    KjOverlayController,
+    {
+      provide: KJ_OVERLAY_TRIGGER_EVENT_STRATEGY,
+      useFactory: () => ({
+        ariaHasPopup: 'menu' as const,
+        attach() {},
+        bindToggle() {},
+        onOpen() {},
+        onClose() {},
+        detach() {},
+      }),
+    },
+  ],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: '',
+})
+class TrigMenuHost {
+  private readonly ctrl = inject(KjOverlayController);
+  constructor() {
+    this.ctrl.attachStrategies({
+      mount: bodyPortal(),
+      position: viewportCentered(),
+      trigger: inject(KJ_OVERLAY_TRIGGER_EVENT_STRATEGY),
+    });
+  }
+}
+
+@Component({
+  selector: 'kj-trig-ctrl-host',
+  standalone: true,
+  hostDirectives: [KjOverlayTrigger],
+  providers: [
+    KjOverlayController,
+    { provide: KJ_OVERLAY_TRIGGER_EVENT_STRATEGY, useFactory: () => onClick() },
+  ],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: '',
+})
+class TrigCtrlHost {
+  readonly ctrl = inject(KjOverlayController);
+}
+
+describe('KjOverlayTrigger', () => {
+  it('host has aria-haspopup and data-state attrs initially', async () => {
+    const { fixture } = await render(TrigHost);
+    const el = fixture.nativeElement as HTMLElement;
+    expect(el.getAttribute('data-state')).toBe('closed');
+    expect(el.getAttribute('aria-expanded')).toBe('false');
+  });
+
+  it('exports as kjOverlayTrigger', () => {
+    expect(KjOverlayTrigger).toBeTruthy();
+  });
+
+  it('controller is provided per-host', async () => {
+    const { fixture } = await render(TrigCtrlHost);
+    expect(fixture.componentInstance.ctrl).toBeTruthy();
+    expect(fixture.componentInstance.ctrl.state()).toBe('closed');
+  });
+
+  it('aria-haspopup uses strategy value', async () => {
+    const { fixture } = await render(TrigMenuHost);
+    const el = fixture.nativeElement as HTMLElement;
+    expect(el.getAttribute('aria-haspopup')).toBe('menu');
+  });
+});

package/src/primitives/overlay/trigger.ts

@@ -0,0 +1,75 @@
+import { Directive, ElementRef, inject, model, computed, effect, untracked } from '@angular/core';
+import { KjOverlayController } from './controller';
+import { KJ_OVERLAY_TRIGGER_EVENT_STRATEGY } from './tokens';
+import type { KjOverlayPanel } from './panel';
+
+/**
+ * Marks an element as the overlay trigger — owns `aria-haspopup`,
+ * `aria-expanded`, `aria-controls`, the trigger-event strategy, and the
+ * two-way `kjOpen` model that mirrors the controller's open state.
+ *
+ * @doc-category Core/Overlay
+ * @doc
+ * @doc-name overlay-trigger
+ * @doc-is-main
+ * @doc-description Marks an element as the trigger that opens and closes an overlay panel.
+ */
+@Directive({
+  selector: '[kjOverlayTrigger]',
+  exportAs: 'kjOverlayTrigger',
+  // NOTE: do NOT provide KjOverlayController here. Consumer trigger directives
+  // (e.g. KjSelectTrigger, KjTreeSelectTrigger) provide it on their host
+  // element so the SAME instance is visible to both KjOverlayTrigger and any
+  // sibling KjOverlayPanel via [kjFor]. For "controller-on-root" patterns
+  // (e.g. KjColorPicker), the root directive provides it and ALL descendants
+  // share one instance.
+  host: {
+    '[attr.aria-haspopup]':  'ariaHasPopup() ?? null',
+    '[attr.aria-expanded]':  'isOpen()',
+    '[attr.aria-controls]':  'panelId() ?? null',
+    '[attr.data-state]':     'state()',
+  },
+})
+export class KjOverlayTrigger {
+  private readonly host       = inject(ElementRef<HTMLElement>);
+  /**
+   * The overlay controller for this trigger's scope. Exposed publicly so
+   * sibling `KjOverlayPanel` directives wired via `[kjFor]` can read it
+   * from their element injector (which would otherwise not see this
+   * directive's providers).
+   */
+  readonly controller = inject(KjOverlayController);
+  private readonly triggerStrategy = inject(KJ_OVERLAY_TRIGGER_EVENT_STRATEGY);
+
+  readonly kjOpen = model<boolean>(false);
+  readonly state   = this.controller.state;
+  readonly isOpen  = this.controller.isOpen;
+  readonly panelId = computed(() => this.controller.panelEl()?.id ?? null);
+  readonly ariaHasPopup = computed(() => this.triggerStrategy.ariaHasPopup);
+
+  attachPanel(panel: KjOverlayPanel): void {
+    this.controller.bindPanel(panel.host.nativeElement);
+  }
+
+  constructor() {
+    this.controller.bindTrigger(this.host.nativeElement);
+    // The trigger strategy lives on the trigger element. Attach + bind here so
+    // its DOM listeners wire up regardless of whether a panel ever attaches
+    // (e.g. tooltip with no [kjFor]).
+    this.triggerStrategy.attach(this.controller.context);
+    this.triggerStrategy.bindToggle(() => this.controller.toggle());
+    // Sync model → controller (user toggled kjOpen via two-way binding)
+    effect(() => {
+      const wantOpen = this.kjOpen();
+      const isOpen = untracked(() => this.controller.isOpen());
+      if (wantOpen && !isOpen) this.controller.open();
+      if (!wantOpen && isOpen) this.controller.close('programmatic');
+    });
+    // Sync controller → model (controller state changed via trigger event / outside-click / esc)
+    effect(() => {
+      const isOpen = this.controller.isOpen();
+      const wantOpen = untracked(() => this.kjOpen());
+      if (isOpen !== wantOpen) this.kjOpen.set(isOpen);
+    });
+  }
+}

package/src/primitives/overlay/types.ts

@@ -0,0 +1,24 @@
+/** Side on which a floating element is placed relative to its anchor. */
+export type KjSide = 'top' | 'bottom' | 'left' | 'right';
+
+/** Alignment of the floating element along the cross-axis of its side. */
+export type KjAlign = 'start' | 'center' | 'end';
+
+/** Resolved (post-flip / post-shift) placement. */
+export interface KjPlacement {
+  side: KjSide;
+  align: KjAlign;
+}
+
+/** Lifecycle state of an overlay. */
+export type KjOverlayState = 'closed' | 'opening' | 'open' | 'closing';
+
+/** ARIA role applied to the panel element. */
+export type KjPanelRole =
+  | 'dialog' | 'alertdialog'
+  | 'tooltip'
+  | 'menu' | 'listbox' | 'tree'
+  | 'status' | 'alert';
+
+/** Reason a close was requested. */
+export type KjCloseReason = 'esc' | 'outside' | 'programmatic';