@textui/core 0.1.0

package/src/core/animation.ts

@@ -0,0 +1,144 @@
+import type { AnimationDriver, Easing, TickerOptions, TweenOptions } from '../types/animation.js';
+import type { Disposable } from '../types/disposable.js';
+import { toDisposable } from '../util/disposable.js';
+
+const EASINGS: Record<string, (t: number) => number> = {
+  linear: (t) => t,
+  easeIn: (t) => t * t,
+  easeOut: (t) => t * (2 - t),
+  easeInOut: (t) => (t < 0.5 ? 2 * t * t : -1 + (4 - 2 * t) * t),
+};
+
+function easingFn(easing: Easing | undefined): (t: number) => number {
+  if (typeof easing === 'function') return easing;
+  return EASINGS[easing ?? 'easeOut'] as (t: number) => number;
+}
+
+interface Ticker {
+  fps: number;
+  onTick(frame: number, elapsedMs: number): void;
+  frame: number;
+  accumulated: number;
+}
+
+/**
+ * One driver for everything that moves.
+ *
+ * Spinners, progress, value transitions and appearing elements all run off the
+ * same clock, so `enabled = false` is a single flag that stops all of it, and
+ * a slow link can drop the frame rate for all of it at once. The clock can
+ * also be driven by hand, which is how the test harness advances time.
+ */
+export class Animation implements AnimationDriver {
+  enabled = true;
+  maxFps = 30;
+
+  private tickers = new Set<Ticker>();
+  private timer: ReturnType<typeof setInterval> | null = null;
+  private lastTime = 0;
+  private manual: boolean;
+
+  constructor(options: { enabled?: boolean; maxFps?: number; manual?: boolean } = {}) {
+    this.enabled = options.enabled ?? true;
+    this.maxFps = options.maxFps ?? 30;
+    this.manual = options.manual ?? false;
+  }
+
+  get disabled(): boolean {
+    return !this.enabled;
+  }
+
+  ticker(options: TickerOptions): Disposable {
+    const entry: Ticker = {
+      fps: Math.min(options.fps ?? this.maxFps, this.maxFps),
+      onTick: options.onTick,
+      frame: 0,
+      accumulated: 0,
+    };
+    this.tickers.add(entry);
+    this.ensureRunning();
+    return toDisposable(() => {
+      this.tickers.delete(entry);
+      this.stopIfIdle();
+    });
+  }
+
+  tween(options: TweenOptions): Disposable {
+    const { from, to, durationMs, onUpdate, onComplete } = options;
+    const ease = easingFn(options.easing);
+
+    if (!this.enabled || durationMs <= 0) {
+      onUpdate(to);
+      onComplete?.();
+      return toDisposable(() => {});
+    }
+
+    let elapsed = 0;
+    const ticker = this.ticker({
+      fps: this.maxFps,
+      onTick: (_frame, delta) => {
+        elapsed += delta;
+        const t = Math.min(1, elapsed / durationMs);
+        onUpdate(from + (to - from) * ease(t));
+        if (t >= 1) {
+          ticker.dispose();
+          onComplete?.();
+        }
+      },
+    });
+    return ticker;
+  }
+
+  /** Advance by hand. The test harness and the static renderer use this. */
+  advance(ms: number): void {
+    this.tick(ms);
+  }
+
+  private tick(delta: number): void {
+    if (!this.enabled) return;
+    for (const ticker of [...this.tickers]) {
+      const interval = 1000 / Math.max(1, ticker.fps);
+      ticker.accumulated += delta;
+      if (ticker.accumulated < interval) continue;
+
+      const frames = Math.floor(ticker.accumulated / interval);
+      ticker.accumulated -= frames * interval;
+      ticker.frame += frames;
+      try {
+        ticker.onTick(ticker.frame, frames * interval);
+      } catch {
+        // A failing ticker must not take the frame loop down with it.
+        this.tickers.delete(ticker);
+      }
+    }
+  }
+
+  private ensureRunning(): void {
+    if (this.manual || this.timer || !this.enabled || this.tickers.size === 0) return;
+    const interval = Math.max(1000 / this.maxFps, 16);
+    this.lastTime = Date.now();
+    this.timer = setInterval(() => {
+      const now = Date.now();
+      const delta = now - this.lastTime;
+      this.lastTime = now;
+      this.tick(delta);
+    }, interval);
+    this.timer.unref?.();
+  }
+
+  private stopIfIdle(): void {
+    if (this.tickers.size > 0 || !this.timer) return;
+    clearInterval(this.timer);
+    this.timer = null;
+  }
+
+  dispose(): void {
+    if (this.timer) clearInterval(this.timer);
+    this.timer = null;
+    this.tickers.clear();
+  }
+}
+
+export function createAnimation(options?: ConstructorParameters<typeof Animation>[0]): Animation {
+  return new Animation(options);
+}

package/src/core/clipboard.ts

@@ -0,0 +1,40 @@
+import type { BindingPath } from '../types/graph.js';
+import type { ReactiveStore } from '../types/store.js';
+import type { TerminalAdapter } from '../types/terminal.js';
+
+/**
+ * The clipboard.
+ *
+ * A terminal can be *told* what to put on the system clipboard - OSC 52 - and
+ * cannot be asked what is on it. The read half of that sequence is a way for
+ * anything with a pty to read whatever you last copied, so terminals worth
+ * using refuse it, and the ones that answer are the ones you would not want
+ * to. So a copy goes two places: out to the system clipboard, where the rest
+ * of the desktop can reach it, and into the store, which is the half a paste
+ * can read back.
+ *
+ * That makes the store the clipboard as far as this application is concerned.
+ * It is in the session scope because a clipboard is not worth persisting and
+ * is worth surviving a screen change.
+ */
+export const CLIPBOARD_PATH = '$/session/clipboard' as BindingPath;
+
+export function readClipboard(store: ReactiveStore): string {
+  return store.get<string>(CLIPBOARD_PATH) ?? '';
+}
+
+/**
+ * Put text on the clipboard.
+ *
+ * The terminal is optional because the store half is the half that has to
+ * work: a session with no OSC 52 - a plain console, a pipe, the test harness -
+ * still copies and pastes within the application.
+ */
+export function writeClipboard(
+  store: ReactiveStore,
+  text: string,
+  terminal?: TerminalAdapter | null,
+): void {
+  store.set(CLIPBOARD_PATH, text);
+  terminal?.writeClipboard?.(text);
+}

package/src/core/commands.ts

@@ -0,0 +1,169 @@
+import type {
+  CommandContext, CommandDefinition, CommandRegistry, CommandScope,
+} from '../types/command.js';
+import type { Disposable } from '../types/disposable.js';
+import type { ReactiveStore } from '../types/store.js';
+import type { WhenEngine } from '../types/when.js';
+import type { TextUIApp } from '../types/app.js';
+import { toDisposable } from '../util/disposable.js';
+
+const SCOPE_ORDER: CommandScope[] = ['component', 'region', 'screen', 'app'];
+
+/**
+ * Commands are the only way an action should be spelled.
+ *
+ * A button that calls an API directly and a palette entry that calls the same
+ * API are two implementations that will drift; a button that runs a registered
+ * command cannot drift from the command. That is also why resolution walks
+ * from the most specific scope outward - `table.search` means whichever table
+ * is focused, without every table inventing its own id.
+ */
+export class Commands implements CommandRegistry {
+  private byId = new Map<string, CommandDefinition[]>();
+  /** Scope instance ids that are currently active, innermost first. */
+  private activeScopes: string[] = [];
+
+  constructor(
+    private deps: {
+      store: ReactiveStore;
+      when: WhenEngine;
+      app(): TextUIApp | null;
+      onError(err: unknown, context: string): void;
+    },
+  ) {}
+
+  setActiveScopes(ids: string[]): void {
+    this.activeScopes = ids;
+  }
+
+  register(def: CommandDefinition): Disposable {
+    const list = this.byId.get(def.id) ?? [];
+    list.push(def);
+    this.byId.set(def.id, list);
+
+    return toDisposable(() => {
+      const current = this.byId.get(def.id);
+      if (!current) return;
+      const next = current.filter((d) => d !== def);
+      if (next.length === 0) this.byId.delete(def.id);
+      else this.byId.set(def.id, next);
+    });
+  }
+
+  unregister(id: string, scopeId?: string): void {
+    if (scopeId === undefined) {
+      this.byId.delete(id);
+      return;
+    }
+    const next = (this.byId.get(id) ?? []).filter((d) => d.scopeId !== scopeId);
+    if (next.length === 0) this.byId.delete(id);
+    else this.byId.set(id, next);
+  }
+
+  get(id: string): CommandDefinition | undefined {
+    return this.resolve(id);
+  }
+
+  list(options: { scope?: CommandScope; slot?: string; enabledOnly?: boolean } = {}): CommandDefinition[] {
+    const out: CommandDefinition[] = [];
+    for (const defs of this.byId.values()) {
+      for (const def of defs) {
+        if (options.scope && (def.scope ?? 'app') !== options.scope) continue;
+        if (options.slot && !(def.slots ?? []).includes(options.slot)) continue;
+        if (options.enabledOnly && !this.deps.when.evaluate(def.when)) continue;
+        out.push(def);
+      }
+    }
+    return out;
+  }
+
+  /** Innermost active scope wins; an app-scoped registration is the floor. */
+  resolve(id: string): CommandDefinition | undefined {
+    const candidates = (this.byId.get(id) ?? []).filter((def) =>
+      this.deps.when.evaluate(def.when),
+    );
+    if (candidates.length === 0) return undefined;
+    if (candidates.length === 1) return candidates[0];
+
+    for (const scopeId of this.activeScopes) {
+      const match = candidates.find((d) => d.scopeId === scopeId);
+      if (match) return match;
+    }
+    for (const scope of SCOPE_ORDER) {
+      const match = candidates.find((d) => (d.scope ?? 'app') === scope && !d.scopeId);
+      if (match) return match;
+    }
+    return candidates[candidates.length - 1];
+  }
+
+  enabled(id: string): boolean {
+    return this.resolve(id) !== undefined;
+  }
+
+  isChecked(id: string): boolean | undefined {
+    const clause = this.resolve(id)?.checked;
+    return clause === undefined ? undefined : this.deps.when.evaluate(clause);
+  }
+
+  async execute(
+    id: string,
+    args: Record<string, unknown> = {},
+    source: CommandContext['source'] = 'api',
+  ): Promise<unknown> {
+    const def = this.resolve(id);
+    if (!def) {
+      // Registered but gated is not the same as absent, and it used to be
+      // reported as absent: `alt+left` with nothing open said "no command
+      // registered as go.previousTab" about a command registered forty lines
+      // away, whose `when` simply did not pass.
+      //
+      // A `when` that does not pass is the command saying "not now", which is
+      // what it is for - so this does nothing, and the key does nothing. A
+      // typo still throws, because a keybinding pointing at a name that was
+      // never registered has to be findable.
+      if ((this.byId.get(id) ?? []).length > 0) return undefined;
+      throw new Error(`[textui] no command registered as "${id}"`);
+    }
+
+    const missing = (def.args ?? [])
+      .filter((a) => a.required && args[a.name] === undefined && a.default === undefined)
+      .map((a) => a.name);
+    if (missing.length > 0) {
+      throw new Error(`[textui] command "${id}" needs: ${missing.join(', ')}`);
+    }
+
+    const filled: Record<string, unknown> = { ...args };
+    for (const spec of def.args ?? []) {
+      if (filled[spec.name] === undefined && spec.default !== undefined) {
+        filled[spec.name] = spec.default;
+      }
+    }
+
+    const app = this.deps.app();
+    const ctx: CommandContext = {
+      app: app as TextUIApp,
+      store: this.deps.store,
+      scopeId: def.scopeId ?? null,
+      source,
+    };
+
+    // Announced, not just run. Which command fired and what asked for it is
+    // the first question anyone debugging a keybinding, a menu or a palette
+    // has, and reconstructing it from its effects is guesswork.
+    app?.events.emit('@/command/run', { id, source, args: filled });
+
+    try {
+      const result = await def.run(filled, ctx);
+      app?.events.emit('@/command/done', { id, source });
+      return result;
+    } catch (err) {
+      app?.events.emit('@/command/error', { id, source, message: String(err) });
+      this.deps.onError(err, `command "${id}"`);
+      throw err;
+    }
+  }
+}
+
+export function createCommands(deps: ConstructorParameters<typeof Commands>[0]): Commands {
+  return new Commands(deps);
+}

package/src/core/components.ts

@@ -0,0 +1,91 @@
+import type {
+  ComponentCategory, ComponentDefinition, ComponentRegistry,
+} from '../types/component-registry.js';
+import type { Disposable } from '../types/disposable.js';
+import { toDisposable, createBag } from '../util/disposable.js';
+
+/**
+ * Late binding is the mechanism the whole design rests on: a graph names a
+ * component, and the name is resolved at mount time. A name that was never
+ * registered is a runtime miss rather than a compile error - that is the price
+ * of a screen being data, and it is why the miss renders visibly.
+ */
+export class Components implements ComponentRegistry {
+  private defs = new Map<string, ComponentDefinition>();
+  private resolving = new Map<string, Promise<ComponentDefinition>>();
+
+  register(def: ComponentDefinition): Disposable {
+    this.defs.set(def.component, def);
+    return toDisposable(() => {
+      if (this.defs.get(def.component) === def) this.defs.delete(def.component);
+    });
+  }
+
+  registerMany(defs: ComponentDefinition[]): Disposable {
+    const bag = createBag();
+    for (const def of defs) bag.add(this.register(def));
+    return bag;
+  }
+
+  unregister(component: string): void {
+    this.defs.delete(component);
+    this.resolving.delete(component);
+  }
+
+  get(component: string): ComponentDefinition | undefined {
+    return this.defs.get(component);
+  }
+
+  has(component: string): boolean {
+    return this.defs.has(component);
+  }
+
+  list(category?: ComponentCategory): ComponentDefinition[] {
+    const all = [...this.defs.values()];
+    return category ? all.filter((d) => d.category === category) : all;
+  }
+
+  async resolve(component: string): Promise<ComponentDefinition> {
+    const def = this.defs.get(component);
+    if (!def) throw new Error(`[textui] no component registered as "${component}"`);
+    if (def.renderer.kind !== 'lazy') return def;
+
+    const inFlight = this.resolving.get(component);
+    if (inFlight) return inFlight;
+
+    const load = def.renderer.load;
+    const promise = Promise.resolve(load()).then((mod) => {
+      const render = typeof mod === 'function' ? mod : mod.default;
+      const resolved: ComponentDefinition = {
+        ...def,
+        renderer: { kind: 'function', render },
+      };
+      this.defs.set(component, resolved);
+      this.resolving.delete(component);
+      return resolved;
+    });
+
+    this.resolving.set(component, promise);
+    return promise;
+  }
+
+  pending(): string[] {
+    return [...this.defs.values()]
+      .filter((d) => d.renderer.kind === 'lazy')
+      .map((d) => d.component);
+  }
+
+  /**
+   * Which components can display a resource of this kind. The selector is not
+   * evaluated here - a caller with a store re-filters through `when`.
+   */
+  findOpeners(resourceKind: string): ComponentDefinition[] {
+    return [...this.defs.values()]
+      .filter((d) => d.opens?.resourceKinds?.some((k) => k === resourceKind || resourceKind.startsWith(k + '.')))
+      .sort((a, b) => (b.opens?.priority ?? 0) - (a.opens?.priority ?? 0));
+  }
+}
+
+export function createComponents(): Components {
+  return new Components();
+}

package/src/core/events.ts

@@ -0,0 +1,95 @@
+import type { EventBus } from '../types/store.js';
+import type { EventPath } from '../types/graph.js';
+import type { Disposable } from '../types/disposable.js';
+import { toDisposable } from '../util/disposable.js';
+import { isDescendantKey, matchKey } from '../util/paths.js';
+
+interface Listener {
+  key: string;
+  subtree: boolean;
+  wildcard: boolean;
+  once: boolean;
+  fn: (payload: unknown, path: EventPath) => void;
+}
+
+function eventKey(path: string): string {
+  const body = path.startsWith('@/') ? path.slice(2) : path.replace(/^\//, '');
+  return body.split('/').filter((s) => s !== '').join('/');
+}
+
+/**
+ * Transient events, addressed like store paths on purpose - `@/dialog/confirm`
+ * reads the same way `$/dialog/open` does - but with no value to read back.
+ * That difference is the whole reason they are two mechanisms.
+ */
+export class Events implements EventBus {
+  private listeners = new Set<Listener>();
+  private disposed = false;
+
+  onError: (err: unknown, context: string) => void = (err, context) => {
+    console.error(`[textui/events] ${context}`, err);
+  };
+
+  emit(path: EventPath, payload?: unknown): void {
+    if (this.disposed) return;
+    const key = eventKey(path);
+    for (const listener of [...this.listeners]) {
+      if (!this.matches(listener, key)) continue;
+      if (listener.once) this.listeners.delete(listener);
+      try {
+        listener.fn(payload, path);
+      } catch (err) {
+        this.onError(err, `listener of @/${listener.key}`);
+      }
+    }
+  }
+
+  private matches(listener: Listener, key: string): boolean {
+    if (listener.wildcard) return matchKey(key, listener.key, listener.subtree);
+    if (listener.key === key) return true;
+    return listener.subtree && isDescendantKey(key, listener.key);
+  }
+
+  on(
+    path: EventPath,
+    fn: (payload: unknown, path: EventPath) => void,
+    options: { subtree?: boolean; once?: boolean } = {},
+  ): Disposable {
+    const key = eventKey(path);
+    const listener: Listener = {
+      key,
+      subtree: options.subtree ?? false,
+      wildcard: key.includes('*'),
+      once: options.once ?? false,
+      fn,
+    };
+    this.listeners.add(listener);
+    return toDisposable(() => this.listeners.delete(listener));
+  }
+
+  next(path: EventPath, timeoutMs?: number): Promise<unknown> {
+    return new Promise((resolve, reject) => {
+      const sub = this.on(path, (payload) => {
+        if (timer) clearTimeout(timer);
+        resolve(payload);
+      }, { once: true });
+
+      const timer = timeoutMs
+        ? setTimeout(() => {
+            sub.dispose();
+            reject(new Error(`timed out waiting for ${path}`));
+          }, timeoutMs)
+        : null;
+      timer?.unref?.();
+    });
+  }
+
+  dispose(): void {
+    this.disposed = true;
+    this.listeners.clear();
+  }
+}
+
+export function createEvents(): Events {
+  return new Events();
+}