@kouji-ui/core 0.0.4 → 0.1.1

package/src/tree-select/tree-select-content.ts

@@ -0,0 +1,199 @@
+import {
+  ChangeDetectionStrategy,
+  Component,
+  ElementRef,
+  Injector,
+  ViewEncapsulation,
+  effect,
+  inject,
+  input,
+  signal,
+} from '@angular/core';
+import { KjOverlayPanel } from '../primitives/overlay/panel';
+import type { KjOverlayController } from '../primitives/overlay/controller';
+import {
+  KJ_OVERLAY_MOUNT_STRATEGY,
+  KJ_OVERLAY_POSITION_STRATEGY,
+  KJ_OVERLAY_PANEL_ROLE,
+} from '../primitives/overlay/tokens';
+import type { KjSide, KjAlign } from '../primitives/overlay/types';
+import { bodyPortal } from '../primitives/overlay/strategies/mount/body-portal';
+import { anchoredTo } from '../primitives/overlay/strategies/position/anchored-to';
+import {
+  KJ_LIST_FOCUS_MODE,
+  KjListNavigator,
+  type KjListFocusMode,
+} from '../primitives/list';
+import { KJ_TREE_SELECT } from './tree-select.context';
+
+// Token override below pins the focus mode to `'roving'` for descendant
+// `KjListItem`s. Defined at module scope so it can be referenced from
+// the `providers` array literal without a class capture.
+const ROVING_FOCUS_MODE = signal<KjListFocusMode>('roving');
+
+/**
+ * Tree panel container. Composes `KjOverlayPanel` for mount/position/role
+ * wiring (carries `role="tree"` from the panel role provider) and
+ * `KjListNavigator` for the generic Up/Down / Home/End / Enter / Space /
+ * type-ahead contract. The tree-specific ArrowLeft / ArrowRight keys
+ * remain handled here because they carry expand/collapse +
+ * parent/first-child semantics the generic navigator doesn't cover.
+ *
+ * Roving DOM focus is wired here (rather than via the navigator's own
+ * `kjFocusMode="roving"` mode) because Angular's `hostDirectives.inputs`
+ * surface can only rename inputs — it can't push a static default into a
+ * composed input signal. Instead this component (1) overrides the
+ * `KJ_LIST_FOCUS_MODE` provider so child `KjListItem`s flip their
+ * `tabindex` correctly, and (2) drives the active-item DOM focus via a
+ * local effect on `KjListNavigator.activeId()`. The navigator itself
+ * continues to run its keyboard / type-ahead state machine unchanged.
+ *
+ * @doc-category Core/Inputs
+ */
+@Component({
+  selector: 'kj-tree-select-content',
+  standalone: true,
+  hostDirectives: [
+    { directive: KjOverlayPanel, inputs: ['kjFor'] },
+    KjListNavigator,
+  ],
+  providers: [
+    { provide: KJ_OVERLAY_PANEL_ROLE, useValue: 'tree' as const },
+    { provide: KJ_OVERLAY_MOUNT_STRATEGY, useFactory: () => bodyPortal() },
+    { provide: KJ_OVERLAY_POSITION_STRATEGY, useFactory: () => anchoredTo() },
+    // Pin items' focus model to `'roving'` (per WAI-ARIA APG tree). This
+    // overrides the provider the navigator registers (which mirrors the
+    // navigator's own `kjFocusMode` signal). The navigator's internal
+    // seed / focus effects are skipped — both are driven here instead.
+    { provide: KJ_LIST_FOCUS_MODE, useValue: ROVING_FOCUS_MODE },
+  ],
+  host: {
+    '[attr.aria-multiselectable]':
+      'ctx?.selectionMode() === "multiple" ? "true" : null',
+    '(keydown)': 'onKeydown($event)',
+    '(document:keydown.escape)': 'controller?.close("esc")',
+    '(document:click)': 'onDocClick($event)',
+    '(click)': '$event.stopPropagation()',
+  },
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  encapsulation: ViewEncapsulation.None,
+  template: `<ng-content />`,
+})
+export class KjTreeSelectContent {
+  private readonly el = inject(ElementRef<HTMLElement>);
+  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;
+  }
+  /** @internal */
+  get controller(): KjOverlayController | null {
+    return this._panel?.controller ?? null;
+  }
+  /** @internal */
+  readonly ctx = inject(KJ_TREE_SELECT, { optional: true });
+  // The composed `KjListNavigator` owns the generic Up/Down/Home/End/
+  // Enter/Space/type-ahead contract. We read its `activeItem()` below to
+  // anchor ArrowLeft / ArrowRight off the currently focused tree node
+  // and to follow the active id with DOM focus (roving model).
+  private readonly nav = inject(KjListNavigator);
+
+  readonly kjSide = input<KjSide>('bottom');
+  readonly kjAlign = input<KjAlign>('start');
+  readonly kjOffset = input<number, unknown>(4, {
+    transform: v => Number(v) || 4,
+  });
+
+  constructor() {
+    const pos = inject(KJ_OVERLAY_POSITION_STRATEGY) as ReturnType<typeof anchoredTo>;
+    pos.configure({ side: this.kjSide, align: this.kjAlign, offset: this.kjOffset, matchTriggerWidth: 'min' });
+
+    // Roving focus follow: mirror the navigator's `activeId` to DOM
+    // focus. Equivalent to `KjListNavigator`'s internal focus effect,
+    // re-implemented here because the navigator's effect is gated on
+    // `kjFocusMode() === 'roving'` and we can't statically push that
+    // value into a hostDirective input signal.
+    effect(() => {
+      const item = this.nav.activeItem();
+      if (!item) return;
+      const host = item._host();
+      if (host && document.activeElement !== host) host.focus();
+    });
+  }
+
+  /** @internal */
+  onDocClick(event: MouseEvent): void {
+    const ctrl = this.controller;
+    if (!ctrl?.isOpen()) return;
+    const target = event.target as Node | null;
+    if (!target) return;
+    if (this.el.nativeElement.contains(target)) return;
+    const trigger = ctrl.triggerEl();
+    if (trigger && trigger.contains(target)) return;
+    ctrl.close('outside');
+  }
+
+  /**
+   * Tree-specific ArrowLeft / ArrowRight handling. Up/Down/Home/End/
+   * Enter/Space/type-ahead all flow through the composed
+   * `KjListNavigator` — they aren't reimplemented here.
+   *
+   * - ArrowRight on a collapsed branch → expand (toggle).
+   * - ArrowRight on an expanded branch → move active to first child.
+   * - ArrowLeft on an expanded branch → collapse (toggle).
+   * - ArrowLeft elsewhere → move active to the parent (prior item with
+   *   `aria-level` less than current).
+   *
+   * @internal
+   */
+  onKeydown(event: KeyboardEvent): void {
+    if (event.key !== 'ArrowLeft' && event.key !== 'ArrowRight') return;
+    const active = this.nav.activeItem();
+    if (!active) return;
+    const node = active._host();
+    const items = this._domNodes();
+    const idx = items.indexOf(node);
+    if (idx === -1) return;
+    const hasChildren = node.getAttribute('data-has-children') === 'true';
+    const expanded = node.getAttribute('data-expanded') === 'true';
+
+    if (event.key === 'ArrowRight') {
+      event.preventDefault();
+      if (hasChildren && !expanded) {
+        const toggle = node.querySelector('[kjTreeSelectToggle]') as HTMLElement | null;
+        toggle?.click();
+      } else if (hasChildren && expanded) {
+        const next = items[idx + 1];
+        if (next) this.nav.setActive(next.id);
+      }
+      return;
+    }
+
+    // ArrowLeft
+    event.preventDefault();
+    if (hasChildren && expanded) {
+      const toggle = node.querySelector('[kjTreeSelectToggle]') as HTMLElement | null;
+      toggle?.click();
+      return;
+    }
+    const currentLevel = parseInt(node.getAttribute('aria-level') ?? '1', 10);
+    for (let i = idx - 1; i >= 0; i--) {
+      const lvl = parseInt(items[i]?.getAttribute('aria-level') ?? '1', 10);
+      if (lvl < currentLevel) {
+        this.nav.setActive(items[i].id);
+        break;
+      }
+    }
+  }
+
+  /** DOM-order list of tree nodes scoped to this panel. */
+  private _domNodes(): HTMLElement[] {
+    return Array.from(
+      this.el.nativeElement.querySelectorAll('[kjTreeSelectNode]'),
+    ) as HTMLElement[];
+  }
+}
+

package/src/tree-select/tree-select-node.ts

@@ -0,0 +1,132 @@
+import {
+  booleanAttribute,
+  computed,
+  Directive,
+  inject,
+  input,
+} from '@angular/core';
+import { KjListItem, injectListItem } from '../primitives/list';
+import { KJ_TREE_SELECT } from './tree-select.context';
+
+/**
+ * Individual tree node (treeitem). Composes `KjListItem` via
+ * `hostDirectives` — the list item owns the stable id, the
+ * click/Enter/Space activation, the `aria-selected` / `aria-disabled`
+ * bindings, and the shared `KjSelectionModel` toggle. This directive
+ * contributes only tree-specific semantics: `role="treeitem"`,
+ * `aria-level` / `aria-setsize` / `aria-posinset` from the parent's
+ * derived metadata, `aria-expanded` from the tree context's
+ * expanded-id set, and the `data-*` styling hooks.
+ *
+ * @example
+ * ```html
+ * <div
+ *   kjTreeSelectNode
+ *   [kjValue]="node.value"
+ *   [kjLabel]="node.label"
+ *   [kjNodeLevel]="1"
+ *   [kjHasChildren]="true"
+ * >
+ *   <button kjTreeSelectToggle>▶</button>
+ *   <span>{{ node.label }}</span>
+ * </div>
+ * ```
+ * @doc-category Core/Inputs
+ * @doc
+ * @doc-name tree-select
+ * @doc-description Renders one tree node with accessible treeitem semantics; selection + activation owned by the composed KjListItem.
+ */
+@Directive({
+  selector: '[kjTreeSelectNode]',
+  standalone: true,
+  exportAs: 'kjTreeSelectNode',
+  hostDirectives: [
+    {
+      directive: KjListItem,
+      inputs: [
+        'kjItemValue:kjValue',
+        'kjItemLabel:kjLabel',
+        'kjDisabled:kjDisabled',
+      ],
+    },
+  ],
+  host: {
+    'class': 'kj-tree-select-node',
+    'role': 'treeitem',
+    '[attr.aria-level]':        'kjNodeLevel()',
+    '[attr.aria-setsize]':      'kjNodeSize()',
+    '[attr.aria-posinset]':     'kjNodePos()',
+    '[attr.aria-expanded]':     'kjHasChildren() ? (isExpanded() ? "true" : "false") : null',
+    '[attr.data-expanded]':     'isExpanded() ? "true" : "false"',
+    '[attr.data-has-children]': 'kjHasChildren() ? "true" : "false"',
+    // `aria-selected` is owned by the composed `KjListItem` (it binds
+    // off the shared `KjSelectionModel`). We surface it as a
+    // `data-selected` styling hook here so consumer CSS doesn't have to
+    // care that the source of truth is one directive layer down.
+    '[attr.data-selected]': 'item.ariaSelected() === "true" ? "" : null',
+  },
+})
+export class KjTreeSelectNode {
+  /** Nesting depth (1-based). Maps to `aria-level`. */
+  readonly kjNodeLevel   = input<number>(1);
+  /** Number of sibling nodes at the same level. Maps to `aria-setsize`. */
+  readonly kjNodeSize    = input<number>(1);
+  /** 1-based position among siblings. Maps to `aria-posinset`. */
+  readonly kjNodePos     = input<number>(1);
+  /** Whether this node has child nodes (branch vs. leaf). */
+  readonly kjHasChildren = input(false, { transform: booleanAttribute });
+
+  private readonly ctx = inject(KJ_TREE_SELECT);
+  /** @internal — composed list-item primitive providing id/value/disabled/activation. */
+  readonly item = injectListItem<unknown>();
+
+  /** Stable id minted by the composed `KjListItem` (used by toggle + aria refs). */
+  get id(): string { return this.item.id; }
+  /** Current value carried by this node (from the composed `KjListItem`). */
+  get value(): unknown { return this.item.value(); }
+  /** Whether this node is disabled (delegated to the composed `KjListItem`). */
+  readonly disabled   = this.item.disabled;
+  /** Whether the node is currently expanded (reactive computed from context). */
+  readonly isExpanded = computed(() => this.ctx.isExpanded(this.id));
+}
+
+/**
+ * Expand/collapse toggle button inside a `KjTreeSelectNode`. Intercepts
+ * clicks before they bubble to the node (preventing accidental
+ * activation through the composed `KjListItem`) and toggles the
+ * tree-context expansion state by both the node's id and its value.
+ * Only meaningful on branch nodes (`[kjHasChildren]="true"`).
+ *
+ * Carries `aria-label` that reflects the current state.
+ *
+ * @example
+ * ```html
+ * <button kjTreeSelectToggle aria-hidden="true"></button>
+ * ```
+ * @doc-category Core/Inputs
+ */
+@Directive({
+  selector: '[kjTreeSelectToggle]',
+  standalone: true,
+  host: {
+    '[attr.aria-label]': 'isExpanded() ? "Collapse" : "Expand"',
+    '[attr.data-expanded]': 'isExpanded() ? "true" : "false"',
+    '(click)': 'handleClick($event)',
+  },
+})
+export class KjTreeSelectToggle {
+  private readonly ctx = inject(KJ_TREE_SELECT);
+  /** @internal — parent node context */
+  private readonly node = inject(KjTreeSelectNode);
+
+  /** Whether the parent node is currently expanded (reactive computed). */
+  readonly isExpanded = this.node.isExpanded;
+
+  /** @internal */
+  handleClick(event: Event): void {
+    event.stopPropagation();
+    if (this.node.disabled()) return;
+    this.ctx.toggleNode(this.node.id);
+    this.ctx.toggleNodeByValue(this.node.value);
+  }
+}

package/src/tree-select/tree-select-root.ts

@@ -0,0 +1,272 @@
+import {
+  computed,
+  contentChildren,
+  Directive,
+  effect,
+  forwardRef,
+  inject,
+  input,
+  model,
+  output,
+  signal,
+  untracked,
+  type Signal,
+  type WritableSignal,
+} from '@angular/core';
+import { KjOverlayController } from '../primitives/overlay/controller';
+import {
+  KJ_LIST_NAVIGATOR_CONFIG,
+  KjListItem,
+  KjSelectionModel,
+  type KjCompareFn,
+  type KjListNavigatorConfig,
+  type KjListSelectionMode,
+  type KjTreeShape,
+} from '../primitives/list';
+import { KJ_TREE_SELECT, type KjTreeNode, type KjTreeSelectContext } from './tree-select.context';
+
+let _treeSelectIdCounter = 0;
+
+function setsEqual(a: ReadonlySet<unknown>, b: ReadonlySet<unknown>): boolean {
+  if (a.size !== b.size) return false;
+  for (const v of a) if (!b.has(v)) return false;
+  return true;
+}
+
+/**
+ * Root Tree Select container. Owns selection model, expanded node state,
+ * and the shared `KjOverlayController` so the trigger, content, and
+ * individual nodes all wire to the same overlay state.
+ *
+ * Mirrors the `[kjSelect]` pattern: umbrella root holds context +
+ * controller; leaf directives read from it via DI.
+ *
+ * Supports two selection modes:
+ * - `'single'` (default) — selecting a node writes that value and closes the panel.
+ * - `'multiple'` — selecting toggles the value in the selection set; the panel
+ *   stays open.
+ *
+ * Implements {@link KjListNavigatorConfig}: descendants (`KjListNavigator`,
+ * `KjSelectionModel`) read the canonical `value`, `mode`, `compareBy`, and
+ * optional `treeShape` from the same root via `KJ_LIST_NAVIGATOR_CONFIG`.
+ * The legacy {@link KjTreeSelectContext} surface is preserved as a thin
+ * delegate so existing node/toggle directives keep working.
+ *
+ * @example
+ * ```html
+ * <div kjTreeSelect [(kjValue)]="selected" [kjNodes]="categories">
+ *   <button kjTreeSelectTrigger #t="kjTreeSelectTrigger">Select category</button>
+ *   <kj-tree-select-content [kjFor]="t"></kj-tree-select-content>
+ * </div>
+ * ```
+ * @doc-category Core/Inputs
+ * @doc
+ * @doc-name tree-select
+ * @doc-is-main
+ * @doc-description Unstyled tree-select root that holds the selection model and shares state with trigger, content, and nodes.
+ */
+@Directive({
+  selector: '[kjTreeSelect]',
+  standalone: true,
+  providers: [
+    { provide: KJ_TREE_SELECT, useExisting: KjTreeSelect },
+    { provide: KJ_LIST_NAVIGATOR_CONFIG, useExisting: forwardRef(() => KjTreeSelect) },
+    KjSelectionModel,
+    KjOverlayController,
+  ],
+})
+export class KjTreeSelect implements KjListNavigatorConfig, KjTreeSelectContext {
+  // Note: selection state (current value, isSelected membership) lives
+  // on the shared `KjSelectionModel` injected by `KjListItem`. The
+  // tree-select context here only owns tree-specific surface:
+  // expansion, the node-data signal, and the public `selectionMode`
+  // input name. Programmatic selection routes through the same
+  // `kjValue` signal that the selection model writes to — see
+  // `afterSelect` below.
+  /** @internal — shared overlay controller; trigger + content + nodes all see this same instance. */
+  private readonly controller = inject(KjOverlayController);
+
+  /** Tree node data. Each node may carry children, forming a hierarchy. */
+  readonly kjNodes = input<readonly KjTreeNode[]>([]);
+
+  /** Selection mode: `'single'` closes the panel on select; `'multiple'` toggles. */
+  readonly kjSelectionMode = input<'single' | 'multiple'>('single');
+
+  /**
+   * Two-way model for the selected value(s). In `'single'` mode this holds
+   * one value (or `undefined`); in `'multiple'` mode it holds an array.
+   */
+  readonly kjValue = model<unknown>(undefined);
+
+  /**
+   * Optional tree topology used by `KjSelectionModel` in `'leaf'` /
+   * `'cascade'` selection modes. Exposed as a signal so the model can
+   * follow it reactively without `KjTreeSelect` having to inject the
+   * model (that would re-introduce the NG0200 cycle).
+   */
+  readonly kjTreeShape = input<KjTreeShape<unknown> | null>(null);
+
+  /** Set of node IDs that are currently expanded (two-way bindable). */
+  readonly kjExpandedKeys = model<readonly unknown[]>([]);
+
+  /** Emitted when a node is selected. */
+  readonly kjNodeSelect = output<unknown>();
+
+  /** Emitted when a node branch is expanded. */
+  readonly kjNodeExpand = output<unknown>();
+
+  /** Emitted when a node branch is collapsed. */
+  readonly kjNodeCollapse = output<unknown>();
+
+  /** Stable panel id used for `aria-controls`. */
+  readonly panelId = `kj-tree-select-panel-${++_treeSelectIdCounter}`;
+
+  private readonly _expandedIds = signal<Set<string>>(new Set());
+  private readonly _expandedValues = signal<Set<unknown>>(new Set());
+
+  // ── KjListNavigatorConfig implementation ────────────────────────────
+
+  /**
+   * Items contributed by `KjListItem` instances under this root. Empty
+   * until node-level wiring lands (Task 3 of the migration plan); kept
+   * here now so the config contract is satisfied today.
+   */
+  readonly items = contentChildren(KjListItem, { descendants: true });
+
+  /**
+   * Single canonical value signal. Shared with the legacy `kjValue`
+   * model — `KjSelectionModel` reads / writes through this signal.
+   */
+  readonly value = this.kjValue as unknown as WritableSignal<
+    unknown | readonly unknown[] | null
+  >;
+
+  /**
+   * `KjListSelectionMode` view of {@link kjSelectionMode}:
+   * - `'single'` → `'single'` (one value, closes panel)
+   * - `'multiple'` → `'cascade'` (tri-state tree selection: toggling a
+   *   parent selects/deselects every leaf descendant; parent renders
+   *   `aria-checked="mixed"` when only some descendants are selected).
+   *
+   * Cascade mode requires a tree shape; {@link treeShape} falls back to
+   * a shape auto-derived from {@link kjNodes} when the consumer does
+   * not supply one.
+   */
+  readonly mode: Signal<KjListSelectionMode> = computed(() =>
+    this.kjSelectionMode() === 'multiple' ? 'cascade' : 'single',
+  );
+
+  /** Equality fn used by `KjSelectionModel`. Defaults to `Object.is`. */
+  readonly compareBy = signal<KjCompareFn<unknown>>(Object.is as KjCompareFn<unknown>);
+
+  /**
+   * Effective tree topology. Consumer-supplied `kjTreeShape` takes
+   * precedence; otherwise an auto-built shape is derived from the
+   * `kjNodes` input so cascade mode works out of the box for the
+   * canonical data-driven usage.
+   */
+  readonly treeShape = computed<KjTreeShape<unknown> | null>(() =>
+    this.kjTreeShape() ?? this._nodeShape(),
+  );
+
+  /**
+   * @internal Tree shape built from the `kjNodes` data structure. Walks
+   * each branch once to populate parent / children / leaf maps keyed by
+   * `node.value`.
+   */
+  private readonly _nodeShape = computed<KjTreeShape<unknown> | null>(() => {
+    const roots = this.kjNodes();
+    if (roots.length === 0) return null;
+    const parentOf = new Map<unknown, unknown | null>();
+    const childrenOf = new Map<unknown, unknown[]>();
+    const walk = (node: KjTreeNode, parent: unknown | null): void => {
+      parentOf.set(node.value, parent);
+      const kids = node.children ?? [];
+      childrenOf.set(node.value, kids.map(c => c.value));
+      for (const c of kids) walk(c, node.value);
+    };
+    for (const r of roots) walk(r, null);
+    return {
+      getParent:  (n) => parentOf.get(n) ?? null,
+      getChildren:(n) => childrenOf.get(n) ?? [],
+      isLeaf:     (n) => (childrenOf.get(n)?.length ?? 0) === 0,
+    };
+  });
+
+  /**
+   * Hook called by `KjListItem` after it toggles the shared selection
+   * model. Re-emits the public `kjNodeSelect` output so consumers see
+   * the same notification they saw before the migration (the legacy
+   * per-node `handleClick` emitted it; activation now happens inside
+   * `KjListItem._activate`, so the root is the only place left to
+   * forward it). In single mode (the only mode that returns
+   * `closeRequested: true`) we then close the overlay; multi keeps the
+   * panel open.
+   */
+  afterSelect(value: unknown, closeRequested: boolean): void {
+    if (value !== undefined) this.kjNodeSelect.emit(value);
+    if (closeRequested) this.controller.close('programmatic');
+  }
+
+  // ── KjTreeSelectContext implementation ──────────────────────────────
+
+  readonly selectionMode = computed(() => this.kjSelectionMode());
+  readonly expandedIds = computed(() =>
+    new Set(this._expandedIds()) as ReadonlySet<string>,
+  );
+  readonly expandedValues = computed(() =>
+    new Set(this._expandedValues()) as ReadonlySet<unknown>,
+  );
+  readonly nodes = computed(() => this.kjNodes());
+
+  /** Directly-injected selection model; wired via `bind()` below. */
+  private readonly _selection = inject(KjSelectionModel);
+
+  constructor() {
+    this._selection.bind({
+      value:     this.value,
+      items:     this.items,
+      mode:      this.mode,
+      compareBy: this.compareBy,
+      treeShape: this.treeShape,
+    });
+
+    // Sync kjExpandedKeys (controlled input) → _expandedValues
+    effect(() => {
+      const keys = this.kjExpandedKeys();
+      const next = new Set(keys);
+      const current = untracked(this._expandedValues);
+      if (!setsEqual(current, next)) {
+        this._expandedValues.set(next);
+      }
+    });
+  }
+
+  // ── Expansion ops ────────────────────────────────────────────────────
+
+  toggleNode(nodeId: string): void {
+    const set = new Set(this._expandedIds());
+    if (set.has(nodeId)) set.delete(nodeId);
+    else set.add(nodeId);
+    this._expandedIds.set(set);
+  }
+
+  toggleNodeByValue(value: unknown): void {
+    const set = new Set(this._expandedValues());
+    const wasExpanded = set.has(value);
+    if (wasExpanded) set.delete(value);
+    else set.add(value);
+    this._expandedValues.set(set);
+    this.kjExpandedKeys.set(Array.from(set));
+    if (wasExpanded) this.kjNodeCollapse.emit(value);
+    else this.kjNodeExpand.emit(value);
+  }
+
+  isExpanded(nodeId: string): boolean {
+    return this._expandedIds().has(nodeId);
+  }
+
+  isValueExpanded(value: unknown): boolean {
+    return this._expandedValues().has(value);
+  }
+}

package/src/tree-select/tree-select-trigger.ts

@@ -0,0 +1,90 @@
+import { Directive, booleanAttribute, inject, input } from '@angular/core';
+import { KjFocusRing } from '../primitives';
+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,
+  type KjTriggerEventStrategy,
+} from '../primitives/overlay/tokens';
+import { onClick } from '../primitives/overlay/strategies/trigger-event/on-click';
+
+/**
+ * Wraps `onClick()` and forces `ariaHasPopup` to `'tree'` so the trigger
+ * advertises its panel role to assistive tech.
+ */
+function treeClickTrigger(): KjTriggerEventStrategy {
+  const inner = onClick();
+  return {
+    ariaHasPopup: 'tree',
+    attach: c => inner.attach(c),
+    bindToggle: t => inner.bindToggle(t),
+    onOpen: () => inner.onOpen?.(),
+    onClose: () => inner.onClose?.(),
+    detach: () => inner.detach(),
+  };
+}
+
+/**
+ * Trigger button that opens/closes the Tree Select panel. Composes the
+ * overlay `KjOverlayTrigger` host directive (which wires `aria-expanded`,
+ * `aria-controls`, `aria-haspopup`, and click handling) and forces
+ * `role="combobox"` on the host element.
+ *
+ * @example
+ * ```html
+ * <button kjTreeSelectTrigger>Select category</button>
+ * ```
+ * @doc-category Core/Inputs
+ */
+@Directive({
+  selector: '[kjTreeSelectTrigger]',
+  exportAs: 'kjTreeSelectTrigger',
+  standalone: true,
+  hostDirectives: [
+    KjFocusRing,
+    { directive: KjOverlayTrigger, inputs: ['kjOpen'] },
+  ],
+  providers: [
+    {
+      provide: KJ_OVERLAY_TRIGGER_EVENT_STRATEGY,
+      useFactory: () => treeClickTrigger(),
+    },
+    { provide: KJ_OVERLAY_PANEL_ROLE, useValue: 'tree' as const },
+  ],
+  host: {
+    'role': 'combobox',
+    '(keydown)': 'onKeydown($event)',
+  },
+})
+export class KjTreeSelectTrigger {
+  /** @internal */
+  readonly controller = inject(KjOverlayController);
+
+  /** Disabled state. */
+  readonly kjDisabled = input(false, { transform: booleanAttribute });
+
+  /** @internal */
+  onKeydown(event: KeyboardEvent): void {
+    switch (event.key) {
+      case 'ArrowDown':
+      case ' ':
+      case 'Enter':
+        event.preventDefault();
+        if (!this.controller.isOpen()) this.controller.open();
+        break;
+      case 'Escape':
+        if (this.controller.isOpen()) {
+          event.preventDefault();
+          this.controller.close('programmatic');
+        }
+        break;
+    }
+  }
+
+  private readonly _overlayTrigger = inject(KjOverlayTrigger, { self: true });
+  attachPanel(panel: KjOverlayPanel): void {
+    this._overlayTrigger.attachPanel(panel);
+  }
+}