@textui/core 0.6.1 → 0.8.0

package/src/core/focus.ts

@@ -223,12 +223,29 @@ export class Focus implements FocusManager {
         return (n.scopeId ?? GLOBAL_SCOPE) === scope;
       });
 
-    return candidates
-      .map((n, i) => ({ n, i }))
+    // A tree is placed where its first control registered, and its controls
+    // by where they sit in it. Registration order alone put a control that
+    // mounted late - a field a choice revealed - after everything that was
+    // already there, however far up the form it is drawn.
+    const firstOf = new Map<unknown, number>();
+    const entries = candidates.map((n, i) => {
+      const place = n.place?.();
+      const root = place ? place.root : n;
+      if (!firstOf.has(root)) firstOf.set(root, i);
+      return { n, i, root, path: place?.path };
+    });
+
+    return entries
       .sort((a, b) => {
         const ao = a.n.order ?? Number.MAX_SAFE_INTEGER;
         const bo = b.n.order ?? Number.MAX_SAFE_INTEGER;
-        return ao === bo ? a.i - b.i : ao - bo;
+        if (ao !== bo) return ao - bo;
+        if (a.root !== b.root) return (firstOf.get(a.root) as number) - (firstOf.get(b.root) as number);
+        if (a.path && b.path) {
+          const by = comparePaths(a.path, b.path);
+          if (by !== 0) return by;
+        }
+        return a.i - b.i;
       })
       .map((e) => e.n.id);
   }
@@ -367,3 +384,13 @@ export class Focus implements FocusManager {
 export function createFocus(onChange?: () => void): Focus {
   return new Focus(onChange);
 }
+
+/** Document order of two places in one tree; an ancestor comes first. */
+function comparePaths(a: number[], b: number[]): number {
+  const length = Math.min(a.length, b.length);
+  for (let i = 0; i < length; i++) {
+    const by = (a[i] as number) - (b[i] as number);
+    if (by !== 0) return by;
+  }
+  return a.length - b.length;
+}

package/src/core/i18n.ts

@@ -57,18 +57,22 @@ export class I18nRegistry implements I18n {
     return [...this.bundles.keys()];
   }
 
-  /** Missing keys fall through to the fallback locale, then to the key. */
-  t(key: string, values?: Record<string, unknown>): string {
+  /**
+   * Missing keys fall through to the base language, then the fallback locale,
+   * then `fallback`, then the key.
+   */
+  t(key: string, values?: Record<string, unknown>, fallback?: string): string {
     const primary = this.bundles.get(this.locale);
     const base = this.locale.includes('-')
       ? this.bundles.get(this.locale.split('-')[0] as string)
       : undefined;
-    const fallback = this.bundles.get(this.fallbackLocale);
+    const secondary = this.bundles.get(this.fallbackLocale);
 
     const template =
       (primary && lookup(primary, key)) ??
       (base && lookup(base, key)) ??
-      (fallback && lookup(fallback, key)) ??
+      (secondary && lookup(secondary, key)) ??
+      fallback ??
       key;
 
     return values ? interpolate(template, values) : template;
@@ -90,10 +94,10 @@ export class I18nRegistry implements I18n {
     return new Intl.ListFormat(this.locale, options).format(items);
   }
 
-  plural(count: number, forms: Record<string, string>): string {
+  plural(count: number, forms: Record<string, string>, values?: Record<string, unknown>): string {
     const rule = new Intl.PluralRules(this.locale).select(count);
     const template = forms[rule] ?? forms.other ?? '';
-    return interpolate(template, { count });
+    return interpolate(template, { ...values, count });
   }
 
   onChange(fn: (locale: LocaleId) => void): Disposable {

package/src/jsx/intrinsics.ts

@@ -24,6 +24,31 @@ export interface BaseProps extends Style {
   disabled?: boolean;
   selected?: boolean;
 
+  /**
+   * The states this node is in, for `style` overlays and for a theme.
+   *
+   * `focused` is a tri-state on purpose. Left out, the runtime asks the focus
+   * manager - which is right for a control and wrong for a row: a list row does
+   * not hold the keyboard, the list does. A row that has to be told so, or the
+   * distinction between "this is the current row" and "this is the current row
+   * and you can type at it" cannot be drawn at all.
+   */
+  focused?: boolean;
+
+  /**
+   * Which of the component's boxes a theme styles.
+   *
+   * A composite component draws plain `box` nodes, so without this its entry
+   * in a theme's `components` map is a key nothing reads - a list row is a
+   * `box`, and `components.List.selected` is what a theme author would reach
+   * for. The name has to be stated by the component that owns the box, which
+   * is the only place that knows what the row is part of.
+   *
+   * Omitted, the node is styled under its own host name, so `components.box`
+   * and a `variant` keep working exactly as they did.
+   */
+  styleAs?: string;
+
   /** Participates in tab order. Implied by an interactive role. */
   focusable?: boolean;
   /** The focus scope this node belongs to. */

package/src/runtime/hooks.ts

@@ -556,6 +556,20 @@ export function focusScopeOf(instance: Instance): string | undefined {
   return typeof found === 'string' ? found : undefined;
 }
 
+/** Where an instance sits: its root, and its child index at each level. */
+function placeOf(instance: Instance): { root: unknown; path: number[] } | undefined {
+  const path: number[] = [];
+  let cursor = instance;
+  while (cursor.parent) {
+    const at = cursor.parent.children.indexOf(cursor);
+    // Rendered but not yet adopted, or already dropped: no place to answer.
+    if (at < 0) return undefined;
+    path.unshift(at);
+    cursor = cursor.parent;
+  }
+  return { root: cursor, path };
+}
+
 export function useFocus(options: UseFocusOptions = {}): FocusHandle {
   const instance = currentInstance();
   const runtime = instance.runtime;
@@ -575,6 +589,7 @@ export function useFocus(options: UseFocusOptions = {}): FocusHandle {
       skipTab: options.skipTab,
       order: options.order,
       scopeId,
+      place: () => placeOf(instance),
       onFocus: () => {
         invalidate(instance, 'focus');
         options.onFocus?.();

package/src/runtime/paint.ts

@@ -12,7 +12,7 @@ import type { Buffer } from '../render/buffer.js';
 import { COLOR_DEFAULT, mix, packColor, type PackedColor } from '../render/color.js';
 import { rectIntersect } from '../types/geometry.js';
 import {
-  graphemes, graphemeWidth, isAscii, sanitize, stringWidth, truncate,
+  graphemes, graphemeWidth, isAscii, markCut, sanitize, stringWidth, truncate,
   truncateSideOf, wrapModeOf, wrapText,
 } from '../util/text.js';
 import {
@@ -751,7 +751,16 @@ function paintText(
 
   for (let i = 0; i < raw.length && i < area.height; i++) {
     let line = raw[i] as string;
-    if (stringWidth(line) > area.width) {
+    // The last line the box has room for is cut when the text goes on past
+    // it, exactly as a line too wide for the box is. Without this a wrapped
+    // paragraph with more to say stopped mid-sentence and read as the whole
+    // of it, which is the failure `truncate` exists to prevent sideways.
+    const stopped = i === area.height - 1 && raw.length > area.height;
+    if (stopped) {
+      // The last row it has room for, with more to say: always marked, since
+      // the row itself may fit to the cell.
+      line = truncateSide === false ? line : markCut(line, area.width, ellipsis);
+    } else if (stringWidth(line) > area.width) {
       line = truncateSide === false
         ? line
         : truncate(line, area.width, ellipsis, truncateSide ?? 'end');

package/src/runtime/style.ts

@@ -1,4 +1,4 @@
-import type { Style, StatefulStyle, StyleInput, BorderSpec, BorderStyle, StyleColor } from '../types/style.js';
+import type { Style, StatefulStyle, StyleInput, BorderSpec, BorderColor, BorderStyle, StyleColor, StateName } from '../types/style.js';
 import type { ResolvedTheme } from '../types/theme.js';
 import type { Edges } from '../types/geometry.js';
 import type { Color } from '../types/cells.js';
@@ -31,6 +31,7 @@ export const STYLE_KEYS = new Set<string>([
 export interface InteractionState {
   focused: boolean;
   hovered: boolean;
+  /** Pressed. Not a selection - that is `selected`. */
   active: boolean;
   selected: boolean;
   disabled: boolean;
@@ -40,6 +41,37 @@ export const NO_INTERACTION: InteractionState = {
   focused: false, hovered: false, active: false, selected: false, disabled: false,
 };
 
+/**
+ * The states, least to most specific - the order the last one wins.
+ *
+ * `flattenStyleInput` merges a `style` prop in this order and so does a
+ * theme's per-component map, which is the only way the two can be made to
+ * agree: a theme states `focus` over `selected` and gets the same answer
+ * whether the state came from the node or from the theme. `hovered` is the
+ * state; `hover` is the name it wears, which is why this is the one place
+ * that has to know the difference.
+ */
+const STATE_ORDER: readonly (keyof InteractionState)[] = [
+  'selected', 'hovered', 'active', 'focused', 'disabled',
+];
+
+const STATE_VARIANT: Record<keyof InteractionState, StateName> = {
+  selected: 'selected',
+  hovered: 'hover',
+  active: 'active',
+  focused: 'focus',
+  disabled: 'disabled',
+};
+
+/** The names of the states that are true, in the order the last one wins. */
+export function stateVariants(state: InteractionState): StateName[] {
+  const out: StateName[] = [];
+  for (const key of STATE_ORDER) {
+    if (state[key]) out.push(STATE_VARIANT[key]);
+  }
+  return out;
+}
+
 function isStateful(value: Style | StatefulStyle): value is StatefulStyle {
   return (
     'base' in value || 'focus' in value || 'hover' in value ||
@@ -68,6 +100,7 @@ export function flattenStyleInput(input: StyleInput | undefined, state: Interact
 
   // Order matters: selected loses to active, active loses to focus, and
   // disabled wins over everything - a disabled control is not focusable.
+  // The same order `stateVariants` gives a theme, so the two cannot disagree.
   return mergeStyles(
     input.base,
     state.selected ? input.selected : undefined,
@@ -94,13 +127,37 @@ export function resolveStyle(
   defaultStyle: Style | undefined,
   state: InteractionState,
 ): Style {
-  const variants: string[] = [];
-  if (typeof props.variant === 'string') variants.push(props.variant);
-  if (typeof props.tone === 'string') variants.push(props.tone);
-  if (typeof props.size === 'string') variants.push(props.size);
+  const qualifiers: string[] = [];
+  if (typeof props.variant === 'string') qualifiers.push(props.variant);
+  if (typeof props.tone === 'string') qualifiers.push(props.tone);
+  if (typeof props.size === 'string') qualifiers.push(props.size);
+  const variants: string[] = [...qualifiers];
+
+  // The states join last, so a theme's entry for one of them wins over the
+  // same name used as a variant - `List.focused` is the fill on the row the
+  // keyboard is on, and a `focused` variant means nothing else.
+  //
+  // Each state is also offered qualified by each of the props-driven names,
+  // immediately after the flat one, for the case the flat name cannot say:
+  // whether a state paints at all is sometimes a property of a variant rather
+  // than of the state. A solid tab is filled and an underline one is not, and
+  // `Tabs.selected` has to mean the pair for both while `Tabs.solid.selected`
+  // is the one that adds the fill. The qualified name merges last and the
+  // order between the states is unchanged, so `disabled` still wins over
+  // everything and `focus` still wins over `selected`.
+  for (const name of stateVariants(state)) {
+    variants.push(name);
+    for (const qualifier of qualifiers) variants.push(`${qualifier}.${name}`);
+  }
+
+  // `styleAs` is how a component says which of its boxes a theme styles. A
+  // list draws its rows as plain `box` nodes, so without it `components.List`
+  // would be a key nothing ever reads - which is what every `components` entry
+  // written for a composite component was until this.
+  const owner = typeof props.styleAs === 'string' ? props.styleAs : component;
 
   return mergeStyles(
-    theme.styleFor(component, variants),
+    theme.styleFor(owner, variants),
     defaultStyle,
     styleFromProps(props),
     flattenStyleInput(props.style as StyleInput | undefined, state),
@@ -109,7 +166,13 @@ export function resolveStyle(
 
 // ------------------------------------------------------------------ colour
 
-/** A token name, a literal colour, or nothing. */
+/**
+ * A token name, a literal colour, or nothing.
+ *
+ * Takes the whole union because it is the one place a colour is turned into
+ * a cell value: the narrowing happened at the field that named it, which is
+ * where the mistake is made and where the error belongs.
+ */
 export function resolveColor(
   value: StyleColor | undefined,
   theme: ResolvedTheme,
@@ -119,6 +182,7 @@ export function resolveColor(
   return theme.color(value as string);
 }
 
+/** Pack a colour for a cell, at the caller's own channel. */
 export function packStyleColor(
   value: StyleColor | undefined,
   theme: ResolvedTheme,
@@ -144,9 +208,9 @@ export function attrsFromStyle(style: Style): number {
 export interface ResolvedBorder {
   style: BorderStyle;
   chars: BorderChars;
-  color: StyleColor | undefined;
+  color: BorderColor | undefined;
   /** Per-edge overrides. Undefined here means "use `color`". */
-  colors: { top?: StyleColor; right?: StyleColor; bottom?: StyleColor; left?: StyleColor };
+  colors: { top?: BorderColor; right?: BorderColor; bottom?: BorderColor; left?: BorderColor };
   dim: boolean;
   sides: { top: boolean; right: boolean; bottom: boolean; left: boolean };
   edges: Edges;

package/src/themes/builtin.ts

@@ -1,3 +1,4 @@
+import type { Style } from '../types/style.js';
 import type { ThemeDefinition } from '../types/theme.js';
 
 /**
@@ -10,6 +11,72 @@ import type { ThemeDefinition } from '../types/theme.js';
  * difference lives here, in border style and density, not in the catalog.
  */
 
+/**
+ * A selection, in the two states it has.
+ *
+ * `selected` is "this is the current one" and `focus` is the same row while
+ * the component holds the keyboard, so a theme states the bright fill once and
+ * the dimmer one for everything the reader has walked away from. They were one
+ * name once - `active` meant both this and pressed - and a word that means two
+ * things gets filled with either.
+ *
+ * Both name tokens rather than colours, which is the point of the whole
+ * arrangement: retint the palette and every component that has not said
+ * otherwise moves with it, while a theme that states `components.List.focused`
+ * moves the list and leaves the table where it was.
+ */
+const SELECTION_FOCUSED: Style = { bg: 'selected', fg: 'onSelected', dim: true };
+const SELECTION_UNFOCUSED: Style = { bg: 'active', fg: 'onActive' };
+const SELECTION_HOVER: Style = { bg: 'hover', fg: 'onActive' };
+// The other way to draw a selection: reverse video, which is legible whatever
+// a theme's own two colours are. Left beside the three above while that is
+// decided - nothing reads them yet.
+// const SELECTION_DEFAULT: Style = { bg: 'default', fg: 'default', inverse: true };
+// const SELECTION_DIMMED: Style = { bg: 'default', fg: 'default', inverse: true, dim: true };
+
+/**
+ * The state colours every built-in theme starts from.
+ *
+ * Stated once and spread into `dark` and `light` because a theme that
+ * extends either inherits it whole: the entries name tokens, so `console`
+ * keeps its own `selected` and gets its own fills, without restating a single
+ * component. That is also what makes them the *defaults* - a theme states
+ * `components` to differ, and says nothing here about what it does not.
+ */
+const STATE_STYLES: ThemeDefinition['components'] = {
+  List: { selected: SELECTION_UNFOCUSED, focus: SELECTION_FOCUSED },
+  Tree: { selected: SELECTION_UNFOCUSED, focus: SELECTION_FOCUSED },
+  Table: { selected: SELECTION_UNFOCUSED, focus: SELECTION_FOCUSED },
+  // The field's own selection, over the text it covers. Same pair, same
+  // reason: a selection left visible in an unfocused field says what is on
+  // the clipboard, and saying it as loudly as the live one would put two
+  // selections on the screen.
+  TextArea: { selected: SELECTION_UNFOCUSED, focus: SELECTION_FOCUSED },
+  // A marked line is a selection. The caret line is that selection plus the
+  // keyboard, so it takes the next fill up rather than a colour of its own.
+  CodeViewer: { selected: SELECTION_UNFOCUSED, focus: SELECTION_HOVER },
+  Menu: { selected: SELECTION_UNFOCUSED, focus: SELECTION_FOCUSED },
+  // A tab is open, not selected. Dimming it when the strip does not have the
+  // keyboard would say no document is open, which is a different claim and a
+  // wrong one - so it has one state and no second.
+  //
+  // Whether a tab is *filled* is a property of the variant rather than of the
+  // state: a solid tab is, an underline one is not. So the pair is stated for
+  // the state and the fill only for the variant that has one.
+  Tabs: { selected: { fg: 'onSelected' }, 'solid.selected': SELECTION_FOCUSED },
+  // The chat rows take the same fills, and for the same reason. `ToolCallRow`
+  // and `ReasoningBlock` are selections in a transcript that the caller
+  // names, so they have `selected` and no `focus`; a `ComposerChip` lights up
+  // only while it holds the keyboard, so it has `focus` and no `selected`.
+  ToolCallRow: { selected: SELECTION_FOCUSED },
+  ReasoningBlock: { selected: SELECTION_FOCUSED },
+  ComposerChip: { focus: SELECTION_FOCUSED },
+  // A range in a document is a selection, and it keeps the colours the text
+  // under it was already drawn in - the syntax of a selection is the syntax of
+  // the code it covers.
+  Editor: { selected: { bg: 'active' } },
+};
+
 export const DARK: ThemeDefinition = {
   id: 'dark',
   name: 'Dark',
@@ -55,6 +122,7 @@ export const DARK: ThemeDefinition = {
     shadow: '#010409',
   },
   spacing: { none: 0, xs: 0, sm: 1, md: 1, lg: 2, xl: 3 },
+  components: { ...STATE_STYLES },
 };
 
 export const LIGHT: ThemeDefinition = {
@@ -93,7 +161,7 @@ export const LIGHT: ThemeDefinition = {
     onWarning: '#ffffff',
     onDanger: '#ffffff',
     hover: '#eaeef2',
-    active: '#dbeafe',
+    active: '#a5bdd8',
     selected: '#0969da',
     focus: '#0969da',
     disabled: '#8c959f',
@@ -102,6 +170,7 @@ export const LIGHT: ThemeDefinition = {
     shadow: '#d0d7de',
   },
   spacing: { none: 0, xs: 0, sm: 1, md: 1, lg: 2, xl: 3 },
+  components: { ...STATE_STYLES },
 };
 
 /** Dense, bordered, high contrast. Every region is a labelled box. */
@@ -127,7 +196,9 @@ export const CONSOLE: ThemeDefinition = {
     //
     // The two selection backgrounds are picked rather than derived: `selected`
     // carries `inverted` text so it has to be light, and `active` carries
-    // `text` so it has to be dark. Same hue, opposite ends.
+    // `text` so it has to be dark. Same hue, opposite ends. `active` is what
+    // a selection looks like when the component does not have the keyboard -
+    // it is the dim end of the pair, not a pressed control.
     primary: '#88c0d0',
     info: '#88c0d0',
     selected: '#6ba3b2',
@@ -172,6 +243,7 @@ export const PAPER: ThemeDefinition = {
     warning: '#d29922',
     danger: '#f85149',
     info: '#58a6ff',
+    /* ---- */
     onAccent: '#0d1117',
     onDefault: '#0d1117',
     onPrimary: '#0d1117',
@@ -181,17 +253,23 @@ export const PAPER: ThemeDefinition = {
     onInfo: '#0d1117',
     onWarning: '#0d1117',
     onDanger: '#0d1117',
+    /* ---- */
     hover: '#1f2937',
-    active: '#264466',
-    selected: '#1f6feb',
+    active: 'default',
+    onActive: '#3191ff',
+    selected: 'default',
+    onSelected: '#58a6ff',
     focus: '#58a6ff',
     disabled: '#484f58',
+
+    /* ---- */
     scrim: '#010409',
     cursor: 'default',
     shadow: '#010409',
   },
   spacing: { none: 0, xs: 1, sm: 1, md: 2, lg: 3, xl: 4 },
   components: {
+    ...STATE_STYLES,
     Panel: { base: { border: 'none', padding: [1, 2] } },
     Button: { base: { padding: [0, 2] } },
   },
@@ -263,6 +341,9 @@ export const WORKBENCH: ThemeDefinition = {
     hover: '#313244',
     active: '#45475a',
     selected: '#585b70',
+    // The selection is a mid grey, so the light text is what reads on it; the
+    // inherited `inverted` is darker than the fill and nearly disappears.
+    onSelected: '#cdd6f4',
     focus: '#89b4fa',
     scrim: '#11111b',
   },
@@ -276,7 +357,12 @@ export const MONO: ThemeDefinition = {
   id: 'mono',
   name: 'Monochrome',
   appearance: 'dark',
+  // The theme's own colours are all `default`; this is what makes that true of
+  // the ones a component states for itself, which is the difference between a
+  // palette that happens to be grey and a theme with no colour in it.
+  monochrome: true,
   border: 'ascii',
+  // border: 'none',
   cursor: 'underline',
   // Chosen, not downgraded to: this theme is ascii on a terminal that could
   // draw anything, so the rule has to say so too.
@@ -317,6 +403,21 @@ export const MONO: ThemeDefinition = {
     cursor: 'default',
     shadow: 'default',
   },
+  components: {
+    List: { selected: { bold: true }, focus: { bold: true } },
+    Tree: { selected: { bold: true }, focus: { bold: true } },
+    Table: { selected: { bold: true }, focus: { bold: true } },
+    TextArea: { selected: { bold: true }, focus: { bold: true } },
+    CodeViewer: { selected: { bold: true }, focus: { bold: true } },
+    Menu: { selected: { bold: true }, focus: { bold: true } },
+    Tabs: { selected: { bold: true }, 'solid.selected': { bold: true } },
+    ToolCallRow: { selected: { bold: true } },
+    ReasoningBlock: { selected: { bold: true } },
+    ComposerChip: { focus: { bold: true } },
+    Editor: { selected: { bold: true } },
+    Panel: { base: { border: 'ascii', padding: [0, 1] } },
+    Button: { base: { padding: [0, 1] } },
+  }
 };
 
 /**

package/src/themes/registry.ts

@@ -24,6 +24,7 @@ const FALLBACK_COLORS: Record<ColorToken, Color> = {
   onDefault: 'default', onMuted: 'default',
   onAccent: 'default', onPrimary: 'default', onSecondary: 'default',
   onSuccess: 'default', onWarning: 'default', onDanger: 'default', onInfo: 'default',
+  onSelected: 'default', onActive: 'default',
   hover: 'default', active: 'default', selected: 'default', focus: 'default',
   disabled: 'default', scrim: 'default', cursor: 'default', shadow: 'default',
 };
@@ -125,6 +126,7 @@ export class Themes implements ThemeRegistry {
     // opts in rather than out.
     let tableRules: TableRules = 'header';
     let density: Density = 'normal';
+    let monochrome = false;
     const components: Record<string, Record<string, Style>> = {};
     let syntaxOverrides: Partial<Record<SyntaxScope, StyleColor>> = {};
 
@@ -155,11 +157,27 @@ export class Themes implements ThemeRegistry {
       if (def.cursor) cursorStyle = def.cursor;
       if (def.tableRules) tableRules = def.tableRules;
       if (def.density) density = def.density;
+      if (def.monochrome !== undefined) monochrome = def.monochrome;
       for (const [name, variants] of Object.entries(def.components ?? {})) {
         components[name] = { ...components[name], ...variants };
       }
     }
 
+    // What is written on a filled row, derived rather than restated.
+    //
+    // A selection background is only half a pair: `selected` carries
+    // `inverted` and `active` carries `text`. Stated as two independent
+    // colours, a theme that restates one half - `paper-light` restates
+    // `inverted`, `paper` leaves `text` as the terminal's - would take the
+    // other half from the theme it extends, or from the terminal, and a row
+    // could come out unreadable with nothing in the theme saying so.
+    //
+    // So the pair follows the theme's own values unless it says otherwise. A
+    // theme that wants a different colour on a fill states it, which is what
+    // `paper` does for `active`.
+    if (colors.onSelected === 'default') colors.onSelected = colors.inverted;
+    if (colors.onActive === 'default') colors.onActive = colors.text;
+
     // A colourless terminal gets no colour, whatever the theme says.
     if (caps.colorDepth === 0) {
       for (const token of Object.keys(colors) as ColorToken[]) {
@@ -190,6 +208,7 @@ export class Themes implements ThemeRegistry {
       id: leaf.id,
       name: leaf.name,
       appearance: leaf.appearance,
+      monochrome,
       colors,
       spacing,
       glyphs,
@@ -202,6 +221,10 @@ export class Themes implements ThemeRegistry {
       syntax,
 
       color(token: string): Color {
+        // A monochrome theme has no colour to give, and that has to include the
+        // literal a component states for itself - otherwise the one theme whose
+        // whole point is no colour is the one that cannot promise it.
+        if (monochrome) return 'default';
         if (token in colors) return colors[token as ColorToken] as Color;
         // Not a token: a literal colour passed straight through.
         return token as Color;

package/src/types/focus.ts

@@ -25,6 +25,14 @@ export interface FocusableOptions {
   id: string;
   /** Explicit order within the scope. Unset = document order. */
   order?: number;
+  /**
+   * Where the focusable sits in the tree, asked each time the tab order is.
+   *
+   * `root` is the tree it is in and `path` the child index at each level
+   * below it. Left off, or answering `undefined`, the focusable is placed by
+   * when it registered.
+   */
+  place?(): { root: unknown; path: number[] } | undefined;
   disabled?: boolean;
   /** Skipped by tab, still reachable by directional navigation and click. */
   skipTab?: boolean;

package/src/types/i18n.ts

@@ -13,13 +13,24 @@ export interface I18n {
   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;
+  /**
+   * Missing keys fall back to the fallback locale, then to `fallback` (the
+   * text a component draws when nobody translated it), then to the key itself.
+   */
+  t(key: string, values?: Record<string, unknown>, fallback?: string): 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;
+  /**
+   * The form the locale's plural rules pick for `count`, with `{count}` and
+   * anything the sentence needs around it.
+   *
+   * `values` carries what else the form names - a limit, a glyph, the total a
+   * count is out of - because a sentence that inflects a noun is the whole
+   * sentence and not a noun with a number in front of it.
+   */
+  plural(count: number, forms: Record<string, string>, values?: Record<string, unknown>): string;
   onChange(fn: (locale: LocaleId) => void): Disposable;
 }