@kouji-ui/core 0.0.3 → 0.1.1

package/src/chat/chat-footer.ts

@@ -0,0 +1,67 @@
+import { DestroyRef, Directive, computed, inject, input } from '@angular/core';
+import { KJ_CHAT, nextChatFooterId, type KjChatState } from './chat.context';
+
+const STATE_LABEL: Readonly<Record<KjChatState, string>> = {
+  sending: 'Sending',
+  sent: 'Sent',
+  delivered: 'Delivered',
+  read: 'Read',
+  error: 'Failed to send',
+};
+
+/**
+ * Mints a stable id for the chat row's footer and registers it with the
+ * parent `KjChat` so the row's host `aria-describedby` references it.
+ *
+ * Reflects `kjState` to a `data-state` host attribute that components-package
+ * CSS reads to paint a status glyph (clock / single-check / double-check /
+ * filled-double-check / exclamation). Also injects an `aria-label` so the
+ * description is intelligible to AT even when the glyph is the only visible
+ * content.
+ *
+ * Free-form text ("Seen 12:46") is fine too — leave `kjState` undefined and
+ * the directive renders only the consumer's projected content.
+ *
+ * @example
+ * ```html
+ * <footer kjChatFooter kjState="read">Read 12:46</footer>
+ * ```
+ * @doc-category Core/Data display
+ * @doc
+ * @doc-name chat
+ */
+@Directive({
+  selector: '[kjChatFooter]',
+  standalone: true,
+  host: {
+    '[id]': 'id',
+    '[attr.data-state]': 'kjState() ?? null',
+    '[attr.aria-label]': 'ariaLabel()',
+  },
+})
+export class KjChatFooter {
+  private readonly chat = inject(KJ_CHAT, { optional: true });
+  private readonly destroyRef = inject(DestroyRef);
+
+  /** Auto-generated id used for the parent row's `aria-describedby`. */
+  readonly id = nextChatFooterId();
+
+  /**
+   * Read / delivery state. Drives `data-state` for the glyph and an injected
+   * `aria-label` for AT. When undefined, only projected content renders.
+   */
+  readonly kjState = input<KjChatState | undefined>(undefined);
+
+  /** Aria label derived from `kjState`. `null` when no state is set. */
+  readonly ariaLabel = computed(() => {
+    const s = this.kjState();
+    return s ? STATE_LABEL[s] : null;
+  });
+
+  constructor() {
+    if (this.chat) {
+      this.chat.registerFooterId(this.id);
+      this.destroyRef.onDestroy(() => this.chat?.unregisterFooterId(this.id));
+    }
+  }
+}

package/src/chat/chat-header.ts

@@ -0,0 +1,41 @@
+import { DestroyRef, Directive, inject } from '@angular/core';
+import { KJ_CHAT, nextChatHeaderId } from './chat.context';
+
+/**
+ * Mints a stable id for the chat row's header and registers it with the
+ * parent `KjChat` so the row's host `aria-labelledby` attribute references
+ * the sender's name + time. Visual chrome (small font, muted colour, spacing
+ * above the bubble) belongs to CSS; the directive does not paint.
+ *
+ * Standalone (no `KjChat` parent) the directive still mints an id but no
+ * wiring fires — the consumer is responsible for the link.
+ *
+ * @example
+ * ```html
+ * <header kjChatHeader>Alice <time datetime="…">12:46</time></header>
+ * ```
+ * @doc-category Core/Data display
+ * @doc
+ * @doc-name chat
+ */
+@Directive({
+  selector: '[kjChatHeader]',
+  standalone: true,
+  host: {
+    '[id]': 'id',
+  },
+})
+export class KjChatHeader {
+  private readonly chat = inject(KJ_CHAT, { optional: true });
+  private readonly destroyRef = inject(DestroyRef);
+
+  /** Auto-generated id used for the parent row's `aria-labelledby`. */
+  readonly id = nextChatHeaderId();
+
+  constructor() {
+    if (this.chat) {
+      this.chat.registerHeaderId(this.id);
+      this.destroyRef.onDestroy(() => this.chat?.unregisterHeaderId(this.id));
+    }
+  }
+}

package/src/chat/chat-log.ts

@@ -0,0 +1,43 @@
+import { Directive, input } from '@angular/core';
+import { KJ_CHAT_LOG, type KjChatLogContext } from './chat.context';
+
+/**
+ * Container for a stream of `[kjChat]` rows. Owns the live region: per APG's
+ * Log pattern, the **container** announces new arrivals — never the bubble
+ * itself. Default `aria-live="polite"` matches the chat-app convention; we
+ * deliberately do not expose `'assertive'` (it would interrupt the user
+ * mid-typing on every inbound message and is the canonical chat-app a11y bug).
+ *
+ * `aria-relevant="additions"` confines announcements to *new* messages so that
+ * edits to existing bubbles don't re-announce the full edited content.
+ *
+ * @example
+ * ```html
+ * <div kjChatLog kjChatLogLabel="Conversation with Alice">
+ *   <div kjChat kjSide="start" kjChatAuthor="alice">…</div>
+ *   <div kjChat kjSide="end"   kjChatAuthor="me">…</div>
+ * </div>
+ * ```
+ * @doc-category Core/Data display
+ * @doc
+ * @doc-name chat
+ */
+@Directive({
+  selector: '[kjChatLog]',
+  standalone: true,
+  providers: [{ provide: KJ_CHAT_LOG, useExisting: KjChatLog }],
+  host: {
+    'role': 'log',
+    '[attr.aria-live]': 'kjChatLogLive()',
+    '[attr.aria-relevant]': '"additions"',
+    '[attr.aria-atomic]': '"false"',
+    '[attr.aria-label]': 'kjChatLogLabel() ?? null',
+  },
+})
+export class KjChatLog implements KjChatLogContext {
+  /** Live-region politeness. `'polite'` (default) or `'off'`. */
+  readonly kjChatLogLive = input<'polite' | 'off'>('polite');
+
+  /** Optional `aria-label` for the log landmark. */
+  readonly kjChatLogLabel = input<string | undefined>(undefined);
+}

package/src/chat/chat.context.ts

@@ -0,0 +1,64 @@
+import { InjectionToken, type Signal } from '@angular/core';
+
+/** Logical side of a chat row. CSS handles the physical RTL flip via cascade. */
+export type KjChatSide = 'start' | 'end';
+
+/**
+ * Per-row role override. Default `'article'` gives screen readers a per-message
+ * landmark; `'listitem'` opts in to list semantics (parent log must then carry
+ * `role="list"`); `null` drops the role attribute entirely.
+ */
+export type KjChatRole = 'article' | 'listitem' | null;
+
+/** Read / delivery state machine for the footer. */
+export type KjChatState =
+  | 'sending'
+  | 'sent'
+  | 'delivered'
+  | 'read'
+  | 'error';
+
+/** Context shape exposed by `KjChatLog` to descendant chat directives. */
+export interface KjChatLogContext {
+  /** Reflected to `aria-live`. `'polite'` (default) or `'off'`. */
+  readonly kjChatLogLive: Signal<'polite' | 'off'>;
+  /** Optional landmark label for the log. */
+  readonly kjChatLogLabel: Signal<string | undefined>;
+}
+
+/**
+ * Context shape exposed by `KjChat` to its child directives. Children read this
+ * to register their minted ids (header / footer) for `aria-labelledby` /
+ * `aria-describedby` wiring, and to ask whether the row is part of a grouped
+ * run for tail / avatar suppression.
+ */
+export interface KjChatContext {
+  readonly kjSide: Signal<KjChatSide>;
+  readonly kjChatAuthor: Signal<string | undefined>;
+  /** True when this row is grouped with the previous row (same author). */
+  readonly grouped: Signal<boolean>;
+  /** Register a header id; the row reflects it as `aria-labelledby`. */
+  registerHeaderId(id: string): void;
+  unregisterHeaderId(id: string): void;
+  /** Register a footer id; the row reflects it as `aria-describedby`. */
+  registerFooterId(id: string): void;
+  unregisterFooterId(id: string): void;
+}
+
+/** Injection token for the `KjChatLog` container. */
+export const KJ_CHAT_LOG = new InjectionToken<KjChatLogContext>('KjChatLog');
+
+/** Injection token for the `KjChat` row. */
+export const KJ_CHAT = new InjectionToken<KjChatContext>('KjChat');
+
+let _chatHeaderIdCounter = 0;
+/** Allocate a stable id used for `aria-labelledby` wiring. */
+export function nextChatHeaderId(): string {
+  return `kj-chat-header-${++_chatHeaderIdCounter}`;
+}
+
+let _chatFooterIdCounter = 0;
+/** Allocate a stable id used for `aria-describedby` wiring. */
+export function nextChatFooterId(): string {
+  return `kj-chat-footer-${++_chatFooterIdCounter}`;
+}

package/src/chat/chat.spec.ts

@@ -0,0 +1,341 @@
+import { render } from '@testing-library/angular';
+import { axe, toHaveNoViolations } from 'jest-axe';
+import { describe, expect, it } from 'vitest';
+import { KjChat } from './chat';
+import { KjChatAvatar } from './chat-avatar';
+import { KjChatBubble } from './chat-bubble';
+import { KjChatFooter } from './chat-footer';
+import { KjChatHeader } from './chat-header';
+import { KjChatLog } from './chat-log';
+import { provideKjChatBubble } from './config';
+
+expect.extend(toHaveNoViolations);
+
+const imports = [
+  KjChatLog,
+  KjChat,
+  KjChatAvatar,
+  KjChatHeader,
+  KjChatBubble,
+  KjChatFooter,
+];
+
+describe('KjChatLog', () => {
+  it('hosts role=log + aria-live=polite by default', async () => {
+    const { container } = await render(
+      `<div kjChatLog data-testid="log"></div>`,
+      { imports },
+    );
+    const log = container.querySelector('[data-testid="log"]')!;
+    expect(log).toHaveAttribute('role', 'log');
+    expect(log).toHaveAttribute('aria-live', 'polite');
+    expect(log).toHaveAttribute('aria-relevant', 'additions');
+    expect(log).toHaveAttribute('aria-atomic', 'false');
+  });
+
+  it('reflects kjChatLogLive=off', async () => {
+    const { container } = await render(
+      `<div kjChatLog kjChatLogLive="off" data-testid="log"></div>`,
+      { imports },
+    );
+    expect(container.querySelector('[data-testid="log"]')).toHaveAttribute(
+      'aria-live',
+      'off',
+    );
+  });
+
+  it('reflects kjChatLogLabel as aria-label', async () => {
+    const { container } = await render(
+      `<div kjChatLog kjChatLogLabel="Conversation with Alice" data-testid="log"></div>`,
+      { imports },
+    );
+    expect(container.querySelector('[data-testid="log"]')).toHaveAttribute(
+      'aria-label',
+      'Conversation with Alice',
+    );
+  });
+});
+
+describe('KjChat', () => {
+  it('default role is article', async () => {
+    const { container } = await render(
+      `<div kjChat data-testid="row"></div>`,
+      { imports },
+    );
+    expect(container.querySelector('[data-testid="row"]')).toHaveAttribute(
+      'role',
+      'article',
+    );
+  });
+
+  it('kjRole=listitem reflects on host', async () => {
+    const { container } = await render(
+      `<div kjChat kjRole="listitem" data-testid="row"></div>`,
+      { imports },
+    );
+    expect(container.querySelector('[data-testid="row"]')).toHaveAttribute(
+      'role',
+      'listitem',
+    );
+  });
+
+  it('kjRole=null drops the role attribute', async () => {
+    const { container } = await render(
+      `<div kjChat [kjRole]="null" data-testid="row"></div>`,
+      { imports },
+    );
+    expect(
+      container.querySelector('[data-testid="row"]'),
+    ).not.toHaveAttribute('role');
+  });
+
+  it('kjSide reflects to data-side', async () => {
+    const { container } = await render(
+      `<div kjChat kjSide="end" data-testid="row"></div>`,
+      { imports },
+    );
+    expect(container.querySelector('[data-testid="row"]')).toHaveAttribute(
+      'data-side',
+      'end',
+    );
+  });
+
+  it('auto-grouping marks the second same-author row with data-grouped', async () => {
+    const { container, fixture } = await render(
+      `<div kjChatLog>
+         <div kjChat kjChatAuthor="alice" data-testid="r1"></div>
+         <div kjChat kjChatAuthor="alice" data-testid="r2"></div>
+         <div kjChat kjChatAuthor="bob"   data-testid="r3"></div>
+       </div>`,
+      { imports },
+    );
+    fixture.detectChanges();
+    await fixture.whenStable();
+    fixture.detectChanges();
+    expect(
+      container.querySelector('[data-testid="r1"]'),
+    ).not.toHaveAttribute('data-grouped');
+    expect(container.querySelector('[data-testid="r2"]')).toHaveAttribute(
+      'data-grouped',
+      '',
+    );
+    expect(
+      container.querySelector('[data-testid="r3"]'),
+    ).not.toHaveAttribute('data-grouped');
+  });
+
+  it('explicit kjChatGrouped overrides auto-grouping', async () => {
+    const { container, fixture } = await render(
+      `<div kjChatLog>
+         <div kjChat kjChatAuthor="alice" data-testid="r1"></div>
+         <div kjChat kjChatAuthor="bob" [kjChatGrouped]="true" data-testid="r2"></div>
+       </div>`,
+      { imports },
+    );
+    fixture.detectChanges();
+    await fixture.whenStable();
+    expect(container.querySelector('[data-testid="r2"]')).toHaveAttribute(
+      'data-grouped',
+      '',
+    );
+  });
+
+  it('header/footer ids wire aria-labelledby and aria-describedby on the row', async () => {
+    const { container } = await render(
+      `<div kjChat data-testid="row">
+         <header kjChatHeader data-testid="h">Alice 12:46</header>
+         <p kjChatBubble>Hi</p>
+         <footer kjChatFooter data-testid="f">Sent</footer>
+       </div>`,
+      { imports },
+    );
+    const row = container.querySelector('[data-testid="row"]')!;
+    const header = container.querySelector('[data-testid="h"]')!;
+    const footer = container.querySelector('[data-testid="f"]')!;
+    expect(header.id).toMatch(/^kj-chat-header-\d+$/);
+    expect(footer.id).toMatch(/^kj-chat-footer-\d+$/);
+    expect(row.getAttribute('aria-labelledby')).toBe(header.id);
+    expect(row.getAttribute('aria-describedby')).toBe(footer.id);
+  });
+});
+
+describe('KjChatAvatar', () => {
+  it('forces aria-hidden=true', async () => {
+    const { container } = await render(
+      `<span kjChatAvatar data-testid="av"></span>`,
+      { imports },
+    );
+    const av = container.querySelector('[data-testid="av"]')!;
+    expect(av).toHaveAttribute('aria-hidden', 'true');
+    expect(av).toHaveAttribute('role', 'presentation');
+  });
+});
+
+describe('KjChatHeader / KjChatFooter', () => {
+  it('mint unique ids for two adjacent headers / footers', async () => {
+    const { container } = await render(
+      `<div kjChatLog>
+         <div kjChat>
+           <header kjChatHeader data-testid="h1">A</header>
+           <footer kjChatFooter data-testid="f1">x</footer>
+         </div>
+         <div kjChat>
+           <header kjChatHeader data-testid="h2">B</header>
+           <footer kjChatFooter data-testid="f2">y</footer>
+         </div>
+       </div>`,
+      { imports },
+    );
+    const h1 = container.querySelector('[data-testid="h1"]')!.id;
+    const h2 = container.querySelector('[data-testid="h2"]')!.id;
+    const f1 = container.querySelector('[data-testid="f1"]')!.id;
+    const f2 = container.querySelector('[data-testid="f2"]')!.id;
+    expect(h1).not.toEqual(h2);
+    expect(f1).not.toEqual(f2);
+    expect(h1).toMatch(/^kj-chat-header-/);
+    expect(f1).toMatch(/^kj-chat-footer-/);
+  });
+
+  it('footer reflects kjState as data-state and aria-label', async () => {
+    const { container } = await render(
+      `<footer kjChatFooter kjState="read" data-testid="f">Read 12:46</footer>`,
+      { imports },
+    );
+    const f = container.querySelector('[data-testid="f"]')!;
+    expect(f).toHaveAttribute('data-state', 'read');
+    expect(f).toHaveAttribute('aria-label', 'Read');
+  });
+
+  it('footer omits data-state and aria-label when kjState is unset', async () => {
+    const { container } = await render(
+      `<footer kjChatFooter data-testid="f">Sent 12:46</footer>`,
+      { imports },
+    );
+    const f = container.querySelector('[data-testid="f"]')!;
+    expect(f).not.toHaveAttribute('data-state');
+    expect(f).not.toHaveAttribute('aria-label');
+  });
+});
+
+describe('KjChatBubble', () => {
+  it('composes KjVariant -> data-variant default', async () => {
+    const { container } = await render(
+      `<p kjChatBubble data-testid="b">Hi</p>`,
+      { imports },
+    );
+    expect(container.querySelector('[data-testid="b"]')).toHaveAttribute(
+      'data-variant',
+      'default',
+    );
+  });
+
+  it('composes KjSize -> data-size default', async () => {
+    const { container } = await render(
+      `<p kjChatBubble data-testid="b">Hi</p>`,
+      { imports },
+    );
+    expect(container.querySelector('[data-testid="b"]')).toHaveAttribute(
+      'data-size',
+      'md',
+    );
+  });
+
+  it('forwards kjVariant + kjSize through hostDirectives', async () => {
+    const { container } = await render(
+      `<p kjChatBubble kjVariant="primary" kjSize="lg" data-testid="b">Hi</p>`,
+      { imports },
+    );
+    const b = container.querySelector('[data-testid="b"]')!;
+    expect(b).toHaveAttribute('data-variant', 'primary');
+    expect(b).toHaveAttribute('data-size', 'lg');
+  });
+
+  it('renders data-tail when not grouped and no-tail not set', async () => {
+    const { container } = await render(
+      `<div kjChat>
+         <p kjChatBubble data-testid="b">Hi</p>
+       </div>`,
+      { imports },
+    );
+    expect(container.querySelector('[data-testid="b"]')).toHaveAttribute(
+      'data-tail',
+      '',
+    );
+  });
+
+  it('omits data-tail when kjChatBubbleNoTail=true', async () => {
+    const { container } = await render(
+      `<div kjChat>
+         <p kjChatBubble [kjChatBubbleNoTail]="true" data-testid="b">Hi</p>
+       </div>`,
+      { imports },
+    );
+    expect(
+      container.querySelector('[data-testid="b"]'),
+    ).not.toHaveAttribute('data-tail');
+  });
+
+  it('omits data-tail when the parent row is auto-grouped', async () => {
+    const { container, fixture } = await render(
+      `<div kjChatLog>
+         <div kjChat kjChatAuthor="alice">
+           <p kjChatBubble data-testid="b1">A</p>
+         </div>
+         <div kjChat kjChatAuthor="alice">
+           <p kjChatBubble data-testid="b2">B</p>
+         </div>
+       </div>`,
+      { imports },
+    );
+    fixture.detectChanges();
+    await fixture.whenStable();
+    fixture.detectChanges();
+    expect(container.querySelector('[data-testid="b1"]')).toHaveAttribute(
+      'data-tail',
+      '',
+    );
+    expect(
+      container.querySelector('[data-testid="b2"]'),
+    ).not.toHaveAttribute('data-tail');
+  });
+
+  it('respects provideKjChatBubble preset overrides', async () => {
+    const { container } = await render(
+      `<p kjChatBubble data-testid="b">x</p>`,
+      {
+        imports,
+        providers: [
+          provideKjChatBubble({
+            variants: ['default', 'primary', 'brand'],
+            defaults: { variant: 'brand', size: 'md' },
+          }),
+        ],
+      },
+    );
+    expect(container.querySelector('[data-testid="b"]')).toHaveAttribute(
+      'data-variant',
+      'brand',
+    );
+  });
+});
+
+describe('a11y', () => {
+  it('passes axe audit on a populated chat log', async () => {
+    const { container } = await render(
+      `<div kjChatLog kjChatLogLabel="Test conversation">
+         <div kjChat kjSide="start" kjChatAuthor="alice">
+           <span kjChatAvatar></span>
+           <header kjChatHeader>Alice 12:46</header>
+           <p kjChatBubble>Hi there</p>
+           <footer kjChatFooter kjState="read">Read 12:46</footer>
+         </div>
+         <div kjChat kjSide="end" kjChatAuthor="me">
+           <p kjChatBubble kjVariant="primary">Hello back</p>
+           <footer kjChatFooter kjState="delivered">Delivered</footer>
+         </div>
+       </div>`,
+      { imports },
+    );
+    expect(await axe(container)).toHaveNoViolations();
+  });
+});