@textui/core 0.1.0 → 0.3.0

package/src/app/app.ts

@@ -99,6 +99,27 @@ export class App implements TextUIApp {
   private resolvedTheme: ResolvedTheme;
   private bag = createBag();
   private hovered: string | null = null;
+  /**
+   * Whoever took the last button down, until it comes back up.
+   *
+   * Mouse dispatch is a hit test, so without this a drag stops the moment the
+   * pointer leaves the box it started in - which is precisely when a drag
+   * becomes interesting. A selection dragged off the bottom of a field, a
+   * slider dragged past its own track and a splitter dragged across the pane
+   * it is resizing are all the pointer being somewhere the handler is not.
+   */
+  private captured: Instance | null = null;
+  /**
+   * Everything under the pointer, innermost outwards.
+   *
+   * A chain rather than one node, because hover is inherited the way it is in
+   * a browser: a row lights up when the pointer is over the label inside it,
+   * and the label is what the hit test finds. Hover used to be a focus id
+   * compared against `props.id`, which meant only a focusable node could ever
+   * be hovered - so a tool call row, a list row and every other box that is
+   * clicked rather than focused had a `hover` style nothing could trigger.
+   */
+  private hoveredChain = new Set<Instance>();
   /** Focus registrations created from `focusable` props, by focus id. */
   private declaredFocus = new Map<string, { instanceId: string; dispose(): void }>();
   private lastFrame: Frame | null = null;
@@ -258,11 +279,23 @@ export class App implements TextUIApp {
     }
     this.themeId = id;
     this.resolvedTheme = this.themes.resolve(id, this.terminal.capabilities());
+    this.applyCursorShape();
     this.store.set('$/modus/theme', id);
     this.buffer_.invalidate();
     this.requestRender(true);
   }
 
+  /**
+   * Ask the terminal for the theme's caret, when the theme states one.
+   *
+   * A theme that says nothing leaves the terminal's own setting alone, which
+   * is why this is not called with a default.
+   */
+  private applyCursorShape(): void {
+    const shape = this.resolvedTheme.cursor;
+    if (shape) this.terminal.setCursorShape?.(shape);
+  }
+
   setShell(id: string): void {
     if (!this.shells.get(id)) {
       throw new Error(`[textui] no shell registered as "${id}"`);
@@ -271,6 +304,22 @@ export class App implements TextUIApp {
     this.store.set('$/layout/shell', id);
     const shell = this.shells.get(id);
     if (shell?.theme && this.themes.get(shell.theme)) this.setTheme(shell.theme);
+
+    // `root` reaches the screen two ways, and this is the moment it changes
+    // which. With no shell registered at boot it was never opened into `main` -
+    // `rootNode` wraps it directly, which is the path an application built out
+    // of primitives takes. A shell arriving afterwards makes `rootNode` return
+    // the shell instead, and the application's entire content was simply gone:
+    // a framed, themed, empty screen.
+    //
+    // `setRoot` has always handled both paths, and says why - "setting one and
+    // not the other works in exactly half of the programs that can exist". This
+    // is the other half of the same sentence. Opening the same key twice
+    // replaces the mount rather than stacking one, so no guard is needed.
+    if (this.options.root) {
+      this.surfaces.open({ surface: 'main', key: ROOT_KEY, target: this.options.root });
+    }
+
     this.buffer_.invalidate();
     this.requestRender(true);
   }
@@ -282,6 +331,7 @@ export class App implements TextUIApp {
   setCapabilityOverrides(overrides: CapabilityOverrides): void {
     this.terminal.setCapabilityOverrides(overrides);
     this.resolvedTheme = this.themes.resolve(this.themeId, this.terminal.capabilities());
+    this.applyCursorShape();
     this.publishEnvironment();
     this.buffer_.invalidate();
     this.requestRender(true);
@@ -325,6 +375,10 @@ export class App implements TextUIApp {
       ...this.options.session,
     });
 
+    // After `acquire`, never before: with no session there is nothing to put
+    // the shape back, so an early call is dropped rather than leaked.
+    this.applyCursorShape();
+
     this.bag.add(this.terminal.onInput((event) => this.handleInput(event)));
     this.bag.add(this.terminal.onResize((size) => this.handleResize(size)));
 
@@ -428,6 +482,44 @@ export class App implements TextUIApp {
     this.renderFrame();
   }
 
+  /**
+   * Render until there is nothing left to render.
+   *
+   * `flush` forces one frame; this is the other question - *has it finished?* -
+   * and there was no way to ask it. What a program wanting one true frame did
+   * instead was guess: every example that writes a still ended with a sleep
+   * loop of four milliseconds times a number somebody tried until the picture
+   * looked right. Eight, mostly. Four in one, twelve in another. A number too
+   * small does not fail; it writes a half-drawn frame.
+   *
+   * A frame settles in more than one pass by design - an effect may mark
+   * something dirty, and a measurement changing runs the layout again - so the
+   * answer is a loop rather than a flag. Each turn yields to the task queue
+   * first, because what has not run yet cannot have marked anything.
+   *
+   * It returns as soon as a pass finds nothing pending, so an application that
+   * animates settles *between* its frames - which is what makes a still of one
+   * possible at all, and why the answer is not "has it stopped moving".
+   *
+   * `false` is the other thing: passes that kept producing work until the
+   * limit ran out, which is a render loop that does not converge - an effect
+   * with no dependency list setting the state it reads. Worth reporting rather
+   * than hanging on, and worth a number rather than a promise a caller can
+   * wait on for ever.
+   */
+  async settled(options: { limit?: number } = {}): Promise<boolean> {
+    const limit = options.limit ?? 100;
+    for (let i = 0; i < limit; i++) {
+      // Deliberately not `unref`'d: this timer is what keeps the process alive
+      // while a still is being rendered, and one that lets it exit would leave
+      // the await unresolved and the frame unwritten.
+      await new Promise<void>((resolve) => setTimeout(resolve, 0));
+      if (!this.frameScheduled && !this.isDirty()) return true;
+      this.flush();
+    }
+    return false;
+  }
+
   /**
    * The tree the frame renders: the shell, always, when one is registered.
    *
@@ -625,7 +717,7 @@ export class App implements TextUIApp {
     const focusedId = this.focus.focused();
     return {
       focused: focusedId === id || focusedId === `${instance.id}:focus`,
-      hovered: this.hovered === id,
+      hovered: this.hovered === id || this.hoveredChain.has(instance),
       active: false,
       selected: instance.props.selected === true,
       disabled: instance.props.disabled === true,
@@ -907,6 +999,28 @@ export class App implements TextUIApp {
       return;
     }
 
+    /*
+     * A modal takes escape before any keybinding does.
+     *
+     * `dismissOnEscape` was unreachable in any application with a global
+     * escape binding, which most have: the binding matched first, the layer
+     * stayed open, and the key went to whatever "go back" means behind it.
+     * What that looks like is a confirm dialog you cannot leave, over a screen
+     * that has navigated somewhere else while you were reading it.
+     *
+     * The test is `trapFocus`, not `dismissOnEscape` alone. A layer that traps
+     * focus has claimed the keyboard, so nothing behind it should be acting on
+     * keys; a toast or a tooltip has not, and those keep the old order so that
+     * escape still reaches the application while one happens to be up.
+     */
+    if (event.name === 'escape') {
+      const top = this.layers.topmostDismissible();
+      if (top && top.trapFocus) {
+        this.layers.close(top.id, 'escape');
+        return;
+      }
+    }
+
     if (this.keybindings.handle(event) !== 'unhandled') {
       this.requestRender();
       return;
@@ -930,16 +1044,44 @@ export class App implements TextUIApp {
   }
 
   private handleMouse(event: MouseEvent): void {
+    // The rest of the gesture belongs to whoever took the button down,
+    // wherever the pointer has got to since - and it is delivered whether or
+    // not the handler claims it, because during a drag there is nothing else
+    // it could be for.
+    if (this.captured && (event.action === 'drag' || event.action === 'up')) {
+      const target = this.captured;
+      if (event.action === 'up') this.captured = null;
+      if (target.mounted) {
+        const onMouse = target.props.onMouse;
+        if (typeof onMouse === 'function') {
+          (onMouse as (e: MouseEvent) => boolean | void)(event);
+          this.requestRender();
+          return;
+        }
+      }
+      // Unmounted mid-drag, or it stopped taking the pointer: the gesture has
+      // nowhere to go, so let the hit test have it back.
+      this.captured = null;
+    }
+
     const hit = this.focus.at(event.x, event.y);
 
     if (event.action === 'move') {
+      const moved = this.updateHover(event);
       if (hit !== this.hovered) {
         this.hovered = hit;
         this.requestRender();
+      } else if (moved) {
+        this.requestRender();
       }
       return;
     }
 
+    // A new press ends the last one, claimed or not: an `up` that never
+    // arrived - a terminal that lost focus mid-drag - must not leave a capture
+    // that eats the next gesture.
+    if (event.action === 'down') this.captured = null;
+
     if (event.action === 'down' && hit) this.focus.focus(hit);
 
     if (this.root) {
@@ -948,6 +1090,41 @@ export class App implements TextUIApp {
     this.requestRender();
   }
 
+  /**
+   * Who the pointer is over now, and who it has just left.
+   *
+   * `onHover` is called on the way in and the way out, once each - a handler
+   * that fires on every pixel of movement is a handler nobody can use for
+   * anything but a repaint.
+   */
+  private updateHover(event: MouseEvent): boolean {
+    const next = new Set<Instance>();
+    if (this.root) collectHover(this.root, event.x, event.y, next);
+
+    let changed = next.size !== this.hoveredChain.size;
+    if (!changed) {
+      for (const instance of next) {
+        if (!this.hoveredChain.has(instance)) { changed = true; break; }
+      }
+    }
+    if (!changed) return false;
+
+    const previous = this.hoveredChain;
+    this.hoveredChain = next;
+
+    for (const instance of previous) {
+      if (next.has(instance) || !instance.mounted) continue;
+      const onHover = instance.props.onHover;
+      if (typeof onHover === 'function') (onHover as (over: boolean) => void)(false);
+    }
+    for (const instance of next) {
+      if (previous.has(instance)) continue;
+      const onHover = instance.props.onHover;
+      if (typeof onHover === 'function') (onHover as (over: boolean) => void)(true);
+    }
+    return true;
+  }
+
   /** Innermost box under the pointer first, then outward. */
   private dispatchMouse(instance: Instance, event: MouseEvent): boolean {
     for (let i = instance.children.length - 1; i >= 0; i--) {
@@ -962,6 +1139,8 @@ export class App implements TextUIApp {
 
     const onMouse = instance.props.onMouse;
     if (typeof onMouse === 'function' && (onMouse as (e: MouseEvent) => boolean | void)(event) === true) {
+      // Taking the button down is what claims the drag that follows it.
+      if (event.action === 'down') this.captured = instance;
       return true;
     }
 
@@ -1094,3 +1273,21 @@ export const WRITER_KEY = serviceKey<FrameWriter>('textui.writer');
 export function createApp(options: CreateAppOptions = {}): App {
   return new App(options);
 }
+
+/**
+ * Every box containing the point, from the root down.
+ *
+ * The whole chain rather than the innermost one: a row is hovered when the
+ * pointer is over the text inside it, and the text is what a hit test finds.
+ * Only boxes with a laid-out rect count - a component that produced no box
+ * occupies no space, so there is nothing to be over.
+ */
+function collectHover(instance: Instance, x: number, y: number, into: Set<Instance>): void {
+  const box = instance.box;
+  if (box) {
+    const { x: bx, y: by, width, height } = box.rect;
+    if (x < bx || x >= bx + width || y < by || y >= by + height) return;
+    into.add(instance);
+  }
+  for (const child of instance.children) collectHover(child, x, y, into);
+}

package/src/core/focus.ts

@@ -129,7 +129,18 @@ export class Focus implements FocusManager {
     // the screen this is for - pushed over whatever had focus, which the push
     // unmounted, leaving none - and a dialog, which opens while its opener
     // still holds focus and whose own controls say which of them wants it.
-    if (!existing && options.disabled !== true && this.current === null) {
+    //
+    // And only onto something a person could have tabbed to. A `global`
+    // handler registers as a focusable - that is how a layer reads escape
+    // without holding focus - and it is `skipTab`, so it is not a place focus
+    // can land. Handed it anyway, focus sat on a node that consumes nothing:
+    // the keys fell through to whatever was behind, and every real control's
+    // own `autoFocus` stood down, because it claims focus only when the scope
+    // does not already hold it. A question with a text field in it was
+    // therefore unanswerable - the field was drawn, `required` beside it, and
+    // what was typed at it went into the composer underneath.
+    const focusable = options.disabled !== true && options.skipTab !== true && options.global !== true;
+    if (!existing && focusable && this.current === null) {
       const scopeId = options.scopeId ?? GLOBAL_SCOPE;
       if (this.scopes.get(scopeId)?.autoFocus === true && this.stack.includes(scopeId)) {
         this.focus(options.id);

package/src/core/store.ts

@@ -6,7 +6,7 @@ import type { BindingPath } from '../types/graph.js';
 import type { Disposable } from '../types/disposable.js';
 import { toDisposable } from '../util/disposable.js';
 import {
-  ancestorKeys, hasWildcard, isDescendantKey, matchKey, pathKey, PathError,
+  hasWildcard, isDescendantKey, keysTouch, matchKey, pathKey, PathError,
 } from '../util/paths.js';
 
 interface Subscription {
@@ -222,12 +222,7 @@ export class Store implements ReactiveStore {
 
   private subMatches(sub: Subscription, changedKey: string): boolean {
     if (sub.wildcard) return matchKey(changedKey, sub.key, sub.subtree);
-    if (sub.key === changedKey) return true;
-    // A write below an exact subscription still changes that object's contents.
-    if (isDescendantKey(changedKey, sub.key)) return true;
-    // A write above it may have replaced the subtree the subscriber reads.
-    if (isDescendantKey(sub.key, changedKey)) return true;
-    return sub.subtree && ancestorKeys(changedKey).includes(sub.key);
+    return keysTouch(changedKey, sub.key);
   }
 
   // ---------------------------------------------------------- subscriptions

package/src/jsx/intrinsics.ts

@@ -42,8 +42,26 @@ export interface BaseProps extends Style {
   onKey?(event: KeyEvent): boolean | void;
   onFocus?(): void;
   onBlur?(): void;
+  /**
+   * Every mouse action on this node, innermost first.
+   *
+   * Returning `true` stops it going any further - and on a `down`, **claims
+   * the rest of the gesture**: the `drag`s and the `up` that follow come here
+   * whatever they are over, until the button comes back up. Dispatch is
+   * otherwise a hit test, so without that a drag would stop at the edge of the
+   * node it started in, which is where a drag starts being worth having.
+   */
   onMouse?(event: MouseEvent): boolean | void;
+  /** The left button going down - a third of a gesture. `onMouse` for the rest. */
   onClick?: Action | ((event: MouseEvent) => void);
+  /**
+   * The pointer entered or left this node. Called once each way, not per cell.
+   *
+   * Hover is inherited the way it is in a browser: a row is hovered while the
+   * pointer is over the label inside it, because the label is what a hit test
+   * finds. A `style` with a `hover` overlay needs nothing else - this is for
+   * the cases where something other than a colour has to happen.
+   */
   onHover?(hovering: boolean): void;
 
   /** OSC 8 link target, where the terminal supports hyperlinks. */

package/src/render/layout.ts

@@ -465,8 +465,13 @@ function layoutBox(box: LayoutBox, rect: Rect): void {
     return;
   }
 
-  const flow = box.children.filter((c) => !isAbsolute(c) && !isHidden(c));
-  const absolute = box.children.filter((c) => isAbsolute(c) && !isHidden(c));
+  const flow: LayoutBox[] = [];
+  const absolute: LayoutBox[] = [];
+  for (const child of box.children) {
+    if (isHidden(child)) continue;
+    if (isAbsolute(child)) absolute.push(child);
+    else flow.push(child);
+  }
 
   if (flow.length > 0) layoutFlow(box, flow);
   for (const child of absolute) layoutAbsolute(box, child);

package/src/runtime/bindings.ts

@@ -94,13 +94,39 @@ export function resolveValue(ctx: ResolveContext, value: unknown): unknown {
   if (isComponentNode(value)) return value;
   if (isAction(value)) return value;
 
-  if (Array.isArray(value)) return value.map((v) => resolveValue(ctx, v));
+  /*
+   * The same array back when there was nothing in it to resolve.
+   *
+   * Identity is what the reconciler compares - a component whose props are
+   * all unchanged is not re-run, and neither is anything under it - so
+   * copying unconditionally made that test impossible to pass for exactly
+   * the props worth passing it for. A list of four hundred rows arrived as a
+   * new array on every pass, its holder re-rendered every frame whatever it
+   * had been told, and the memoisation callers wrote to prevent that could
+   * not reach this far.
+   *
+   * Copying at all is for the bindings: a `{ path }` inside an array has to
+   * become the value it names, and that is a different array. So the copy is
+   * kept and returned only when something in it actually changed.
+   */
+  if (Array.isArray(value)) {
+    let changed = false;
+    const items = value.map((v) => {
+      const resolved = resolveValue(ctx, v);
+      if (resolved !== v) changed = true;
+      return resolved;
+    });
+    return changed ? items : value;
+  }
 
+  let changed = false;
   const out: Record<string, unknown> = {};
   for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
-    out[k] = resolveValue(ctx, v);
+    const resolved = resolveValue(ctx, v);
+    if (resolved !== v) changed = true;
+    out[k] = resolved;
   }
-  return out;
+  return changed ? out : value;
 }
 
 /**

package/src/runtime/hooks.ts

@@ -1001,14 +1001,25 @@ export function useTicker(
   }, [enabled, options.fps]);
 }
 
-/** A frame counter, for spinners and marquees. Frozen when animation is off. */
-export function useFrame(fps = 10): number {
+/**
+ * A frame counter, for spinners and marquees. Frozen when animation is off.
+ *
+ * `enabled` is not a convenience. A ticker is a standing invalidation - it
+ * marks its component dirty `fps` times a second for as long as it is
+ * mounted - so a component that animates only sometimes and calls this
+ * unconditionally keeps the whole application rendering while it sits still.
+ * That is invisible in a small tree and is the entire frame budget in a large
+ * one, which is the case nobody tests. Frozen at 0 while off, so a caret or a
+ * spinner drawn from it is steady rather than absent.
+ */
+export function useFrame(fps = 10, options: { enabled?: boolean } = {}): number {
   const instance = currentInstance();
   const [frame, setFrame] = useState(0);
   const disabled = instance.runtime.animation.disabled;
+  const running = (options.enabled ?? true) && !disabled;
 
-  useTicker(() => setFrame((f) => f + 1), { fps, enabled: !disabled });
-  return disabled ? 0 : frame;
+  useTicker(() => setFrame((f) => f + 1), { fps, enabled: running });
+  return running ? frame : 0;
 }
 
 /** A value that eases towards its target. Snaps when animation is off. */

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';