@textui/core 0.1.0

package/src/types/geometry.ts

@@ -0,0 +1,50 @@
+/** Terminal geometry is integral cells. Never fractional. */
+export interface Point {
+  x: number;
+  y: number;
+}
+
+export interface Size {
+  width: number;
+  height: number;
+}
+
+export interface Rect {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+/** padding / margin / border widths, in cells. */
+export interface Edges {
+  top: number;
+  right: number;
+  bottom: number;
+  left: number;
+}
+
+export type EdgeSpec =
+  | number
+  | [vertical: number, horizontal: number]
+  | [top: number, horizontal: number, bottom: number]
+  | [top: number, right: number, bottom: number, left: number]
+  | Partial<Edges>;
+
+export const ZERO_EDGES: Edges = { top: 0, right: 0, bottom: 0, left: 0 };
+
+export function rectContains(r: Rect, x: number, y: number): boolean {
+  return x >= r.x && x < r.x + r.width && y >= r.y && y < r.y + r.height;
+}
+
+export function rectIntersect(a: Rect, b: Rect): Rect {
+  const x = Math.max(a.x, b.x);
+  const y = Math.max(a.y, b.y);
+  const right = Math.min(a.x + a.width, b.x + b.width);
+  const bottom = Math.min(a.y + a.height, b.y + b.height);
+  return { x, y, width: Math.max(0, right - x), height: Math.max(0, bottom - y) };
+}
+
+export function rectEquals(a: Rect, b: Rect): boolean {
+  return a.x === b.x && a.y === b.y && a.width === b.width && a.height === b.height;
+}

package/src/types/graph.ts

@@ -0,0 +1,174 @@
+/**
+ * The component graph.
+ *
+ * A screen IS its root ComponentNode. JSX compiles to exactly this shape -
+ * `<Row gap={1}/>` and `{ component: 'Row', gap: 1 }` are the same value - so
+ * a screen can be written in TypeScript, loaded from JSON, generated, edited
+ * or sent over a wire without changing the runtime that mounts it.
+ *
+ * Three keys are reserved on every node: `id`, `component`, `$meta`.
+ * Everything else is props, and props are the component's business.
+ */
+export type NodeId = string;
+
+/**
+ * JSON-Pointer-shaped store path.
+ *
+ * `$/seg/seg` - absolute; the first segment is a scope.
+ * `/seg/seg`  - relative to the surrounding data context.
+ * `..`        - forbidden. Escape to the root with `$/` instead, so a node's
+ *               meaning never depends on where it was pasted.
+ * `*`         - wildcard segment, subscriptions only (writes throw).
+ * `#/seg`     - the value AT this path is itself a path; one extra hop.
+ * `{{ /seg }}` inside a path substitutes another path's value first.
+ */
+export type BindingPath = `$/${string}` | `/${string}`;
+
+/**
+ * Transient event path. Same shape, different lifetime: events are delivered
+ * and forgotten, never stored. `@/dialog/confirm`, `@/agent/restart`.
+ */
+export type EventPath = `@/${string}`;
+
+export type DataBinding = { path: BindingPath };
+
+export type FunctionCall = {
+  call: string;
+  args?: Record<string, PropValue>;
+  /** Refuse to route this to a remote dispatcher. */
+  callableFrom?: 'clientOnly';
+};
+
+export type DynamicValue =
+  | string | number | boolean | string[]
+  | DataBinding | FunctionCall;
+
+export type DynamicString = string | DataBinding | FunctionCall;
+export type DynamicNumber = number | DataBinding | FunctionCall;
+export type DynamicBoolean = boolean | DataBinding | FunctionCall;
+export type DynamicStringList = string[] | DataBinding | FunctionCall;
+
+/** Inline children, or one instance of `template` per item at `path`. */
+export type ChildList =
+  | ComponentNode[]
+  | { template: ComponentNode; path: BindingPath };
+
+/**
+ * Discriminated by key presence:
+ *   'emit' in action         -> publish on an event path
+ *   'functionCall' in action -> run a registered command
+ *   'handler' in action      -> a closure. Never serializable; only legal for
+ *                               nodes built in-process (JSX), and stripped
+ *                               when a graph is exported.
+ */
+export type Action =
+  | { emit: { path: EventPath; payload?: PropValue; } }
+  | { functionCall: FunctionCall }
+  | { handler: (...args: any[]) => void };
+
+export type PropValue =
+  | string | number | boolean | null | undefined
+  | DataBinding
+  | FunctionCall
+  | Action
+  | ComponentNode
+  | ComponentNode[]
+  | { template: ComponentNode; path: BindingPath }
+  | { [k: string]: PropValue }
+  | PropValue[]
+  | ((...args: any[]) => unknown);
+
+/** What a component threw, and which component threw it. */
+export interface RenderError {
+  /** The thrown value, whatever it was. */
+  error: unknown;
+  /** `error.message`, or the value stringified. */
+  message: string;
+  /** The component that threw. */
+  component: string;
+}
+
+/**
+ * What to render when a component throws.
+ *
+ * A node keeps the graph data, and is handed the failure as the `error` and
+ * `errorMessage` props - so a registered `ErrorPanel` can show what happened
+ * without the registry holding a function. A function is for the local case,
+ * where the fallback wants the failure itself rather than two props.
+ */
+export type ErrorFallback =
+  | ComponentNode
+  | ((failure: RenderError) => ComponentNode);
+
+/** Internal only - stripped before a node is serialized back to a sender. */
+export type NodeMeta = {
+  origin?: { format: string; version?: string; sourceNodeId?: NodeId };
+  /** Rendered instead when this node's subtree throws. */
+  fallback?: ErrorFallback;
+  /** Set by the JSX factory for a function component, so the registry can
+   *  resolve the same function without a name collision. */
+  fn?: unknown;
+  /** Source location, when the JSX transform provides one. */
+  source?: { file: string; line: number; column: number };
+};
+
+export type ComponentNode = {
+  id?: NodeId;
+  component: string;
+  $meta?: NodeMeta;
+  /** Reconciliation identity among siblings. */
+  key?: string | number;
+  children?: PropValue | unknown;
+  [prop: string]: unknown;
+};
+
+/** A screen IS its root node. No separate {root, nodes} map. */
+export type ScreenState = ComponentNode;
+
+export function isComponentNode(v: unknown): v is ComponentNode {
+  return (
+    typeof v === 'object' && v !== null &&
+    'component' in v && typeof (v as ComponentNode).component === 'string'
+  );
+}
+
+export function isDataBinding(v: unknown): v is DataBinding {
+  // Exactly one key, because that is what the type says: `{ path }`. Testing
+  // only that `path` is present made a binding out of anything that happens to
+  // carry one - `{ kind: 'unix', path: '/tmp/room' }` is a socket address, and
+  // it was resolved against the store and thrown as a PathError instead. The
+  // shape is far too common to claim loosely: a route, a file entry, a config
+  // section. The old guard listed `component` and `template` as exceptions,
+  // which was this same problem met twice and patched twice.
+  return (
+    typeof v === 'object' && v !== null &&
+    typeof (v as DataBinding).path === 'string' &&
+    Object.keys(v).length === 1
+  );
+}
+
+export function isFunctionCall(v: unknown): v is FunctionCall {
+  return (
+    typeof v === 'object' && v !== null &&
+    'call' in v && typeof (v as FunctionCall).call === 'string' &&
+    !('component' in v)
+  );
+}
+
+export function isAction(v: unknown): v is Action {
+  return (
+    typeof v === 'object' && v !== null &&
+    ('emit' in v || 'functionCall' in v || 'handler' in v) &&
+    !('component' in v)
+  );
+}
+
+export function isTemplatedChildren(
+  v: unknown,
+): v is { template: ComponentNode; path: BindingPath } {
+  return (
+    typeof v === 'object' && v !== null &&
+    'template' in v && 'path' in v &&
+    isComponentNode((v as { template: unknown }).template)
+  );
+}

package/src/types/i18n.ts

@@ -0,0 +1,25 @@
+import type { Disposable } from './disposable.js';
+
+export type LocaleId = string;
+
+export interface TranslationBundle {
+  locale: LocaleId;
+  /** Flat or nested; nested keys are addressed with dots. */
+  messages: Record<string, unknown>;
+}
+
+export interface I18n {
+  locale: LocaleId;
+  setLocale(locale: LocaleId): void;
+  register(bundle: TranslationBundle): Disposable;
+  locales(): LocaleId[];
+  /** Missing keys fall back to the fallback locale, then to the key itself. */
+  t(key: string, values?: Record<string, unknown>): string;
+  /** Intl-backed; TextUI does not reimplement formatting. */
+  number(value: number, options?: Intl.NumberFormatOptions): string;
+  date(value: Date | number, options?: Intl.DateTimeFormatOptions): string;
+  relative(value: number, unit: Intl.RelativeTimeFormatUnit): string;
+  list(items: string[], options?: Intl.ListFormatOptions): string;
+  plural(count: number, forms: Record<string, string>): string;
+  onChange(fn: (locale: LocaleId) => void): Disposable;
+}

package/src/types/index.ts

@@ -0,0 +1,31 @@
+export * from './disposable.js';
+export * from './geometry.js';
+export * from './capabilities.js';
+export * from './cells.js';
+export * from './style.js';
+export * from './theme.js';
+export * from './graph.js';
+export * from './store.js';
+export * from './input.js';
+export * from './focus.js';
+export * from './when.js';
+export * from './command.js';
+export * from './keybinding.js';
+export * from './render.js';
+export * from './component-registry.js';
+export * from './resource.js';
+export * from './surface.js';
+export * from './shell.js';
+export * from './navigation.js';
+export * from './layer.js';
+export * from './async.js';
+export * from './stream.js';
+export * from './animation.js';
+export * from './i18n.js';
+export * from './terminal.js';
+export * from './services.js';
+export * from './manifest.js';
+export * from './app.js';
+export * from './syntax.js';
+export * from './adapter.js';
+export * from './markdown.js';

package/src/types/input.ts

@@ -0,0 +1,81 @@
+import type { Disposable } from './disposable.js';
+
+export interface KeyModifiers {
+  ctrl: boolean;
+  alt: boolean;
+  shift: boolean;
+  meta: boolean;
+}
+
+/**
+ * Canonical key name. Printable keys carry the character itself; everything
+ * else uses these names, so a keybinding string is stable across terminals.
+ */
+export type KeyName =
+  | 'up' | 'down' | 'left' | 'right'
+  | 'enter' | 'escape' | 'tab' | 'backspace' | 'delete' | 'space'
+  | 'home' | 'end' | 'pageup' | 'pagedown' | 'insert'
+  | 'f1' | 'f2' | 'f3' | 'f4' | 'f5' | 'f6'
+  | 'f7' | 'f8' | 'f9' | 'f10' | 'f11' | 'f12'
+  | (string & {});
+
+export interface KeyEvent {
+  type: 'key';
+  /** Canonical name, or the printable character. */
+  name: KeyName;
+  /** The character produced, when printable. */
+  char?: string;
+  ctrl: boolean;
+  alt: boolean;
+  shift: boolean;
+  meta: boolean;
+  /** Raw bytes, for adapters and diagnostics. */
+  raw: string;
+  /** Set by a handler to stop propagation up the focus chain. */
+  handled: boolean;
+  /** Kitty protocol only - press/repeat/release. */
+  kind?: 'press' | 'repeat' | 'release';
+}
+
+export type MouseButton = 'left' | 'middle' | 'right' | 'none';
+export type MouseAction = 'down' | 'up' | 'move' | 'drag' | 'wheel';
+
+export interface MouseEvent {
+  type: 'mouse';
+  action: MouseAction;
+  button: MouseButton;
+  /** Terminal cell coordinates, 0-based. */
+  x: number;
+  y: number;
+  /** Negative up, positive down. */
+  wheel?: number;
+  ctrl: boolean;
+  alt: boolean;
+  shift: boolean;
+  handled: boolean;
+}
+
+export interface PasteEvent {
+  type: 'paste';
+  text: string;
+  handled: boolean;
+}
+
+/** Terminal-level focus (the window), not component focus. */
+export interface TerminalFocusEvent {
+  type: 'terminal-focus';
+  focused: boolean;
+}
+
+export interface ResizeEvent {
+  type: 'resize';
+  width: number;
+  height: number;
+}
+
+export type InputEvent =
+  | KeyEvent | MouseEvent | PasteEvent | TerminalFocusEvent | ResizeEvent;
+
+export interface InputSource extends Disposable {
+  on(fn: (event: InputEvent) => void): Disposable;
+}

package/src/types/keybinding.ts

@@ -0,0 +1,51 @@
+import type { Disposable } from './disposable.js';
+import type { WhenClause } from './when.js';
+import type { KeyEvent } from './input.js';
+
+/**
+ * A chord string: `ctrl+p`, `ctrl+k ctrl+s` (a sequence), `shift+tab`, `g g`.
+ * Names match `KeyName`; modifiers are ctrl/alt/shift/meta in that order.
+ */
+export type Chord = string;
+
+export interface KeybindingDefinition {
+  keys: Chord;
+  commandId: string;
+  args?: Record<string, unknown>;
+  /**
+   * What *this key* does, when the command's own title does not say it.
+   *
+   * A binding that carries arguments runs one invocation of a command, not the
+   * command: `ctrl+b` is "Toggle Sidebar" and the command is "Toggle Surface".
+   * Without this the shortcut sheet files the key under the general title and
+   * says something that is not true of the key.
+   */
+  title?: string;
+  when?: WhenClause;
+  /** Only fires while this focus scope (or one inside it) is active. */
+  scopeId?: string;
+  /** Higher wins on conflict. Defaults to registration order. */
+  priority?: number;
+}
+
+export interface KeybindingRegistry {
+  register(def: KeybindingDefinition): Disposable;
+  unregister(keys: Chord, commandId?: string): void;
+  list(): KeybindingDefinition[];
+  /**
+   * Chords bound to a command, for rendering hints next to menu rows.
+   *
+   * Argument-bearing bindings are left out: they run one invocation and not
+   * the command, so offering one as *the* key for the command's menu row
+   * names a key that does something else. Match on `args` through `list()`
+   * when the specific invocation is what is wanted.
+   */
+  forCommand(commandId: string): Chord[];
+  /**
+   * Feed a key in. Returns 'handled', 'pending' (a prefix of a longer chord),
+   * or 'unhandled'.
+   */
+  handle(event: KeyEvent): 'handled' | 'pending' | 'unhandled';
+  /** Abandon a partially typed chord. */
+  reset(): void;
+}

package/src/types/layer.ts

@@ -0,0 +1,46 @@
+import type { Disposable } from './disposable.js';
+import type { ComponentNode } from './graph.js';
+import type { Rect } from './geometry.js';
+
+/** Painting and input order. A layer is a plane, not a component. */
+export type LayerName = 'base' | 'floating' | 'modal' | 'notification' | 'debug';
+
+export type AnchorSide = 'top' | 'right' | 'bottom' | 'left';
+export type AnchorAlign = 'start' | 'center' | 'end';
+
+/** Position a layer entry relative to a focusable, a rect, or the screen. */
+export type LayerPosition =
+  | { kind: 'center' }
+  | { kind: 'screen'; rect: Partial<Rect> }
+  | { kind: 'anchor'; targetId: string; side: AnchorSide; align?: AnchorAlign; offset?: number }
+  | { kind: 'point'; x: number; y: number }
+  | { kind: 'cursor' };
+
+export interface LayerEntry {
+  id: string;
+  layer: LayerName;
+  node: ComponentNode;
+  position?: LayerPosition;
+  /** Dim everything beneath. Modals want this. */
+  scrim?: boolean;
+  /** Trap focus inside and restore it on close. */
+  trapFocus?: boolean;
+  /** Escape closes it. */
+  dismissOnEscape?: boolean;
+  /** A click outside closes it. */
+  dismissOnOutsideClick?: boolean;
+  /** Auto-remove after this many ms. Toasts want this. */
+  timeoutMs?: number;
+  onClose?(reason: 'escape' | 'outside' | 'timeout' | 'api'): void;
+  order?: number;
+}
+
+export interface LayerManager {
+  open(entry: LayerEntry): Disposable;
+  close(id: string, reason?: 'escape' | 'outside' | 'timeout' | 'api'): void;
+  closeLayer(layer: LayerName): void;
+  entries(layer?: LayerName): LayerEntry[];
+  /** The innermost entry that traps focus, if any. */
+  topmostTrap(): LayerEntry | null;
+  update(id: string, patch: Partial<LayerEntry>): void;
+}

package/src/types/manifest.ts

@@ -0,0 +1,101 @@
+import type { Disposable } from './disposable.js';
+import type { ComponentDefinition } from './component-registry.js';
+import type { CommandDefinition } from './command.js';
+import type { KeybindingDefinition } from './keybinding.js';
+import type { ThemeDefinition } from './theme.js';
+import type { ShellDefinition } from './shell.js';
+import type { LayoutDefinition, Mount } from './surface.js';
+import type { ScreenDefinition } from './navigation.js';
+import type {
+  ResourceActionDefinition, ResourceEditorDefinition, ResourceKind,
+  ResourceProvider, ResourceViewerDefinition,
+} from './resource.js';
+import type { ComputedDefinition, DataProviderDefinition } from './store.js';
+import type { BindingPath } from './graph.js';
+import type { CapabilityName } from './capabilities.js';
+
+/**
+ * One source contributing to the typed registries. Deliberately not a generic
+ * plugin bag: every category is its own list with its own type, so a bad
+ * contribution fails where it is written.
+ */
+export interface ManifestSource {
+  id: string;
+  version?: string;
+  displayName?: string;
+  /** One line, for a list of sources that has room to say what each one is. */
+  description?: string;
+}
+
+export interface Contributes {
+  components?: ComponentDefinition[];
+  commands?: CommandDefinition[];
+  keybindings?: KeybindingDefinition[];
+  themes?: ThemeDefinition[];
+  shells?: ShellDefinition[];
+  layouts?: LayoutDefinition[];
+  screens?: ScreenDefinition[];
+  views?: Mount[];
+  resourceKinds?: ResourceKind[];
+  resourceProviders?: ResourceProvider[];
+  resourceViewers?: ResourceViewerDefinition[];
+  resourceEditors?: ResourceEditorDefinition[];
+  resourceActions?: ResourceActionDefinition[];
+  dataProviders?: DataProviderDefinition[];
+  computed?: { path: BindingPath; def: ComputedDefinition }[];
+}
+
+export interface Manifest {
+  source: ManifestSource;
+  /** Other manifest ids that must load first. */
+  requires?: string[];
+  engine?: { textui: string };
+  /** Refuse to load without these terminal capabilities. */
+  requiresCapabilities?: CapabilityName[];
+  contributes?: Contributes;
+}
+
+export interface ManifestAPI {
+  load(manifest: Manifest): Promise<Disposable>;
+  unload(sourceId: string): void;
+  sources(): ManifestSource[];
+  loaded(sourceId: string): boolean;
+}
+
+/**
+ * Registry manifest metadata - what the CLI reads to copy a component's source
+ * into a user's project and to tell later what changed upstream.
+ */
+export interface RegistryComponentManifest {
+  name: string;
+  description?: string;
+  category?: string;
+  version: string;
+  /** Files copied into the project, relative to the registry root. */
+  files: { path: string; target?: string; type?: 'component' | 'style' | 'test' | 'example' }[];
+  /** Other registry components this one needs. */
+  dependencies?: string[];
+  /** npm packages this one needs. */
+  npmDependencies?: Record<string, string>;
+  requiredCapabilities?: CapabilityName[];
+  optionalCapabilities?: CapabilityName[];
+  variants?: string[];
+  /** Store paths this component binds to by convention. */
+  storeBindings?: string[];
+  related?: string[];
+  examples?: { name: string; file: string }[];
+  /** Templates that include this component. */
+  templates?: string[];
+  /** Content hash of the copied files, so the CLI can detect local edits. */
+  hash?: string;
+}
+
+export interface RegistryManifest {
+  name: string;
+  version: string;
+  description?: string;
+  homepage?: string;
+  components: RegistryComponentManifest[];
+  themes?: { name: string; file: string; appearance: 'light' | 'dark' }[];
+  templates?: { name: string; description?: string; files: string[]; components: string[] }[];
+}

package/src/types/markdown.ts

@@ -0,0 +1,47 @@
+import type { StyleColor } from './style.js';
+
+/**
+ * Markdown, as rows a terminal can scroll.
+ *
+ * Two shapes and one invariant: **every row is exactly one row tall.** That is
+ * what makes "how far can this scroll" a length rather than an estimate - one
+ * source line becomes three rows when it wraps and none when it is a fence
+ * marker, so counting source lines is counting the wrong unit and the tail of
+ * a long document becomes unreachable.
+ *
+ * A fence is the exception that proves it: it is several rows, so it becomes
+ * several rows here, each tagged with the fence it belongs to so a painter can
+ * put the visible ones back into one box.
+ */
+
+/** A run of text with one style. Inline emphasis is why rows are not strings. */
+export interface MarkdownRun {
+  text: string;
+  bold?: boolean;
+  italic?: boolean;
+  code?: boolean;
+  /** An OSC 8 target, where the terminal has hyperlinks. */
+  link?: string;
+}
+
+export type MarkdownRow =
+  | { kind: 'rule' }
+  | { kind: 'heading'; runs: MarkdownRun[]; level: number }
+  | { kind: 'text'; runs: MarkdownRun[]; prefix?: string; prefixFg?: StyleColor; fg?: StyleColor }
+  | { kind: 'fence'; fence: number; part: 'open' | 'code' | 'close'; text?: string; language?: string };
+
+export interface MarkdownLayoutOptions {
+  /** Cells to wrap to. Zero means "not measured yet" - nothing is wrapped. */
+  width: number;
+  /** The bullet glyph. Passed in, because glyphs come from the theme. */
+  bullet?: string;
+  /** The rule down the left of a block quote. Also a theme glyph. */
+  quoteBar?: string;
+  /**
+   * Whether a fence gets an opening and closing rule row.
+   *
+   * A borderless theme draws neither, and a layout that reserved two rows for
+   * rules nobody draws stops two rows short of the end of the document.
+   */
+  ruled?: boolean;
+}

package/src/types/navigation.ts

@@ -0,0 +1,42 @@
+import type { Disposable } from './disposable.js';
+import type { ComponentNode } from './graph.js';
+import type { MountDisplay, SurfaceName } from './surface.js';
+
+/**
+ * Screens and a stack, not a router. An application that wants URLs maps them
+ * onto screens itself.
+ */
+export interface ScreenDefinition {
+  id: string;
+  /** Component name, or the node itself. */
+  component: string | ComponentNode;
+  display?: MountDisplay;
+  /**
+   * Where it mounts. `main` unless a screen wants to live somewhere else - a
+   * surface is the application's word, so this is open like the rest of them.
+   */
+  surface?: SurfaceName;
+  /** Screens keep their store scope when navigated away from. */
+  keepAlive?: boolean;
+}
+
+export interface ScreenEntry {
+  id: string;
+  params?: Record<string, unknown>;
+  /** Focus id to restore when this entry becomes current again. */
+  restoreFocus?: string | null;
+}
+
+export interface Navigator {
+  register(screen: ScreenDefinition): Disposable;
+  screens(): ScreenDefinition[];
+  get(id: string): ScreenDefinition | undefined;
+  push(id: string, params?: Record<string, unknown>): void;
+  replace(id: string, params?: Record<string, unknown>): void;
+  pop(): boolean;
+  popTo(id: string): boolean;
+  reset(id: string, params?: Record<string, unknown>): void;
+  current(): ScreenEntry | null;
+  stack(): ScreenEntry[];
+  canGoBack(): boolean;
+}