@kouji-ui/core 0.0.4 → 0.1.1

package/src/drawer/drawer.ts

@@ -0,0 +1,122 @@
+import {
+  ChangeDetectionStrategy,
+  Component,
+  ElementRef,
+  HostListener,
+  ViewEncapsulation,
+  computed,
+  inject,
+} from '@angular/core';
+import { KjOverlayPanel } from '../primitives/overlay/panel';
+import { DRAWER_DRAG, DRAWER_SIDE, type KjDrawerSide } from './drawer.service';
+import { KjDrawerRef } from './drawer.ref';
+
+/** Downward drag fraction past which release dismisses (bottom side). */
+const DEFAULT_DISMISS_THRESHOLD = 0.4;
+/** Downward velocity (px/s) past which release dismisses (bottom side). */
+const DEFAULT_DISMISS_VELOCITY = 600;
+
+/**
+ * Drawer body component. Composes {@link KjOverlayPanel} so the host element
+ * inherits `role`, `[data-state]`, and the configured side strategy from
+ * `KjDrawer.open()`. Preserves the optional drag-to-dismiss behaviour: when
+ * `KjDrawer.open({ drag: true, side: 'bottom' })`, pointer-down on the host
+ * starts a drag that calls `ref.close()` once the threshold is crossed.
+ *
+ * @doc-category Core/Overlay
+ */
+@Component({
+  selector: 'kj-drawer',
+  standalone: true,
+  hostDirectives: [{ directive: KjOverlayPanel }],
+  host: {
+    'class': 'kj-drawer',
+    '[attr.data-kj-side]': 'side',
+    '[attr.data-kj-dragging]': 'dragging() ? "" : null',
+    '[style.touch-action]': 'dragging() ? "none" : null',
+    '(pointerdown)': 'onPointerDown($event)',
+    '(pointermove)': 'onPointerMove($event)',
+    '(pointerup)':   'onPointerUp($event)',
+    '(pointercancel)': 'onPointerCancel($event)',
+  },
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  encapsulation: ViewEncapsulation.None,
+  template: `<ng-content />`,
+})
+export class KjDrawer {
+  /** Resolved drawer side (provided by `KjDrawer.open`). */
+  readonly side = inject<KjDrawerSide>(DRAWER_SIDE, { optional: true }) ?? 'right';
+  /** Whether drag-to-dismiss is active for this drawer. */
+  readonly drag = inject<boolean>(DRAWER_DRAG, { optional: true }) ?? false;
+
+  private readonly ref = inject<KjDrawerRef<unknown>>(KjDrawerRef, { optional: true });
+  private readonly el = inject<ElementRef<HTMLElement>>(ElementRef);
+
+  private startY = 0;
+  private startTime = 0;
+  private pointerId: number | null = null;
+  private _dragging = false;
+
+  /** Reactive flag for `data-kj-dragging` host binding. */
+  protected dragging = computed(() => this._dragging);
+
+  /** @internal */
+  onPointerDown(event: PointerEvent): void {
+    if (!this.drag) return;
+    if (this.side !== 'bottom') return;
+    if (event.button !== undefined && event.button !== 0) return;
+    this.pointerId = event.pointerId;
+    this.startY = event.clientY;
+    this.startTime = typeof performance !== 'undefined' ? performance.now() : Date.now();
+    this._dragging = true;
+    (event.target as Element | null)?.setPointerCapture?.(event.pointerId);
+  }
+
+  /** @internal */
+  onPointerMove(event: PointerEvent): void {
+    if (!this._dragging) return;
+    if (this.pointerId !== null && event.pointerId !== this.pointerId) return;
+    const offset = Math.max(0, event.clientY - this.startY);
+    this.el.nativeElement.style.setProperty('--kj-drawer-drag-offset', `${offset}px`);
+  }
+
+  /** @internal */
+  onPointerUp(event: PointerEvent): void {
+    if (!this._dragging) return;
+    if (this.pointerId !== null && event.pointerId !== this.pointerId) return;
+    const now = typeof performance !== 'undefined' ? performance.now() : Date.now();
+    const dy = Math.max(0, event.clientY - this.startY);
+    const dt = Math.max(1, now - this.startTime);
+    const velocity = (dy / dt) * 1000;
+    this.endDrag();
+    const panelHeight = this.el.nativeElement.getBoundingClientRect().height || 200;
+    if (
+      velocity > DEFAULT_DISMISS_VELOCITY
+      || dy / panelHeight >= DEFAULT_DISMISS_THRESHOLD
+    ) {
+      this.ref?.close();
+    }
+  }
+
+  /** @internal */
+  onPointerCancel(_event: PointerEvent): void {
+    this.endDrag();
+  }
+
+  private endDrag(): void {
+    this._dragging = false;
+    this.pointerId = null;
+    this.el.nativeElement.style.removeProperty('--kj-drawer-drag-offset');
+  }
+
+  /** Close the drawer with an optional payload. */
+  close(result?: unknown): void {
+    (this.ref as KjDrawerRef<unknown, unknown> | null)?.close(result);
+  }
+
+  /** Esc closes via the overlay-stack coordinator on the controller. */
+  @HostListener('keydown.escape')
+  onEscape(): void {
+    this.ref?.close();
+  }
+}

package/src/drawer/index.ts

@@ -0,0 +1,10 @@
+export { KjDrawer } from './drawer';
+export {
+  KjDrawerService,
+  DRAWER_DATA,
+  DRAWER_SIDE,
+  DRAWER_DRAG,
+  type KjDrawerOpenOptions,
+  type KjDrawerSide,
+} from './drawer.service';
+export { KjDrawerRef } from './drawer.ref';

package/src/dropdown-menu/dropdown-menu-content.ts

@@ -0,0 +1,258 @@
+import {
+  Component,
+  ChangeDetectionStrategy,
+  ViewEncapsulation,
+  Injector,
+  computed,
+  contentChildren,
+  effect,
+  forwardRef,
+  inject,
+  input,
+  signal,
+  untracked,
+} from '@angular/core';
+import { KjOverlayPanel } from '../primitives/overlay/panel';
+import {
+  KJ_OVERLAY_MOUNT_STRATEGY,
+  KJ_OVERLAY_POSITION_STRATEGY,
+  KJ_OVERLAY_PANEL_ROLE,
+} from '../primitives/overlay/tokens';
+import type {
+  KjMountStrategy,
+  KjPositionStrategy,
+} from '../primitives/overlay/tokens';
+import type { KjOverlayContext } from '../primitives/overlay/context';
+import type { KjSide, KjAlign } from '../primitives/overlay/types';
+import { bodyPortal } from '../primitives/overlay/strategies/mount/body-portal';
+import { inPlace } from '../primitives/overlay/strategies/mount/in-place';
+import { anchoredTo } from '../primitives/overlay/strategies/position/anchored-to';
+import { pointAt } from '../primitives/overlay/strategies/position/point-at';
+import { inPlaceSibling } from '../primitives/overlay/strategies/position/in-place-sibling';
+import {
+  KJ_LIST_FOCUS_MODE,
+  KJ_LIST_NAVIGATOR_CONFIG,
+  KjListItem,
+  KjListNavigator,
+  KjTypeAhead,
+  type KjCompareFn,
+  type KjListFocusMode,
+  type KjListNavigatorConfig,
+} from '../primitives/list';
+import {
+  KjDropdownMenuTrigger,
+  KJ_DROPDOWN_MENU,
+  type KjDropdownMenuCloseReason,
+  type KjDropdownMenuContext,
+} from './dropdown-menu-trigger';
+
+type KjDeferredMount = KjMountStrategy & { setDelegate(d: KjMountStrategy): void };
+type KjDeferredPosition = KjPositionStrategy & { setDelegate(d: KjPositionStrategy): void };
+
+function deferredMount(): KjDeferredMount {
+  let ctx: KjOverlayContext | null = null;
+  let delegate: KjMountStrategy | null = null;
+  let attached = false;
+  let opened = false;
+  return {
+    get portalled() { return delegate?.portalled ?? true; },
+    attach(c) { ctx = c; attached = true; if (delegate) delegate.attach(c); },
+    onOpen() { opened = true; delegate?.onOpen?.(); },
+    onClose() { opened = false; delegate?.onClose?.(); },
+    detach() { delegate?.detach(); ctx = null; attached = false; },
+    resolveContainer() {
+      const from = delegate?.resolveContainer();
+      if (from) return from;
+      if (typeof document === 'undefined') return null as unknown as HTMLElement;
+      return document.body;
+    },
+    setDelegate(d) {
+      delegate = d;
+      if (attached && ctx) d.attach(ctx);
+      if (opened) d.onOpen?.();
+    },
+  };
+}
+
+function deferredPosition(): KjDeferredPosition {
+  let ctx: KjOverlayContext | null = null;
+  let delegate: KjPositionStrategy | null = null;
+  let attached = false;
+  let opened = false;
+  return {
+    attach(c) { ctx = c; attached = true; if (delegate) delegate.attach(c); },
+    onOpen() { opened = true; delegate?.onOpen?.(); },
+    onClose() { opened = false; delegate?.onClose?.(); },
+    update() { delegate?.update(); },
+    detach() { delegate?.detach(); ctx = null; attached = false; },
+    setDelegate(d) {
+      delegate = d;
+      if (attached && ctx) d.attach(ctx);
+      if (opened) d.onOpen?.();
+    },
+  };
+}
+
+/**
+ * The dropdown-menu content panel. Composes `KjOverlayPanel` and dispatches
+ * mount + position strategies based on `kjMount`:
+ *
+ * - `'portal'` (default) — `bodyPortal()` + `anchoredTo(trigger, side, align)`
+ * - `'point'`            — `bodyPortal()` + `pointAt({x, y})` (right-click / context-menu)
+ * - `'inline'`           — `inPlace()`    + `inPlaceSibling()`
+ *
+ * Sets `role="menu"` via the panel role token. Composes
+ * `KjListNavigator{kjOrientation:'vertical', kjFocusMode:'roving'}` and
+ * provides `KjTypeAhead`, so projected `[kjDropdownMenuItem]`s get the
+ * full WAI-ARIA APG menu keyboard contract (Up/Down/Home/End/type-ahead)
+ * + roving DOM focus for free. Implements {@link KjListNavigatorConfig}
+ * — items are actions, no selection model.
+ *
+ * @doc-category Core/Overlay
+ */
+@Component({
+  selector: 'kj-dropdown-menu-content',
+  standalone: true,
+  hostDirectives: [
+    { directive: KjOverlayPanel, inputs: ['kjFor'] },
+    {
+      directive: KjListNavigator,
+      inputs: ['kjOrientation', 'kjFocusMode'],
+    },
+  ],
+  providers: [
+    { provide: KJ_OVERLAY_PANEL_ROLE, useValue: 'menu' as const },
+    { provide: KJ_OVERLAY_MOUNT_STRATEGY, useFactory: () => deferredMount() },
+    { provide: KJ_OVERLAY_POSITION_STRATEGY, useFactory: () => deferredPosition() },
+    { provide: KJ_DROPDOWN_MENU, useExisting: KjDropdownMenuContent },
+    { provide: KJ_LIST_NAVIGATOR_CONFIG, useExisting: forwardRef(() => KjDropdownMenuContent) },
+    // Force roving focus mode at the element injector. `KjListNavigator`
+    // also provides this token (driven by its own `kjFocusMode` input,
+    // which defaults to `'activedescendant'`). Overriding here means
+    // `KjListItem`s under this content compute their `tabindex` from a
+    // signal that always reads `'roving'` — independent of whether the
+    // consumer remembered to set `kjFocusMode` on the navigator.
+    {
+      provide: KJ_LIST_FOCUS_MODE,
+      useFactory: () => signal<KjListFocusMode>('roving'),
+    },
+    KjTypeAhead,
+  ],
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  encapsulation: ViewEncapsulation.None,
+  host: {
+    'class': 'kj-dropdown-menu',
+    // The KjListNavigator host directive reads `kjOrientation` and
+    // `kjFocusMode` as signal inputs; setting the matching static
+    // attributes here seeds their initial values for the menu pattern
+    // (vertical orientation + roving DOM focus per WAI-ARIA APG).
+    'kjOrientation': 'vertical',
+    'kjFocusMode': 'roving',
+    '(keydown.escape)': 'onEscape($event)',
+  },
+  template: `<ng-content />`,
+})
+export class KjDropdownMenuContent implements KjDropdownMenuContext, KjListNavigatorConfig {
+  readonly kjSide  = input<KjSide>('bottom');
+  readonly kjAlign = input<KjAlign>('start');
+  readonly kjMount = input<'portal' | 'point' | 'inline'>('portal');
+
+  // ── KjListNavigatorConfig ────────────────────────────────────────────
+  /** All `KjListItem`s projected into the menu panel. */
+  readonly items = contentChildren(KjListItem, { descendants: true });
+  /** Menu items are actions — no selection model. Kept as `Object.is`. */
+  readonly compareBy = signal<KjCompareFn<unknown>>(Object.is as KjCompareFn<unknown>);
+  /**
+   * Universal menu UX: any item activation closes the menu. `KjListItem`
+   * calls this with `closeRequested=false` since no `KjSelectionModel` is
+   * provided — we override the flag and always close.
+   */
+  afterSelect(_value: unknown, _closeRequested: boolean): void {
+    this.hide('item');
+  }
+
+  private readonly _injector = inject(Injector);
+  private _panelCache: KjOverlayPanel | null | undefined = undefined;
+  private get _panel(): KjOverlayPanel | null {
+    if (this._panelCache === undefined) {
+      this._panelCache = this._injector.get(KjOverlayPanel, null);
+    }
+    return this._panelCache;
+  }
+
+  /** Mirror of trigger's closeOnSelect — defaults to true; trigger overrides via its own provider. */
+  readonly closeOnSelect = computed(() => true);
+
+  /** Item-driven close. Routes through the panel's controller (resolved via `kjFor`). */
+  hide(_reason: KjDropdownMenuCloseReason): void {
+    this._panel?.controller?.close('programmatic');
+  }
+
+  /** Escape key — closes the menu. KjListNavigator does not own Escape. */
+  protected onEscape(event: Event): void {
+    event.preventDefault();
+    event.stopPropagation();
+    this.hide('escape');
+  }
+
+  /**
+   * Lazily-resolved reference to the composed `KjListNavigator`. Resolved
+   * inside effects (not at construction) to avoid the
+   * `KjListNavigator <-> KJ_LIST_NAVIGATOR_CONFIG (useExisting this) <-> KjListNavigator`
+   * NG0200 cycle that synchronous injection of `KjListNavigator` would
+   * trigger at the element injector.
+   */
+  private _navCache: KjListNavigator | null = null;
+  private getNav(): KjListNavigator | null {
+    if (this._navCache) return this._navCache;
+    this._navCache = this._injector.get(KjListNavigator, null, { self: true });
+    return this._navCache;
+  }
+
+  constructor() {
+    const mount = inject(KJ_OVERLAY_MOUNT_STRATEGY) as KjDeferredMount;
+    const position = inject(KJ_OVERLAY_POSITION_STRATEGY) as KjDeferredPosition;
+    const trigDir = inject(KjDropdownMenuTrigger, { optional: true });
+    const m = this.kjMount();
+    if (m === 'inline') {
+      mount.setDelegate(inPlace());
+      position.setDelegate(inPlaceSibling());
+    } else if (m === 'point' && trigDir) {
+      mount.setDelegate(bodyPortal());
+      position.setDelegate(pointAt({ x: trigDir.kjPointX, y: trigDir.kjPointY }));
+    } else {
+      mount.setDelegate(bodyPortal());
+      position.setDelegate(anchoredTo({ side: this.kjSide, align: this.kjAlign }));
+    }
+
+    // Roving seed: when nothing is active yet (e.g. just-opened menu),
+    // point the navigator at the first non-disabled item so its host
+    // gets `tabindex=0` and is reachable by Tab. Mirrors the seed effect
+    // inside `KjListNavigator` for the `'roving'` focus mode — needed
+    // here because the navigator's own seed gates on `kjFocusMode()`,
+    // which stays at the directive's default `'activedescendant'`
+    // (host-directive inputs cannot be defaulted from this component).
+    effect(() => {
+      const items = this.items();
+      const nav = this.getNav();
+      if (!nav) return;
+      if (nav.activeId() !== null) return;
+      const first = items.find(i => !i.disabled());
+      if (first) untracked(() => nav.setActive(first.id));
+    });
+
+    // Roving focus follow: move DOM focus onto the active item's host.
+    // Same rationale as the seed effect — the navigator's own
+    // focus-follow effect gates on `kjFocusMode() === 'roving'`.
+    effect(() => {
+      const nav = this.getNav();
+      if (!nav) return;
+      const item = nav.activeItem();
+      if (!item) return;
+      const host = item._host();
+      if (host && typeof document !== 'undefined' && document.activeElement !== host) {
+        untracked(() => host.focus());
+      }
+    });
+  }
+}

package/src/dropdown-menu/dropdown-menu-group.ts

@@ -0,0 +1,31 @@
+import { Directive } from '@angular/core';
+import { KjListGroup } from '../primitives/list';
+
+/**
+ * A logical grouping of items inside a `[kjDropdownMenu]` panel.
+ *
+ * Composes the shared `KjListGroup` primitive — `role="group"`,
+ * auto-`aria-labelledby` wiring to a child `[kjDropdownMenuLabel]`, and
+ * auto-hide when every child item is filter-hidden.
+ *
+ * @example
+ * ```html
+ * <div kjDropdownMenuGroup>
+ *   <span kjDropdownMenuLabel>Account</span>
+ *   <button kjDropdownMenuItem>Profile</button>
+ *   <button kjDropdownMenuItem>Settings</button>
+ * </div>
+ * ```
+ * @doc-category Core/Overlay
+ */
+@Directive({
+  selector: '[kjDropdownMenuGroup]',
+  standalone: true,
+  hostDirectives: [
+    { directive: KjListGroup, inputs: ['kjId'] },
+  ],
+  host: {
+    'class': 'kj-dropdown-menu-group',
+  },
+})
+export class KjDropdownMenuGroup {}

package/src/dropdown-menu/dropdown-menu-item.ts

@@ -0,0 +1,51 @@
+import {
+  Directive,
+  output,
+} from '@angular/core';
+import { KjListItem, injectListItem } from '../primitives/list';
+
+/**
+ * An individual item inside a `[kjDropdownMenu]` panel.
+ *
+ * Apply on a `<button>`. Sets `role="menuitem"` and composes `KjListItem`
+ * for id, value, label, disabled state, click + Enter/Space activation,
+ * `aria-disabled`, and (via the surrounding `KjListNavigator` in roving
+ * mode) `tabindex` driven by the active-item state.
+ *
+ * Activation flows through `KjListItem._activate` → root config's
+ * `afterSelect` hook → overlay close. This directive only contributes
+ * `role="menuitem"`, the `kj-dropdown-menu-item` class, the `kj*` input
+ * aliases, and re-emits the composed `activate` output as `kjSelect`.
+ *
+ * @doc-category Core/Overlay
+ */
+@Directive({
+  selector: '[kjDropdownMenuItem]',
+  standalone: true,
+  hostDirectives: [
+    {
+      directive: KjListItem,
+      inputs: [
+        'kjItemLabel:kjLabel',
+        'kjShortcut:kjShortcut',
+        'kjDisabled:kjDisabled',
+      ],
+    },
+  ],
+  host: {
+    'class': 'kj-dropdown-menu-item',
+    'role': 'menuitem',
+  },
+})
+export class KjDropdownMenuItem {
+  private readonly item = injectListItem<unknown>();
+
+  /** Emitted when the item is activated (click / Enter / Space). */
+  readonly kjSelect = output<void>();
+
+  constructor() {
+    // Forward the primitive's activation output so consumers can keep
+    // listening to `(kjSelect)` exactly as before.
+    this.item.activate.subscribe(() => this.kjSelect.emit());
+  }
+}

package/src/dropdown-menu/dropdown-menu-label.ts

@@ -0,0 +1,41 @@
+import { Directive, inject } from '@angular/core';
+import { KjListGroupLabel } from '../primitives/list';
+
+/**
+ * A non-interactive heading inside a `[kjDropdownMenu]` panel.
+ *
+ * Composes the shared `KjListGroupLabel` primitive, which mints a stable
+ * id and registers it with the surrounding `[kjDropdownMenuGroup]`
+ * (composing `KjListGroup`) so screen readers announce the group with
+ * the label's text content via `aria-labelledby`.
+ *
+ * Sets `role="presentation"` — the label is heading text, not a
+ * focusable item, and the surrounding navigator skips it.
+ *
+ * @example
+ * ```html
+ * <span kjDropdownMenuLabel>Account</span>
+ * ```
+ * @doc-category Core/Overlay
+ */
+@Directive({
+  selector: '[kjDropdownMenuLabel]',
+  standalone: true,
+  exportAs: 'kjDropdownMenuLabel',
+  hostDirectives: [
+    { directive: KjListGroupLabel, inputs: ['kjId'] },
+  ],
+  host: {
+    'class': 'kj-dropdown-menu-label',
+    'role': 'presentation',
+  },
+})
+export class KjDropdownMenuLabel {
+  /** Composed label primitive — exposes the resolved id. */
+  private readonly label = inject(KjListGroupLabel, { self: true });
+
+  /** Stable id used by a wrapping `[kjDropdownMenuGroup]` for `aria-labelledby`. */
+  get id(): string {
+    return this.label.id();
+  }
+}

package/src/dropdown-menu/dropdown-menu-separator.ts

@@ -0,0 +1,27 @@
+import { Directive } from '@angular/core';
+import { KjListSeparator } from '../primitives/list';
+
+/**
+ * A non-focusable horizontal divider between groups of menu items.
+ *
+ * Composes the shared `KjListSeparator` primitive — sets
+ * `role="separator"` and `aria-orientation="horizontal"`. The roving
+ * navigator / type-ahead in `[kjDropdownMenu]` skips it because it isn't
+ * a `KjListItem`.
+ *
+ * @example
+ * ```html
+ * <div kjDropdownMenuSeparator></div>
+ * ```
+ * @doc-category Core/Overlay
+ */
+@Directive({
+  selector: '[kjDropdownMenuSeparator]',
+  standalone: true,
+  hostDirectives: [KjListSeparator],
+  host: {
+    'class': 'kj-dropdown-menu-separator',
+    'tabindex': '-1',
+  },
+})
+export class KjDropdownMenuSeparator {}

package/src/dropdown-menu/dropdown-menu-trigger.ts

@@ -0,0 +1,140 @@
+import {
+  Directive,
+  ElementRef,
+  InjectionToken,
+  booleanAttribute,
+  inject,
+  input,
+  output,
+  signal,
+  type Signal,
+} from '@angular/core';
+import { KjOverlayTrigger } from '../primitives/overlay/trigger';
+import type { KjOverlayPanel } from '../primitives/overlay/panel';
+import { KjOverlayController } from '../primitives/overlay/controller';
+import {
+  KJ_OVERLAY_TRIGGER_EVENT_STRATEGY,
+  KJ_OVERLAY_PANEL_ROLE,
+} from '../primitives/overlay/tokens';
+import { onClick } from '../primitives/overlay/strategies/trigger-event/on-click';
+import { onContextMenu } from '../primitives/overlay/strategies/trigger-event/on-context-menu';
+
+/** Trigger event mode. `'click'` (default) or `'contextmenu'` (right-click / long-press). */
+export type KjDropdownMenuTriggerKind = 'click' | 'contextmenu';
+
+/** How and where the panel mounts: portal (default), at a point, or inline (in-place). */
+export type KjDropdownMenuMount = 'portal' | 'point' | 'inline';
+
+/** Reason a dropdown menu close was requested. */
+export type KjDropdownMenuCloseReason =
+  | 'item'
+  | 'escape'
+  | 'tab'
+  | 'click-outside'
+  | 'programmatic';
+
+/**
+ * Minimal context surface consumed by item-level directives
+ * (`KjDropdownMenuItem`, etc.). The trigger directive provides this token.
+ */
+export interface KjDropdownMenuContext {
+  readonly closeOnSelect: Signal<boolean>;
+  hide(reason: KjDropdownMenuCloseReason): void;
+}
+
+/** DI token for the dropdown menu shared context (item-level). */
+export const KJ_DROPDOWN_MENU = new InjectionToken<KjDropdownMenuContext>(
+  'KjDropdownMenu',
+);
+
+let _labelIdCounter = 0;
+/** Allocate a stable label id for `aria-labelledby` wiring on a group. */
+export function nextDropdownMenuLabelId(): string {
+  return `kj-dropdown-menu-label-${++_labelIdCounter}`;
+}
+
+/**
+ * The button that opens a dropdown menu. Composes `KjOverlayTrigger`.
+ *
+ * `kjTrigger` switches between `onClick()` (default) and `onContextMenu()`
+ * (replacement for the old `KjContextMenuTrigger`). For `kjMount="point"`,
+ * the trigger captures the originating pointer coords into signals consumed
+ * by `pointAt()` in the content component.
+ *
+ * Wires `aria-haspopup="menu"`, `aria-expanded`, `aria-controls` via the
+ * underlying `KjOverlayTrigger` host directive.
+ *
+ * @doc-category Core/Overlay
+ */
+@Directive({
+  selector: '[kjDropdownMenuTrigger]',
+  exportAs: 'kjDropdownMenuTrigger',
+  standalone: true,
+  hostDirectives: [{ directive: KjOverlayTrigger, inputs: ['kjOpen'] }],
+  providers: [
+    KjOverlayController,
+    {
+      provide: KJ_OVERLAY_TRIGGER_EVENT_STRATEGY,
+      // MVP: resolve at construction. `contextmenu` consumers should set
+      // `kjTrigger="contextmenu"` declaratively at construction time.
+      useFactory: () => {
+        // Read input attribute on the host element synchronously to pick the
+        // strategy. Falls back to click.
+        const el = inject(ElementRef<HTMLElement>).nativeElement as HTMLElement;
+        const kind = el.getAttribute('kjTrigger') ?? el.getAttribute('kjtrigger');
+        return kind === 'contextmenu' ? onContextMenu({ longPressMs: 500 }) : onClick();
+      },
+    },
+    { provide: KJ_OVERLAY_PANEL_ROLE, useValue: 'menu' as const },
+    { provide: KJ_DROPDOWN_MENU, useExisting: KjDropdownMenuTrigger },
+  ],
+  host: {
+    '(click)': 'onPointer($event)',
+    '(contextmenu)': 'onPointer($event)',
+  },
+})
+export class KjDropdownMenuTrigger implements KjDropdownMenuContext {
+  /** Public — read by sibling `[kjFor]` panels. */
+  readonly controller = inject(KjOverlayController);
+
+  /** Trigger event kind. */
+  readonly kjTrigger = input<KjDropdownMenuTriggerKind>('click');
+
+  /** Mount mode for the content panel. */
+  readonly kjMount = input<KjDropdownMenuMount>('portal');
+
+  /** Suppresses opening entirely. */
+  readonly kjDisabled = input(false, { transform: booleanAttribute });
+
+  /** Whether item activation closes the menu by default. */
+  readonly kjCloseOnSelect = input(true, { transform: booleanAttribute });
+
+  /** Emitted when the menu closes, with the reason. */
+  readonly kjMenuClosed = output<KjDropdownMenuCloseReason>();
+
+  /** Captured pointer coordinates for `kjMount="point"`. */
+  readonly kjPointX = signal<number>(0);
+  readonly kjPointY = signal<number>(0);
+
+  /** Mirror exposed to item directives via `KJ_DROPDOWN_MENU`. */
+  readonly closeOnSelect = this.kjCloseOnSelect;
+
+  /** Capture pointer coords for point-mount; the strategy reads them. */
+  protected onPointer(e: MouseEvent): void {
+    if (this.kjMount() === 'point') {
+      this.kjPointX.set(e.clientX);
+      this.kjPointY.set(e.clientY);
+    }
+  }
+
+  /** Item-driven close (`KJ_DROPDOWN_MENU.hide`). */
+  hide(reason: KjDropdownMenuCloseReason): void {
+    this.controller.close('programmatic');
+    this.kjMenuClosed.emit(reason);
+  }
+
+  private readonly _overlayTrigger = inject(KjOverlayTrigger, { self: true });
+  attachPanel(panel: KjOverlayPanel): void {
+    this._overlayTrigger.attachPanel(panel);
+  }
+}