@bindtty/text 0.1.0-alpha.1

package/README.md

@@ -0,0 +1,17 @@
+# @bindtty/text
+
+Plain terminal text measurement and wrapping utilities for BindTTY.
+
+**现行规范**：[doc/specs/DISPLAY_WIDTH.md](../../doc/specs/DISPLAY_WIDTH.md)
+
+MVP scope:
+
+- Plain text only.
+- Display-width-aware measurement via `string-width`.
+- Grapheme segmentation via `Intl.Segmenter`, with code point fallback.
+- CJK, common emoji, and combining mark measurement.
+- Display-column wrap, hard wrap, truncate, and slice helpers.
+- Wrap and hard-wrap preserve whole graphemes; if one grapheme is wider than the target width, the produced line may be wider than the target.
+- Truncate helpers keep output display width within the target width.
+- No embedded ANSI escape support.
+- Complex ZWJ emoji sequence behavior follows the package display-width oracle and is not font/terminal perfect.

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export { layoutText, normalizeWrapMode, readTextWrapMode } from "./layout.js";
+export { measureText } from "./measure.js";
+export { truncateEnd, truncateMiddle, truncateStart } from "./truncate.js";
+export { segmentText } from "./segment.js";
+export { sliceTextByWidth } from "./slice.js";
+export { hardWrapLine, wordWrapLine } from "./wrap.js";
+export { measureTextWidth } from "./width.js";
+export type { PublicTextWrapMode, TextLayout, TextLayoutOptions, TextMeasure, TextSegment, TextWrapMode } from "./types.js";
+export { TEXT_WRAP_MODES } from "./types.js";

package/dist/index.js

@@ -0,0 +1,8 @@
+export { layoutText, normalizeWrapMode, readTextWrapMode } from "./layout.js";
+export { measureText } from "./measure.js";
+export { truncateEnd, truncateMiddle, truncateStart } from "./truncate.js";
+export { segmentText } from "./segment.js";
+export { sliceTextByWidth } from "./slice.js";
+export { hardWrapLine, wordWrapLine } from "./wrap.js";
+export { measureTextWidth } from "./width.js";
+export { TEXT_WRAP_MODES } from "./types.js";

package/dist/layout.d.ts

@@ -0,0 +1,4 @@
+import { type TextLayout, type TextLayoutOptions, type TextWrapMode } from "./types.js";
+export declare function layoutText(text: string, options?: TextLayoutOptions): TextLayout;
+export declare function normalizeWrapMode(wrap: TextLayoutOptions["wrap"]): TextWrapMode;
+export declare function readTextWrapMode(wrap: unknown): TextWrapMode;

package/dist/layout.js

@@ -0,0 +1,91 @@
+import { measureTextWidth } from "./width.js";
+import { TEXT_WRAP_MODES } from "./types.js";
+import { truncateEnd, truncateMiddle, truncateStart } from "./truncate.js";
+import { hardWrapLine, wordWrapLine } from "./wrap.js";
+const layoutCache = new Map();
+export function layoutText(text, options = {}) {
+    const wrap = normalizeWrapMode(options.wrap);
+    const width = normalizeWidth(options.width);
+    const cacheKey = `${text}\0${width ?? "auto"}\0${wrap}`;
+    const cached = layoutCache.get(cacheKey);
+    if (cached) {
+        return cached;
+    }
+    const lines = createLines(text, wrap, width);
+    const layout = {
+        width: lines.reduce((maxWidth, line) => Math.max(maxWidth, measureTextWidth(line)), 0),
+        height: lines.length,
+        lines
+    };
+    layoutCache.set(cacheKey, layout);
+    return layout;
+}
+export function normalizeWrapMode(wrap) {
+    if (wrap === null || wrap === undefined) {
+        return "legacy";
+    }
+    if (isTextWrapMode(wrap)) {
+        return wrap;
+    }
+    throw new Error(`Unsupported text wrap mode: ${String(wrap)}`);
+}
+export function readTextWrapMode(wrap) {
+    if (wrap === null || wrap === undefined) {
+        return "legacy";
+    }
+    if (isTextWrapMode(wrap)) {
+        return wrap;
+    }
+    throw new Error(`Unsupported text wrap mode: ${String(wrap)}`);
+}
+function isTextWrapMode(value) {
+    return (typeof value === "string" &&
+        TEXT_WRAP_MODES.includes(value));
+}
+function normalizeWidth(width) {
+    if (width === undefined || !Number.isFinite(width)) {
+        return undefined;
+    }
+    return Math.max(0, Math.floor(width));
+}
+function createLines(text, wrap, width) {
+    if (text === "" || width === 0) {
+        return [];
+    }
+    switch (wrap) {
+        case "legacy":
+            return firstLine(text);
+        case "none":
+            return splitLines(text);
+        case "wrap":
+            return wrapLines(text, width, wordWrapLine);
+        case "hard":
+            return wrapLines(text, width, hardWrapLine);
+        case "truncate-end":
+            return truncateLines(text, width, truncateEnd);
+        case "truncate-middle":
+            return truncateLines(text, width, truncateMiddle);
+        case "truncate-start":
+            return truncateLines(text, width, truncateStart);
+    }
+}
+function firstLine(text) {
+    const line = text.split("\n", 1)[0] ?? "";
+    return line === "" ? [] : [line];
+}
+function splitLines(text) {
+    return text.split("\n");
+}
+function wrapLines(text, width, wrapLine) {
+    if (width === undefined) {
+        return splitLines(text);
+    }
+    return splitLines(text).flatMap((line) => wrapLine(line, width));
+}
+function truncateLines(text, width, truncate) {
+    const lines = splitLines(text);
+    if (width === undefined) {
+        return lines;
+    }
+    return lines.map((line) => truncate(line, width));
+}

package/dist/lines.d.ts

@@ -0,0 +1,2 @@
+export declare function splitExplicitLines(text: string): string[];
+export declare function firstExplicitLine(text: string): string;

package/dist/lines.js

@@ -0,0 +1,6 @@
+export function splitExplicitLines(text) {
+    return text === "" ? [] : text.split("\n");
+}
+export function firstExplicitLine(text) {
+    return text.split("\n", 1)[0] ?? "";
+}

package/dist/measure.d.ts

@@ -0,0 +1,2 @@
+import type { TextMeasure } from "./types.js";
+export declare function measureText(text: string): TextMeasure;

package/dist/measure.js

@@ -0,0 +1,16 @@
+import { measureTextWidth } from "./width.js";
+const measureCache = new Map();
+export function measureText(text) {
+    const cached = measureCache.get(text);
+    if (cached) {
+        return cached;
+    }
+    const lines = text.split("\n");
+    const width = lines.reduce((maxWidth, line) => Math.max(maxWidth, measureTextWidth(line)), 0);
+    const measure = {
+        width,
+        height: text === "" ? 0 : lines.length
+    };
+    measureCache.set(text, measure);
+    return measure;
+}

package/dist/segment.d.ts

@@ -0,0 +1,3 @@
+import type { TextSegment } from "./types.js";
+export declare function segmentText(text: string): TextSegment[];
+export declare function measureSegmentsWidth(segments: readonly TextSegment[]): number;

package/dist/segment.js

@@ -0,0 +1,34 @@
+import stringWidth from "string-width";
+export function segmentText(text) {
+    if (text === "") {
+        return [];
+    }
+    return splitGraphemes(text).map((segment) => ({
+        text: segment,
+        width: normalizeSegmentWidth(stringWidth(segment))
+    }));
+}
+export function measureSegmentsWidth(segments) {
+    return segments.reduce((width, segment) => width + segment.width, 0);
+}
+function splitGraphemes(text) {
+    const Segmenter = readSegmenter();
+    if (Segmenter) {
+        return Array.from(new Segmenter("en", { granularity: "grapheme" }).segment(text), (part) => part.segment);
+    }
+    return Array.from(text);
+}
+function readSegmenter() {
+    const segmenter = Intl
+        .Segmenter;
+    return typeof segmenter === "function" ? segmenter : null;
+}
+function normalizeSegmentWidth(width) {
+    if (!Number.isFinite(width) || width <= 0) {
+        return 0;
+    }
+    if (width >= 2) {
+        return 2;
+    }
+    return 1;
+}

package/dist/slice.d.ts

@@ -0,0 +1 @@
+export declare function sliceTextByWidth(text: string, startColumn: number, endColumn: number): string;

package/dist/slice.js

@@ -0,0 +1,26 @@
+import { segmentText } from "./segment.js";
+export function sliceTextByWidth(text, startColumn, endColumn) {
+    const start = normalizeColumn(startColumn);
+    const end = normalizeColumn(endColumn);
+    if (end <= start || text === "") {
+        return "";
+    }
+    let cursor = 0;
+    let output = "";
+    for (const segment of segmentText(text)) {
+        const nextCursor = cursor + segment.width;
+        if (segment.width > 0 &&
+            cursor >= start &&
+            nextCursor <= end) {
+            output += segment.text;
+        }
+        cursor = nextCursor;
+    }
+    return output;
+}
+function normalizeColumn(value) {
+    if (!Number.isFinite(value)) {
+        return 0;
+    }
+    return Math.max(0, Math.floor(value));
+}

package/dist/truncate.d.ts

@@ -0,0 +1,3 @@
+export declare function truncateEnd(text: string, width: number): string;
+export declare function truncateStart(text: string, width: number): string;
+export declare function truncateMiddle(text: string, width: number): string;

package/dist/truncate.js

@@ -0,0 +1,85 @@
+import { measureSegmentsWidth, segmentText } from "./segment.js";
+const ELLIPSIS = "…";
+const ELLIPSIS_WIDTH = measureTextWidthBySegments(ELLIPSIS);
+export function truncateEnd(text, width) {
+    if (fits(text, width)) {
+        return text;
+    }
+    if (width <= 0) {
+        return "";
+    }
+    if (width === 1) {
+        return ELLIPSIS;
+    }
+    return takeStartByWidth(text, width - ELLIPSIS_WIDTH) + ELLIPSIS;
+}
+export function truncateStart(text, width) {
+    if (fits(text, width)) {
+        return text;
+    }
+    if (width <= 0) {
+        return "";
+    }
+    if (width === 1) {
+        return ELLIPSIS;
+    }
+    return ELLIPSIS + takeEndByWidth(text, width - ELLIPSIS_WIDTH);
+}
+export function truncateMiddle(text, width) {
+    if (fits(text, width)) {
+        return text;
+    }
+    if (width <= 0) {
+        return "";
+    }
+    if (width === 1) {
+        return ELLIPSIS;
+    }
+    const available = width - ELLIPSIS_WIDTH;
+    const left = Math.ceil(available / 2);
+    const right = Math.floor(available / 2);
+    return takeStartByWidth(text, left) + ELLIPSIS + takeEndByWidth(text, right);
+}
+function fits(text, width) {
+    return measureTextWidthBySegments(text) <= Math.max(0, width);
+}
+function takeStartByWidth(text, width) {
+    let output = "";
+    let currentWidth = 0;
+    for (const segment of segmentText(text)) {
+        if (segment.width === 0) {
+            output += segment.text;
+            continue;
+        }
+        if (currentWidth + segment.width > width) {
+            break;
+        }
+        output += segment.text;
+        currentWidth += segment.width;
+    }
+    return output;
+}
+function takeEndByWidth(text, width) {
+    const segments = segmentText(text);
+    const output = [];
+    let currentWidth = 0;
+    for (let index = segments.length - 1; index >= 0; index -= 1) {
+        const segment = segments[index];
+        if (!segment) {
+            continue;
+        }
+        if (segment.width === 0) {
+            output.unshift(segment.text);
+            continue;
+        }
+        if (currentWidth + segment.width > width) {
+            break;
+        }
+        output.unshift(segment.text);
+        currentWidth += segment.width;
+    }
+    return output.join("");
+}
+function measureTextWidthBySegments(text) {
+    return measureSegmentsWidth(segmentText(text));
+}

package/dist/types.d.ts

@@ -0,0 +1,20 @@
+export type TextWrapMode = "legacy" | "none" | "wrap" | "hard" | "truncate-end" | "truncate-middle" | "truncate-start";
+export type PublicTextWrapMode = Exclude<TextWrapMode, "legacy">;
+export interface TextMeasure {
+    width: number;
+    height: number;
+}
+export interface TextLayoutOptions {
+    width?: number;
+    wrap?: TextWrapMode | PublicTextWrapMode | null | undefined;
+}
+export interface TextLayout {
+    width: number;
+    height: number;
+    lines: string[];
+}
+export interface TextSegment {
+    text: string;
+    width: 0 | 1 | 2;
+}
+export declare const TEXT_WRAP_MODES: readonly ["legacy", "none", "wrap", "hard", "truncate-end", "truncate-middle", "truncate-start"];

package/dist/types.js

@@ -0,0 +1,9 @@
+export const TEXT_WRAP_MODES = [
+    "legacy",
+    "none",
+    "wrap",
+    "hard",
+    "truncate-end",
+    "truncate-middle",
+    "truncate-start"
+];

package/dist/width.d.ts

@@ -0,0 +1 @@
+export declare function measureTextWidth(text: string): number;

package/dist/width.js

@@ -0,0 +1,4 @@
+import { measureSegmentsWidth, segmentText } from "./segment.js";
+export function measureTextWidth(text) {
+    return measureSegmentsWidth(segmentText(text));
+}

package/dist/wrap.d.ts

@@ -0,0 +1,2 @@
+export declare function hardWrapLine(line: string, width: number): string[];
+export declare function wordWrapLine(line: string, width: number): string[];

package/dist/wrap.js

@@ -0,0 +1,73 @@
+import { measureTextWidth } from "./width.js";
+import { segmentText } from "./segment.js";
+export function hardWrapLine(line, width) {
+    if (width <= 0 || line === "") {
+        return line === "" ? [""] : [];
+    }
+    const lines = [];
+    let current = "";
+    let currentWidth = 0;
+    for (const segment of segmentText(line)) {
+        if (segment.width === 0) {
+            current += segment.text;
+            continue;
+        }
+        if (current !== "" && currentWidth + segment.width > width) {
+            lines.push(current);
+            current = "";
+            currentWidth = 0;
+        }
+        if (segment.width > width) {
+            if (current !== "") {
+                lines.push(current);
+                current = "";
+                currentWidth = 0;
+            }
+            lines.push(segment.text);
+            continue;
+        }
+        current += segment.text;
+        currentWidth += segment.width;
+    }
+    if (current !== "" || lines.length === 0) {
+        lines.push(current);
+    }
+    return lines;
+}
+export function wordWrapLine(line, width) {
+    if (width <= 0) {
+        return [];
+    }
+    if (line === "") {
+        return [""];
+    }
+    const tokens = line.match(/\S+\s*/g) ?? [line];
+    const lines = [];
+    let current = "";
+    for (const token of tokens) {
+        if (measureTextWidth(token.trimEnd()) > width) {
+            if (current !== "") {
+                lines.push(trimTrailingSpaces(current));
+                current = "";
+            }
+            lines.push(...hardWrapLine(token.trimEnd(), width));
+            const trailingSpaces = token.match(/\s+$/)?.[0] ?? "";
+            current = trailingSpaces.length > 0 ? trailingSpaces : "";
+            continue;
+        }
+        if (current !== "" &&
+            measureTextWidth(current + token.trimEnd()) > width) {
+            lines.push(trimTrailingSpaces(current));
+            current = token;
+            continue;
+        }
+        current += token;
+    }
+    if (current !== "" || lines.length === 0) {
+        lines.push(trimTrailingSpaces(current));
+    }
+    return lines;
+}
+function trimTrailingSpaces(value) {
+    return value.replace(/\s+$/g, "");
+}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@bindtty/text",
+  "version": "0.1.0-alpha.1",
+  "type": "module",
+  "description": "Plain terminal text measurement and wrapping utilities for BindTTY.",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepublishOnly": "npm run build",
+    "test": "npm run build && tsc -p test/tsconfig.json && node --test test/dist/*.test.js"
+  },
+  "dependencies": {
+    "string-width": "7.2.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.5.0"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lithdoo/BindTTY.git",
+    "directory": "packages/text"
+  },
+  "bugs": {
+    "url": "https://github.com/lithdoo/BindTTY/issues"
+  },
+  "homepage": "https://github.com/lithdoo/BindTTY/tree/main/packages/text#readme"
+}