@textui/core 0.1.0 → 0.2.0

package/src/themes/builtin.ts

@@ -24,6 +24,7 @@ export const DARK: ThemeDefinition = {
     border: '#30363d',
     borderStrong: '#484f58',
     borderSubtle: '#21262d',
+    divider: '#484f58',
     text: '#e6edf3',
     muted: '#8b949e',
     subtle: '#6e7681',
@@ -70,6 +71,7 @@ export const LIGHT: ThemeDefinition = {
     border: '#d0d7de',
     borderStrong: '#8c959f',
     borderSubtle: '#eaeef2',
+    divider: '#8c959f',
     text: '#1f2328',
     muted: '#656d76',
     subtle: '#8c959f',
@@ -115,6 +117,7 @@ export const CONSOLE: ThemeDefinition = {
     surface: '#0a0e14',
     border: '#3b4252',
     borderStrong: '#5e81ac',
+    divider: '#5e81ac',
     accent: '#88c0d0',
     text: '#d8dee9',
     muted: '#616e88',
@@ -145,6 +148,59 @@ export const CONSOLE: ThemeDefinition = {
 export const PAPER: ThemeDefinition = {
   id: 'paper',
   name: 'Paper',
+  appearance: 'dark',
+  extends: 'dark',
+  border: 'none',
+  density: 'airy',
+  colors: {
+    canvas: 'default',
+    surface: 'default',
+    surfaceAlt: 'default',
+    overlay: 'default',
+    border: 'default',
+    borderStrong: 'default',
+    borderSubtle: 'default',
+    divider: 'default',
+    text: 'default',
+    muted: '#9b949e',
+    subtle: '#a7a7a7',
+    inverted: '#0d1117',
+    accent: '#58a6ff',
+    primary: '#388bfd',
+    secondary: '#a371f7',
+    success: '#3fb950',
+    warning: '#d29922',
+    danger: '#f85149',
+    info: '#58a6ff',
+    onAccent: '#0d1117',
+    onDefault: '#0d1117',
+    onPrimary: '#0d1117',
+    onSecondary: '#0d1117',
+    onMuted: '#0d1117',
+    onSuccess: '#0d1117',
+    onInfo: '#0d1117',
+    onWarning: '#0d1117',
+    onDanger: '#0d1117',
+    hover: '#1f2937',
+    active: '#264466',
+    selected: '#1f6feb',
+    focus: '#58a6ff',
+    disabled: '#484f58',
+    scrim: '#010409',
+    cursor: 'default',
+    shadow: '#010409',
+  },
+  spacing: { none: 0, xs: 1, sm: 1, md: 2, lg: 3, xl: 4 },
+  components: {
+    Panel: { base: { border: 'none', padding: [1, 2] } },
+    Button: { base: { padding: [0, 2] } },
+  },
+};
+
+/** Borderless. Whitespace and alignment do the separating. */
+export const PAPER_LIGHT: ThemeDefinition = {
+  id: 'paper-light',
+  name: 'Paper Light',
   appearance: 'light',
   extends: 'light',
   border: 'none',
@@ -155,6 +211,7 @@ export const PAPER: ThemeDefinition = {
     surfaceAlt: '#f5f2ec',
     border: '#e5e0d8',
     borderSubtle: '#f0ece5',
+    divider: 'default',
     subtle: '#c56532',
     text: '#2b2a27',
     muted: '#7a756c',
@@ -192,6 +249,7 @@ export const WORKBENCH: ThemeDefinition = {
     overlay: '#181825',
     border: '#45475a',
     borderStrong: '#585b70',
+    divider: '#585b70',
     text: '#cdd6f4',
     muted: '#a6adc8',
     subtle: '#6c7086',
@@ -219,6 +277,10 @@ export const MONO: ThemeDefinition = {
   name: 'Monochrome',
   appearance: 'dark',
   border: 'ascii',
+  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.
+  divider: 'ascii',
   density: 'normal',
   colors: {
     canvas: 'default',
@@ -228,6 +290,7 @@ export const MONO: ThemeDefinition = {
     border: 'default',
     borderStrong: 'default',
     borderSubtle: 'default',
+    divider: 'default',
     text: 'default',
     muted: 'default',
     subtle: 'default',
@@ -277,6 +340,7 @@ export const PAPER_DARK: ThemeDefinition = {
     surfaceAlt: '#26231f',
     border: '#3a352e',
     borderSubtle: '#2a2621',
+    divider: 'default',
     subtle: '#db8c4c',
     text: '#e8e3d9',
     muted: '#9a9287',
@@ -297,5 +361,5 @@ export const PAPER_DARK: ThemeDefinition = {
 };
 
 export const BUILTIN_THEMES: ThemeDefinition[] = [
-  DARK, LIGHT, CONSOLE, PAPER, PAPER_DARK, WORKBENCH, MONO,
+  DARK, LIGHT, CONSOLE, PAPER, PAPER_LIGHT, PAPER_DARK, WORKBENCH, MONO,
 ];

package/src/themes/dividers.ts

@@ -0,0 +1,48 @@
+import type { DividerChars, DividerStyle } from '../types/style.js';
+
+/**
+ * The divider sets.
+ *
+ * A parallel to `BORDER_SETS`, and deliberately not part of it. A border is
+ * thirteen characters that only mean anything together - they enclose a box.
+ * A divider encloses nothing: it is one rule, in one direction, whose whole
+ * job is to separate. Folding it into `BorderChars` made a theme choose a
+ * frame style in order to choose a rule, so a borderless theme could not have
+ * one without every bordered component reserving a ring it never draws.
+ */
+export const DIVIDER_SETS: Record<DividerStyle, DividerChars> = {
+  none: { horizontal: ' ', vertical: ' ' },
+  single: { horizontal: '┈', vertical: '│' },
+  double: { horizontal: '═', vertical: '║' },
+  dashed: { horizontal: '┄', vertical: '┆' },
+  thick: { horizontal: '━', vertical: '┃' },
+  ascii: { horizontal: '-', vertical: '|' },
+};
+
+/** What a terminal with no box drawing gets instead. */
+const ASCII_FALLBACK: Record<DividerStyle, DividerStyle> = {
+  none: 'none',
+  single: 'ascii',
+  double: 'ascii',
+  dashed: 'ascii',
+  thick: 'ascii',
+  ascii: 'ascii',
+};
+
+/**
+ * The BMP tier has box drawing but not every weight of it: `┄` and `━` are
+ * outside it, and a missing glyph is a question mark on somebody's terminal.
+ */
+const BMP_FALLBACK: Partial<Record<DividerStyle, DividerStyle>> = {
+  dashed: 'single',
+  thick: 'single',
+};
+
+export function dividerCharsFor(
+  style: DividerStyle,
+  unicode: 'ascii' | 'bmp' | 'full',
+): DividerChars {
+  if (unicode === 'ascii') return DIVIDER_SETS[ASCII_FALLBACK[style]];
+  if (unicode === 'bmp') return DIVIDER_SETS[BMP_FALLBACK[style] ?? style];
+  return DIVIDER_SETS[style];
+}

package/src/themes/glyphs.ts

@@ -22,6 +22,8 @@ export const FULL_GLYPHS: ThemeGlyphs = {
   chevronUp: '▴',
   arrowUp: '↑',
   arrowDown: '↓',
+  arrowLeft: '←',
+  arrowRight: '→',
   ellipsis: '…',
   search: '⌕',
   radioOn: '●',
@@ -71,6 +73,8 @@ export const ASCII_GLYPHS: ThemeGlyphs = {
   chevronUp: '^',
   arrowUp: '^',
   arrowDown: 'v',
+  arrowLeft: '<',
+  arrowRight: '>',
   ellipsis: '...',
   search: '/',
   radioOn: '(*)',

package/src/themes/index.ts

@@ -1,4 +1,5 @@
 export * from './borders.js';
+export * from './dividers.js';
 export * from './glyphs.js';
 export * from './builtin.js';
 export * from './registry.js';

package/src/themes/registry.ts

@@ -2,13 +2,14 @@ import type {
   ResolvedTheme, ThemeDefinition, ThemeGlyphs, ThemeRegistry, ThemeSpacing,
 } from '../types/theme.js';
 import type { Color } from '../types/cells.js';
-import type { BorderChars, BorderStyle, ColorToken, Density, StyleColor } from '../types/style.js';
+import type { BorderChars, BorderStyle, ColorToken, CursorStyle, Density, DividerChars, DividerStyle, StyleColor, TableRules } from '../types/style.js';
 import type { Style } from '../types/style.js';
 import type { SyntaxScope } from '../types/syntax.js';
 import type { TerminalCapabilities } from '../types/capabilities.js';
 import type { Disposable } from '../types/disposable.js';
 import { toDisposable } from '../util/disposable.js';
 import { borderCharsFor } from './borders.js';
+import { dividerCharsFor } from './dividers.js';
 import { glyphsFor } from './glyphs.js';
 import { BUILTIN_THEMES } from './builtin.js';
 
@@ -16,7 +17,7 @@ const DEFAULT_SPACING: ThemeSpacing = { none: 0, xs: 0, sm: 1, md: 1, lg: 2, xl:
 
 const FALLBACK_COLORS: Record<ColorToken, Color> = {
   canvas: 'default', surface: 'default', surfaceAlt: 'default', overlay: 'default',
-  border: 'default', borderStrong: 'default', borderSubtle: 'default',
+  border: 'default', borderStrong: 'default', borderSubtle: 'default', divider: 'default',
   text: 'default', muted: 'default', subtle: 'default', inverted: 'default',
   accent: 'default', primary: 'default', secondary: 'default',
   success: 'default', warning: 'default', danger: 'default', info: 'default',
@@ -115,6 +116,14 @@ export class Themes implements ThemeRegistry {
     let spacing = { ...DEFAULT_SPACING };
     let glyphOverrides: Partial<ThemeGlyphs> = {};
     let border: BorderStyle = 'single';
+    let divider: DividerStyle = 'single';
+    // Undefined means "leave the terminal's own setting alone", which is the
+    // right default: a theme that says nothing should not restyle the caret.
+    let cursorStyle: CursorStyle | undefined;
+    // The quiet one. A rule between every pair of rows is right for a table of
+    // few, long rows and noise on a table of twenty short ones, so a theme
+    // opts in rather than out.
+    let tableRules: TableRules = 'header';
     let density: Density = 'normal';
     const components: Record<string, Record<string, Style>> = {};
     let syntaxOverrides: Partial<Record<SyntaxScope, StyleColor>> = {};
@@ -142,6 +151,9 @@ export class Themes implements ThemeRegistry {
       if (def.spacing) spacing = { ...spacing, ...def.spacing };
       if (def.glyphs) glyphOverrides = { ...glyphOverrides, ...def.glyphs };
       if (def.border) border = def.border;
+      if (def.divider) divider = def.divider;
+      if (def.cursor) cursorStyle = def.cursor;
+      if (def.tableRules) tableRules = def.tableRules;
       if (def.density) density = def.density;
       for (const [name, variants] of Object.entries(def.components ?? {})) {
         components[name] = { ...components[name], ...variants };
@@ -172,6 +184,7 @@ export class Themes implements ThemeRegistry {
 
     const glyphs: ThemeGlyphs = { ...glyphsFor(caps.unicode), ...glyphOverrides };
     const charCache = new Map<BorderStyle, BorderChars>();
+    const ruleCache = new Map<DividerStyle, DividerChars>();
 
     const resolved: ResolvedTheme = {
       id: leaf.id,
@@ -181,6 +194,9 @@ export class Themes implements ThemeRegistry {
       spacing,
       glyphs,
       border,
+      divider,
+      cursor: cursorStyle,
+      tableRules,
       density,
       components,
       syntax,
@@ -203,6 +219,18 @@ export class Themes implements ThemeRegistry {
         return chars;
       },
 
+      dividerChars(style?: DividerStyle): DividerChars {
+        const s = style ?? divider;
+        let chars = ruleCache.get(s);
+        if (!chars) {
+          const base = dividerCharsFor(s, caps.unicode);
+          const custom = leaf.dividerChars?.[s];
+          chars = custom ? { ...base, ...custom } : base;
+          ruleCache.set(s, chars);
+        }
+        return chars;
+      },
+
       styleFor(component: string, variants: string[] = []): Style {
         const entry = components[component];
         if (!entry) return {};

package/src/types/command.ts

@@ -43,6 +43,16 @@ export interface ArgSpec {
   /** Fixed choices, or a resolver for a picker. */
   choices?: ArgChoices | (() => Promise<ArgChoices> | ArgChoices);
   default?: unknown;
+  /**
+   * How the picker should lay out each choice's `description`.
+   *
+   * The argument is what knows: a list of branch names has nothing to say
+   * under each one, and a list of approval modes is *only* told apart by what
+   * is under each one. `below` gives every choice a second line, which is the
+   * only place a sentence fits - inline it shares the width with the label and
+   * every answer shows the same truncated half.
+   */
+  descriptions?: 'inline' | 'below';
 
   /**
    * Show what a choice would do, before it is chosen.
@@ -75,6 +85,13 @@ export interface CommandDefinition {
   id: string;
   title: string;
   description?: string;
+  /**
+   * The group this belongs to. The palette names it once, above the group.
+   *
+   * It is not a per-row label: repeating it beside every row spends the width
+   * the rows need for saying what they do, and still does not say where one
+   * group ends and the next begins.
+   */
   category?: string;
   icon?: string;
   /**
@@ -86,7 +103,7 @@ export interface CommandDefinition {
    */
   keepOpen?: boolean;
   /**
-   * A short state word shown beside the row, in place of the category.
+   * A short state word shown beside the row, in place of its description.
    *
    * The icon is the row's identity and should not move under the reader as
    * state changes; this is where the state goes instead.

package/src/types/input.ts

@@ -52,6 +52,15 @@ export interface MouseEvent {
   ctrl: boolean;
   alt: boolean;
   shift: boolean;
+  /**
+   * When it happened, in milliseconds.
+   *
+   * A terminal reports presses and releases and never says "double click" -
+   * there is no such thing on the wire - so telling one gesture from two is
+   * arithmetic on when they arrived and where. Stamped by whatever produced
+   * the event, which is the only thing that knows.
+   */
+  at?: number;
   handled: boolean;
 }
 

package/src/types/markdown.ts

@@ -1,4 +1,4 @@
-import type { StyleColor } from './style.js';
+import type { StyleColor, TableRules } from './style.js';
 
 /**
  * Markdown, as rows a terminal can scroll.
@@ -14,6 +14,9 @@ import type { StyleColor } from './style.js';
  * put the visible ones back into one box.
  */
 
+/** Which edge a table column's text is pushed against. */
+export type MarkdownAlign = 'left' | 'center' | 'right';
+
 /** A run of text with one style. Inline emphasis is why rows are not strings. */
 export interface MarkdownRun {
   text: string;
@@ -28,7 +31,30 @@ export type MarkdownRow =
   | { kind: 'rule' }
   | { kind: 'heading'; runs: MarkdownRun[]; level: number }
   | { kind: 'text'; runs: MarkdownRun[]; prefix?: string; prefixFg?: StyleColor; fg?: StyleColor }
-  | { kind: 'fence'; fence: number; part: 'open' | 'code' | 'close'; text?: string; language?: string };
+  | { kind: 'fence'; fence: number; part: 'open' | 'code' | 'close'; text?: string; language?: string }
+  /**
+   * One line of a table, with its cells already fitted to their columns.
+   *
+   * The widths are decided once for the whole table and repeated on every row
+   * of it, because a column that is measured per row is not a column. Cells
+   * arrive padded and truncated to exactly `widths[i]`, so a painter only has
+   * to put the separators in - which is also what keeps the one-row-per-row
+   * invariant: a cell too long for its column is cut, never wrapped, or the
+   * table would be a different height than the document said it was.
+   *
+   * `top`, `rule` and `bottom` are edges and carry no cells; the painter draws
+   * them from the widths, in whatever the theme's border characters are. They
+   * are rows here for the same reason a fence's rules are: they take a line on
+   * the screen, so anything counting rows has to be able to count them.
+   */
+  | {
+    kind: 'table';
+    table: number;
+    part: 'top' | 'head' | 'rule' | 'body' | 'bottom';
+    cells: MarkdownRun[][];
+    widths: number[];
+    align: MarkdownAlign[];
+  };
 
 export interface MarkdownLayoutOptions {
   /** Cells to wrap to. Zero means "not measured yet" - nothing is wrapped. */
@@ -44,4 +70,14 @@ export interface MarkdownLayoutOptions {
    * rules nobody draws stops two rows short of the end of the document.
    */
   ruled?: boolean;
+  /**
+   * How much of a table gets ruled. The theme's `tableRules`, passed through.
+   *
+   * It has to be decided here rather than by whatever paints the rows,
+   * because a rule between two rows *is* a row - it takes a line on the
+   * screen. A painter that added them would be drawing more lines than the
+   * layout counted, and every viewer that scrolls by row index would land in
+   * the wrong place by one per table row.
+   */
+  tableRules?: TableRules;
 }

package/src/types/style.ts

@@ -16,7 +16,7 @@ export type ColorToken =
   | 'onAccent' | 'onPrimary' | 'onSecondary'
   | 'onSuccess' | 'onWarning' | 'onDanger' | 'onInfo'
   | 'hover' | 'active' | 'selected' | 'focus' | 'disabled'
-  | 'scrim' | 'cursor' | 'shadow';
+  | 'scrim' | 'cursor' | 'shadow' | 'divider';
 
 /** Anywhere a colour is accepted, a semantic token is accepted too. */
 export type StyleColor = ColorToken | Color;
@@ -45,6 +45,38 @@ export interface BorderChars {
   teeRight: string;
 }
 
+/**
+ * A rule that separates, rather than a frame that encloses.
+ *
+ * Kept apart from `BorderStyle` on purpose: a theme that draws no frames may
+ * still want a rule, and tying the two means choosing a divider glyph decides
+ * whether every bordered component reserves a ring.
+ */
+export type DividerStyle =
+  | 'none' | 'single' | 'double' | 'dashed' | 'thick' | 'ascii';
+
+/** A divider runs either way, so it names both. */
+export interface DividerChars {
+  horizontal: string;
+  vertical: string;
+}
+
+/**
+ * The shape of the caret.
+ *
+ * Named for DECSCUSR, which is what a terminal understands, so a theme value
+ * maps straight onto the escape sequence with nothing to translate.
+ */
+export type CursorStyle = 'block' | 'underline' | 'bar';
+
+/**
+ * How much of a table gets ruled: the header only, or between every row.
+ *
+ * Not a border style - it is a question about how many lines, not which
+ * glyphs. The glyphs are the theme's border set either way.
+ */
+export type TableRules = 'header' | 'all';
+
 export type BorderSides = {
   top?: boolean;
   right?: boolean;

package/src/types/terminal.ts

@@ -1,3 +1,4 @@
+import type { CursorStyle } from './style.js';
 import type { Disposable } from './disposable.js';
 import type { Size } from './geometry.js';
 import type { TerminalCapabilities, CapabilityOverrides } from './capabilities.js';
@@ -30,6 +31,8 @@ export interface AcquiredState {
   focusEvents: boolean;
   paste: boolean;
   cursorHidden: boolean;
+  /** Whether this session changed the caret shape, and so owes a reset. */
+  cursorShaped?: boolean;
   enhancedKeys: boolean;
   rawMode: boolean;
   titleSet: boolean;
@@ -55,4 +58,10 @@ export interface TerminalAdapter extends Disposable {
   /** OSC 52, when the terminal allows it. */
   writeClipboard?(text: string): void;
   setTitle?(title: string): void;
+  /**
+   * DECSCUSR. Session state rather than frame state - it survives until
+   * something changes it, so it is set when it changes and put back on
+   * teardown, the way the alt screen and raw mode are.
+   */
+  setCursorShape?(shape: CursorStyle): void;
 }

package/src/types/theme.ts

@@ -1,5 +1,8 @@
 import type { Color } from './cells.js';
-import type { BorderChars, BorderStyle, ColorToken, Density, Style, StyleColor } from './style.js';
+import type {
+  BorderChars, BorderStyle, ColorToken, CursorStyle, Density, DividerChars, DividerStyle,
+  Style, StyleColor, TableRules,
+} from './style.js';
 import type { SyntaxScope } from './syntax.js';
 import type { Disposable } from './disposable.js';
 import type { TerminalCapabilities } from './capabilities.js';
@@ -33,6 +36,8 @@ export interface ThemeGlyphs {
   chevronUp: string;
   arrowUp: string;
   arrowDown: string;
+  arrowLeft: string;
+  arrowRight: string;
   ellipsis: string;
   search: string;
   radioOn: string;
@@ -80,6 +85,25 @@ export interface ThemeDefinition {
   /** Default border style for chrome. `'none'` gives the borderless look. */
   border?: BorderStyle;
   borderChars?: Partial<Record<BorderStyle, BorderChars>>;
+  /**
+   * Default rule style. Independent of `border`, so a borderless theme can
+   * still separate with a line.
+   */
+  divider?: DividerStyle;
+  dividerChars?: Partial<Record<DividerStyle, DividerChars>>;
+  /** The caret's shape. The terminal's own setting is the default. */
+  cursor?: CursorStyle;
+  /**
+   * How much of a table gets ruled.
+   *
+   * `header` is the default and the quiet one: a box, and a rule under the
+   * header. `all` puts a rule between every pair of rows as well, which is
+   * what a table of few, long rows wants - a wrapped-looking cell beside a
+   * short one is ambiguous about which row it belongs to until something
+   * separates them. On a table of twenty short rows the same lines are noise,
+   * which is why it is the theme's call rather than the default.
+   */
+  tableRules?: TableRules;
   density?: Density;
   /** Per-component style overrides, keyed by component name then variant. */
   components?: Record<string, Record<string, Style>>;
@@ -100,6 +124,9 @@ export interface ResolvedTheme {
   spacing: ThemeSpacing;
   glyphs: ThemeGlyphs;
   border: BorderStyle;
+  divider: DividerStyle;
+  cursor: CursorStyle | undefined;
+  tableRules: TableRules;
   density: Density;
   components: Record<string, Record<string, Style>>;
   /** Every syntax scope, resolved to a colour. */
@@ -107,6 +134,7 @@ export interface ResolvedTheme {
   /** Resolve a token (or pass a literal colour through). */
   color(token: string): Color;
   borderChars(style?: BorderStyle): BorderChars;
+  dividerChars(style?: DividerStyle): DividerChars;
   /** Component style for a name + variant list, merged in order. */
   styleFor(component: string, variants?: string[]): Style;
 }