@kouji-ui/components 0.1.1

package/src/number-input/number-input.css

@@ -0,0 +1,115 @@
+/* ─────────────────────────────────────────────────────────────
+   .kj-number-input — wrapper around KjNumberInput + KjNumberStepper.
+
+   Tokens default to shared layer values; the stepper buttons live as
+   sibling buttons inside the group. Bounds-aware aria-disabled is
+   reflected from the directive — CSS only reads the attribute.
+   ──────────────────────────────────────────────────────────── */
+
+@layer kj.component {
+  .kj-number-input {
+    --kj-number-input-bg:               var(--kj-bg-field);
+    --kj-number-input-fg:               var(--kj-fg-default);
+    --kj-number-input-border-color:     var(--kj-border-default);
+    --kj-number-input-border-width:     var(--kj-border);
+    --kj-number-input-radius:           var(--kj-radius-field);
+    --kj-number-input-padding-x:        var(--kj-space-md);
+    --kj-number-input-font:             var(--kj-font-sans);
+    --kj-number-input-font-size:        var(--kj-text-sm);
+    --kj-number-input-stepper-bg:       var(--kj-bg-surface);
+    --kj-number-input-stepper-fg:       var(--kj-fg-default);
+    --kj-number-input-stepper-size:     2.25rem;
+    /* Same height contract as .kj-input — keep form rows aligned. */
+    --kj-number-input-height:           2.25rem;
+
+    display: inline-flex;
+    align-items: stretch;
+    height: var(--kj-number-input-height);
+    background: var(--kj-number-input-bg);
+    color: var(--kj-number-input-fg);
+    border: var(--kj-number-input-border-width) solid var(--kj-number-input-border-color);
+    border-radius: var(--kj-number-input-radius);
+    overflow: hidden;
+    font: var(--kj-number-input-font-size) / 1.4 var(--kj-number-input-font);
+    transition: var(--kj-transition);
+  }
+  .kj-number-input[data-size="xs"] { --kj-number-input-height: 1.75rem; --kj-number-input-stepper-size: 1.75rem; --kj-number-input-font-size: 0.75rem;   --kj-number-input-padding-x: var(--kj-space-sm); }
+  .kj-number-input[data-size="sm"] { --kj-number-input-height: 2rem;    --kj-number-input-stepper-size: 2rem;    --kj-number-input-font-size: 0.8125rem; }
+  .kj-number-input[data-size="lg"] { --kj-number-input-height: 2.75rem; --kj-number-input-stepper-size: 2.75rem; --kj-number-input-font-size: 1rem; }
+
+  /* At `xs` we hide the stepper buttons — at 28px the +/- glyphs become
+     too cramped to hit accurately, and the typical xs context (filter rows,
+     inline editors) doesn't want a stepper anyway. The keyboard contract
+     (Arrow/Page/Home/End) still works on the inner <input>. */
+  .kj-number-input[data-size="xs"] .kj-number-input__stepper { display: none; }
+  .kj-number-input[data-size="xs"] .kj-number-input__field { text-align: left; }
+
+  .kj-number-input:focus-within {
+    --kj-number-input-border-color: var(--kj-fg-primary);
+    outline: 2px solid var(--kj-fg-primary);
+    outline-offset: 2px;
+  }
+
+  .kj-number-input[data-invalid] {
+    --kj-number-input-border-color: var(--kj-fg-danger);
+  }
+
+  .kj-number-input[data-disabled] {
+    opacity: 0.55;
+    cursor: not-allowed;
+  }
+
+  .kj-number-input__field {
+    flex: 1 1 auto;
+    min-width: 0;
+    height: 100%;
+    background: transparent;
+    color: inherit;
+    border: 0;
+    padding: 0 var(--kj-number-input-padding-x);
+    font: inherit;
+    text-align: right;
+  }
+  .kj-number-input__field:focus { outline: none; }
+  .kj-number-input__field::placeholder { color: var(--kj-fg-muted); }
+
+  .kj-number-input__stepper {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    min-width: var(--kj-number-input-stepper-size);
+    min-height: var(--kj-number-input-stepper-size);
+    background: var(--kj-number-input-stepper-bg);
+    color: var(--kj-number-input-stepper-fg);
+    border: 0;
+    cursor: pointer;
+    font: inherit;
+    line-height: 1;
+    transition: background var(--kj-transition), color var(--kj-transition), opacity var(--kj-transition);
+  }
+  .kj-number-input__stepper:hover {
+    background: color-mix(in oklab, var(--kj-fg-default) 8%, var(--kj-number-input-stepper-bg));
+  }
+  .kj-number-input__stepper[aria-disabled="true"] {
+    opacity: 0.4;
+    cursor: not-allowed;
+    pointer-events: none;
+  }
+
+  /* Flanking layout (default): decrement | input | increment */
+  .kj-number-input[data-stepper-layout="flanking"] .kj-number-input__stepper--down { order: -1; }
+  .kj-number-input[data-stepper-layout="flanking"] .kj-number-input__stepper--up   { order:  1; }
+
+  /* Stacked layout: input on the left, up / down stacked vertically on the right. */
+  .kj-number-input[data-stepper-layout="stacked"] {
+    align-items: stretch;
+  }
+  .kj-number-input[data-stepper-layout="stacked"] .kj-number-input__steppers {
+    display: flex;
+    flex-direction: column;
+  }
+  .kj-number-input[data-stepper-layout="stacked"] .kj-number-input__stepper {
+    flex: 1 1 auto;
+    min-height: calc(var(--kj-number-input-stepper-size) / 2);
+  }
+}

package/src/number-input/number-input.playground.ts

@@ -0,0 +1,92 @@
+import { ChangeDetectionStrategy, Component, signal } from '@angular/core';
+import { KjNumberInputComponent } from './number-input';
+import type { PlaygroundFile } from '@kouji-ui/components/playground-types';
+
+/**
+ * Playground state — module-scope signals. Knobs cover the numeric envelope
+ * (min/max/step), formatting locale, and read-only / disabled toggles.
+ */
+const value = signal<number>(50);
+const min = signal<number>(0);
+const max = signal<number>(100);
+const step = signal<number>(5);
+const stepperLayout = signal<'flanking' | 'stacked'>('flanking');
+const disabled = signal(false);
+const readonlyState = signal(false);
+
+@Component({
+  selector: 'kj-number-input-playground',
+  standalone: true,
+  imports: [KjNumberInputComponent],
+  template: `
+    <kj-number-input
+      [(kjValue)]="value"
+      [kjMin]="min()"
+      [kjMax]="max()"
+      [kjStep]="step()"
+      [kjStepperLayout]="stepperLayout()"
+      [kjDisabled]="disabled()"
+      [kjReadonly]="readonlyState()"
+      kjAriaLabel="Quantity"
+    />
+  `,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class KjNumberInputPlaygroundDemo {
+  protected readonly value = value;
+  protected readonly min = min;
+  protected readonly max = max;
+  protected readonly step = step;
+  protected readonly stepperLayout = stepperLayout;
+  protected readonly disabled = disabled;
+  protected readonly readonlyState = readonlyState;
+}
+
+export const PLAYGROUND: PlaygroundFile = {
+  component: KjNumberInputPlaygroundDemo,
+  state: {
+    value: value as unknown as ReturnType<typeof signal>,
+    min: min as unknown as ReturnType<typeof signal>,
+    max: max as unknown as ReturnType<typeof signal>,
+    step: step as unknown as ReturnType<typeof signal>,
+    stepperLayout: stepperLayout as unknown as ReturnType<typeof signal>,
+    disabled: disabled as unknown as ReturnType<typeof signal>,
+    readonlyState: readonlyState as unknown as ReturnType<typeof signal>,
+  },
+  controls: [
+    { kind: 'number', name: 'value', label: 'value' },
+    { kind: 'number', name: 'min', label: 'min' },
+    { kind: 'number', name: 'max', label: 'max' },
+    { kind: 'number', name: 'step', label: 'step', min: 1 },
+    {
+      kind: 'chips',
+      name: 'stepperLayout',
+      label: 'stepper layout',
+      options: ['flanking', 'stacked'],
+    },
+    { kind: 'toggle', name: 'disabled', label: 'disabled' },
+    { kind: 'toggle', name: 'readonlyState', label: 'readonly' },
+  ],
+  snippet: (values) => {
+    const s = values as {
+      value: number;
+      min: number;
+      max: number;
+      step: number;
+      stepperLayout: string;
+      disabled: boolean;
+      readonlyState: boolean;
+    };
+    const attrs: string[] = [
+      `[(kjValue)]="value"`,
+      `[kjMin]="${s.min}"`,
+      `[kjMax]="${s.max}"`,
+      `[kjStep]="${s.step}"`,
+      `kjStepperLayout="${s.stepperLayout}"`,
+    ];
+    if (s.disabled) attrs.push('[kjDisabled]="true"');
+    if (s.readonlyState) attrs.push('[kjReadonly]="true"');
+    attrs.push('kjAriaLabel="Quantity"');
+    return `<kj-number-input\n  ${attrs.join('\n  ')}\n/>`;
+  },
+};

package/src/number-input/number-input.spec.ts

@@ -0,0 +1,102 @@
+import { Component, signal, ChangeDetectionStrategy } from '@angular/core';
+import { TestBed } from '@angular/core/testing';
+import { describe, expect, test, beforeEach } from 'vitest';
+import { KjNumberInputComponent } from './number-input';
+
+@Component({
+  standalone: true,
+  imports: [KjNumberInputComponent],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: `
+    <kj-number-input
+      [(kjValue)]="value"
+      [kjMin]="min"
+      [kjMax]="max"
+      [kjStep]="step"
+      [kjDisabled]="disabled"
+      [kjReadonly]="readonly"
+      kjAriaLabel="Quantity"
+    />
+  `,
+})
+class HostComponent {
+  value = signal<number | null>(3);
+  min: number | undefined = 0;
+  max: number | undefined = 10;
+  step = 1;
+  disabled = false;
+  readonly = false;
+}
+
+describe('KjNumberInputComponent', () => {
+  beforeEach(() => {
+    TestBed.configureTestingModule({ imports: [HostComponent] });
+  });
+
+  test('renders a wrapper with two stepper buttons and an internal input', () => {
+    const fixture = TestBed.createComponent(HostComponent);
+    fixture.detectChanges();
+    const root = fixture.nativeElement.querySelector('.kj-number-input');
+    expect(root).not.toBeNull();
+    const buttons = root.querySelectorAll('button');
+    expect(buttons.length).toBe(2);
+    expect(root.querySelector('input.kj-number-input__field')).not.toBeNull();
+  });
+
+  test('forwards initial value to the internal input', () => {
+    const fixture = TestBed.createComponent(HostComponent);
+    fixture.detectChanges();
+    const input = fixture.nativeElement.querySelector('input') as HTMLInputElement;
+    expect(input.getAttribute('aria-valuenow')).toBe('3');
+  });
+
+  test('clicking the increment button increases the value', () => {
+    const fixture = TestBed.createComponent(HostComponent);
+    fixture.detectChanges();
+    const up = fixture.nativeElement.querySelector(
+      '.kj-number-input__stepper--up',
+    ) as HTMLButtonElement;
+    up.click();
+    fixture.detectChanges();
+    expect(fixture.componentInstance.value()).toBe(4);
+  });
+
+  test('clicking the decrement button decreases the value', () => {
+    const fixture = TestBed.createComponent(HostComponent);
+    fixture.detectChanges();
+    const down = fixture.nativeElement.querySelector(
+      '.kj-number-input__stepper--down',
+    ) as HTMLButtonElement;
+    down.click();
+    fixture.detectChanges();
+    expect(fixture.componentInstance.value()).toBe(2);
+  });
+
+  test('increment button reports aria-disabled at kjMax', () => {
+    const fixture = TestBed.createComponent(HostComponent);
+    fixture.componentInstance.value.set(10);
+    fixture.detectChanges();
+    const up = fixture.nativeElement.querySelector(
+      '.kj-number-input__stepper--up',
+    ) as HTMLButtonElement;
+    expect(up.getAttribute('aria-disabled')).toBe('true');
+  });
+
+  test('decrement button reports aria-disabled at kjMin', () => {
+    const fixture = TestBed.createComponent(HostComponent);
+    fixture.componentInstance.value.set(0);
+    fixture.detectChanges();
+    const down = fixture.nativeElement.querySelector(
+      '.kj-number-input__stepper--down',
+    ) as HTMLButtonElement;
+    expect(down.getAttribute('aria-disabled')).toBe('true');
+  });
+
+  test('forwards kjDisabled to the wrapper data attribute and the field', () => {
+    const fixture = TestBed.createComponent(HostComponent);
+    fixture.componentInstance.disabled = true;
+    fixture.detectChanges();
+    const root = fixture.nativeElement.querySelector('.kj-number-input');
+    expect(root.getAttribute('data-disabled')).toBe('');
+  });
+});

package/src/number-input/number-input.ts

@@ -0,0 +1,212 @@
+import {
+  ChangeDetectionStrategy,
+  Component,
+  ElementRef,
+  ModelSignal,
+  ViewEncapsulation,
+  booleanAttribute,
+  input,
+  model,
+  viewChild,
+} from '@angular/core';
+import {
+  KjNumberInput,
+  KjNumberInputGroup,
+  KjNumberStepper,
+} from '@kouji-ui/core';
+
+/**
+ * Styled wrapper around the headless `KjNumberInput` directive family.
+ *
+ * Renders an internal `[kjNumberInput]` field flanked (or stacked) with two
+ * `[kjNumberStepper]` buttons. All directive inputs (`kjMin`, `kjMax`,
+ * `kjStep`, `kjFormat`, `kjLocale`, `kjCurrency`, …) are forwarded; the
+ * `[(kjValue)]` model is two-way bindable.
+ *
+ * @doc-example Default
+ *   The bare-minimum recipe — a quantity stepper bound to a number signal.
+ *   @doc-file number-input.example.ts
+ * @doc-example Usage
+ *   A walkthrough of the most common usages — quantity, bounded picker, and
+ *   currency formatting. Use this as the copy-paste starting point.
+ *   @doc-file number-input.usage.example.ts
+ * @doc-example With explicit stepper buttons
+ *   `kjStepperLayout="flanking"` keeps the +/- buttons on either side.
+ *   @doc-file number-input.with-stepper.example.ts
+ * @doc-example Min / max / step
+ *   Bound the input via `kjMin` / `kjMax`; `kjStep` drives the +/- delta.
+ *   @doc-file number-input.min-max.example.ts
+ * @doc-example Decimal precision
+ *   `kjMinimumFractionDigits` and `kjMaximumFractionDigits` pin the display.
+ *   @doc-file number-input.decimal.example.ts
+ * @doc-example Currency formatting
+ *   `kjFormat="currency"` + `kjCurrency` + `kjLocale` — Intl.NumberFormat all the way.
+ *   @doc-file number-input.currency.example.ts
+ *
+ * @doc-keyboard
+ *   ArrowUp       — Increment by `kjStep`
+ *   ArrowDown     — Decrement by `kjStep`
+ *   PageUp        — Increment by `kjPageStep` (when > 0)
+ *   PageDown      — Decrement by `kjPageStep` (when > 0)
+ *   Home          — Jump to `kjMin`
+ *   End           — Jump to `kjMax`
+ *   Enter         — Commit the typed value and reformat
+ *
+ * @doc-aria
+ *   role="spinbutton"   — On the inner `<input>` (provided by the directive)
+ *   aria-valuemin       — Reflects `kjMin`
+ *   aria-valuemax       — Reflects `kjMax`
+ *   aria-valuenow       — Reflects the current numeric value
+ *   aria-invalid        — Reflects `kjInvalid`
+ *   aria-disabled       — Reflects `kjDisabled` on field + stepper buttons
+ *   aria-label          — Wired from `kjAriaLabel`; required for icon-only / no-label usage
+ *
+ * @doc-touch
+ *   The two stepper buttons render at `--kj-number-input-stepper-size`
+ *   (defaults to 2.75rem / 44px) — meets WCAG 2.5.5. The field row matches
+ *   `kj-input` height for form-row alignment.
+ *
+ * @doc-a11y
+ *   Composes a real `<input>` with the spinbutton role and locale-aware
+ *   formatting. Always pair with a visible `<label>` or set `kjAriaLabel` —
+ *   the directive does not synthesise an accessible name. The +/- buttons
+ *   own their own `kjDecrementLabel` / `kjIncrementLabel` for SR clarity.
+ *
+ * @doc-related input,slider,form
+ *
+ * @doc-css-var
+ *   --kj-number-input-bg            — Background fill. Inherits --kj-bg-field.
+ *   --kj-number-input-fg            — Foreground (text) color.
+ *   --kj-number-input-border-color  — Border color. Flips to danger when [data-invalid].
+ *   --kj-number-input-border-width  — Border thickness. Inherits --kj-border.
+ *   --kj-number-input-radius        — Corner radius. Inherits --kj-radius-field.
+ *   --kj-number-input-padding-x     — Horizontal padding on the inner field.
+ *   --kj-number-input-font          — Font family. Defaults to --kj-font-sans.
+ *   --kj-number-input-font-size     — Font size. Size attributes override.
+ *   --kj-number-input-height        — Row height. Matches input/select for form alignment.
+ *   --kj-number-input-stepper-bg    — Stepper button background fill.
+ *   --kj-number-input-stepper-fg    — Stepper button foreground color.
+ *   --kj-number-input-stepper-size  — Stepper button min width/height. Drives touch target.
+ *
+ * @doc-category Library/Data input
+ * @doc
+ * @doc-name number-input
+ * @doc-description Themed numeric input with stepper buttons, locale formatting, and min/max/step constraints.
+ * @doc-is-main
+ */
+@Component({
+  selector: 'kj-number-input',
+  standalone: true,
+  imports: [KjNumberInput, KjNumberInputGroup, KjNumberStepper],
+  template: `
+    <div
+      kjNumberInputGroup
+      class="kj-number-input"
+      [attr.data-stepper-layout]="kjStepperLayout()"
+      [attr.data-size]="kjSize() === 'md' ? null : kjSize()"
+      [attr.data-disabled]="kjDisabled() ? '' : null"
+    >
+      <button
+        type="button"
+        kjNumberStepper
+        kjStep="down"
+        class="kj-number-input__stepper kj-number-input__stepper--down"
+        [kjAriaLabel]="kjDecrementLabel()"
+        [kjDisabled]="kjDisabled()"
+      >−</button>
+      <input
+        #nativeInput
+        kjNumberInput
+        class="kj-number-input__field"
+        [(kjValue)]="kjValue"
+        [kjMin]="kjMin()"
+        [kjMax]="kjMax()"
+        [kjStep]="kjStep()"
+        [kjPageStep]="kjPageStep()"
+        [kjAllowEmpty]="kjAllowEmpty()"
+        [kjAllowDecimals]="kjAllowDecimals()"
+        [kjAllowNegative]="kjAllowNegative()"
+        [kjReadonly]="kjReadonly()"
+        [kjDisabled]="kjDisabled()"
+        [kjInvalid]="kjInvalid()"
+        [kjUseNativeNumber]="kjUseNativeNumber()"
+        [kjFormat]="kjFormat()"
+        [kjLocale]="kjLocale()"
+        [kjCurrency]="kjCurrency()"
+        [kjCurrencyDisplay]="kjCurrencyDisplay()"
+        [kjUnit]="kjUnit()"
+        [kjUnitDisplay]="kjUnitDisplay()"
+        [kjUseGrouping]="kjUseGrouping()"
+        [kjMinimumFractionDigits]="kjMinimumFractionDigits()"
+        [kjMaximumFractionDigits]="kjMaximumFractionDigits()"
+        [kjAriaLabel]="kjAriaLabel()"
+        [placeholder]="kjPlaceholder()"
+      />
+      <button
+        type="button"
+        kjNumberStepper
+        kjStep="up"
+        class="kj-number-input__stepper kj-number-input__stepper--up"
+        [kjAriaLabel]="kjIncrementLabel()"
+        [kjDisabled]="kjDisabled()"
+      >+</button>
+    </div>
+  `,
+  styleUrl: './number-input.css',
+  encapsulation: ViewEncapsulation.None,
+  host: { style: 'display: contents;' },
+  changeDetection: ChangeDetectionStrategy.OnPush,
+})
+export class KjNumberInputComponent {
+  /** Two-way bindable numeric model. `null` for empty. */
+  readonly kjValue: ModelSignal<number> = model<number>(0);
+
+  /** Native `<input>` element queried via template-ref. Exposed so callers
+   *  (cell editors, form managers) can move focus without reaching into
+   *  the DOM. */
+  readonly nativeInput = viewChild<ElementRef<HTMLInputElement>>('nativeInput');
+
+  /** Focus the underlying `<input>`. No-op until the view renders. */
+  focus(): void {
+    this.nativeInput()?.nativeElement.focus();
+  }
+
+  readonly kjMin = input<number>(Number.NEGATIVE_INFINITY);
+  readonly kjMax = input<number>(Number.POSITIVE_INFINITY);
+  readonly kjStep = input<number>(1);
+  readonly kjPageStep = input<number>(0);
+
+  readonly kjAllowEmpty = input(true, { transform: booleanAttribute });
+  readonly kjAllowDecimals = input(true, { transform: booleanAttribute });
+  readonly kjAllowNegative = input(true, { transform: booleanAttribute });
+  readonly kjReadonly = input(false, { transform: booleanAttribute });
+  readonly kjDisabled = input(false, { transform: booleanAttribute });
+  readonly kjInvalid = input(false, { transform: booleanAttribute });
+  readonly kjUseNativeNumber = input(false, { transform: booleanAttribute });
+
+  readonly kjFormat = input<'decimal' | 'currency' | 'percent' | 'unit'>('decimal');
+  readonly kjLocale = input<string>('');
+  readonly kjCurrency = input<string>('');
+  readonly kjCurrencyDisplay = input<'symbol' | 'narrowSymbol' | 'code' | 'name'>('symbol');
+  readonly kjUnit = input<string>('');
+  readonly kjUnitDisplay = input<'short' | 'long' | 'narrow'>('short');
+  readonly kjUseGrouping = input(true, { transform: booleanAttribute });
+  readonly kjMinimumFractionDigits = input<number>(0);
+  readonly kjMaximumFractionDigits = input<number>(0);
+
+  readonly kjPlaceholder = input<string>('');
+  readonly kjAriaLabel = input<string>('');
+
+  /** Layout for the stepper buttons. */
+  readonly kjStepperLayout = input<'flanking' | 'stacked'>('flanking');
+
+  /** Size tier — matches `KjInput`. `xs` (28px) hides the steppers so the
+   *  control collapses to a bare numeric field for filter rows / inline edits. */
+  readonly kjSize = input<'xs' | 'sm' | 'md' | 'lg'>('md');
+
+  /** Accessible label for the decrement button. */
+  readonly kjDecrementLabel = input<string>('Decrease value');
+
+  /** Accessible label for the increment button. */
+  readonly kjIncrementLabel = input<string>('Increase value');
+}

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

@@ -0,0 +1,73 @@
+import { Component, signal, ChangeDetectionStrategy } from '@angular/core';
+import { KjNumberInputComponent } from './number-input';
+
+/**
+ * A walkthrough of the most common number-input usages — a plain quantity
+ * stepper, a constrained min/max/step picker, and a currency-formatted price
+ * field. Use this as the copy-paste starting point for new forms.
+ */
+@Component({
+  selector: 'kj-number-input-usage-example',
+  standalone: true,
+  imports: [KjNumberInputComponent],
+  styles: [
+    `
+      :host {
+        display: flex;
+        flex-direction: column;
+        gap: var(--kj-space-md);
+      }
+      .row {
+        display: flex;
+        gap: var(--kj-space-md);
+        flex-wrap: wrap;
+        align-items: center;
+      }
+      label {
+        font-size: 0.875rem;
+        color: var(--kj-fg-default);
+        display: grid;
+        gap: var(--kj-space-xs);
+      }
+    `,
+  ],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: `
+    <div class="row">
+      <!-- eslint-disable-next-line @angular-eslint/template/label-has-associated-control -->
+      <label>
+        Quantity
+        <kj-number-input [(kjValue)]="qty" kjAriaLabel="Quantity" />
+      </label>
+      <!-- eslint-disable-next-line @angular-eslint/template/label-has-associated-control -->
+      <label>
+        Servings (1–12)
+        <kj-number-input
+          [(kjValue)]="servings"
+          [kjMin]="1"
+          [kjMax]="12"
+          [kjStep]="1"
+          kjAriaLabel="Servings"
+        />
+      </label>
+      <!-- eslint-disable-next-line @angular-eslint/template/label-has-associated-control -->
+      <label>
+        Price
+        <kj-number-input
+          [(kjValue)]="price"
+          kjFormat="currency"
+          kjCurrency="USD"
+          kjLocale="en-US"
+          [kjMinimumFractionDigits]="2"
+          [kjMaximumFractionDigits]="2"
+          kjAriaLabel="Price"
+        />
+      </label>
+    </div>
+  `,
+})
+export class KjNumberInputUsageExample {
+  readonly qty = signal<number>(3);
+  readonly servings = signal<number>(4);
+  readonly price = signal<number>(19.99);
+}

package/src/overlay/overlay.css

@@ -0,0 +1,32 @@
+/* ─────────────────────────────────────────────────────────────
+   @kouji-ui/components — overlay-family aggregator
+   --------------------------------------------------------------
+   Single global stylesheet entry for every overlay-based piece in
+   the kit. Re-exports:
+
+   - The core overlay primitive's container/wrapper/backdrop CSS
+     (`@kouji-ui/core/src/primitives/overlay/overlay.css`).
+   - Every themed overlay-family component stylesheet
+     (popover, tooltip, dropdown-menu, dialog, drawer, toast,
+     confirm-popup).
+
+   Each themed file is also imported by its wrapper component's
+   `styleUrl`, so the wrapper-component path keeps working. This
+   aggregator exists so the directive-level API (e.g.
+   `<kj-dropdown-menu-content>` straight from `@kouji-ui/core`)
+   is styled without forcing consumers to instantiate the wrapper
+   component.
+
+   Register this file once in your build configuration (e.g. via
+   `angular.json` `styles`) alongside `@kouji-ui/themes`.
+   ──────────────────────────────────────────────────────────── */
+
+@import "../../../core/src/primitives/overlay/overlay.css";
+
+@import "../popover/popover.css";
+@import "../tooltip/tooltip.css";
+@import "../dropdown-menu/dropdown-menu.css";
+@import "../dialog/dialog.css";
+@import "../drawer/drawer.css";
+@import "../toast/toast.css";
+@import "../confirm-popup/confirm-popup.css";

package/src/overlay-badge/_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 { KjOverlayBadgeDescribedExample } from './overlay-badge.described.example';
+export { KjOverlayBadgeDotExample } from './overlay-badge.dot.example';
+export { KjOverlayBadgeExample } from './overlay-badge.example';
+export { KjOverlayBadgeOnAvatarExample } from './overlay-badge.on-avatar.example';
+export { KjOverlayBadgePositionsExample } from './overlay-badge.positions.example';

package/src/overlay-badge/_examples/overlay-badge.described.example.ts

@@ -0,0 +1,36 @@
+import { Component, ChangeDetectionStrategy } from '@angular/core';
+import { KjButtonComponent } from '../../button/button';
+import { KjOverlayBadgeComponent } from '../overlay-badge';
+
+/**
+ * Demonstrates `kjDescription` for AT context. The description text is
+ * rendered in a visually-hidden span and its id is merged into the
+ * anchor's `aria-describedby`. Without this wiring the badge would be
+ * `aria-hidden` — a stray "248" with no context is worse than silence.
+ *
+ * The `kjValue` of `248` is also above the default `kjMaxValue` of `99`,
+ * so it paints as `99+`.
+ */
+@Component({
+  selector: 'kj-overlay-badge-described-example',
+  standalone: true,
+  imports: [KjOverlayBadgeComponent, KjButtonComponent],
+  styles: [
+    `
+      :host {
+        display: block;
+      }
+    `,
+  ],
+  changeDetection: ChangeDetectionStrategy.Eager,
+  template: `
+    <kj-overlay-badge
+      [kjValue]="248"
+      kjVariant="destructive"
+      kjDescription="More than 99 unread messages"
+    >
+      <kj-button kjVariant="secondary">Messages</kj-button>
+    </kj-overlay-badge>
+  `,
+})
+export class KjOverlayBadgeDescribedExample {}