@textui/core 0.1.0

package/src/themes/builtin.ts

@@ -0,0 +1,301 @@
+import type { ThemeDefinition } from '../types/theme.js';
+
+/**
+ * The built-in themes.
+ *
+ * `dark` and `light` are the two bases; everything else extends one of them
+ * and restates only what it changes. The three that follow exist because the
+ * same application should be able to look like a dense operator console, an
+ * airy report or a workbench without a component knowing which - so the
+ * difference lives here, in border style and density, not in the catalog.
+ */
+
+export const DARK: ThemeDefinition = {
+  id: 'dark',
+  name: 'Dark',
+  appearance: 'dark',
+  border: 'single',
+  density: 'normal',
+  colors: {
+    canvas: '#0d1117',
+    surface: '#161b22',
+    surfaceAlt: '#1c2128',
+    overlay: '#1c2128',
+    border: '#30363d',
+    borderStrong: '#484f58',
+    borderSubtle: '#21262d',
+    text: '#e6edf3',
+    muted: '#8b949e',
+    subtle: '#6e7681',
+    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: '#58a6ff',
+    shadow: '#010409',
+  },
+  spacing: { none: 0, xs: 0, sm: 1, md: 1, lg: 2, xl: 3 },
+};
+
+export const LIGHT: ThemeDefinition = {
+  id: 'light',
+  name: 'Light',
+  appearance: 'light',
+  border: 'single',
+  density: 'normal',
+  colors: {
+    canvas: '#ffffff',
+    surface: '#f6f8fa',
+    surfaceAlt: '#eaeef2',
+    overlay: '#ffffff',
+    border: '#d0d7de',
+    borderStrong: '#8c959f',
+    borderSubtle: '#eaeef2',
+    text: '#1f2328',
+    muted: '#656d76',
+    subtle: '#8c959f',
+    inverted: '#ffffff',
+    accent: '#0969da',
+    primary: '#0969da',
+    secondary: '#8250df',
+    success: '#1a7f37',
+    warning: '#faca00',
+    danger: '#e95c5e',
+    info: '#0969da',
+    onAccent: '#ffffff',
+    onDefault: '#ffffff',
+    onPrimary: '#ffffff',
+    onSecondary: '#ffffff',
+    onMuted: '#ffffff',
+    onSuccess: '#ffffff',
+    onInfo: '#ffffff',
+    onWarning: '#ffffff',
+    onDanger: '#ffffff',
+    hover: '#eaeef2',
+    active: '#dbeafe',
+    selected: '#0969da',
+    focus: '#0969da',
+    disabled: '#8c959f',
+    scrim: '#8c959f',
+    cursor: '#0969da',
+    shadow: '#d0d7de',
+  },
+  spacing: { none: 0, xs: 0, sm: 1, md: 1, lg: 2, xl: 3 },
+};
+
+/** Dense, bordered, high contrast. Every region is a labelled box. */
+export const CONSOLE: ThemeDefinition = {
+  id: 'console',
+  name: 'Console',
+  appearance: 'dark',
+  extends: 'dark',
+  border: 'single',
+  density: 'compact',
+  colors: {
+    canvas: '#000000',
+    surface: '#0a0e14',
+    border: '#3b4252',
+    borderStrong: '#5e81ac',
+    accent: '#88c0d0',
+    text: '#d8dee9',
+    muted: '#616e88',
+    // The accent is teal, so the things made of it are too. Inheriting these
+    // from `dark` is what left a teal underline over a blue focus ring and a
+    // blue selected row - one theme wearing two accents.
+    //
+    // 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.
+    primary: '#88c0d0',
+    info: '#88c0d0',
+    selected: '#6ba3b2',
+    active: '#1e3d47',
+    onAccent: '#0a0e14',
+    onPrimary: '#0a0e14',
+    onInfo: '#0a0e14',
+    hover: '#141a21',
+  },
+  spacing: { none: 0, xs: 0, sm: 0, md: 1, lg: 1, xl: 2 },
+  components: {
+    Panel: { base: { border: 'single', padding: 0 } },
+    Button: { base: { padding: [0, 1] } },
+  },
+};
+
+/** Borderless. Whitespace and alignment do the separating. */
+export const PAPER: ThemeDefinition = {
+  id: 'paper',
+  name: 'Paper',
+  appearance: 'light',
+  extends: 'light',
+  border: 'none',
+  density: 'airy',
+  colors: {
+    canvas: '#fffdf9',
+    surface: '#fffdf9',
+    surfaceAlt: '#f5f2ec',
+    border: '#e5e0d8',
+    borderSubtle: '#f0ece5',
+    subtle: '#c56532',
+    text: '#2b2a27',
+    muted: '#7a756c',
+    accent: '#b4531f',
+    primary: '#b4531f',
+    // Selection as a tint of the page, not a block of another colour.
+    // `paper` inherits from `light`, whose selection is a saturated blue -
+    // dropped onto cream it reads as damage rather than as a highlight, and
+    // every component that fills with `selected` inherits that.
+    hover: '#f7f1e7',
+    active: '#efe4d2',
+    selected: '#eadcc6',
+    inverted: '#2b2a27',
+    focus: '#b4531f',
+  },
+  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] } },
+  },
+};
+
+/** Rounded chrome around a persistent frame. */
+export const WORKBENCH: ThemeDefinition = {
+  id: 'workbench',
+  name: 'Workbench',
+  appearance: 'dark',
+  extends: 'dark',
+  border: 'round',
+  density: 'normal',
+  colors: {
+    canvas: '#1e1e2e',
+    surface: '#181825',
+    surfaceAlt: '#313244',
+    overlay: '#181825',
+    border: '#45475a',
+    borderStrong: '#585b70',
+    text: '#cdd6f4',
+    muted: '#a6adc8',
+    subtle: '#6c7086',
+    accent: '#89b4fa',
+    primary: '#89b4fa',
+    secondary: '#cba6f7',
+    success: '#a6e3a1',
+    warning: '#f9e2af',
+    danger: '#f38ba8',
+    info: '#89dceb',
+    hover: '#313244',
+    active: '#45475a',
+    selected: '#585b70',
+    focus: '#89b4fa',
+    scrim: '#11111b',
+  },
+  components: {
+    Panel: { base: { border: 'round' } },
+  },
+};
+
+/** No colour at all. What a `colorDepth: 0` terminal or a pipe gets. */
+export const MONO: ThemeDefinition = {
+  id: 'mono',
+  name: 'Monochrome',
+  appearance: 'dark',
+  border: 'ascii',
+  density: 'normal',
+  colors: {
+    canvas: 'default',
+    surface: 'default',
+    surfaceAlt: 'default',
+    overlay: 'default',
+    border: 'default',
+    borderStrong: 'default',
+    borderSubtle: 'default',
+    text: 'default',
+    muted: 'default',
+    subtle: 'default',
+    inverted: 'default',
+    accent: 'default',
+    primary: 'default',
+    secondary: 'default',
+    success: 'default',
+    warning: 'default',
+    danger: 'default',
+    info: 'default',
+    onAccent: 'default',
+    onPrimary: 'default',
+    onSuccess: 'default',
+    onWarning: 'default',
+    onDanger: 'default',
+    onInfo: 'default',
+    hover: 'default',
+    active: 'default',
+    selected: 'default',
+    focus: 'default',
+    disabled: 'default',
+    scrim: 'default',
+    cursor: 'default',
+    shadow: 'default',
+  },
+};
+
+/**
+ * Paper, after dark.
+ *
+ * The same airy, borderless, warm-accented character as `paper` - the point of
+ * it is the restraint, not the brightness - with the ink and the page swapped.
+ * A warm dark rather than a blue one, so the two read as one family and a
+ * reader moving between them is not moving between two different products.
+ */
+export const PAPER_DARK: ThemeDefinition = {
+  id: 'paper-dark',
+  name: 'Paper Dark',
+  appearance: 'dark',
+  extends: 'dark',
+  border: 'none',
+  density: 'airy',
+  colors: {
+    canvas: '#1c1a17',
+    surface: '#1c1a17',
+    surfaceAlt: '#26231f',
+    border: '#3a352e',
+    borderSubtle: '#2a2621',
+    subtle: '#db8c4c',
+    text: '#e8e3d9',
+    muted: '#9a9287',
+    accent: '#e0873f',
+    primary: '#e0873f',
+    // The same restraint, the other way up.
+    hover: '#26231f',
+    active: '#332e27',
+    selected: '#3d362c',
+    inverted: '#f4efe6',
+    focus: '#e0873f',
+  },
+  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] } },
+  },
+};
+
+export const BUILTIN_THEMES: ThemeDefinition[] = [
+  DARK, LIGHT, CONSOLE, PAPER, PAPER_DARK, WORKBENCH, MONO,
+];

package/src/themes/glyphs.ts

@@ -0,0 +1,101 @@
+import type { ThemeGlyphs } from '../types/theme.js';
+import type { UnicodeLevel } from '../types/capabilities.js';
+
+/**
+ * The glyph vocabulary, named by role.
+ *
+ * A component asks for `bulletFilled`, never for `'●'`, so the same catalog
+ * renders on a full-Unicode terminal and on one that can only do ASCII - and
+ * so a theme can restate the vocabulary without touching a component.
+ */
+export const FULL_GLYPHS: ThemeGlyphs = {
+  bulletFilled: '●',
+  bulletHollow: '○',
+  bulletHalf: '◌',
+  check: '✓',
+  cross: '✕',
+  warning: '⚠',
+  info: 'ℹ',
+  chevronRight: '▸',
+  chevronDown: '▾',
+  chevronLeft: '◂',
+  chevronUp: '▴',
+  arrowUp: '↑',
+  arrowDown: '↓',
+  ellipsis: '…',
+  search: '⌕',
+  radioOn: '●',
+  radioOff: '○',
+  checkboxOn: '■',
+  checkboxOff: '□',
+  checkboxMixed: '☒',
+  blocks: ['▁', '▂', '▃', '▄', '▅', '▆', '▇', '█'],
+  progressFull: '█',
+  progressEmpty: '░',
+  progressPartial: ['▏', '▎', '▍', '▌', '▋', '▊', '▉'],
+  spinner: ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'],
+  caret: '▏',
+  separator: '·',
+  breadcrumb: '›',
+  regionTop: '⬒',
+  regionBottom: '⬓',
+  regionLeft: '◧',
+  regionRight: '◨',
+  regionCentre: '▣',
+  regionOff: '□',
+};
+
+/** Box-drawing and geometric shapes only - no braille, no dingbats. */
+export const BMP_GLYPHS: ThemeGlyphs = {
+  ...FULL_GLYPHS,
+  check: '√',
+  cross: 'x',
+  info: 'i',
+  spinner: ['|', '/', '-', '\\'],
+  checkboxOn: '[x]',
+  checkboxOff: '[ ]',
+  checkboxMixed: '[-]',
+};
+
+export const ASCII_GLYPHS: ThemeGlyphs = {
+  bulletFilled: '*',
+  bulletHollow: 'o',
+  bulletHalf: '+',
+  check: 'v',
+  cross: 'x',
+  warning: '!',
+  info: 'i',
+  chevronRight: '>',
+  chevronDown: 'v',
+  chevronLeft: '<',
+  chevronUp: '^',
+  arrowUp: '^',
+  arrowDown: 'v',
+  ellipsis: '...',
+  search: '/',
+  radioOn: '(*)',
+  radioOff: '( )',
+  checkboxOn: '[x]',
+  checkboxOff: '[ ]',
+  checkboxMixed: '[-]',
+  blocks: ['_', '.', ',', '-', '=', '+', '*', '#'],
+  progressFull: '#',
+  progressEmpty: '-',
+  progressPartial: ['-'],
+  spinner: ['|', '/', '-', '\\'],
+  caret: '_',
+  separator: '-',
+  breadcrumb: '>',
+  regionTop: '^',
+  regionBottom: 'v',
+  regionLeft: '[',
+  regionRight: ']',
+  regionCentre: '+',
+  regionOff: '.',
+};
+
+export function glyphsFor(unicode: UnicodeLevel): ThemeGlyphs {
+  if (unicode === 'ascii') return ASCII_GLYPHS;
+  if (unicode === 'bmp') return BMP_GLYPHS;
+  return FULL_GLYPHS;
+}

package/src/themes/index.ts

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

package/src/themes/registry.ts

@@ -0,0 +1,224 @@
+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 { 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 { glyphsFor } from './glyphs.js';
+import { BUILTIN_THEMES } from './builtin.js';
+
+const DEFAULT_SPACING: ThemeSpacing = { none: 0, xs: 0, sm: 1, md: 1, lg: 2, xl: 3 };
+
+const FALLBACK_COLORS: Record<ColorToken, Color> = {
+  canvas: 'default', surface: 'default', surfaceAlt: 'default', overlay: 'default',
+  border: 'default', borderStrong: 'default', borderSubtle: 'default',
+  text: 'default', muted: 'default', subtle: 'default', inverted: 'default',
+  accent: 'default', primary: 'default', secondary: 'default',
+  success: 'default', warning: 'default', danger: 'default', info: 'default',
+  onDefault: 'default', onMuted: 'default',
+  onAccent: 'default', onPrimary: 'default', onSecondary: 'default',
+  onSuccess: 'default', onWarning: 'default', onDanger: 'default', onInfo: 'default',
+  hover: 'default', active: 'default', selected: 'default', focus: 'default',
+  disabled: 'default', scrim: 'default', cursor: 'default', shadow: 'default',
+};
+
+/**
+ * What each syntax scope means in semantic terms.
+ *
+ * Naming a token rather than a colour is what makes highlighting survive a
+ * theme swap: `paper` gets ink-on-white strings and `console` gets green ones
+ * from the same highlighter, and a theme with no palette at all - or a
+ * terminal with no colour - resolves the lot to the default foreground.
+ */
+const SYNTAX_DEFAULTS: Record<SyntaxScope, ColorToken> = {
+  plain: 'text',
+  keyword: 'primary',
+  string: 'success',
+  number: 'info',
+  boolean: 'warning',
+  null: 'muted',
+  comment: 'subtle',
+  punctuation: 'muted',
+  key: 'accent',
+  operator: 'text',
+  type: 'secondary',
+  function: 'accent',
+  tag: 'primary',
+  attribute: 'accent',
+  regexp: 'warning',
+  escape: 'warning',
+  invalid: 'danger',
+};
+
+/** Tokens that are the accent rather than merely near it. */
+const FOLLOWS_ACCENT = ['focus', 'cursor'] as const;
+
+export class Themes implements ThemeRegistry {
+  private defs = new Map<string, ThemeDefinition>();
+  private cache = new Map<string, ResolvedTheme>();
+
+  constructor(initial: ThemeDefinition[] = BUILTIN_THEMES) {
+    for (const def of initial) this.defs.set(def.id, def);
+  }
+
+  register(def: ThemeDefinition): Disposable {
+    this.defs.set(def.id, def);
+    this.cache.clear();
+    return toDisposable(() => {
+      this.defs.delete(def.id);
+      this.cache.clear();
+    });
+  }
+
+  unregister(id: string): void {
+    this.defs.delete(id);
+    this.cache.clear();
+  }
+
+  get(id: string): ThemeDefinition | undefined {
+    return this.defs.get(id);
+  }
+
+  list(): ThemeDefinition[] {
+    return [...this.defs.values()];
+  }
+
+  /**
+   * Flatten the `extends` chain, then degrade glyphs and borders to what the
+   * terminal can draw. Colour is *not* reduced here - the writer does that per
+   * cell against `colorDepth`, so one resolved theme serves every depth.
+   */
+  resolve(id: string, caps: TerminalCapabilities): ResolvedTheme {
+    const key = `${id}:${caps.unicode}:${caps.colorDepth}`;
+    const cached = this.cache.get(key);
+    if (cached) return cached;
+
+    const chain: ThemeDefinition[] = [];
+    let cursor = this.defs.get(id);
+    const seen = new Set<string>();
+    while (cursor && !seen.has(cursor.id)) {
+      seen.add(cursor.id);
+      chain.unshift(cursor);
+      cursor = cursor.extends ? this.defs.get(cursor.extends) : undefined;
+    }
+    if (chain.length === 0) {
+      throw new Error(`[textui] no theme registered as "${id}"`);
+    }
+    const leaf = chain[chain.length - 1] as ThemeDefinition;
+
+    const colors = { ...FALLBACK_COLORS };
+    let spacing = { ...DEFAULT_SPACING };
+    let glyphOverrides: Partial<ThemeGlyphs> = {};
+    let border: BorderStyle = 'single';
+    let density: Density = 'normal';
+    const components: Record<string, Record<string, Style>> = {};
+    let syntaxOverrides: Partial<Record<SyntaxScope, StyleColor>> = {};
+
+    for (const def of chain) {
+      Object.assign(colors, def.colors);
+      // A theme that restates the accent restates what the accent is *for*.
+      //
+      // `focus` and `cursor` have no identity of their own - a focus ring and
+      // a caret are the accent, drawn somewhere. Left to a plain merge they
+      // keep whatever the extended theme set, so `console` overrode accent to
+      // teal and kept a blue focus ring, and `paper` went warm all over with a
+      // blue caret still in it. Accent teal here and blue there, in one theme.
+      //
+      // Only these two. `selected` and `active` are backgrounds that have to
+      // be dim or bright enough for the text on them, which is a decision
+      // about contrast rather than hue - a theme picks those itself.
+      const stated = def.colors ?? {};
+      if (stated.accent !== undefined) {
+        for (const token of FOLLOWS_ACCENT) {
+          if (stated[token] === undefined) colors[token] = stated.accent;
+        }
+      }
+      if (def.syntax) syntaxOverrides = { ...syntaxOverrides, ...def.syntax };
+      if (def.spacing) spacing = { ...spacing, ...def.spacing };
+      if (def.glyphs) glyphOverrides = { ...glyphOverrides, ...def.glyphs };
+      if (def.border) border = def.border;
+      if (def.density) density = def.density;
+      for (const [name, variants] of Object.entries(def.components ?? {})) {
+        components[name] = { ...components[name], ...variants };
+      }
+    }
+
+    // A colourless terminal gets no colour, whatever the theme says.
+    if (caps.colorDepth === 0) {
+      for (const token of Object.keys(colors) as ColorToken[]) {
+        colors[token] = 'default';
+      }
+    }
+
+    const syntax = {} as Record<SyntaxScope, Color>;
+    for (const [scope, token] of Object.entries(SYNTAX_DEFAULTS) as [SyntaxScope, ColorToken][]) {
+      const override = syntaxOverrides[scope];
+      syntax[scope] = override === undefined
+        ? (colors[token] as Color)
+        : ((typeof override === 'string' && override in colors
+            ? colors[override as ColorToken]
+            : override) as Color);
+    }
+    // A theme may name a literal colour for a scope, so blanking `colors` is
+    // not enough to make a colourless terminal colourless.
+    if (caps.colorDepth === 0) {
+      for (const scope of Object.keys(syntax) as SyntaxScope[]) syntax[scope] = 'default';
+    }
+
+    const glyphs: ThemeGlyphs = { ...glyphsFor(caps.unicode), ...glyphOverrides };
+    const charCache = new Map<BorderStyle, BorderChars>();
+
+    const resolved: ResolvedTheme = {
+      id: leaf.id,
+      name: leaf.name,
+      appearance: leaf.appearance,
+      colors,
+      spacing,
+      glyphs,
+      border,
+      density,
+      components,
+      syntax,
+
+      color(token: string): Color {
+        if (token in colors) return colors[token as ColorToken] as Color;
+        // Not a token: a literal colour passed straight through.
+        return token as Color;
+      },
+
+      borderChars(style?: BorderStyle): BorderChars {
+        const s = style ?? border;
+        let chars = charCache.get(s);
+        if (!chars) {
+          const base = borderCharsFor(s, caps.unicode);
+          const custom = leaf.borderChars?.[s];
+          chars = custom ? { ...base, ...custom } : base;
+          charCache.set(s, chars);
+        }
+        return chars;
+      },
+
+      styleFor(component: string, variants: string[] = []): Style {
+        const entry = components[component];
+        if (!entry) return {};
+        let out: Style = { ...entry.base };
+        for (const variant of variants) {
+          if (entry[variant]) out = { ...out, ...entry[variant] };
+        }
+        return out;
+      },
+    };
+
+    this.cache.set(key, resolved);
+    return resolved;
+  }
+}
+
+export function createThemes(initial?: ThemeDefinition[]): Themes {
+  return new Themes(initial);
+}

package/src/types/adapter.ts

@@ -0,0 +1,41 @@
+import type { Disposable } from './disposable.js';
+import type { ComponentDefinition } from './component-registry.js';
+import type { CommandDefinition } from './command.js';
+import type { KeybindingDefinition } from './keybinding.js';
+import type { HighlighterDefinition } from './syntax.js';
+import type {
+  ResourceActionDefinition, ResourceEditorDefinition, ResourceKind,
+  ResourceProvider, ResourceViewerDefinition,
+} from './resource.js';
+import type { TextUIApp } from './app.js';
+
+/**
+ * A resource adapter.
+ *
+ * Everything one resource type needs, in one value: what it is, where it comes
+ * from, what opens it, how it is coloured, and what can be done to it. The
+ * registries underneath stay separate - an adapter is a convenience for the
+ * author and a unit of undo for the application, not a new mechanism.
+ *
+ * Registering returns a `Disposable` that removes exactly what was added, so a
+ * plugin can be unloaded without the screen keeping a viewer nobody can
+ * explain.
+ */
+export interface ResourceAdapter {
+  id: string;
+  title?: string;
+  description?: string;
+  kinds?: ResourceKind[];
+  providers?: ResourceProvider[];
+  viewers?: ResourceViewerDefinition[];
+  editors?: ResourceEditorDefinition[];
+  actions?: ResourceActionDefinition[];
+  highlighters?: HighlighterDefinition[];
+  /** Commands the adapter contributes. Usually one per action. */
+  commands?: CommandDefinition[];
+  keybindings?: KeybindingDefinition[];
+  /** Components the viewers and editors name. */
+  components?: ComponentDefinition[];
+  /** Anything the fields above cannot express. */
+  register?(app: TextUIApp): Disposable | void;
+}