@kouji-ui/core 0.0.3 → 0.1.1

package/src/menubar/menubar.ts

@@ -0,0 +1,309 @@
+import {
+  Directive,
+  Injector,
+  booleanAttribute,
+  contentChildren,
+  effect,
+  forwardRef,
+  inject,
+  input,
+  numberAttribute,
+  output,
+  signal,
+  untracked,
+} from '@angular/core';
+import {
+  KJ_LIST_FOCUS_MODE,
+  KJ_LIST_NAVIGATOR_CONFIG,
+  KjListItem,
+  KjListNavigator,
+  KjTypeAhead,
+  type KjCompareFn,
+  type KjListFocusMode,
+  type KjListNavigatorConfig,
+} from '../primitives/list';
+import {
+  KJ_MENUBAR,
+  type KjMenubarContext,
+  type KjMenubarItemContext,
+} from './menubar.context';
+
+/**
+ * The application menubar — `role="menubar"`, a horizontal row of top-level
+ * menu disclosures (File / Edit / View / Help …). Each child
+ * `[kjMenubarItem]` owns a submenu opened on activation.
+ *
+ * Composition:
+ *
+ * - Implements {@link KjListNavigatorConfig} (items + `afterSelect`) and
+ *   provides itself via `KJ_LIST_NAVIGATOR_CONFIG`.
+ * - Composes `KjListNavigator` via `hostDirectives` so the navigator's
+ *   element-injector lives on the bar's host, giving `KjListItem`s under
+ *   the bar a navigator to register with.
+ * - Forces `KJ_LIST_FOCUS_MODE = 'roving'` (host-directive inputs cannot
+ *   be defaulted from a composing directive — same workaround as
+ *   `KjDropdownMenuContent`). This makes `KjListItem.tabIndex` track the
+ *   navigator's active id.
+ * - Provides `KjTypeAhead` so the navigator routes printable characters
+ *   to the matching bar item.
+ * - The navigator's built-in keyboard handler defaults to vertical
+ *   orientation. Since defaulting host-directive inputs is impossible
+ *   from a composing directive, the menubar handles `ArrowLeft`,
+ *   `ArrowRight`, `Home`, `End`, `Escape` itself, delegating to
+ *   `KjListNavigator.moveBy / moveToFirst / moveToLast` — the navigator
+ *   remains the single source of truth for active id + skip-disabled.
+ *
+ * @doc-category Core/Navigation
+ * @doc
+ * @doc-name menubar
+ * @doc-description Unstyled application menubar with horizontal arrow-key navigation and roving focus.
+ * @doc-is-main
+ */
+@Directive({
+  selector: '[kjMenubar]',
+  standalone: true,
+  exportAs: 'kjMenubar',
+  hostDirectives: [KjListNavigator],
+  providers: [
+    { provide: KJ_MENUBAR, useExisting: KjMenubar },
+    { provide: KJ_LIST_NAVIGATOR_CONFIG, useExisting: forwardRef(() => KjMenubar) },
+    {
+      provide: KJ_LIST_FOCUS_MODE,
+      useFactory: () => signal<KjListFocusMode>('roving'),
+    },
+    KjTypeAhead,
+  ],
+  host: {
+    'role': 'menubar',
+    'aria-orientation': 'horizontal',
+    '[attr.aria-label]': 'kjAriaLabel() || null',
+    '(keydown)': '_onKeydown($event)',
+    '(focusin)': '_onFocusin($event)',
+  },
+})
+export class KjMenubar implements KjMenubarContext, KjListNavigatorConfig {
+  /** When `true`, ArrowRight at the last item wraps to the first (and vice versa). */
+  readonly kjLoop = input(false, { transform: booleanAttribute });
+  readonly loop = this.kjLoop;
+
+  /**
+   * Deprecated. The pre-primitives bar shipped a "roll-over" hover auto-disclose
+   * mode here; with the new composition, hover is opt-in per consumer (e.g. by
+   * listening to `pointerenter` on `[kjMenubarItem]`). Kept as a no-op input
+   * so existing template bindings don't break — remove in a major bump.
+   * @deprecated
+   */
+  readonly kjAutoDisclose = input(true, { transform: booleanAttribute });
+
+  /**
+   * Deprecated. Roll-over dwell delay used by the old auto-disclose path —
+   * unused in the primitives-based menubar. Kept as a no-op input to avoid
+   * breaking existing template bindings.
+   * @deprecated
+   */
+  readonly kjAutoDiscloseDelayMs = input(0, { transform: numberAttribute });
+
+  /** Optional accessible name forwarded to the host as `aria-label`. */
+  readonly kjAriaLabel = input<string | null>(null);
+
+  /** Emits the bar item's id when its popup opens, or `null` when all are closed. */
+  readonly kjOpenChange = output<string | null>();
+
+  // ── KjListNavigatorConfig ────────────────────────────────────────────
+
+  /** All `KjListItem`s composed by `KjMenubarItem` children. */
+  readonly items = contentChildren(KjListItem, { descendants: true });
+  /** No selection model on a menubar. Identity compare. */
+  readonly compareBy = signal<KjCompareFn<unknown>>(Object.is as KjCompareFn<unknown>);
+
+  /**
+   * Required by `KjListNavigatorConfig`. The menubar has no selection
+   * model and activation is wired item-side (`KjMenubarItem` subscribes
+   * to its own composed `KjListItem.activate` and toggles its submenu)
+   * because the bar's nav active id doesn't always identify the item
+   * that was clicked (mouse click can fire before focusin). Kept as a
+   * no-op stub to satisfy the contract.
+   */
+  afterSelect(_value: unknown, _closeRequested: boolean): void {
+    /* no-op: each KjMenubarItem owns its own activation */
+  }
+
+  // ── KjMenubarContext ─────────────────────────────────────────────────
+
+  private readonly _items = signal<KjMenubarItemContext[]>([]);
+  /** @internal Used by `afterSelect` to resolve `KjListItem` ids back to bar items. */
+  readonly _itemCtxs = this._items.asReadonly();
+
+  private readonly _openItem = signal<KjMenubarItemContext | null>(null);
+  readonly openItem = this._openItem.asReadonly();
+
+  registerItem(item: KjMenubarItemContext): void {
+    this._items.update((arr) => {
+      if (arr.includes(item)) return arr;
+      const next = [...arr, item];
+      // Sort by DOM order so ArrowLeft / ArrowRight follow visual order
+      // regardless of the order in which items happen to register.
+      next.sort((a, b) => {
+        const pos = a.el.compareDocumentPosition(b.el);
+        if (pos & Node.DOCUMENT_POSITION_FOLLOWING) return -1;
+        if (pos & Node.DOCUMENT_POSITION_PRECEDING) return 1;
+        return 0;
+      });
+      return next;
+    });
+  }
+
+  unregisterItem(item: KjMenubarItemContext): void {
+    this._items.update((arr) => arr.filter((i) => i !== item));
+    if (this._openItem() === item) this._openItem.set(null);
+  }
+
+  notifyItemOpened(item: KjMenubarItemContext): void {
+    const prev = this._openItem();
+    if (prev && prev !== item) prev.closePopup();
+    this._openItem.set(item);
+    this.kjOpenChange.emit(item.el.id || null);
+  }
+
+  notifyItemClosed(item: KjMenubarItemContext): void {
+    if (this._openItem() === item) {
+      this._openItem.set(null);
+      this.kjOpenChange.emit(null);
+    }
+  }
+
+  // ── Keyboard ─────────────────────────────────────────────────────────
+
+  /**
+   * Horizontal navigation routes here because `KjListNavigator`'s
+   * `kjOrientation` cannot be defaulted by a composing directive (it
+   * stays at `'vertical'`, so its built-in ArrowLeft/Right would no-op).
+   * `Home`, `End`, `Escape`, and `ArrowDown` (open submenu) are owned at
+   * the menubar level too; `Enter` / `Space` reach the focused item's
+   * `KjListItem._activate` directly and route through `afterSelect`.
+   * Type-ahead is handled by the navigator via the provided `KjTypeAhead`
+   * (printable keys → navigator's default handler matches haystacks).
+   */
+  protected _onKeydown(event: KeyboardEvent): void {
+    const nav = this._nav();
+    if (!nav) return;
+    switch (event.key) {
+      case 'ArrowRight':
+        event.preventDefault();
+        this._move(nav, 1);
+        return;
+      case 'ArrowLeft':
+        event.preventDefault();
+        this._move(nav, -1);
+        return;
+      case 'Home':
+        event.preventDefault();
+        nav.moveToFirst();
+        nav.activeItem()?._host()?.focus();
+        return;
+      case 'End':
+        event.preventDefault();
+        nav.moveToLast();
+        nav.activeItem()?._host()?.focus();
+        return;
+      case 'ArrowDown': {
+        // APG menubar: ArrowDown on a top-level item opens its submenu.
+        const id = nav.activeId();
+        if (!id) return;
+        const ctx = this._items().find((c) => c.el.id === id);
+        if (!ctx || ctx.disabled()) return;
+        event.preventDefault();
+        ctx.openPopup();
+        return;
+      }
+      case 'Escape': {
+        const open = this._openItem();
+        if (!open) return;
+        event.preventDefault();
+        event.stopPropagation();
+        open.closePopup();
+        return;
+      }
+    }
+  }
+
+  /**
+   * Wrap-aware move. `KjListNavigator.moveBy` always uses its own `kjWrap`
+   * (default `true`), and that input can't be defaulted by a composing
+   * directive — so the menubar clamps before delegating when `kjLoop()`
+   * is `false`.
+   */
+  private _move(nav: KjListNavigator, delta: 1 | -1): void {
+    if (!this.kjLoop()) {
+      const navigable = this.items().filter((i) => !i.disabled());
+      if (!navigable.length) return;
+      const idx = navigable.findIndex((i) => i.id === nav.activeId());
+      if (delta > 0 && idx >= navigable.length - 1) return;
+      if (delta < 0 && idx <= 0) return;
+    }
+    nav.moveBy(delta);
+    // Synchronously mirror the navigator's new active id into DOM focus.
+    // The roving focus-follow effect (mounted in the constructor) also
+    // does this, but with `vi.useFakeTimers({ toFake: ['queueMicrotask'] })`
+    // active in the spec the effect can be deferred past the test's
+    // assertion — drive focus here so keyboard navigation never depends
+    // on microtask scheduling.
+    nav.activeItem()?._host()?.focus();
+  }
+
+  /**
+   * Keep the navigator's active id aligned with the actually-focused bar
+   * item (e.g. user clicked on a different item, or Tabbed in). `focusin`
+   * bubbles up to the menubar host, so we resolve which item caught
+   * focus by walking up from the event target.
+   */
+  protected _onFocusin(event: FocusEvent): void {
+    const target = event.target as HTMLElement | null;
+    if (!target) return;
+    const nav = this._nav();
+    if (!nav) return;
+    const item = this.items().find((i) => i._host() === target);
+    if (item) nav.setActive(item.id);
+  }
+
+  // ── Navigator resolution + roving effects ────────────────────────────
+
+  private readonly _injector = inject(Injector);
+  private _navCache: KjListNavigator | null | undefined = undefined;
+  private _nav(): KjListNavigator | null {
+    if (this._navCache !== undefined) return this._navCache;
+    this._navCache = this._injector.get(KjListNavigator, null, { self: true });
+    return this._navCache;
+  }
+
+  constructor() {
+    // Roving seed: set the navigator's active id to the first non-disabled
+    // item so its `tabindex=0` makes the bar reachable by Tab on first
+    // render (WAI-ARIA APG). Same pattern as `KjDropdownMenuContent`,
+    // needed because `KjListNavigator`'s built-in seed gates on its
+    // `kjFocusMode()` input (which defaults to `'activedescendant'` and
+    // can't be defaulted from a composing directive).
+    effect(() => {
+      const nav = this._nav();
+      if (!nav) return;
+      const list = this.items();
+      if (nav.activeId() !== null) return;
+      const first = list.find((i) => !i.disabled());
+      if (first) untracked(() => nav.setActive(first.id));
+    });
+
+    // Roving focus follow: mirror the navigator's `activeItem()` into DOM
+    // focus. Same rationale as the seed — `KjListNavigator`'s built-in
+    // focus-follow gates on its own `kjFocusMode()`.
+    effect(() => {
+      const nav = this._nav();
+      if (!nav) return;
+      const item = nav.activeItem();
+      if (!item) return;
+      const host = item._host();
+      if (host && typeof document !== 'undefined' && document.activeElement !== host) {
+        untracked(() => host.focus());
+      }
+    });
+  }
+}

package/src/number-input/index.ts

@@ -0,0 +1,4 @@
+export { KjNumberInput } from './number-input';
+export { KjNumberStepper } from './number-stepper';
+export { KjNumberInputGroup } from './number-input-group';
+export { KJ_NUMBER_INPUT, type KjNumberInputContext } from './number-input.context';

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

@@ -0,0 +1,64 @@
+import { Directive, Signal, computed, signal } from '@angular/core';
+import { KJ_NUMBER_INPUT, KjNumberInputContext } from './number-input.context';
+
+/**
+ * Layout container for `[kjNumberInput]` + `[kjNumberStepper]`.
+ *
+ * Acts as a *context bridge*: the group provides `KJ_NUMBER_INPUT`, the
+ * `[kjNumberInput]` registers itself with the group on construction, and
+ * sibling `[kjNumberStepper]` directives inject the group's context to find
+ * the input. This lets steppers and the input live as DOM siblings while
+ * still sharing state via DI.
+ *
+ * Without the group the input still publishes the context to its own
+ * descendants, but stepper buttons that are not descendants of the `<input>`
+ * (almost always the case) need the group as their common ancestor.
+ *
+ * @example
+ * ```html
+ * <div kjNumberInputGroup>
+ *   <button kjNumberStepper kjStep="down" aria-label="Decrease">−</button>
+ *   <input kjNumberInput [(kjValue)]="qty" />
+ *   <button kjNumberStepper kjStep="up" aria-label="Increase">+</button>
+ * </div>
+ * ```
+ * @doc-category Core/Inputs
+ * @doc
+ * @doc-name number-input
+ */
+@Directive({
+  selector: '[kjNumberInputGroup]',
+  standalone: true,
+  providers: [{ provide: KJ_NUMBER_INPUT, useExisting: KjNumberInputGroup }],
+  host: {
+    'role': 'group',
+  },
+})
+export class KjNumberInputGroup implements KjNumberInputContext {
+  private readonly registered = signal<KjNumberInputContext | null>(null);
+
+  /** Called by `[kjNumberInput]` from its constructor. @internal */
+  register(input: KjNumberInputContext): void {
+    this.registered.set(input);
+  }
+
+  // ── Forward each context member through to the registered input ──────────
+  // While no input is registered, the signals fall back to safe sentinel
+  // values; steppers inside an empty group are simply inert.
+
+  readonly value: Signal<number | null> = computed(() => this.registered()?.value() ?? null);
+  readonly min: Signal<number> = computed(() => this.registered()?.min() ?? -Infinity);
+  readonly max: Signal<number> = computed(() => this.registered()?.max() ?? Infinity);
+  readonly step: Signal<number> = computed(() => this.registered()?.step() ?? 1);
+  readonly pageStep: Signal<number> = computed(() => this.registered()?.pageStep() ?? 10);
+  readonly disabled: Signal<boolean> = computed(() => this.registered()?.disabled() ?? false);
+  readonly readonly: Signal<boolean> = computed(() => this.registered()?.readonly() ?? false);
+
+  stepBy(units: number, amount?: number): void {
+    this.registered()?.stepBy(units, amount);
+  }
+
+  setValue(value: number | null): void {
+    this.registered()?.setValue(value);
+  }
+}

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

@@ -0,0 +1,31 @@
+import { InjectionToken, Signal } from '@angular/core';
+
+/**
+ * Shared context published by `[kjNumberInput]` and consumed by sibling
+ * `[kjNumberStepper]` directives inside an optional `[kjNumberInputGroup]`.
+ *
+ * The number-input registers itself as the implementation; steppers call
+ * `stepBy()` for click / long-press activations.
+ */
+export interface KjNumberInputContext {
+  /** Current numeric value, or `null` for empty. */
+  readonly value: Signal<number | null>;
+  /** Effective minimum (`-Infinity` when no `kjMin` is set). */
+  readonly min: Signal<number>;
+  /** Effective maximum (`+Infinity` when no `kjMax` is set). */
+  readonly max: Signal<number>;
+  /** Step amount used for stepper presses and ArrowUp / ArrowDown. */
+  readonly step: Signal<number>;
+  /** PageUp / PageDown amount. Defaults to `step * 10`. */
+  readonly pageStep: Signal<number>;
+  /** Whether the field is fully disabled. */
+  readonly disabled: Signal<boolean>;
+  /** Whether the field is read-only. */
+  readonly readonly: Signal<boolean>;
+  /** Apply `n` step units. Positive for up, negative for down. Clamps + snaps. */
+  stepBy(units: number, amount?: number): void;
+  /** Set the value directly. Clamps + snaps. */
+  setValue(value: number | null): void;
+}
+
+export const KJ_NUMBER_INPUT = new InjectionToken<KjNumberInputContext>('KjNumberInput');

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

@@ -0,0 +1,148 @@
+/**
+ * Internal format / parse helpers for `[kjNumberInput]`.
+ *
+ * `Intl.NumberFormat` ships no standard `parse()` method. We compose one by
+ * inspecting `formatToParts()` to derive the locale's group and decimal
+ * separators, plus a regex per (locale, options) pair. Best-effort: locales
+ * with non-ASCII digits (`ar-EG`) parse both Arabic-Indic and Western digits;
+ * mixed / malformed input falls back to `null`.
+ */
+
+export interface KjNumberFormatOptions {
+  readonly locale?: string;
+  readonly format?: 'decimal' | 'currency' | 'percent' | 'unit';
+  readonly currency?: string;
+  readonly currencyDisplay?: 'symbol' | 'narrowSymbol' | 'code' | 'name';
+  readonly unit?: string;
+  readonly unitDisplay?: 'short' | 'long' | 'narrow';
+  readonly useGrouping?: boolean;
+  readonly minimumFractionDigits?: number;
+  readonly maximumFractionDigits?: number;
+  readonly minimumIntegerDigits?: number;
+  readonly minimumSignificantDigits?: number;
+  readonly maximumSignificantDigits?: number;
+}
+
+/** Build an `Intl.NumberFormat` options bag from our directive inputs. */
+function toIntlOptions(options: KjNumberFormatOptions): Intl.NumberFormatOptions {
+  const o: Intl.NumberFormatOptions = {};
+  if (options.format) o.style = options.format;
+  if (options.format === 'currency' && options.currency) o.currency = options.currency;
+  if (options.currencyDisplay) o.currencyDisplay = options.currencyDisplay;
+  if (options.format === 'unit' && options.unit) o.unit = options.unit;
+  if (options.unitDisplay) o.unitDisplay = options.unitDisplay;
+  if (options.useGrouping !== undefined) o.useGrouping = options.useGrouping;
+  if (options.minimumFractionDigits !== undefined) o.minimumFractionDigits = options.minimumFractionDigits;
+  if (options.maximumFractionDigits !== undefined) o.maximumFractionDigits = options.maximumFractionDigits;
+  if (options.minimumIntegerDigits !== undefined) o.minimumIntegerDigits = options.minimumIntegerDigits;
+  if (options.minimumSignificantDigits !== undefined) o.minimumSignificantDigits = options.minimumSignificantDigits;
+  if (options.maximumSignificantDigits !== undefined) o.maximumSignificantDigits = options.maximumSignificantDigits;
+  return o;
+}
+
+/** Format `value` for display (with grouping / currency / unit / percent). */
+export function formatNumber(
+  value: number,
+  options: KjNumberFormatOptions,
+): string {
+  try {
+    return new Intl.NumberFormat(options.locale, toIntlOptions(options)).format(value);
+  } catch {
+    return String(value);
+  }
+}
+
+/** Format `value` for *editing*: locale decimal separator, sign, digits — no grouping, no symbol. */
+export function formatForEdit(value: number, locale: string | undefined): string {
+  try {
+    return new Intl.NumberFormat(locale, { useGrouping: false, maximumFractionDigits: 20 }).format(value);
+  } catch {
+    return String(value);
+  }
+}
+
+/** Cache of (locale → separators) — `Intl.NumberFormat` instantiation is non-trivial. */
+const separatorCache = new Map<string, { group: string; decimal: string }>();
+
+/** Derive group + decimal separators for a locale via `formatToParts`. */
+export function getSeparators(locale: string | undefined): { group: string; decimal: string } {
+  const key = locale ?? '';
+  const hit = separatorCache.get(key);
+  if (hit) return hit;
+  let group = ',';
+  let decimal = '.';
+  try {
+    const parts = new Intl.NumberFormat(locale, { useGrouping: true }).formatToParts(12345.6);
+    for (const p of parts) {
+      if (p.type === 'group') group = p.value;
+      else if (p.type === 'decimal') decimal = p.value;
+    }
+  } catch {
+    /* fall back to defaults */
+  }
+  const sep = { group, decimal };
+  separatorCache.set(key, sep);
+  return sep;
+}
+
+/**
+ * Parse a user-typed / pasted string into a number. Strips currency / percent /
+ * unit symbols, normalises Arabic-Indic digits, accepts the locale's decimal
+ * separator. Returns `null` for empty / unparseable input.
+ *
+ * For percent format, the user types `50` and we store `0.5` — the multiplier
+ * is applied here when `format === 'percent'`.
+ */
+export function parseNumber(
+  raw: string,
+  options: KjNumberFormatOptions,
+): number | null {
+  if (raw == null) return null;
+  const trimmed = String(raw).trim();
+  if (trimmed === '') return null;
+
+  const { group, decimal } = getSeparators(options.locale);
+
+  // Normalise Arabic-Indic (0660-0669) and extended Arabic-Indic (06F0-06F9) digits.
+  let s = trimmed.replace(/[٠-٩]/g, d => String(d.charCodeAt(0) - 0x0660));
+  s = s.replace(/[۰-۹]/g, d => String(d.charCodeAt(0) - 0x06F0));
+
+  // Drop everything that is not a digit, sign, decimal sep, or group sep.
+  // Group separators (incl. NBSP / narrow NBSP) get dropped; decimal becomes '.'.
+  s = s.replace(new RegExp(`[${escapeRegex(group)}\u00A0\u202F\u2009 ]`, 'g'), '');
+  if (decimal !== '.') s = s.replace(new RegExp(escapeRegex(decimal), 'g'), '.');
+
+  // Strip everything except digits, '.', '-', '+'.
+  s = s.replace(/[^\d.+-]/g, '');
+  if (s === '' || s === '-' || s === '+' || s === '.') return null;
+
+  const n = Number(s);
+  if (!Number.isFinite(n)) return null;
+
+  if (options.format === 'percent') return n / 100;
+  return n;
+}
+
+function escapeRegex(s: string): string {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/** Clamp `value` into `[min, max]`. */
+export function clamp(value: number, min: number, max: number): number {
+  if (value < min) return min;
+  if (value > max) return max;
+  return value;
+}
+
+/** Snap `value` to the nearest `base + n * step` lattice. */
+export function snapToStep(value: number, step: number, base: number): number {
+  if (!Number.isFinite(step) || step <= 0) return value;
+  const offset = value - base;
+  const snapped = Math.round(offset / step) * step + base;
+  // Round to a sensible decimal precision derived from `step` to suppress FP drift.
+  const stepStr = String(step);
+  const dot = stepStr.indexOf('.');
+  const decimals = dot === -1 ? 0 : stepStr.length - dot - 1;
+  const factor = Math.pow(10, decimals);
+  return Math.round(snapped * factor) / factor;
+}