@kouji-ui/components 0.1.1

package/src/input-otp/input-otp.ts

@@ -0,0 +1,244 @@
+import {
+  AfterViewInit,
+  ChangeDetectionStrategy,
+  Component,
+  ViewEncapsulation,
+  booleanAttribute,
+  computed,
+  forwardRef,
+  input,
+  output,
+  viewChild,
+} from '@angular/core';
+import {
+  ControlValueAccessor,
+  NG_VALUE_ACCESSOR,
+} from '@angular/forms';
+import { KjInputOtp, KjInputOtpCell } from '@kouji-ui/core';
+
+/**
+ * Styled wrapper around the headless `KjInputOtp` + `KjInputOtpCell`
+ * directive family.
+ *
+ * Renders N square cells in a flex row. Supports `[(ngModel)]` and
+ * `[formControl]` / `[formControlName]` out of the box — the full
+ * concatenated code string is the form value. Use `[kjSeparatorAfter]="[2]"`
+ * to render a visual dash between cell groups (e.g. `123–456`); the
+ * separator is purely decorative and never included in the form value.
+ *
+ * @doc-example Default
+ *   6-digit OTP with `[(ngModel)]` two-way binding — anchors the chrome.
+ *   @doc-file input-otp.example.ts
+ * @doc-example Usage
+ *   Common OTP shapes — reactive form, length 4, masked digits, and a visual
+ *   separator — assembled as a copy-paste starting point.
+ *   @doc-file input-otp.usage.example.ts
+ * @doc-example Reactive form
+ *   Wires up `[formControl]` with a `minLength` validator + a submit handler.
+ *   @doc-file input-otp.reactive.example.ts
+ * @doc-example Lengths
+ *   Common lengths (4 / 6 / 8) side-by-side.
+ *   @doc-file input-otp.lengths.example.ts
+ * @doc-example Masked
+ *   `[kjMask]="true"` flips cells to `type="password"` for sensitive codes.
+ *   @doc-file input-otp.masked.example.ts
+ * @doc-example With separator
+ *   `[kjSeparatorAfter]="[2]"` renders a decorative dash between cell groups.
+ *   @doc-file input-otp.separator.example.ts
+ * @doc-example Auto-submit
+ *   Emits `(kjComplete)` once the code is fully entered — handy for short codes.
+ *   @doc-file input-otp.autosubmit.example.ts
+ *
+ * @doc-keyboard
+ *   Digits|Letters — Type to populate the focused cell, advance to the next
+ *   Backspace      — Clears the focused cell and moves focus back
+ *   Arrow left|right — Move focus across cells without altering the value
+ *   Home|End       — Jump to the first / last cell
+ *   Cmd|Ctrl + V   — Paste a code; characters distribute across remaining cells
+ *
+ * @doc-aria
+ *   role="group"     — On the OTP container; labelled by [kjAriaLabel] or the surrounding kj-field
+ *   aria-label       — Bound from [kjAriaLabel] when no kj-field-label is present
+ *   aria-invalid     — Reflected on the group when [kjInvalid] is true (touched-gated)
+ *   aria-disabled    — Reflected on the group when [kjDisabled] is true
+ *   aria-readonly    — Reflected on the group when [kjReadonly] is true
+ *   inputmode        — Set on each cell to "numeric" for digits charset
+ *
+ * @doc-touch
+ *   `--kj-otp-cell-size` defaults to 44 px so each cell already meets WCAG
+ *   2.5.5. The visual separator is `aria-hidden` and never receives focus.
+ *
+ * @doc-a11y
+ *   `KjInputOtp` owns paste distribution, charset filtering, and the live
+ *   announcement on `(kjComplete)`. The widget composes `KjFormControl` (CVA)
+ *   so `[(ngModel)]` and `[formControl]` work out of the box — the full
+ *   concatenated code is the form value; the decorative separator is never
+ *   included.
+ *
+ * @doc-related input,input-mask,field,form
+ *
+ * @doc-css-var
+ *   --kj-otp-cell-size         — Square cell width/height. Default 44px (WCAG 2.5.5 touch target).
+ *   --kj-otp-cell-gap          — Gap between adjacent cells.
+ *   --kj-otp-cell-bg           — Cell background fill.
+ *   --kj-otp-cell-fg           — Cell foreground (digit) color.
+ *   --kj-otp-cell-border-color — Cell border color. Focus and invalid states retarget this.
+ *   --kj-otp-cell-border-width — Cell border thickness. Inherits --kj-border.
+ *   --kj-otp-cell-radius       — Cell corner radius. Inherits --kj-radius-field.
+ *   --kj-otp-cell-font         — Font family inside cells.
+ *   --kj-otp-cell-font-size    — Font size inside cells.
+ *
+ * @doc-category Library/Data input
+ * @doc
+ * @doc-name input-otp
+ * @doc-description Themed OTP input with N cells, paste distribution, auto-submit, masking, and visual separators.
+ * @doc-is-main
+ */
+@Component({
+  selector: 'kj-input-otp',
+  standalone: true,
+  imports: [KjInputOtp, KjInputOtpCell],
+  providers: [
+    {
+      provide: NG_VALUE_ACCESSOR,
+      useExisting: forwardRef(() => KjInputOtpComponent),
+      multi: true,
+    },
+  ],
+  template: `
+    <div
+      kjInputOtp
+      class="kj-input-otp__group"
+      [kjLength]="kjLength()"
+      [kjCharSet]="kjCharSet()"
+      [kjMask]="kjMask()"
+      [kjAutoSubmit]="kjAutoSubmit()"
+      [kjInvalid]="kjInvalid()"
+      [kjDisabled]="kjDisabled()"
+      [kjReadonly]="kjReadonly()"
+      [kjAriaLabel]="kjAriaLabel()"
+      (kjComplete)="kjComplete.emit($event)"
+      (kjPasted)="kjPasted.emit($event)"
+    >
+      @for (i of _indices(); track i) {
+        <input
+          kjInputOtpCell
+          class="kj-input-otp__cell"
+          [kjIndex]="i"
+        />
+        @if (kjSeparatorAfter().includes(i)) {
+          <span class="kj-input-otp__separator" aria-hidden="true">–</span>
+        }
+      }
+    </div>
+  `,
+  styleUrl: './input-otp.css',
+  encapsulation: ViewEncapsulation.None,
+  host: { class: 'kj-input-otp' },
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class KjInputOtpComponent implements ControlValueAccessor, AfterViewInit {
+  // ── Forwarded inputs ─────────────────────────────────────────────────────────
+
+  /** Number of OTP cells. Common values: 4, 6, 8. */
+  readonly kjLength = input<number>(6);
+
+  /** Character-set restriction. */
+  readonly kjCharSet = input<'digits' | 'alphanumeric' | RegExp>('digits');
+
+  /** When `true`, cells render as `type="password"`. */
+  readonly kjMask = input(false, { transform: booleanAttribute });
+
+  /** When `true`, emits `kjComplete` once the code is fully entered. */
+  readonly kjAutoSubmit = input(false, { transform: booleanAttribute });
+
+  /** Reflects invalid state via `aria-invalid` (touched-gated). */
+  readonly kjInvalid = input(false, { transform: booleanAttribute });
+
+  /** Disables all cells and the root. */
+  readonly kjDisabled = input(false, { transform: booleanAttribute });
+
+  /** Sets all cells to `readonly`. */
+  readonly kjReadonly = input(false, { transform: booleanAttribute });
+
+  /**
+   * Accessible label for the widget (used when there is no parent `KjFormField`).
+   */
+  readonly kjAriaLabel = input<string>('');
+
+  /**
+   * Indices after which to render a visual separator dash.
+   * E.g. `[2]` renders `123–456` for a 6-digit code.
+   * Purely decorative — the separator never appears in the form value.
+   */
+  readonly kjSeparatorAfter = input<readonly number[]>([]);
+
+  // ── Outputs ─────────────────────────────────────────────────────────────────
+
+  /** Emitted when the full code is entered. */
+  readonly kjComplete = output<string>();
+
+  /** Emitted after a paste distributes characters across cells. */
+  readonly kjPasted = output<string>();
+
+  // ── Internal ─────────────────────────────────────────────────────────────────
+
+  /** The inner `KjInputOtp` directive that owns the CVA logic. */
+  private readonly _otp = viewChild.required(KjInputOtp);
+
+  /** The array of cell indices `[0, 1, ..., kjLength-1]`. */
+  readonly _indices = computed(() =>
+    Array.from({ length: this.kjLength() }, (_, i) => i),
+  );
+
+  /** Buffered CVA calls made before the view is initialised. */
+  private _pendingValue: string | null = null;
+  private _pendingOnChange: ((val: string) => void) | null = null;
+  private _pendingOnTouched: (() => void) | null = null;
+  private _pendingDisabled: boolean | null = null;
+  private _viewReady = false;
+
+  ngAfterViewInit(): void {
+    this._viewReady = true;
+    const ctrl = this._otp().formCtrl;
+    if (this._pendingValue !== null) ctrl.writeValue(this._pendingValue);
+    if (this._pendingOnChange !== null) ctrl.registerOnChange(this._pendingOnChange as (val: unknown) => void);
+    if (this._pendingOnTouched !== null) ctrl.registerOnTouched(this._pendingOnTouched);
+    if (this._pendingDisabled !== null) ctrl.setDisabledState(this._pendingDisabled);
+  }
+
+  // ── ControlValueAccessor ─────────────────────────────────────────────────────
+
+  writeValue(value: string | null): void {
+    const v = value ?? '';
+    if (this._viewReady) {
+      this._otp().formCtrl.writeValue(v);
+    } else {
+      this._pendingValue = v;
+    }
+  }
+
+  registerOnChange(fn: (val: string) => void): void {
+    if (this._viewReady) {
+      this._otp().formCtrl.registerOnChange(fn as (val: unknown) => void);
+    } else {
+      this._pendingOnChange = fn;
+    }
+  }
+
+  registerOnTouched(fn: () => void): void {
+    if (this._viewReady) {
+      this._otp().formCtrl.registerOnTouched(fn);
+    } else {
+      this._pendingOnTouched = fn;
+    }
+  }
+
+  setDisabledState(isDisabled: boolean): void {
+    if (this._viewReady) {
+      this._otp().formCtrl.setDisabledState(isDisabled);
+    } else {
+      this._pendingDisabled = isDisabled;
+    }
+  }
+}

package/src/input-otp/input-otp.usage.example.ts

@@ -0,0 +1,45 @@
+import { ChangeDetectionStrategy, Component } from '@angular/core';
+import { FormsModule } from '@angular/forms';
+import { KjInputOtpComponent } from './input-otp';
+
+/**
+ * Common OTP shapes — default 6-digit, short 4-digit, masked code, and a
+ * grouped 6-digit with a visual separator. Copy-paste starting point.
+ */
+@Component({
+  selector: 'kj-input-otp-usage-example',
+  standalone: true,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  imports: [KjInputOtpComponent, FormsModule],
+  styles: [`
+    :host { display: flex; flex-direction: column; gap: var(--kj-space-lg); }
+    .row { display: flex; flex-direction: column; gap: var(--kj-space-xs); }
+    label { font: 500 var(--kj-text-sm)/1.4 var(--kj-font-sans); }
+    code { font: var(--kj-text-xs)/1 var(--kj-font-mono); color: var(--kj-fg-muted); }
+  `],
+  template: `
+    <div class="row">
+      <label for="usage-otp-6">Verification code</label>
+      <kj-input-otp id="usage-otp-6" kjAriaLabel="Verification code" [(ngModel)]="code" />
+      <code>{{ code || '——' }}</code>
+    </div>
+
+    <div class="row">
+      <label for="usage-otp-4">Short PIN</label>
+      <kj-input-otp id="usage-otp-4" [kjLength]="4" kjAriaLabel="Short PIN" />
+    </div>
+
+    <div class="row">
+      <label for="usage-otp-masked">Masked code</label>
+      <kj-input-otp id="usage-otp-masked" [kjMask]="true" kjAriaLabel="Masked code" />
+    </div>
+
+    <div class="row">
+      <label for="usage-otp-sep">Grouped code</label>
+      <kj-input-otp id="usage-otp-sep" [kjSeparatorAfter]="[2]" kjAriaLabel="Grouped code" />
+    </div>
+  `,
+})
+export class KjInputOtpUsageExample {
+  code = '';
+}

package/src/kbd/_examples/index.ts

@@ -0,0 +1,6 @@
+// AUTO-GENERATED by scripts/migrate-examples.mjs
+// One barrel per component folder — used by the docs app as a lazy chunk.
+export { KjKbdComboExample } from './kbd.combo.example';
+export { KjKbdExample } from './kbd.example';
+export { KjKbdInTooltipExample } from './kbd.in-tooltip.example';
+export { KjKbdSizesExample } from './kbd.sizes.example';

package/src/kbd/_examples/kbd.combo.example.ts

@@ -0,0 +1,24 @@
+import { Component, ChangeDetectionStrategy } from '@angular/core';
+import { KjKbdComponent } from '../kbd';
+
+/**
+ * Combo example: sibling `<kj-kbd>` elements with a literal " + " between
+ * them. Per the analysis there is no `KjKbdGroup` directive — the visual
+ * gap is just inline whitespace plus a `+` glyph, and AT correctly
+ * announces the combo as e.g. "Control plus K" without extra ARIA wiring.
+ */
+@Component({
+  selector: 'kj-kbd-combo-example',
+  standalone: true,
+  imports: [KjKbdComponent],
+  styles: [
+    `
+      :host {
+        display: block;
+      }
+    `,
+  ],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: `<p><kj-kbd>Ctrl</kj-kbd> + <kj-kbd>K</kj-kbd></p>`,
+})
+export class KjKbdComboExample {}

package/src/kbd/_examples/kbd.example.ts

@@ -0,0 +1,22 @@
+import { Component, ChangeDetectionStrategy } from '@angular/core';
+import { KjKbdComponent } from '../kbd';
+
+/**
+ * Default usage example for KjKbdComponent.
+ * A single keyboard-key visual rendered inline with prose. Anchors the chrome.
+ */
+@Component({
+  selector: 'kj-kbd-example',
+  standalone: true,
+  imports: [KjKbdComponent],
+  styles: [
+    `
+      :host {
+        display: block;
+      }
+    `,
+  ],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: `<p>Press <kj-kbd>K</kj-kbd> to focus search.</p>`,
+})
+export class KjKbdExample {}

package/src/kbd/_examples/kbd.in-tooltip.example.ts

@@ -0,0 +1,43 @@
+import { Component, ChangeDetectionStrategy } from '@angular/core';
+import { KjKbdComponent } from '../kbd';
+import { KjTooltipTrigger, KjTooltipContent } from '../../tooltip/tooltip';
+import { KjButtonComponent } from '../../button/button';
+
+/**
+ * Kbd inside a tooltip — the canonical "shortcut hint" surface. The tooltip's
+ * `aria-describedby` wiring picks up the kbd's text content automatically; no
+ * special integration needed. Lives in the kbd folder so the kbd docs page
+ * can preview it without depending on the tooltip docs page's example
+ * registry.
+ */
+@Component({
+  selector: 'kj-kbd-in-tooltip-example',
+  standalone: true,
+  imports: [KjKbdComponent, KjTooltipTrigger, KjTooltipContent, KjButtonComponent],
+  styles: [
+    `
+      :host {
+        display: block;
+        padding: var(--kj-space-2xl);
+      }
+      .kj-kbd-in-tooltip-body {
+        display: inline-flex;
+        align-items: center;
+        gap: var(--kj-space-2xs);
+      }
+    `,
+  ],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: `
+    <kj-button kjTooltipTrigger #t="kjTooltipTrigger" kjVariant="outline">Save</kj-button>
+    <kj-tooltip-content [kjFor]="t">
+      <span class="kj-kbd-in-tooltip-body">
+        Save
+        <kj-kbd kjSize="xs">Ctrl</kj-kbd>
+        +
+        <kj-kbd kjSize="xs">S</kj-kbd>
+      </span>
+    </kj-tooltip-content>
+  `,
+})
+export class KjKbdInTooltipExample {}

package/src/kbd/_examples/kbd.sizes.example.ts

@@ -0,0 +1,31 @@
+import { Component, ChangeDetectionStrategy } from '@angular/core';
+import { KjKbdComponent } from '../kbd';
+
+/**
+ * Size scale: `xs` / `sm` / `md` / `lg`. Kbd is the one component that
+ * legitimately wants `xs` (inline-with-prose hint chips need to be smaller
+ * than the surrounding type so they don't dominate visually).
+ */
+@Component({
+  selector: 'kj-kbd-sizes-example',
+  standalone: true,
+  imports: [KjKbdComponent],
+  styles: [
+    `
+      :host {
+        display: flex;
+        gap: var(--kj-space-md);
+        align-items: center;
+        flex-wrap: wrap;
+      }
+    `,
+  ],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: `
+    <kj-kbd kjSize="xs">Esc</kj-kbd>
+    <kj-kbd kjSize="sm">Esc</kj-kbd>
+    <kj-kbd kjSize="md">Esc</kj-kbd>
+    <kj-kbd kjSize="lg">Esc</kj-kbd>
+  `,
+})
+export class KjKbdSizesExample {}

package/src/kbd/index.ts

@@ -0,0 +1 @@
+export * from './kbd';

package/src/kbd/kbd.css

@@ -0,0 +1,67 @@
+/* ─────────────────────────────────────────────────────────────
+   .kj-kbd — component-layer tokens + structural CSS
+
+   Theme-token-only. The directive sets `data-size` on the host;
+   the rest is a small "raised key" silhouette: 1px border + soft
+   inner shadow + monospace text. No variant — the kbd is tonally
+   neutral (see analysis Open question section).
+   ──────────────────────────────────────────────────────────── */
+
+@layer kj.component {
+  .kj-kbd {
+    --kj-kbd-bg:           var(--kj-bg-surface);
+    --kj-kbd-fg:           var(--kj-fg-default);
+    --kj-kbd-border-color: var(--kj-border-default);
+    --kj-kbd-border-width: var(--kj-border, 1px);
+    --kj-kbd-radius:       var(--kj-radius-selector, 0.25rem);
+    --kj-kbd-padding-x:    0.4em;
+    --kj-kbd-padding-y:    0.15em;
+    --kj-kbd-font:         var(--kj-font-mono);
+    --kj-kbd-font-size:    var(--kj-text-sm);
+
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    vertical-align: baseline;
+
+    background: var(--kj-kbd-bg);
+    color: var(--kj-kbd-fg);
+    border: var(--kj-kbd-border-width) solid var(--kj-kbd-border-color);
+    border-radius: var(--kj-kbd-radius);
+    padding: var(--kj-kbd-padding-y) var(--kj-kbd-padding-x);
+
+    font-family: var(--kj-kbd-font);
+    font-size: var(--kj-kbd-font-size);
+    line-height: 1;
+    white-space: nowrap;
+  }
+
+  /* Size routing — driven by the directive's [attr.data-size]. */
+  .kj-kbd[data-size='xs'] {
+    /* At xs the border carries most of the visual identity; bump it to a
+       higher-contrast token so it clears 3:1 against base-100/200/300 page
+       backgrounds (analysis Open question 5). */
+    --kj-kbd-border-color: color-mix(in oklab, var(--kj-fg-default) 30%, transparent);
+    --kj-kbd-font-size: var(--kj-text-xs);
+    --kj-kbd-padding-x: 0.3em;
+    --kj-kbd-padding-y: 0.1em;
+  }
+
+  .kj-kbd[data-size='sm'] {
+    --kj-kbd-font-size: var(--kj-text-xs);
+    --kj-kbd-padding-x: 0.35em;
+    --kj-kbd-padding-y: 0.12em;
+  }
+
+  .kj-kbd[data-size='md'] {
+    --kj-kbd-font-size: var(--kj-text-sm);
+    --kj-kbd-padding-x: 0.4em;
+    --kj-kbd-padding-y: 0.15em;
+  }
+
+  .kj-kbd[data-size='lg'] {
+    --kj-kbd-font-size: var(--kj-text-base);
+    --kj-kbd-padding-x: 0.5em;
+    --kj-kbd-padding-y: 0.2em;
+  }
+}

package/src/kbd/kbd.playground.ts

@@ -0,0 +1,51 @@
+import { ChangeDetectionStrategy, Component, signal } from '@angular/core';
+import { KjKbdComponent } from './kbd';
+import type { PlaygroundFile } from '@kouji-ui/components/playground-types';
+
+/**
+ * Playground state — module-scope signals. Knobs let users drive the kbd
+ * size scale (the only library component that legitimately ships below
+ * `sm`), the visible label, and the optional `aria-label` override for
+ * unicode-glyph keys (⌘, ⌥, ↵).
+ */
+const size = signal<'xs' | 'sm' | 'md' | 'lg'>('md');
+const label = signal('Enter');
+const ariaLabel = signal('');
+
+@Component({
+  selector: 'kj-kbd-playground',
+  standalone: true,
+  imports: [KjKbdComponent],
+  template: `
+    <kj-kbd
+      [kjSize]="size()"
+      [kjKbdAriaLabel]="ariaLabel() || undefined"
+    >{{ label() }}</kj-kbd>
+  `,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class KjKbdPlaygroundDemo {
+  protected readonly size = size;
+  protected readonly label = label;
+  protected readonly ariaLabel = ariaLabel;
+}
+
+export const PLAYGROUND: PlaygroundFile = {
+  component: KjKbdPlaygroundDemo,
+  state: {
+    size: size as unknown as ReturnType<typeof signal>,
+    label: label as unknown as ReturnType<typeof signal>,
+    ariaLabel: ariaLabel as unknown as ReturnType<typeof signal>,
+  },
+  controls: [
+    { kind: 'chips', name: 'size', label: 'size', options: ['xs', 'sm', 'md', 'lg'] },
+    { kind: 'text', name: 'label', label: 'label' },
+    { kind: 'text', name: 'ariaLabel', label: 'aria-label (glyph keys)', placeholder: 'Command' },
+  ],
+  snippet: (values) => {
+    const s = values as { size: string; label: string; ariaLabel: string };
+    const attrs: string[] = [`kjSize="${s.size}"`];
+    if (s.ariaLabel) attrs.push(`kjKbdAriaLabel="${s.ariaLabel}"`);
+    return `<kj-kbd\n  ${attrs.join('\n  ')}\n>${s.label}</kj-kbd>`;
+  },
+};

package/src/kbd/kbd.spec.ts

@@ -0,0 +1,123 @@
+import { Component, ChangeDetectionStrategy } from '@angular/core';
+import { TestBed } from '@angular/core/testing';
+import { describe, expect, test, beforeEach } from 'vitest';
+import { KjKbdComponent } from './kbd';
+
+/**
+ * Flush microtasks + the rAF that backs `afterNextRender` so the underlying
+ * `KjKbd` directive's dev-mode host inspection has a chance to settle before
+ * assertions.
+ */
+async function flushAfterNextRender(): Promise<void> {
+  await new Promise<void>((resolve) => setTimeout(resolve, 0));
+  await Promise.resolve();
+  await Promise.resolve();
+}
+
+@Component({
+  standalone: true,
+  imports: [KjKbdComponent],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: `<kj-kbd>K</kj-kbd>`,
+})
+class DefaultHost {}
+
+@Component({
+  standalone: true,
+  imports: [KjKbdComponent],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: `<kj-kbd [kjSize]="size">{{ label }}</kj-kbd>`,
+})
+class SizedHost {
+  size: 'xs' | 'sm' | 'md' | 'lg' = 'md';
+  label = 'Enter';
+}
+
+@Component({
+  standalone: true,
+  imports: [KjKbdComponent],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: `<kj-kbd [kjKbdAriaLabel]="ariaLabel">{{ label }}</kj-kbd>`,
+})
+class AriaLabelHost {
+  ariaLabel: string | undefined = undefined;
+  label = '⌘';
+}
+
+describe('KjKbdComponent', () => {
+  beforeEach(() => {
+    TestBed.configureTestingModule({});
+  });
+
+  describe('host element', () => {
+    test('renders an inner <kbd> with the .kj-kbd class', async () => {
+      const fixture = TestBed.createComponent(DefaultHost);
+      fixture.detectChanges();
+      await flushAfterNextRender();
+      fixture.detectChanges();
+      const root = fixture.nativeElement as HTMLElement;
+      expect(root.querySelector('kj-kbd kbd.kj-kbd')).not.toBeNull();
+    });
+
+    test('projects content into the inner <kbd>', async () => {
+      const fixture = TestBed.createComponent(DefaultHost);
+      fixture.detectChanges();
+      await flushAfterNextRender();
+      fixture.detectChanges();
+      const kbd = fixture.nativeElement.querySelector('kj-kbd kbd.kj-kbd')!;
+      expect(kbd.textContent?.trim()).toBe('K');
+    });
+  });
+
+  describe('aliased input forwarding', () => {
+    test('resolves kjSize via the wrapper preset (default md)', async () => {
+      const fixture = TestBed.createComponent(SizedHost);
+      fixture.detectChanges();
+      await flushAfterNextRender();
+      fixture.detectChanges();
+      const host = fixture.nativeElement.querySelector('kj-kbd kbd.kj-kbd')!;
+      expect(host.getAttribute('data-size')).toBe('md');
+    });
+
+    test('forwards kjSize=xs to the directive (data-size)', async () => {
+      const fixture = TestBed.createComponent(SizedHost);
+      fixture.componentInstance.size = 'xs';
+      fixture.detectChanges();
+      await flushAfterNextRender();
+      fixture.detectChanges();
+      const host = fixture.nativeElement.querySelector('kj-kbd kbd.kj-kbd')!;
+      expect(host.getAttribute('data-size')).toBe('xs');
+    });
+
+    test('forwards kjSize=lg to the directive (data-size)', async () => {
+      const fixture = TestBed.createComponent(SizedHost);
+      fixture.componentInstance.size = 'lg';
+      fixture.detectChanges();
+      await flushAfterNextRender();
+      fixture.detectChanges();
+      const host = fixture.nativeElement.querySelector('kj-kbd kbd.kj-kbd')!;
+      expect(host.getAttribute('data-size')).toBe('lg');
+    });
+  });
+
+  describe('aria-label propagation', () => {
+    test('omits aria-label by default', async () => {
+      const fixture = TestBed.createComponent(AriaLabelHost);
+      fixture.detectChanges();
+      await flushAfterNextRender();
+      fixture.detectChanges();
+      const host = fixture.nativeElement.querySelector('kj-kbd kbd.kj-kbd')!;
+      expect(host.hasAttribute('aria-label')).toBe(false);
+    });
+
+    test('reflects kjKbdAriaLabel to the inner <kbd> aria-label', async () => {
+      const fixture = TestBed.createComponent(AriaLabelHost);
+      fixture.componentInstance.ariaLabel = 'Command';
+      fixture.detectChanges();
+      await flushAfterNextRender();
+      fixture.detectChanges();
+      const host = fixture.nativeElement.querySelector('kj-kbd kbd.kj-kbd')!;
+      expect(host.getAttribute('aria-label')).toBe('Command');
+    });
+  });
+});