take4-console 0.15.0

package/src/Screen/controls/LineChart.mts

@@ -0,0 +1,202 @@
+import type { LineChartProperties, WindowProperties, StyleId } from '../types.mjs';
+import { Window } from '../Window.mjs';
+import { getRegistry } from '../RegistryHolder.mjs';
+
+/** Formats a Y-axis label value as a compact string. */
+function formatYLabel(value: number): string {
+	if (Number.isInteger(value)) return String(value);
+	const rounded = Math.round(value * 10) / 10;
+	return String(rounded);
+}
+
+/** A read-only line chart that renders a data series using box-drawing characters.
+ *  Includes a labelled Y-axis on the left and an X-axis at the bottom. */
+export class LineChart extends Window {
+	private data:     number[];
+	private minValue: number | undefined;
+	private maxValue: number | undefined;
+
+	private lineStyleId:  StyleId;
+	private axisStyleId:  StyleId;
+	private labelStyleId: StyleId;
+
+	/** Creates a LineChart from window properties and optional control-specific properties.
+	 *  Uses the global StyleRegistry set by the Screen constructor. */
+	public constructor(wp: WindowProperties, cp?: LineChartProperties) {
+		super(wp);
+
+		this.data     = cp?.data ?? [];
+		this.minValue = cp?.min;
+		this.maxValue = cp?.max;
+
+		const reg = getRegistry();
+		this.lineStyleId  = reg.register({ foreground: cp?.color ?? 75 });
+		this.axisStyleId  = reg.register({ foreground: 245 });
+		this.labelStyleId = reg.register({ foreground: 245 });
+	}
+
+	/** Sets the data series. Call render() afterwards. */
+	public setData(data: number[]): void {
+		this.data = data;
+	}
+
+	/** Returns the current data series. */
+	public getData(): number[] {
+		return this.data;
+	}
+
+	/** Sets the minimum Y value. Pass undefined to derive from data. Call render() afterwards. */
+	public setMin(min: number | undefined): void {
+		this.minValue = min;
+	}
+
+	/** Returns the configured minimum Y value, or undefined if derived from data. */
+	public getMin(): number | undefined {
+		return this.minValue;
+	}
+
+	/** Sets the maximum Y value. Pass undefined to derive from data. Call render() afterwards. */
+	public setMax(max: number | undefined): void {
+		this.maxValue = max;
+	}
+
+	/** Returns the configured maximum Y value, or undefined if derived from data. */
+	public getMax(): number | undefined {
+		return this.maxValue;
+	}
+
+	public override render(): void {
+		this.clear();
+
+		const { width, height } = this.getInnerSize();
+		const { x: ox, y: oy } = this.getInnerOffset();
+
+		if (width < 4 || height < 3) {
+			super.render();
+			return;
+		}
+
+		// ── 1. Resolve data range ───────────────────────��───────────────────────
+		const dataMin   = this.minValue ?? (this.data.length > 0 ? Math.min(...this.data) : 0);
+		const dataMax   = this.maxValue ?? (this.data.length > 0 ? Math.max(...this.data) : 1);
+		const dataRange = dataMax - dataMin;
+
+		// ── 2. Compute Y-axis label width ────────────────────────────────────────
+		const numYLabels   = Math.min(5, Math.max(2, height - 1));
+		const yLabelValues = Array.from({ length: numYLabels }, (_, k) =>
+			dataMin + (k / (numYLabels - 1)) * dataRange,
+		);
+		const yLabelStrs   = yLabelValues.map(formatYLabel);
+		const maxLabelLen  = Math.max(...yLabelStrs.map(s => s.length));
+		const yLabelWidth  = maxLabelLen + 2;  // space + label + '┤'
+
+		// ── 3. Plot dimensions ───────────────────────��───────────────────────────
+		const plotW = width  - yLabelWidth;
+		const plotH = height - 1;  // last row = X-axis
+
+		if (plotW < 1 || plotH < 1) {
+			super.render();
+			return;
+		}
+
+		/** Maps a value to a plot row (0 = top = dataMax). */
+		const valueToRow = (v: number): number => {
+			if (dataRange === 0) return Math.floor((plotH - 1) / 2);
+			const norm = Math.min(1, Math.max(0, (v - dataMin) / dataRange));
+			return (plotH - 1) - Math.round(norm * (plotH - 1));
+		};
+
+		// ── 4. Draw Y-axis ───────────────────��────────────────────────────────────
+		const yAxisAbsX = ox + yLabelWidth - 1;  // column of '┤' / '│'
+
+		// Draw vertical line for all plot rows
+		for (let row = 0; row < plotH; row++) {
+			this.setCell(yAxisAbsX, oy + row, '│', this.axisStyleId);
+		}
+
+		// Overwrite with '┤' and labels at each label row
+		for (let k = 0; k < numYLabels; k++) {
+			// k=0 → bottom label (dataMin), k=numYLabels-1 → top label (dataMax)
+			const labelValue = yLabelValues[k];
+			const labelRow   = valueToRow(labelValue);
+			const labelStr   = yLabelStrs[k];
+			// Right-justify within maxLabelLen columns starting at ox
+			const padded     = labelStr.padStart(maxLabelLen);
+			this.setCell(yAxisAbsX, oy + labelRow, '┤', this.axisStyleId);
+			for (let c = 0; c < padded.length; c++) {
+				this.setCell(ox + c, oy + labelRow, padded[c], this.labelStyleId);
+			}
+		}
+
+		// ── 5. Draw X-axis ─────────────────────────���─────────────────────────���────
+		const xAxisAbsY = oy + plotH;
+		for (let col = 0; col < plotW; col++) {
+			const absX = ox + yLabelWidth + col;
+			this.setCell(absX, xAxisAbsY, col === 0 ? '┼' : '─', this.axisStyleId);
+		}
+		// Y-axis bottom corner
+		this.setCell(yAxisAbsX, xAxisAbsY, '┼', this.axisStyleId);
+
+		// ── 6. Plot the line ──────────────────────────────────────────────────────
+		if (this.data.length === 0) {
+			super.render();
+			return;
+		}
+
+		// Build an interpolated row index for every plot column. With more
+		// columns than data points, this upsamples the series; with fewer,
+		// it averages between adjacent samples.
+		const dataRow: number[] = new Array(plotW);
+		if (this.data.length === 1) {
+			const r0 = valueToRow(this.data[0]);
+			for (let c = 0; c < plotW; c++) dataRow[c] = r0;
+		} else {
+			for (let c = 0; c < plotW; c++) {
+				const t    = (c / (plotW - 1)) * (this.data.length - 1);
+				const i0   = Math.floor(t);
+				const i1   = Math.min(i0 + 1, this.data.length - 1);
+				const frac = t - i0;
+				const v    = this.data[i0] * (1 - frac) + this.data[i1] * frac;
+				dataRow[c] = valueToRow(v);
+			}
+		}
+
+		/** Draws a single line cell in plot space. */
+		const plot = (col: number, row: number, ch: string): void => {
+			this.setCell(ox + yLabelWidth + col, oy + row, ch, this.lineStyleId);
+		};
+
+		// Each column either holds a flat horizontal segment or a self-contained
+		// vertical step bridging the previous column's row to this column's row.
+		// The first column has no incoming step.
+		plot(0, dataRow[0], '─');
+
+		for (let c = 1; c < plotW; c++) {
+			const inRow  = dataRow[c - 1];
+			const outRow = dataRow[c];
+
+			if (inRow === outRow) {
+				plot(c, outRow, '─');
+				continue;
+			}
+
+			const top = Math.min(inRow, outRow);
+			const bot = Math.max(inRow, outRow);
+
+			if (outRow < inRow) {
+				// Going up: line enters from left at the bottom, exits right at the top.
+				plot(c, bot, '╯');  // LEFT + TOP
+				plot(c, top, '╭');  // BOTTOM + RIGHT
+			} else {
+				// Going down: line enters from left at the top, exits right at the bottom.
+				plot(c, top, '╮');  // LEFT + BOTTOM
+				plot(c, bot, '╰');  // TOP + RIGHT
+			}
+			for (let row = top + 1; row < bot; row++) {
+				plot(c, row, '│');
+			}
+		}
+
+		super.render();
+	}
+}

package/src/Screen/controls/ListBox.mts

@@ -0,0 +1,154 @@
+import type { ListBoxProperties, WindowProperties, StyleId } from '../types.mjs';
+import { Window } from '../Window.mjs';
+import { getRegistry } from '../RegistryHolder.mjs';
+
+/** A scrollable list of single-line items. The selected item is highlighted and may
+ *  be moved with arrow keys, PgUp/PgDn, and Home/End. Emits onChange whenever the
+ *  selection index changes via keyboard. Appearance follows the same built-in style
+ *  naming scheme as the other focusable controls. */
+export class ListBox extends Window {
+	private items: string[];
+	private selectedIndex: number;
+	private scrollTop: number;
+	private onChange?: (index: number, item: string) => void;
+	private selectedStyleId:  StyleId;
+	private focusedSelStyle:  StyleId;
+
+	/** Creates a ListBox from window properties and optional control-specific properties.
+	 *  Uses the global StyleRegistry set by the Screen constructor. */
+	public constructor(wp: WindowProperties, cp?: ListBoxProperties) {
+		super({
+			...wp,
+			defaultBorder: { top: true, right: true, bottom: true, left: true, style: 'single' },
+		});
+
+		this.items         = cp?.items ?? [];
+		this.onChange      = cp?.onChange;
+		this.scrollTop     = 0;
+		this.selectedIndex = cp?.selectedIndex ?? (this.items.length > 0 ? 0 : -1);
+
+		// Selected row: muted highlight when unfocused, bright inverse when focused.
+		const reg = getRegistry();
+		this.selectedStyleId = reg.register({ background: 238, foreground: 252 });
+		this.focusedSelStyle = reg.register({ background: 75, foreground: 231, bold: true });
+	}
+
+	/** Replaces the list items. Resets selection to 0 (or -1 if empty) and scrolls to top. */
+	public setItems(items: string[]): void {
+		this.items         = items;
+		this.selectedIndex = items.length > 0 ? 0 : -1;
+		this.scrollTop     = 0;
+	}
+
+	/** Returns the current list items. */
+	public getItems(): string[] {
+		return this.items;
+	}
+
+	/** Sets the selected index. Clamped to valid range; -1 allowed only when items is empty. */
+	public setSelectedIndex(index: number): void {
+		if (this.items.length === 0) {
+			this.selectedIndex = -1;
+			return;
+		}
+		this.selectedIndex = Math.max(0, Math.min(this.items.length - 1, index));
+		this.ensureVisible();
+	}
+
+	/** Returns the currently selected index, or -1 when the list is empty. */
+	public getSelectedIndex(): number {
+		return this.selectedIndex;
+	}
+
+	/** Returns the currently selected item string, or undefined when nothing is selected. */
+	public getSelectedItem(): string | undefined {
+		if (this.selectedIndex < 0 || this.selectedIndex >= this.items.length) return undefined;
+		return this.items[this.selectedIndex];
+	}
+
+	/** Processes a key press: arrow keys, Home/End, PgUp/PgDn move the selection. */
+	public handleKey(key: string): void {
+		if (this.disabled || this.items.length === 0) return;
+
+		const prev   = this.selectedIndex;
+		const pageSz = Math.max(1, this.getInnerSize().height);
+
+		switch (key) {
+			case '\x1b[A': // Up arrow
+				this.selectedIndex = Math.max(0, this.selectedIndex - 1);
+				break;
+			case '\x1b[B': // Down arrow
+				this.selectedIndex = Math.min(this.items.length - 1, this.selectedIndex + 1);
+				break;
+			case '\x1b[H': // Home
+			case '\x1b[1~':
+				this.selectedIndex = 0;
+				break;
+			case '\x1b[F': // End
+			case '\x1b[4~':
+				this.selectedIndex = this.items.length - 1;
+				break;
+			case '\x1b[5~': // PgUp
+				this.selectedIndex = Math.max(0, this.selectedIndex - pageSz);
+				break;
+			case '\x1b[6~': // PgDn
+				this.selectedIndex = Math.min(this.items.length - 1, this.selectedIndex + pageSz);
+				break;
+			default:
+				return;
+		}
+
+		this.ensureVisible();
+		if (this.selectedIndex !== prev) {
+			this.onChange?.(this.selectedIndex, this.items[this.selectedIndex]);
+		}
+	}
+
+	/** Adjusts scrollTop so that the selected index remains within the visible window. */
+	private ensureVisible(): void {
+		const visibleRows = Math.max(1, this.getInnerSize().height);
+		if (this.selectedIndex < this.scrollTop) {
+			this.scrollTop = this.selectedIndex;
+		} else if (this.selectedIndex >= this.scrollTop + visibleRows) {
+			this.scrollTop = this.selectedIndex - visibleRows + 1;
+		}
+		// Clamp scrollTop so we don't leave trailing empty rows unless necessary.
+		const maxScroll = Math.max(0, this.items.length - visibleRows);
+		this.scrollTop  = Math.max(0, Math.min(maxScroll, this.scrollTop));
+	}
+
+	/** Rebuilds the list: renders visible rows with styles. */
+	public override render(): void {
+		this.clear();
+
+		const { width, height } = this.getInnerSize();
+		if (width < 1 || height < 1) {
+			super.render();
+			return;
+		}
+
+		this.ensureVisible();
+
+		const visibleCount = Math.min(height, this.items.length - this.scrollTop);
+		for (let row = 0; row < visibleCount; row++) {
+			const itemIndex = this.scrollTop + row;
+			const rawText   = this.items[itemIndex];
+			// Truncate to fit width; pad with spaces so the highlight covers the whole row.
+			const text      = rawText.length > width ? rawText.slice(0, width) : rawText;
+			const padded    = text + ' '.repeat(width - text.length);
+
+			let style: StyleId;
+			if (this.disabled) {
+				style = this.disabledStyleId;
+			} else if (itemIndex === this.selectedIndex) {
+				style = this.focused ? this.focusedSelStyle : this.selectedStyleId;
+			} else {
+				style = this.normalStyleId;
+			}
+
+			this.writeText(padded, { x: 0, y: row, style });
+		}
+
+		super.render();
+	}
+}

package/src/Screen/controls/ProgressBar.mts

@@ -0,0 +1,88 @@
+import type { ProgressBarProperties, WindowProperties, StyleId } from '../types.mjs';
+import { Window } from '../Window.mjs';
+import { getRegistry } from '../RegistryHolder.mjs';
+
+/** Character used for the filled portion of the bar. */
+const CHAR_FILL  = '█';
+/** Character used for the empty portion of the bar. */
+const CHAR_EMPTY = '░';
+
+/** A horizontal read-only progress bar that fills left-to-right using block characters.
+ *  Displays an optional centred percentage label over the bar. */
+export class ProgressBar extends Window {
+	private value:     number;
+	private max:       number;
+	private showLabel: boolean;
+
+	private fillStyleId:  StyleId;
+	private emptyStyleId: StyleId;
+	private labelStyleId: StyleId;
+
+	/** Creates a ProgressBar from window properties and optional control-specific properties.
+	 *  Recommended height: 1 (no border) or 3 (with border).
+	 *  Uses the global StyleRegistry set by the Screen constructor. */
+	public constructor(wp: WindowProperties, cp?: ProgressBarProperties) {
+		super(wp);
+
+		this.max       = Math.max(1, cp?.max ?? 100);
+		this.value     = Math.max(0, Math.min(cp?.value ?? 0, this.max));
+		this.showLabel = cp?.showLabel ?? true;
+
+		const reg = getRegistry();
+		this.fillStyleId  = reg.register({ background: cp?.fillColor  ?? 75  });
+		this.emptyStyleId = reg.register({ background: cp?.emptyColor ?? 237 });
+		this.labelStyleId = reg.register({ foreground: 255, bold: true });
+	}
+
+	/** Sets the current value (clamped to 0–max). Call render() afterwards. */
+	public setValue(value: number): void {
+		this.value = Math.max(0, Math.min(value, this.max));
+	}
+
+	/** Returns the current value. */
+	public getValue(): number {
+		return this.value;
+	}
+
+	/** Sets the maximum value (minimum 1). Call render() afterwards. */
+	public setMax(max: number): void {
+		this.max   = Math.max(1, max);
+		this.value = Math.min(this.value, this.max);
+	}
+
+	/** Returns the maximum value. */
+	public getMax(): number {
+		return this.max;
+	}
+
+	public override render(): void {
+		this.clear();
+
+		const { width, height } = this.getInnerSize();
+		const { x: ox, y: oy } = this.getInnerOffset();
+
+		if (width < 1 || height < 1) {
+			super.render();
+			return;
+		}
+
+		const ratio      = this.max > 0 ? Math.min(1, Math.max(0, this.value / this.max)) : 0;
+		const filledCols = Math.round(ratio * width);
+		const barRow     = Math.floor(height / 2);
+
+		for (let x = 0; x < width; x++) {
+			const isFilled = x < filledCols;
+			this.setCell(ox + x, oy + barRow, isFilled ? CHAR_FILL : CHAR_EMPTY,
+				isFilled ? this.fillStyleId : this.emptyStyleId);
+		}
+
+		if (this.showLabel) {
+			const pct    = Math.round(ratio * 100);
+			const text   = `${pct}%`;
+			const labelX = Math.max(0, Math.floor((width - text.length) / 2));
+			this.writeText(text, { x: labelX, y: barRow, style: this.labelStyleId });
+		}
+
+		super.render();
+	}
+}

package/src/Screen/controls/ProgressBarV.mts

@@ -0,0 +1,77 @@
+import type { ProgressBarVProperties, WindowProperties, StyleId } from '../types.mjs';
+import { Window } from '../Window.mjs';
+import { getRegistry } from '../RegistryHolder.mjs';
+
+/** Character used for the filled portion of the bar. */
+const CHAR_FILL  = '█';
+/** Character used for the empty portion of the bar. */
+const CHAR_EMPTY = '░';
+
+/** A vertical read-only progress bar that fills from the bottom upward using block characters. */
+export class ProgressBarV extends Window {
+	private value: number;
+	private max:   number;
+
+	private fillStyleId:  StyleId;
+	private emptyStyleId: StyleId;
+
+	/** Creates a ProgressBarV from window properties and optional control-specific properties.
+	 *  Uses the global StyleRegistry set by the Screen constructor. */
+	public constructor(wp: WindowProperties, cp?: ProgressBarVProperties) {
+		super(wp);
+
+		this.max   = Math.max(1, cp?.max ?? 100);
+		this.value = Math.max(0, Math.min(cp?.value ?? 0, this.max));
+
+		const reg = getRegistry();
+		this.fillStyleId  = reg.register({ background: cp?.fillColor  ?? 75  });
+		this.emptyStyleId = reg.register({ background: cp?.emptyColor ?? 237 });
+	}
+
+	/** Sets the current value (clamped to 0–max). Call render() afterwards. */
+	public setValue(value: number): void {
+		this.value = Math.max(0, Math.min(value, this.max));
+	}
+
+	/** Returns the current value. */
+	public getValue(): number {
+		return this.value;
+	}
+
+	/** Sets the maximum value (minimum 1). Call render() afterwards. */
+	public setMax(max: number): void {
+		this.max   = Math.max(1, max);
+		this.value = Math.min(this.value, this.max);
+	}
+
+	/** Returns the maximum value. */
+	public getMax(): number {
+		return this.max;
+	}
+
+	public override render(): void {
+		this.clear();
+
+		const { width, height } = this.getInnerSize();
+		const { x: ox, y: oy } = this.getInnerOffset();
+
+		if (width < 1 || height < 1) {
+			super.render();
+			return;
+		}
+
+		const ratio      = this.max > 0 ? Math.min(1, Math.max(0, this.value / this.max)) : 0;
+		const filledRows = Math.round(ratio * height);
+
+		for (let row = 0; row < height; row++) {
+			const isFilled = row >= (height - filledRows);
+			const char     = isFilled ? CHAR_FILL : CHAR_EMPTY;
+			const styleId  = isFilled ? this.fillStyleId : this.emptyStyleId;
+			for (let col = 0; col < width; col++) {
+				this.setCell(ox + col, oy + row, char, styleId);
+			}
+		}
+
+		super.render();
+	}
+}

package/src/Screen/controls/Radio.mts

@@ -0,0 +1,66 @@
+import type { RadioProperties, WindowProperties, StyleId } from '../types.mjs';
+import { BUILTIN_TEXT_CHECKED } from '../types.mjs';
+import { Window } from '../Window.mjs';
+import { Size } from '../Size.mjs';
+import { getRegistry } from '../RegistryHolder.mjs';
+
+/** Width of the indicator prefix: `(●) ` = 4 columns. */
+const INDICATOR_WIDTH = 4;
+
+/** A single-selection radio control rendering `(●) label` (selected) or `( ) label` (unselected).
+ *  Width is derived automatically from the label length when size is not provided.
+ *  Group management (ensuring at most one is selected) is the caller's responsibility. */
+export class Radio extends Window {
+	private checked: boolean;
+	private onChange?: (checked: boolean) => void;
+	private checkedStyleId: StyleId;
+
+	/** Creates a Radio button from window properties and optional control-specific properties.
+	 *  When wp.size is omitted, width is computed from wp.label automatically.
+	 *  Uses the global StyleRegistry set by the Screen constructor. */
+	public constructor(wp: WindowProperties, cp?: RadioProperties) {
+		const label = wp.label ?? '';
+		const size  = wp.size ?? new Size(INDICATOR_WIDTH + label.length, 1);
+		super({ ...wp, size });
+
+		this.checked  = cp?.checked  ?? false;
+		this.onChange = cp?.onChange;
+
+		this.checkedStyleId = getRegistry().getNamed(BUILTIN_TEXT_CHECKED)!;
+	}
+
+	/** Sets the selected state. */
+	public setChecked(checked: boolean): void {
+		this.checked = checked;
+	}
+
+	/** Returns the current selected state. */
+	public isChecked(): boolean {
+		return this.checked;
+	}
+
+	/** Processes a key press; Space selects this radio button and fires onChange. */
+	public handleKey(key: string): void {
+		if (this.disabled) return;
+		if (key === ' ' || key === 'space') {
+			this.checked = true;
+			this.onChange?.(true);
+		}
+	}
+
+	/** Rebuilds the radio button: draws indicator and label with appropriate styles. */
+	public override render(): void {
+		this.clear();
+
+		const indicator      = this.checked ? '(●)' : '( )';
+		// For indicator: use checkedStyleId when checked (and not disabled); auto-pick otherwise.
+		const indicatorStyle = (!this.disabled && this.checked) ? this.checkedStyleId : undefined;
+
+		// Write indicator (first 3 chars) and label separately to allow distinct colouring.
+		// Label uses auto-style (disabled/focused/normal via writeText).
+		this.writeText(indicator, { style: indicatorStyle });
+		this.writeText(` ${this.label}`, { x: INDICATOR_WIDTH - 1 });
+
+		super.render();
+	}
+}

package/src/Screen/controls/Sparkline.mts

@@ -0,0 +1,101 @@
+import type { SparklineProperties, WindowProperties, StyleId } from '../types.mjs';
+import { Window } from '../Window.mjs';
+import { getRegistry } from '../RegistryHolder.mjs';
+
+/** Eight-level block character ramp from empty → full. */
+const RAMP = [' ', '▁', '▂', '▃', '▄', '▅', '▆', '▇', '█'] as const;
+
+/** A one-row inline sparkline chart using block-character glyphs. Ideal for
+ *  tucking a live trend indicator into status bars, table rows, or tight
+ *  spaces where a full LineChart would be overkill. The control can be any
+ *  height, but only the last row is used for the glyphs. */
+export class Sparkline extends Window {
+	private data:     number[];
+	private minValue: number | undefined;
+	private maxValue: number | undefined;
+
+	private glyphStyleId: StyleId;
+
+	/** Creates a Sparkline from window properties and optional control-specific properties.
+	 *  Uses the global StyleRegistry set by the Screen constructor. */
+	public constructor(wp: WindowProperties, cp?: SparklineProperties) {
+		super(wp);
+
+		this.data     = cp?.data ?? [];
+		this.minValue = cp?.min;
+		this.maxValue = cp?.max;
+
+		this.glyphStyleId = getRegistry().register({ foreground: cp?.color ?? 75 });
+	}
+
+	/** Sets the data series. Call render() afterwards. */
+	public setData(data: number[]): void {
+		this.data = data;
+	}
+
+	/** Returns the current data series. */
+	public getData(): number[] {
+		return this.data;
+	}
+
+	/** Sets the minimum value. Pass undefined to derive from data. Call render() afterwards. */
+	public setMin(min: number | undefined): void {
+		this.minValue = min;
+	}
+
+	/** Returns the configured minimum value, or undefined if derived from data. */
+	public getMin(): number | undefined {
+		return this.minValue;
+	}
+
+	/** Sets the maximum value. Pass undefined to derive from data. Call render() afterwards. */
+	public setMax(max: number | undefined): void {
+		this.maxValue = max;
+	}
+
+	/** Returns the configured maximum value, or undefined if derived from data. */
+	public getMax(): number | undefined {
+		return this.maxValue;
+	}
+
+	public override render(): void {
+		this.clear();
+
+		const { width, height } = this.getInnerSize();
+		const { x: ox, y: oy } = this.getInnerOffset();
+
+		if (width < 1 || height < 1 || this.data.length === 0) {
+			super.render();
+			return;
+		}
+
+		const dataMin = this.minValue ?? Math.min(...this.data);
+		const dataMax = this.maxValue ?? Math.max(...this.data);
+		const range   = dataMax - dataMin;
+
+		// Glyphs live on the bottom-most row of the inner area; any rows above
+		// remain blank (useful when the caller wants the sparkline aligned to
+		// the baseline of a taller container).
+		const row = oy + height - 1;
+
+		for (let c = 0; c < width; c++) {
+			// Map column → fractional data index so that width != data.length still works.
+			let value: number;
+			if (this.data.length === 1) {
+				value = this.data[0];
+			} else {
+				const t    = (c / Math.max(1, width - 1)) * (this.data.length - 1);
+				const i0   = Math.floor(t);
+				const i1   = Math.min(i0 + 1, this.data.length - 1);
+				const frac = t - i0;
+				value      = this.data[i0] * (1 - frac) + this.data[i1] * frac;
+			}
+
+			const norm  = range > 0 ? Math.min(1, Math.max(0, (value - dataMin) / range)) : 0.5;
+			const level = Math.round(norm * (RAMP.length - 1));
+			this.setCell(ox + c, row, RAMP[level], this.glyphStyleId);
+		}
+
+		super.render();
+	}
+}