@kouji-ui/components 0.1.1

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

@@ -0,0 +1,77 @@
+import { Component, signal, ChangeDetectionStrategy } from '@angular/core';
+import { KjFieldComponent, KjFieldHelpComponent, KjFieldLabelComponent } from '../../field/field';
+import { KjTreeSelectComponent } from '../tree-select';
+import type { KjTreeNode } from '@kouji-ui/core';
+
+/**
+ * Tree select inside a `<kj-field>` wrapper that provides a label and hint
+ * text. The field label is associated to the trigger via the standard `kj-field`
+ * composition pattern.
+ */
+@Component({
+  selector: 'kj-tree-select-field-example',
+  standalone: true,
+  imports: [KjFieldComponent, KjFieldLabelComponent, KjFieldHelpComponent, KjTreeSelectComponent],
+  styles: [
+    `
+      :host {
+        display: block;
+        max-width: 400px;
+      }
+    `,
+    `
+      .kj-tree-select {
+        width: 100%;
+      }
+    `,
+  ],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: `
+    <kj-field>
+      <kj-field-label>Department</kj-field-label>
+      <kj-tree-select
+        [kjNodes]="departments"
+        [(kjValue)]="selected"
+        placeholder="Choose a department"
+        style="width: 100%"
+      />
+      <kj-field-help>Select the department this issue belongs to.</kj-field-help>
+    </kj-field>
+    @if (selected()) {
+      <p style="margin-top: var(--kj-space-md); font: 0.875rem var(--kj-font-sans);">
+        Selected: {{ selected() }}
+      </p>
+    }
+  `,
+})
+export class KjTreeSelectFieldExample {
+  protected readonly selected = signal<string | undefined>(undefined);
+
+  protected readonly departments: KjTreeNode<string>[] = [
+    {
+      value: 'engineering',
+      label: 'Engineering',
+      children: [
+        { value: 'frontend-team', label: 'Frontend' },
+        { value: 'backend-team', label: 'Backend' },
+        { value: 'platform-team', label: 'Platform' },
+      ],
+    },
+    {
+      value: 'product',
+      label: 'Product',
+      children: [
+        { value: 'ux', label: 'UX Design' },
+        { value: 'pm', label: 'Product Management' },
+      ],
+    },
+    {
+      value: 'operations',
+      label: 'Operations',
+      children: [
+        { value: 'hr', label: 'Human Resources' },
+        { value: 'finance', label: 'Finance' },
+      ],
+    },
+  ];
+}

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

@@ -0,0 +1,73 @@
+import { Component, computed, signal, ChangeDetectionStrategy } from '@angular/core';
+import { KjTreeSelectComponent } from '../tree-select';
+import type { KjTreeNode } from '@kouji-ui/core';
+
+/**
+ * Multi-select mode example. The panel stays open after each selection so
+ * multiple values can be picked. The trigger shows how many items are selected.
+ * A checkbox indicator appears on each node row.
+ */
+@Component({
+  selector: 'kj-tree-select-multi-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]="permissions"
+      [(kjValue)]="selected"
+      kjSelectionMode="multiple"
+      placeholder="Select permissions"
+    />
+    <p>
+      Selected ({{ count() }}):
+      {{ selected().length ? selected().join(', ') : 'none' }}
+    </p>
+  `,
+})
+export class KjTreeSelectMultiExample {
+  protected readonly selected = signal<string[]>([]);
+  protected readonly count = computed(() => this.selected().length);
+
+  protected readonly permissions: KjTreeNode<string>[] = [
+    {
+      value: 'users',
+      label: 'Users',
+      children: [
+        { value: 'users:read', label: 'Read users' },
+        { value: 'users:write', label: 'Write users' },
+        { value: 'users:delete', label: 'Delete users' },
+      ],
+    },
+    {
+      value: 'content',
+      label: 'Content',
+      children: [
+        { value: 'content:read', label: 'Read content' },
+        { value: 'content:publish', label: 'Publish content' },
+      ],
+    },
+    {
+      value: 'settings',
+      label: 'Settings',
+      children: [
+        { value: 'settings:view', label: 'View settings' },
+        { value: 'settings:edit', label: 'Edit settings' },
+      ],
+    },
+  ];
+}

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

@@ -0,0 +1,85 @@
+import { Component, signal, ChangeDetectionStrategy } from '@angular/core';
+import type { KjTreeNode } from '@kouji-ui/core';
+import { KjTreeSelectComponent } from '../tree-select';
+
+/**
+ * A walkthrough of the most common tree-select usages — single-select with a
+ * readout, multi-select that reports a count, and a pre-expanded panel on
+ * mount. Use this as the copy-paste starting point.
+ */
+@Component({
+  selector: 'kj-tree-select-usage-example',
+  standalone: true,
+  imports: [KjTreeSelectComponent],
+  styles: [
+    `
+      :host {
+        display: flex;
+        flex-direction: column;
+        gap: var(--kj-space-lg);
+      }
+      p {
+        margin: 0;
+        font: 0.875rem var(--kj-font-sans);
+        color: var(--kj-fg-muted);
+      }
+      .row {
+        display: flex;
+        gap: var(--kj-space-md);
+        align-items: center;
+      }
+    `,
+  ],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: `
+    <div class="row">
+      <kj-tree-select [kjNodes]="topics" [(kjValue)]="single" placeholder="Pick a topic" />
+      <p>Selected: {{ single() ?? 'none' }}</p>
+    </div>
+
+    <div class="row">
+      <kj-tree-select
+        [kjNodes]="topics"
+        kjSelectionMode="multiple"
+        [(kjValue)]="multi"
+        placeholder="Pick topics"
+      />
+      <p>{{ multi().length }} selected</p>
+    </div>
+
+    <div class="row">
+      <kj-tree-select
+        [kjNodes]="topics"
+        [(kjValue)]="open"
+        [(kjExpandedKeys)]="expanded"
+        placeholder="Pre-expanded"
+      />
+    </div>
+  `,
+})
+export class KjTreeSelectUsageExample {
+  protected readonly single = signal<string | undefined>(undefined);
+  protected readonly multi = signal<string[]>([]);
+  protected readonly open = signal<string | undefined>(undefined);
+  protected readonly expanded = signal<unknown[]>(['frontend']);
+
+  protected readonly topics: 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' },
+      ],
+    },
+  ];
+}

package/src/tree-select/index.ts

@@ -0,0 +1 @@
+export { KjTreeSelectComponent, KjTreeSelectNodeComponent } from './tree-select';

package/src/tree-select/tree-select.css

@@ -0,0 +1,220 @@
+@layer kj.component {
+  /* ── Root ──────────────────────────────────────────────────────────── */
+  .kj-tree-select {
+    position: relative;
+    display: inline-block;
+    min-width: 14rem;
+  }
+
+  /* ── Trigger ───────────────────────────────────────────────────────── */
+  .kj-tree-select-trigger {
+    width: 100%;
+    min-height: 2.75rem; /* WCAG 2.5.5 — 44px touch target */
+    display: inline-flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: var(--kj-space-sm);
+    background: var(--kj-bg-body);
+    color: var(--kj-fg-default);
+    border: var(--kj-border) solid var(--kj-border-default);
+    border-radius: var(--kj-radius-field);
+    padding: var(--kj-space-sm) var(--kj-space-md);
+    font: 0.875rem var(--kj-font-sans);
+    cursor: pointer;
+    text-align: left;
+  }
+  .kj-tree-select-trigger:focus-visible {
+    outline: 2px solid var(--kj-bg-primary);
+    outline-offset: 2px;
+  }
+  .kj-tree-select[data-disabled] .kj-tree-select-trigger {
+    opacity: 0.45;
+    cursor: not-allowed;
+    pointer-events: none;
+  }
+
+  .kj-tree-select-trigger-label {
+    flex: 1;
+    overflow: hidden;
+    white-space: nowrap;
+    text-overflow: ellipsis;
+  }
+  /* Placeholder styling — when nothing is selected the label matches placeholder color */
+  .kj-tree-select[data-empty] .kj-tree-select-trigger-label,
+  .kj-tree-select:not([data-has-value]) .kj-tree-select-trigger-label {
+    color: color-mix(in oklab, var(--kj-fg-default) 55%, transparent);
+  }
+
+  .kj-tree-select-caret {
+    flex-shrink: 0;
+    color: color-mix(in oklab, var(--kj-fg-default) 60%, transparent);
+    font-size: 0.75rem;
+    transition: transform var(--kj-transition, 150ms ease);
+  }
+  .kj-tree-select[data-open] .kj-tree-select-caret {
+    transform: rotate(180deg);
+  }
+
+  /* ── Panel ─────────────────────────────────────────────────────────── */
+  .kj-tree-select-panel {
+    box-sizing: border-box;
+    min-width: 14rem;
+    width: max-content;
+    background: var(--kj-bg-elevated);
+    border: var(--kj-border) solid var(--kj-border-default);
+    border-radius: var(--kj-radius-field);
+    box-shadow: var(--kj-shadow-md, 0 8px 24px rgb(0 0 0 / 0.12));
+    padding: 4px;
+    max-height: 18rem;
+    overflow: auto;
+    z-index: 100;
+  }
+  .kj-tree-select-panel[hidden] {
+    display: none;
+  }
+
+  .kj-tree-select-empty {
+    padding: var(--kj-space-sm) var(--kj-space-md);
+    color: color-mix(in oklab, var(--kj-fg-default) 55%, transparent);
+    font: 0.875rem var(--kj-font-sans);
+  }
+
+  /* ── Node row ──────────────────────────────────────────────────────── */
+  .kj-tree-select-node {
+    display: flex;
+    align-items: center;
+    gap: var(--kj-space-xs);
+    border-radius: var(--kj-radius-selector);
+    cursor: pointer;
+    color: var(--kj-fg-default);
+    font: 0.875rem var(--kj-font-sans);
+    min-height: 2.25rem; /* WCAG 2.5.5 — 36px is acceptable within a scrollable list */
+    outline: none;
+    /* padding-inline-start is set via inline style per-level */
+    padding-block: var(--kj-space-xs);
+    padding-inline-end: var(--kj-space-md);
+  }
+  .kj-tree-select-node:hover {
+    background: var(--kj-bg-surface);
+  }
+  .kj-tree-select-node:focus-visible {
+    outline: 2px solid var(--kj-bg-primary);
+    outline-offset: -2px;
+    background: var(--kj-bg-surface);
+  }
+  .kj-tree-select-node[data-selected] {
+    background: color-mix(in oklab, var(--kj-bg-primary) 12%, transparent);
+    color: var(--kj-fg-primary);
+  }
+  .kj-tree-select-node[data-selected]:hover {
+    background: color-mix(in oklab, var(--kj-bg-primary) 18%, transparent);
+  }
+  .kj-tree-select-node[aria-disabled='true'] {
+    opacity: 0.45;
+    cursor: not-allowed;
+    pointer-events: none;
+  }
+
+  /* Collapsed children are hidden via [hidden] attribute */
+  .kj-tree-select-node[hidden] {
+    display: none;
+  }
+
+  /* ── Toggle button ─────────────────────────────────────────────────── */
+  .kj-tree-select-toggle {
+    flex-shrink: 0;
+    width: 1.25rem;
+    height: 1.25rem;
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    background: transparent;
+    border: 0;
+    padding: 0;
+    cursor: pointer;
+    color: color-mix(in oklab, var(--kj-fg-default) 60%, transparent);
+    border-radius: var(--kj-radius-selector);
+  }
+  .kj-tree-select-toggle:hover {
+    background: color-mix(in oklab, var(--kj-fg-default) 10%, transparent);
+  }
+
+  .kj-tree-select-toggle-icon {
+    display: inline-block;
+    width: 0;
+    height: 0;
+    border-style: solid;
+    /* Collapsed: right-pointing triangle */
+    border-width: 4px 0 4px 7px;
+    border-color: transparent transparent transparent currentColor;
+    transition: transform var(--kj-transition, 150ms ease);
+  }
+  .kj-tree-select-node[data-expanded='true'] .kj-tree-select-toggle-icon {
+    /* Expanded: downward triangle */
+    transform: rotate(90deg);
+  }
+
+  /* Indent spacer for leaf nodes (keeps labels aligned with branch labels) */
+  .kj-tree-select-indent {
+    flex-shrink: 0;
+    width: 1.25rem;
+    height: 1.25rem;
+    display: inline-block;
+  }
+
+  .kj-tree-select-label {
+    flex: 1;
+    overflow: hidden;
+    white-space: nowrap;
+    text-overflow: ellipsis;
+  }
+
+  /* ── Checkbox (multi mode — tri-state via aria-checked) ─────────────── */
+  .kj-tree-select-checkbox {
+    flex-shrink: 0;
+    width: 1rem;
+    height: 1rem;
+    border: var(--kj-border) solid var(--kj-border-default);
+    border-radius: var(--kj-radius-selector);
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    font-size: 0.75rem;
+    line-height: 1;
+    /* Visual breathing room between the checkbox and the label so the
+       glyph never butts up against the text. The container's `gap`
+       handles the toggle ↔ checkbox spacing; this rule owns checkbox ↔
+       label specifically. */
+    margin-inline-end: var(--kj-space-sm);
+  }
+  /* Checked (cascade: all leaf descendants selected, or this is a
+     selected leaf). */
+  .kj-tree-select-node[aria-checked='true'] .kj-tree-select-checkbox {
+    background: var(--kj-bg-primary);
+    border-color: var(--kj-bg-primary);
+    color: var(--kj-fg-on-primary);
+  }
+  .kj-tree-select-node[aria-checked='true'] .kj-tree-select-checkbox::before {
+    content: '✓';
+  }
+  /* Indeterminate (cascade: some — but not all — leaf descendants
+     selected). Renders a dash glyph and keeps the primary fill so
+     screen-reader users hearing `aria-checked="mixed"` see the same
+     state visually. */
+  .kj-tree-select-node[aria-checked='mixed'] .kj-tree-select-checkbox {
+    background: var(--kj-bg-primary);
+    border-color: var(--kj-bg-primary);
+    color: var(--kj-fg-on-primary);
+  }
+  .kj-tree-select-node[aria-checked='mixed'] .kj-tree-select-checkbox::before {
+    content: '−'; /* U+2212 minus, not a hyphen */
+  }
+  /* Row highlight for fully checked branches/leaves in cascade mode. */
+  .kj-tree-select-node[aria-checked='true'] {
+    background: color-mix(in oklab, var(--kj-bg-primary) 12%, transparent);
+    color: var(--kj-fg-primary);
+  }
+  .kj-tree-select-node[aria-checked='true']:hover {
+    background: color-mix(in oklab, var(--kj-bg-primary) 18%, transparent);
+  }
+}

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

@@ -0,0 +1,83 @@
+import { ChangeDetectionStrategy, Component, signal } from '@angular/core';
+import { KjTreeSelectComponent } from './tree-select';
+import type { KjTreeNode } from '@kouji-ui/core';
+import type { PlaygroundFile } from '@kouji-ui/components/playground-types';
+
+/**
+ * Playground state — module-scope signals.
+ */
+const selectionMode = signal<'single' | 'multiple'>('single');
+const placeholder = signal('Pick a topic');
+const disabled = signal(false);
+
+const NODES: 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' },
+    ],
+  },
+];
+
+@Component({
+  selector: 'kj-tree-select-playground',
+  standalone: true,
+  imports: [KjTreeSelectComponent],
+  template: `
+    <kj-tree-select
+      [kjNodes]="nodes"
+      [kjSelectionMode]="selectionMode()"
+      [(kjValue)]="selected"
+      [placeholder]="placeholder()"
+      [disabled]="disabled()"
+    />
+  `,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class KjTreeSelectPlaygroundDemo {
+  protected readonly selectionMode = selectionMode;
+  protected readonly placeholder = placeholder;
+  protected readonly disabled = disabled;
+  protected readonly nodes = NODES;
+  protected readonly selected = signal<string | string[] | undefined>(undefined);
+}
+
+export const PLAYGROUND: PlaygroundFile = {
+  component: KjTreeSelectPlaygroundDemo,
+  state: {
+    selectionMode: selectionMode as unknown as ReturnType<typeof signal>,
+    placeholder: placeholder as unknown as ReturnType<typeof signal>,
+    disabled: disabled as unknown as ReturnType<typeof signal>,
+  },
+  controls: [
+    { kind: 'chips', name: 'selectionMode', label: 'mode', options: ['single', 'multiple'] },
+    { kind: 'text', name: 'placeholder', label: 'placeholder' },
+    { kind: 'toggle', name: 'disabled', label: 'disabled' },
+  ],
+  snippet: (values) => {
+    const s = values as {
+      selectionMode: string;
+      placeholder: string;
+      disabled: boolean;
+    };
+    const attrs: string[] = [
+      '[kjNodes]="nodes"',
+      `kjSelectionMode="${s.selectionMode}"`,
+      '[(kjValue)]="selected"',
+      `placeholder="${s.placeholder}"`,
+    ];
+    if (s.disabled) attrs.push('[disabled]="true"');
+    return `<kj-tree-select\n  ${attrs.join('\n  ')}\n/>`;
+  },
+};