@textui/core 0.1.0

package/src/core/focus.ts

@@ -0,0 +1,358 @@
+import type {
+  FocusableOptions, FocusDirection, FocusManager, FocusScopeOptions,
+} from '../types/focus.js';
+import type { KeyEvent } from '../types/input.js';
+import type { Rect } from '../types/geometry.js';
+import type { Disposable } from '../types/disposable.js';
+import { toDisposable } from '../util/disposable.js';
+import { rectContains } from '../types/geometry.js';
+
+interface Scope extends FocusScopeOptions {
+  /** What was focused when this scope activated, for `restore`. */
+  restoreTo: string | null;
+}
+
+/** The scope every global handler lives in, always active and always last. */
+export const GLOBAL_SCOPE = '__global__';
+
+/**
+ * Focus.
+ *
+ * Tab order is registration order within a scope unless a node states one.
+ * Directional navigation is geometric, because in a terminal "the thing to the
+ * right" is a real question a table, a menu and a dashboard all ask, and none
+ * of them can answer it from document order.
+ */
+export class Focus implements FocusManager {
+  private scopes = new Map<string, Scope>();
+  private nodes = new Map<string, FocusableOptions>();
+  /** Registration order, which is tab order when nothing states otherwise. */
+  private order_: string[] = [];
+  private stack: string[] = [];
+  private current: string | null = null;
+
+  constructor(private onChange: () => void = () => {}) {
+    this.scopes.set(GLOBAL_SCOPE, { id: GLOBAL_SCOPE, priority: -1, restoreTo: null });
+    this.stack.push(GLOBAL_SCOPE);
+  }
+
+  // ------------------------------------------------------------- scopes
+
+  registerScope(options: FocusScopeOptions): Disposable {
+    this.scopes.set(options.id, { ...options, restoreTo: null });
+    return toDisposable(() => {
+      this.deactivateScope(options.id);
+      this.scopes.delete(options.id);
+    });
+  }
+
+  activateScope(id: string): void {
+    const scope = this.scopes.get(id);
+    if (!scope) return;
+    if (this.stack.includes(id)) return;
+
+    scope.restoreTo = this.current;
+    this.stack.push(id);
+
+    if (scope.autoFocus) {
+      const first = this.order(id)[0];
+      if (first) this.focus(first);
+    }
+    this.onChange();
+  }
+
+  deactivateScope(id: string): void {
+    const index = this.stack.indexOf(id);
+    if (index <= 0) return;
+    const scope = this.scopes.get(id);
+    this.stack.splice(index, 1);
+
+    // A scope closing may only move focus it was holding. Blurring regardless
+    // took focus off whatever was driving the change - a sidebar that swaps
+    // the screen beside it lost focus on every arrow press, and the incoming
+    // screen then claimed it, so the sidebar could be moved exactly once.
+    // "Nothing holds focus" counts as held: a scope closing takes its own
+    // contents with it, so by the time this runs the thing it had focused has
+    // usually already unmounted. What must not count is focus sitting on
+    // something *outside* - that belongs to whoever put it there.
+    const held = this.current === null || this.scopeOf(this.current) === id;
+
+    if (scope?.restore && held) {
+      const target = scope.restoreTo;
+      scope.restoreTo = null;
+      if (target && this.nodes.has(target)) {
+        this.focus(target);
+        return;
+      }
+      this.blur();
+    } else if (scope?.restore) {
+      scope.restoreTo = null;
+    } else if (held) {
+      this.blur();
+    }
+    this.onChange();
+  }
+
+  activeScope(): string | null {
+    const top = this.stack[this.stack.length - 1];
+    return top === GLOBAL_SCOPE ? null : top ?? null;
+  }
+
+  /** The innermost active scope that traps, if any. */
+  private trappingScope(): string | null {
+    for (let i = this.stack.length - 1; i >= 0; i--) {
+      const id = this.stack[i] as string;
+      if (this.scopes.get(id)?.trap) return id;
+    }
+    return null;
+  }
+
+  /** Which scope a focusable belongs to. `GLOBAL_SCOPE` when it names none. */
+  scopeOf(nodeId: string): string {
+    return this.nodes.get(nodeId)?.scopeId ?? GLOBAL_SCOPE;
+  }
+
+  // ---------------------------------------------------------- focusables
+
+  register(options: FocusableOptions): Disposable {
+    const existing = this.nodes.has(options.id);
+    this.nodes.set(options.id, options);
+    if (!existing) this.order_.push(options.id);
+
+    // A scope that asked to take focus takes it here, as its first control
+    // arrives - not when it was activated, because a scope is empty then. Its
+    // contents register on the way up, one effect at a time, and effects run
+    // parent-first, so `autoFocus` at activation could only ever have found
+    // something in a scope that already had something in it.
+    //
+    // Only when *nothing at all* holds focus. That is the difference between
+    // the screen this is for - pushed over whatever had focus, which the push
+    // unmounted, leaving none - and a dialog, which opens while its opener
+    // still holds focus and whose own controls say which of them wants it.
+    if (!existing && options.disabled !== true && this.current === null) {
+      const scopeId = options.scopeId ?? GLOBAL_SCOPE;
+      if (this.scopes.get(scopeId)?.autoFocus === true && this.stack.includes(scopeId)) {
+        this.focus(options.id);
+      }
+    }
+
+    return toDisposable(() => {
+      this.nodes.delete(options.id);
+      const i = this.order_.indexOf(options.id);
+      if (i >= 0) this.order_.splice(i, 1);
+      if (this.current === options.id) {
+        this.current = null;
+        this.onChange();
+      }
+    });
+  }
+
+  update(id: string, patch: Partial<FocusableOptions>): void {
+    const node = this.nodes.get(id);
+    if (!node) return;
+    this.nodes.set(id, { ...node, ...patch });
+
+    // Focus cannot sit on something that has just been disabled. Nothing else
+    // would move it - the keys it would have handled are now nobody's - so the
+    // tab order is the only way out and this is what puts the reader back in
+    // it.
+    if (patch.disabled === true && this.current === id) {
+      this.current = null;
+      node.onBlur?.();
+      this.onChange();
+    }
+  }
+
+  has(id: string): boolean {
+    return this.nodes.has(id);
+  }
+
+  focus(id: string): boolean {
+    const node = this.nodes.get(id);
+    if (!node || node.disabled) return false;
+    if (this.current === id) return true;
+
+    const previous = this.current ? this.nodes.get(this.current) : undefined;
+    this.current = id;
+    previous?.onBlur?.();
+    node.onFocus?.();
+    this.onChange();
+    return true;
+  }
+
+  blur(): void {
+    if (!this.current) return;
+    const node = this.nodes.get(this.current);
+    this.current = null;
+    node?.onBlur?.();
+    this.onChange();
+  }
+
+  focused(): string | null {
+    return this.current;
+  }
+
+  chain(): string[] {
+    const out: string[] = [];
+    if (this.current) out.push(this.current);
+    for (let i = this.stack.length - 1; i >= 0; i--) out.push(this.stack[i] as string);
+    return out;
+  }
+
+  /** Tab order: explicit `order` first, then registration order. */
+  order(scopeId?: string): string[] {
+    const trap = this.trappingScope();
+    const scope = scopeId ?? trap ?? undefined;
+
+    const candidates = this.order_
+      .map((id) => this.nodes.get(id))
+      .filter((n): n is FocusableOptions => {
+        if (!n || n.disabled || n.skipTab) return false;
+        if (scope === undefined) return true;
+        return (n.scopeId ?? GLOBAL_SCOPE) === scope;
+      });
+
+    return candidates
+      .map((n, i) => ({ n, i }))
+      .sort((a, b) => {
+        const ao = a.n.order ?? Number.MAX_SAFE_INTEGER;
+        const bo = b.n.order ?? Number.MAX_SAFE_INTEGER;
+        return ao === bo ? a.i - b.i : ao - bo;
+      })
+      .map((e) => e.n.id);
+  }
+
+  move(direction: FocusDirection): string | null {
+    if (direction === 'next' || direction === 'previous') {
+      const list = this.order();
+      if (list.length === 0) return null;
+      const index = this.current ? list.indexOf(this.current) : -1;
+      const step = direction === 'next' ? 1 : -1;
+      const nextIndex = index === -1
+        ? (direction === 'next' ? 0 : list.length - 1)
+        : (index + step + list.length) % list.length;
+      const id = list[nextIndex] as string;
+      return this.focus(id) ? id : null;
+    }
+    return this.moveDirectional(direction);
+  }
+
+  /**
+   * Geometric navigation. Candidates must lie in the requested direction; the
+   * winner is the nearest, with distance along the axis weighted more heavily
+   * than drift across it, so `right` from a table cell finds the next column
+   * rather than a distant button that happens to be closer in a straight line.
+   */
+  private moveDirectional(direction: 'up' | 'down' | 'left' | 'right'): string | null {
+    const from = this.current ? this.nodes.get(this.current) : undefined;
+    const origin = from?.rect;
+    if (!origin) {
+      const first = this.order()[0];
+      return first && this.focus(first) ? first : null;
+    }
+
+    const trap = this.trappingScope();
+    const cx = origin.x + origin.width / 2;
+    const cy = origin.y + origin.height / 2;
+
+    let best: { id: string; score: number } | null = null;
+
+    for (const node of this.nodes.values()) {
+      if (node.id === from.id || node.disabled || !node.rect) continue;
+      if (trap && (node.scopeId ?? GLOBAL_SCOPE) !== trap) continue;
+
+      const r = node.rect;
+      const nx = r.x + r.width / 2;
+      const ny = r.y + r.height / 2;
+      const dx = nx - cx;
+      const dy = ny - cy;
+
+      const along = direction === 'left' ? -dx : direction === 'right' ? dx
+        : direction === 'up' ? -dy : dy;
+      if (along <= 0) continue;
+
+      const across = direction === 'left' || direction === 'right'
+        ? Math.abs(dy)
+        : Math.abs(dx);
+
+      const score = along + across * 3;
+      if (!best || score < best.score) best = { id: node.id, score };
+    }
+
+    if (!best) return null;
+    return this.focus(best.id) ? best.id : null;
+  }
+
+  at(x: number, y: number): string | null {
+    let found: string | null = null;
+    let smallest = Infinity;
+    for (const node of this.nodes.values()) {
+      if (node.disabled || !node.rect) continue;
+      if (!rectContains(node.rect as Rect, x, y)) continue;
+      // The innermost hit wins, and "innermost" is the smallest area.
+      const area = node.rect.width * node.rect.height;
+      if (area < smallest) {
+        smallest = area;
+        found = node.id;
+      }
+    }
+    return found;
+  }
+
+  /**
+   * Focused node first, then outward through active scopes, then global -
+   * except that a trap stops the walk at itself.
+   *
+   * `order` and `move` already honoured the trap, so tab could not leave a
+   * modal; keys could, and did. A menu bar whose labels live in the global
+   * scope kept receiving every arrow while its own dropdown was open, so down
+   * re-opened the menu instead of moving inside it, and a palette opened over
+   * the top inherited the same problem - two layers reading one keystroke, and
+   * two escapes needed to get out.
+   *
+   * A trap owns the keyboard. Nothing outside it is a target, including a
+   * focused node left over from before it opened.
+   */
+  dispatch(event: KeyEvent): boolean {
+    const trap = this.trappingScope();
+    const inTrap = (node: { scopeId?: string }): boolean =>
+      trap === null || (node.scopeId ?? GLOBAL_SCOPE) === trap;
+
+    if (this.current) {
+      const node = this.nodes.get(this.current);
+      if (node && inTrap(node) && (node.onKey?.(event) === true || event.handled)) return true;
+    }
+
+    // Then the handlers that are not about one control.
+    //
+    // Only those. This loop used to offer the event to every registered
+    // handler, focused or not, which quietly undid the line above it: a list
+    // moved on an arrow it never received, because the arrow reached it here.
+    // With nothing focused it went to whichever focusable registered first -
+    // so a page with two lists moved the earlier one, and a tab strip and a
+    // list beneath it split the arrow keys between them by accident. That
+    // reads as working until the second list exists.
+    for (let i = this.stack.length - 1; i >= 0; i--) {
+      const scopeId = this.stack[i] as string;
+      if (trap !== null && scopeId !== trap) continue;
+      for (const node of this.nodes.values()) {
+        if (node.id === this.current) continue;
+        if (node.global !== true) continue;
+        if ((node.scopeId ?? GLOBAL_SCOPE) !== scopeId) continue;
+        if (!node.onKey) continue;
+        if (node.onKey(event) === true || event.handled) return true;
+      }
+    }
+    return false;
+  }
+
+  /** Called by the renderer after layout, so hit-testing has real rects. */
+  setRect(id: string, rect: Rect): void {
+    const node = this.nodes.get(id);
+    if (node) node.rect = rect;
+  }
+}
+
+export function createFocus(onChange?: () => void): Focus {
+  return new Focus(onChange);
+}

package/src/core/i18n.ts

@@ -0,0 +1,107 @@
+import type { I18n, LocaleId, TranslationBundle } from '../types/i18n.js';
+import type { Disposable } from '../types/disposable.js';
+import { toDisposable } from '../util/disposable.js';
+
+function lookup(messages: Record<string, unknown>, key: string): string | undefined {
+  if (key in messages) {
+    const direct = messages[key];
+    return typeof direct === 'string' ? direct : undefined;
+  }
+  let cursor: unknown = messages;
+  for (const part of key.split('.')) {
+    if (cursor === null || typeof cursor !== 'object') return undefined;
+    cursor = (cursor as Record<string, unknown>)[part];
+  }
+  return typeof cursor === 'string' ? cursor : undefined;
+}
+
+function interpolate(template: string, values: Record<string, unknown>): string {
+  return template.replace(/\{(\w+)\}/g, (match, name: string) =>
+    name in values ? String(values[name]) : match,
+  );
+}
+
+/**
+ * Lightweight i18n. Formatting is `Intl`'s job - recreating number, date and
+ * list formatting would be a second, worse implementation of something the
+ * runtime already ships.
+ */
+export class I18nRegistry implements I18n {
+  locale: LocaleId;
+  private bundles = new Map<LocaleId, Record<string, unknown>>();
+  private listeners = new Set<(locale: LocaleId) => void>();
+
+  constructor(
+    locale: LocaleId = 'en',
+    private fallbackLocale: LocaleId = 'en',
+  ) {
+    this.locale = locale;
+  }
+
+  setLocale(locale: LocaleId): void {
+    if (this.locale === locale) return;
+    this.locale = locale;
+    for (const fn of [...this.listeners]) fn(locale);
+  }
+
+  register(bundle: TranslationBundle): Disposable {
+    const existing = this.bundles.get(bundle.locale) ?? {};
+    this.bundles.set(bundle.locale, { ...existing, ...bundle.messages });
+    if (this.locale === bundle.locale) {
+      for (const fn of [...this.listeners]) fn(this.locale);
+    }
+    return toDisposable(() => this.bundles.delete(bundle.locale));
+  }
+
+  locales(): LocaleId[] {
+    return [...this.bundles.keys()];
+  }
+
+  /** Missing keys fall through to the fallback locale, then to the key. */
+  t(key: string, values?: Record<string, unknown>): string {
+    const primary = this.bundles.get(this.locale);
+    const base = this.locale.includes('-')
+      ? this.bundles.get(this.locale.split('-')[0] as string)
+      : undefined;
+    const fallback = this.bundles.get(this.fallbackLocale);
+
+    const template =
+      (primary && lookup(primary, key)) ??
+      (base && lookup(base, key)) ??
+      (fallback && lookup(fallback, key)) ??
+      key;
+
+    return values ? interpolate(template, values) : template;
+  }
+
+  number(value: number, options?: Intl.NumberFormatOptions): string {
+    return new Intl.NumberFormat(this.locale, options).format(value);
+  }
+
+  date(value: Date | number, options?: Intl.DateTimeFormatOptions): string {
+    return new Intl.DateTimeFormat(this.locale, options).format(value);
+  }
+
+  relative(value: number, unit: Intl.RelativeTimeFormatUnit): string {
+    return new Intl.RelativeTimeFormat(this.locale, { numeric: 'auto' }).format(value, unit);
+  }
+
+  list(items: string[], options?: Intl.ListFormatOptions): string {
+    return new Intl.ListFormat(this.locale, options).format(items);
+  }
+
+  plural(count: number, forms: Record<string, string>): string {
+    const rule = new Intl.PluralRules(this.locale).select(count);
+    const template = forms[rule] ?? forms.other ?? '';
+    return interpolate(template, { count });
+  }
+
+  onChange(fn: (locale: LocaleId) => void): Disposable {
+    this.listeners.add(fn);
+    return toDisposable(() => this.listeners.delete(fn));
+  }
+}
+
+export function createI18n(locale?: string, fallback?: string): I18nRegistry {
+  return new I18nRegistry(locale, fallback);
+}

package/src/core/keybindings.ts

@@ -0,0 +1,184 @@
+import type { Chord, KeybindingDefinition, KeybindingRegistry } from '../types/keybinding.js';
+import type { KeyEvent } from '../types/input.js';
+import type { Disposable } from '../types/disposable.js';
+import type { WhenEngine } from '../types/when.js';
+import type { CommandRegistry } from '../types/command.js';
+import { toDisposable } from '../util/disposable.js';
+
+/** `ctrl+shift+p` or a sequence: `ctrl+k ctrl+s`, `g g`. */
+function parseChord(chord: Chord): string[] {
+  return chord.trim().split(/\s+/).map(normalizeStroke);
+}
+
+const MODIFIER = /^(ctrl|control|alt|option|shift|meta|cmd|super)\+/i;
+
+/**
+ * Split one stroke into its modifiers and its key.
+ *
+ * Modifiers are consumed off the front by name and whatever survives is the
+ * key, verbatim. Splitting on `+` cannot work here: `+` is the separator and
+ * a key, so `'+'.split('+')` loses the only thing it was asked about. Parsing
+ * forwards means `+` is `+`, and `ctrl++` is ctrl and `+`.
+ *
+ * One parser, exported, because a chord that the test harness presses and a
+ * chord that the registry stored have to agree - and two implementations of
+ * one grammar disagree eventually.
+ */
+export function splitStroke(stroke: string): { mods: string[]; key: string } {
+  const mods: string[] = [];
+  let rest = stroke.trim();
+  for (let match = MODIFIER.exec(rest); match !== null; match = MODIFIER.exec(rest)) {
+    const [whole, name = ''] = match;
+    mods.push(name.toLowerCase());
+    rest = rest.slice(whole.length);
+  }
+  return { mods, key: rest };
+}
+
+/** The canonical stroke a chord is filed under. `strokeOf` must agree with it. */
+export function normalizeStroke(stroke: string): string {
+  const { mods: names, key } = splitStroke(stroke);
+  const mods = new Set<string>();
+  for (const name of names) {
+    if (name === 'ctrl' || name === 'control') mods.add('ctrl');
+    else if (name === 'alt' || name === 'option') mods.add('alt');
+    else if (name === 'shift') mods.add('shift');
+    else mods.add('meta');
+  }
+  // Shift is not part of a stroke for a single character it *shifted*. A
+  // terminal reports a bare shift+p as the character `P`, and `strokeOf` reads
+  // it back that way, so `shift+p` would wait for a stroke no keypress makes.
+  //
+  // Held with another modifier it is the opposite. `ctrl+shift+p` cannot
+  // arrive as an uppercase letter, because a control code carries no case:
+  // a terminal speaking a keyboard protocol reports the *unshifted* key and a
+  // shift bit beside it. Dropping shift here filed `ctrl+shift+f` under
+  // `ctrl+f`, where it sat behind whichever binding registered first - so the
+  // workspace search had a documented key that ran the in-file search.
+  if ([...key].length === 1 && mods.size === 1 && mods.has('shift')) mods.delete('shift');
+
+  const order = ['ctrl', 'alt', 'shift', 'meta'].filter((m) => mods.has(m));
+  return [...order, key.toLowerCase()].join('+');
+}
+
+export function strokeOf(event: KeyEvent): string {
+  const mods: string[] = [];
+  if (event.ctrl) mods.push('ctrl');
+  if (event.alt) mods.push('alt');
+  // Shift is implied by an uppercase character, so it is not named for a
+  // single character on its own. Beside another modifier nothing is implied -
+  // the name is the unshifted key - so there it has to be said. Must agree
+  // with `normalizeStroke`.
+  const modified = event.ctrl || event.alt || event.meta;
+  if (event.shift && (event.name.length > 1 || modified)) mods.push('shift');
+  if (event.meta) mods.push('meta');
+  return [...mods, event.name.toLowerCase()].join('+');
+}
+
+/**
+ * Keybindings resolve to commands, never to handlers, so the same action is
+ * reachable from a chord, a menu row and the palette without three copies.
+ * A partially typed chord is remembered, which is what makes `ctrl+k ctrl+s`
+ * possible without blocking `ctrl+k` on its own.
+ */
+export class Keybindings implements KeybindingRegistry {
+  private bindings: (KeybindingDefinition & { strokes: string[] })[] = [];
+  private pending: string[] = [];
+  private pendingTimer: ReturnType<typeof setTimeout> | null = null;
+
+  constructor(
+    private deps: {
+      when: WhenEngine;
+      commands: CommandRegistry;
+      activeScopes(): string[];
+      onError(err: unknown, context: string): void;
+      /** How long a half-typed chord waits for its next stroke. */
+      chordTimeoutMs?: number;
+    },
+  ) {}
+
+  register(def: KeybindingDefinition): Disposable {
+    const entry = { ...def, strokes: parseChord(def.keys) };
+    this.bindings.push(entry);
+    this.bindings.sort((a, b) => (b.priority ?? 0) - (a.priority ?? 0));
+    return toDisposable(() => {
+      const i = this.bindings.indexOf(entry);
+      if (i >= 0) this.bindings.splice(i, 1);
+    });
+  }
+
+  unregister(keys: Chord, commandId?: string): void {
+    const strokes = parseChord(keys).join(' ');
+    this.bindings = this.bindings.filter(
+      (b) => !(b.strokes.join(' ') === strokes && (commandId === undefined || b.commandId === commandId)),
+    );
+  }
+
+  list(): KeybindingDefinition[] {
+    return this.bindings.map(({ strokes: _strokes, ...def }) => def);
+  }
+
+  forCommand(commandId: string): Chord[] {
+    return this.bindings
+      // An argument-bearing binding is a key for one invocation, not for the
+      // command. `ctrl+shift+b` opens the palette at the sidebar panels; it is
+      // not the key for "Command Palette", and offering it as one put a wrong
+      // - and wider - hint beside that menu row.
+      .filter((b) => b.commandId === commandId && b.args === undefined)
+      .map((b) => b.keys);
+  }
+
+  private applicable(binding: KeybindingDefinition): boolean {
+    if (!this.deps.when.evaluate(binding.when)) return false;
+    if (!binding.scopeId) return true;
+    return this.deps.activeScopes().includes(binding.scopeId);
+  }
+
+  handle(event: KeyEvent): 'handled' | 'pending' | 'unhandled' {
+    const stroke = strokeOf(event);
+    const sequence = [...this.pending, stroke];
+
+    let sawPrefix = false;
+    for (const binding of this.bindings) {
+      if (!this.applicable(binding)) continue;
+
+      const { strokes } = binding;
+      if (strokes.length === sequence.length && strokes.every((s, i) => s === sequence[i])) {
+        this.reset();
+        void this.deps.commands
+          .execute(binding.commandId, binding.args ?? {}, 'keybinding')
+          .catch((err: unknown) => this.deps.onError(err, `keybinding ${binding.keys}`));
+        return 'handled';
+      }
+      if (
+        strokes.length > sequence.length &&
+        sequence.every((s, i) => strokes[i] === s)
+      ) {
+        sawPrefix = true;
+      }
+    }
+
+    if (sawPrefix) {
+      this.pending = sequence;
+      if (this.pendingTimer) clearTimeout(this.pendingTimer);
+      this.pendingTimer = setTimeout(() => this.reset(), this.deps.chordTimeoutMs ?? 1200);
+      this.pendingTimer.unref?.();
+      return 'pending';
+    }
+
+    this.reset();
+    return 'unhandled';
+  }
+
+  reset(): void {
+    this.pending = [];
+    if (this.pendingTimer) {
+      clearTimeout(this.pendingTimer);
+      this.pendingTimer = null;
+    }
+  }
+}
+
+export function createKeybindings(deps: ConstructorParameters<typeof Keybindings>[0]): Keybindings {
+  return new Keybindings(deps);
+}