@textui/core 0.7.0 → 0.9.0

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,