@kouji-ui/components 0.1.1

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

@@ -0,0 +1,16 @@
+import { Component, ChangeDetectionStrategy } from '@angular/core';
+import { KjTooltipTrigger, KjTooltipContent } from '@kouji-ui/core';
+import { KjButtonComponent } from '../../button/button';
+
+// TODO(wrapper-overlay): re-skin via styled wrapper layer.
+@Component({
+  selector: 'kj-tooltip-example',
+  standalone: true,
+  imports: [KjTooltipTrigger, KjTooltipContent, KjButtonComponent],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: `
+    <kj-button kjTooltipTrigger #t="kjTooltipTrigger">Hover me</kj-button>
+    <kj-tooltip-content [kjFor]="t">Save the document</kj-tooltip-content>
+  `,
+})
+export class KjTooltipExample {}

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

@@ -0,0 +1,20 @@
+import { Component, ChangeDetectionStrategy } from '@angular/core';
+import { KjTooltipTrigger, KjTooltipContent, KjTooltipGroup } from '@kouji-ui/core';
+import { KjButtonComponent } from '../../button/button';
+
+// TODO(wrapper-overlay): re-skin tooltip group demo.
+@Component({
+  selector: 'kj-tooltip-group-example',
+  standalone: true,
+  imports: [KjTooltipTrigger, KjTooltipContent, KjTooltipGroup, KjButtonComponent],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: `
+    <div kjTooltipGroup>
+      <kj-button kjTooltipTrigger #a="kjTooltipTrigger">A</kj-button>
+      <kj-tooltip-content [kjFor]="a">Tip A</kj-tooltip-content>
+      <kj-button kjTooltipTrigger #b="kjTooltipTrigger">B</kj-button>
+      <kj-tooltip-content [kjFor]="b">Tip B</kj-tooltip-content>
+    </div>
+  `,
+})
+export class KjTooltipGroupExample {}

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

@@ -0,0 +1,19 @@
+import { Component, ChangeDetectionStrategy } from '@angular/core';
+import { KjTooltipTrigger, KjTooltipContent, KjTooltipArrow } from '@kouji-ui/core';
+import { KjButtonComponent } from '../../button/button';
+
+// TODO(wrapper-overlay): re-skin rich tooltip demo.
+@Component({
+  selector: 'kj-tooltip-rich-example',
+  standalone: true,
+  imports: [KjTooltipTrigger, KjTooltipContent, KjTooltipArrow, KjButtonComponent],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: `
+    <kj-button kjTooltipTrigger #t="kjTooltipTrigger">Save</kj-button>
+    <kj-tooltip-content [kjFor]="t">
+      <strong>Save</strong>
+      <span kjTooltipArrow></span>
+    </kj-tooltip-content>
+  `,
+})
+export class KjTooltipRichExample {}

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

@@ -0,0 +1,18 @@
+import { Component, ChangeDetectionStrategy } from '@angular/core';
+import { KjTooltipTrigger, KjTooltipContent } from '@kouji-ui/core';
+import { KjButtonComponent } from '../../button/button';
+
+// TODO(wrapper-overlay): re-skin sides demo.
+@Component({
+  selector: 'kj-tooltip-sides-example',
+  standalone: true,
+  imports: [KjTooltipTrigger, KjTooltipContent, KjButtonComponent],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: `
+    <kj-button kjTooltipTrigger #top="kjTooltipTrigger">Top</kj-button>
+    <kj-tooltip-content [kjFor]="top" kjSide="top">Top</kj-tooltip-content>
+    <kj-button kjTooltipTrigger #bottom="kjTooltipTrigger">Bottom</kj-button>
+    <kj-tooltip-content [kjFor]="bottom" kjSide="bottom">Bottom</kj-tooltip-content>
+  `,
+})
+export class KjTooltipSidesExample {}

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

@@ -0,0 +1,50 @@
+import { Component, ChangeDetectionStrategy } from '@angular/core';
+import { KjTooltipTrigger, KjTooltipContent } from '@kouji-ui/core';
+import { KjButtonComponent } from '../../button/button';
+
+/**
+ * A walkthrough of the most common tooltip usages — default placement, an
+ * explicit side, a slower delay for verbose copy, and a rich body with a
+ * heading and supporting text. Use this as the copy-paste starting point.
+ */
+@Component({
+  selector: 'kj-tooltip-usage-example',
+  standalone: true,
+  imports: [KjTooltipTrigger, KjTooltipContent, KjButtonComponent],
+  styles: [
+    `
+      :host {
+        display: flex;
+        gap: var(--kj-space-md);
+        flex-wrap: wrap;
+        align-items: center;
+        padding: var(--kj-space-2xl);
+      }
+      .rich {
+        display: flex;
+        flex-direction: column;
+        gap: var(--kj-space-2xs);
+      }
+      .rich strong {
+        font-weight: 600;
+      }
+    `,
+  ],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: `
+    <kj-button kjTooltipTrigger #saveTrig="kjTooltipTrigger">Save</kj-button>
+    <kj-tooltip-content [kjFor]="saveTrig">Save the document</kj-tooltip-content>
+
+    <kj-button kjTooltipTrigger #shipTrig="kjTooltipTrigger" kjSide="right">Ship</kj-button>
+    <kj-tooltip-content [kjFor]="shipTrig" kjSide="right">Deploy to production</kj-tooltip-content>
+
+    <kj-button kjTooltipTrigger #slowTrig="kjTooltipTrigger" [kjOpenDelay]="500">Help</kj-button>
+    <kj-tooltip-content [kjFor]="slowTrig">
+      <div class="rich">
+        <strong>Need a hand?</strong>
+        <span>Press ⌘K to open the command palette.</span>
+      </div>
+    </kj-tooltip-content>
+  `,
+})
+export class KjTooltipUsageExample {}

package/src/tooltip/index.ts

@@ -0,0 +1 @@
+export * from './tooltip';

package/src/tooltip/tooltip.css

@@ -0,0 +1,61 @@
+@layer kj.component {
+  /* The wrapper hosts use display: contents — they don't add a box. */
+
+  .kj-tooltip-content {
+    --kj-tooltip-bg:           var(--kj-fg-default);
+    --kj-tooltip-fg:           var(--kj-bg-body);
+    --kj-tooltip-border-color: transparent;
+    --kj-tooltip-radius:       var(--kj-radius-selector);
+    --kj-tooltip-padding-x:    var(--kj-space-md);
+    --kj-tooltip-padding-y:    var(--kj-space-xs);
+    --kj-tooltip-font-size:    0.8125rem;
+    --kj-tooltip-shadow:       var(--kj-shadow-md, 0 4px 12px rgb(0 0 0 / 0.18));
+    --kj-tooltip-arrow-size:   6px;
+
+    /* Layout — the directive applies position: fixed and writes top/left. */
+    display: inline-flex;
+    align-items: center;
+    gap: 0.375rem;
+    max-width: min(20rem, calc(100vw - 1rem));
+    background: var(--kj-tooltip-bg);
+    color: var(--kj-tooltip-fg);
+    border: var(--kj-border) solid var(--kj-tooltip-border-color);
+    border-radius: var(--kj-tooltip-radius);
+    padding: var(--kj-tooltip-padding-y) var(--kj-tooltip-padding-x);
+    font: var(--kj-tooltip-font-size) / 1.4 var(--kj-font-sans);
+    box-shadow: var(--kj-tooltip-shadow);
+    pointer-events: auto;
+    z-index: 1000;
+    word-wrap: break-word;
+  }
+
+  /* Closed: KjOverlayPanel sets `hidden` when state is closed — keep portaled panel out of layout.
+     Load this stylesheet globally when using KjTooltipTrigger + kj-tooltip-content from core
+     (see packages/core tooltip finance example; avoid duplicating `[hidden]` in app CSS). */
+  /* Must win over any app-level tooltip overrides (e.g. encapsulation + extra classes). */
+  .kj-tooltip-content[hidden] {
+    display: none !important;
+  }
+
+  /* Arrow positioning relative to the content's resolved data-side. */
+  .kj-tooltip-arrow {
+    position: absolute;
+    width: var(--kj-tooltip-arrow-size);
+    height: var(--kj-tooltip-arrow-size);
+    background: var(--kj-tooltip-bg);
+    transform: rotate(45deg);
+  }
+
+  .kj-tooltip-content[data-side="top"]    .kj-tooltip-arrow { bottom: calc(var(--kj-tooltip-arrow-size) / -2); left: 50%; margin-left: calc(var(--kj-tooltip-arrow-size) / -2); }
+  .kj-tooltip-content[data-side="bottom"] .kj-tooltip-arrow { top:    calc(var(--kj-tooltip-arrow-size) / -2); left: 50%; margin-left: calc(var(--kj-tooltip-arrow-size) / -2); }
+  .kj-tooltip-content[data-side="left"]   .kj-tooltip-arrow { right:  calc(var(--kj-tooltip-arrow-size) / -2); top:  50%; margin-top:  calc(var(--kj-tooltip-arrow-size) / -2); }
+  .kj-tooltip-content[data-side="right"]  .kj-tooltip-arrow { left:   calc(var(--kj-tooltip-arrow-size) / -2); top:  50%; margin-top:  calc(var(--kj-tooltip-arrow-size) / -2); }
+
+  @media (prefers-reduced-motion: no-preference) {
+    .kj-tooltip-content {
+      transition: opacity 120ms ease-out;
+    }
+    .kj-tooltip-content[data-state="closed"] { opacity: 0; }
+    .kj-tooltip-content[data-state="open"]   { opacity: 1; }
+  }
+}

package/src/tooltip/tooltip.playground.ts

@@ -0,0 +1,79 @@
+import { ChangeDetectionStrategy, Component, signal } from '@angular/core';
+import { KjTooltipTrigger, KjTooltipContent } from '@kouji-ui/core';
+import { KjButtonComponent } from '../button/button';
+import type { PlaygroundFile } from '@kouji-ui/components/playground-types';
+import type { KjSide, KjAlign } from '@kouji-ui/core';
+
+/**
+ * Playground state — module-scope signals. Tooltip wakes on hover/focus of
+ * the trigger; knobs control placement + delay + disabled state.
+ */
+const side = signal<KjSide>('top');
+const align = signal<KjAlign>('center');
+const openDelay = signal<200 | 0 | 500 | 1000>(200);
+const disabled = signal(false);
+const body = signal('Save the document');
+
+@Component({
+  selector: 'kj-tooltip-playground',
+  standalone: true,
+  imports: [KjButtonComponent, KjTooltipTrigger, KjTooltipContent],
+  styles: [`
+    :host { display: block; min-height: 6rem; }
+    .hint { margin-block-start: var(--kj-space-md); font: 0.8125rem var(--kj-font-sans); color: var(--kj-fg-muted); }
+  `],
+  template: `
+    <kj-button
+      kjTooltipTrigger
+      #t="kjTooltipTrigger"
+      [kjOpenDelay]="openDelay()"
+      [kjDisabled]="disabled()"
+    >Hover me</kj-button>
+    <kj-tooltip-content [kjFor]="t" [kjSide]="side()" [kjAlign]="align()">
+      {{ body() }}
+    </kj-tooltip-content>
+    <p class="hint">Tip: hover or focus the trigger to reveal the tooltip.</p>
+  `,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class KjTooltipPlaygroundDemo {
+  protected readonly side = side;
+  protected readonly align = align;
+  protected readonly openDelay = openDelay;
+  protected readonly disabled = disabled;
+  protected readonly body = body;
+}
+
+export const PLAYGROUND: PlaygroundFile = {
+  component: KjTooltipPlaygroundDemo,
+  state: {
+    side: side as unknown as ReturnType<typeof signal>,
+    align: align as unknown as ReturnType<typeof signal>,
+    openDelay: openDelay as unknown as ReturnType<typeof signal>,
+    disabled: disabled as unknown as ReturnType<typeof signal>,
+    body: body as unknown as ReturnType<typeof signal>,
+  },
+  controls: [
+    { kind: 'chips', name: 'side', label: 'side', options: ['top', 'right', 'bottom', 'left'] },
+    { kind: 'chips', name: 'align', label: 'align', options: ['start', 'center', 'end'] },
+    { kind: 'chips', name: 'openDelay', label: 'open delay', options: [0, 200, 500, 1000] },
+    { kind: 'toggle', name: 'disabled', label: 'disabled' },
+    { kind: 'text', name: 'body', label: 'content' },
+  ],
+  snippet: (values) => {
+    const s = values as {
+      side: string;
+      align: string;
+      openDelay: number;
+      disabled: boolean;
+      body: string;
+    };
+    const triggerAttrs: string[] = ['kjTooltipTrigger', '#t="kjTooltipTrigger"'];
+    if (s.openDelay !== 200) triggerAttrs.push(`[kjOpenDelay]="${s.openDelay}"`);
+    if (s.disabled) triggerAttrs.push('[kjDisabled]="true"');
+    const contentAttrs: string[] = ['[kjFor]="t"'];
+    if (s.side !== 'top') contentAttrs.push(`kjSide="${s.side}"`);
+    if (s.align !== 'center') contentAttrs.push(`kjAlign="${s.align}"`);
+    return `<kj-button\n  ${triggerAttrs.join('\n  ')}\n>Hover me</kj-button>\n<kj-tooltip-content\n  ${contentAttrs.join('\n  ')}\n>${s.body}</kj-tooltip-content>`;
+  },
+};

package/src/tooltip/tooltip.spec.ts

@@ -0,0 +1,5 @@
+import { describe, it } from 'vitest';
+
+describe('KjTooltip (wrapper)', () => {
+  it.todo('rewrite for new overlay API (KjTooltipTrigger / KjTooltipContent primitives)');
+});

package/src/tooltip/tooltip.ts

@@ -0,0 +1,102 @@
+import { ChangeDetectionStrategy, Component, ViewEncapsulation } from '@angular/core';
+import {
+  KjTooltipTrigger,
+  KjTooltipContent,
+  KjTooltipArrow,
+  KjTooltipGroup,
+} from '@kouji-ui/core';
+
+export {
+  KjTooltipTrigger,
+  KjTooltipContent,
+  KjTooltipArrow,
+  KjTooltipGroup,
+} from '@kouji-ui/core';
+
+/**
+ * Tooltip surface styles: `tooltip.css` in this folder. Apps that compose
+ * `KjTooltipTrigger` + `kj-tooltip-content` from `@kouji-ui/core` (without this
+ * wrapper) must load `packages/components/src/tooltip/tooltip.css` globally
+ * (see docs `angular.json` styles) so `.kj-tooltip-content[hidden]{display:none}`
+ * and theme tokens apply — same contract as the finance tooltip example.
+ *
+ * Hover/focus tooltip. Compose `[kjTooltipTrigger]` + `<kj-tooltip-content [kjFor]="t">`
+ * for declarative use. The wrapper itself renders only projected content — its
+ * purpose is to host the documentation tags for the tooltip suite.
+ *
+ * @doc
+ * @doc-name tooltip
+ * @doc-description Themed hover and focus tooltip with placement, delay, group, and rich-content options.
+ * @doc-is-main
+ * @doc-example Default
+ *   The default playground — a trigger and tooltip wired by template ref.
+ *   @doc-file tooltip.example.ts
+ * @doc-example Usage
+ *   A walkthrough of the most common tooltip usages — placement, custom delay,
+ *   and a small rich body with secondary info.
+ *   @doc-file tooltip.usage.example.ts
+ * @doc-example Sides
+ *   `kjSide` placement — `top` / `right` / `bottom` / `left`.
+ *   @doc-file tooltip.sides.example.ts
+ * @doc-example Delays
+ *   `[kjOpenDelay]` / `[kjCloseDelay]` tune the hover-intent thresholds.
+ *   @doc-file tooltip.delays.example.ts
+ * @doc-example Rich content
+ *   Project structured content with a heading + body inside the tooltip.
+ *   @doc-file tooltip.rich.example.ts
+ * @doc-example Disabled
+ *   `[kjDisabled]="true"` on the trigger suppresses the tooltip entirely.
+ *   @doc-file tooltip.disabled.example.ts
+ * @doc-example Grouped
+ *   `<kj-tooltip-group>` shares the open delay across nearby triggers, so the
+ *   second one opens instantly after the first.
+ *   @doc-file tooltip.group.example.ts
+ *
+ * @doc-keyboard
+ *   Tab     — Moves focus onto the trigger; opens the tooltip (no delay on focus)
+ *   Escape  — Closes the open tooltip without losing trigger focus
+ *   Shift+Tab — Moves focus away; closes the tooltip
+ *
+ * @doc-aria
+ *   role="tooltip"   — applied to `<kj-tooltip-content>` by the directive
+ *   aria-describedby — wired from the trigger to the content's id while open
+ *   data-state       — "open" | "closed" mirror for CSS targeting on the content
+ *   data-side        — Mirrors the resolved placement for theme/arrow hooks
+ *
+ * @doc-touch
+ *   Tooltips are pointer/keyboard-only by contract — touch shouldn't depend
+ *   on hover for information. Pair the trigger with a visible label or use
+ *   Popover instead when the content is essential on touch.
+ *
+ * @doc-a11y
+ *   Implements the WAI-ARIA Tooltip APG pattern via `aria-describedby` on the
+ *   trigger. Hover-intent timing prevents flicker on quick mouse movement.
+ *   Escape closes the tooltip per APG. Never put interactive controls inside
+ *   the tooltip — use Popover for that.
+ *
+ * @doc-related popover,dropdown-menu,kbd
+ *
+ * @doc-css-var
+ *   --kj-tooltip-bg            — Background fill of the content panel and arrow.
+ *   --kj-tooltip-fg            — Foreground (text) color of the content panel.
+ *   --kj-tooltip-border-color  — Border color of the content panel. Default transparent.
+ *   --kj-tooltip-radius        — Corner radius. Inherits --kj-radius-selector.
+ *   --kj-tooltip-padding-x     — Horizontal padding of the content panel.
+ *   --kj-tooltip-padding-y     — Vertical padding of the content panel.
+ *   --kj-tooltip-font-size     — Font size of the content text.
+ *   --kj-tooltip-shadow        — Elevation shadow on the content panel.
+ *   --kj-tooltip-arrow-size    — Edge length of the diamond arrow. Default 6px.
+ *
+ * @doc-category Library/Overlay
+ */
+@Component({
+  selector: 'kj-tooltip',
+  standalone: true,
+  imports: [KjTooltipTrigger, KjTooltipContent, KjTooltipArrow, KjTooltipGroup],
+  template: `<ng-content />`,
+  styleUrl: './tooltip.css',
+  encapsulation: ViewEncapsulation.None,
+  host: { style: 'display: contents;' },
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class KjTooltipComponent {}

package/src/tree-select/_examples/index.ts

@@ -0,0 +1,8 @@
+// AUTO-GENERATED by scripts/migrate-examples.mjs
+// One barrel per component folder — used by the docs app as a lazy chunk.
+export { KjTreeSelectDisabledExample } from './tree-select.disabled.example';
+export { KjTreeSelectExample } from './tree-select.example';
+export { KjTreeSelectExpandedExample } from './tree-select.expanded.example';
+export { KjTreeSelectFieldExample } from './tree-select.field.example';
+export { KjTreeSelectMultiExample } from './tree-select.multi.example';
+export { KjTreeSelectUsageExample } from './tree-select.usage.example';

package/src/tree-select/_examples/tree-select.disabled.example.ts

@@ -0,0 +1,106 @@
+import { Component, signal, ChangeDetectionStrategy } from '@angular/core';
+import { KjTreeSelectComponent } from '../tree-select';
+import type { KjTreeNode } from '@kouji-ui/core';
+
+/**
+ * Disabled state examples for tree select. The first select is entirely
+ * disabled (the trigger cannot be activated). The second select has individual
+ * nodes disabled — the "Legacy API" branch is disabled and cannot be selected.
+ */
+@Component({
+  selector: 'kj-tree-select-disabled-example',
+  standalone: true,
+  imports: [KjTreeSelectComponent],
+  styles: [
+    `
+      :host {
+        display: block;
+        display: flex;
+        flex-direction: column;
+        gap: var(--kj-space-lg);
+      }
+    `,
+    `
+      label {
+        font: 0.75rem var(--kj-font-sans);
+        color: var(--kj-fg-default);
+        opacity: 0.7;
+        margin-bottom: var(--kj-space-xs);
+        display: block;
+      }
+    `,
+  ],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: `
+    <div>
+      <label for="tree-select-disabled-all">Entirely disabled</label>
+      <kj-tree-select
+        id="tree-select-disabled-all"
+        [kjNodes]="categories"
+        [(kjValue)]="selected1"
+        disabled
+        placeholder="Disabled select"
+      />
+    </div>
+    <div>
+      <label for="tree-select-disabled-node">Individual node disabled</label>
+      <kj-tree-select
+        id="tree-select-disabled-node"
+        [kjNodes]="categoriesWithDisabled"
+        [(kjValue)]="selected2"
+        placeholder="Some nodes disabled"
+      />
+    </div>
+  `,
+})
+export class KjTreeSelectDisabledExample {
+  protected readonly selected1 = signal<string | undefined>(undefined);
+  protected readonly selected2 = signal<string | undefined>(undefined);
+
+  protected readonly categories: KjTreeNode<string>[] = [
+    {
+      value: 'api',
+      label: 'API',
+      children: [
+        { value: 'rest', label: 'REST' },
+        { value: 'graphql', label: 'GraphQL' },
+      ],
+    },
+    {
+      value: 'sdk',
+      label: 'SDK',
+      children: [
+        { value: 'js-sdk', label: 'JavaScript' },
+        { value: 'python-sdk', label: 'Python' },
+      ],
+    },
+  ];
+
+  protected readonly categoriesWithDisabled: KjTreeNode<string>[] = [
+    {
+      value: 'api-v2',
+      label: 'API v2',
+      children: [
+        { value: 'rest-v2', label: 'REST' },
+        { value: 'graphql-v2', label: 'GraphQL' },
+      ],
+    },
+    {
+      value: 'api-legacy',
+      label: 'Legacy API',
+      disabled: true,
+      children: [
+        { value: 'rest-v1', label: 'REST v1', disabled: true },
+        { value: 'soap', label: 'SOAP', disabled: true },
+      ],
+    },
+    {
+      value: 'sdk-v2',
+      label: 'SDK v2',
+      children: [
+        { value: 'js-sdk-v2', label: 'JavaScript' },
+        { value: 'python-sdk-v2', label: 'Python', disabled: true },
+      ],
+    },
+  ];
+}

package/src/tree-select/_examples/tree-select.example.ts

@@ -0,0 +1,65 @@
+import { Component, signal, ChangeDetectionStrategy } from '@angular/core';
+import { KjTreeSelectComponent } from '../tree-select';
+import type { KjTreeNode } from '@kouji-ui/core';
+
+/**
+ * Default tree select example with categories and subcategories.
+ * Click a category to expand it, then click a leaf to select it.
+ * The selected label is shown in the trigger button.
+ */
+@Component({
+  selector: 'kj-tree-select-example',
+  standalone: true,
+  imports: [KjTreeSelectComponent],
+  styles: [
+    `
+      :host {
+        display: block;
+      }
+    `,
+    `
+      p {
+        margin-top: var(--kj-space-md);
+        font: 0.875rem var(--kj-font-sans);
+        color: var(--kj-fg-default);
+      }
+    `,
+  ],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: `
+    <kj-tree-select [kjNodes]="categories" [(kjValue)]="selected" placeholder="Select a topic" />
+    <p>Selected: {{ selected() ?? 'none' }}</p>
+  `,
+})
+export class KjTreeSelectExample {
+  protected readonly selected = signal<string | undefined>(undefined);
+
+  protected readonly categories: KjTreeNode<string>[] = [
+    {
+      value: 'frontend',
+      label: 'Frontend',
+      children: [
+        { value: 'html', label: 'HTML' },
+        { value: 'css', label: 'CSS' },
+        { value: 'javascript', label: 'JavaScript' },
+      ],
+    },
+    {
+      value: 'backend',
+      label: 'Backend',
+      children: [
+        { value: 'nodejs', label: 'Node.js' },
+        { value: 'python', label: 'Python' },
+        { value: 'go', label: 'Go' },
+      ],
+    },
+    {
+      value: 'devops',
+      label: 'DevOps',
+      children: [
+        { value: 'docker', label: 'Docker' },
+        { value: 'kubernetes', label: 'Kubernetes' },
+      ],
+    },
+  ];
+}

package/src/tree-select/_examples/tree-select.expanded.example.ts

@@ -0,0 +1,72 @@
+import { Component, signal, ChangeDetectionStrategy } from '@angular/core';
+import { KjTreeSelectComponent } from '../tree-select';
+import type { KjTreeNode } from '@kouji-ui/core';
+
+/**
+ * Pre-expanded tree select. The `kjExpandedKeys` input controls which branches
+ * are initially expanded when the panel opens. Here "Animals" and "Plants" start
+ * open so their children are immediately visible.
+ */
+@Component({
+  selector: 'kj-tree-select-expanded-example',
+  standalone: true,
+  imports: [KjTreeSelectComponent],
+  styles: [
+    `
+      :host {
+        display: block;
+      }
+    `,
+    `
+      p {
+        margin-top: var(--kj-space-md);
+        font: 0.875rem var(--kj-font-sans);
+        color: var(--kj-fg-default);
+      }
+    `,
+  ],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: `
+    <kj-tree-select
+      [kjNodes]="organisms"
+      [(kjValue)]="selected"
+      [kjExpandedKeys]="expandedKeys()"
+      placeholder="Choose an organism"
+    />
+    <p>Selected: {{ selected() ?? 'none' }}</p>
+  `,
+})
+export class KjTreeSelectExpandedExample {
+  protected readonly selected = signal<string | undefined>(undefined);
+  /** Pre-expand "Animals" and "Plants" branches on load. */
+  protected readonly expandedKeys = signal<string[]>(['animals', 'plants']);
+
+  protected readonly organisms: KjTreeNode<string>[] = [
+    {
+      value: 'animals',
+      label: 'Animals',
+      children: [
+        { value: 'cat', label: 'Cat' },
+        { value: 'dog', label: 'Dog' },
+        { value: 'parrot', label: 'Parrot' },
+      ],
+    },
+    {
+      value: 'plants',
+      label: 'Plants',
+      children: [
+        { value: 'oak', label: 'Oak' },
+        { value: 'rose', label: 'Rose' },
+        { value: 'cactus', label: 'Cactus' },
+      ],
+    },
+    {
+      value: 'fungi',
+      label: 'Fungi',
+      children: [
+        { value: 'mushroom', label: 'Mushroom' },
+        { value: 'truffle', label: 'Truffle' },
+      ],
+    },
+  ];
+}