@textui/chat 0.6.0

package/src/controls.tsx

@@ -0,0 +1,222 @@
+import type { BoxProps, RenderOutput } from '@textui/core';
+import { defineComponent, useFocus, useInput, useTheme } from '@textui/core';
+import { Column, Row } from '@textui/widgets';
+
+/**
+ * The composer's control rows: what this message will be sent as.
+ *
+ * Under the field, and everything on it is a *current value* rather than a
+ * label. What will run - which harness, which model, how much it may do
+ * before it asks - and, when the host asks it, where: the directory, whether
+ * in place or in a worktree, and from which branch. A person can read what
+ * will happen without opening anything, and change any of it without leaving
+ * the composer.
+ *
+ * Where gets a row of its own, and only when there is a where. One line held
+ * all of it until a host that answers every question the reference host asks
+ * put eight chips on it, and the row truncated each to its mark; a host that
+ * asks nothing about where - a chat that runs where it was opened - keeps the
+ * one line, with send at the end of it, rather than a second row holding
+ * nothing but send.
+ *
+ * Each chip is one command's argument, asked through the palette (see
+ * `picker.ts`). That is the whole design: nothing here knows what a model or a
+ * permission mode is, so a new chip is a new command and no change to this
+ * file.
+ */
+
+export interface ComposerOption {
+  id: string;
+  /** The value, as a person reads it. Never the id the host stores. */
+  label: string;
+  /**
+   * The question, as opposed to the answer in `label`.
+   *
+   * The chip has no room for it - "Ask each time" is the whole row and the
+   * mark in front says which question it belongs to - but anything listing
+   * these somewhere with more space needs the pair, and the host's own wording
+   * for both is on the schema rather than in this file.
+   */
+  title?: string;
+  icon?: string;
+  /** The command whose argument this chip asks about. Absent: shown, not asked. */
+  commandId?: string;
+  /** On the second row, with the workspace: where the session runs rather than what runs it. */
+  where?: boolean;
+}
+
+export interface ComposerBarProps extends BoxProps {
+  options: ComposerOption[];
+  onOpen(option: ComposerOption, anchorId: string): void;
+  onSend(): void;
+  /** Escape on a chip: back to the field. */
+  onLeave?(): void;
+  /** A turn is running, so this message joins the queue instead. */
+  running?: boolean;
+  queued?: number;
+  sendDisabled?: boolean;
+}
+
+/** The focus id of one chip. The picker anchors to it, so it has to be knowable. */
+export const chipId = (id: string): string => `chat.option.${id}`;
+
+export const SEND_ID = 'chat.send';
+
+/**
+ * How many rows the bar takes for these options.
+ *
+ * Two when any of them is a `where`, and one otherwise - which is the number
+ * the composer needs before the bar is drawn, to know how much of a short
+ * terminal is left for the menu above it.
+ */
+export function composerRows(options: ComposerOption[]): 1 | 2 {
+  return options.some((option) => option.where) ? 2 : 1;
+}
+
+export const ComposerBar: (props: ComposerBarProps) => RenderOutput =
+  defineComponent<ComposerBarProps>('ComposerBar', (props) => {
+    const { options, onOpen, onSend, onLeave, running, queued = 0, sendDisabled, ...rest } = props;
+    const theme = useTheme();
+
+    // The first row and then the second, which is also the tab order. Stated
+    // rather than inherited: tab order is registration order, and which chips
+    // exist is the *host's* answer - it arrives one round trip after the rows
+    // are first drawn, so the ones that were there from the start would
+    // otherwise come first however far to the right they sit.
+    const what = options.filter((option) => !option.where);
+    const where = options.filter((option) => option.where);
+    const ordered = [...what, ...where];
+    const chip = (option: ComposerOption): RenderOutput => (option.commandId
+      ? (
+        <Chip
+          key={option.id}
+          focusId={chipId(option.id)}
+          order={ordered.indexOf(option)}
+          label={option.label}
+          {...(option.icon ? { icon: option.icon } : {})}
+          onOpen={() => onOpen(option, chipId(option.id))}
+          {...(onLeave ? { onLeave } : {})}
+        />
+      )
+      : (
+        // Shown, not asked: a value that is fixed for this session is
+        // still worth reading, and a chip that opens a panel offering one
+        // choice is a worse way of saying so.
+        <Row key={option.id} gap={1}>
+          {option.icon ? <text content={option.icon} fg="subtle" /> : null}
+          <text content={option.label} fg="subtle" />
+        </Row>
+      ));
+
+    // The end of the last row, whichever row that is: what is waiting, and
+    // the one verb on the bar.
+    const tail = [
+      <text key="gap" content="" flex={1} />,
+      queued > 0 ? <text key="queued" content={`${queued} queued`} fg="warning" /> : null,
+      <Chip
+        key="send"
+        focusId={SEND_ID}
+        order={ordered.length}
+        label={running ? 'queue' : 'send'}
+        trailing={theme.glyphs.chevronRight}
+        tone="accent"
+        {...(sendDisabled ? { disabled: true } : {})}
+        onOpen={onSend}
+        {...(onLeave ? { onLeave } : {})}
+      />,
+    ];
+
+    if (where.length === 0) {
+      return (
+        <Row gap={1} {...rest}>
+          {what.map(chip)}
+          {tail}
+        </Row>
+      );
+    }
+
+    return (
+      <Column gap={0} {...rest}>
+        <Row gap={1}>
+          {what.map(chip)}
+        </Row>
+        <Row gap={1}>
+          {where.map(chip)}
+          {tail}
+        </Row>
+      </Column>
+    );
+  });
+
+interface ChipProps {
+  focusId: string;
+  /** Where tab reaches it. The row's own order, not the order it mounted in. */
+  order: number;
+  label: string;
+  icon?: string;
+  /** After the label. A chevron for something that opens, an arrow for send. */
+  trailing?: string;
+  tone?: 'accent';
+  disabled?: boolean;
+  onOpen(): void;
+  /** Escape. Absent, the key goes on to whatever the screen does with it. */
+  onLeave?(): void;
+}
+
+/**
+ * One value on the control row.
+ *
+ * Not a `Button`: a button is a verb and these are nouns, and at `size="sm"`
+ * four of them still read as four buttons rather than as one sentence about
+ * what is about to be sent. What it borrows from a button is the part that
+ * matters - it is focusable, tab reaches it, and enter opens it.
+ */
+const Chip = defineComponent<ChipProps>('ComposerChip', (props) => {
+  const { focusId, order, label, icon, trailing, tone, disabled, onOpen, onLeave } = props;
+  const theme = useTheme();
+  const focus = useFocus({ id: focusId, order, disabled: disabled === true });
+
+  useInput((event) => {
+    if (disabled) return false;
+    // Out of the row and back to the field, the way escape leaves the field
+    // for the transcript: one step out, not out of the screen.
+    if (event.name === 'escape' && onLeave) {
+      onLeave();
+      return true;
+    }
+    // Down as well as enter: the panel comes up out of the chip, and reaching
+    // for it downwards is what the shape of the thing suggests.
+    if (event.name === 'enter' || event.name === 'space' || event.name === 'down') {
+      onOpen();
+      return true;
+    }
+    return false;
+  }, { focusId: focus.id, enabled: disabled !== true });
+
+  return (
+    <Row
+      id={focus.id}
+      gap={1}
+      padding={[0, 1]}
+      {...(focus.focused ? { bg: 'selected' as const } : {})}
+      onClick={disabled ? undefined : onOpen}
+    >
+      {/* The mark and the chevron never give up room. As the terminal
+          narrows the labels truncate from the right, and a chip that has
+          given up its mark as well is four cells of ellipsis that could be
+          any of six questions. */}
+      {icon ? <text content={icon} shrink={0} fg={focus.focused ? 'inverted' : tone ?? 'muted'} /> : null}
+      <text
+        content={label}
+        truncate="end"
+        fg={focus.focused ? 'inverted' : disabled ? 'disabled' : tone ?? undefined}
+        {...(tone ? { bold: true } : {})}
+      />
+      <text
+        content={trailing ?? theme.glyphs.chevronDown}
+        shrink={0}
+        fg={focus.focused ? 'inverted' : 'subtle'}
+      />
+    </Row>
+  );
+});

package/src/details.tsx

@@ -0,0 +1,162 @@
+import type { BoxProps, RenderOutput, SemanticVariant } from '@textui/core';
+import {
+  defineComponent,
+  useClipboard,
+  useEffect,
+  useFocus,
+  useInput,
+  useState,
+  useTheme,
+} from '@textui/core';
+import { Column, Row } from '@textui/widgets';
+
+/**
+ * A property list you can walk, and take a value out of.
+ *
+ * The catalogue's detail pane is where the identifiers live - a session URI, a
+ * chat URI - and an identifier you cannot read in full or paste anywhere is
+ * decoration. `KeyValue` draws the same pairs and is static: nothing selects a
+ * row, so nothing can be copied and nothing can be shown untruncated.
+ *
+ * So the selected row is the one that gets the room. Every other row is one
+ * line with its value truncated, and the selected row wraps its value across
+ * as many lines as it needs - which costs nothing when the value is short and
+ * is the whole answer when it is a URI in a 36-column pane. `enter` puts it on
+ * the clipboard.
+ *
+ * This is a finding, not a flourish: it is the third component this example
+ * wanted that the catalog does not have.
+ */
+
+export interface DetailField {
+  id: string;
+  label: string;
+  value: string;
+  tone?: SemanticVariant;
+  /** Shown instead of the value when there is none, in the subtle tone. */
+  absent?: string;
+}
+
+export interface SessionDetailsProps extends BoxProps {
+  fields: DetailField[];
+  focusId?: string;
+  /**
+   * Width of the label column, where a caller wants to fix it.
+   *
+   * Left off, it is the widest label there is. It used to be a constant on
+   * the grounds that the labels were ours, and they are not: a session's
+   * settings and a model's options are named by whichever host is answering,
+   * in words this client does not choose, and the constant was one character
+   * wider than the longest label anybody had thought of.
+   */
+  labelWidth?: number;
+  /**
+   * Take the keyboard on the frame this mounts, out of whatever holds it.
+   *
+   * Not `autoFocus`, which claims focus rather than taking it: a pane that
+   * appears *because* a key asked for it has to end up with the cursor, and
+   * the thing it is taking the cursor from - the session list - is in the
+   * same focus scope and already has it.
+   *
+   * It has to be done here rather than by the screen that mounts this,
+   * because a focusable registers in its own effect: on the render that opens
+   * the pane, the id does not exist yet and the screen's `focus()` is a call
+   * that quietly returns false.
+   */
+  claim?: boolean;
+  /**
+   * Which rows show their value whole.
+   *
+   * `selected` is the default and the one that keeps the pane a list: every
+   * row is one line, and the row you have stopped on wraps to as many as its
+   * value needs. `all` wraps every row, which is what you want when the
+   * values *are* the point - a pane of URIs where the answer is on the third
+   * one down and reading it should not mean walking there first.
+   */
+  values?: 'selected' | 'all';
+}
+
+export const SessionDetails: (props: SessionDetailsProps) => RenderOutput =
+  defineComponent<SessionDetailsProps>('SessionDetails', (props) => {
+    const { fields, focusId, labelWidth, claim, values = 'selected', ...rest } = props;
+    // Floored at the eleven this used to be, so nothing that already fitted
+    // moves, and capped so one verbose title cannot take the pane from the
+    // values it is there to label.
+    const column = labelWidth ?? Math.min(20, Math.max(11, ...fields.map((field) => field.label.length)));
+    const theme = useTheme();
+    const clipboard = useClipboard();
+    const focus = useFocus({ ...(focusId ? { id: focusId } : {}) });
+    const [index, setIndex] = useState(0);
+    const [copied, setCopied] = useState<string | null>(null);
+
+    // The selection is an index into a list that changes with the selected
+    // session, so it is clamped on the way out rather than reset on the way in.
+    const at = Math.max(0, Math.min(index, fields.length - 1));
+
+    // After the registration above, which is the whole point of it being here.
+    useEffect(() => { if (claim) focus.focus(); }, [claim]);
+
+    useInput((event) => {
+      if (fields.length === 0) return false;
+      switch (event.name) {
+        case 'up': setIndex(Math.max(0, at - 1)); setCopied(null); return true;
+        case 'down': setIndex(Math.min(fields.length - 1, at + 1)); setCopied(null); return true;
+        case 'home': setIndex(0); setCopied(null); return true;
+        case 'end': setIndex(fields.length - 1); setCopied(null); return true;
+        case 'enter': {
+          const field = fields[at];
+          if (!field || !field.value) return true;
+          // OSC 52 where the terminal takes it, and the store either way - so
+          // a test can assert what was copied without a terminal at all.
+          clipboard.write(field.value);
+          setCopied(field.id);
+          return true;
+        }
+        default: return false;
+      }
+    }, { focusId: focus.id });
+
+    return (
+      <Column {...rest} id={focus.id}>
+        {fields.map((field, i) => {
+          const active = i === at;
+          const selected = active && focus.focused;
+          const whole = values === 'all' || active;
+          return (
+            // `align="start"` because a wrapped value makes the row two lines
+            // tall and the label is one: centred, it drifted down to sit
+            // beside the *second* line of a URI, with nothing at all beside
+            // the first. A label names the row it starts.
+            <Row key={field.id} gap={1} align="start">
+              <text
+                content={active ? theme.glyphs.chevronRight : ' '}
+                fg={selected ? 'accent' : 'subtle'}
+                shrink={0}
+              />
+              {/* Neither of these gives up a cell. `width` is a starting size,
+                  not a floor - shrink is 1 unless it is said - so a value with
+                  no space in it to break at was squeezing the label column,
+                  and `Chat` ended up four columns left of `Harness`. A column
+                  that moves per row is not a column. */}
+              <text
+                content={field.label}
+                width={column}
+                shrink={0}
+                fg="muted"
+                truncate="end"
+              />
+              <text
+                content={field.value || field.absent || '-'}
+                flex={1}
+                {...(whole ? { wrap: 'word' as const } : { truncate: 'end' as const })}
+                {...(field.value ? {} : { fg: 'subtle' as const })}
+                {...(field.tone && field.value ? { fg: field.tone } : {})}
+                {...(selected ? { bold: true } : {})}
+              />
+              {copied === field.id ? <text content="copied" fg="success" shrink={0} /> : null}
+            </Row>
+          );
+        })}
+      </Column>
+    );
+  });

package/src/diff.ts

@@ -0,0 +1,132 @@
+/**
+ * A line diff, small enough to read.
+ *
+ * The host sends two whole files and a count of what changed between them; it
+ * does not send the diff itself, so somebody has to work out which lines those
+ * were. This is that, and it is deliberately the textbook algorithm rather
+ * than anything clever: the longest common subsequence of the two line arrays,
+ * with everything not in it marked as removed on the left or added on the
+ * right.
+ *
+ * The cost is quadratic in the number of lines, which is why `diffLines` takes
+ * a ceiling. Two files of ten thousand lines each is a hundred million cells
+ * and a terminal that stops answering, and the honest answer at that size is
+ * to say the files are too big rather than to spend a minute proving it.
+ */
+
+export type DiffKind = 'same' | 'added' | 'removed';
+
+export interface DiffRow {
+  kind: DiffKind;
+  /** 1-based, on the side this row exists on. Absent on the side it does not. */
+  before?: number;
+  after?: number;
+  text: string;
+}
+
+export interface DiffResult {
+  rows: DiffRow[];
+  added: number;
+  removed: number;
+  /** Set instead of a diff when the pair was over `limit`. */
+  tooLarge?: { lines: number; limit: number };
+}
+
+/** Lines of a file, with the trailing newline not counted as an empty last line. */
+export function toLines(text: string): string[] {
+  if (text === '') return [];
+  const lines = text.split('\n');
+  if (lines[lines.length - 1] === '') lines.pop();
+  return lines;
+}
+
+/**
+ * The two sides, lined up.
+ *
+ * A creation has no `before` and a deletion no `after`; both are passed as an
+ * empty string rather than as a special case, because "every line is an
+ * addition" is exactly the right diff for a new file and needs no branch of
+ * its own.
+ */
+export function diffLines(before: string, after: string, limit = 4000): DiffResult {
+  const a = toLines(before);
+  const b = toLines(after);
+
+  if (a.length + b.length > limit) {
+    return { rows: [], added: 0, removed: 0, tooLarge: { lines: a.length + b.length, limit } };
+  }
+
+  // The common head and tail first. Two files that differ in one line share
+  // everything either side of it, and taking those off shrinks the table the
+  // quadratic part has to fill to the part that actually differs.
+  let head = 0;
+  while (head < a.length && head < b.length && a[head] === b[head]) head++;
+  let tail = 0;
+  while (
+    tail < a.length - head
+    && tail < b.length - head
+    && a[a.length - 1 - tail] === b[b.length - 1 - tail]
+  ) tail++;
+
+  const midA = a.slice(head, a.length - tail);
+  const midB = b.slice(head, b.length - tail);
+  const table = lcs(midA, midB);
+
+  const rows: DiffRow[] = [];
+  let added = 0;
+  let removed = 0;
+  const push = (kind: DiffKind, text: string, ai: number, bi: number): void => {
+    rows.push({
+      kind,
+      ...(kind !== 'added' ? { before: ai + 1 } : {}),
+      ...(kind !== 'removed' ? { after: bi + 1 } : {}),
+      text,
+    });
+    if (kind === 'added') added++;
+    if (kind === 'removed') removed++;
+  };
+
+  for (let i = 0; i < head; i++) push('same', a[i] as string, i, i);
+
+  // Walking the table forwards, so the rows come out in file order.
+  let i = 0;
+  let j = 0;
+  while (i < midA.length || j < midB.length) {
+    if (i < midA.length && j < midB.length && midA[i] === midB[j]) {
+      push('same', midA[i] as string, head + i, head + j);
+      i++; j++;
+    // A tie goes to the removal, so a replaced line reads `-old` then `+new`
+    // the way every other diff on the machine prints it. With `>=` here the
+    // pair comes out the other way round, which is not wrong so much as
+    // unreadable next to `git diff`.
+    } else if (j < midB.length && (i === midA.length || (table[i]?.[j + 1] ?? 0) > (table[i + 1]?.[j] ?? 0))) {
+      push('added', midB[j] as string, head + i, head + j);
+      j++;
+    } else {
+      push('removed', midA[i] as string, head + i, head + j);
+      i++;
+    }
+  }
+
+  for (let k = 0; k < tail; k++) {
+    push('same', a[a.length - tail + k] as string, a.length - tail + k, b.length - tail + k);
+  }
+
+  return { rows, added, removed };
+}
+
+/**
+ * `table[i][j]` is the length of the longest common subsequence of `a[i..]`
+ * and `b[j..]`, filled from the end so the walk above can go forwards.
+ */
+function lcs(a: string[], b: string[]): number[][] {
+  const table: number[][] = Array.from({ length: a.length + 1 }, () => new Array<number>(b.length + 1).fill(0));
+  for (let i = a.length - 1; i >= 0; i--) {
+    for (let j = b.length - 1; j >= 0; j--) {
+      (table[i] as number[])[j] = a[i] === b[j]
+        ? (table[i + 1]?.[j + 1] ?? 0) + 1
+        : Math.max(table[i + 1]?.[j] ?? 0, table[i]?.[j + 1] ?? 0);
+    }
+  }
+  return table;
+}

package/src/filediff.tsx

@@ -0,0 +1,118 @@
+import type { BoxProps, RenderOutput } from '@textui/core';
+import { defineComponent, useTheme } from '@textui/core';
+import { Column, EmptyState, Row, ScrollView } from '@textui/widgets';
+import type { DiffResult } from './diff.js';
+
+/**
+ * One file out of a changeset, both sides of it.
+ *
+ * Unified rather than side by side, and not for want of a splitter: a terminal
+ * that a changeset list already shares with a session pane has sixty columns
+ * left, and eighty characters of source in thirty is two columns of nothing
+ * legible. Unified spends the width on the line instead.
+ *
+ * Every row is exactly one row tall. The scroll position is a row count, so a
+ * line that wrapped would put the gutter numbers out of step with what is on
+ * screen - which is the same invariant the markdown layout keeps, for the same
+ * reason. Long lines are clipped, and the file is there to be read rather than
+ * edited.
+ */
+
+export interface FileDiffProps extends BoxProps {
+  /** The file, as the changeset names it. */
+  path: string;
+  diff: DiffResult;
+  /** Absent `before` is a creation, absent `after` a deletion. */
+  kind: 'new' | 'edited' | 'deleted';
+  /** Set instead of a diff when the bytes are not text. */
+  binary?: { bytes: number; contentType?: string };
+}
+
+export const FileDiff: (props: FileDiffProps) => RenderOutput =
+  defineComponent<FileDiffProps>('FileDiff', (props) => {
+    const { path, diff, kind, binary, ...rest } = props;
+    const theme = useTheme();
+
+    if (binary) {
+      return (
+        <EmptyState
+          title="Not text"
+          message={`${binary.contentType ?? 'Binary'}, ${binary.bytes} bytes. There is nothing to show a line at a time.`}
+          {...rest}
+        />
+      );
+    }
+
+    if (diff.tooLarge) {
+      return (
+        <EmptyState
+          title="Too big to line up"
+          message={`${diff.tooLarge.lines} lines between the two sides, over the ${diff.tooLarge.limit} this will compare. Open it in an editor.`}
+          {...rest}
+        />
+      );
+    }
+
+    if (diff.rows.length === 0) {
+      return <EmptyState title="Nothing between the two" message="Both sides of this file are the same." {...rest} />;
+    }
+
+    // The widest line number either side will need, so the gutter does not
+    // change width partway down the file.
+    const width = String(Math.max(
+      ...diff.rows.map((row) => Math.max(row.before ?? 0, row.after ?? 0)),
+    )).length;
+
+    return (
+      <Column {...rest}>
+        <Row gap={1}>
+          <text
+            content={kind === 'new' ? '+' : kind === 'deleted' ? '-' : theme.glyphs.chevronRight}
+            fg={kind === 'new' ? 'success' : kind === 'deleted' ? 'danger' : 'muted'}
+            shrink={0}
+          />
+          <text content={path} flex={1} truncate="start" />
+          <text content={`+${diff.added}`} fg="success" shrink={0} />
+          <text content={`-${diff.removed}`} fg="danger" shrink={0} />
+        </Row>
+
+        <ScrollView flex={1} focusId="changes.file">
+          <Column>
+            {diff.rows.map((row, index) => (
+              <Row key={index} gap={1}>
+                {/* Both gutters, always. A single number that means the left
+                    file on one row and the right on the next is a number
+                    nobody can use to find anything. */}
+                <text
+                  content={String(row.before ?? '').padStart(width)}
+                  fg="subtle"
+                  shrink={0}
+                />
+                <text
+                  content={String(row.after ?? '').padStart(width)}
+                  fg="subtle"
+                  shrink={0}
+                />
+                <text
+                  content={row.kind === 'added' ? '+' : row.kind === 'removed' ? '-' : ' '}
+                  fg={row.kind === 'added' ? 'success' : row.kind === 'removed' ? 'danger' : 'muted'}
+                  shrink={0}
+                />
+                <text
+                  content={row.text}
+                  wrap="none"
+                  truncate="end"
+                  flex={1}
+                  {...(row.kind === 'added'
+                    ? { fg: 'success' as const }
+                    : row.kind === 'removed'
+                      ? { fg: 'danger' as const }
+                      : {})}
+                />
+              </Row>
+            ))}
+          </Column>
+        </ScrollView>
+      </Column>
+    );
+  });