knodin 0.5.0

package/dist/src/terminal-help.js

@@ -0,0 +1,83 @@
+const DEFAULT_HELP_WIDTH = 100;
+const MIN_HELP_WIDTH = 60;
+function leadingWidth(line) {
+    return line.length - line.trimStart().length;
+}
+function logicalLines(template) {
+    const logical = [];
+    let current = null;
+    for (const raw of template.replaceAll("\t", "    ").split("\n")) {
+        if (raw.trim() === "") {
+            if (current)
+                logical.push(current);
+            current = null;
+            logical.push(null);
+            continue;
+        }
+        if (current && leadingWidth(raw) >= 4) {
+            current.continuations.push(raw);
+            continue;
+        }
+        if (current)
+            logical.push(current);
+        current = { first: raw.trimEnd(), continuations: [] };
+    }
+    if (current)
+        logical.push(current);
+    return logical;
+}
+function wrapWords(text, firstPrefix, continuationPrefix, width) {
+    const words = text.trim().split(/\s+/);
+    const lines = [];
+    let line = firstPrefix;
+    for (const word of words) {
+        const separator = line.trim().length > 0 ? " " : "";
+        if (line.length + separator.length + word.length > width && line.trim().length > 0) {
+            lines.push(line.trimEnd());
+            line = `${continuationPrefix}${word}`;
+        }
+        else {
+            line += `${separator}${word}`;
+        }
+    }
+    if (line.trim().length > 0)
+        lines.push(line.trimEnd());
+    return lines;
+}
+function renderLogicalLine(line, width) {
+    const firstIndent = " ".repeat(leadingWidth(line.first));
+    const firstText = line.first.trim();
+    if (line.continuations.length === 0 && line.first.length <= width)
+        return [line.first];
+    const continuationColumn = line.continuations.length > 0
+        ? Math.min(...line.continuations.map(leadingWidth))
+        : leadingWidth(line.first);
+    const joined = [firstText, ...line.continuations.map((value) => value.trim())].join(" ");
+    if (line.continuations.length > 0 && firstIndent.length + firstText.length > width * 0.55) {
+        return wrapWords(joined, firstIndent, `${firstIndent}  `, width);
+    }
+    const separator = /\s{2,}/.exec(firstText);
+    if (separator?.index !== undefined) {
+        const left = firstText.slice(0, separator.index).trimEnd();
+        const description = joined.slice(separator.index + separator[0].length).trim();
+        const descriptionColumn = Math.max(firstIndent.length + left.length + 2, continuationColumn);
+        return wrapWords(description, `${firstIndent}${left}${" ".repeat(Math.max(2, descriptionColumn - firstIndent.length - left.length))}`, " ".repeat(descriptionColumn), width);
+    }
+    if (line.continuations.length > 0) {
+        const commandWidth = firstIndent.length + firstText.length;
+        const descriptionColumn = Math.max(commandWidth + 2, continuationColumn);
+        const description = line.continuations.map((value) => value.trim()).join(" ");
+        return wrapWords(description, `${firstIndent}${firstText}${" ".repeat(Math.max(2, descriptionColumn - commandWidth))}`, " ".repeat(descriptionColumn), width);
+    }
+    return wrapWords(firstText, firstIndent, firstIndent, width);
+}
+/** Reflow authored help to the active TTY, with a deterministic width for piped output. */
+export function formatTerminalHelp(template, columns) {
+    const width = columns === undefined || !Number.isFinite(columns)
+        ? DEFAULT_HELP_WIDTH
+        : Math.max(MIN_HELP_WIDTH, Math.floor(columns) - 1);
+    const rendered = logicalLines(template).flatMap((line) => line === null ? [""] : renderLogicalLine(line, width));
+    while (rendered.at(-1) === "")
+        rendered.pop();
+    return `${rendered.join("\n")}\n`;
+}