Claude Code. Any Model. The most powerful AI coding agent now speaks every language.
/** @jsxImportSource @opentui/react */
/**
* theme/widgets.tsx — the six single-row visuals, as React components.
*
* Surface: `@opentui/react` (JSX). Lowercase intrinsics only, flat props. Not one
* construct call appears here and none is needed: every widget below is ONE ROW of
* styled text, and a `FrameBufferRenderable` would be the wrong tool for all six.
* (`Panel` is the exception that proves the rule: it is chrome, not a visual — pure
* `<box>` props, no glyphs of its own.)
*
* Two structural rules, both load-bearing. Colour is applied PER CELL, one
* `<span>` per column — that is what makes a fill read as continuous rather than
* as four chunky `░▒▓█` steps. And every widget emits ONE `<text>`: sibling
* `<text>`s inside a box overprint at the same coordinates, `<span>`s inside a
* single `<text>` do not. Props are hex / `ColorInput`; `RGBA` stays in `./color`.
*
* THE COROLLARY of that second rule, and the reason `BadgeSpan` exists: a `<text>`
* cannot nest inside a `<text>`, so the ONE-`<text>` form is un-composable. Any
* widget that has to share a row with other content needs a `<span>` variant.
*
* TWO CONVENTIONS THE WHOLE FILE KEEPS, because a reader who learns one widget will
* assume the other three. EMPTY INPUT RENDERS `null` — never an empty `<text>`, which
* is still a flex item and still eats a row: `HeatRow values={[]}` pushed the row
* under it down by one while `Sparkline values={[]}` beside it did not, so an absent
* series moved the layout depending on which widget was absent. And every widget
* forwards the same layout props a parent may set on a `Panel` — see `WidgetLayout`.
*/
import { type ColorInput, createTextAttributes } from "@opentui/core";
import type { BoxProps, TextProps } from "@opentui/react";
import type { ReactNode } from "react";
import { blendStops, heatRamp, pickInk } from "./color";
import { displayWidth, splitCells } from "./text";
import { type Ramp, ramps, tokens } from "./tokens";
const BOLD = createTextAttributes({ bold: true });
const FILL = "█";
const TRACK = "░";
const SPARK = ["▁", "▂", "▃", "▄", "▅", "▆", "▇", "█"] as const;
/** A non-finite sample in a series. A SPACE, not `▁`: the floor glyph would read as
* "nearly zero", which is a lie about data that is absent. */
const GAP = " ";
/** A meter whose value is absent, one glyph per cell. NOT `TRACK`: a full `░` row is
* exactly what a healthy 0% paints, so `NaN` painting one made a dead sensor and an
* idle one pixel-identical. Same lie as `GAP`, a whole row at a time. */
const NODATA = "╌";
/**
* The layout keys a parent may set on anything in this file — sizing, growth and
* placement, and deliberately NOTHING that changes how a component looks. Appearance
* is each component's own API; see `PanelLayout` for why that exclusion is enforced by
* the type rather than by a convention.
*/
type LayoutKeys =
| "flexGrow"
| "flexShrink"
| "flexBasis"
| "alignSelf"
| "minWidth"
| "minHeight"
| "maxWidth"
| "maxHeight"
| "margin"
| "marginX"
| "marginY"
| "marginTop"
| "marginRight"
| "marginBottom"
| "marginLeft";
/**
* A DATA WIDGET IS A FLEX ITEM, AND UNTIL IT COULD SAY SO IT WAS AT YOGA'S MERCY.
* `Panel` forwarded layout from the start; the widgets forwarded nothing, so a parent
* had no way to defend a widget's column budget. MEASURED, `<box width={20}>` holding a
* `UP` badge, a service name and a latency — ONE column over budget: Yoga's default
* `flexShrink: 1` took that column off the FIRST child, painting a 3-column chip (` UP`)
* plus a 1-column stub of green background sitting under its neighbour's first letter.
* `captureCharFrame()` shows ` UPapi…` and is BLIND to the stub; only `captureSpans()`
* sees it, which is why a full character-level suite passed over a mangled row.
*
* Hence `flexShrink={0}` as the DEFAULT on every widget here. A widget's `width` is a
* cell count the caller computed (`react-patterns.md`: widths of data widgets are
* arithmetic), so a layout that quietly shortens it has broken the caller's maths.
* Over-budget now overflows and clips at the parent's edge — visible, and attributable
* to the row rather than to the widget. `flexShrink={1}` opts back in.
*
* No `width`/`height` here, unlike `PanelLayout`: these components already take `width`
* as a CELL COUNT, and one name meaning two things is how a call site ends up meaning
* neither. Constrain them with `minWidth`/`maxWidth` instead.
*/
export type WidgetLayout = Pick<TextProps, LayoutKeys>;
const RAMP_CACHE = new Map<string, readonly string[]>();
const RAMP_CACHE_MAX = 64;
/**
* Memoised `blendStops` — the ramp for `width` cells across `stops`.
*
* `app-architecture.md` says to hoist ramps out of render, and `Meter` used to break
* that rule on its own flagship path: `blendStops(width, ...ramp)` in the render body
* re-derived 40 colours (40 `parseColor` + 40 `rgbToHex`) on EVERY frame of EVERY
* meter, for a value that changes only when the terminal resizes. Keyed on
* `width|stops`, so a dashboard of 20 meters at one width computes one ramp between
* them all — a per-instance `useMemo` could not do that.
*
* NO STOPS FALLS BACK TO `ramps.load` rather than returning `[]`. `blendStops` answers
* `[]` for zero stops, which is correct for it and catastrophic here: `Meter` painted
* one cell per ramp entry, so `ramp={[]}` rendered a ZERO-WIDTH meter — the requested
* width silently gone, no error, no glyph. The `Ramp` type now rejects `[]` at the call
* site; this is the belt to that braces, for the JS caller the type cannot reach.
*
* FIFO-bounded at 64 entries (Map iteration is insertion-ordered), because a drag
* resize walks through widths and an unbounded cache would keep every one.
*
* The returned array is SHARED. Treat it as read-only — the type says so. */
export function rampFor(width: number, stops: readonly string[]): readonly string[] {
const use = stops.length > 0 ? stops : ramps.load;
const key = `${width}|${use.join(":")}`;
const hit = RAMP_CACHE.get(key);
if (hit) return hit;
const built: readonly string[] = blendStops(width, ...use);
if (RAMP_CACHE.size >= RAMP_CACHE_MAX) RAMP_CACHE.delete(RAMP_CACHE.keys().next().value!);
RAMP_CACHE.set(key, built);
return built;
}
/**
* Filled cell count for `pct` over `width` — extracted from `Meter` because it is
* the one part of a meter that can be wrong without looking wrong.
*
* `NaN` is the case: `Math.max(0, NaN)` is `NaN`, so an unguarded clamp passes it
* straight through to `Math.round`, `filled` becomes `NaN`, `i < NaN` is false for
* every cell, and the meter renders a full-width TRACK — pixel-identical to a healthy
* 0%. `NaN → 0` here keeps the ARITHMETIC honest for anyone counting cells; it is not
* on its own enough for the meter, which draws `NODATA` before it ever gets here, so
* absent data and idle data no longer paint the same row.
*
* ±Infinity is NOT lumped in with it: the clamp maps it to 100 / 0, which is the
* right answer, and `Number.isFinite` would have thrown away a usable value. */
export function fillCells(pct: number, width: number): number {
const cells = Math.floor(width);
if (!Number.isFinite(cells) || cells <= 0 || Number.isNaN(pct)) return 0;
return Math.round((Math.min(100, Math.max(0, pct)) / 100) * cells);
}
/**
* Gradient meter — the workhorse, and the reason `blendStops` exists. `pct` is
* 0..100 and is clamped; `NaN` is ABSENT DATA and paints a dim `╌` row instead of a
* track, because a dead sensor that paints a healthy 0% is a lie no reader can catch.
* `ramp` is gradient STOPS (default `ramps.load`), blended to `width` colours so every
* filled cell gets its own: colour encodes POSITION along the fill, the case that must
* be smooth. The painted row is EXACTLY `width` cells — it is driven by the width, never
* by the ramp's length, so no ramp can change the geometry. `width <= 0`, fractional or
* non-finite renders nothing rather than throwing.
*/
export function Meter({
pct,
width,
ramp = ramps.load,
style,
...layout
}: WidgetLayout & { pct: number; width: number; ramp?: Ramp; style?: WidgetLayout }): ReactNode {
const cells = Math.floor(width);
if (!Number.isFinite(cells) || cells <= 0) return null;
if (Number.isNaN(pct))
return (
<text fg={tokens.dead} flexShrink={0} {...layout} style={style}>
{NODATA.repeat(cells)}
</text>
);
const cols = rampFor(cells, ramp);
const filled = fillCells(pct, cells);
return (
<text flexShrink={0} {...layout} style={style}>
{Array.from({ length: cells }, (_, i) => (
// biome-ignore lint/suspicious/noArrayIndexKey: a meter cell is position-addressed — index IS identity
<span key={i} fg={i < filled ? cols[i]! : tokens.border}>
{i < filled ? FILL : TRACK}
</span>
))}
</text>
);
}
/**
* The same meter as `<span>`s, for a MIXED-CONTENT row — the exact counterpart of
* `BadgeSpan`, and it exists for the identical reason: `Meter` is a `<text>`, a `<text>`
* cannot nest in a `<text>`, so the ONE-`<text>` form is un-composable and a meter sharing
* a row with a chip and a label has nowhere to go.
*
* <text><BadgeSpan label="17h" bg={…} /><MeterSpan pct={72} width={12} /><span> 1.5 MB</span></text>
*
* The alternative — a flex ROW of `<text>` siblings — is measurably worse than untidy:
* Yoga's default `flexShrink: 1` shaves columns off a sibling the moment the row is one
* column over, and it takes them off the LAST one, which is how a branch name rendered as
* `mai` with thirty free columns beside it.
*
* Same `rampFor` and `fillCells` as `Meter`, so the two cannot drift by a cell — share the
* cell maths, never the drawing. No layout props: a `<span>` is not a flex item, so its
* row's `<text>` owns the layout for both. `NaN` paints the same dim `╌` run.
*/
export function MeterSpan({
pct,
width,
ramp = ramps.load,
}: { pct: number; width: number; ramp?: Ramp }): ReactNode {
const cells = Math.floor(width);
if (!Number.isFinite(cells) || cells <= 0) return null;
if (Number.isNaN(pct)) return <span fg={tokens.dead}>{NODATA.repeat(cells)}</span>;
const cols = rampFor(cells, ramp);
const filled = fillCells(pct, cells);
return (
<>
{Array.from({ length: cells }, (_, i) => (
// biome-ignore lint/suspicious/noArrayIndexKey: a meter cell is position-addressed — index IS identity
<span key={i} fg={i < filled ? cols[i]! : tokens.border}>
{i < filled ? FILL : TRACK}
</span>
))}
</>
);
}
/**
* Inline trend, one row of block glyphs — deliberately ONE colour, because the
* glyph height already encodes magnitude and a second encoding would only add
* noise. Empty input renders nothing. Constant data has no range to normalise
* against, so it draws a flat MID-ramp row instead of dividing by zero.
*
* A non-finite sample POISONS a naive min/max: `Math.max(m, NaN)` is `NaN`, so one
* gap in the series made `range` NaN, sent `range > 0` false, and flattened the whole
* row to the mid glyph — a real series turned into fake constant data, which is worse
* than a hole because it looks fine. So the range is taken over the FINITE samples
* only and each non-finite one draws a `GAP`, keeping one column per sample so a
* sparkline never shifts under the value beside it. All-non-finite draws a full row of
* gaps; the series has no scale, and inventing one would be a lie.
*
* THE RANGE IS HALVED, and that is not a micro-optimisation: `max - min` OVERFLOWS on
* finite input. `[-MAX_VALUE, 0, MAX_VALUE]` made it `Infinity`, `(v - min) / range`
* `NaN` at the top sample, `SPARK[NaN]` `undefined`, and `join("")` swallowed the hole —
* a three-sample series painted TWO columns (`▁▁`), one sample gone and every column
* right of it shifted. Halving both sides keeps every intermediate finite (`|v / 2|` is
* at most `MAX_VALUE / 2`, so the difference cannot overflow) and is exact in binary
* floating point, so not one cell moves. The index is clamped for the same reason the
* range is halved: `SPARK[i]!` must not be able to assert a lie. */
export function Sparkline({
values,
fg = tokens.info,
style,
...layout
}: WidgetLayout & { values: readonly number[]; fg?: ColorInput; style?: WidgetLayout }): ReactNode {
const row = sparkGlyphs(values);
if (row === null) return null;
return (
<text fg={fg} flexShrink={0} {...layout} style={style}>
{row}
</text>
);
}
/**
* The glyph row a sparkline paints — extracted so the `<text>` and `<span>` forms cannot
* drift, exactly as `fillCells`/`rampFor` keep `Meter` and `MeterSpan` in step. `null` for
* an empty series (the caller renders nothing at all; an empty `<text>` still eats a row).
*/
export function sparkGlyphs(values: readonly number[]): string | null {
if (values.length === 0) return null;
let max = Number.NEGATIVE_INFINITY;
let min = Number.POSITIVE_INFINITY;
for (const v of values)
if (Number.isFinite(v)) {
max = Math.max(max, v);
min = Math.min(min, v);
}
if (max === Number.NEGATIVE_INFINITY) return GAP.repeat(values.length);
const half = max / 2 - min / 2;
const mid = SPARK[Math.floor((SPARK.length - 1) / 2)]!;
const top = SPARK.length - 1;
const glyph = (v: number) =>
SPARK[Math.min(top, Math.max(0, Math.round(((v / 2 - min / 2) / half) * top)))]!;
return values.map((v) => (!Number.isFinite(v) ? GAP : half > 0 ? glyph(v) : mid)).join("");
}
/**
* The same sparkline as a `<span>`, for a MIXED-CONTENT row. Same argument as `BadgeSpan`
* and `MeterSpan`: a `<text>` cannot nest in a `<text>`, so a trend sharing a row with a
* label or a chip needs the span form or it forces the row into flex siblings — the
* arrangement Yoga silently shrinks. Shares `sparkGlyphs`, so the two forms are identical
* glyph for glyph.
*/
export function SparklineSpan({
values,
fg = tokens.info,
}: { values: readonly number[]; fg?: ColorInput }): ReactNode {
const row = sparkGlyphs(values);
return row === null ? null : <span fg={fg}>{row}</span>;
}
/**
* One heat row: hue FIXED so the row scans as a single severity, brightness per
* column so the row reads as magnitude over time. Colour goes in the BACKGROUND of
* a space, so cells abut into a continuous ribbon instead of a run of glyphs.
*
* `max` IS THE SCALE, AND THE CHOICE IS THE WHOLE READING OF THE PANEL. A number is a
* GLOBAL max — the default, and the only way brightness stays comparable between rows.
* Its cost is real and was measured on a live panel: a `5xx` row peaking at ~10% of the
* `2xx` row rendered within a step of the ramp floor across every column and read as a
* dead panel rather than as errors. `max="row"` opts into a PER-ROW scale, where each
* row spends the full ramp on its own peak — legible per row, and no longer comparable
* across rows, so a bright `5xx` no longer means "as bad as `2xx` is busy". Use it only
* where the rows are genuinely separate scales, and say so in the panel's label; if the
* rows belong on one scale but the small one still disappears, split the panel instead.
* `max <= 0` (or an all-zero row) draws the ramp floor — never a NaN index.
*/
export function HeatRow({
values,
max,
hue,
style,
...layout
}: WidgetLayout & {
values: readonly number[];
max: number | "row";
hue: ColorInput;
style?: WidgetLayout;
}): ReactNode {
if (values.length === 0) return null;
const ramp = heatRamp(hue);
const top = ramp.length - 1;
const cap =
max === "row" ? values.reduce((m, v) => (Number.isFinite(v) ? Math.max(m, v) : m), 0) : max;
return (
<text flexShrink={0} {...layout} style={style}>
{values.map((v, i) => {
const t = cap > 0 && Number.isFinite(v) ? Math.min(1, Math.max(0, v / cap)) : 0;
return (
// biome-ignore lint/suspicious/noArrayIndexKey: a heat cell is position-addressed — index IS identity
<span key={i} bg={ramp[Math.round(t * top)]}>
{" "}
</span>
);
})}
</text>
);
}
/**
* A row of DISCRETE LEVELS — the bucket counterpart to `HeatRow`, and a separate widget
* rather than an option on it because the distinction is not taste (`aesthetics-and-color.md`,
* "Smooth ramp or discrete buckets?"). A heat row's brightness encodes POSITION along a
* continuous magnitude, so it must be smooth. A level row's colour encodes a VALUE that has
* already been placed in a band, so it must NOT be: the whole point of a band is that two
* cells one band apart are visibly different, which a 24-step ramp deliberately prevents —
* the same reason a continuous scale made 976 ms, 2519 ms and 4713 ms read as one colour.
*
* THE CALLER OWNS THE BUCKETING and passes level INDICES, not values. Where a band's edges
* fall — absolute thresholds, or quantiles of the visible window — is a claim about the
* data that only the caller can make, and a widget that guessed would bury it. So this
* paints and nothing else; `palette[0]` is the empty level and the index is clamped, so a
* caller cannot address a colour that is not there.
*
* <text><span fg={tokens.trace}>{"-3w "}</span><LevelRowSpan levels={week} palette={GH} /></text>
*
* A `<span>` form because a `<text>` cannot nest in a `<text>` — same argument as
* `BadgeSpan`, `MeterSpan` and `SparklineSpan`, and it bites hardest here: a level row is
* coloured SPACES, so a column Yoga shaved off a flex sibling would leave a stub of
* background that `captureCharFrame()` cannot see at all.
*/
export function LevelRowSpan({
levels,
palette,
}: { levels: readonly number[]; palette: readonly string[] }): ReactNode {
if (levels.length === 0 || palette.length === 0) return null;
const top = palette.length - 1;
return (
<>
{levels.map((n, i) => (
// biome-ignore lint/suspicious/noArrayIndexKey: a heat cell is position-addressed — index IS identity
<span key={i} bg={palette[Math.min(top, Math.max(0, Math.round(n)))]!}>
{" "}
</span>
))}
</>
);
}
/** One category of a `StackedBar`: how much, and in what colour. */
export type BarSegment = { value: number; color: ColorInput };
/**
* Stacked bar — the default visual for a CATEGORY DISTRIBUTION (gonzo's severity
* mix, a pass/fail/skip split), and the sixth widget because `name: count` lines are
* the anti-pattern it replaces.
*
* All the difficulty is in the apportionment, which is why `splitCells` is a tested
* pure function and this is a thin renderer over it: consecutive `<span bg>` runs of
* spaces in ONE `<text>`, so the segments abut into a continuous ribbon with no
* seams. Two renderers rounding independently drift by a cell — share the maths,
* never the drawing.
*
* The width invariant is absolute: the painted row is EXACTLY `width` columns for any
* input, so a bar never shifts the column to its right. `splitCells` guarantees the
* segments sum to `width` and that every non-zero category keeps at least one cell
* (down to `width < categories`, where the largest `width` of them get one each).
* ALL-ZERO is the one case it cannot fill — no shares to apportion — so an empty
* distribution draws a full-width TRACK row rather than collapsing to nothing. */
export function StackedBar({
segments,
width,
style,
...layout
}: WidgetLayout & {
segments: readonly BarSegment[];
width: number;
style?: WidgetLayout;
}): ReactNode {
const cells = Math.floor(width);
if (!Number.isFinite(cells) || cells <= 0 || segments.length === 0) return null;
const split = splitCells(
segments.map((s) => s.value),
cells
);
if (split.reduce((a, b) => a + b, 0) === 0)
return (
<text fg={tokens.border} flexShrink={0} {...layout} style={style}>
{TRACK.repeat(cells)}
</text>
);
return (
<text flexShrink={0} {...layout} style={style}>
{split.map((n, i) =>
n > 0 ? (
// biome-ignore lint/suspicious/noArrayIndexKey: a bar segment is position-addressed — index IS identity
<span key={i} bg={segments[i]!.color}>
{" ".repeat(n)}
</span>
) : null
)}
</text>
);
}
/** A status chip: `label` and `bg` are the chip itself; `width` is the COLUMN it sits
* in. See `badgePad` — the padding to `width` goes OUTSIDE the fill.
*
* `fg` IS THE FOURTH ADDITIVE DEVIATION FROM THE SKILL'S SHIPPED FILE, and it exists
* because `pickInk` answers a DIFFERENT question from the one a chip we own is asking.
* `pickInk` picks the more legible of the two THEME inks, which is right for a fill
* whose colour it cannot predict; but a chip whose fill we chose owns BOTH sides, so
* its ink should be deterministic rather than a function of the user's palette.
* MEASURED on `#15803d`: dark mode picks white (5.02:1), light mode picks black
* (4.02:1) — the same chip, two inks, and the worse ratio on the page where a reader
* is most likely to be squinting. Omit `fg` and nothing changes; pass `C.ink` and the
* chip reads the same in both themes. */
export type BadgeChip = { label: string; bg: ColorInput; width?: number; fg?: ColorInput };
/**
* Filler columns so a badge can hold a fixed-width COLUMN without growing its fill.
*
* PAD OUTSIDE THE CHIP, NEVER INSIDE THE LABEL. `label={padTo("UP", 8)}` looks like the
* same thing and is not: the padding lands inside `bg`, so every chip paints 10 saturated
* columns instead of 4. MEASURED on a 24-service list — 24 `UP` chips padded that way
* stacked into one solid green RECTANGLE running down the panel, no gap between rows to
* separate them, the labels floating in a field of green. Padding outside keeps each fill
* at `displayWidth(label) + 2`, so the column still aligns and the fills stay chips.
*
* `width` under the chip's own width pads nothing: a chip is never clipped, because half
* a label (`WAR`) is a worse failure than a column one cell wide. */
function badgePad(label: string, width?: number): ReactNode {
const pad = Math.max(0, (width ?? 0) - displayWidth(label) - 2);
return pad > 0 ? <span>{" ".repeat(pad)}</span> : null;
}
/**
* Status chip: dark ink on a saturated fill, one space of padding each side, so
* the badge occupies `displayWidth(label) + 2` columns — plus plain filler when a
* `width` is given. Keep the text LABEL — colour alone fails a red/green-blind reader
* and fails in grayscale.
*/
export function Badge({
label,
bg,
width,
fg,
style,
...layout
}: WidgetLayout & BadgeChip & { style?: WidgetLayout }): ReactNode {
return (
<text flexShrink={0} {...layout} style={style}>
<span fg={fg ?? pickInk(bg)} bg={bg} attributes={BOLD}>{` ${label} `}</span>
{badgePad(label, width)}
</text>
);
}
/**
* The same chip as a `<span>`, for a MIXED-CONTENT row — `<Badge>` is a `<text>`, and
* a `<text>` cannot nest in a `<text>`, so the standalone form can only ever be a row
* of its own or a cell in a flex row of boxes. Every log line and service row
* (`[WARN] disk 82%`, `api ● 12ms`) is one `<text>` by the overprint rule, so without
* this the chip has to be re-inlined by hand at each site — `pickInk(bg)` + `BOLD` +
* `` ` ${label} ` `` copied out, which is how the ink threshold and the padding drift
* apart across a codebase.
*
* <text><BadgeSpan label="WARN" bg={tokens.warn} /><span fg={tokens.text}> disk 82%</span></text>
*
* Same three props, same two-space padding, same `displayWidth(label) + 2` columns as
* `Badge`. The pair is spelled out twice rather than shared through a helper so each
* form reads as one line of JSX; change one, change the other. No layout props: a
* `<span>` is not a flex item, so its row's `<text>` owns the layout for both. */
export function BadgeSpan({ label, bg, width, fg }: BadgeChip): ReactNode {
return (
<>
<span fg={fg ?? pickInk(bg)} bg={bg} attributes={BOLD}>{` ${label} `}</span>
{badgePad(label, width)}
</>
);
}
/**
* The layout props a parent may set on a `Panel` — sizing, growth and placement, and
* deliberately NOTHING that changes how it looks. Appearance is the component's own
* API (`title`, `focused`); a call site that could pass `borderStyle="double"` or its
* own `backgroundColor` is a call site that can break "one border style, one accent"
* app-wide, so those keys are absent by construction and the compiler says so.
*
* `style` is narrowed to this same set, so `style={{ flexGrow: 1 }}` works for readers
* who reach for OpenTUI's style form while `style={{ borderStyle: "double" }}` does not
* compile. `width`/`height` are here and absent from `WidgetLayout`, which is the one
* real difference: a panel's width is a box, a widget's `width` is a cell count. */
export type PanelLayout = Pick<BoxProps, LayoutKeys | "width" | "height">;
/**
* Panel chrome — the lazygit/btop focus model. Accent border when focused, dim
* border otherwise; that contrast is what makes a multi-panel UI navigable. ONE
* border style across the whole app: mixed styles read as broken. The title is
* drawn IN the border, so no header row is needed, and `overflow="hidden"` keeps a
* title or child wider than the panel from spilling into its neighbour on an
* 80-column terminal. No outer margin — the parent owns placement.
*
* "THE PARENT OWNS PLACEMENT" IS A PROMISE THAT HAS TO BE KEPT IN THE PROPS. It was
* not: the component took `title`, `focused` and `children`, forwarded no layout prop
* and carried no rest spread, so there was no way for a parent to own anything. The
* measured cost, at 40×12 with the panel inside a `<box flexGrow={1}>`: the panel
* sized to its content and painted 3 rows — one body row — leaving 9 rows of unpainted
* terminal below it, where the same chrome props written out by hand with `flexGrow`
* painted all 12. A full-screen dashboard cannot be built out of a box that will not
* grow, and the reader who hits this abandons the component and re-types the chrome.
*
* So a parent sizes it exactly as it would size a `<box>` — one flat prop:
*
* <box flexDirection="row" gap={1} flexGrow={1}>
* <Panel title="Load" flexGrow={2}>…</Panel> // 2/3 of the width, full height
* <Panel title="Log" flexGrow={1}>…</Panel> // 1/3
* </box>
*
* There is deliberately no default `flexGrow`: growth is placement, placement is the
* parent's, and a component that grows on its own would balloon a one-row status strip
* to fill the screen. Pass it, and the panel fills what it is given. The spread sits
* AFTER the chrome props so sizing always wins, and the layout type cannot reach the
* chrome to contradict it.
*
* `flush` DROPS THE HORIZONTAL PADDING, for the one case the default gets wrong: a
* SELECTION LIST. The 1-column gutter is right for a form or a paragraph, and wrong for
* rows that carry their own full-width cursor highlight — the highlight stops a column
* short of the border on both sides, so the selected row reads as a floating chip rather
* than as a bar, and every row loses two columns of the text it is scanned by. It is on
* the component's own API (like `title` and `focused`) rather than in `PanelLayout`,
* because padding is appearance and appearance is not the parent's to set arbitrarily;
* this is one named, documented choice, not an open door to per-call-site chrome. A
* flush panel's children own the edge, so they must size themselves to `width - 2`.
*/
export function Panel({
title,
focused = false,
flush = false,
children,
style,
...layout
}: PanelLayout & {
title: string;
focused?: boolean;
flush?: boolean;
children?: ReactNode;
style?: PanelLayout;
}): ReactNode {
return (
<box
border
borderStyle="rounded"
borderColor={focused ? tokens.accent : tokens.border}
backgroundColor={tokens.bgPanel}
title={title}
titleAlignment="left"
flexDirection="column"
overflow="hidden"
paddingLeft={flush ? 0 : 1}
paddingRight={flush ? 0 : 1}
{...layout}
style={style}
>
{children}
</box>
);
}