@textui/widgets 0.1.0

package/dist/surface/surface-area.js

@@ -0,0 +1,32 @@
+import { defineComponent, h, useRuntime, useStoreSubtree } from '@textui/core';
+/**
+ * Render one surface through its active layout.
+ *
+ * This subscribes to the surface's state and mount list rather than to the
+ * whole store, so opening a tab in `main` does not re-render the status bar.
+ */
+export const SurfaceArea = defineComponent('SurfaceArea', (props) => {
+    const runtime = useRuntime();
+    const { surface, layout: layoutOverride, fallback, ...rest } = props;
+    // Subscribing to both paths is what makes a surface reactive.
+    useStoreSubtree(`$/layout/surfaces/${surface}`);
+    useStoreSubtree(`$/layout/mounts/${surface}`);
+    const app = runtime.app();
+    if (!app)
+        return null;
+    const state = app.surfaces.state(surface);
+    if (!state.visible || state.collapsed)
+        return null;
+    const mounts = app.surfaces.mounts(surface);
+    if (mounts.length === 0)
+        return fallback ? h('box', { ...rest }, fallback) : null;
+    const layoutName = layoutOverride ?? state.layout;
+    const definition = app.layouts.get(layoutName);
+    if (!definition) {
+        return h('text', {
+            content: `[textui] no layout registered as "${layoutName}"`,
+            fg: 'danger',
+        });
+    }
+    return h(definition.component, { surface, mounts, state, ...rest });
+});

package/dist/surface/tabs-layout.d.ts

@@ -0,0 +1,4 @@
+import type { LayoutProps } from './shared.js';
+/** A tab strip and the active mount. */
+export declare const TabsLayout: (props: LayoutProps) => import("@textui/core").RenderOutput;
+//# sourceMappingURL=tabs-layout.d.ts.map

package/dist/surface/tabs-layout.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tabs-layout.d.ts","sourceRoot":"","sources":["../../src/surface/tabs-layout.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE/C,wCAAwC;AACxC,eAAO,MAAM,UAAU,6DAuBrB,CAAC"}

package/dist/surface/tabs-layout.js

@@ -0,0 +1,24 @@
+import { defineComponent, h, useRuntime } from '@textui/core';
+import { Tabs } from '../navigation/index.js';
+import { MountView } from './mount-view.js';
+/** A tab strip and the active mount. */
+export const TabsLayout = defineComponent('TabsLayout', (props) => {
+    const runtime = useRuntime();
+    const { mounts, state, surface, ...rest } = props;
+    if (mounts.length === 0)
+        return null;
+    const active = mounts.find((m) => m.key === state.activeKey) ?? mounts[0];
+    const app = runtime.app();
+    return h('box', { direction: 'column', flex: 1, ...rest }, mounts.length > 1
+        ? h(Tabs, {
+            items: mounts.map((m) => ({
+                id: m.key,
+                label: m.display?.title ?? m.key,
+                icon: m.display?.icon,
+                badge: m.display?.badge,
+            })),
+            activeId: active?.key,
+            onChange: (key) => app?.surfaces.activate(surface, key),
+        })
+        : null, active ? h(MountView, { mount: active, flex: 1 }) : null);
+});

package/dist/tone.d.ts

@@ -0,0 +1,16 @@
+import type { SemanticVariant, StyleColor } from '@textui/core';
+/**
+ * The two halves of a tone.
+ *
+ * `TONE` is the colour a tone is drawn *in*; `ON_TONE` is what is written *on*
+ * it once it becomes a background. They belong together and are stated once,
+ * because a component that pairs `danger` with the wrong foreground produces
+ * the one thing a status colour must never be, which is unreadable.
+ *
+ * The theme states an `on*` token per tone rather than a single "inverted" for
+ * all of them: the contrast that works on a green fill is not the one that
+ * works on a red one.
+ */
+export declare const TONE: Record<SemanticVariant, StyleColor>;
+export declare const ON_TONE: Record<SemanticVariant, StyleColor>;
+//# sourceMappingURL=tone.d.ts.map

package/dist/tone.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tone.d.ts","sourceRoot":"","sources":["../src/tone.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAEhE;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,IAAI,EAAE,MAAM,CAAC,eAAe,EAAE,UAAU,CAUpD,CAAC;AAaF,eAAO,MAAM,OAAO,EAAE,MAAM,CAAC,eAAe,EAAE,UAAU,CAUvD,CAAC"}

package/dist/tone.js

@@ -0,0 +1,45 @@
+/**
+ * The two halves of a tone.
+ *
+ * `TONE` is the colour a tone is drawn *in*; `ON_TONE` is what is written *on*
+ * it once it becomes a background. They belong together and are stated once,
+ * because a component that pairs `danger` with the wrong foreground produces
+ * the one thing a status colour must never be, which is unreadable.
+ *
+ * The theme states an `on*` token per tone rather than a single "inverted" for
+ * all of them: the contrast that works on a green fill is not the one that
+ * works on a red one.
+ */
+export const TONE = {
+    default: 'text',
+    primary: 'primary',
+    secondary: 'secondary',
+    accent: 'accent',
+    success: 'success',
+    warning: 'warning',
+    danger: 'danger',
+    info: 'info',
+    muted: 'muted',
+};
+// Adding a tone, or renaming an `on*` token, means three edits and only two of
+// them are checked:
+//
+//   1. this map and its `TONE` pair;
+//   2. every theme in themes/builtin.ts, or the token resolves to nothing;
+//   3. the palette list in docs/themes/tokens.md - which `pnpm docs:check`
+//      does NOT catch, because that check reads component prop interfaces and
+//      knows nothing about token names.
+//
+// The third is the one that gets missed. `onDefault`, `onSecondary` and
+// `onMuted` were absent from that page until they were added by hand.
+export const ON_TONE = {
+    default: 'onDefault',
+    primary: 'onPrimary',
+    secondary: 'onSecondary',
+    accent: 'onAccent',
+    success: 'onSuccess',
+    warning: 'onWarning',
+    danger: 'onDanger',
+    info: 'onInfo',
+    muted: 'onMuted',
+};

package/dist/viewport.d.ts

@@ -0,0 +1,30 @@
+import type { Rect, Dimension } from '@textui/core';
+/**
+ * How many rows a scrolling component should draw.
+ *
+ * The subtle part is knowing when the measurement means anything. A box that
+ * was stretched, flexed or given a height fills what the layout handed it, and
+ * measuring tells it how much that was. A box with none of those is sized *by*
+ * its own content - measuring it just reports back how many rows it drew last
+ * frame, and clamping to that would mean an expanding tree could never grow
+ * past the size it had when it was first drawn.
+ *
+ * So: layout-sized components fill and scroll, content-sized ones draw
+ * everything, and which one you get is decided by the props you passed.
+ */
+export interface SizedProps {
+    flex?: number;
+    height?: Dimension;
+    maxHeight?: number;
+    basis?: Dimension;
+}
+export declare function sizedByLayout(props: SizedProps): boolean;
+/**
+ * The row count to render: what was asked for, else what fits, else all of it.
+ * `reserved` takes off rows the component spends on chrome, like a header.
+ */
+export declare function viewportRows(props: SizedProps, measured: Rect, content: number, options?: {
+    requested?: number;
+    reserved?: number;
+}): number;
+//# sourceMappingURL=viewport.d.ts.map

package/dist/viewport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"viewport.d.ts","sourceRoot":"","sources":["../src/viewport.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAEpD;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,UAAU;IACzB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,SAAS,CAAC;CACnB;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAOxD;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,UAAU,EACjB,QAAQ,EAAE,IAAI,EACd,OAAO,EAAE,MAAM,EACf,OAAO,GAAE;IAAE,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAO,GACtD,MAAM,CAIR"}

package/dist/viewport.js

@@ -0,0 +1,17 @@
+export function sizedByLayout(props) {
+    return (props.flex !== undefined ||
+        props.height !== undefined ||
+        props.maxHeight !== undefined ||
+        props.basis !== undefined);
+}
+/**
+ * The row count to render: what was asked for, else what fits, else all of it.
+ * `reserved` takes off rows the component spends on chrome, like a header.
+ */
+export function viewportRows(props, measured, content, options = {}) {
+    if (options.requested !== undefined)
+        return Math.max(1, options.requested);
+    if (!sizedByLayout(props) || measured.height <= 0)
+        return content;
+    return Math.max(1, measured.height - (options.reserved ?? 0));
+}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@textui/widgets",
+  "version": "0.1.0",
+  "description": "The TextUI component catalog - layout, display, controls, data, overlays and charts",
+  "keywords": [
+    "terminal",
+    "tui",
+    "components",
+    "widgets",
+    "jsx",
+    "ui",
+    "catalog",
+    "text-ui"
+  ],
+  "homepage": "https://softov.github.io/textui/",
+  "bugs": {
+    "url": "https://github.com/softov/textui/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/softov/textui.git",
+    "directory": "packages/widgets"
+  },
+  "license": "MIT",
+  "author": "Softov <softov@brbyte.com>",
+  "type": "module",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=22"
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@textui/core": "^0.1.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.test.json",
+    "test": "vitest run"
+  }
+}

package/src/chart/area-chart.ts

@@ -0,0 +1,9 @@
+import { defineComponent, h } from '@textui/core';
+import { LineChart } from './line-chart.js';
+import type { LineChartProps } from './shared.js';
+
+export type AreaChartProps = LineChartProps;
+
+export const AreaChart = defineComponent<AreaChartProps>('AreaChart', (props) =>
+  h(LineChart, { area: true, ...props }),
+);

package/src/chart/bar-chart.ts

@@ -0,0 +1,74 @@
+import type { BoxProps, SemanticVariant } from '@textui/core';
+import { defineComponent, h, stringWidth, useTheme } from '@textui/core';
+import { TONE, VerticalBars } from './shared.js';
+
+export interface BarChartProps extends BoxProps {
+  data: { label: string; value: number; tone?: SemanticVariant }[];
+  max?: number;
+  /** Cells the bars occupy, not counting labels. Horizontal only - see below. */
+  barWidth?: number;
+  showValue?: boolean;
+  format?(value: number): string;
+  orientation?: 'horizontal' | 'vertical';
+  /**
+   * How many cells across each bar is, standing up.
+   *
+   * Vertical only, and one by default - which is what it always was, and is a
+   * hairline rather than a bar. Two or three read as bars, and the label under
+   * each one grows to match, so `columnWidth: 2` gets two letters instead of
+   * an initial.
+   *
+   * The two axes are named separately on purpose. `barWidth` is how far a
+   * horizontal bar runs, which is the *value* axis; this is the thickness of a
+   * vertical one, which is the category axis. Lying flat they swap over, and a
+   * single prop meaning both would mean neither.
+   */
+  columnWidth?: number;
+  /** Rows tall, standing up. Vertical only. */
+  chartHeight?: number;
+}
+
+export const BarChart = defineComponent<BarChartProps>('BarChart', (props) => {
+  const theme = useTheme();
+  const {
+    data, max, barWidth = 20, showValue = true, format,
+    orientation = 'horizontal', columnWidth, chartHeight = 8, ...rest
+  } = props;
+
+  const hi = max ?? Math.max(1, ...data.map((d) => d.value));
+  const labelWidth = Math.max(0, ...data.map((d) => stringWidth(d.label)));
+
+  if (orientation === 'vertical') {
+    return h(VerticalBars, {
+      data,
+      max: hi,
+      height: chartHeight,
+      ...(columnWidth === undefined ? {} : { columnWidth }),
+      ...rest,
+    });
+  }
+
+  const partials = theme.glyphs.progressPartial;
+
+  return h('box', { direction: 'column', ...rest },
+    ...data.map((item) => {
+      const exact = (item.value / hi) * barWidth;
+      const full = Math.floor(exact);
+      const rem = exact - full;
+      const partial = full < barWidth && rem > 0
+        ? (partials[Math.floor(rem * partials.length)] ?? '')
+        : '';
+
+      return h('box', { key: item.label, direction: 'row', gap: 1 },
+        h('box', { width: labelWidth }, h('text', { content: item.label, fg: 'muted' })),
+        h('text', {
+          content: theme.glyphs.progressFull.repeat(full) + partial,
+          fg: TONE[item.tone ?? 'accent'],
+        }),
+        showValue
+          ? h('text', { content: format ? format(item.value) : String(item.value), fg: 'muted' })
+          : null,
+      );
+    }),
+  );
+});

package/src/chart/gauge.ts

@@ -0,0 +1,60 @@
+import type { BoxProps, SemanticVariant } from '@textui/core';
+import { defineComponent, h, useTheme } from '@textui/core';
+import { TONE } from './shared.js';
+
+export interface GaugeProps extends BoxProps {
+  value: number;
+  min?: number;
+  max?: number;
+  label?: string;
+  /** Bands that colour the reading by range. */
+  thresholds?: { at: number; tone: SemanticVariant }[];
+  format?(value: number): string;
+  gaugeWidth?: number;
+  /**
+   * Push the gauge away from the label, to the right edge of the row.
+   *
+   * The label's cell stretches, so it stays at the left and
+   * the track ends up hard against the right - which is what makes a column of
+   * these read as a table rather than as a ragged stack. Needs a row wider
+   * than its contents to have any effect, so the caller has to have given it a
+   * width or a `flex`.
+   */
+  spacer?: boolean;
+}
+
+export const Gauge = defineComponent<GaugeProps>('Gauge', (props) => {
+  const theme = useTheme();
+  const {
+    value, min = 0, max = 100, label, thresholds = [], format, gaugeWidth = 20,
+    spacer, ...rest
+  } = props;
+
+  const ratio = Math.max(0, Math.min(1, (value - min) / (max - min || 1)));
+  const filled = Math.round(ratio * gaugeWidth);
+
+  // The highest threshold at or below the value wins.
+  const tone = [...thresholds]
+    .sort((a, b) => b.at - a.at)
+    .find((t) => value >= t.at)?.tone ?? 'accent';
+
+  return h('box', { direction: 'row', gap: 1, role: 'meter', label, ...rest },
+    label !== undefined
+      // The label's own cell stretches rather than a `spacer` child going in
+      // beside it: a child would be free but its gap would not, and a row
+      // sized exactly to its contents would truncate the gauge to fit a space.
+      ? h('text', { content: label, fg: 'muted', ...(spacer === true ? { flex: 1 } : {}) })
+      : spacer === true ? h('spacer', {}) : null,
+    h('text', {
+      content:
+        theme.glyphs.progressFull.repeat(filled) +
+        theme.glyphs.progressEmpty.repeat(Math.max(0, gaugeWidth - filled)),
+      fg: TONE[tone],
+    }),
+    h('text', {
+      content: format ? format(value) : `${Math.round(ratio * 100)}%`,
+      fg: TONE[tone],
+      bold: true,
+    }),
+  );
+});

package/src/chart/heatmap.ts

@@ -0,0 +1,49 @@
+import type { BoxProps } from '@textui/core';
+import { defineComponent, h, stringWidth, useTheme } from '@textui/core';
+import { bounds } from './shared.js';
+
+export interface HeatmapProps extends BoxProps {
+  /** Rows of values. All rows should be the same length. */
+  data: number[][];
+  min?: number;
+  max?: number;
+  rowLabels?: string[];
+  columnLabels?: string[];
+  /** Glyph ramp, lowest to highest. Defaults to the theme's blocks. */
+  ramp?: readonly string[];
+}
+
+export const Heatmap = defineComponent<HeatmapProps>('Heatmap', (props) => {
+  const theme = useTheme();
+  const { data, min, max, rowLabels, columnLabels, ramp, ...rest } = props;
+  const glyphs = ramp ?? theme.glyphs.blocks;
+  const flat = data.flat();
+  const [lo, hi] = bounds(flat, min, max);
+  const labelWidth = rowLabels ? Math.max(0, ...rowLabels.map(stringWidth)) : 0;
+
+  return h('box', { direction: 'column', ...rest },
+    columnLabels
+      ? h('box', { direction: 'row', gap: 0 },
+          labelWidth ? h('box', { width: labelWidth + 1 }) : null,
+          h('text', {
+            content: columnLabels.map((l) => l.slice(0, 1)).join(''),
+            fg: 'subtle',
+          }))
+      : null,
+    ...data.map((row, y) =>
+      h('box', { key: y, direction: 'row', gap: rowLabels ? 1 : 0 },
+        rowLabels
+          ? h('box', { width: labelWidth }, h('text', { content: rowLabels[y] ?? '', fg: 'muted' }))
+          : null,
+        h('text', {
+          content: row
+            .map((v) => {
+              const ratio = (v - lo) / (hi - lo);
+              const index = Math.max(0, Math.min(glyphs.length - 1, Math.round(ratio * (glyphs.length - 1))));
+              return glyphs[index] as string;
+            })
+            .join(''),
+          fg: 'accent',
+        }))),
+  );
+});

package/src/chart/histogram.ts

@@ -0,0 +1,36 @@
+import type { BoxProps, SemanticVariant } from '@textui/core';
+import { defineComponent, h } from '@textui/core';
+import { VerticalBars, bounds } from './shared.js';
+
+export interface HistogramProps extends BoxProps {
+  values: number[];
+  /** Number of buckets. */
+  buckets?: number;
+  min?: number;
+  max?: number;
+  tone?: SemanticVariant;
+  chartHeight?: number;
+}
+
+export const Histogram = defineComponent<HistogramProps>('Histogram', (props) => {
+  const { values, buckets = 12, min, max, tone = 'accent', chartHeight = 6, ...rest } = props;
+  const [lo, hi] = bounds(values, min, max);
+
+  const counts = new Array<number>(buckets).fill(0);
+  for (const value of values) {
+    const ratio = (value - lo) / (hi - lo);
+    const index = Math.max(0, Math.min(buckets - 1, Math.floor(ratio * buckets)));
+    counts[index] = (counts[index] as number) + 1;
+  }
+
+  return h(VerticalBars, {
+    data: counts.map((count, i) => ({
+      label: String(Math.round(lo + ((hi - lo) * i) / buckets)),
+      value: count,
+      tone,
+    })),
+    max: Math.max(1, ...counts),
+    height: chartHeight,
+    ...rest,
+  });
+});

package/src/chart/index.ts

@@ -0,0 +1,36 @@
+import type { ComponentDefinition } from '@textui/core';
+import { AreaChart } from './area-chart.js';
+import { BarChart } from './bar-chart.js';
+import { Gauge } from './gauge.js';
+import { Heatmap } from './heatmap.js';
+import { Histogram } from './histogram.js';
+import { LineChart } from './line-chart.js';
+import { Sparkline } from './sparkline.js';
+
+/**
+ * Charts.
+ *
+ * A terminal chart has one cell of resolution vertically and one horizontally,
+ * so the honest approach is to pick glyphs that subdivide a cell - eight block
+ * levels, four braille dots - rather than to pretend at pixel plotting. Every
+ * chart here also states its numbers, because a shape without a scale is
+ * decoration.
+ */
+export * from './area-chart.js';
+export * from './bar-chart.js';
+export * from './gauge.js';
+export * from './heatmap.js';
+export * from './histogram.js';
+export * from './line-chart.js';
+export * from './sparkline.js';
+export type { LineChartProps, Series } from './shared.js';
+
+export const CHART_COMPONENTS: ComponentDefinition[] = [
+  { component: 'Sparkline', category: 'chart', renderer: { kind: 'function', render: Sparkline }, description: 'One row of block glyphs; eight levels per cell.' },
+  { component: 'BarChart', category: 'chart', renderer: { kind: 'function', render: BarChart }, description: 'Labelled bars, horizontal or vertical.' },
+  { component: 'LineChart', category: 'chart', renderer: { kind: 'function', render: LineChart }, description: 'Braille plot at 2x4 the cell resolution.' },
+  { component: 'AreaChart', category: 'chart', renderer: { kind: 'function', render: AreaChart }, description: 'A line chart, filled.' },
+  { component: 'Histogram', category: 'chart', renderer: { kind: 'function', render: Histogram }, description: 'Bucketed distribution.' },
+  { component: 'Gauge', category: 'chart', renderer: { kind: 'function', render: Gauge }, role: 'meter', description: 'A reading against thresholds.' },
+  { component: 'Heatmap', category: 'chart', renderer: { kind: 'function', render: Heatmap }, description: 'A grid of intensities.' },
+];

package/src/chart/line-chart.ts

@@ -0,0 +1,100 @@
+import type { PaintSurface, RenderContext } from '@textui/core';
+import { defineComponent, fitTo, h, stringWidth, useTheme } from '@textui/core';
+import type { LineChartProps } from './shared.js';
+import { TONE, bounds, resample } from './shared.js';
+
+/**
+ * A line chart on a braille canvas: each cell holds a 2x4 dot grid, so a
+ * 40x8 chart really has 80x32 plot positions.
+ */
+export const LineChart = defineComponent<LineChartProps>('LineChart', (props) => {
+  const theme = useTheme();
+  const {
+    series, min, max, chartWidth, chartHeight = 8,
+    axis = true, area = false, format, ...rest
+  } = props;
+
+  const all = series.flatMap((s) => s.values);
+  const [lo, hi] = bounds(all, min, max);
+  const braille = theme.glyphs.blocks.length > 0 && theme.glyphs.spinner[0] !== '|';
+
+  const draw = (surface: PaintSurface, ctx: RenderContext): void => {
+    const { width, height } = surface.rect;
+    if (width <= 0 || height <= 0) return;
+
+    for (const [index, s] of series.entries()) {
+      const color = ctx.color(TONE[s.tone ?? (index === 0 ? 'accent' : 'secondary')]);
+      const points = resample(s.values, braille ? width * 2 : width);
+
+      if (braille) {
+        // Accumulate dots per cell, then emit one braille glyph per cell.
+        const cells = new Map<string, number>();
+        for (let px = 0; px < points.length; px++) {
+          const value = points[px] as number;
+          const ratio = (value - lo) / (hi - lo);
+          const py = Math.round((1 - ratio) * (height * 4 - 1));
+          const startY = area ? py : py;
+          const endY = area ? height * 4 - 1 : py;
+          for (let y = startY; y <= endY; y++) {
+            const cx = Math.floor(px / 2);
+            const cy = Math.floor(y / 4);
+            const key = `${cx},${cy}`;
+            cells.set(key, (cells.get(key) ?? 0) | brailleBit(px % 2, y % 4));
+          }
+        }
+        for (const [key, bits] of cells) {
+          const [cx, cy] = key.split(',').map(Number) as [number, number];
+          surface.put(cx, cy, String.fromCharCode(0x2800 + bits), { fg: color });
+        }
+        continue;
+      }
+
+      // No braille: fall back to block levels, one column per cell.
+      const blocks = theme.glyphs.blocks;
+      for (let x = 0; x < points.length && x < width; x++) {
+        const ratio = ((points[x] as number) - lo) / (hi - lo);
+        const y = Math.round((1 - ratio) * (height - 1));
+        const level = blocks[Math.max(0, Math.min(blocks.length - 1, Math.round(ratio * (blocks.length - 1))))] as string;
+        surface.put(x, y, level, { fg: color });
+      }
+    }
+  };
+
+  const chart = h('canvas', {
+    draw,
+    flex: 1,
+    height: chartHeight,
+    ...(chartWidth !== undefined ? { width: chartWidth } : {}),
+  });
+
+  if (!axis) return h('box', { direction: 'column', ...rest }, chart);
+
+  const fmt = format ?? ((v: number): string => (Number.isInteger(v) ? String(v) : v.toFixed(1)));
+  const axisWidth = Math.max(stringWidth(fmt(hi)), stringWidth(fmt(lo)));
+
+  return h('box', { direction: 'column', ...rest },
+    h('box', { direction: 'row', gap: 1 },
+      h('box', { direction: 'column', width: axisWidth, height: chartHeight, justify: 'between' },
+        h('text', { content: fitTo(fmt(hi), axisWidth, 'right'), fg: 'subtle' }),
+        h('text', { content: fitTo(fmt(lo), axisWidth, 'right'), fg: 'subtle' })),
+      chart),
+    series.some((s) => s.label)
+      ? h('box', { direction: 'row', gap: 2 },
+          ...series.map((s, i) =>
+            h('box', { key: i, direction: 'row', gap: 1 },
+              h('text', { content: theme.glyphs.bulletFilled, fg: TONE[s.tone ?? (i === 0 ? 'accent' : 'secondary')] }),
+              h('text', { content: s.label ?? `series ${i + 1}`, fg: 'muted' }))))
+      : null,
+  );
+});
+
+function brailleBit(x: number, y: number): number {
+  // Braille dot numbering is column-major and not contiguous; this is the map.
+  const MAP = [
+    [0x01, 0x08],
+    [0x02, 0x10],
+    [0x04, 0x20],
+    [0x40, 0x80],
+  ];
+  return (MAP[y] as number[])[x] as number;
+}