linegauge 0.1.0 → 0.2.0

package/dist/wrap.js

@@ -1,3 +1,4 @@
+import { ASCII_PRINTABLE, ROW_BOUNDARY, TAB_SIZE, applyLeadingResets, applyParameters, closingSequence, forEachSegment, hyperlink, matchEscape, openingSequence, segmenter, sgr } from './style.js';
 /**
  * Wrapping text that carries ANSI, ported from wrap-ansi 10 — the third dependency the
  * render façades share, after the spinner corpus and the width function (R7, R10).
@@ -13,112 +14,8 @@
  * is graded against `string-width`: the incumbent is the specification.
  */
 import { measure } from './width.js';
-const ESC = '\u001B';
-const BELL = '\u0007';
-/** The single-byte C1 form of `ESC [`, which a terminal accepts and a suite will send. */
-const C1_CSI = '\u009B';
-const CSI = '[';
-const OSC = ']';
-const SGR_TERMINATOR = 'm';
-const SGR_RESET = 0;
-const SGR_RESET_FOREGROUND = 39;
-const SGR_RESET_BACKGROUND = 49;
-const SGR_RESET_UNDERLINE_COLOR = 59;
-const SGR_FOREGROUND_EXTENDED = 38;
-const SGR_BACKGROUND_EXTENDED = 48;
-const SGR_UNDERLINE_COLOR_EXTENDED = 58;
-const SGR_COLOR_MODE_RGB = 2;
-const SGR_COLOR_MODE_256 = 5;
-const FOREGROUND_FIRST = 30;
-const FOREGROUND_LAST = 37;
-const FOREGROUND_BRIGHT_FIRST = 90;
-const FOREGROUND_BRIGHT_LAST = 97;
-const BACKGROUND_FIRST = 40;
-const BACKGROUND_LAST = 47;
-const BACKGROUND_BRIGHT_FIRST = 100;
-const BACKGROUND_BRIGHT_LAST = 107;
-/** How many columns a tab advances to the next stop. */
-const TAB_SIZE = 8;
-/** `38;5;n` — the code, the mode, and one index. */
-const COLOR_256_PARTS = 3;
-/** `38;2;r;g;b` — the code, the mode, and three components. */
-const COLOR_RGB_PARTS = 3;
-/** `38:2::r:g:b` carries a colour space between the mode and the components. */
-const COLON_RGB_WITH_SPACE = 6;
-const ESCAPES = new Set([ESC, C1_CSI]);
-const ESCAPE_CHARACTERS = [...ESCAPES].join('');
-const CSI_INTRODUCER = `(?:${ESC}\\${CSI}|${C1_CSI})`;
-const CSI_PARAMETERS = '[0-?]*[ -/]*[@-~]';
-const SGR_PARAMETERS = `(?<sgr>[0-9;:]*)${SGR_TERMINATOR}`;
-const OSC_TERMINATOR = `(?:${BELL}|${ESC}\\\\)`;
-const OSC_PAYLOAD = String.raw `[^\u0000-\u001F\u007F-\u009F]*`;
-/** `OSC 8 ; params ; URI ST` — a hyperlink, whose URI is tracked so a row can reopen it. */
-const LINK_PARAMETERS = String.raw `8;(?<parameters>[^;\u0000-\u001F\u007F-\u009F]*);(?<uri>${OSC_PAYLOAD})${OSC_TERMINATOR}`;
-// Deliberately not a terminal emulator: semicolon-delimited SGR, colon-delimited extended
-// colour and OSC 8 links are understood; every other complete CSI or OSC command is carried
-// through as an opaque zero-width unit, and anything that only looks like an introducer
-// stays plain text. `y` (sticky), so a match is anchored where the scan asked.
-const ANSI_ESCAPE = new RegExp(`${CSI_INTRODUCER}(?:${SGR_PARAMETERS}|${CSI_PARAMETERS})|${ESC}\\${OSC}(?:${LINK_PARAMETERS}|${OSC_PAYLOAD}${OSC_TERMINATOR})`, 'y');
-const ESCAPE_INTRODUCER = new RegExp(`[${ESCAPE_CHARACTERS}]`, 'g');
-const ROW_BOUNDARY = new RegExp(`[\\n${ESCAPE_CHARACTERS}]`, 'g');
-/** Every printable ASCII character is its own cluster of width one — skip the segmenter. */
-const ASCII_PRINTABLE = /^[ -~]*$/;
-/**
- * Which SGR code closes which modifier. This is ECMA-48, not any library's table — bold
- * opens with 1 and closes with 22 wherever you read it — so it lives here rather than
- * being imported, which keeps `wrap()` free of `roundel/chalk` and takes 18 KB off every
- * subpath that wraps. The colour families close with 39, 49 and 59 and are handled by name
- * above, before this map is consulted.
- */
-const MODIFIER_CLOSE = new Map([
-    [1, 22],
-    [2, 22],
-    [3, 23],
-    [4, 24],
-    [7, 27],
-    [8, 28],
-    [9, 29],
-    [53, 55],
-]);
-const MODIFIER_CLOSE_CODES = new Set(MODIFIER_CLOSE.values());
-const segmenter = new Intl.Segmenter();
-const sgr = (code) => `${ESC}${CSI}${code}${SGR_TERMINATOR}`;
-const hyperlink = (url, parameters = '') => `${ESC}${OSC}8;${parameters};${url}${BELL}`;
-/** The complete escape sequence starting at `index`, or nothing when none starts there. */
-function matchEscape(string, index) {
-    if (!ESCAPES.has(string[index] ?? ''))
-        return undefined;
-    ANSI_ESCAPE.lastIndex = index;
-    return ANSI_ESCAPE.exec(string) ?? undefined;
-}
-/**
- * Walk a string as alternating runs of plain text and complete escape sequences. A
- * character that looks like an introducer but starts no valid sequence stays plain text.
- */
-function forEachSegment(string, onPlainText, onEscape = () => undefined) {
-    let plainStart = 0;
-    let index = 0;
-    while (index < string.length) {
-        ESCAPE_INTRODUCER.lastIndex = index;
-        const introducer = ESCAPE_INTRODUCER.exec(string);
-        if (introducer === null)
-            break;
-        const escape = matchEscape(string, introducer.index);
-        if (escape === undefined) {
-            index = introducer.index + 1;
-            continue;
-        }
-        if (introducer.index > plainStart)
-            onPlainText(string.slice(plainStart, introducer.index));
-        onEscape(escape[0]);
-        index = introducer.index + escape[0].length;
-        plainStart = index;
-    }
-    if (plainStart < string.length)
-        onPlainText(string.slice(plainStart));
-}
 /** The visible width of a string, escape sequences ignored. */
-function visibleWidth(string) {
+export function visibleWidth(string) {
     let plainText = '';
     forEachSegment(string, (part) => {
         plainText += part;
@@ -164,155 +61,6 @@ function splitWords(string) {
         word.width = measure(word.plainText);
     return words;
 }
-const isDigits = (value) => /^\d+$/.test(value);
-/** `38:5:9` and `38:2::r:g:b` — the colon form, which carries its arguments in one parameter. */
-function colonColorToken(parameter) {
-    const parts = parameter.split(':');
-    const code = Number.parseInt(parts[0] ?? '', 10);
-    const mode = Number.parseInt(parts[1] ?? '', 10);
-    if (![SGR_FOREGROUND_EXTENDED, SGR_BACKGROUND_EXTENDED, SGR_UNDERLINE_COLOR_EXTENDED].includes(code))
-        return undefined;
-    if (mode === SGR_COLOR_MODE_256 && parts.length === COLOR_256_PARTS && isDigits(parts[2] ?? '')) {
-        return { code, open: parameter, hasArguments: true };
-    }
-    if (mode !== SGR_COLOR_MODE_RGB)
-        return undefined;
-    const withSpace = parts.length === COLON_RGB_WITH_SPACE;
-    const components = withSpace ? parts.slice(3) : parts.slice(2);
-    const colorSpace = withSpace ? parts[2] : undefined;
-    if (components.length === COLOR_RGB_PARTS && components.every(isDigits) && (colorSpace === undefined || /^\d*$/.test(colorSpace))) {
-        return { code, open: parameter, hasArguments: true };
-    }
-    return undefined;
-}
-/** One extended-colour parameter run, `38;5;n` or `38;2;r;g;b`, or nothing if malformed. */
-function extendedColorToken(code, parameters, index) {
-    const mode = Number.parseInt(parameters[index + 1] ?? '', 10);
-    const first = Number.parseInt(parameters[index + 2] ?? '', 10);
-    if (mode === SGR_COLOR_MODE_256 && Number.isFinite(first)) {
-        return { token: { code, open: [code, mode, first].join(';'), hasArguments: true }, consumed: 2 };
-    }
-    const green = Number.parseInt(parameters[index + 3] ?? '', 10);
-    const blue = Number.parseInt(parameters[index + 4] ?? '', 10);
-    if (mode === SGR_COLOR_MODE_RGB && Number.isFinite(first) && Number.isFinite(green) && Number.isFinite(blue)) {
-        return { token: { code, open: [code, mode, first, green, blue].join(';'), hasArguments: true }, consumed: 4 };
-    }
-    return undefined;
-}
-const isExtendedColor = (code) => code === SGR_FOREGROUND_EXTENDED || code === SGR_BACKGROUND_EXTENDED || code === SGR_UNDERLINE_COLOR_EXTENDED;
-function sgrTokens(parameters) {
-    const parts = parameters.split(';');
-    const tokens = [];
-    for (let index = 0; index < parts.length; index += 1) {
-        const parameter = parts[index] ?? '';
-        if (parameter.includes(':')) {
-            const token = colonColorToken(parameter);
-            if (token !== undefined)
-                tokens.push(token);
-            continue;
-        }
-        const code = parameter === '' ? SGR_RESET : Number.parseInt(parameter, 10);
-        if (!Number.isFinite(code))
-            continue;
-        if (isExtendedColor(code)) {
-            if (index + 1 >= parts.length)
-                break;
-            const extended = extendedColorToken(code, parts, index);
-            if (extended === undefined)
-                break;
-            tokens.push(extended.token);
-            index += extended.consumed;
-            continue;
-        }
-        tokens.push({ code, open: String(code), hasArguments: false });
-    }
-    return tokens;
-}
-function removeFamily(active, family) {
-    const at = active.findIndex((style) => style.family === family);
-    if (at !== -1)
-        active.splice(at, 1);
-}
-function colorStyle(token) {
-    const { code, open, hasArguments } = token;
-    if ((code >= FOREGROUND_FIRST && code <= FOREGROUND_LAST) || (code >= FOREGROUND_BRIGHT_FIRST && code <= FOREGROUND_BRIGHT_LAST) || (code === SGR_FOREGROUND_EXTENDED && hasArguments)) {
-        return { family: 'foreground', open, close: SGR_RESET_FOREGROUND };
-    }
-    if ((code >= BACKGROUND_FIRST && code <= BACKGROUND_LAST) || (code >= BACKGROUND_BRIGHT_FIRST && code <= BACKGROUND_BRIGHT_LAST) || (code === SGR_BACKGROUND_EXTENDED && hasArguments)) {
-        return { family: 'background', open, close: SGR_RESET_BACKGROUND };
-    }
-    if (code === SGR_UNDERLINE_COLOR_EXTENDED && hasArguments) {
-        return { family: 'underlineColor', open, close: SGR_RESET_UNDERLINE_COLOR };
-    }
-    return undefined;
-}
-/** True when the code closed something rather than opening it. */
-function applyResetCode(code, active) {
-    if (code === SGR_RESET) {
-        active.length = 0;
-        return true;
-    }
-    if (code === SGR_RESET_FOREGROUND) {
-        removeFamily(active, 'foreground');
-        return true;
-    }
-    if (code === SGR_RESET_BACKGROUND) {
-        removeFamily(active, 'background');
-        return true;
-    }
-    if (code === SGR_RESET_UNDERLINE_COLOR) {
-        removeFamily(active, 'underlineColor');
-        return true;
-    }
-    if (MODIFIER_CLOSE_CODES.has(code)) {
-        // One close code can end several modifiers — `22` ends both bold and dim.
-        for (let index = active.length - 1; index >= 0; index -= 1) {
-            const style = active[index];
-            if (style !== undefined && style.family.startsWith('modifier-') && style.close === code)
-                active.splice(index, 1);
-        }
-        return true;
-    }
-    return false;
-}
-function applyToken(token, active) {
-    if (applyResetCode(token.code, active))
-        return;
-    const color = colorStyle(token);
-    if (color !== undefined) {
-        removeFamily(active, color.family);
-        active.push(color);
-        return;
-    }
-    const close = MODIFIER_CLOSE.get(token.code);
-    if (close !== undefined && close !== SGR_RESET) {
-        const family = `modifier-${token.code}`;
-        removeFamily(active, family);
-        active.push({ family, open: token.open, close });
-    }
-}
-const applyParameters = (parameters, active) => {
-    for (const token of sgrTokens(parameters))
-        applyToken(token, active);
-};
-const applyResets = (parameters, active) => {
-    for (const { code } of sgrTokens(parameters))
-        applyResetCode(code, active);
-};
-/** A row that opens with its own resets should not have them undone by the reopening. */
-function applyLeadingResets(string, startIndex, active) {
-    let index = startIndex;
-    while (index < string.length) {
-        const match = matchEscape(string, index);
-        if (match === undefined)
-            break;
-        if (match.groups?.['sgr'] !== undefined)
-            applyResets(match.groups['sgr'], active);
-        index += match[0].length;
-    }
-}
-const closingSequence = (active) => [...active].reverse().map((style) => sgr(style.close)).join('');
-const openingSequence = (active) => active.map((style) => sgr(style.open)).join('');
 /**
  * Break one long word across rows. Takes the visible width of the row it starts on and
  * returns the width of the row it ends on, so the caller never measures a row itself.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "linegauge",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "A printer's line gauge \u2014 the steel rule marked in picas and points. Measuring, wrapping, truncating and slicing styled terminal text without the edge fraying \u2014 grapheme-correct over Intl.Segmenter. Drop-in paths for string-width, wrap-ansi, strip-ansi and slice-ansi. Zero dependencies.",
   "license": "MIT",
   "type": "module",
@@ -17,6 +17,26 @@
       "types": "./dist/wrap.d.ts",
       "import": "./dist/wrap.js",
       "default": "./dist/wrap.js"
+    },
+    "./slice": {
+      "types": "./dist/slice.d.ts",
+      "import": "./dist/slice.js",
+      "default": "./dist/slice.js"
+    },
+    "./truncate": {
+      "types": "./dist/truncate.d.ts",
+      "import": "./dist/truncate.js",
+      "default": "./dist/truncate.js"
+    },
+    "./widest": {
+      "types": "./dist/widest.d.ts",
+      "import": "./dist/widest.js",
+      "default": "./dist/widest.js"
+    },
+    "./strip": {
+      "types": "./dist/strip.d.ts",
+      "import": "./dist/strip.js",
+      "default": "./dist/strip.js"
     }
   },
   "files": [
@@ -28,6 +48,7 @@
     "build": "tsc -p tsconfig.build.json",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "test": "vitest run --passWithNoTests",
+    "coverage": "vitest run --coverage.enabled",
     "lint": "eslint src"
   },
   "repository": {
@@ -54,8 +75,6 @@
     "unicode"
   ],
   "devDependencies": {
-    "string-width": "^8.1.0",
-    "vitest": "^4.0.0",
-    "wrap-ansi": "^10.0.1"
+    "vitest": "^5.0.0"
   }
 }