@kouji-ui/core 0.0.4 → 0.1.1

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

@@ -0,0 +1,168 @@
+import {
+  computed,
+  Directive,
+  effect,
+  ElementRef,
+  inject,
+  input,
+} from '@angular/core';
+import { KjListNavigator } from '../primitives/list';
+import { nextCascadeId } from './cascade-select.context';
+import { KjCascadeSelect } from './cascade-select-root';
+import { KjCascadeSelectOption } from './cascade-select-option';
+
+/**
+ * Sub-panel for a single level in the cascade. Apply as a child of a
+ * `[kjCascadeSelectOption]` that acts as a sub-trigger (branch node).
+ *
+ * Composes `KjListNavigator` (vertical + activedescendant) for the
+ * generic Up/Down / Home/End / Enter / Space / type-ahead contract.
+ * Cascade-specific ArrowRight (open the next-level sub-panel) and
+ * ArrowLeft (close this sub-panel + focus parent) remain handled here.
+ *
+ * Resolves its parent `KjCascadeSelectOption` through Angular DI — no
+ * `document.getElementById` / `setParentOptionId` plumbing. The
+ * sub-panel reads the parent's auto-generated `KjListItem.id` for its
+ * `aria-labelledby` and uses the parent's host element directly for
+ * fixed-position anchoring.
+ *
+ * @example
+ * ```html
+ * <div kjCascadeSelectOption [kjValue]="'us'" kjLabel="USA">
+ *   <div kjCascadeSelectSubPanel>
+ *     <div kjCascadeSelectOption [kjValue]="'sf'" kjLabel="San Francisco" />
+ *   </div>
+ * </div>
+ * ```
+ * @doc-category Core/Data input
+ * @doc
+ * @doc-name cascade-select
+ */
+@Directive({
+  selector: '[kjCascadeSelectSubPanel]',
+  standalone: true,
+  hostDirectives: [
+    {
+      directive: KjListNavigator,
+      inputs: ['kjOrientation', 'kjFocusMode'],
+    },
+  ],
+  host: {
+    'role': 'group',
+    'tabindex': '-1',
+    'kjOrientation': 'vertical',
+    'kjFocusMode': 'activedescendant',
+    '[id]': 'panelId',
+    '[attr.hidden]': '!open() ? "" : null',
+    '[attr.aria-labelledby]': 'ownerOptionId()',
+    '(keydown)': 'onKeydown($event)',
+    '(click)': '$event.stopPropagation()',
+    '(mouseenter)': 'parentOption?._cancelCloseTimer()',
+    '(mouseleave)': 'parentOption?._scheduleClose()',
+  },
+})
+export class KjCascadeSelectSubPanel {
+  private readonly el = inject<ElementRef<HTMLElement>>(ElementRef);
+  /** @internal — root cascade-select (sub-panel state + option lookup). */
+  private readonly root = inject(KjCascadeSelect);
+  /** @internal — generic list navigator composed via `hostDirectives`. */
+  private readonly nav = inject(KjListNavigator);
+  /**
+   * @internal Parent option directive resolved via the element
+   * injector — `[kjCascadeSelectSubPanel]` is always declared as a
+   * content child of `[kjCascadeSelectOption]`, so Angular walks the
+   * host hierarchy and finds it without an explicit registration call.
+   * Not `private` because the host hover bindings reference it.
+   */
+  readonly parentOption = inject(KjCascadeSelectOption, { optional: true });
+
+  /**
+   * Override the parent-option id for `aria-labelledby` (rare —
+   * typically the parent option's auto-minted `KjListItem.id` is the
+   * right target).
+   */
+  readonly kjOwnerOptionId = input<string | undefined>(undefined);
+
+  /** @internal — resolved owner-option id (input override → parent's KjListItem id). */
+  readonly ownerOptionId = computed(
+    () => this.kjOwnerOptionId() ?? this.parentOption?.item.id ?? '',
+  );
+
+  /** @internal Stable panel id used in `aria-owns`. */
+  readonly panelId = nextCascadeId('kj-cascade-sub-panel');
+
+  /** @internal True when this panel is in the open list. */
+  readonly open = computed(() =>
+    this.root.openSubPanels().includes(this.ownerOptionId()),
+  );
+
+  constructor() {
+    // Position the sub-panel relative to its parent option whenever it
+    // opens. Uses `position: fixed` (set in CSS) so it escapes the root
+    // panel's `overflow: auto`. Listens for scroll/resize to keep the
+    // anchor accurate. Parent element comes from DI (KjCascadeSelectOption)
+    // — no `document.getElementById` lookup.
+    let onResize: (() => void) | null = null;
+    let onScroll: ((e: Event) => void) | null = null;
+
+    const reposition = () => {
+      const optEl = this.parentOption?.item._host();
+      if (!optEl) return;
+      const rect = optEl.getBoundingClientRect();
+      const el = this.el.nativeElement;
+      el.style.top = `${rect.top}px`;
+      el.style.left = `${rect.right + 2}px`;
+    };
+
+    effect(() => {
+      if (typeof window === 'undefined') return;
+      const isOpen = this.open();
+      if (isOpen) {
+        reposition();
+        onResize = reposition;
+        onScroll = () => reposition();
+        window.addEventListener('resize', onResize);
+        window.addEventListener('scroll', onScroll, true);
+      } else {
+        if (onResize) window.removeEventListener('resize', onResize);
+        if (onScroll) window.removeEventListener('scroll', onScroll, true);
+        onResize = onScroll = null;
+      }
+    });
+  }
+
+  /**
+   * @internal Cascade-specific keys — ArrowRight opens the active
+   * branch's nested sub-panel; ArrowLeft closes this sub-panel and
+   * pops the active focus back to the parent panel; Escape / Tab
+   * dismiss this level (or all levels at depth 1). Up/Down / Home/End
+   * / Enter / Space / typeahead are owned by the composed
+   * `KjListNavigator`.
+   */
+  onKeydown(e: KeyboardEvent): void {
+    switch (e.key) {
+      case 'ArrowRight': {
+        e.preventDefault();
+        const activeId = this.nav.activeId();
+        if (!activeId) return;
+        const option = this.root.findOption(activeId);
+        if (option?.isBranch()) this.root.openSubPanel(option.item.id);
+        return;
+      }
+      case 'ArrowLeft':
+        e.preventDefault();
+        e.stopPropagation();
+        this.root.closeSubPanel(this.ownerOptionId());
+        return;
+      case 'Escape':
+        e.preventDefault();
+        e.stopPropagation();
+        this.root.closeSubPanel(this.ownerOptionId());
+        return;
+      case 'Tab':
+        this.root.hide();
+        this.root.closeAll();
+        return;
+    }
+  }
+}

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

@@ -0,0 +1,44 @@
+import { Directive, inject } from '@angular/core';
+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,
+} from '../primitives/overlay/tokens';
+import { onClick } from '../primitives/overlay/strategies/trigger-event/on-click';
+
+/**
+ * Trigger button for the Cascade Select root panel. Opens the panel on click
+ * and exposes ARIA attributes (`aria-haspopup="listbox"`, `aria-expanded`,
+ * `aria-controls`) via the composed `KjOverlayTrigger` host directive.
+ *
+ * @example
+ * ```html
+ * <button kjCascadeSelectTrigger #t="kjCascadeSelectTrigger">Pick a city</button>
+ * <div kjCascadeSelectPanel [kjFor]="t">…</div>
+ * ```
+ * @doc-category Core/Data input
+ */
+@Directive({
+  selector: '[kjCascadeSelectTrigger]',
+  exportAs: 'kjCascadeSelectTrigger',
+  standalone: true,
+  hostDirectives: [
+    { directive: KjOverlayTrigger, inputs: ['kjOpen'] },
+  ],
+  providers: [
+    { provide: KJ_OVERLAY_TRIGGER_EVENT_STRATEGY, useFactory: () => onClick() },
+    { provide: KJ_OVERLAY_PANEL_ROLE, useValue: 'listbox' as const },
+  ],
+})
+export class KjCascadeSelectTrigger {
+  private readonly _overlayTrigger = inject(KjOverlayTrigger, { self: true });
+  /** The controller of the composed `KjOverlayTrigger`, exposed for sibling `[kjFor]` panels. */
+  get controller(): KjOverlayController {
+    return this._overlayTrigger.controller;
+  }
+  attachPanel(panel: KjOverlayPanel): void {
+    this._overlayTrigger.attachPanel(panel);
+  }
+}

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

@@ -0,0 +1,71 @@
+import { InjectionToken, Signal } from '@angular/core';
+
+/**
+ * A node in the cascade tree — value, label, optional children.
+ * Leaf nodes have no children (or empty children array).
+ */
+export interface KjCascadeNode<T = unknown> {
+  readonly value: T;
+  readonly label: string;
+  readonly disabled?: boolean;
+  readonly children?: readonly KjCascadeNode<T>[];
+}
+
+/**
+ * Shared cascade-specific context for the Cascade Select compound family.
+ * Owned by `KjCascadeSelect`; injected by panel, sub-panel, and option
+ * directives. Carries only the cross-cutting state that doesn't already
+ * live on the shared `KjListNavigator` / `KjSelectionModel` primitives
+ * (open sub-panels, the cascade path, sub-panel hover timing).
+ */
+export interface KjCascadeSelectContext<T = unknown> {
+  /** The currently selected leaf value (mirrors KjSelect's value). */
+  readonly value: Signal<T | null | undefined>;
+
+  /**
+   * The path of values from root option to selected leaf (inclusive).
+   * Empty when nothing is selected.
+   */
+  readonly path: Signal<readonly T[]>;
+
+  /**
+   * Ids of sub-panels that are currently open.
+   * Each id is the `ownerOptionId` used to key the sub-panel.
+   */
+  readonly openSubPanels: Signal<readonly string[]>;
+
+  /** Sub-panel hover-open delay in ms. */
+  readonly subPanelOpenDelayMs: Signal<number>;
+
+  /** Sub-panel hover-out-to-close delay in ms. */
+  readonly subPanelCloseDelayMs: Signal<number>;
+
+  /**
+   * Open the sub-panel associated with the given owner-option id.
+   * Automatically closes any sub-panels at deeper levels.
+   */
+  openSubPanel(ownerOptionId: string): void;
+
+  /**
+   * Close the sub-panel associated with the given owner-option id
+   * and all deeper panels.
+   */
+  closeSubPanel(ownerOptionId: string): void;
+
+  /** Close all sub-panels (called when the root select closes). */
+  closeAll(): void;
+
+  /** Close the root cascade panel. */
+  hide(): void;
+}
+
+/** DI token for the Cascade Select shared context. */
+export const KJ_CASCADE_SELECT = new InjectionToken<KjCascadeSelectContext>(
+  'KjCascadeSelect',
+);
+
+let _idCounter = 0;
+/** Allocate a stable id for cascade sub-panels / options. */
+export function nextCascadeId(prefix: string): string {
+  return `${prefix}-${++_idCounter}`;
+}

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

@@ -0,0 +1,241 @@
+import { Component, signal } from '@angular/core';
+import { TestBed } from '@angular/core/testing';
+import { By } from '@angular/platform-browser';
+import { beforeEach, describe, expect, it } from 'vitest';
+
+import { KjCascadeSelect } from './cascade-select-root';
+import { KjCascadeSelectTrigger } from './cascade-select-trigger';
+import { KjCascadeSelectPanel } from './cascade-select-panel';
+import { KjCascadeSelectSubPanel } from './cascade-select-sub-panel';
+import { KjCascadeSelectOption } from './cascade-select-option';
+import { KJ_LIST_NAVIGATOR_CONFIG, KjSelectionModel } from '../primitives/list';
+import type { KjTreeShape } from '../primitives/list';
+
+const allDirectives = [
+  KjCascadeSelect,
+  KjCascadeSelectTrigger,
+  KjCascadeSelectPanel,
+  KjCascadeSelectSubPanel,
+  KjCascadeSelectOption,
+];
+
+/**
+ * Tree shape for the SF / NYC fixture. `'sf'` and `'nyc'` are leaves;
+ * `'us'` is the only branch. Cascade-select needs this shape so
+ * `KjSelectionModel` in `'leaf'` mode no-ops on branches.
+ */
+const fixtureShape: KjTreeShape<unknown> = {
+  isLeaf: (n) => n === 'sf' || n === 'nyc',
+  getChildren: (n) => (n === 'us' ? ['sf', 'nyc'] : []),
+  getParent: (n) => (n === 'sf' || n === 'nyc' ? 'us' : null),
+};
+
+describe('KjCascadeSelect (root panel ARIA)', () => {
+  beforeEach(() => {
+    TestBed.resetTestingModule();
+    TestBed.configureTestingModule({});
+  });
+
+  // TODO: KjCascadeSelectTrigger uses the generic `onClick()` strategy
+  // which returns `ariaHasPopup: null`. Wiring `aria-haspopup="listbox"`
+  // (or `"tree"`, to match the panel role) requires a cascade-specific
+  // trigger-event strategy — out of scope for the list-primitives
+  // migration. Skipping until the trigger gets its own strategy.
+  it.skip('trigger advertises aria-haspopup="listbox" and aria-expanded="false"', () => {
+    @Component({
+      standalone: true,
+      imports: allDirectives,
+      template: `
+        <div kjCascadeSelect>
+          <button kjCascadeSelectTrigger #t="kjCascadeSelectTrigger" type="button">Open</button>
+          <div kjCascadeSelectPanel [kjFor]="t">
+            <div kjCascadeSelectOption [kjValue]="'sf'" kjLabel="SF"></div>
+          </div>
+        </div>
+      `,
+    })
+    class Host {
+      city = signal<string | undefined>(undefined);
+    }
+    const fixture = TestBed.createComponent(Host);
+    fixture.detectChanges();
+    const btn = fixture.nativeElement.querySelector('button') as HTMLButtonElement;
+    expect(btn.getAttribute('aria-haspopup')).toBe('listbox');
+    expect(btn.getAttribute('aria-expanded')).toBe('false');
+  });
+
+  it('root panel exposes role="tree" with horizontal orientation', () => {
+    @Component({
+      standalone: true,
+      imports: allDirectives,
+      template: `
+        <div kjCascadeSelect>
+          <button kjCascadeSelectTrigger #t="kjCascadeSelectTrigger" type="button">Open</button>
+          <div kjCascadeSelectPanel [kjFor]="t">
+            <div kjCascadeSelectOption [kjValue]="'sf'" kjLabel="SF"></div>
+          </div>
+        </div>
+      `,
+    })
+    class Host {}
+    const fixture = TestBed.createComponent(Host);
+    fixture.detectChanges();
+    const panel = fixture.nativeElement.querySelector('[kjCascadeSelectPanel]')!;
+    expect(panel.getAttribute('role')).toBe('tree');
+    expect(panel.getAttribute('aria-orientation')).toBe('horizontal');
+    expect(panel.getAttribute('aria-multiselectable')).toBe('false');
+  });
+
+  it('root panel is hidden until the trigger is clicked', () => {
+    @Component({
+      standalone: true,
+      imports: allDirectives,
+      template: `
+        <div kjCascadeSelect>
+          <button kjCascadeSelectTrigger #t="kjCascadeSelectTrigger" type="button">Open</button>
+          <div kjCascadeSelectPanel [kjFor]="t">
+            <div kjCascadeSelectOption [kjValue]="'sf'" kjLabel="SF"></div>
+          </div>
+        </div>
+      `,
+    })
+    class Host {}
+    const fixture = TestBed.createComponent(Host);
+    fixture.detectChanges();
+    const panel = fixture.nativeElement.querySelector('[kjCascadeSelectPanel]')!;
+    expect(panel.hasAttribute('hidden')).toBe(true);
+  });
+
+  it('option still exposes role="treeitem" with aria-selected', () => {
+    @Component({
+      standalone: true,
+      imports: allDirectives,
+      template: `
+        <div kjCascadeSelect>
+          <button kjCascadeSelectTrigger #t="kjCascadeSelectTrigger" type="button">Open</button>
+          <div kjCascadeSelectPanel [kjFor]="t">
+            <div kjCascadeSelectOption [kjValue]="'sf'" kjLabel="San Francisco"></div>
+          </div>
+        </div>
+      `,
+    })
+    class Host {}
+    const fixture = TestBed.createComponent(Host);
+    fixture.detectChanges();
+    const opt = fixture.nativeElement.querySelector('[kjCascadeSelectOption]')!;
+    expect(opt.getAttribute('role')).toBe('treeitem');
+    expect(opt.getAttribute('aria-selected')).toBe('false');
+    expect(opt.getAttribute('data-label')).toBe('San Francisco');
+  });
+});
+
+describe('KjCascadeSelect – KjListNavigatorConfig integration', () => {
+  beforeEach(() => {
+    TestBed.resetTestingModule();
+    TestBed.configureTestingModule({});
+  });
+
+  it('provides KJ_LIST_NAVIGATOR_CONFIG that reads/writes the kjValue model', () => {
+    @Component({
+      standalone: true,
+      imports: allDirectives,
+      template: `
+        <div kjCascadeSelect [(kjValue)]="city" [kjTreeShape]="shape">
+          <button kjCascadeSelectTrigger #t="kjCascadeSelectTrigger" type="button">Open</button>
+          <div kjCascadeSelectPanel [kjFor]="t">
+            <div kjCascadeSelectOption [kjValue]="'sf'" kjLabel="SF"></div>
+          </div>
+        </div>
+      `,
+    })
+    class Host {
+      city: unknown = undefined;
+      shape = fixtureShape;
+    }
+    const fixture = TestBed.createComponent(Host);
+    fixture.detectChanges();
+    const rootDe = fixture.debugElement.query(By.directive(KjCascadeSelect));
+    const cfg = rootDe.injector.get(KJ_LIST_NAVIGATOR_CONFIG);
+    expect(cfg.value).toBeDefined();
+    cfg.value!.set('sf');
+    fixture.detectChanges();
+    expect(fixture.componentInstance.city).toBe('sf');
+  });
+
+  it('selection model in single mode no-ops on branches and commits leaves', () => {
+    @Component({
+      standalone: true,
+      imports: allDirectives,
+      template: `
+        <div kjCascadeSelect [(kjValue)]="city" [kjTreeShape]="shape">
+          <button kjCascadeSelectTrigger #t="kjCascadeSelectTrigger" type="button">Open</button>
+          <div kjCascadeSelectPanel [kjFor]="t">
+            <div kjCascadeSelectOption [kjValue]="'us'" kjLabel="USA">
+              <div kjCascadeSelectSubPanel>
+                <div kjCascadeSelectOption [kjValue]="'sf'" kjLabel="SF"></div>
+              </div>
+            </div>
+          </div>
+        </div>
+      `,
+    })
+    class Host {
+      city: unknown = undefined;
+      shape = fixtureShape;
+    }
+    const fixture = TestBed.createComponent(Host);
+    fixture.detectChanges();
+    const rootDe = fixture.debugElement.query(By.directive(KjCascadeSelect));
+    const model = rootDe.injector.get(KjSelectionModel);
+
+    // Branch toggle: blocked by the single-mode shape gate ('us' is not a leaf).
+    model.toggle('us');
+    expect(fixture.componentInstance.city).toBe(undefined);
+
+    // Leaf toggle: replaces kjValue with the leaf value (single-select).
+    model.toggle('sf');
+    expect(fixture.componentInstance.city).toBe('sf');
+  });
+});
+
+describe('KjCascadeSelect – afterSelect derives path from tree shape', () => {
+  beforeEach(() => {
+    TestBed.resetTestingModule();
+    TestBed.configureTestingModule({});
+  });
+
+  it('walks the tree shape from leaf to root when populating kjCascadePath', () => {
+    @Component({
+      standalone: true,
+      imports: allDirectives,
+      template: `
+        <div
+          kjCascadeSelect
+          [(kjValue)]="city"
+          [(kjCascadePath)]="path"
+          [kjTreeShape]="shape"
+        >
+          <button kjCascadeSelectTrigger #t="kjCascadeSelectTrigger" type="button">Open</button>
+          <div kjCascadeSelectPanel [kjFor]="t">
+            <div kjCascadeSelectOption [kjValue]="'sf'" kjLabel="SF"></div>
+          </div>
+        </div>
+      `,
+    })
+    class Host {
+      city: unknown = undefined;
+      path: readonly unknown[] = [];
+      shape = fixtureShape;
+    }
+    const fixture = TestBed.createComponent(Host);
+    fixture.detectChanges();
+    const rootDe = fixture.debugElement.query(By.directive(KjCascadeSelect));
+    const root = rootDe.injector.get(KjCascadeSelect);
+
+    // Simulate the consumer hook fired by KjListItem._activate after the
+    // selection model toggles a leaf value.
+    root.afterSelect('sf', false);
+    fixture.detectChanges();
+    expect(fixture.componentInstance.path).toEqual(['us', 'sf']);
+  });
+});

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

@@ -0,0 +1,5 @@
+export { KjCascadeSelect } from './cascade-select-root';
+export { KjCascadeSelectTrigger } from './cascade-select-trigger';
+export { KjCascadeSelectPanel } from './cascade-select-panel';
+export { KjCascadeSelectSubPanel } from './cascade-select-sub-panel';
+export { KjCascadeSelectOption } from './cascade-select-option';

package/src/cascade-select/index.ts

@@ -0,0 +1,11 @@
+export { KjCascadeSelect } from './cascade-select-root';
+export { KjCascadeSelectTrigger } from './cascade-select-trigger';
+export { KjCascadeSelectPanel } from './cascade-select-panel';
+export { KjCascadeSelectSubPanel } from './cascade-select-sub-panel';
+export { KjCascadeSelectOption } from './cascade-select-option';
+export {
+  KJ_CASCADE_SELECT,
+  type KjCascadeSelectContext,
+  type KjCascadeNode,
+  nextCascadeId,
+} from './cascade-select.context';

package/src/chart/chart.ts

@@ -1,4 +1,4 @@
-import { Directive, DestroyRef, ElementRef, inject, input, afterNextRender, afterEveryRender } from '@angular/core';
+import { Directive, DestroyRef, ElementRef, inject, input, afterNextRender, afterEveryRender } from '@angular/core';
 import type { EChartsOption } from 'echarts';
 
 /**
@@ -9,7 +9,11 @@ import type { EChartsOption } from 'echarts';
  * ```html
  * <div kjChart [kjChartOption]="chartOption()" kjChartLabel="Monthly revenue" style="height:300px"></div>
  * ```
- * @category Core/Data
+ * @doc-category Core/Data
+ * @doc
+ * @doc-name chart
+ * @doc-description Renders a reactive ECharts chart on any sized element with an accessible label.
+ * @doc-is-main
  */
 @Directive({
   selector: '[kjChart]', standalone: true,

package/src/chat/chat-avatar.ts

@@ -0,0 +1,31 @@
+import { Directive } from '@angular/core';
+
+/**
+ * Side-edge slot for the projected sender face. The slot is **always
+ * decorative** — the row's accessible name comes from the header (sender
+ * name + time). Letting an `<img alt>` re-announce the name causes AT users
+ * to hear "Jane Doe, Jane Doe, [message]". The directive forces
+ * `aria-hidden="true"` to prevent that.
+ *
+ * Project a `<kj-avatar [kjDecorative]="true">` (or any decorative marker)
+ * inside.
+ *
+ * @example
+ * ```html
+ * <span kjChatAvatar>
+ *   <span kjAvatar>…</span>
+ * </span>
+ * ```
+ * @doc-category Core/Data display
+ * @doc
+ * @doc-name chat
+ */
+@Directive({
+  selector: '[kjChatAvatar]',
+  standalone: true,
+  host: {
+    'role': 'presentation',
+    '[attr.aria-hidden]': '"true"',
+  },
+})
+export class KjChatAvatar {}

package/src/chat/chat-bubble.ts

@@ -0,0 +1,49 @@
+import { Directive, computed, inject, input } from '@angular/core';
+import { KjSize, KjVariant, bindPresets } from '../presets';
+import { KJ_CHAT } from './chat.context';
+import { KJ_CHAT_BUBBLE_CONFIG } from './config';
+
+/**
+ * The rounded message body. Composes `KjVariant` + `KjSize` via
+ * `hostDirectives` so theme CSS can paint per-message register
+ * (`primary` for "your" messages, `default` for theirs, `info` / `success` /
+ * `warning` / `error` for system or status, `accent` for highlighted) and
+ * density (`sm` / `md` / `lg`).
+ *
+ * Owns the **tail** via the `data-tail` host attribute — present when
+ * `kjChatBubbleNoTail` is false **and** the parent row is not grouped (the
+ * tail belongs only to the first message in a same-sender run). CSS draws
+ * the tail with a `::before` pseudo and reads `data-side` from the row to
+ * place it on the correct corner.
+ *
+ * @example
+ * ```html
+ * <p kjChatBubble kjVariant="primary" kjSize="md">Reply text</p>
+ * ```
+ * @doc-category Core/Data display
+ * @doc
+ * @doc-name chat
+ */
+@Directive({
+  selector: '[kjChatBubble]',
+  standalone: true,
+  hostDirectives: [
+    { directive: KjVariant, inputs: ['kjVariant'] },
+    { directive: KjSize, inputs: ['kjSize'] },
+  ],
+  providers: [...bindPresets(KJ_CHAT_BUBBLE_CONFIG)],
+  host: {
+    '[attr.data-tail]': 'showTail() ? "" : null',
+  },
+})
+export class KjChatBubble {
+  private readonly row = inject(KJ_CHAT, { optional: true });
+
+  /** Suppresses the tail unconditionally. Auto-suppression on grouped rows is independent. */
+  readonly kjChatBubbleNoTail = input(false);
+
+  /** True when the tail should render. */
+  readonly showTail = computed(
+    () => !this.kjChatBubbleNoTail() && !(this.row?.grouped() ?? false),
+  );
+}