@textui/core 0.1.0

package/src/core/when.ts

@@ -0,0 +1,238 @@
+import type { ContextValue, WhenClause, WhenEngine } from '../types/when.js';
+import type { BindingPath } from '../types/graph.js';
+import type { ReactiveStore } from '../types/store.js';
+
+/**
+ * A `when` clause is a small expression over store paths and context keys.
+ * Chrome that should not exist for this user does not mount, rather than
+ * mounting disabled - which is why this evaluates rather than styles.
+ *
+ * Supported: `&&` `||` `!` `==` `!=` `>` `>=` `<` `<=` `=~`, parentheses,
+ * string/number/boolean literals, `$/store/paths` and bare context keys.
+ * Deliberately not a language: no calls, no member access, no assignment.
+ */
+
+type Token =
+  | { t: 'path'; v: string }
+  | { t: 'ident'; v: string }
+  | { t: 'string'; v: string }
+  | { t: 'number'; v: number }
+  | { t: 'op'; v: string };
+
+const OPERATORS = ['&&', '||', '==', '!=', '>=', '<=', '=~', '!', '>', '<', '(', ')'];
+
+function tokenize(input: string): Token[] {
+  const out: Token[] = [];
+  let i = 0;
+  while (i < input.length) {
+    const c = input[i] as string;
+    if (/\s/.test(c)) { i++; continue; }
+
+    if (c === '$' && input[i + 1] === '/') {
+      let j = i + 2;
+      while (j < input.length && /[A-Za-z0-9_\-./*]/.test(input[j] as string)) j++;
+      out.push({ t: 'path', v: input.slice(i, j) });
+      i = j;
+      continue;
+    }
+
+    if (c === "'" || c === '"') {
+      let j = i + 1;
+      let v = '';
+      while (j < input.length && input[j] !== c) {
+        if (input[j] === '\\') j++;
+        v += input[j];
+        j++;
+      }
+      out.push({ t: 'string', v });
+      i = j + 1;
+      continue;
+    }
+
+    if (/[0-9]/.test(c)) {
+      let j = i;
+      while (j < input.length && /[0-9.]/.test(input[j] as string)) j++;
+      out.push({ t: 'number', v: Number(input.slice(i, j)) });
+      i = j;
+      continue;
+    }
+
+    const op = OPERATORS.find((o) => input.startsWith(o, i));
+    if (op) {
+      out.push({ t: 'op', v: op });
+      i += op.length;
+      continue;
+    }
+
+    if (/[A-Za-z_]/.test(c)) {
+      let j = i;
+      while (j < input.length && /[A-Za-z0-9_.:-]/.test(input[j] as string)) j++;
+      out.push({ t: 'ident', v: input.slice(i, j) });
+      i = j;
+      continue;
+    }
+
+    throw new SyntaxError(`unexpected character "${c}" in when clause: ${input}`);
+  }
+  return out;
+}
+
+type Resolver = (name: string, isPath: boolean) => unknown;
+
+function truthy(v: unknown): boolean {
+  if (v === undefined || v === null) return false;
+  if (typeof v === 'boolean') return v;
+  if (typeof v === 'number') return v !== 0;
+  if (typeof v === 'string') return v !== '' && v !== 'false';
+  if (Array.isArray(v)) return v.length > 0;
+  return true;
+}
+
+class Parser {
+  private pos = 0;
+  constructor(private tokens: Token[], private resolve: Resolver) {}
+
+  parse(): unknown {
+    const v = this.or();
+    if (this.pos < this.tokens.length) {
+      throw new SyntaxError('trailing tokens in when clause');
+    }
+    return v;
+  }
+
+  private peek(): Token | undefined {
+    return this.tokens[this.pos];
+  }
+
+  private eat(op: string): boolean {
+    const t = this.peek();
+    if (t && t.t === 'op' && t.v === op) {
+      this.pos++;
+      return true;
+    }
+    return false;
+  }
+
+  private or(): unknown {
+    let left = this.and();
+    while (this.eat('||')) {
+      const right = this.and();
+      left = truthy(left) || truthy(right);
+    }
+    return left;
+  }
+
+  private and(): unknown {
+    let left = this.comparison();
+    while (this.eat('&&')) {
+      const right = this.comparison();
+      left = truthy(left) && truthy(right);
+    }
+    return left;
+  }
+
+  private comparison(): unknown {
+    const left = this.unary();
+    for (const op of ['==', '!=', '>=', '<=', '>', '<', '=~'] as const) {
+      if (this.eat(op)) {
+        const right = this.unary();
+        switch (op) {
+          case '==': return looseEquals(left, right);
+          case '!=': return !looseEquals(left, right);
+          case '>': return Number(left) > Number(right);
+          case '>=': return Number(left) >= Number(right);
+          case '<': return Number(left) < Number(right);
+          case '<=': return Number(left) <= Number(right);
+          case '=~': return new RegExp(String(right)).test(String(left ?? ''));
+        }
+      }
+    }
+    return left;
+  }
+
+  private unary(): unknown {
+    if (this.eat('!')) return !truthy(this.unary());
+    return this.primary();
+  }
+
+  private primary(): unknown {
+    if (this.eat('(')) {
+      const v = this.or();
+      if (!this.eat(')')) throw new SyntaxError('missing ")" in when clause');
+      return v;
+    }
+    const t = this.peek();
+    if (!t) throw new SyntaxError('unexpected end of when clause');
+    this.pos++;
+    switch (t.t) {
+      case 'string': return t.v;
+      case 'number': return t.v;
+      case 'path': return this.resolve(t.v, true);
+      case 'ident':
+        if (t.v === 'true') return true;
+        if (t.v === 'false') return false;
+        if (t.v === 'null') return null;
+        return this.resolve(t.v, false);
+      default:
+        throw new SyntaxError(`unexpected "${t.v}" in when clause`);
+    }
+  }
+}
+
+function looseEquals(a: unknown, b: unknown): boolean {
+  if (a === b) return true;
+  if (a == null || b == null) return false;
+  if (typeof a === 'number' || typeof b === 'number') return Number(a) === Number(b);
+  return String(a) === String(b);
+}
+
+export class When implements WhenEngine {
+  private context = new Map<string, ContextValue>();
+  private cache = new Map<string, Token[]>();
+
+  constructor(private store: ReactiveStore) {}
+
+  evaluate(clause: WhenClause | undefined, extra?: Record<string, ContextValue>): boolean {
+    if (!clause || clause.trim() === '') return true;
+    try {
+      let tokens = this.cache.get(clause);
+      if (!tokens) {
+        tokens = tokenize(clause);
+        this.cache.set(clause, tokens);
+      }
+      const resolve: Resolver = (name, isPath) => {
+        if (isPath) return this.store.get(name as BindingPath);
+        if (extra && name in extra) return extra[name];
+        return this.context.get(name);
+      };
+      return truthy(new Parser(tokens, resolve).parse());
+    } catch (err) {
+      // A malformed clause is a programmer error, and hiding chrome silently
+      // is worse than showing it - fail loud, render visible.
+      console.error(`[textui/when] bad clause "${clause}"`, err);
+      return true;
+    }
+  }
+
+  dependencies(clause: WhenClause): BindingPath[] {
+    try {
+      return tokenize(clause)
+        .filter((t): t is { t: 'path'; v: string } => t.t === 'path')
+        .map((t) => t.v as BindingPath);
+    } catch {
+      return [];
+    }
+  }
+
+  setContext(key: string, value: ContextValue): void {
+    this.context.set(key, value);
+  }
+
+  getContext(key: string): ContextValue | undefined {
+    return this.context.get(key);
+  }
+}
+
+export function createWhen(store: ReactiveStore): When {
+  return new When(store);
+}

package/src/index.ts

@@ -0,0 +1,76 @@
+// Contracts
+export * from './types/index.js';
+
+// JSX
+export { h, Fragment, defineComponent, componentNameOf, toSerializable, nodeFunction } from './jsx/factory.js';
+export type { BoxProps, TextProps, CanvasProps, SpacerProps, BaseProps } from './jsx/intrinsics.js';
+
+// Core
+export { createStore, Store } from './core/store.js';
+export { createEvents, Events } from './core/events.js';
+export { createWhen, When } from './core/when.js';
+export { createComponents, Components } from './core/components.js';
+export { createServices, Services } from './core/services.js';
+export { createCommands, Commands } from './core/commands.js';
+export { createKeybindings, Keybindings, strokeOf, splitStroke, normalizeStroke } from './core/keybindings.js';
+export { createFocus, Focus, GLOBAL_SCOPE } from './core/focus.js';
+export { createLayers, Layers } from './core/layers.js';
+export { createAnimation, Animation } from './core/animation.js';
+export { createI18n, I18nRegistry } from './core/i18n.js';
+export { CLIPBOARD_PATH, readClipboard, writeClipboard } from './core/clipboard.js';
+export { serviceKey } from './types/services.js';
+
+// Render
+export { Buffer, createBuffer } from './render/buffer.js';
+export { diffFrame } from './render/diff.js';
+export type { Frame, Run } from './render/diff.js';
+export * from './render/color.js';
+export { layout, measureBox, resolveEdges } from './render/layout.js';
+export type { LayoutBox } from './render/layout.js';
+export { renderOnce, renderToString, createStaticRuntime } from './render/static.js';
+export type { StaticRenderOptions, StaticRenderResult } from './render/static.js';
+
+// Runtime
+export type { Runtime } from './runtime/runtime.js';
+export type { Instance } from './runtime/instance.js';
+export { renderTree, collectEffects, disposeTree } from './runtime/reconcile.js';
+export { buildBoxes, paintTree, createRenderContext } from './runtime/paint.js';
+export type { PaintEnv } from './runtime/paint.js';
+export * from './runtime/style.js';
+export * from './runtime/hooks.js';
+export { Screen, SCREEN_COMPONENTS } from './ui/screen.js';
+export type { ScreenProps } from './ui/screen.js';
+
+// The application
+export { App, createApp, WRITER_KEY } from './app/app.js';
+export type { FrameWriter } from './app/app.js';
+
+// Registries
+export { createSurfaces, createLayouts, createShells, SURFACE_NAMES } from './core/surfaces.js';
+export { createNavigation, Navigation } from './core/navigation.js';
+export { createResources, Resources } from './core/resources.js';
+export {
+  createSyntax, Syntax, nameOf, plainTokens, tokensFromSpans, spanHighlighter,
+} from './core/syntax.js';
+export { createManifests, Manifests } from './core/manifest.js';
+
+// Themes
+export * from './themes/index.js';
+
+// The host primitives.
+//
+// Not the catalog - that is `@textui/widgets`. These four are what the layout
+// engine and the painter actually reason about, so they belong to the runtime
+// that reasons about them. `Box`, `Text` and `Canvas` are the Capitalized
+// spellings, and they are the strings themselves.
+export { PRIMITIVES, Box, Text, Canvas, Spacer } from './ui/primitives.js';
+
+// Adapters
+export * from './adapters/index.js';
+
+// Utilities
+export * from './util/text.js';
+export * from './util/markdown.js';
+export * from './util/paths.js';
+export * from './util/stream.js';
+export { createBag, toDisposable, disposeAll, NOOP_DISPOSABLE } from './util/disposable.js';

package/src/jsx/factory.ts

@@ -0,0 +1,124 @@
+import type { ComponentNode, PropValue } from '../types/graph.js';
+import type { FunctionComponent, RenderOutput } from '../types/render.js';
+
+/**
+ * JSX compiles to component nodes.
+ *
+ * `<Row gap={1}/>` and `{ component: 'Row', gap: 1 }` are the same value, so a
+ * screen written in TypeScript, loaded from JSON or generated by something
+ * else all reach the runtime as one shape. That is the whole trick, and it is
+ * why every prop should stay serializable: a closure in a node is legal but
+ * marks the node as in-process only.
+ *
+ * The naming rule mirrors HTML's: **lowercase is a host primitive**
+ * (`box`, `text`, `canvas`, `spacer`), **Capitalized is a registered
+ * component** resolved through the registry at mount time.
+ */
+
+const NAME = Symbol.for('textui.componentName');
+
+interface NamedFunction {
+  (props: never): RenderOutput;
+  [NAME]?: string;
+  displayName?: string;
+  name: string;
+}
+
+let anonymousCounter = 0;
+
+/** The registry name for a function component, assigning one if needed. */
+export function componentNameOf(fn: FunctionComponent): string {
+  const f = fn as unknown as NamedFunction;
+  const existing = f[NAME];
+  if (existing) return existing;
+
+  const inferred = f.displayName || f.name;
+  const name = inferred && inferred !== 'anonymous'
+    ? inferred
+    : `Anonymous${++anonymousCounter}`;
+  f[NAME] = name;
+  return name;
+}
+
+/** Name a component explicitly. Do this for anything the registry exposes. */
+export function defineComponent<P>(name: string, fn: (props: P) => RenderOutput): (props: P) => RenderOutput {
+  (fn as unknown as NamedFunction)[NAME] = name;
+  (fn as unknown as NamedFunction).displayName = name;
+  return fn;
+}
+
+export function isNamed(fn: unknown): boolean {
+  return typeof fn === 'function' && (fn as NamedFunction)[NAME] !== undefined;
+}
+
+export const Fragment = defineComponent<{ children?: unknown }>('Fragment', (props) => {
+  return (props.children ?? null) as RenderOutput;
+});
+
+export type ElementType = string | FunctionComponent;
+
+/**
+ * Build a node. `key` is lifted out of props because it is reconciliation
+ * identity, not data the component receives.
+ */
+export function h(
+  type: ElementType,
+  props?: (Record<string, unknown> & { key?: string | number }) | null,
+  ...children: unknown[]
+): ComponentNode {
+  const { key, ...rest } = props ?? {};
+
+  const node: ComponentNode =
+    typeof type === 'string'
+      ? { component: type, ...rest }
+      : { component: componentNameOf(type), ...rest, $meta: { fn: type } };
+
+  if (children.length > 0) {
+    node.children = (children.length === 1 ? children[0] : children) as PropValue;
+  }
+  if (key !== undefined) node.key = key;
+
+  return node;
+}
+
+/** The function behind a node built from a function component, if any. */
+export function nodeFunction(node: ComponentNode): FunctionComponent | undefined {
+  const fn = node.$meta?.fn;
+  return typeof fn === 'function' ? (fn as FunctionComponent) : undefined;
+}
+
+/**
+ * Strip everything unserializable so a node can be persisted or sent. Closures
+ * (`$meta.fn`, `{ handler }` actions, function props) are dropped, which is
+ * exactly the set of things that only mean something in this process.
+ */
+export function toSerializable(node: ComponentNode): ComponentNode {
+  const out: ComponentNode = { component: node.component };
+  if (node.id !== undefined) out.id = node.id;
+  if (node.key !== undefined) out.key = node.key;
+
+  for (const [k, v] of Object.entries(node)) {
+    if (k === 'component' || k === 'id' || k === 'key' || k === '$meta') continue;
+    const clean = cleanValue(v);
+    if (clean !== undefined) out[k] = clean;
+  }
+  return out;
+}
+
+function cleanValue(v: unknown): unknown {
+  if (typeof v === 'function') return undefined;
+  if (v === null || typeof v !== 'object') return v;
+  if (Array.isArray(v)) {
+    const arr = v.map(cleanValue).filter((x) => x !== undefined);
+    return arr;
+  }
+  if ('component' in (v as object)) return toSerializable(v as ComponentNode);
+  if ('handler' in (v as object)) return undefined;
+
+  const out: Record<string, unknown> = {};
+  for (const [k, val] of Object.entries(v as Record<string, unknown>)) {
+    const clean = cleanValue(val);
+    if (clean !== undefined) out[k] = clean;
+  }
+  return out;
+}

package/src/jsx/intrinsics.ts

@@ -0,0 +1,99 @@
+import type { Style, StyleInput } from '../types/style.js';
+import type { SemanticRole } from '../types/component-registry.js';
+import type { KeyEvent, MouseEvent } from '../types/input.js';
+import type { PaintSurface, RenderContext } from '../types/render.js';
+import type { Action } from '../types/graph.js';
+
+/**
+ * Props every node accepts.
+ *
+ * Style arrives three ways on purpose: the full `style` object for anything
+ * stateful, a merged list for composition, and the individual style keys
+ * inline as convenience props - `<box gap={1} border="single">` rather than
+ * `<box style={{ gap: 1, border: 'single' }}>` for the common case.
+ */
+export interface BaseProps extends Style {
+  id?: string;
+  key?: string | number;
+  style?: StyleInput;
+
+  /** Semantic metadata. Drives the test harness, and future a11y work. */
+  role?: SemanticRole;
+  label?: string;
+  description?: string;
+  disabled?: boolean;
+  selected?: boolean;
+
+  /** Participates in tab order. Implied by an interactive role. */
+  focusable?: boolean;
+  /** The focus scope this node belongs to. */
+  focusScope?: string;
+  autoFocus?: boolean;
+  /**
+   * `onKey` runs whether or not this node is focused.
+   *
+   * For a node that wraps something else and wants the keys that thing
+   * declines - a dropdown panel taking left and right while the menu inside it
+   * keeps up and down. Without this a handler only runs while focused, which
+   * is what focus means.
+   */
+  global?: boolean;
+
+  onKey?(event: KeyEvent): boolean | void;
+  onFocus?(): void;
+  onBlur?(): void;
+  onMouse?(event: MouseEvent): boolean | void;
+  onClick?: Action | ((event: MouseEvent) => void);
+  onHover?(hovering: boolean): void;
+
+  /** OSC 8 link target, where the terminal supports hyperlinks. */
+  link?: string;
+
+  /** Below this width the node renders `compact`; below that, `minimal`. */
+  breakpoints?: { compact?: number; minimal?: number };
+}
+
+export interface BoxProps extends BaseProps {
+  children?: unknown;
+  /** Header text drawn into the top border. Needs a border to land on. */
+  title?: string;
+  titleAlign?: 'left' | 'center' | 'right';
+  /**
+   * A second label on the top border, hard against the right.
+   *
+   * For the short thing that belongs beside a heading rather than under it - a
+   * count, a shortcut, a state. It takes its space first and `title` gets what
+   * is left, so the two never collide and the title is the one that truncates.
+   */
+  rightTitle?: string;
+  /** Footer text drawn into the bottom border. */
+  footer?: string;
+  footerAlign?: 'left' | 'center' | 'right';
+  /** Scroll offset in cells, when overflow is 'scroll'. */
+  scrollTop?: number;
+  scrollLeft?: number;
+}
+
+export interface TextProps extends BaseProps {
+  children?: unknown;
+  /** The string to draw. `children` is accepted as a shorthand. */
+  content?: string;
+  /** Where to cut when the text does not fit. */
+  truncate?: 'end' | 'start' | 'middle' | false;
+  ellipsis?: string;
+}
+
+export interface CanvasProps extends BaseProps {
+  /**
+   * Paint directly. The escape hatch charts and gauges use; everything else
+   * should compose `box` and `text` so the layout engine can reason about it.
+   */
+  draw(surface: PaintSurface, ctx: RenderContext): void;
+  /** Intrinsic size when the style does not fix one. */
+  intrinsic?: { width?: number; height?: number };
+}
+
+export interface SpacerProps extends BaseProps {
+  /** Cells to take. Unset means "take whatever is left", the same as `flex: 1`. */
+  size?: number;
+}

package/src/jsx/jsx-dev-runtime.ts

@@ -0,0 +1,23 @@
+import type { ComponentNode } from '../types/graph.js';
+import type { FunctionComponent } from '../types/render.js';
+import { jsx, Fragment, type JSX } from './jsx-runtime.js';
+
+export { Fragment };
+export type { JSX };
+
+export function jsxDEV(
+  type: string | FunctionComponent,
+  props: Record<string, unknown> & { children?: unknown },
+  key: string | number | undefined,
+  _isStatic: boolean,
+  source?: { fileName: string; lineNumber: number; columnNumber: number },
+): ComponentNode {
+  const node = jsx(type, props, key);
+  if (source) {
+    node.$meta = {
+      ...node.$meta,
+      source: { file: source.fileName, line: source.lineNumber, column: source.columnNumber },
+    };
+  }
+  return node;
+}

package/src/jsx/jsx-runtime.ts

@@ -0,0 +1,76 @@
+import type { ComponentNode } from '../types/graph.js';
+import type { FunctionComponent } from '../types/render.js';
+import type { RenderOutput } from '../types/render.js';
+import { componentNameOf, Fragment } from './factory.js';
+import type { BoxProps, CanvasProps, SpacerProps, TextProps } from './intrinsics.js';
+
+export { Fragment };
+export type { BoxProps, TextProps, CanvasProps, SpacerProps };
+
+type Props = Record<string, unknown> & { children?: unknown };
+
+function build(
+  type: string | FunctionComponent,
+  props: Props,
+  key?: string | number,
+): ComponentNode {
+  const node: ComponentNode =
+    typeof type === 'string'
+      ? { component: type, ...props }
+      : { component: componentNameOf(type), ...props, $meta: { fn: type } };
+  if (key !== undefined) node.key = key;
+  return node;
+}
+
+export function jsx(
+  type: string | FunctionComponent,
+  props: Props,
+  key?: string | number,
+): ComponentNode {
+  return build(type, props, key);
+}
+
+export function jsxs(
+  type: string | FunctionComponent,
+  props: Props,
+  key?: string | number,
+): ComponentNode {
+  return build(type, props, key);
+}
+
+// TypeScript looks for a `JSX` namespace on the jsx-runtime module by name.
+// This is the one place a namespace is not a style choice.
+// eslint-disable-next-line @typescript-eslint/no-namespace
+export declare namespace JSX {
+  type Element = ComponentNode;
+
+  /**
+   * What may appear as a JSX tag.
+   *
+   * A component returns `RenderOutput` - a node, a list, a string, or nothing -
+   * rather than exactly one element. Without this, TypeScript insists every
+   * component return a single node, and `return null` stops compiling.
+   */
+  type ElementType = string | ((props: never) => RenderOutput);
+
+  interface ElementChildrenAttribute {
+    children: unknown;
+  }
+
+  /**
+   * Lowercase names are host primitives - the only three shapes the layout
+   * engine reasons about, plus a spacer. Everything Capitalized is a component
+   * you import, which is what gives it prop types.
+   */
+  interface IntrinsicElements {
+    box: BoxProps;
+    text: TextProps;
+    canvas: CanvasProps;
+    spacer: SpacerProps;
+  }
+
+  interface IntrinsicAttributes {
+    key?: string | number;
+    id?: string;
+  }
+}