@textui/core 0.7.0 → 0.8.0

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/i18n.ts

@@ -23,6 +23,14 @@ export interface I18n {
   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;
 }

package/src/types/style.ts

@@ -2,23 +2,77 @@ import type { Color } from './cells.js';
 import type { EdgeSpec } from './geometry.js';
 
 /**
- * Semantic theme tokens. A component names a role, never a colour - which is
- * what lets one catalog render the same under a light theme, a dark theme and
- * a 16-colour ssh session.
+ * Semantic theme tokens, split by the channel each one is written in.
+ *
+ * A component names a role, never a colour - which is what lets one catalog
+ * render the same under a light theme, a dark theme and a 16-colour ssh
+ * session. The role is not enough on its own, though: a token also has to be
+ * somewhere it can actually be drawn. `canvas` is a fill, `onAccent` is
+ * writing, `borderStrong` is a rule - and one union for all three is what let
+ * `fg: 'canvas'` and `border: 'onAccent'` compile, to be found by somebody
+ * looking at a frame.
+ *
+ * So each token is listed under the channels it may appear in, and `Style`
+ * takes the matching one. A token may appear in more than one - the tones are
+ * both a fill and a colour of their own - and a literal colour is the shared
+ * escape out of all three.
+ *
+ * A token missing from a list is a token that channel cannot use. Adding one
+ * is a decision about where it reads, not a convenience.
  */
-export type ColorToken =
-  | 'canvas' | 'surface' | 'surfaceAlt' | 'overlay'
-  | 'border' | 'borderStrong' | 'borderSubtle'
-  | 'text' | 'muted' | 'subtle' | 'inverted'
+
+/** Colours a cell's foreground may be. */
+export type FgColorToken =
+  // A tone is a colour in its own right as well as a fill it provides.
   | 'accent' | 'primary' | 'secondary'
   | 'success' | 'warning' | 'danger' | 'info'
+  // The states are readable as text too: a disabled label, a focus-coloured
+  // border rendered as a caption.
+  | 'hover' | 'active' | 'selected' | 'focus' | 'disabled'
+  | 'text' | 'muted' | 'subtle' | 'inverted'
+  // A quiet rule is also the quietest text there is.
+  | 'borderSubtle'
+  // The caret is the one token that is honestly both: an underline caret is
+  // drawn in the foreground, and a block caret is the foreground swapped, so
+  // both halves are reached by naming it here.
+  | 'cursor'
   | 'onDefault' | 'onMuted'
   | 'onAccent' | 'onPrimary' | 'onSecondary'
   | 'onSuccess' | 'onWarning' | 'onDanger' | 'onInfo'
+  | 'onSelected' | 'onActive';
+
+/** Colours a cell's background may be. */
+export type BgColorToken =
+  | 'canvas' | 'surface' | 'surfaceAlt' | 'overlay'
   | 'hover' | 'active' | 'selected' | 'focus' | 'disabled'
-  | 'scrim' | 'cursor' | 'shadow' | 'divider';
+  | 'accent' | 'primary' | 'secondary'
+  | 'success' | 'warning' | 'danger' | 'info'
+  // What is over everything, what the caret is, and what a shadow is.
+  | 'scrim' | 'cursor' | 'shadow';
+
+/** Colours a rule may be. */
+export type BorderColorToken =
+  | 'border' | 'borderStrong' | 'borderSubtle' | 'divider'
+  | 'accent' | 'primary' | 'secondary'
+  | 'success' | 'warning' | 'danger' | 'info'
+  | 'hover' | 'focus'
+  // A quiet rule and a quiet label are the same two colours often enough that
+  // a frame drawn in `muted` is a line somebody means, not a mistake. What is
+  // refused here is the loud end of the foreground list: a rule in `text` or
+  // in an `on*` token is writing used as structure.
+  | 'muted' | 'subtle';
+
+/** Every token, for the places that take a colour without saying which. */
+export type ColorToken = FgColorToken | BgColorToken | BorderColorToken;
 
-/** Anywhere a colour is accepted, a semantic token is accepted too. */
+/** A foreground: an `FgColorToken`, or a literal colour. */
+export type FgColor = FgColorToken | Color;
+/** A background: a `BgColorToken`, or a literal colour. */
+export type BgColor = BgColorToken | Color;
+/** A rule: a `BorderColorToken`, or a literal colour. */
+export type BorderColor = BorderColorToken | Color;
+
+/** Anywhere a colour is accepted, any token and any literal are accepted too. */
 export type StyleColor = ColorToken | Color;
 
 export type Dimension = number | `${number}%` | 'auto';
@@ -86,17 +140,17 @@ export type BorderSides = {
 
 /** A colour per edge. Unnamed edges fall back to the border's `color`. */
 export type BorderColors = {
-  top?: StyleColor;
-  right?: StyleColor;
-  bottom?: StyleColor;
-  left?: StyleColor;
+  top?: BorderColor;
+  right?: BorderColor;
+  bottom?: BorderColor;
+  left?: BorderColor;
 };
 
 export type BorderSpec =
   | BorderStyle
   | {
       style?: BorderStyle;
-      color?: StyleColor;
+      color?: BorderColor;
       /**
        * Per-edge colour, over `color`. A corner belongs to the edge that runs
        * through it - the top rule owns both top corners - because a cell holds
@@ -143,7 +197,7 @@ export interface Style {
    * but stays legible, rather than being replaced by a rectangle of nothing.
    * `true` uses the theme's `scrim` token; a number sets the strength.
    */
-  scrim?: boolean | StyleColor;
+  scrim?: boolean | BgColor;
   scrimStrength?: number;
 
   // --- box ---
@@ -196,8 +250,8 @@ export interface Style {
   overflowY?: Overflow;
 
   // --- paint ---
-  fg?: StyleColor;
-  bg?: StyleColor;
+  fg?: FgColor;
+  bg?: BgColor;
   bold?: boolean;
   dim?: boolean;
   italic?: boolean;
@@ -214,16 +268,29 @@ export interface Style {
   fill?: string;
 }
 
-/** Styles selected by interaction state. Merged over the base in this order. */
+/**
+ * Styles selected by interaction state. Merged over the base in this order.
+ *
+ * `selected` is "this is the current one"; `focus` is "and the keyboard is
+ * here", so a row that has both wears `focus` and a row that has only the
+ * first wears the dimmer `selected`. They are separate names because they
+ * were the same word once - `active` meant both the unfocused selection here
+ * and the pressed state in `InteractionState` - and a token that meant two
+ * things could be filled with either and looked wrong half the time.
+ */
 export interface StatefulStyle {
   base?: Style;
   focus?: Style;
   hover?: Style;
+  /** Pressed. Never a selection. */
   active?: Style;
   selected?: Style;
   disabled?: Style;
 }
 
+/** The states, in the order the last one wins. The shared vocabulary. */
+export type StateName = 'selected' | 'hover' | 'active' | 'focus' | 'disabled';
+
 export type StyleInput = Style | StatefulStyle | (Style | StatefulStyle | undefined | false)[];
 
 /** Global semantic variants, available to every component that opts in. */

package/src/types/theme.ts

@@ -77,6 +77,16 @@ export interface ThemeDefinition {
   id: string;
   name: string;
   appearance: 'light' | 'dark';
+  /**
+   * Whether this theme has any colour to give.
+   *
+   * A theme's palette is its own business, but a component can state a literal
+   * colour - an ink, a chart, a hand-picked hex - and that used to come through
+   * untouched, so `mono` painted a rainbow the moment a banner asked for one.
+   * Stated, every colour resolves to the terminal's own: tokens and literals
+   * alike, which is what a theme that says it has no colour has to mean.
+   */
+  monochrome?: boolean;
   /** Extend another registered theme; only the differences need stating. */
   extends?: string;
   colors: Partial<Record<ColorToken, Color>>;
@@ -105,7 +115,16 @@ export interface ThemeDefinition {
    */
   tableRules?: TableRules;
   density?: Density;
-  /** Per-component style overrides, keyed by component name then variant. */
+  /**
+   * Per-component style overrides, keyed by component name then variant or
+   * state.
+   *
+   * A composite component has to name which of its boxes this is - a list row
+   * is a `box` node, and `List` is what a theme author knows it by - so the
+   * name is stated at the node with `styleAs` and the map is keyed by it.
+   * `base` is the component at rest; the rest are the variants it supports and
+   * the five states in `StateName`.
+   */
   components?: Record<string, Record<string, Style>>;
   /**
    * Colours for syntax scopes. Every scope has a default drawn from the
@@ -120,6 +139,8 @@ export interface ResolvedTheme {
   id: string;
   name: string;
   appearance: 'light' | 'dark';
+  /** Whether every colour this theme gives back is the terminal's own. */
+  monochrome: boolean;
   colors: Record<ColorToken, Color>;
   spacing: ThemeSpacing;
   glyphs: ThemeGlyphs;
@@ -131,11 +152,24 @@ export interface ResolvedTheme {
   components: Record<string, Record<string, Style>>;
   /** Every syntax scope, resolved to a colour. */
   syntax: Record<SyntaxScope, Color>;
-  /** Resolve a token (or pass a literal colour through). */
+  /** Resolve a token (or pass a literal colour through, unless monochrome). */
   color(token: string): Color;
   borderChars(style?: BorderStyle): BorderChars;
   dividerChars(style?: DividerStyle): DividerChars;
-  /** Component style for a name + variant list, merged in order. */
+  /**
+   * Component style for a name and a list of names to merge over it, in the
+   * order given - later names win.
+   *
+   * The names are the component's `variant`, `tone` and `size` followed by the
+   * interaction states that are true: `selected`, `hover`, `active` (pressed),
+   * `focus` and `disabled`. So `components.List.selected` is the fill on the
+   * current row, and `components.List.focused` is the brighter one on the
+   * current row while the list has the keyboard.
+   *
+   * The order is the same one `flattenStyleInput` merges a `style` prop in, so
+   * a state stated at the node and the same state stated by the theme resolve
+   * to one answer rather than to whichever happened to be asked second.
+   */
   styleFor(component: string, variants?: string[]): Style;
 }
 

package/src/util/text.ts

@@ -283,6 +283,21 @@ export function expandTabs(text: string, tabWidth = 4): string {
 
 export type TruncateSide = 'end' | 'start' | 'middle';
 
+/**
+ * Fit into `width` cells, marking the cut whether or not there was one.
+ *
+ * `truncate` marks only what it had to cut, which is right for a string that
+ * has to fit a cell. A paragraph stopped by the box rather than by its own
+ * length is the other case: its last visible row may fit exactly and still not
+ * be the end of the text, and it has to say so.
+ */
+export function markCut(text: string, width: number, ellipsis = '…'): string {
+  if (width <= 0) return '';
+  const ew = stringWidth(ellipsis);
+  if (width <= ew) return sliceByWidth(ellipsis, width);
+  return sliceByWidth(text, width - ew).trimEnd() + ellipsis;
+}
+
 /** Fit into `width` cells, marking the cut with `ellipsis`. */
 export function truncate(
   text: string,