@textui/core 0.1.0

package/src/render/buffer.ts

@@ -0,0 +1,318 @@
+import type { Rect } from '../types/geometry.js';
+import type { Cell, CellBuffer } from '../types/cells.js';
+import { COLOR_DEFAULT, packColor, type PackedColor } from './color.js';
+
+/** One cell as it is stored: colours packed, nothing allocated to read it. */
+export interface PackedCell {
+  char: string;
+  fg: PackedColor;
+  bg: PackedColor;
+  attrs: number;
+  link: string | undefined;
+}
+import { graphemeWidth } from '../util/text.js';
+
+/** Internal cell flags, kept out of the public attrs bitfield. */
+export const FLAG_CONTINUATION = 1;
+
+/**
+ * The frame.
+ *
+ * Cells live in parallel arrays rather than objects because the diff walks
+ * every cell of every frame, and one allocation per cell per frame is the
+ * difference between a smooth redraw and a visibly stuttering one.
+ */
+export class Buffer implements CellBuffer {
+  width: number;
+  height: number;
+
+  chars: string[];
+  fg: Int32Array;
+  bg: Int32Array;
+  attrs: Uint16Array;
+  flags: Uint8Array;
+  links: (string | undefined)[];
+
+  private prevChars: string[];
+  private prevFg: Int32Array;
+  private prevBg: Int32Array;
+  private prevAttrs: Uint16Array;
+  private prevLinks: (string | undefined)[];
+  private committed = false;
+
+  constructor(width: number, height: number) {
+    this.width = Math.max(0, width);
+    this.height = Math.max(0, height);
+    const n = this.width * this.height;
+    this.chars = new Array<string>(n).fill(' ');
+    this.fg = new Int32Array(n).fill(COLOR_DEFAULT);
+    this.bg = new Int32Array(n).fill(COLOR_DEFAULT);
+    this.attrs = new Uint16Array(n);
+    this.flags = new Uint8Array(n);
+    this.links = new Array<string | undefined>(n).fill(undefined);
+
+    this.prevChars = new Array<string>(n).fill(' ');
+    this.prevFg = new Int32Array(n).fill(COLOR_DEFAULT);
+    this.prevBg = new Int32Array(n).fill(COLOR_DEFAULT);
+    this.prevAttrs = new Uint16Array(n);
+    this.prevLinks = new Array<string | undefined>(n).fill(undefined);
+  }
+
+  /** Cell-object access, for the `CellBuffer` contract and the test harness. */
+  get(x: number, y: number): Cell | undefined {
+    if (!this.inBounds(x, y)) return undefined;
+    const i = this.index(x, y);
+    return {
+      char: this.chars[i] as string,
+      fg: packedToColor(this.fg[i] as number),
+      bg: packedToColor(this.bg[i] as number),
+      attrs: this.attrs[i] as number,
+      link: this.links[i],
+      continuation: ((this.flags[i] as number) & FLAG_CONTINUATION) !== 0,
+    };
+  }
+
+  /**
+   * The same cell, as the numbers it is actually stored as.
+   *
+   * `get` is the friendly shape: it unpacks both colours into `Color` values,
+   * which is right for a test or a caller reasoning about colour and wrong for
+   * a loop over a region - packing them straight back is an allocation and a
+   * round trip per cell. This is what the renderer's inner loops use.
+   */
+  packedAt(x: number, y: number): PackedCell | undefined {
+    if (!this.inBounds(x, y)) return undefined;
+    const i = this.index(x, y);
+    return {
+      char: this.chars[i] as string,
+      fg: this.fg[i] as number,
+      bg: this.bg[i] as number,
+      attrs: this.attrs[i] as number,
+      link: this.links[i],
+    };
+  }
+
+  set(x: number, y: number, cell: Cell): void {
+    this.put(
+      x, y, cell.char,
+      packColor(cell.fg), packColor(cell.bg), cell.attrs, cell.link,
+    );
+  }
+
+  index(x: number, y: number): number {
+    return y * this.width + x;
+  }
+
+  inBounds(x: number, y: number): boolean {
+    return x >= 0 && x < this.width && y >= 0 && y < this.height;
+  }
+
+  /**
+   * Write one grapheme. A double-width grapheme claims the next cell as a
+   * continuation, and writing over either half clears the other - otherwise a
+   * half-overwritten wide character shifts every cell after it on that row.
+   */
+  put(
+    x: number,
+    y: number,
+    char: string,
+    fg: PackedColor = COLOR_DEFAULT,
+    bg: PackedColor = COLOR_DEFAULT,
+    attrs = 0,
+    link?: string,
+  ): void {
+    if (!this.inBounds(x, y)) return;
+    const i = this.index(x, y);
+
+    // Overwriting the right half of a wide pair: blank the left half.
+    if (((this.flags[i] as number) & FLAG_CONTINUATION) !== 0 && x > 0) {
+      this.chars[i - 1] = ' ';
+      this.flags[i - 1] = 0;
+    }
+    // Overwriting a wide left half: blank its continuation.
+    if (x + 1 < this.width && ((this.flags[i + 1] as number) & FLAG_CONTINUATION) !== 0) {
+      this.chars[i + 1] = ' ';
+      this.flags[i + 1] = 0;
+    }
+
+    /*
+     * The width of one printable ASCII character, without asking.
+     *
+     * `graphemeWidth` is a function call per cell painted - twelve thousand of
+     * them a frame on a full screen - to answer "is `a` one cell wide". It is,
+     * and the character code says so.
+     */
+    const only = char.length === 1 ? char.charCodeAt(0) : -1;
+    const w = only >= 0x20 && only <= 0x7e ? 1 : graphemeWidth(char);
+    if (w === 0) return;
+
+    this.chars[i] = char;
+    this.fg[i] = fg;
+    this.bg[i] = bg;
+    this.attrs[i] = attrs;
+    this.flags[i] = 0;
+    this.links[i] = link;
+
+    if (w === 2) {
+      if (x + 1 >= this.width) {
+        // A wide grapheme in the last column cannot render; blank it.
+        this.chars[i] = ' ';
+        return;
+      }
+      const j = i + 1;
+      if (x + 2 < this.width && ((this.flags[j + 1] as number) & FLAG_CONTINUATION) !== 0) {
+        this.chars[j + 1] = ' ';
+        this.flags[j + 1] = 0;
+      }
+      this.chars[j] = '';
+      this.fg[j] = fg;
+      this.bg[j] = bg;
+      this.attrs[j] = attrs;
+      this.flags[j] = FLAG_CONTINUATION;
+      this.links[j] = link;
+    }
+  }
+
+  /**
+   * Blank a region, or the whole buffer.
+   *
+   * By span rather than by cell. Clearing everything happens once a frame, and
+   * a cell-at-a-time loop over twelve thousand of them - each with two bounds
+   * checks and an index multiply - was costing more than painting the content
+   * that replaced it. `fill` is one call into the engine per array, and the
+   * four that matter are typed.
+   */
+  clear(rect?: Rect, bg: PackedColor = COLOR_DEFAULT): void {
+    if (rect === undefined) {
+      this.fillSpan(0, this.width * this.height, bg);
+      return;
+    }
+
+    const x0 = Math.max(0, rect.x);
+    const x1 = Math.min(this.width, rect.x + rect.width);
+    const y0 = Math.max(0, rect.y);
+    const y1 = Math.min(this.height, rect.y + rect.height);
+    if (x1 <= x0 || y1 <= y0) return;
+
+    // A row at a time: rows are contiguous, columns are not.
+    for (let y = y0; y < y1; y++) {
+      const start = y * this.width;
+      this.fillSpan(start + x0, start + x1, bg);
+    }
+  }
+
+  private fillSpan(from: number, to: number, bg: PackedColor): void {
+    this.chars.fill(' ', from, to);
+    this.fg.fill(COLOR_DEFAULT, from, to);
+    this.bg.fill(bg, from, to);
+    this.attrs.fill(0, from, to);
+    this.flags.fill(0, from, to);
+    this.links.fill(undefined, from, to);
+  }
+
+  resize(width: number, height: number): void {
+    if (width === this.width && height === this.height) return;
+    const next = new Buffer(width, height);
+    const w = Math.min(width, this.width);
+    const h = Math.min(height, this.height);
+    for (let y = 0; y < h; y++) {
+      for (let x = 0; x < w; x++) {
+        const from = this.index(x, y);
+        const to = next.index(x, y);
+        next.chars[to] = this.chars[from] as string;
+        next.fg[to] = this.fg[from] as number;
+        next.bg[to] = this.bg[from] as number;
+        next.attrs[to] = this.attrs[from] as number;
+        next.flags[to] = this.flags[from] as number;
+        next.links[to] = this.links[from];
+      }
+    }
+    this.width = next.width;
+    this.height = next.height;
+    this.chars = next.chars;
+    this.fg = next.fg;
+    this.bg = next.bg;
+    this.attrs = next.attrs;
+    this.flags = next.flags;
+    this.links = next.links;
+
+    // A resize invalidates the previous frame entirely.
+    const n = width * height;
+    this.prevChars = new Array<string>(n).fill(' ');
+    this.prevFg = new Int32Array(n).fill(COLOR_DEFAULT);
+    this.prevBg = new Int32Array(n).fill(COLOR_DEFAULT);
+    this.prevAttrs = new Uint16Array(n);
+    this.prevLinks = new Array<string | undefined>(n).fill(undefined);
+    this.committed = false;
+  }
+
+  cellChanged(i: number): boolean {
+    return (
+      this.chars[i] !== this.prevChars[i] ||
+      this.fg[i] !== this.prevFg[i] ||
+      this.bg[i] !== this.prevBg[i] ||
+      this.attrs[i] !== this.prevAttrs[i] ||
+      this.links[i] !== this.prevLinks[i]
+    );
+  }
+
+  dirtyRows(): number[] {
+    if (!this.committed) {
+      return Array.from({ length: this.height }, (_, y) => y);
+    }
+    const rows: number[] = [];
+    for (let y = 0; y < this.height; y++) {
+      const start = y * this.width;
+      for (let x = 0; x < this.width; x++) {
+        if (this.cellChanged(start + x)) {
+          rows.push(y);
+          break;
+        }
+      }
+    }
+    return rows;
+  }
+
+  commit(): void {
+    this.prevChars = this.chars.slice();
+    this.prevFg = this.fg.slice();
+    this.prevBg = this.bg.slice();
+    this.prevAttrs = this.attrs.slice();
+    this.prevLinks = this.links.slice();
+    this.committed = true;
+  }
+
+  /** Force the next diff to repaint everything. After a resize or a redraw. */
+  invalidate(): void {
+    this.committed = false;
+  }
+
+  toText(rect?: Rect): string {
+    const r = rect ?? { x: 0, y: 0, width: this.width, height: this.height };
+    const lines: string[] = [];
+    for (let y = r.y; y < r.y + r.height; y++) {
+      if (y < 0 || y >= this.height) continue;
+      let line = '';
+      for (let x = r.x; x < r.x + r.width; x++) {
+        if (x < 0 || x >= this.width) continue;
+        const i = this.index(x, y);
+        if (((this.flags[i] as number) & FLAG_CONTINUATION) !== 0) continue;
+        line += this.chars[i] as string;
+      }
+      lines.push(line.replace(/[ ]+$/, ''));
+    }
+    return lines.join('\n');
+  }
+}
+
+export function createBuffer(width: number, height: number): Buffer {
+  return new Buffer(width, height);
+}
+
+function packedToColor(packed: PackedColor): Cell['fg'] {
+  if (packed === COLOR_DEFAULT) return 'default';
+  if (packed >= 0x1000000) {
+    return { rgb: [(packed >> 16) & 0xff, (packed >> 8) & 0xff, packed & 0xff] };
+  }
+  return { palette: packed };
+}

package/src/render/color.ts

@@ -0,0 +1,180 @@
+import type { AnsiColorName, Color, ColorDepth } from '../types/index.js';
+
+/**
+ * Colours are packed into one integer so a cell is cheap to store and cheap to
+ * compare - the frame diff runs over every cell, every frame.
+ *
+ *   -1              terminal default
+ *   0..255          palette index (0..15 are the ANSI names)
+ *   >= 0x1000000    24-bit rgb, as 0x1000000 | rrggbb
+ */
+export type PackedColor = number;
+
+export const COLOR_DEFAULT: PackedColor = -1;
+const RGB_FLAG = 0x1000000;
+
+export const ANSI_NAMES: Record<AnsiColorName, number> = {
+  black: 0, red: 1, green: 2, yellow: 3,
+  blue: 4, magenta: 5, cyan: 6, white: 7,
+  brightBlack: 8, brightRed: 9, brightGreen: 10, brightYellow: 11,
+  brightBlue: 12, brightMagenta: 13, brightCyan: 14, brightWhite: 15,
+};
+
+export function packRgb(r: number, g: number, b: number): PackedColor {
+  return RGB_FLAG | ((r & 0xff) << 16) | ((g & 0xff) << 8) | (b & 0xff);
+}
+
+export function isRgb(c: PackedColor): boolean {
+  return c >= RGB_FLAG;
+}
+
+export function unpackRgb(c: PackedColor): [number, number, number] {
+  return [(c >> 16) & 0xff, (c >> 8) & 0xff, c & 0xff];
+}
+
+export function packColor(color: Color | undefined): PackedColor {
+  if (color === undefined || color === 'default') return COLOR_DEFAULT;
+  if (typeof color === 'string') {
+    if (color.startsWith('#')) {
+      const hex = color.slice(1);
+      if (hex.length === 3) {
+        const r = parseInt(hex[0] as string, 16);
+        const g = parseInt(hex[1] as string, 16);
+        const b = parseInt(hex[2] as string, 16);
+        return packRgb(r * 17, g * 17, b * 17);
+      }
+      if (hex.length === 6) {
+        return packRgb(
+          parseInt(hex.slice(0, 2), 16),
+          parseInt(hex.slice(2, 4), 16),
+          parseInt(hex.slice(4, 6), 16),
+        );
+      }
+      return COLOR_DEFAULT;
+    }
+    const idx = ANSI_NAMES[color as AnsiColorName];
+    return idx === undefined ? COLOR_DEFAULT : idx;
+  }
+  if ('rgb' in color) {
+    const [r, g, b] = color.rgb;
+    return packRgb(r, g, b);
+  }
+  if ('palette' in color) return color.palette & 0xff;
+  return COLOR_DEFAULT;
+}
+
+/** The xterm 256 palette, so 24-bit can be reduced without a lookup table. */
+const CUBE_STEPS = [0, 95, 135, 175, 215, 255];
+
+function nearestCube(v: number): number {
+  let best = 0;
+  let bestDist = Infinity;
+  for (let i = 0; i < CUBE_STEPS.length; i++) {
+    const d = Math.abs((CUBE_STEPS[i] as number) - v);
+    if (d < bestDist) { bestDist = d; best = i; }
+  }
+  return best;
+}
+
+function rgbTo256(r: number, g: number, b: number): number {
+  // Greyscale ramp is a better fit when the channels are close.
+  if (Math.abs(r - g) < 8 && Math.abs(g - b) < 8) {
+    if (r < 8) return 16;
+    if (r > 248) return 231;
+    return 232 + Math.round(((r - 8) / 247) * 23);
+  }
+  return 16 + 36 * nearestCube(r) + 6 * nearestCube(g) + nearestCube(b);
+}
+
+const ANSI16_RGB: [number, number, number][] = [
+  [0, 0, 0], [205, 49, 49], [13, 188, 121], [229, 229, 16],
+  [36, 114, 200], [188, 63, 188], [17, 168, 205], [229, 229, 229],
+  [102, 102, 102], [241, 76, 76], [35, 209, 139], [245, 245, 67],
+  [59, 142, 234], [214, 112, 214], [41, 184, 219], [255, 255, 255],
+];
+
+function rgbTo16(r: number, g: number, b: number): number {
+  let best = 0;
+  let bestDist = Infinity;
+  for (let i = 0; i < 16; i++) {
+    const [cr, cg, cb] = ANSI16_RGB[i] as [number, number, number];
+    const d = (r - cr) ** 2 + (g - cg) ** 2 + (b - cb) ** 2;
+    if (d < bestDist) { bestDist = d; best = i; }
+  }
+  return best;
+}
+
+function palette256ToRgb(idx: number): [number, number, number] {
+  if (idx < 16) return ANSI16_RGB[idx] as [number, number, number];
+  if (idx >= 232) {
+    const v = 8 + (idx - 232) * 10;
+    return [v, v, v];
+  }
+  const n = idx - 16;
+  return [
+    CUBE_STEPS[Math.floor(n / 36) % 6] as number,
+    CUBE_STEPS[Math.floor(n / 6) % 6] as number,
+    CUBE_STEPS[n % 6] as number,
+  ];
+}
+
+/**
+ * Reduce a colour to what the terminal can show. A component never picks a
+ * fallback itself - it names a token, and this decides what that survives as.
+ */
+export function downsample(c: PackedColor, depth: ColorDepth): PackedColor {
+  if (c === COLOR_DEFAULT) return c;
+  if (depth === 0) return COLOR_DEFAULT;
+  if (depth === 24) return c;
+
+  if (isRgb(c)) {
+    const [r, g, b] = unpackRgb(c);
+    return depth === 8 ? rgbTo256(r, g, b) : rgbTo16(r, g, b);
+  }
+  if (depth === 8) return c;
+  if (c < 16) return c;
+  const [r, g, b] = palette256ToRgb(c);
+  return rgbTo16(r, g, b);
+}
+
+/** Relative luminance, for picking readable foreground over a background. */
+export function luminance(c: PackedColor): number {
+  const [r, g, b] = isRgb(c) ? unpackRgb(c) : palette256ToRgb(c < 0 ? 0 : c);
+  const f = (v: number): number => {
+    const s = v / 255;
+    return s <= 0.03928 ? s / 12.92 : ((s + 0.055) / 1.055) ** 2.4;
+  };
+  return 0.2126 * f(r) + 0.7152 * f(g) + 0.0722 * f(b);
+}
+
+/** Mix two packed colours. `t` of 0 is `a`, 1 is `b`. */
+export function mix(a: PackedColor, b: PackedColor, t: number): PackedColor {
+  const [ar, ag, ab] = isRgb(a) ? unpackRgb(a) : palette256ToRgb(Math.max(0, a));
+  const [br, bg, bb] = isRgb(b) ? unpackRgb(b) : palette256ToRgb(Math.max(0, b));
+  return packRgb(
+    Math.round(ar + (br - ar) * t),
+    Math.round(ag + (bg - ag) * t),
+    Math.round(ab + (bb - ab) * t),
+  );
+}
+
+/**
+ * A packed colour back as a `Color`, which is the shape a style takes.
+ *
+ * The inverse of `packColor`, for the places that compute a colour and then
+ * have to hand it to a component - blending a tint out of two theme colours,
+ * say. Painting goes the other way and should stay packed.
+ */
+export function unpackColor(packed: PackedColor): Color {
+  if (packed === COLOR_DEFAULT) return 'default';
+  if (isRgb(packed)) {
+    const [r, g, b] = unpackRgb(packed);
+    return { rgb: [r, g, b] };
+  }
+  return { palette: packed };
+}
+
+export function toHex(c: PackedColor): string {
+  const [r, g, b] = isRgb(c) ? unpackRgb(c) : palette256ToRgb(Math.max(0, c));
+  return `#${[r, g, b].map((v) => v.toString(16).padStart(2, '0')).join('')}`;
+}

package/src/render/diff.ts

@@ -0,0 +1,99 @@
+import type { Buffer } from './buffer.js';
+import { FLAG_CONTINUATION } from './buffer.js';
+import type { PackedColor } from './color.js';
+
+/** One contiguous run of identical-style cells - what the writer emits. */
+export interface Run {
+  x: number;
+  y: number;
+  text: string;
+  fg: PackedColor;
+  bg: PackedColor;
+  attrs: number;
+  link: string | undefined;
+}
+
+export interface Frame {
+  runs: Run[];
+  cursor: { x: number; y: number; visible: boolean } | null;
+  /** True when every row was emitted - first frame, or after invalidate. */
+  full: boolean;
+}
+
+/**
+ * Turn changed cells into runs.
+ *
+ * Two economies matter here and nowhere else: only touched rows are walked,
+ * and within a row, adjacent changed cells sharing a style become one run, so
+ * a redraw costs one cursor move and one SGR change per run rather than per
+ * cell. A run continues through a short stretch of unchanged cells when
+ * repainting them is cheaper than moving the cursor around them.
+ */
+export function diffFrame(
+  buffer: Buffer,
+  cursor: { x: number; y: number; visible: boolean } | null = null,
+  gapTolerance = 4,
+): Frame {
+  const runs: Run[] = [];
+  const rows = buffer.dirtyRows();
+  const full = rows.length === buffer.height && buffer.height > 0;
+
+  for (const y of rows) {
+    const base = y * buffer.width;
+    let x = 0;
+
+    while (x < buffer.width) {
+      const i = base + x;
+      if (((buffer.flags[i] as number) & FLAG_CONTINUATION) !== 0 || !buffer.cellChanged(i)) {
+        x++;
+        continue;
+      }
+
+      const fg = buffer.fg[i] as number;
+      const bg = buffer.bg[i] as number;
+      const attrs = buffer.attrs[i] as number;
+      const link = buffer.links[i];
+
+      let text = '';
+      let cx = x;
+      let gap = 0;
+      let pendingGap = '';
+
+      while (cx < buffer.width) {
+        const j = base + cx;
+        if (((buffer.flags[j] as number) & FLAG_CONTINUATION) !== 0) {
+          cx++;
+          continue;
+        }
+
+        const sameStyle =
+          buffer.fg[j] === fg &&
+          buffer.bg[j] === bg &&
+          buffer.attrs[j] === attrs &&
+          buffer.links[j] === link;
+        if (!sameStyle) break;
+
+        if (buffer.cellChanged(j)) {
+          if (pendingGap !== '') {
+            text += pendingGap;
+            pendingGap = '';
+            gap = 0;
+          }
+          text += buffer.chars[j] as string;
+          cx++;
+          continue;
+        }
+
+        gap++;
+        if (gap > gapTolerance) break;
+        pendingGap += buffer.chars[j] as string;
+        cx++;
+      }
+
+      if (text !== '') runs.push({ x, y, text, fg, bg, attrs, link });
+      x = cx > x ? cx : x + 1;
+    }
+  }
+
+  return { runs, cursor, full };
+}