@textui/core 0.1.0

package/src/types/style.ts

@@ -0,0 +1,205 @@
+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.
+ */
+export type ColorToken =
+  | 'canvas' | 'surface' | 'surfaceAlt' | 'overlay'
+  | 'border' | 'borderStrong' | 'borderSubtle'
+  | 'text' | 'muted' | 'subtle' | 'inverted'
+  | 'accent' | 'primary' | 'secondary'
+  | 'success' | 'warning' | 'danger' | 'info'
+  | 'onDefault' | 'onMuted'
+  | 'onAccent' | 'onPrimary' | 'onSecondary'
+  | 'onSuccess' | 'onWarning' | 'onDanger' | 'onInfo'
+  | 'hover' | 'active' | 'selected' | 'focus' | 'disabled'
+  | 'scrim' | 'cursor' | 'shadow';
+
+/** Anywhere a colour is accepted, a semantic token is accepted too. */
+export type StyleColor = ColorToken | Color;
+
+export type Dimension = number | `${number}%` | 'auto';
+
+export type BorderStyle =
+  | 'none' | 'single' | 'double' | 'round' | 'bold'
+  | 'dashed' | 'ascii' | 'thick' | 'half';
+
+/** The twelve glyphs a box needs. Themes may ship their own set. */
+export interface BorderChars {
+  topLeft: string;
+  top: string;
+  topRight: string;
+  right: string;
+  bottomRight: string;
+  bottom: string;
+  bottomLeft: string;
+  left: string;
+  /** junctions, for tables and split panels */
+  cross: string;
+  teeTop: string;
+  teeBottom: string;
+  teeLeft: string;
+  teeRight: string;
+}
+
+export type BorderSides = {
+  top?: boolean;
+  right?: boolean;
+  bottom?: boolean;
+  left?: boolean;
+};
+
+/** A colour per edge. Unnamed edges fall back to the border's `color`. */
+export type BorderColors = {
+  top?: StyleColor;
+  right?: StyleColor;
+  bottom?: StyleColor;
+  left?: StyleColor;
+};
+
+export type BorderSpec =
+  | BorderStyle
+  | {
+      style?: BorderStyle;
+      color?: StyleColor;
+      /**
+       * 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
+       * one colour and a terminal has no mitre to split it along.
+       */
+      colors?: BorderColors;
+      sides?: BorderSides;
+      chars?: Partial<BorderChars>;
+      /**
+       * Draw the frame dim. The frame only: a dim attribute on the box itself
+       * would take the content with it, and a quiet border around ordinary
+       * text is the whole reason to ask.
+       */
+      dim?: boolean;
+    };
+
+export type Align = 'start' | 'center' | 'end' | 'stretch' | 'baseline';
+export type Justify = 'start' | 'center' | 'end' | 'between' | 'around' | 'evenly';
+export type Overflow = 'visible' | 'hidden' | 'scroll' | 'ellipsis';
+export type Position = 'relative' | 'absolute';
+export type FlexWrap = 'nowrap' | 'wrap';
+/**
+ * How a run of text meets the edge of its box.
+ *
+ * `none`, `word` and `char` describe *wrapping*: the text keeps every
+ * character and takes as many rows as it needs. The `truncate-*` forms are the
+ * opposite bargain - one row, and whatever does not fit is replaced by an
+ * ellipsis at the named end. `truncate` is `truncate-end`, which is the one
+ * everybody means.
+ *
+ * A truncating text is one row tall by definition, so an embedded newline
+ * would have nowhere to go; those become spaces rather than being dropped,
+ * because a joined sentence still reads and a silently halved one does not.
+ */
+export type TextWrap =
+  | 'none' | 'word' | 'char'
+  | 'truncate' | 'truncate-start' | 'truncate-middle' | 'truncate-end';
+
+
+export interface Style {
+  /**
+   * Wash whatever is already painted here toward this colour, instead of
+   * drawing over it. A modal scrim in a terminal: the screen behind recedes
+   * 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;
+  scrimStrength?: number;
+
+  // --- box ---
+  display?: 'flex' | 'none';
+  direction?: 'row' | 'column';
+  /** Space between children on both axes. `columnGap`/`rowGap` override it. */
+  gap?: number;
+  /**
+   * Space between columns - horizontal, whichever way the container runs. It
+   * is the gap *between* children on a row, and the gap between wrapped lines
+   * on a column.
+   */
+  columnGap?: number;
+  /** Space between rows - vertical. The mirror of `columnGap`. */
+  rowGap?: number;
+  /**
+   * Whether children that do not fit start a new line. `nowrap` is the
+   * default and the cheaper path: one line, children shrink or get clipped.
+   */
+  flexWrap?: FlexWrap;
+  padding?: EdgeSpec;
+  margin?: EdgeSpec;
+  width?: Dimension;
+  height?: Dimension;
+  minWidth?: number;
+  maxWidth?: number;
+  minHeight?: number;
+  maxHeight?: number;
+  /** Grow factor along the parent's main axis. 0 = size to content. */
+  flex?: number;
+  /** Shrink factor. Defaults to 1 when flex is unset. */
+  shrink?: number;
+  /** Base size along the main axis before grow/shrink. */
+  basis?: Dimension;
+  align?: Align;
+  alignSelf?: Align;
+  justify?: Justify;
+  position?: Position;
+  top?: number;
+  right?: number;
+  bottom?: number;
+  left?: number;
+  /** Painting and hit-testing order within a layer. */
+  zIndex?: number;
+  /** What happens to content past the edge, on both axes. */
+  overflow?: Overflow;
+  /** Overrides `overflow` sideways. A row that scrolls but does not grow. */
+  overflowX?: Overflow;
+  /** Overrides `overflow` downwards. The usual scroll container. */
+  overflowY?: Overflow;
+
+  // --- paint ---
+  fg?: StyleColor;
+  bg?: StyleColor;
+  bold?: boolean;
+  dim?: boolean;
+  italic?: boolean;
+  underline?: boolean;
+  inverse?: boolean;
+  strike?: boolean;
+  blink?: boolean;
+  border?: BorderSpec;
+
+  // --- text ---
+  wrap?: TextWrap;
+  textAlign?: 'left' | 'center' | 'right';
+  /** Character painted into empty cells of this box. */
+  fill?: string;
+}
+
+/** Styles selected by interaction state. Merged over the base in this order. */
+export interface StatefulStyle {
+  base?: Style;
+  focus?: Style;
+  hover?: Style;
+  active?: Style;
+  selected?: Style;
+  disabled?: Style;
+}
+
+export type StyleInput = Style | StatefulStyle | (Style | StatefulStyle | undefined | false)[];
+
+/** Global semantic variants, available to every component that opts in. */
+export type SemanticVariant =
+  | 'default' | 'primary' | 'secondary' | 'accent'
+  | 'success' | 'warning' | 'danger' | 'info' | 'muted';
+
+/** Presentational variants a component may support. */
+export type SurfaceVariant = 'solid' | 'outline' | 'ghost' | 'link';
+
+export type Density = 'compact' | 'normal' | 'airy';

package/src/types/surface.ts

@@ -0,0 +1,119 @@
+import type { Disposable } from './disposable.js';
+import type { BindingPath, ComponentNode } from './graph.js';
+import type { WhenClause } from './when.js';
+import type { StyleColor } from './style.js';
+
+/**
+ * Where something is mounted.
+ *
+ * A surface is the application's word, not the library's. The names below are
+ * the ones the shipped shells happen to use, and they are listed so an editor
+ * can complete them - `(string & {})` keeps the type open, so `lateral1`,
+ * `inspector` or `panel:bottom` are all equally valid and need no change here.
+ *
+ * The runtime never checks a surface name against a list. A name it has not
+ * seen gets default state the first time it is used, and a shell renders
+ * whichever surfaces it decides to render.
+ */
+export type SurfaceName =
+  | 'header'      // title bar / tab strip
+  | 'rail'        // narrow icon strip (an activity bar)
+  | 'sidebar'     // primary side region
+  | 'aside'       // secondary side region
+  | 'main'        // the content
+  | 'panel'       // bottom drawer: logs, output, terminal
+  | 'status'      // one-line status bar
+  | 'overlay'     // modals, palettes, popovers, tooltips
+  | 'notify'      // toasts
+  | (string & {});
+
+export interface MountDisplay {
+  title?: string;
+  subtitle?: string;
+  icon?: string;
+  color?: StyleColor;
+  badge?: string | number;
+  /** Commands offered in this mount's header. */
+  actions?: string[];
+}
+
+export interface MountPolicy {
+  /** Survives a session snapshot. */
+  persistent?: boolean;
+  /** Removed on the next navigation. Previews want this. */
+  transient?: boolean;
+  closable?: boolean;
+  /** The user may move it to another surface. */
+  movable?: boolean;
+}
+
+/** An inline node, or a binding whose value is a node. */
+export type MountTarget = ComponentNode | { path: BindingPath };
+
+export interface Mount {
+  key: string;
+  surface: SurfaceName;
+  target: MountTarget;
+  display?: MountDisplay;
+  policy?: MountPolicy;
+  when?: WhenClause;
+  /** Relative paths inside this mount resolve against here. */
+  dataContext?: BindingPath;
+  order?: number;
+}
+
+/** How a surface arranges the several mounts it holds. */
+export type LayoutName =
+  | 'single'    // only the active one
+  | 'tabs'      // tab strip plus the active one
+  | 'stack'     // all of them, vertically
+  | 'split'     // all of them, resizable
+  | 'rail'      // icons only
+  | 'bar'       // one line, horizontal
+  | 'inline'    // all of them, no chrome
+  | 'floating'  // positioned; overlay uses this
+  | 'toast';    // stacked, ephemeral
+
+export interface SurfaceState {
+  /**
+   * Open, like `SurfaceName` and like `LayoutDefinition.name`. An application
+   * that registers a layout has to be able to put a surface into it, and the
+   * runtime never assumed a closed set anyway - `SurfaceArea` looks the name
+   * up in the registry and renders a diagnostic when nothing answers to it.
+   */
+  layout: LayoutName | (string & {});
+  activeKey: string | null;
+  visible: boolean;
+  /** Cells along the surface's cross axis. Unset lets the shell decide. */
+  size?: number;
+  collapsed?: boolean;
+}
+
+export interface SurfaceRegistry {
+  open(mount: Mount): Disposable;
+  close(surface: SurfaceName, key: string): void;
+  closeAll(surface: SurfaceName): void;
+  get(surface: SurfaceName, key: string): Mount | undefined;
+  mounts(surface: SurfaceName): Mount[];
+  activate(surface: SurfaceName, key: string): void;
+  state(surface: SurfaceName): SurfaceState;
+  setState(surface: SurfaceName, patch: Partial<SurfaceState>): void;
+  /** Resolve a resource's viewer and mount it. */
+  openResource(uri: string, options?: { surface?: SurfaceName; viewerId?: string; mode?: 'view' | 'edit' }): Promise<Disposable | null>;
+}
+
+/** A layout is a component that receives a surface's mounts and renders them. */
+export interface LayoutDefinition {
+  name: LayoutName | (string & {});
+  /** Component name receiving `{ surface, mounts, state }`. */
+  component: string;
+  title?: string;
+  /** Surfaces this layout is offered for. Unset = all. */
+  surfaces?: SurfaceName[];
+}
+
+export interface LayoutRegistry {
+  register(def: LayoutDefinition): Disposable;
+  get(name: string): LayoutDefinition | undefined;
+  list(surface?: SurfaceName): LayoutDefinition[];
+}

package/src/types/syntax.ts

@@ -0,0 +1,93 @@
+import type { Disposable } from './disposable.js';
+
+/**
+ * Syntax highlighting.
+ *
+ * A highlighter names *scopes*, never colours. The theme owns the palette, so
+ * one JSON highlighter looks right on a dark console, a paper report and a
+ * sixteen-colour terminal without knowing that any of them exist - and a
+ * colourless terminal simply resolves every scope to the default foreground.
+ *
+ * The scope list is closed on purpose. An open vocabulary means a theme can
+ * only guess what a highlighter will emit, and the guess is what produces the
+ * uncoloured token nobody can explain.
+ */
+export type SyntaxScope =
+  | 'plain'
+  | 'keyword'
+  | 'string'
+  | 'number'
+  | 'boolean'
+  | 'null'
+  | 'comment'
+  | 'punctuation'
+  /** An object key, a column name, a field label - the left of a pair. */
+  | 'key'
+  | 'operator'
+  | 'type'
+  | 'function'
+  | 'tag'
+  | 'attribute'
+  | 'regexp'
+  | 'escape'
+  /** Syntactically wrong. Worth seeing rather than hiding. */
+  | 'invalid';
+
+export const SYNTAX_SCOPES: readonly SyntaxScope[] = [
+  'plain', 'keyword', 'string', 'number', 'boolean', 'null', 'comment',
+  'punctuation', 'key', 'operator', 'type', 'function', 'tag', 'attribute',
+  'regexp', 'escape', 'invalid',
+];
+
+/** A run of text with one scope. Never spans a newline. */
+export interface SyntaxToken {
+  text: string;
+  scope: SyntaxScope;
+}
+
+/** A scored region of the source, before it is split into lines. */
+export interface SyntaxSpan {
+  start: number;
+  end: number;
+  scope: SyntaxScope;
+}
+
+export interface HighlighterDefinition {
+  id: string;
+  title?: string;
+  /** Resource kinds this claims: `file.data.json`, `log.stream`. */
+  kinds?: string[];
+  /** Filename globs, for when nothing has classified the resource yet. */
+  extensions?: string[];
+  /** Higher wins when several match. */
+  priority?: number;
+  /**
+   * Tokenise a whole document into one array per line.
+   *
+   * The result must have exactly as many entries as `text.split('\n')`, and
+   * the tokens on each line must join back to that line. The registry checks
+   * both and falls back to plain text rather than paint a file that no longer
+   * lines up with its own gutter.
+   */
+  tokenize(text: string): SyntaxToken[][];
+}
+
+export interface SyntaxQuery {
+  /** Resource kind, when the resource has been classified. */
+  kind?: string;
+  /** URI or filename, matched against `extensions`. */
+  uri?: string;
+  /** An explicit highlighter id, which wins over everything. */
+  language?: string;
+}
+
+export interface SyntaxRegistry {
+  register(def: HighlighterDefinition): Disposable;
+  unregister(id: string): void;
+  get(id: string): HighlighterDefinition | undefined;
+  list(): HighlighterDefinition[];
+  /** The best highlighter for this resource, or undefined. */
+  find(query: SyntaxQuery): HighlighterDefinition | undefined;
+  /** Tokenise, falling back to one plain token per line. */
+  tokenize(text: string, query?: SyntaxQuery): SyntaxToken[][];
+}

package/src/types/terminal.ts

@@ -0,0 +1,58 @@
+import type { Disposable } from './disposable.js';
+import type { Size } from './geometry.js';
+import type { TerminalCapabilities, CapabilityOverrides } from './capabilities.js';
+import type { InputEvent } from './input.js';
+
+/**
+ * Which capabilities the session wants turned on. The adapter records what it
+ * actually acquired, and `release` undoes exactly that and nothing else -
+ * which is the whole difference between a managed session and an embedded one.
+ */
+export interface TerminalSessionOptions {
+  /** TextUI owns setup and teardown of the terminal. */
+  managed?: boolean;
+  altScreen?: boolean;
+  mouse?: boolean;
+  wheel?: boolean;
+  focusEvents?: boolean;
+  paste?: boolean;
+  hideCursor?: boolean;
+  /** Kitty keyboard disambiguation, when available. */
+  enhancedKeys?: boolean;
+  title?: string;
+}
+
+/** What the adapter actually turned on, so release is exact. */
+export interface AcquiredState {
+  altScreen: boolean;
+  mouse: boolean;
+  wheel: boolean;
+  focusEvents: boolean;
+  paste: boolean;
+  cursorHidden: boolean;
+  enhancedKeys: boolean;
+  rawMode: boolean;
+  titleSet: boolean;
+}
+
+export interface TerminalAdapter extends Disposable {
+  readonly id: string;
+  size(): Size;
+  capabilities(): TerminalCapabilities;
+  /** Explicit overrides win over detection. */
+  setCapabilityOverrides(overrides: CapabilityOverrides): void;
+
+  acquire(options: TerminalSessionOptions): Promise<AcquiredState> | AcquiredState;
+  release(): Promise<void> | void;
+  readonly acquired: AcquiredState | null;
+
+  write(data: string): void;
+  flush(): Promise<void> | void;
+
+  onInput(fn: (event: InputEvent) => void): Disposable;
+  onResize(fn: (size: Size) => void): Disposable;
+
+  /** OSC 52, when the terminal allows it. */
+  writeClipboard?(text: string): void;
+  setTitle?(title: string): void;
+}

package/src/types/theme.ts

@@ -0,0 +1,121 @@
+import type { Color } from './cells.js';
+import type { BorderChars, BorderStyle, ColorToken, Density, Style, StyleColor } from './style.js';
+import type { SyntaxScope } from './syntax.js';
+import type { Disposable } from './disposable.js';
+import type { TerminalCapabilities } from './capabilities.js';
+
+/** Spacing scale, in cells. Terminals have no sub-cell spacing. */
+export interface ThemeSpacing {
+  none: number;
+  xs: number;
+  sm: number;
+  md: number;
+  lg: number;
+  xl: number;
+}
+
+/**
+ * The glyph vocabulary. Separated from colour because a 16-colour terminal may
+ * still be full-Unicode, and an ascii-only terminal may be truecolor.
+ */
+export interface ThemeGlyphs {
+  /** Status dots, bullets, arrows - keyed by role so a component names a role. */
+  bulletFilled: string;
+  bulletHollow: string;
+  bulletHalf: string;
+  check: string;
+  cross: string;
+  warning: string;
+  info: string;
+  chevronRight: string;
+  chevronDown: string;
+  chevronLeft: string;
+  chevronUp: string;
+  arrowUp: string;
+  arrowDown: string;
+  ellipsis: string;
+  search: string;
+  radioOn: string;
+  radioOff: string;
+  checkboxOn: string;
+  checkboxOff: string;
+  checkboxMixed: string;
+  /** Eight levels for sparklines and bar charts. */
+  blocks: readonly string[];
+  /** Progress bar track and fill. */
+  progressFull: string;
+  progressEmpty: string;
+  progressPartial: readonly string[];
+  spinner: readonly string[];
+  /** Text cursor when the terminal cursor is unavailable. */
+  caret: string;
+  separator: string;
+  /** Path separator in a breadcrumb. */
+  breadcrumb: string;
+  /**
+   * Where a region sits in the frame.
+   *
+   * One family, so a list of regions reads as a diagram rather than as six
+   * unrelated marks: the glyph says *where*, and `regionOff` says the region
+   * is not on screen. A tick cannot say where, which is why a list of ticks
+   * needs a second column of words to be readable at all.
+   */
+  regionTop: string;
+  regionBottom: string;
+  regionLeft: string;
+  regionRight: string;
+  regionCentre: string;
+  regionOff: string;
+}
+
+export interface ThemeDefinition {
+  id: string;
+  name: string;
+  appearance: 'light' | 'dark';
+  /** Extend another registered theme; only the differences need stating. */
+  extends?: string;
+  colors: Partial<Record<ColorToken, Color>>;
+  spacing?: Partial<ThemeSpacing>;
+  glyphs?: Partial<ThemeGlyphs>;
+  /** Default border style for chrome. `'none'` gives the borderless look. */
+  border?: BorderStyle;
+  borderChars?: Partial<Record<BorderStyle, BorderChars>>;
+  density?: Density;
+  /** Per-component style overrides, keyed by component name then variant. */
+  components?: Record<string, Record<string, Style>>;
+  /**
+   * Colours for syntax scopes. Every scope has a default drawn from the
+   * semantic palette, so a theme states only what it wants to differ - and a
+   * theme that states nothing still highlights.
+   */
+  syntax?: Partial<Record<SyntaxScope, StyleColor>>;
+}
+
+/** A theme after `extends` resolution and capability downgrade. */
+export interface ResolvedTheme {
+  id: string;
+  name: string;
+  appearance: 'light' | 'dark';
+  colors: Record<ColorToken, Color>;
+  spacing: ThemeSpacing;
+  glyphs: ThemeGlyphs;
+  border: BorderStyle;
+  density: Density;
+  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). */
+  color(token: string): Color;
+  borderChars(style?: BorderStyle): BorderChars;
+  /** Component style for a name + variant list, merged in order. */
+  styleFor(component: string, variants?: string[]): Style;
+}
+
+export interface ThemeRegistry {
+  register(def: ThemeDefinition): Disposable;
+  unregister(id: string): void;
+  get(id: string): ThemeDefinition | undefined;
+  list(): ThemeDefinition[];
+  /** Resolve `extends`, apply capability downgrade, return a usable theme. */
+  resolve(id: string, caps: TerminalCapabilities): ResolvedTheme;
+}

package/src/types/when.ts

@@ -0,0 +1,21 @@
+import type { BindingPath } from './graph.js';
+
+export type ContextValue = string | number | boolean | null;
+
+/**
+ * A small expression over store paths and context keys. Chrome that should not
+ * exist for this user does not mount, rather than mounting disabled.
+ *
+ *   "$/session/role == 'admin'"
+ *   "$/modus/capabilities/mouse && !$/ui/sidebar/collapsed"
+ *   "$/modus/size/width >= 100"
+ */
+export type WhenClause = string;
+
+export interface WhenEngine {
+  evaluate(clause: WhenClause | undefined, extra?: Record<string, ContextValue>): boolean;
+  /** Paths a clause reads, so a caller can subscribe to exactly those. */
+  dependencies(clause: WhenClause): BindingPath[];
+  setContext(key: string, value: ContextValue): void;
+  getContext(key: string): ContextValue | undefined;
+}