@mnmal-ai/surface-kit 0.16.0 → 0.17.1

package/dist/index.d.ts

@@ -1,5 +1,7 @@
 export { BAR_GLYPH, barFrame } from './bar.js';
 export { cellWidth, cutToWidth, padCells, truncateCells } from './cells.js';
+export { filterRows, LIST_GUTTER, LIST_INDENT, LIST_ORDINAL_GAP, LIST_VALUE_GAP, type ListLine, type ListRow, type ListSpan, type ListSpec, listLines, wrapCells } from './list.js';
+export { ListRows, type ListRowsProps } from './list-view.js';
 export { type MarkdownSpan, type MarkdownStyle, markdownSpans } from './markdown.js';
 export { Panel, type PanelProps } from './panel.js';
 export { sparkline } from './sparkline.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AAC/C,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAC5E,OAAO,EAAE,KAAK,YAAY,EAAE,KAAK,aAAa,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AACrF,OAAO,EAAE,KAAK,EAAE,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AACpD,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AAC/C,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAC5E,OAAO,EACL,UAAU,EACV,WAAW,EACX,WAAW,EACX,gBAAgB,EAChB,cAAc,EACd,KAAK,QAAQ,EACb,KAAK,OAAO,EACZ,KAAK,QAAQ,EACb,KAAK,QAAQ,EACb,SAAS,EACT,SAAS,EACV,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,QAAQ,EAAE,KAAK,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAC9D,OAAO,EAAE,KAAK,YAAY,EAAE,KAAK,aAAa,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AACrF,OAAO,EAAE,KAAK,EAAE,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AACpD,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC"}

package/dist/index.js

@@ -1,8 +1,40 @@
 import { a as sparkline, c as barFrame, i as spinnerFrame, n as BRAILLE_RING, o as markdownSpans, r as SPINNER, s as BAR_GLYPH, t as BOX_CHASE } from "./spinner-DIFSSHah.js";
 import { cellWidth, cutToWidth, padCells, truncateCells } from "./cells.js";
+import { LIST_GUTTER, LIST_INDENT, LIST_ORDINAL_GAP, LIST_VALUE_GAP, filterRows, listLines, wrapCells } from "./list.js";
 import { Box, Text } from "ink";
 import { jsx, jsxs } from "react/jsx-runtime";
 
+//#region src/list-view.tsx
+/** Laid-out list lines, one terminal line each: dim ordinal, name, dim details, value. */
+function ListRows({ lines, theme, cursor }) {
+	const detailColumn = lines.some((l) => l.detail !== "");
+	return /* @__PURE__ */ jsx(Box, {
+		flexDirection: "column",
+		children: lines.map((l, i) => /* @__PURE__ */ jsxs(Text, {
+			wrap: "truncate",
+			...i === cursor ? { backgroundColor: theme.color.selection } : {},
+			children: [
+				" ".repeat(2),
+				l.ordinal !== "" ? /* @__PURE__ */ jsx(Text, {
+					color: theme.color.dim,
+					children: l.ordinal + " ".repeat(2)
+				}) : null,
+				l.name.map((s, j) => s.em === true ? /* @__PURE__ */ jsx(Text, {
+					bold: true,
+					italic: true,
+					children: s.text
+				}, j) : /* @__PURE__ */ jsx(Text, { children: s.text }, j)),
+				detailColumn ? /* @__PURE__ */ jsx(Text, {
+					color: theme.color.dim,
+					children: " ".repeat(3) + l.detail
+				}) : null,
+				l.value !== "" ? /* @__PURE__ */ jsx(Text, { children: " ".repeat(2) + l.value }) : null
+			]
+		}, i))
+	});
+}
+
+//#endregion
 //#region src/panel.tsx
 /** The panel anatomy: a single-line border in the panel's tone and an upper-case title line led by `theme.glyph.title`. */
 function Panel({ title, theme, tone = "accent", width, ground, children }) {
@@ -24,4 +56,4 @@ function Panel({ title, theme, tone = "accent", width, ground, children }) {
 }
 
 //#endregion
-export { BAR_GLYPH, BOX_CHASE, BRAILLE_RING, Panel, SPINNER, barFrame, cellWidth, cutToWidth, markdownSpans, padCells, sparkline, spinnerFrame, truncateCells };
+export { BAR_GLYPH, BOX_CHASE, BRAILLE_RING, LIST_GUTTER, LIST_INDENT, LIST_ORDINAL_GAP, LIST_VALUE_GAP, ListRows, Panel, SPINNER, barFrame, cellWidth, cutToWidth, filterRows, listLines, markdownSpans, padCells, sparkline, spinnerFrame, truncateCells, wrapCells };

package/dist/list-view.d.ts

@@ -0,0 +1,13 @@
+import type { Theme } from '@mnmal-ai/surface-theme';
+import type { ReactElement } from 'react';
+import { type ListLine } from './list.js';
+export interface ListRowsProps {
+    /** From `listLines`, at the width this view draws in. */
+    readonly lines: readonly ListLine[];
+    readonly theme: Theme;
+    /** The highlighted row, on the `selection` tone as the palette's is. */
+    readonly cursor?: number;
+}
+/** Laid-out list lines, one terminal line each: dim ordinal, name, dim details, value. */
+export declare function ListRows({ lines, theme, cursor }: ListRowsProps): ReactElement;
+//# sourceMappingURL=list-view.d.ts.map

package/dist/list-view.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"list-view.d.ts","sourceRoot":"","sources":["../src/list-view.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,yBAAyB,CAAC;AAErD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,OAAO,CAAC;AAC1C,OAAO,EAKL,KAAK,QAAQ,EACd,MAAM,WAAW,CAAC;AAEnB,MAAM,WAAW,aAAa;IAC5B,yDAAyD;IACzD,QAAQ,CAAC,KAAK,EAAE,SAAS,QAAQ,EAAE,CAAC;IACpC,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IACtB,wEAAwE;IACxE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,0FAA0F;AAC1F,wBAAgB,QAAQ,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE,aAAa,GAAG,YAAY,CAkC9E"}

package/dist/list.d.ts

@@ -0,0 +1,44 @@
+export interface ListSpan {
+    readonly text: string;
+    readonly em?: boolean;
+}
+export interface ListRow {
+    /** Stable identity, for the app's hooks; never shown. */
+    readonly key: string;
+    /** What the row is: plain text, or spans with emphasised parts (`"*Kid A*" by *Radiohead*`). */
+    readonly name: string | readonly ListSpan[];
+    /** Quieter facts beside the name, joined with ` · `. */
+    readonly details?: readonly string[];
+    /** One figure per row (money, a count, a score), right-aligned in its own column. */
+    readonly value?: string;
+}
+export interface ListSpec {
+    readonly heading: string;
+    readonly rows: readonly ListRow[];
+    /** All matches, when the rows are only some of them. */
+    readonly total?: number;
+    /** Asides drawn after the rows. */
+    readonly notes?: readonly string[];
+}
+export interface ListLine {
+    /** Right-aligned to the widest ordinal. */
+    readonly ordinal: string;
+    /** Fitted, and padded to the shared name width when a detail or value column follows. */
+    readonly name: readonly ListSpan[];
+    /** ` · `-joined details, fitted; padded to the detail column when a value column follows. */
+    readonly detail: string;
+    /** Right-aligned to the value column; '' when no row has a value. */
+    readonly value: string;
+}
+/** The gaps the view draws: before the ordinal, after it, before the details, before the value. */
+export declare const LIST_INDENT = 2;
+export declare const LIST_ORDINAL_GAP = 2;
+export declare const LIST_GUTTER = 3;
+export declare const LIST_VALUE_GAP = 2;
+/** One line per row in `width` cells, numbered from `firstOrdinal`. */
+export declare function listLines(rows: readonly ListRow[], width: number, firstOrdinal?: number): ListLine[];
+/** Rows whose name or details contain `filter`, ignoring case. An empty filter keeps them all. */
+export declare function filterRows(rows: readonly ListRow[], filter: string): ListRow[];
+/** `text` wrapped to `width` cells on spaces; a word longer than the width is cut. */
+export declare function wrapCells(text: string, width: number): string[];
+//# sourceMappingURL=list.d.ts.map

package/dist/list.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"list.d.ts","sourceRoot":"","sources":["../src/list.ts"],"names":[],"mappings":"AAMA,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,CAAC,EAAE,OAAO,CAAC;CACvB;AAED,MAAM,WAAW,OAAO;IACtB,yDAAyD;IACzD,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,gGAAgG;IAChG,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,QAAQ,EAAE,CAAC;IAC5C,wDAAwD;IACxD,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,qFAAqF;IACrF,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,SAAS,OAAO,EAAE,CAAC;IAClC,wDAAwD;IACxD,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,mCAAmC;IACnC,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACpC;AAED,MAAM,WAAW,QAAQ;IACvB,2CAA2C;IAC3C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,yFAAyF;IACzF,QAAQ,CAAC,IAAI,EAAE,SAAS,QAAQ,EAAE,CAAC;IACnC,6FAA6F;IAC7F,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,qEAAqE;IACrE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,mGAAmG;AACnG,eAAO,MAAM,WAAW,IAAI,CAAC;AAC7B,eAAO,MAAM,gBAAgB,IAAI,CAAC;AAClC,eAAO,MAAM,WAAW,IAAI,CAAC;AAC7B,eAAO,MAAM,cAAc,IAAI,CAAC;AAuDhC,uEAAuE;AACvE,wBAAgB,SAAS,CAAC,IAAI,EAAE,SAAS,OAAO,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,YAAY,SAAI,GAAG,QAAQ,EAAE,CA8C/F;AAED,kGAAkG;AAClG,wBAAgB,UAAU,CAAC,IAAI,EAAE,SAAS,OAAO,EAAE,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,EAAE,CAM9E;AAED,sFAAsF;AACtF,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CA6B/D"}

package/dist/list.js

@@ -0,0 +1,121 @@
+import { cellWidth, cutToWidth, padCells, truncateCells } from "./cells.js";
+
+//#region src/list.ts
+/** The gaps the view draws: before the ordinal, after it, before the details, before the value. */
+const LIST_INDENT = 2;
+const LIST_ORDINAL_GAP = 2;
+const LIST_GUTTER = 3;
+const LIST_VALUE_GAP = 2;
+/** The narrowest a shortened detail cell is cut to: below this an ellipsis says nothing. */
+const MIN_CELL = 8;
+/** A detail column is not squeezed below this while the name can give way. */
+const MIN_DETAIL = 16;
+/** A name is not cut below this while a value column can give way. */
+const MIN_NAME = 8;
+const DETAIL_SEP = " · ";
+const EMPTY = "—";
+const spansOf = (name) => typeof name === "string" ? [{ text: name }] : name;
+const spanText = (spans) => spans.map((s) => s.text).join("");
+const detailsOf = (r) => (r.details ?? []).filter((d) => d !== "");
+/** Spans cut to `max` cells, ending in `…` when anything was cut. */
+function fitSpans(spans, max) {
+	if (cellWidth(spanText(spans)) <= max) return [...spans];
+	if (max <= 1) return [{ text: cutToWidth(spanText(spans), Math.max(0, max)) }];
+	const out = [];
+	let left = max - 1;
+	for (const s of spans) {
+		if (left <= 0) break;
+		const t = cutToWidth(s.text, left);
+		out.push(s.em === true ? {
+			text: t,
+			em: true
+		} : { text: t });
+		left -= cellWidth(t);
+		if (t !== s.text) break;
+	}
+	out.push({ text: "…" });
+	return out;
+}
+/** Details fitted into `room` by shortening the longest cell first, so short facts survive. */
+function fitCells(cells, room) {
+	const out = [...cells];
+	const length = () => cellWidth(out.join(DETAIL_SEP));
+	while (length() > room) {
+		let longest = -1;
+		for (const [i, c] of out.entries()) if (cellWidth(c) > MIN_CELL && (longest < 0 || cellWidth(c) > cellWidth(out[longest] ?? ""))) longest = i;
+		if (longest < 0) return truncateCells(out.join(DETAIL_SEP), room);
+		const c = out[longest] ?? "";
+		out[longest] = truncateCells(c, Math.max(MIN_CELL, cellWidth(c) - (length() - room)));
+	}
+	return out.join(DETAIL_SEP);
+}
+/** One line per row in `width` cells, numbered from `firstOrdinal`. */
+function listLines(rows, width, firstOrdinal = 1) {
+	const ordinals = rows.map((_, i) => String(firstOrdinal + i));
+	const ordW = Math.max(0, ...ordinals.map((o) => o.length));
+	const names = rows.map((r) => spansOf(r.name));
+	const details = rows.map(detailsOf);
+	const hasValue = rows.some((r) => r.value !== void 0 && r.value !== "");
+	const values = rows.map((r) => r.value === void 0 || r.value === "" ? EMPTY : r.value);
+	const avail0 = width - 2 - (ordW > 0 ? ordW + 2 : 0);
+	const valW = hasValue ? Math.max(1, Math.min(Math.max(...values.map(cellWidth)), Math.floor(width / 3), avail0 - 2 - MIN_NAME)) : 0;
+	const avail = avail0 - (hasValue ? valW + 2 : 0);
+	const detailWidth = Math.max(0, ...details.map((d) => cellWidth(d.join(DETAIL_SEP))));
+	const nameNatural = Math.max(0, ...names.map((n) => cellWidth(spanText(n))));
+	const detailFloor = detailWidth > 0 ? 3 + Math.min(detailWidth, MIN_DETAIL) : 0;
+	const nameWidth = Math.max(1, Math.min(MIN_NAME, avail), Math.min(nameNatural, avail - detailFloor));
+	const detailRoom = Math.max(0, avail - nameWidth - (detailWidth > 0 ? 3 : 0));
+	const padName = detailWidth > 0 || hasValue;
+	return rows.map((_, i) => {
+		const fitted = fitSpans(names[i] ?? [], nameWidth);
+		const pad = padName ? nameWidth - cellWidth(spanText(fitted)) : 0;
+		const name = pad > 0 ? [...fitted, { text: " ".repeat(pad) }] : fitted;
+		const cells = details[i] ?? [];
+		const fit = cells.length === 0 || detailRoom === 0 ? "" : fitCells(cells, detailRoom);
+		const detail = hasValue && detailRoom > 0 && detailWidth > 0 ? padCells(fit, detailRoom) : fit;
+		return {
+			ordinal: ordinals[i]?.padStart(ordW) ?? "",
+			name,
+			detail,
+			value: hasValue ? padCells(truncateCells(values[i] ?? EMPTY, valW), valW, true) : ""
+		};
+	});
+}
+/** Rows whose name or details contain `filter`, ignoring case. An empty filter keeps them all. */
+function filterRows(rows, filter) {
+	const f = filter.toLowerCase();
+	if (f === "") return [...rows];
+	return rows.filter((r) => `${spanText(spansOf(r.name))} ${detailsOf(r).join(" ")}`.toLowerCase().includes(f));
+}
+/** `text` wrapped to `width` cells on spaces; a word longer than the width is cut. */
+function wrapCells(text, width) {
+	const w = Math.max(1, width);
+	const out = [];
+	for (const para of text.split("\n")) {
+		const start = out.length;
+		let line = "";
+		for (let word of para.split(" ").filter((x) => x !== "")) {
+			while (cellWidth(word) > w) {
+				if (line !== "") {
+					out.push(line);
+					line = "";
+				}
+				const head = cutToWidth(word, w) || ([...word][0] ?? "");
+				out.push(head);
+				word = word.slice(head.length);
+			}
+			if (word === "") continue;
+			const next = line === "" ? word : `${line} ${word}`;
+			if (cellWidth(next) <= w) line = next;
+			else {
+				out.push(line);
+				line = word;
+			}
+		}
+		if (line !== "" || out.length === start) out.push(line);
+	}
+	return out;
+}
+
+//#endregion
+export { LIST_GUTTER, LIST_INDENT, LIST_ORDINAL_GAP, LIST_VALUE_GAP, filterRows, listLines, wrapCells };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mnmal-ai/surface-kit",
-  "version": "0.16.0",
+  "version": "0.17.1",
   "description": "Stateless Ink view primitives for surface terminal UIs: panels, cells, markdown spans, spinners, sparklines.",
   "license": "Apache-2.0",
   "repository": {
@@ -21,13 +21,17 @@
     "./text": {
       "types": "./dist/text.d.ts",
       "import": "./dist/text.js"
+    },
+    "./list": {
+      "types": "./dist/list.d.ts",
+      "import": "./dist/list.js"
     }
   },
   "files": [
     "dist"
   ],
   "dependencies": {
-    "@mnmal-ai/surface-theme": "0.16.0",
+    "@mnmal-ai/surface-theme": "0.17.1",
     "string-width": "^8.1.0"
   },
   "peerDependencies": {