@kouji-ui/components 0.1.1

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

@@ -0,0 +1,201 @@
+import {
+  ChangeDetectionStrategy,
+  Component,
+  computed,
+  forwardRef,
+  inject,
+  input,
+  ViewEncapsulation,
+} from '@angular/core';
+import {
+  KjCascadeSelect,
+  KjCascadeSelectOption,
+  KjCascadeSelectPanel,
+  KjCascadeSelectSubPanel,
+  KjCascadeSelectTrigger,
+  KjIconDirective,
+} from '@kouji-ui/core';
+
+/**
+ * Cascade-select root wrapper. Renders a trigger button + caret, the root
+ * panel, and projects sub-tree options supplied by the consumer.
+ *
+ * Bind the selected leaf value via `[(kjValue)]`. Listen for the full path
+ * via `(kjCascadePathChange)`.
+ *
+ * @doc-example Default
+ *   The default playground — three-level country/state/city tree.
+ *   @doc-file cascade-select.example.ts
+ * @doc-example Usage
+ *   The common shape — controlled leaf value with a path listener. Use this as
+ *   the copy-paste starting point.
+ *   @doc-file cascade-select.usage.example.ts
+ * @doc-example Data-driven
+ *   Build the option tree from a `TreeNode[]` source so it can be hydrated
+ *   from an API response.
+ *   @doc-file cascade-select.data-driven.example.ts
+ * @doc-example Path output
+ *   Bind `[(kjCascadePath)]` to mirror the full ancestor chain into the form.
+ *   @doc-file cascade-select.path.example.ts
+ * @doc-example In a field
+ *   Wraps the trigger in `<kj-field>` for label / hint / error wiring.
+ *   @doc-file cascade-select.field.example.ts
+ * @doc-example Disabled options
+ *   Mark an option `disabled` to skip it in navigation and prevent selection.
+ *   @doc-file cascade-select.disabled.example.ts
+ *
+ * @doc-keyboard
+ *   Enter|Space    — Opens the panel from the trigger; activates the focused option
+ *   ArrowDown      — Moves focus to the next option in the current panel
+ *   ArrowUp        — Moves focus to the previous option in the current panel
+ *   ArrowRight     — Opens a branch option's sub-panel
+ *   ArrowLeft      — Closes the current sub-panel and returns focus to its owner
+ *   Home|End       — Jumps to the first / last option in the current panel
+ *   Escape         — Closes all panels and returns focus to the trigger
+ *
+ * @doc-aria
+ *   role                 — `combobox` on the trigger; each panel is `listbox`; options are `option`
+ *   aria-haspopup        — `"listbox"` on the trigger
+ *   aria-expanded        — Reflected on the trigger; flips with the panel open state
+ *   aria-controls        — Trigger references the root panel id
+ *   aria-activedescendant — Trigger references the currently-focused option id
+ *   aria-disabled        — Reflected on disabled options
+ *
+ * @doc-touch
+ *   The trigger inherits `<kj-button>` sizing — default `md` is ≥ 36px tall;
+ *   bump to `lg` for touch-first surfaces. Option rows are full-width and
+ *   meet WCAG 2.5.5 on the default padding.
+ *
+ * @doc-a11y
+ *   Implements the WAI-ARIA APG Combobox + nested Listbox pattern. The panel
+ *   is portalled via the shared overlay primitive so it escapes clipping
+ *   ancestors. Selection emits at the leaf level via `[(kjValue)]`; the full
+ *   ancestor chain is available via `[(kjCascadePath)]` for forms that need
+ *   the breadcrumb.
+ *
+ * @doc-related select,tree-select,combobox
+ *
+ * @doc-category Library/Data input
+ * @doc
+ * @doc-name cascade-select
+ * @doc-description Themed hierarchical select for multi-level option trees with hover or arrow-key sub-panel navigation.
+ * @doc-is-main
+ */
+@Component({
+  selector: 'kj-cascade-select',
+  standalone: true,
+  // Compose the umbrella KjCascadeSelect directive on the wrapper element.
+  // Forwarding `kjValue`/`kjCascadePath` so the consumer can bind via
+  // `[(value)]`/`[(cascadePath)]` on `<kj-cascade-select>`. The directive
+  // provides `KJ_CASCADE_SELECT` (+ `KJ_SELECT`) at this element so
+  // projected options/sub-panels resolve the same context via DI.
+  hostDirectives: [
+    {
+      directive: KjCascadeSelect,
+      inputs: ['kjValue', 'kjCascadePath'],
+      outputs: ['kjValueChange', 'kjCascadePathChange'],
+    },
+  ],
+  imports: [KjCascadeSelectTrigger, KjCascadeSelectPanel],
+  template: `
+    <button
+      type="button"
+      kjCascadeSelectTrigger
+      #trigger="kjCascadeSelectTrigger"
+      class="kj-cascade-trigger"
+      [disabled]="disabled() || null"
+    >
+      <span class="kj-cascade-trigger-label">{{ displayLabel() }}</span>
+      <span class="kj-cascade-trigger-caret" aria-hidden="true">▾</span>
+    </button>
+    <div
+      kjCascadeSelectPanel
+      class="kj-cascade-panel"
+      [kjFor]="trigger"
+    >
+      <ng-content />
+    </div>
+  `,
+  styleUrl: './cascade-select.css',
+  encapsulation: ViewEncapsulation.None,
+  host: {
+    'class': 'kj-cascade-select',
+    '[attr.data-disabled]': "disabled() ? '' : null",
+  },
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class KjCascadeSelectComponent {
+  /** Placeholder shown when no value is selected. */
+  readonly placeholder = input<string>('Select…');
+
+  /** Whether the trigger is disabled. */
+  readonly disabled = input(false);
+
+  /** @internal — read the composed root directive's value for the label. */
+  private readonly cascade = inject(KjCascadeSelect);
+
+  /** @internal */
+  readonly displayLabel = computed(() => {
+    const v = this.cascade.value() as string | null | undefined;
+    if (v === undefined || v === null || v === '') return this.placeholder();
+    return String(v);
+  });
+}
+
+/**
+ * A single option row in a `<kj-cascade-select>`. Renders the option label
+ * with an optional selection checkmark and a chevron glyph for branch options.
+ * @doc
+ * @doc-name cascade-select
+ */
+@Component({
+  selector: 'kj-cascade-option',
+  standalone: true,
+  // Extends `KjCascadeSelectOption` so this component IS the option
+  // directive: inherits its inputs (`kjValue`/`kjLabel`/`kjDisabled` via the
+  // inner `KjListItem` aliases), its host bindings (role, click handler,
+  // hover timers, `data-*`), and its `KjListItem` hostDirective composition
+  // — all without going through outer `hostDirectives` forwarding (Angular
+  // 21 NG2017 forbids that for alias-exposed inputs). The `useExisting`
+  // provider routes `inject(KjCascadeSelectOption)` from projected
+  // sub-panels to this same instance.
+  imports: [KjIconDirective],
+  providers: [
+    { provide: KjCascadeSelectOption, useExisting: forwardRef(() => KjCascadeOptionComponent) },
+  ],
+  template: `
+    <span class="kj-cascade-option-label">{{ item.label() }}</span>
+    @if (isBranch()) {
+      <i class="kj-cascade-option-chevron" kjIcon="chevron-right"></i>
+    }
+    <ng-content />
+  `,
+  encapsulation: ViewEncapsulation.None,
+  host: { 'class': 'kj-cascade-option' },
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class KjCascadeOptionComponent extends KjCascadeSelectOption {}
+
+/**
+ * Sub-panel container for child options of a `<kj-cascade-option>`.
+ * Projects `<kj-cascade-option>` rows for the next level of the hierarchy.
+ * @doc
+ * @doc-name cascade-select
+ */
+@Component({
+  selector: 'kj-cascade-sub-panel',
+  standalone: true,
+  hostDirectives: [
+    {
+      directive: KjCascadeSelectSubPanel,
+      inputs: ['kjOwnerOptionId'],
+    },
+  ],
+  template: `<ng-content />`,
+  encapsulation: ViewEncapsulation.None,
+  host: {
+    'class': 'kj-cascade-sub-panel',
+  },
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class KjCascadeSubPanelComponent {}

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

@@ -0,0 +1,44 @@
+import { ChangeDetectionStrategy, Component, signal } from '@angular/core';
+import {
+  KjCascadeOptionComponent,
+  KjCascadeSelectComponent,
+  KjCascadeSubPanelComponent,
+} from './cascade-select';
+
+/**
+ * Common cascade-select shape — controlled leaf value plus a path listener.
+ * Use this as the copy-paste starting point for new screens.
+ */
+@Component({
+  selector: 'kj-cascade-select-usage-example',
+  standalone: true,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  imports: [
+    KjCascadeSelectComponent,
+    KjCascadeOptionComponent,
+    KjCascadeSubPanelComponent,
+  ],
+  styles: [`:host { display: flex; flex-direction: column; gap: var(--kj-space-md); align-items: flex-start; }`],
+  template: `
+    <kj-cascade-select [(kjValue)]="city" placeholder="Pick a city">
+      <kj-cascade-option [kjValue]="'fr'" kjLabel="France">
+        <kj-cascade-sub-panel>
+          <kj-cascade-option [kjValue]="'paris'" kjLabel="Paris" />
+          <kj-cascade-option [kjValue]="'lyon'" kjLabel="Lyon" />
+        </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-sub-panel>
+      </kj-cascade-option>
+    </kj-cascade-select>
+    <p style="font-size: 0.875rem; color: var(--kj-fg-muted);">
+      Selected: <strong>{{ city() ?? '—' }}</strong>
+    </p>
+  `,
+})
+export class KjCascadeSelectUsageExample {
+  readonly city = signal<string | undefined>(undefined);
+}

package/src/cascade-select/index.ts

@@ -0,0 +1,5 @@
+export {
+  KjCascadeSelectComponent,
+  KjCascadeOptionComponent,
+  KjCascadeSubPanelComponent,
+} from './cascade-select';

package/src/chat/_examples/chat-bubble.example.ts

@@ -0,0 +1,71 @@
+import { Component, ChangeDetectionStrategy } from '@angular/core';
+import { KjAvatarComponent } from '../../avatar/avatar';
+import {
+  KjChatAvatarComponent,
+  KjChatBubbleComponent,
+  KjChatComponent,
+  KjChatFooterComponent,
+  KjChatHeaderComponent,
+  KjChatLogComponent,
+} from '../chat';
+
+/**
+ * Default usage example for the Chat Bubble family. A four-message
+ * conversation between two senders inside a `<kj-chat-log>` — anchors
+ * `kjSide`, the avatar slot, header + `<time>`, bubble variants
+ * (`default` for theirs, `primary` for mine), and the footer state glyph.
+ */
+@Component({
+  selector: 'kj-chat-bubble-example',
+  standalone: true,
+  imports: [
+    KjChatLogComponent,
+    KjChatComponent,
+    KjChatAvatarComponent,
+    KjChatHeaderComponent,
+    KjChatBubbleComponent,
+    KjChatFooterComponent,
+    KjAvatarComponent,
+  ],
+  styles: [
+    `
+      :host {
+        display: block;
+      }
+      kj-chat-log {
+        max-height: 22rem;
+      }
+    `,
+  ],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: `
+    <kj-chat-log kjChatLogLabel="Conversation with Alice">
+      <kj-chat kjSide="start" kjChatAuthor="alice">
+        <kj-chat-avatar>
+          <kj-avatar content="AL" alt="Alice" />
+        </kj-chat-avatar>
+        <kj-chat-header>Alice <time datetime="2025-05-06T12:46">12:46</time></kj-chat-header>
+        <kj-chat-bubble>Hey! Did you see the new spec?</kj-chat-bubble>
+      </kj-chat>
+
+      <kj-chat kjSide="end" kjChatAuthor="me">
+        <kj-chat-bubble kjVariant="primary">Just landed, reading it now.</kj-chat-bubble>
+        <kj-chat-footer kjState="read">Read 12:47</kj-chat-footer>
+      </kj-chat>
+
+      <kj-chat kjSide="start" kjChatAuthor="alice">
+        <kj-chat-avatar>
+          <kj-avatar content="AL" alt="Alice" />
+        </kj-chat-avatar>
+        <kj-chat-header>Alice <time datetime="2025-05-06T12:48">12:48</time></kj-chat-header>
+        <kj-chat-bubble>Section 3 is the interesting part.</kj-chat-bubble>
+      </kj-chat>
+
+      <kj-chat kjSide="end" kjChatAuthor="me">
+        <kj-chat-bubble kjVariant="primary">Agreed — let's pair on it tomorrow.</kj-chat-bubble>
+        <kj-chat-footer kjState="delivered">Delivered</kj-chat-footer>
+      </kj-chat>
+    </kj-chat-log>
+  `,
+})
+export class KjChatBubbleExample {}

package/src/chat/_examples/chat-bubble.grouped.example.ts

@@ -0,0 +1,69 @@
+import { Component, ChangeDetectionStrategy } from '@angular/core';
+import { KjAvatarComponent } from '../../avatar/avatar';
+import {
+  KjChatAvatarComponent,
+  KjChatBubbleComponent,
+  KjChatComponent,
+  KjChatHeaderComponent,
+  KjChatLogComponent,
+} from '../chat';
+
+/**
+ * Auto-grouping by sender. Three messages from Alice in a row, then one
+ * from me — the avatar slot, header, and tail appear only on the first
+ * Alice message; the next two are visually grouped (avatar visibility
+ * hidden, header hidden, no tail). Grouping is computed by the row
+ * directive walking `previousElementSibling` against a shared registry.
+ */
+@Component({
+  selector: 'kj-chat-bubble-grouped-example',
+  standalone: true,
+  imports: [
+    KjChatLogComponent,
+    KjChatComponent,
+    KjChatAvatarComponent,
+    KjChatHeaderComponent,
+    KjChatBubbleComponent,
+    KjAvatarComponent,
+  ],
+  styles: [
+    `
+      :host {
+        display: block;
+      }
+    `,
+  ],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: `
+    <kj-chat-log kjChatLogLabel="Grouped messages">
+      <kj-chat kjSide="start" kjChatAuthor="alice">
+        <kj-chat-avatar>
+          <kj-avatar content="AL" alt="Alice" />
+        </kj-chat-avatar>
+        <kj-chat-header>Alice <time datetime="2025-05-06T10:00">10:00</time></kj-chat-header>
+        <kj-chat-bubble>Hey, quick question —</kj-chat-bubble>
+      </kj-chat>
+
+      <kj-chat kjSide="start" kjChatAuthor="alice">
+        <kj-chat-avatar>
+          <kj-avatar content="AL" alt="Alice" />
+        </kj-chat-avatar>
+        <kj-chat-header>Alice <time datetime="2025-05-06T10:00">10:00</time></kj-chat-header>
+        <kj-chat-bubble>are you free for 15 mins?</kj-chat-bubble>
+      </kj-chat>
+
+      <kj-chat kjSide="start" kjChatAuthor="alice">
+        <kj-chat-avatar>
+          <kj-avatar content="AL" alt="Alice" />
+        </kj-chat-avatar>
+        <kj-chat-header>Alice <time datetime="2025-05-06T10:01">10:01</time></kj-chat-header>
+        <kj-chat-bubble>around 2pm?</kj-chat-bubble>
+      </kj-chat>
+
+      <kj-chat kjSide="end" kjChatAuthor="me">
+        <kj-chat-bubble kjVariant="primary">Yep, 2pm works.</kj-chat-bubble>
+      </kj-chat>
+    </kj-chat-log>
+  `,
+})
+export class KjChatBubbleGroupedExample {}

package/src/chat/_examples/chat-bubble.sides.example.ts

@@ -0,0 +1,41 @@
+import { Component, ChangeDetectionStrategy } from '@angular/core';
+import {
+  KjChatBubbleComponent,
+  KjChatComponent,
+  KjChatHeaderComponent,
+  KjChatLogComponent,
+} from '../chat';
+
+/**
+ * Demonstrates the `start` / `end` side mapping. Side is logical — CSS
+ * reads `data-side` on the row and handles the physical column flip,
+ * including RTL via cascade. DOM order (header → bubble → footer) is
+ * fixed for meaningful-sequence reading order.
+ */
+@Component({
+  selector: 'kj-chat-bubble-sides-example',
+  standalone: true,
+  imports: [KjChatLogComponent, KjChatComponent, KjChatHeaderComponent, KjChatBubbleComponent],
+  styles: [
+    `
+      :host {
+        display: block;
+      }
+    `,
+  ],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: `
+    <kj-chat-log kjChatLogLabel="Sides demo">
+      <kj-chat kjSide="start">
+        <kj-chat-header>Them <time datetime="2025-05-06T09:00">09:00</time></kj-chat-header>
+        <kj-chat-bubble>Side: start (theirs)</kj-chat-bubble>
+      </kj-chat>
+
+      <kj-chat kjSide="end">
+        <kj-chat-header>You <time datetime="2025-05-06T09:01">09:01</time></kj-chat-header>
+        <kj-chat-bubble kjVariant="primary">Side: end (yours)</kj-chat-bubble>
+      </kj-chat>
+    </kj-chat-log>
+  `,
+})
+export class KjChatBubbleSidesExample {}

package/src/chat/_examples/chat-bubble.variants.example.ts

@@ -0,0 +1,58 @@
+import { Component, ChangeDetectionStrategy } from '@angular/core';
+import {
+  KjChatBubbleComponent,
+  KjChatComponent,
+  KjChatHeaderComponent,
+  KjChatLogComponent,
+} from '../chat';
+
+/**
+ * Demonstrates the bubble variant set: `default` for theirs, `primary`
+ * for yours, `info` / `success` / `warning` / `error` for system or
+ * status messages, `accent` for highlighted (mention / quoted) replies.
+ */
+@Component({
+  selector: 'kj-chat-bubble-variants-example',
+  standalone: true,
+  imports: [KjChatLogComponent, KjChatComponent, KjChatHeaderComponent, KjChatBubbleComponent],
+  styles: [
+    `
+      :host {
+        display: block;
+      }
+    `,
+  ],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: `
+    <kj-chat-log kjChatLogLabel="Variants demo">
+      <kj-chat kjSide="start">
+        <kj-chat-header>System <time datetime="2025-05-06T08:00">08:00</time></kj-chat-header>
+        <kj-chat-bubble kjVariant="info">Alice joined the conversation.</kj-chat-bubble>
+      </kj-chat>
+
+      <kj-chat kjSide="start">
+        <kj-chat-header>Bot <time datetime="2025-05-06T08:01">08:01</time></kj-chat-header>
+        <kj-chat-bubble kjVariant="success">Build #42 succeeded.</kj-chat-bubble>
+      </kj-chat>
+
+      <kj-chat kjSide="end">
+        <kj-chat-bubble kjVariant="primary">Nice — pushing now.</kj-chat-bubble>
+      </kj-chat>
+
+      <kj-chat kjSide="end">
+        <kj-chat-bubble kjVariant="error">Failed to send.</kj-chat-bubble>
+      </kj-chat>
+
+      <kj-chat kjSide="start">
+        <kj-chat-header>Bot <time datetime="2025-05-06T08:05">08:05</time></kj-chat-header>
+        <kj-chat-bubble kjVariant="warning">Tests took longer than usual.</kj-chat-bubble>
+      </kj-chat>
+
+      <kj-chat kjSide="start">
+        <kj-chat-header>Alice <time datetime="2025-05-06T08:06">08:06</time></kj-chat-header>
+        <kj-chat-bubble kjVariant="accent">@you can you take a look?</kj-chat-bubble>
+      </kj-chat>
+    </kj-chat-log>
+  `,
+})
+export class KjChatBubbleVariantsExample {}

package/src/chat/_examples/chat-bubble.with-state.example.ts

@@ -0,0 +1,57 @@
+import { Component, ChangeDetectionStrategy } from '@angular/core';
+import {
+  KjChatBubbleComponent,
+  KjChatComponent,
+  KjChatFooterComponent,
+  KjChatLogComponent,
+} from '../chat';
+
+/**
+ * Read-receipt progression: `sending` → `sent` → `delivered` → `read`
+ * plus the `error` terminal. Footer's `data-state` drives the glyph;
+ * the directive injects an `aria-label` so AT users hear "Sending",
+ * "Sent", "Delivered", "Read", or "Failed to send" regardless of the
+ * visual glyph.
+ */
+@Component({
+  selector: 'kj-chat-bubble-with-state-example',
+  standalone: true,
+  imports: [KjChatLogComponent, KjChatComponent, KjChatBubbleComponent, KjChatFooterComponent],
+  styles: [
+    `
+      :host {
+        display: block;
+      }
+    `,
+  ],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: `
+    <kj-chat-log kjChatLogLabel="Read receipts">
+      <kj-chat kjSide="end">
+        <kj-chat-bubble kjVariant="primary">Drafting…</kj-chat-bubble>
+        <kj-chat-footer kjState="sending">Sending</kj-chat-footer>
+      </kj-chat>
+
+      <kj-chat kjSide="end">
+        <kj-chat-bubble kjVariant="primary">Off it goes.</kj-chat-bubble>
+        <kj-chat-footer kjState="sent">Sent 12:46</kj-chat-footer>
+      </kj-chat>
+
+      <kj-chat kjSide="end">
+        <kj-chat-bubble kjVariant="primary">Hope this lands.</kj-chat-bubble>
+        <kj-chat-footer kjState="delivered">Delivered</kj-chat-footer>
+      </kj-chat>
+
+      <kj-chat kjSide="end">
+        <kj-chat-bubble kjVariant="primary">She read it.</kj-chat-bubble>
+        <kj-chat-footer kjState="read">Read 12:48</kj-chat-footer>
+      </kj-chat>
+
+      <kj-chat kjSide="end">
+        <kj-chat-bubble kjVariant="error">Tried to send a 50MB GIF.</kj-chat-bubble>
+        <kj-chat-footer kjState="error">Tap to retry</kj-chat-footer>
+      </kj-chat>
+    </kj-chat-log>
+  `,
+})
+export class KjChatBubbleWithStateExample {}

package/src/chat/_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 { KjChatBubbleExample } from './chat-bubble.example';
+export { KjChatBubbleGroupedExample } from './chat-bubble.grouped.example';
+export { KjChatBubbleSidesExample } from './chat-bubble.sides.example';
+export { KjChatBubbleVariantsExample } from './chat-bubble.variants.example';
+export { KjChatBubbleWithStateExample } from './chat-bubble.with-state.example';