@kouji-ui/components 0.1.1

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

@@ -0,0 +1,80 @@
+import { Component, signal, ChangeDetectionStrategy } from '@angular/core';
+import {
+  KjCascadeSelectComponent,
+  KjCascadeOptionComponent,
+  KjCascadeSubPanelComponent,
+} from '../cascade-select';
+
+/**
+ * Default cascade-select example: Country → State → City (3 levels).
+ * Selecting a city value commits it via `[(kjValue)]`.
+ *
+ * `<kj-cascade-sub-panel>` automatically binds to its parent
+ * `<kj-cascade-option>` — no `kjOwnerOptionId` needed.
+ */
+@Component({
+  selector: 'kj-cascade-select-example',
+  standalone: true,
+  imports: [KjCascadeSelectComponent, KjCascadeOptionComponent, KjCascadeSubPanelComponent],
+  styles: [
+    `
+      :host {
+        display: block;
+      }
+    `,
+  ],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: `
+    <kj-cascade-select [(kjValue)]="selectedCity" placeholder="Select a city">
+      <kj-cascade-option [kjValue]="'us'" kjLabel="USA">
+        <kj-cascade-sub-panel>
+          <kj-cascade-option [kjValue]="'ca'" kjLabel="California">
+            <kj-cascade-sub-panel>
+              <kj-cascade-option [kjValue]="'sf'" kjLabel="San Francisco" />
+              <kj-cascade-option [kjValue]="'la'" kjLabel="Los Angeles" />
+              <kj-cascade-option [kjValue]="'sd'" kjLabel="San Diego" />
+            </kj-cascade-sub-panel>
+          </kj-cascade-option>
+          <kj-cascade-option [kjValue]="'ny'" kjLabel="New York">
+            <kj-cascade-sub-panel>
+              <kj-cascade-option [kjValue]="'nyc'" kjLabel="New York City" />
+              <kj-cascade-option [kjValue]="'buf'" kjLabel="Buffalo" />
+            </kj-cascade-sub-panel>
+          </kj-cascade-option>
+        </kj-cascade-sub-panel>
+      </kj-cascade-option>
+
+      <kj-cascade-option [kjValue]="'gb'" kjLabel="United Kingdom">
+        <kj-cascade-sub-panel>
+          <kj-cascade-option [kjValue]="'eng'" kjLabel="England">
+            <kj-cascade-sub-panel>
+              <kj-cascade-option [kjValue]="'lon'" kjLabel="London" />
+              <kj-cascade-option [kjValue]="'man'" kjLabel="Manchester" />
+            </kj-cascade-sub-panel>
+          </kj-cascade-option>
+          <kj-cascade-option [kjValue]="'sco'" kjLabel="Scotland">
+            <kj-cascade-sub-panel>
+              <kj-cascade-option [kjValue]="'edi'" kjLabel="Edinburgh" />
+              <kj-cascade-option [kjValue]="'gla'" kjLabel="Glasgow" />
+            </kj-cascade-sub-panel>
+          </kj-cascade-option>
+        </kj-cascade-sub-panel>
+      </kj-cascade-option>
+
+      <kj-cascade-option [kjValue]="'jp'" kjLabel="Japan">
+        <kj-cascade-sub-panel>
+          <kj-cascade-option [kjValue]="'tok'" kjLabel="Tokyo" />
+          <kj-cascade-option [kjValue]="'osa'" kjLabel="Osaka" />
+          <kj-cascade-option [kjValue]="'kyo'" kjLabel="Kyoto" />
+        </kj-cascade-sub-panel>
+      </kj-cascade-option>
+    </kj-cascade-select>
+
+    <p style="margin-top: 1rem; font-size: 0.875rem; color: var(--kj-fg-default);">
+      Selected: <strong>{{ selectedCity() ?? '—' }}</strong>
+    </p>
+  `,
+})
+export class KjCascadeSelectExample {
+  readonly selectedCity = signal<string | undefined>(undefined);
+}

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

@@ -0,0 +1,73 @@
+import { Component, signal, ChangeDetectionStrategy } from '@angular/core';
+import {
+  KjCascadeSelectComponent,
+  KjCascadeOptionComponent,
+  KjCascadeSubPanelComponent,
+} from '../cascade-select';
+
+/**
+ * Cascade select wrapped in a `<div kjField>` with a label and helper hint.
+ * Demonstrates `KjField` integration — the field label is programmatically
+ * associated with the trigger via `aria-labelledby`.
+ */
+@Component({
+  selector: 'kj-cascade-select-field-example',
+  standalone: true,
+  imports: [KjCascadeSelectComponent, KjCascadeOptionComponent, KjCascadeSubPanelComponent],
+  styles: [
+    `
+      :host {
+        display: block;
+      }
+    `,
+  ],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: `
+    <div style="display: flex; flex-direction: column; gap: 0.25rem; max-width: 20rem;">
+      <label
+        for="cascade-delivery-location"
+        style="font-size: 0.875rem; font-weight: 500; color: var(--kj-fg-default);"
+      >
+        Delivery location
+      </label>
+      <kj-cascade-select
+        id="cascade-delivery-location"
+        [(kjValue)]="location"
+        placeholder="Select a city"
+      >
+        <kj-cascade-option [kjValue]="'us'" kjLabel="United States">
+          <kj-cascade-sub-panel kjOwnerOptionId="field-us">
+            <kj-cascade-option [kjValue]="'ca'" kjLabel="California">
+              <kj-cascade-sub-panel kjOwnerOptionId="field-ca">
+                <kj-cascade-option [kjValue]="'sf'" kjLabel="San Francisco" />
+                <kj-cascade-option [kjValue]="'la'" kjLabel="Los Angeles" />
+              </kj-cascade-sub-panel>
+            </kj-cascade-option>
+            <kj-cascade-option [kjValue]="'tx'" kjLabel="Texas">
+              <kj-cascade-sub-panel kjOwnerOptionId="field-tx">
+                <kj-cascade-option [kjValue]="'hou'" kjLabel="Houston" />
+                <kj-cascade-option [kjValue]="'dal'" kjLabel="Dallas" />
+              </kj-cascade-sub-panel>
+            </kj-cascade-option>
+          </kj-cascade-sub-panel>
+        </kj-cascade-option>
+        <kj-cascade-option [kjValue]="'ca-c'" kjLabel="Canada">
+          <kj-cascade-sub-panel kjOwnerOptionId="field-ca-c">
+            <kj-cascade-option [kjValue]="'tor'" kjLabel="Toronto" />
+            <kj-cascade-option [kjValue]="'van'" kjLabel="Vancouver" />
+          </kj-cascade-sub-panel>
+        </kj-cascade-option>
+      </kj-cascade-select>
+      <span style="font-size: 0.75rem; color: var(--kj-fg-muted, #888);">
+        Choose your country, state, then city.
+      </span>
+    </div>
+
+    <p style="margin-top: 1rem; font-size: 0.875rem;">
+      Selected: <strong>{{ location() ?? '—' }}</strong>
+    </p>
+  `,
+})
+export class KjCascadeSelectFieldExample {
+  readonly location = signal<string | undefined>(undefined);
+}

package/src/cascade-select/_examples/cascade-select.path.example.ts

@@ -0,0 +1,85 @@
+import { Component, signal, ChangeDetectionStrategy } from '@angular/core';
+import {
+  KjCascadeSelectComponent,
+  KjCascadeOptionComponent,
+  KjCascadeSubPanelComponent,
+} from '../cascade-select';
+
+const LABELS: Record<string, string> = {
+  us: 'USA',
+  gb: 'UK',
+  ca: 'California',
+  ny: 'New York',
+  sf: 'San Francisco',
+  la: 'Los Angeles',
+  nyc: 'New York City',
+  lon: 'London',
+};
+
+/**
+ * Demonstrates `(kjCascadePathChange)` — the full path from root to leaf
+ * is emitted on every selection and rendered as a breadcrumb.
+ */
+@Component({
+  selector: 'kj-cascade-select-path-example',
+  standalone: true,
+  imports: [KjCascadeSelectComponent, KjCascadeOptionComponent, KjCascadeSubPanelComponent],
+  styles: [
+    `
+      :host {
+        display: block;
+      }
+    `,
+  ],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: `
+    <div style="margin-bottom: 0.75rem; font-size: 0.875rem; color: var(--kj-fg-default);">
+      Path: <span style="font-weight: 600;">{{ breadcrumb() }}</span>
+    </div>
+
+    <kj-cascade-select
+      [(kjValue)]="selectedCity"
+      (kjCascadePathChange)="onPathChange($event)"
+      placeholder="Select a city"
+    >
+      <kj-cascade-option [kjValue]="'us'" kjLabel="USA">
+        <kj-cascade-sub-panel kjOwnerOptionId="path-us">
+          <kj-cascade-option [kjValue]="'ca'" kjLabel="California">
+            <kj-cascade-sub-panel kjOwnerOptionId="path-ca">
+              <kj-cascade-option [kjValue]="'sf'" kjLabel="San Francisco" />
+              <kj-cascade-option [kjValue]="'la'" kjLabel="Los Angeles" />
+            </kj-cascade-sub-panel>
+          </kj-cascade-option>
+          <kj-cascade-option [kjValue]="'ny'" kjLabel="New York">
+            <kj-cascade-sub-panel kjOwnerOptionId="path-ny">
+              <kj-cascade-option [kjValue]="'nyc'" kjLabel="New York City" />
+            </kj-cascade-sub-panel>
+          </kj-cascade-option>
+        </kj-cascade-sub-panel>
+      </kj-cascade-option>
+      <kj-cascade-option [kjValue]="'gb'" kjLabel="United Kingdom">
+        <kj-cascade-sub-panel kjOwnerOptionId="path-gb">
+          <kj-cascade-option [kjValue]="'lon'" kjLabel="London" />
+        </kj-cascade-sub-panel>
+      </kj-cascade-option>
+    </kj-cascade-select>
+
+    <p style="margin-top: 1rem; font-size: 0.875rem; color: var(--kj-fg-default);">
+      Selected value: <strong>{{ selectedCity() ?? '—' }}</strong>
+    </p>
+  `,
+})
+export class KjCascadeSelectPathExample {
+  readonly selectedCity = signal<string | undefined>(undefined);
+  readonly path = signal<readonly unknown[]>([]);
+
+  readonly breadcrumb = () => {
+    const p = this.path();
+    if (!p.length) return '—';
+    return p.map((v) => LABELS[v as string] ?? String(v)).join(' › ');
+  };
+
+  onPathChange(p: readonly unknown[]): void {
+    this.path.set(p);
+  }
+}

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

@@ -0,0 +1,7 @@
+// AUTO-GENERATED by scripts/migrate-examples.mjs
+// One barrel per component folder — used by the docs app as a lazy chunk.
+export { KjCascadeSelectDataDrivenExample } from './cascade-select.data-driven.example';
+export { KjCascadeSelectDisabledExample } from './cascade-select.disabled.example';
+export { KjCascadeSelectExample } from './cascade-select.example';
+export { KjCascadeSelectFieldExample } from './cascade-select.field.example';
+export { KjCascadeSelectPathExample } from './cascade-select.path.example';

package/src/cascade-select/cascade-select.css

@@ -0,0 +1,120 @@
+@layer kj.component {
+  /* ── Root ────────────────────────────────────────────────────────────── */
+  .kj-cascade-select {
+    position: relative;
+    display: inline-block;
+    min-width: 12rem;
+  }
+
+  /* ── Trigger button ──────────────────────────────────────────────────── */
+  .kj-cascade-trigger {
+    width: 100%;
+    display: inline-flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: var(--kj-space-sm);
+    background: var(--kj-bg-field);
+    color: var(--kj-fg-default);
+    border: 1px 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;
+    min-height: 2.75rem; /* 44px touch target */
+  }
+  .kj-cascade-trigger:focus-visible {
+    outline: 2px solid var(--kj-border-focus);
+    outline-offset: 2px;
+  }
+  .kj-cascade-select[data-disabled] .kj-cascade-trigger {
+    opacity: 0.45;
+    cursor: not-allowed;
+    pointer-events: none;
+  }
+
+  /* ── Root panel ──────────────────────────────────────────────────────── */
+  .kj-cascade-panel {
+    box-sizing: border-box;
+    background: var(--kj-bg-elevated);
+    border: 1px solid var(--kj-border-default);
+    border-radius: var(--kj-radius-field);
+    box-shadow: var(--kj-shadow-md);
+    padding: 4px;
+    min-width: 12rem;
+    max-height: 20rem;
+    overflow: auto;
+    z-index: 200;
+  }
+  .kj-cascade-panel[hidden] { display: none; }
+
+  /* ── Sub-panel ───────────────────────────────────────────────────────── */
+  /* `position: fixed` so the sub-panel escapes the root panel's
+     `overflow: auto`. Coords are written inline by the sub-panel directive
+     based on the parent option's bounding rect. */
+  .kj-cascade-sub-panel {
+    position: fixed;
+    background: var(--kj-bg-elevated);
+    border: 1px solid var(--kj-border-default);
+    border-radius: var(--kj-radius-field);
+    box-shadow: var(--kj-shadow-md);
+    padding: 4px;
+    min-width: 12rem;
+    max-height: 20rem;
+    overflow: auto;
+    z-index: 1001;
+  }
+  .kj-cascade-sub-panel[hidden] { display: none; }
+
+  /* ── Option row ──────────────────────────────────────────────────────── */
+  .kj-cascade-option {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    padding: var(--kj-space-sm) var(--kj-space-md);
+    border-radius: var(--kj-radius-selector);
+    cursor: pointer;
+    color: var(--kj-fg-default);
+    font: 0.875rem var(--kj-font-sans);
+    min-height: 2.75rem; /* 44px touch target */
+    position: relative;
+  }
+  .kj-cascade-option:hover,
+  .kj-cascade-option[data-active] {
+    background: var(--kj-bg-surface);
+  }
+  .kj-cascade-option[aria-selected="true"] {
+    background: var(--kj-bg-primary-subtle, var(--kj-bg-surface));
+    color: var(--kj-fg-primary, var(--kj-fg-default));
+  }
+  .kj-cascade-option[data-disabled] {
+    opacity: 0.45;
+    cursor: not-allowed;
+    pointer-events: none;
+  }
+  .kj-cascade-option[data-active-path] {
+    font-weight: 500;
+  }
+
+  /* ── Option label ────────────────────────────────────────────────────── */
+  .kj-cascade-option-label {
+    flex: 1;
+    min-width: 0;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+  }
+
+  /* ── Chevron ─────────────────────────────────────────────────────────── */
+  .kj-cascade-option-chevron {
+    flex-shrink: 0;
+    font-size: 1rem;
+    color: var(--kj-fg-muted, currentColor);
+    opacity: 0.6;
+    margin-left: var(--kj-space-sm);
+  }
+  /* Hide chevron on leaf options (data-leaf="true" is set on the host element) */
+  [data-leaf="true"] .kj-cascade-option-chevron,
+  [data-leaf="true"].kj-cascade-option .kj-cascade-option-chevron {
+    display: none;
+  }
+}

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

@@ -0,0 +1,133 @@
+import { ChangeDetectionStrategy, Component, signal } from '@angular/core';
+import {
+  KjCascadeOptionComponent,
+  KjCascadeSelectComponent,
+  KjCascadeSubPanelComponent,
+} from './cascade-select';
+import type { PlaygroundFile } from '@kouji-ui/components/playground-types';
+
+/**
+ * Playground state — module-scope signals. Tunes placeholder text, disabled
+ * state, region count (drives panel structure), and whether one of the
+ * leaves is marked disabled so the navigation skip can be observed.
+ */
+const placeholder = signal('Select a country');
+const disabled = signal(false);
+const regionCount = signal<1 | 2 | 3>(2);
+const disableLeaf = signal(false);
+
+const REGIONS: ReadonlyArray<{
+  value: string;
+  label: string;
+  children: ReadonlyArray<{ value: string; label: string }>;
+}> = [
+  {
+    value: 'eu',
+    label: 'Europe',
+    children: [
+      { value: 'fr', label: 'France' },
+      { value: 'de', label: 'Germany' },
+      { value: 'it', label: 'Italy' },
+    ],
+  },
+  {
+    value: 'am',
+    label: 'Americas',
+    children: [
+      { value: 'us', label: 'United States' },
+      { value: 'br', label: 'Brazil' },
+    ],
+  },
+  {
+    value: 'as',
+    label: 'Asia',
+    children: [
+      { value: 'jp', label: 'Japan' },
+      { value: 'in', label: 'India' },
+    ],
+  },
+];
+
+@Component({
+  selector: 'kj-cascade-select-playground',
+  standalone: true,
+  imports: [
+    KjCascadeSelectComponent,
+    KjCascadeOptionComponent,
+    KjCascadeSubPanelComponent,
+  ],
+  template: `
+    <kj-cascade-select
+      [(kjValue)]="selected"
+      [placeholder]="placeholder()"
+      [disabled]="disabled()"
+    >
+      @for (region of visibleRegions(); track region.value) {
+        <kj-cascade-option [kjValue]="region.value" [kjLabel]="region.label">
+          <kj-cascade-sub-panel>
+            @for (child of region.children; track child.value; let first = $first) {
+              <kj-cascade-option
+                [kjValue]="child.value"
+                [kjLabel]="child.label"
+                [kjDisabled]="disableLeaf() && first"
+              />
+            }
+          </kj-cascade-sub-panel>
+        </kj-cascade-option>
+      }
+    </kj-cascade-select>
+  `,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class KjCascadeSelectPlaygroundDemo {
+  protected readonly placeholder = placeholder;
+  protected readonly disabled = disabled;
+  protected readonly regionCount = regionCount;
+  protected readonly disableLeaf = disableLeaf;
+  protected readonly selected = signal<string | undefined>(undefined);
+
+  protected visibleRegions(): typeof REGIONS {
+    return REGIONS.slice(0, regionCount());
+  }
+}
+
+export const PLAYGROUND: PlaygroundFile = {
+  component: KjCascadeSelectPlaygroundDemo,
+  state: {
+    placeholder: placeholder as unknown as ReturnType<typeof signal>,
+    disabled: disabled as unknown as ReturnType<typeof signal>,
+    regionCount: regionCount as unknown as ReturnType<typeof signal>,
+    disableLeaf: disableLeaf as unknown as ReturnType<typeof signal>,
+  },
+  controls: [
+    { kind: 'text', name: 'placeholder', label: 'placeholder' },
+    { kind: 'chips', name: 'regionCount', label: 'regions', options: [1, 2, 3] },
+    { kind: 'toggle', name: 'disabled', label: 'disabled' },
+    { kind: 'toggle', name: 'disableLeaf', label: 'disable first leaf' },
+  ],
+  snippet: (values) => {
+    const s = values as {
+      placeholder: string;
+      disabled: boolean;
+      regionCount: number;
+      disableLeaf: boolean;
+    };
+    const attrs: string[] = [
+      `[(kjValue)]="selected"`,
+      `placeholder="${s.placeholder}"`,
+    ];
+    if (s.disabled) attrs.push('[disabled]="true"');
+    const regions = REGIONS.slice(0, s.regionCount)
+      .map((region) => {
+        const children = region.children
+          .map((child, i) => {
+            const disabledAttr = s.disableLeaf && i === 0 ? ' [kjDisabled]="true"' : '';
+            return `      <kj-cascade-option kjValue="${child.value}" kjLabel="${child.label}"${disabledAttr} />`;
+          })
+          .join('\n');
+        return `  <kj-cascade-option kjValue="${region.value}" kjLabel="${region.label}">\n    <kj-cascade-sub-panel>\n${children}\n    </kj-cascade-sub-panel>\n  </kj-cascade-option>`;
+      })
+      .join('\n');
+    return `<kj-cascade-select\n  ${attrs.join('\n  ')}\n>\n${regions}\n</kj-cascade-select>`;
+  },
+};