@kouji-ui/core 0.0.4 → 0.1.1

package/src/chat/chat.ts

@@ -0,0 +1,191 @@
+import {
+  DestroyRef,
+  Directive,
+  ElementRef,
+  Injector,
+  afterNextRender,
+  computed,
+  effect,
+  inject,
+  input,
+  signal,
+} from '@angular/core';
+import {
+  KJ_CHAT,
+  KJ_CHAT_LOG,
+  type KjChatContext,
+  type KjChatRole,
+  type KjChatSide,
+} from './chat.context';
+
+/**
+ * Element → directive map used by `KjChat` to walk previous siblings without
+ * relying on Angular dev-mode internals. Each row registers itself on its host
+ * element on construction and unregisters on destroy.
+ */
+const CHAT_ROW_REGISTRY = new WeakMap<Element, KjChat>();
+
+/**
+ * A single chat row. Owns the logical side, the per-row role, and the
+ * group-by-sender computation; reflects header / footer ids registered by
+ * its children for `aria-labelledby` / `aria-describedby` wiring.
+ *
+ * **Grouping uses DOM traversal, not a registry**, deliberately: the registry
+ * pattern races on the bottom-up `ngOnInit` order (children before parent),
+ * which means the first row could ask for its previous sibling before the
+ * previous row has registered. DOM traversal via `previousElementSibling` is
+ * deterministic and works at first render.
+ *
+ * Standalone rows (no `KjChatLog` parent) skip auto-grouping entirely;
+ * consumers set `kjChatGrouped` explicitly when they want grouped chrome.
+ *
+ * @example
+ * ```html
+ * <div kjChat kjSide="start" kjChatAuthor="alice">
+ *   <span kjChatAvatar>…</span>
+ *   <header kjChatHeader>Alice 12:46</header>
+ *   <p kjChatBubble>Hey!</p>
+ *   <footer kjChatFooter kjState="read">Read 12:46</footer>
+ * </div>
+ * ```
+ * @doc-category Core/Data display
+ * @doc
+ * @doc-name chat
+ * @doc-description Unstyled chat row with side, sender grouping, and ARIA wiring for message log semantics.
+ * @doc-is-main
+ */
+@Directive({
+  selector: '[kjChat]',
+  standalone: true,
+  providers: [{ provide: KJ_CHAT, useExisting: KjChat }],
+  host: {
+    '[attr.role]': 'kjRole()',
+    '[attr.data-side]': 'kjSide()',
+    '[attr.data-grouped]': 'grouped() ? "" : null',
+    '[attr.aria-labelledby]': 'headerId() ?? null',
+    '[attr.aria-describedby]': 'footerId() ?? null',
+  },
+})
+export class KjChat implements KjChatContext {
+  private readonly el = inject<ElementRef<HTMLElement>>(ElementRef);
+  private readonly injector = inject(Injector);
+  private readonly destroyRef = inject(DestroyRef);
+  private readonly log = inject(KJ_CHAT_LOG, { optional: true });
+
+  /** Logical side of this row. CSS reads `data-side` and handles RTL flip. */
+  readonly kjSide = input<KjChatSide>('start');
+
+  /** Sender id — drives auto-grouping with the previous sibling row. */
+  readonly kjChatAuthor = input<string | undefined>(undefined);
+
+  /**
+   * Explicit group override. When defined, wins over the auto-computed value;
+   * use this when no `KjChatLog` parent is present.
+   */
+  readonly kjChatGrouped = input<boolean | undefined>(undefined);
+
+  /**
+   * Per-row role. Default `'article'` gives AT users a per-message landmark
+   * navigable via JAWS / NVDA `M`; `'listitem'` opts in to list semantics
+   * (parent log must then expose `role="list"`); `null` drops the attribute.
+   */
+  readonly kjRole = input<KjChatRole>('article');
+
+  private readonly headerIds = signal<readonly string[]>([]);
+  private readonly footerIds = signal<readonly string[]>([]);
+
+  /** Composed `aria-labelledby` value. */
+  readonly headerId = computed(() => {
+    const ids = this.headerIds();
+    return ids.length === 0 ? null : ids.join(' ');
+  });
+
+  /** Composed `aria-describedby` value. */
+  readonly footerId = computed(() => {
+    const ids = this.footerIds();
+    return ids.length === 0 ? null : ids.join(' ');
+  });
+
+  private readonly autoGrouped = signal(false);
+
+  /** True when this row groups with the previous one (same author). */
+  readonly grouped = computed(
+    () => this.kjChatGrouped() ?? this.autoGrouped(),
+  );
+
+  constructor() {
+    // Registry write happens in the constructor so any sibling rendered
+    // *after* us finds us during its own afterNextRender pass. (Angular
+    // builds child instances bottom-up, but DOM siblings are ordered
+    // top-down — by the time the second row's afterNextRender fires,
+    // the first row's host element exists and is keyed in the WeakMap.)
+    CHAT_ROW_REGISTRY.set(this.el.nativeElement, this);
+    this.destroyRef.onDestroy(() =>
+      CHAT_ROW_REGISTRY.delete(this.el.nativeElement),
+    );
+
+    // DOM-traversal grouping: run after first render (so the previous
+    // sibling exists) and re-run whenever this row's author changes.
+    afterNextRender(() => {
+      this.recomputeAutoGrouped();
+    });
+    effect(
+      () => {
+        // Track the input — touching it inside the effect creates the dep.
+        this.kjChatAuthor();
+        this.recomputeAutoGrouped();
+      },
+      { injector: this.injector },
+    );
+  }
+
+  /** @internal */
+  registerHeaderId(id: string): void {
+    this.headerIds.update(ids => [...ids, id]);
+    this.destroyRef.onDestroy(() => this.unregisterHeaderId(id));
+  }
+
+  /** @internal */
+  unregisterHeaderId(id: string): void {
+    this.headerIds.update(ids => ids.filter(x => x !== id));
+  }
+
+  /** @internal */
+  registerFooterId(id: string): void {
+    this.footerIds.update(ids => [...ids, id]);
+    this.destroyRef.onDestroy(() => this.unregisterFooterId(id));
+  }
+
+  /** @internal */
+  unregisterFooterId(id: string): void {
+    this.footerIds.update(ids => ids.filter(x => x !== id));
+  }
+
+  private recomputeAutoGrouped(): void {
+    if (!this.log) {
+      this.autoGrouped.set(false);
+      return;
+    }
+    const me = this.kjChatAuthor();
+    if (me === undefined) {
+      this.autoGrouped.set(false);
+      return;
+    }
+    const prev = this.previousChatRow();
+    if (!prev) {
+      this.autoGrouped.set(false);
+      return;
+    }
+    this.autoGrouped.set(prev.kjChatAuthor() === me);
+  }
+
+  private previousChatRow(): KjChat | null {
+    let sib = this.el.nativeElement.previousElementSibling as Element | null;
+    while (sib) {
+      const row = CHAT_ROW_REGISTRY.get(sib);
+      if (row) return row;
+      sib = sib.previousElementSibling;
+    }
+    return null;
+  }
+}

package/src/chat/config.ts

@@ -0,0 +1,53 @@
+import { InjectionToken, Provider } from '@angular/core';
+
+/** Shape of the bubble's preset configuration. */
+export interface KjChatBubbleConfig {
+  variants: string[];
+  sizes: string[];
+  defaults: { variant: string; size: string };
+}
+
+/**
+ * Default Chat-Bubble presets shipped by kouji-ui. Exported so consumers can
+ * spread when extending: `[...KJ_CHAT_BUBBLE_DEFAULTS.variants, 'brand']`.
+ */
+export const KJ_CHAT_BUBBLE_DEFAULTS: KjChatBubbleConfig = {
+  variants: [
+    'default',
+    'primary',
+    'secondary',
+    'accent',
+    'info',
+    'success',
+    'warning',
+    'error',
+  ],
+  sizes: ['sm', 'md', 'lg'],
+  defaults: { variant: 'default', size: 'md' },
+};
+
+/**
+ * DI token for the active Chat-Bubble presets. Default factory yields
+ * `KJ_CHAT_BUBBLE_DEFAULTS`. Override via `provideKjChatBubble(…)` at the
+ * application or component scope.
+ */
+export const KJ_CHAT_BUBBLE_CONFIG = new InjectionToken<KjChatBubbleConfig>(
+  'kj.chat-bubble.config',
+  { factory: () => KJ_CHAT_BUBBLE_DEFAULTS },
+);
+
+/**
+ * Configures the Chat-Bubble presets for the enclosing injector. Replaces
+ * (does not merge) `variants` and `sizes`; spread `KJ_CHAT_BUBBLE_DEFAULTS.variants`
+ * to extend.
+ */
+export function provideKjChatBubble(
+  config: Partial<KjChatBubbleConfig>,
+): Provider[] {
+  return [
+    {
+      provide: KJ_CHAT_BUBBLE_CONFIG,
+      useValue: { ...KJ_CHAT_BUBBLE_DEFAULTS, ...config },
+    },
+  ];
+}

package/src/chat/index.ts

@@ -0,0 +1,21 @@
+export { KjChatLog } from './chat-log';
+export { KjChat } from './chat';
+export { KjChatAvatar } from './chat-avatar';
+export { KjChatHeader } from './chat-header';
+export { KjChatBubble } from './chat-bubble';
+export { KjChatFooter } from './chat-footer';
+export {
+  KJ_CHAT,
+  KJ_CHAT_LOG,
+  type KjChatContext,
+  type KjChatLogContext,
+  type KjChatRole,
+  type KjChatSide,
+  type KjChatState,
+} from './chat.context';
+export {
+  KJ_CHAT_BUBBLE_CONFIG,
+  KJ_CHAT_BUBBLE_DEFAULTS,
+  provideKjChatBubble,
+  type KjChatBubbleConfig,
+} from './config';

package/src/checkbox/checkbox.ts

@@ -1,10 +1,14 @@
-import { Directive, inject, model } from '@angular/core';
+import { Directive, inject, model } from '@angular/core';
 import { KjDisabled, KjFocusRing, KjFormControl } from '../primitives';
 
 /**
  * Adds checkbox semantics with Angular forms integration.
  * Supports `formControl`, `formControlName`, and `ngModel` bindings.
  *
+ * Apply `[kjCheckbox]` to any focusable element to get `role="checkbox"`,
+ * `aria-checked` reflection, Space/click toggle, and the shared focus-ring
+ * primitive — all composable onto custom markup with no styling attached.
+ *
  * @example
  * ```html
  * <div kjCheckbox tabindex="0" [(kjChecked)]="accepted" aria-label="Accept terms">Accept</div>
@@ -44,7 +48,10 @@ import { KjDisabled, KjFocusRing, KjFormControl } from '../primitives';
  *         newsletter = signal(true);
  *       }
  *    ```
- * @category Core/Inputs
+ * @doc-category Core/Inputs
+ * @doc-name checkbox
+ * @doc-description Adds accessible checkbox behaviour and Angular forms support to any element you bring.
+ * @doc-is-main
  */
 @Directive({
   selector: '[kjCheckbox]',

package/src/color-picker/color-picker.context.ts

@@ -0,0 +1,74 @@
+import { InjectionToken, Signal } from '@angular/core';
+import type { KjHsl, KjHsv, KjRgb } from './color-picker.utils';
+
+/** Output formats supported by `KjColorPicker`. */
+export type KjColorFormat = 'hex' | 'rgb' | 'hsl';
+
+/**
+ * Public emitted value for `KjColorPicker`.
+ * Concrete shape depends on the active `kjFormat`:
+ *  - `'hex'` → `string` (`'#rrggbb'` or `'#rrggbbaa'` when alpha is on).
+ *  - `'rgb'` → `[r, g, b]` or `[r, g, b, a]` when alpha is on.
+ *  - `'hsl'` → `{ h, s, l }` or `{ h, s, l, a }` when alpha is on.
+ */
+export type KjColorValue =
+  | string
+  | readonly [number, number, number]
+  | readonly [number, number, number, number]
+  | { h: number; s: number; l: number }
+  | { h: number; s: number; l: number; a: number };
+
+/** A single preset swatch in the color picker's palette grid. */
+export interface KjColorPreset {
+  /** Any parseable hex color string. */
+  readonly value: string;
+  /** Optional accessible name announced to AT in place of the raw hex. */
+  readonly label?: string;
+}
+
+/**
+ * Shared state container exposed to every `KjColorPicker` sub-directive
+ * via the `KJ_COLOR_PICKER` token. The root directive is the sole writer;
+ * sub-directives read derived signals and call mutator methods.
+ */
+export interface KjColorPickerContext {
+  // Canonical state
+  readonly hue:        Signal<number>;
+  readonly saturation: Signal<number>;
+  readonly value:      Signal<number>;
+  readonly alpha:      Signal<number>;
+
+  // Derived projections
+  readonly hex:  Signal<string>;
+  readonly rgb:  Signal<KjRgb>;
+  readonly hsv:  Signal<KjHsv>;
+  readonly hsl:  Signal<KjHsl>;
+
+  // Mutators
+  setHue(h: number): void;
+  setSaturationValue(s: number, v: number): void;
+  setAlpha(a: number): void;
+  setHex(hex: string): boolean;
+  setRgb(r: number, g: number, b: number, a?: number): void;
+
+  // UI state
+  readonly open:      Signal<boolean>;
+  readonly disabled:  Signal<boolean>;
+  readonly format:    Signal<KjColorFormat>;
+  readonly showAlpha: Signal<boolean>;
+  readonly presets:   Signal<readonly KjColorPreset[]>;
+  setOpen(open: boolean): void;
+
+  // Wiring ids
+  readonly panelId:   Signal<string>;
+  readonly triggerId: Signal<string>;
+}
+
+/**
+ * DI token consumed by every `KjColorPicker*` sub-directive. Provided by
+ * the root `KjColorPicker` directive — sub-directives outside that
+ * context throw at injection time in dev.
+ */
+export const KJ_COLOR_PICKER = new InjectionToken<KjColorPickerContext>(
+  'KjColorPicker',
+);

package/src/color-picker/color-picker.spec.ts

@@ -0,0 +1,241 @@
+import { render, fireEvent } from '@testing-library/angular';
+import { FormControl, ReactiveFormsModule } from '@angular/forms';
+import { axe, toHaveNoViolations } from 'jest-axe';
+import {
+  KjColorPicker,
+  KjColorPickerAlphaSlider,
+  KjColorPickerArea,
+  KjColorPickerHueSlider,
+  KjColorPickerInput,
+  KjColorPickerPanel,
+  KjColorPickerTrigger,
+} from './color-picker';
+import {
+  kjHsvToRgb,
+  kjParseHex,
+  kjRgbToHex,
+  kjRgbToHsv,
+} from './color-picker.utils';
+
+expect.extend(toHaveNoViolations);
+
+const directiveImports = [
+  KjColorPicker,
+  KjColorPickerTrigger,
+  KjColorPickerPanel,
+  KjColorPickerArea,
+  KjColorPickerHueSlider,
+  KjColorPickerAlphaSlider,
+  KjColorPickerInput,
+];
+
+const fullTemplate = `
+  <div kjColorPicker [formControl]="ctrl" [kjShowAlpha]="showAlpha">
+    <button kjColorPickerTrigger>open</button>
+    <div kjColorPickerPanel>
+      <div kjColorPickerArea></div>
+      <input kjColorPickerHueSlider />
+      <input kjColorPickerAlphaSlider />
+      <input kjColorPickerInput />
+    </div>
+  </div>
+`;
+
+/** When `bodyPortal` mounts the panel out to <body>, search there too. */
+function findPanel(container: HTMLElement): HTMLElement {
+  return (
+    container.querySelector('[kjColorPickerPanel]') ??
+    document.body.querySelector('[kjColorPickerPanel]')!
+  ) as HTMLElement;
+}
+
+describe('color-picker utils', () => {
+  it('parses 6-char hex with leading hash', () => {
+    expect(kjParseHex('#ff0000')).toEqual({ r: 255, g: 0, b: 0, a: 1 });
+  });
+
+  it('parses 3-char hex without leading hash', () => {
+    expect(kjParseHex('f00')).toEqual({ r: 255, g: 0, b: 0, a: 1 });
+  });
+
+  it('parses 8-char hex with alpha', () => {
+    const r = kjParseHex('#ff000080');
+    expect(r?.r).toBe(255);
+    expect(r?.g).toBe(0);
+    expect(r?.b).toBe(0);
+    expect(r?.a).toBeCloseTo(0x80 / 255, 5);
+  });
+
+  it('returns null for invalid hex', () => {
+    expect(kjParseHex('not-a-color')).toBeNull();
+    expect(kjParseHex('#xyzxyz')).toBeNull();
+    expect(kjParseHex('#ff')).toBeNull();
+  });
+
+  it('round-trips RGB → HSV → RGB for primary red', () => {
+    const hsv = kjRgbToHsv({ r: 255, g: 0, b: 0, a: 1 });
+    const back = kjHsvToRgb(hsv);
+    expect(back.r).toBe(255);
+    expect(back.g).toBe(0);
+    expect(back.b).toBe(0);
+  });
+
+  it('round-trips RGB → HSV → RGB for arbitrary color', () => {
+    const original = { r: 184, g: 245, b: 0, a: 1 };
+    const hsv = kjRgbToHsv(original);
+    const back = kjHsvToRgb(hsv);
+    expect(back.r).toBe(original.r);
+    expect(back.g).toBe(original.g);
+    expect(back.b).toBe(original.b);
+  });
+
+  it('formats RGB to lowercase six-char hex by default', () => {
+    expect(kjRgbToHex({ r: 0xab, g: 0xcd, b: 0xef, a: 1 }, false))
+      .toBe('#abcdef');
+  });
+
+  it('formats RGB to eight-char hex when alpha is requested', () => {
+    expect(kjRgbToHex({ r: 0, g: 0, b: 0, a: 0.5 }, true))
+      .toBe('#00000080');
+  });
+});
+
+describe('KjColorPicker', () => {
+  function makeCtrl(initial = '#ff0000') {
+    return new FormControl(initial);
+  }
+
+  it('panel is hidden by default', async () => {
+    const { container } = await render(fullTemplate, {
+      imports: [...directiveImports, ReactiveFormsModule],
+      componentProperties: { ctrl: makeCtrl(), showAlpha: false },
+    });
+    expect(findPanel(container)).toHaveAttribute('hidden', '');
+  });
+
+  it('clicking the trigger opens the panel', async () => {
+    const { container } = await render(fullTemplate, {
+      imports: [...directiveImports, ReactiveFormsModule],
+      componentProperties: { ctrl: makeCtrl(), showAlpha: false },
+    });
+    fireEvent.click(container.querySelector('[kjColorPickerTrigger]')!);
+    expect(findPanel(container)).not.toHaveAttribute('hidden');
+  });
+
+  it('trigger reflects aria-expanded based on open state', async () => {
+    const { container } = await render(fullTemplate, {
+      imports: [...directiveImports, ReactiveFormsModule],
+      componentProperties: { ctrl: makeCtrl(), showAlpha: false },
+    });
+    const trigger = container.querySelector('[kjColorPickerTrigger]')!;
+    expect(trigger).toHaveAttribute('aria-expanded', 'false');
+    fireEvent.click(trigger);
+    expect(trigger).toHaveAttribute('aria-expanded', 'true');
+  });
+
+  it('trigger has aria-haspopup="dialog"', async () => {
+    const { container } = await render(fullTemplate, {
+      imports: [...directiveImports, ReactiveFormsModule],
+      componentProperties: { ctrl: makeCtrl(), showAlpha: false },
+    });
+    const trigger = container.querySelector('[kjColorPickerTrigger]')!;
+    expect(trigger).toHaveAttribute('aria-haspopup', 'dialog');
+  });
+
+  it('panel has role="dialog"', async () => {
+    const { container } = await render(fullTemplate, {
+      imports: [...directiveImports, ReactiveFormsModule],
+      componentProperties: { ctrl: makeCtrl(), showAlpha: false },
+    });
+    const panel = findPanel(container);
+    expect(panel).toHaveAttribute('role', 'dialog');
+  });
+
+  it('sat/value area has role="slider" with aria-valuetext', async () => {
+    const { container } = await render(fullTemplate, {
+      imports: [...directiveImports, ReactiveFormsModule],
+      componentProperties: { ctrl: makeCtrl(), showAlpha: false },
+    });
+    const area = container.querySelector('[kjColorPickerArea]')!;
+    expect(area).toHaveAttribute('role', 'slider');
+    expect(area.getAttribute('aria-valuetext')).toMatch(/saturation/i);
+  });
+
+  it('arrow keys on the sat/value area update aria-valuenow', async () => {
+    const { container } = await render(fullTemplate, {
+      imports: [...directiveImports, ReactiveFormsModule],
+      componentProperties: { ctrl: makeCtrl(), showAlpha: false },
+    });
+    fireEvent.click(container.querySelector('[kjColorPickerTrigger]')!);
+    const area = container.querySelector('[kjColorPickerArea]')
+      ?? document.body.querySelector('[kjColorPickerArea]')!;
+    // Initial red has saturation=1; ArrowLeft is the unambiguous direction to move.
+    const before = area.getAttribute('aria-valuenow');
+    fireEvent.keyDown(area, { key: 'ArrowLeft' });
+    const after = area.getAttribute('aria-valuenow');
+    expect(after).not.toBe(before);
+  });
+
+  it('hex input commits a parseable value on Enter', async () => {
+    const ctrl = makeCtrl();
+    const { container, fixture } = await render(fullTemplate, {
+      imports: [...directiveImports, ReactiveFormsModule],
+      componentProperties: { ctrl, showAlpha: false },
+    });
+    fireEvent.click(container.querySelector('[kjColorPickerTrigger]')!);
+    const input = (container.querySelector('[kjColorPickerInput]')
+      ?? document.body.querySelector('[kjColorPickerInput]')) as HTMLInputElement;
+    input.value = '#00ff00';
+    fireEvent.input(input, { target: input });
+    fireEvent.keyDown(input, { key: 'Enter' });
+    fixture.detectChanges();
+    expect(ctrl.value).toBe('#00ff00');
+  });
+
+  it('writeValue parses external hex and reflects it on the trigger', async () => {
+    const ctrl = makeCtrl('#000000');
+    const { container, fixture } = await render(fullTemplate, {
+      imports: [...directiveImports, ReactiveFormsModule],
+      componentProperties: { ctrl, showAlpha: false },
+    });
+    ctrl.setValue('#0000ff');
+    fixture.detectChanges();
+    await fixture.whenStable();
+    fixture.detectChanges();
+    const trigger = container.querySelector('[kjColorPickerTrigger]') as HTMLElement;
+    expect(trigger.style.getPropertyValue('--kj-color-picker-current'))
+      .toBe('#0000ff');
+  });
+
+  it('hue slider has aria-label="Hue" and is a native range input', async () => {
+    const { container } = await render(fullTemplate, {
+      imports: [...directiveImports, ReactiveFormsModule],
+      componentProperties: { ctrl: makeCtrl(), showAlpha: false },
+    });
+    const hue = container.querySelector('[kjColorPickerHueSlider]')!;
+    expect(hue).toHaveAttribute('aria-label', 'Hue');
+    expect(hue).toHaveAttribute('type', 'range');
+  });
+
+  it('alpha slider mounts but is disabled until kjShowAlpha is true', async () => {
+    const { container, fixture } = await render(fullTemplate, {
+      imports: [...directiveImports, ReactiveFormsModule],
+      componentProperties: { ctrl: makeCtrl(), showAlpha: false },
+    });
+    const alpha = container.querySelector('[kjColorPickerAlphaSlider]') as HTMLInputElement;
+    expect(alpha.disabled).toBe(true);
+    (fixture.componentInstance as { showAlpha: boolean }).showAlpha = true;
+    fixture.detectChanges();
+    expect(alpha.disabled).toBe(false);
+  });
+
+  it('panel passes axe audit when open', async () => {
+    const { container } = await render(fullTemplate, {
+      imports: [...directiveImports, ReactiveFormsModule],
+      componentProperties: { ctrl: makeCtrl(), showAlpha: false },
+    });
+    fireEvent.click(container.querySelector('[kjColorPickerTrigger]')!);
+    const results = await axe(document.body);
+    expect(results).toHaveNoViolations();
+  });
+});