@textui/core 0.1.0

package/src/ui/primitives.ts

@@ -0,0 +1,118 @@
+import type { ComponentDefinition } from '../types/component-registry.js';
+import type { HostComponent } from '../types/render.js';
+
+/**
+ * The host primitives.
+ *
+ * There are four, and there is a reason not to add a fifth: the layout engine
+ * and the painter only reason about these shapes, so every component in the
+ * catalog composing them means layout has one implementation rather than
+ * dozens. Painting for `box`, `text` and `canvas` lives in the painter, which
+ * is why these carry no `paint` of their own.
+ */
+
+/*
+ * The primitives under Capitalized names, for JSX.
+ *
+ * These are the strings, not wrappers around them. JSX resolves a Capitalized
+ * tag to the value in scope, and a value whose type is a string literal is an
+ * intrinsic - so `<Box margin={2}/>` compiles to `h('box', { margin: 2 })`,
+ * the identical node. No function to call, no extra depth in the tree, and
+ * `BoxProps` still checks the props: `<Box notAProp/>` is the same error
+ * `<box notAProp/>` is.
+ *
+ * They exist so a screen can be written in one case. Every other component is
+ * Capitalized already - it has to be, that is how JSX tells a registry lookup
+ * from a host tag - and the four primitives being the exception meant mixing
+ * `<Row>` and `<box>` in one file. The lowercase names remain what the node
+ * actually holds, and stay the spelling for a screen written as data.
+ *
+ * Each carries its own doc below rather than sharing this one, because a
+ * comment above a group attaches to the first declaration and leaves the rest
+ * hovering as nothing - and going to the definition of a name that turns out
+ * to be an undocumented string is worse than not going anywhere.
+ */
+
+/**
+ * The container. Flex layout, background, border, title and footer.
+ *
+ * Props: `BoxProps`. The same node as `<box/>` - this constant is the string,
+ * so JSX resolves the tag as an intrinsic rather than as a component.
+ *
+ * ```tsx
+ * <Box border="round" padding={1} direction="column" gap={1}>
+ *   <Text bold>Title</Text>
+ * </Box>
+ * ```
+ */
+export const Box = 'box' as const;
+
+/**
+ * A run of text. Wraps, truncates and aligns within its box.
+ *
+ * Props: `TextProps` - `content`, or children as a shorthand, plus `truncate`
+ * and every style key. The same node as `<text/>`.
+ *
+ * ```tsx
+ * <Text bold fg="success">{count} tests passed</Text>
+ * ```
+ */
+export const Text = 'text' as const;
+
+/**
+ * Direct cell painting. The escape hatch charts and gauges use.
+ *
+ * Props: `CanvasProps` - a `draw` callback handed a surface and a render
+ * context, and an `intrinsic` size for when the style does not fix one. Prefer
+ * composing `Box` and `Text` where you can: the layout engine can reason about
+ * those and cannot reason about this. The same node as `<canvas/>`.
+ */
+export const Canvas = 'canvas' as const;
+
+/**
+ * Empty space. Greedy by default, or a fixed number of cells.
+ *
+ * Props: `SpacerProps` - `size` in cells; leave it unset and it takes whatever
+ * is left, which is how two things end up at opposite ends of a row. The same
+ * node as `<spacer/>`.
+ *
+ * Between *every* child, `gap` on the container is shorter and does not need a
+ * node per space.
+ */
+export const Spacer = 'spacer' as const;
+
+const box: HostComponent = { name: 'box', container: true };
+const text: HostComponent = { name: 'text', leaf: true };
+const canvas: HostComponent = { name: 'canvas', leaf: true };
+const spacer: HostComponent = { name: 'spacer', leaf: true };
+
+export const PRIMITIVES: ComponentDefinition[] = [
+  {
+    component: 'box',
+    category: 'layout',
+    description: 'The container. Flex layout, background, border, title and footer.',
+    renderer: { kind: 'host', host: box },
+    role: 'presentation',
+  },
+  {
+    component: 'text',
+    category: 'display',
+    description: 'A run of text. Wraps, truncates and aligns within its box.',
+    renderer: { kind: 'host', host: text },
+    role: 'presentation',
+  },
+  {
+    component: 'canvas',
+    category: 'display',
+    description: 'Direct cell painting. The escape hatch charts and gauges use.',
+    renderer: { kind: 'host', host: canvas },
+    role: 'presentation',
+  },
+  {
+    component: 'spacer',
+    category: 'layout',
+    description: 'Empty space. Sized, or greedy when given flex.',
+    renderer: { kind: 'host', host: spacer },
+    role: 'presentation',
+  },
+];

package/src/ui/screen.ts

@@ -0,0 +1,41 @@
+import type { BoxProps } from '../jsx/intrinsics.js';
+import type { ComponentDefinition } from '../types/component-registry.js';
+import type { RenderOutput } from '../types/render.js';
+import { defineComponent, h } from '../jsx/factory.js';
+import { useFocusScope } from '../runtime/hooks.js';
+
+/**
+ * What the navigator mounts.
+ *
+ * A screen is not a special kind of node - it is a mount in a surface, so the
+ * shell arranges it, the layouts apply to it, and everything that reads the
+ * surface registry sees it. What this adds is the one thing a screen needs
+ * that a mount does not have: a focus scope of its own.
+ *
+ * That scope is what makes the stack behave. Tab order belongs to what is on
+ * screen rather than to the application, and `pop` can put focus back where it
+ * was because "where it was" is a question about this scope and not about
+ * every focusable that ever registered.
+ */
+export interface ScreenProps extends BoxProps {
+  screenId: string;
+  children?: RenderOutput;
+}
+
+export const Screen = defineComponent<ScreenProps>('Screen', (props) => {
+  const { screenId, children, ...rest } = props;
+  // A screen takes focus when it arrives. Pushing one unmounts whatever held
+  // focus, so without this the new screen is one no key reaches - and what it
+  // is showing cannot even be scrolled.
+  useFocusScope({ id: `screen:${screenId}`, restore: true, autoFocus: true });
+  return h('box', { direction: 'column', flex: 1, ...rest }, children as never);
+});
+
+export const SCREEN_COMPONENTS: ComponentDefinition[] = [
+  {
+    component: 'Screen',
+    category: 'layout',
+    renderer: { kind: 'function', render: Screen },
+    description: 'The navigator’s mount: one screen, in its own focus scope.',
+  },
+];

package/src/util/disposable.ts

@@ -0,0 +1,49 @@
+import type { Disposable, DisposableBag } from '../types/disposable.js';
+
+export const NOOP_DISPOSABLE: Disposable = { dispose() {} };
+
+export function toDisposable(fn: () => void): Disposable {
+  let done = false;
+  return {
+    dispose() {
+      if (done) return;
+      done = true;
+      fn();
+    },
+  };
+}
+
+export function disposeAll(items: Iterable<Disposable>): void {
+  const errors: unknown[] = [];
+  for (const d of items) {
+    try {
+      d.dispose();
+    } catch (err) {
+      errors.push(err);
+    }
+  }
+  if (errors.length === 1) throw errors[0];
+  if (errors.length > 1) throw new AggregateError(errors, 'dispose failed');
+}
+
+export function createBag(): DisposableBag {
+  const items = new Set<Disposable>();
+  let disposed = false;
+  return {
+    add<T extends Disposable>(d: T): T {
+      if (disposed) {
+        d.dispose();
+        return d;
+      }
+      items.add(d);
+      return d;
+    },
+    dispose() {
+      if (disposed) return;
+      disposed = true;
+      const copy = [...items];
+      items.clear();
+      disposeAll(copy);
+    },
+  };
+}

package/src/util/markdown.ts

@@ -0,0 +1,225 @@
+import type { MarkdownLayoutOptions, MarkdownRow, MarkdownRun } from '../types/markdown.js';
+import type { StyleColor } from '../types/style.js';
+import { graphemes, stringWidth, wrapText } from './text.js';
+
+/**
+ * Markdown, laid out.
+ *
+ * Not a parser - a formatter for the subset that appears in READMEs, notes and
+ * anything an agent or a service writes for a person: headings, lists, rules,
+ * fences, block quotes, and inline emphasis, code and links.
+ *
+ * Pure, and measured in cells. It takes the glyphs it needs rather than
+ * reading a theme, so it can be called from a test, from a viewer that windows
+ * the rows, and from a component that draws all of them.
+ */
+
+/**
+ * The delimiters, guarded.
+ *
+ * The guards are the whole difficulty. A single `*` beside a double one is not
+ * an opener - `2 * 3 and **half a bold` italicised " 3 and " and ate a
+ * character, because the lone asterisk paired with the first half of the
+ * unclosed pair. A delimiter with a space just inside it is arithmetic or a
+ * footnote, not emphasis. And an underscore needs a word boundary as well, or
+ * `snake_case_name` goes italic in the middle.
+ */
+const PATTERNS = [
+  String.raw`\*\*(?!\s)[^*]+(?<!\s)\*\*`,
+  String.raw`(?<![\w_])__(?!\s)[^_]+(?<!\s)__(?![\w_])`,
+  String.raw`\x60[^\x60]+\x60`,
+  String.raw`(?<!\*)\*(?!\s)[^*]+(?<!\s)\*(?!\*)`,
+  String.raw`(?<![\w_])_(?!\s)[^_]+(?<!\s)_(?![\w_])`,
+  String.raw`\[[^\]]+\]\([^)]+\)`,
+];
+
+/** One capturing group, so `split` keeps the delimited pieces. */
+const INLINE = new RegExp(`(${PATTERNS.join('|')})`);
+
+/**
+ * Emphasis, code and links, as styled runs.
+ *
+ * Unmatched markers stay literal: a lone asterisk in prose is an asterisk, and
+ * a document that reformats itself as the closing one arrives is worse than
+ * one that never tried.
+ */
+export function inlineRuns(text: string): MarkdownRun[] {
+  const runs: MarkdownRun[] = [];
+  for (const piece of text.split(INLINE)) {
+    if (piece === '') continue;
+    if (/^\*\*[^*]+\*\*$/.test(piece) || /^__[^_]+__$/.test(piece)) {
+      runs.push({ text: piece.slice(2, -2), bold: true });
+    } else if (/^`[^`]+`$/.test(piece)) {
+      runs.push({ text: piece.slice(1, -1), code: true });
+    } else if (/^\*[^*]+\*$/.test(piece) || /^_[^_]+_$/.test(piece)) {
+      runs.push({ text: piece.slice(1, -1), italic: true });
+    } else {
+      const link = /^\[([^\]]+)\]\(([^)]+)\)$/.exec(piece);
+      if (link) runs.push({ text: link[1] ?? '', link: link[2] ?? '' });
+      else runs.push({ text: piece });
+    }
+  }
+  return runs.length > 0 ? runs : [{ text: '' }];
+}
+
+/**
+ * Fold styled runs into lines that fit.
+ *
+ * `wrapText` wraps a string, and a string cannot carry which half of it was
+ * bold - so the wrap happens over runs, on cell widths rather than character
+ * counts. A word longer than the whole width is broken rather than allowed to
+ * decide the width of the pane it is in.
+ */
+export function wrapRuns(runs: MarkdownRun[], width: number): MarkdownRun[][] {
+  if (width <= 0) return [runs];
+  const lines: MarkdownRun[][] = [];
+  let line: MarkdownRun[] = [];
+  let used = 0;
+
+  const push = (run: MarkdownRun, text: string): void => {
+    const last = line[line.length - 1];
+    if (last && sameStyle(last, run)) last.text += text;
+    else line.push({ ...run, text });
+    used += stringWidth(text);
+  };
+
+  for (const run of runs) {
+    for (const word of run.text.split(/(\s+)/)) {
+      if (word === '') continue;
+      const w = stringWidth(word);
+
+      if (/^\s+$/.test(word)) {
+        // A space at the start of a line is a space nobody typed.
+        if (used > 0 && used + w <= width) push(run, word);
+        continue;
+      }
+
+      if (used + w > width && used > 0) { lines.push(line); line = []; used = 0; }
+
+      if (w > width) {
+        let rest = graphemes(word);
+        while (rest.length > 0) {
+          const room = Math.max(1, width - used);
+          push(run, rest.slice(0, room).join(''));
+          rest = rest.slice(room);
+          if (rest.length > 0) { lines.push(line); line = []; used = 0; }
+        }
+        continue;
+      }
+
+      push(run, word);
+    }
+  }
+
+  if (line.length > 0) lines.push(line);
+  return lines.length > 0 ? lines : [[{ text: '' }]];
+}
+
+function sameStyle(a: MarkdownRun, b: MarkdownRun): boolean {
+  return !!a.bold === !!b.bold && !!a.italic === !!b.italic
+    && !!a.code === !!b.code && a.link === b.link;
+}
+
+/** Wrapped rows behind a gutter: the marker on the first, its width on the rest. */
+function withPrefix(
+  runs: MarkdownRun[],
+  width: number,
+  prefix: string,
+  options: { continued?: string; prefixFg?: StyleColor } = {},
+): MarkdownRow[] {
+  const gutter = stringWidth(prefix);
+  const rest = options.continued ?? ' '.repeat(gutter);
+  return wrapRuns(runs, width <= 0 ? 0 : Math.max(1, width - gutter - 1)).map((line, index) => ({
+    kind: 'text' as const,
+    runs: line,
+    prefix: index === 0 ? prefix : rest,
+    ...(options.prefixFg ? { prefixFg: options.prefixFg } : {}),
+  }));
+}
+
+export function layoutMarkdown(
+  source: string | string[],
+  options: MarkdownLayoutOptions,
+): MarkdownRow[] {
+  const { width, bullet = '-', quoteBar = '|', ruled = true } = options;
+  const lines = Array.isArray(source) ? source : source.replace(/\r\n/g, '\n').split('\n');
+  const rows: MarkdownRow[] = [];
+  let fence = 0;
+  let inFence = false;
+  let language = '';
+
+  for (const line of lines) {
+    const marker = /^\s*```(\S*)\s*$/.exec(line);
+    if (marker) {
+      // An open fence is laid out as a fence from the moment it opens. A turn
+      // is streamed, so the closing marker may simply not have been said yet -
+      // and a block that flickers between prose and code as the words land is
+      // worse than one shown open.
+      if (!inFence) language = marker[1] ?? '';
+      if (ruled) rows.push({ kind: 'fence', fence, part: inFence ? 'close' : 'open', ...(language ? { language } : {}) });
+      if (inFence) fence++;
+      inFence = !inFence;
+      continue;
+    }
+    if (inFence) {
+      rows.push({ kind: 'fence', fence, part: 'code', text: line, ...(language ? { language } : {}) });
+      continue;
+    }
+
+    const heading = /^(#{1,6})\s+(.*)$/.exec(line);
+    if (heading) {
+      const level = (heading[1] as string).length;
+      for (const runs of wrapRuns(inlineRuns(heading[2] ?? ''), width)) {
+        rows.push({ kind: 'heading', runs, level });
+      }
+      continue;
+    }
+
+    if (/^\s*([-*_])\1{2,}\s*$/.test(line)) { rows.push({ kind: 'rule' }); continue; }
+
+    const item = /^(\s*)[-*+]\s+(.*)$/.exec(line);
+    if (item) {
+      rows.push(...withPrefix(inlineRuns(item[2] ?? ''), width, `${item[1]}${bullet}`));
+      continue;
+    }
+
+    const ordered = /^(\s*)(\d+)[.)]\s+(.*)$/.exec(line);
+    if (ordered) {
+      rows.push(...withPrefix(inlineRuns(ordered[3] ?? ''), width, `${ordered[1]}${ordered[2]}.`));
+      continue;
+    }
+
+    const quote = /^\s*>\s?(.*)$/.exec(line);
+    if (quote) {
+      // The bar repeats down every row of the quote: a rule that stopped after
+      // the first wrapped row would read as one quoted line and some prose.
+      rows.push(...withPrefix(inlineRuns(quote[1] ?? ''), width, quoteBar, {
+        continued: quoteBar,
+        prefixFg: 'borderSubtle',
+      }));
+      continue;
+    }
+
+    if (line.trim() === '') { rows.push({ kind: 'text', runs: [{ text: '' }] }); continue; }
+
+    for (const runs of wrapRuns(inlineRuns(line), width)) rows.push({ kind: 'text', runs });
+  }
+
+  // An unterminated fence still gets its closing rule, so the box reads as a
+  // box rather than as something the renderer forgot to finish.
+  if (inFence && ruled) rows.push({ kind: 'fence', fence, part: 'close' });
+
+  return rows;
+}
+
+/** Every run's text, for a measurement or a test that does not care how it looks. */
+export function runsToText(runs: MarkdownRun[]): string {
+  return runs.map((run) => run.text).join('');
+}
+
+/** Wrap plain text the way a row does, for callers that have no runs. */
+export function wrapAt(text: string, width: number): string[] {
+  if (width <= 0) return [text];
+  const wrapped = wrapText(text, width);
+  return wrapped.length > 0 ? wrapped : [''];
+}

package/src/util/paths.ts

@@ -0,0 +1,138 @@
+import type { BindingPath } from '../types/graph.js';
+
+/**
+ * Store paths are JSON-Pointer-shaped.
+ *
+ *   `$/scope/a/b`  absolute; the first segment is the scope
+ *   `/a/b`         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; legal in subscriptions, never in writes
+ *
+ * Internally a path is its segment list. The canonical key is the segments
+ * joined by `/` with no sigil, which is what every map here is keyed by.
+ */
+
+export class PathError extends Error {
+  constructor(message: string, readonly path: string) {
+    super(`${message}: ${path}`);
+    this.name = 'PathError';
+  }
+}
+
+function unescapeSegment(seg: string): string {
+  return seg.includes('~') ? seg.replace(/~1/g, '/').replace(/~0/g, '~') : seg;
+}
+
+export function escapeSegment(seg: string): string {
+  return seg.replace(/~/g, '~0').replace(/\//g, '~1');
+}
+
+export function isAbsolute(path: string): path is `$/${string}` {
+  return path.startsWith('$/');
+}
+
+export function isRelative(path: string): boolean {
+  return path.startsWith('/');
+}
+
+/** Split into segments. Does not resolve relatives - use `resolvePath`. */
+export function segments(path: string): string[] {
+  const body = isAbsolute(path) ? path.slice(2) : path.startsWith('/') ? path.slice(1) : path;
+  if (body === '') return [];
+  const parts = body.split('/');
+  for (const p of parts) {
+    if (p === '..') throw new PathError('".." is forbidden in a store path', path);
+  }
+  return parts.map(unescapeSegment);
+}
+
+/**
+ * Canonical map key for a path: segments joined, no sigil.
+ *
+ * The segments are re-escaped on the way out. Everything downstream - the
+ * store's own walk, `ancestorKeys`, `matchKey` - splits a key on `/`, so a
+ * segment that legitimately contains one (a URI used as a key, a filename with
+ * a slash) has to stay escaped or it silently becomes several segments and the
+ * value lands somewhere nobody looks.
+ */
+export function pathKey(path: string): string {
+  return segments(path).map(escapeSegment).join('/');
+}
+
+export function joinPath(...parts: (string | number)[]): BindingPath {
+  const segs: string[] = [];
+  for (const p of parts) {
+    const s = String(p);
+    for (const seg of s.replace(/^\$\//, '').replace(/^\//, '').split('/')) {
+      if (seg !== '') segs.push(seg);
+    }
+  }
+  return `$/${segs.join('/')}` as BindingPath;
+}
+
+/**
+ * Resolve a possibly-relative path against a data context.
+ * A relative path with no context is an error a caller should never reach.
+ */
+export function resolvePath(path: string, dataContext?: string): BindingPath {
+  if (isAbsolute(path)) return path as BindingPath;
+  if (!path.startsWith('/')) {
+    throw new PathError('a path must start with "$/" or "/"', path);
+  }
+  if (!dataContext) {
+    throw new PathError('relative path used with no data context', path);
+  }
+  const base = segments(dataContext);
+  const rest = segments(path);
+  return `$/${[...base, ...rest].join('/')}` as BindingPath;
+}
+
+export function scopeOf(path: string): string {
+  const segs = segments(path);
+  return segs[0] ?? '';
+}
+
+export function parentKey(key: string): string | null {
+  const i = key.lastIndexOf('/');
+  return i === -1 ? (key === '' ? null : '') : key.slice(0, i);
+}
+
+/** Every ancestor key of `key`, closest first, including `''` for the root. */
+export function ancestorKeys(key: string): string[] {
+  const out: string[] = [];
+  let cur = key;
+  for (;;) {
+    const p = parentKey(cur);
+    if (p === null) break;
+    out.push(p);
+    cur = p;
+    if (p === '') break;
+  }
+  return out;
+}
+
+export function isDescendantKey(key: string, ancestor: string): boolean {
+  if (ancestor === '') return key !== '';
+  return key.startsWith(ancestor + '/');
+}
+
+export function hasWildcard(path: string): boolean {
+  return path.includes('*');
+}
+
+/** Match a concrete key against a pattern key that may contain `*`. */
+export function matchKey(key: string, pattern: string, subtree = false): boolean {
+  if (!pattern.includes('*')) {
+    return key === pattern || (subtree && isDescendantKey(key, pattern));
+  }
+  const p = pattern.split('/');
+  const k = key.split('/');
+  if (!subtree && p.length !== k.length) return false;
+  if (subtree && k.length < p.length) return false;
+  for (let i = 0; i < p.length; i++) {
+    if (p[i] === '*') continue;
+    if (p[i] !== k[i]) return false;
+  }
+  return true;
+}