@shell-shock/plugin-console 0.2.6 → 0.2.8

package/dist/components/console-builtin.mjs

@@ -9,7 +9,7 @@ import { TSDoc, TSDocDefaultValue, TSDocExample, TSDocParam, TSDocRemarks, TSDoc
 import { IsNotDebug, IsNotVerbose } from "@shell-shock/core/components/helpers";
 import { useColors, useTheme } from "@shell-shock/plugin-theme/contexts/theme";
 import { colorKeys, modifierKeys } from "@shell-shock/plugin-theme/helpers/ansi-utils";
-import { camelCase } from "@stryke/string-format";
+import { camelCase, titleCase } from "@stryke/string-format";
 import { getIndefiniteArticle } from "@stryke/string-format/vowels";
 import { isSetObject } from "@stryke/type-checks/is-set-object";
 import { defu } from "defu";
@@ -322,17 +322,18 @@ function AnsiStyleFunctionsDeclaration() {
 			doubleHardline: true,
 			enderPunctuation: true,
 			children: (modifier) => [createComponent(TSDoc, {
-				heading: `A function that applies ${modifier} styling to provided console text.`,
+				get heading() {
+					return `A function that applies ${getIndefiniteArticle(titleCase(modifier))} ${titleCase(modifier)} text-style to provided console text.`;
+				},
 				get children() {
-					return [
-						createComponent(TSDocRemarks, { children: `This function takes a string and an optional boolean indicating whether to apply the color as a background. It returns the input string wrapped in the appropriate ANSI escape codes for the specified color, based on the terminal's color support level. If colors are not supported, it simply returns the input text as a string.` }),
-						createIntrinsic("hbr", {}),
-						createComponent(TSDocParam, {
-							name: "text",
-							children: `The console text to which the ${modifier} styling should be applied.`
-						}),
-						createComponent(TSDocReturns, { children: `A string with ANSI escape codes applied for ${modifier} styling, or the original text if the style is not supported in the current terminal.` })
-					];
+					return [createComponent(TSDocParam, {
+						name: "text",
+						get children() {
+							return `The console text to which the ${titleCase(modifier)} text-style should be applied.`;
+						}
+					}), createComponent(TSDocReturns, { get children() {
+						return `A string with ANSI escape codes applied for ${titleCase(modifier)} text-style, or the original text if the style is not supported in the current terminal.`;
+					} })];
 				}
 			}), createComponent(VarDeclaration, {
 				"const": true,
@@ -363,16 +364,28 @@ function AnsiStyleFunctionsDeclaration() {
 			doubleHardline: true,
 			enderPunctuation: true,
 			children: (color) => [createComponent(TSDoc, {
-				heading: `A helper function to color the provided text as ${color}.`,
+				get heading() {
+					return `A function that applies ${getIndefiniteArticle(titleCase(color))} ${titleCase(color)} color styling to provided console text.`;
+				},
 				get children() {
 					return [
-						createComponent(TSDocRemarks, { children: `This function takes a string and an optional boolean indicating whether to apply the color as a background. It returns the input string wrapped in the appropriate ANSI escape codes for the specified color, based on the terminal's color support level. If colors are not supported, it simply returns the input text as a string.` }),
+						createComponent(TSDocRemarks, { get children() {
+							return `This function takes a string and an optional boolean indicating whether to apply the color as a background. It returns the input string wrapped in the appropriate ANSI escape codes for ${getIndefiniteArticle(titleCase(color))} ${titleCase(color)} color styling, based on the terminal's color support level. If colors are not supported, it simply returns the input text as a string.`;
+						} }),
 						createIntrinsic("hbr", {}),
 						createComponent(TSDocParam, {
 							name: "text",
-							children: `The console text to which the ${color} color should be applied.`
+							get children() {
+								return `The console text to which the ${titleCase(color)} color styling should be applied.`;
+							}
 						}),
-						createComponent(TSDocReturns, { children: `A string with ANSI escape codes applied for ${color} color, or the original text if the color is not supported in the current terminal.` })
+						createComponent(TSDocParam, {
+							name: "background",
+							children: `A boolean indicating whether to apply the color as a background. Defaults to \`false\`.`
+						}),
+						createComponent(TSDocReturns, { get children() {
+							return `A string with ANSI escape codes applied for ${titleCase(color)} color styling, or the original text if the style is not supported in the current terminal.`;
+						} })
 					];
 				}
 			}), createComponent(VarDeclaration, {
@@ -533,6 +546,54 @@ function SplitTextFunctionDeclaration() {
         const openSequence = openCodes.join("");
 
         return [first.replace(/^\\s+/, "").replace(/\\s+$/, "") + closeSequence, openSequence + second.replace(/^\\s+/, "").replace(/\\s+$/, "")]; `
+		}),
+		createComponent(Spacing, {}),
+		createComponent(FunctionDeclaration, {
+			name: "innerSplitText",
+			parameters: [{
+				name: "text",
+				type: "string"
+			}, {
+				name: "maxLength",
+				type: "number | SizeToken"
+			}],
+			children: code`let line = text;
+        let result = [] as string[];
+
+        const calculatedMaxLength = isSizeToken(maxLength) ? calculateWidth(maxLength) : maxLength;
+        while (stripAnsi(line).length > calculatedMaxLength || line.indexOf("\\n") !== -1) {
+          if (line.indexOf("\\n") !== -1) {
+            result.push(...innerSplitText(line.slice(0, line.indexOf("\\n")).replace(/(\\r)?\\n/, ""), calculatedMaxLength));
+            line = line.indexOf("\\n") + 1 < line.length
+              ? line.slice(line.indexOf("\\n") + 1)
+              : "";
+          } else {
+            const index = [" ", "/", ".", ",", "-", ":", "|", "@", "+"].reduce((ret, split) => {
+              let current = ret;
+              while (stripAnsi(line).indexOf(split, current + 1) !== -1 && stripAnsi(line).indexOf(split, current + 1) <= calculatedMaxLength) {
+                current = line.indexOf(split, adjustIndex(line, current + 1));
+              }
+
+              return current;
+            }, -1);
+            if (index === -1) {
+              break;
+            }
+
+            const lines = breakLine(line, index);
+            result.push(lines[0]);
+            line = lines[1];
+          }
+        }
+
+        while (stripAnsi(line).length > calculatedMaxLength) {
+          const lines = breakLine(line, calculatedMaxLength);
+          result.push(lines[0]);
+          line = lines[1];
+        }
+
+        result.push(line);
+        return result; `
 		}),
 		createComponent(Spacing, {}),
 		createComponent(TSDoc, {
@@ -562,45 +623,16 @@ function SplitTextFunctionDeclaration() {
 				name: "maxLength",
 				type: "number | SizeToken"
 			}],
-			children: code`
-  let line = text;
-  let result = [] as string[];
-
-  const calculatedMaxLength = isSizeToken(maxLength) ? calculateWidth(maxLength) : maxLength;
-  while (stripAnsi(line).length > calculatedMaxLength || line.indexOf("\\n") !== -1) {
-    if (line.indexOf("\\n") !== -1) {
-      result.push(...splitText(line.slice(0, line.indexOf("\\n")).replace(/(\\r)?\\n/, ""), calculatedMaxLength));
-      line = line.indexOf("\\n") + 1 < line.length
-        ? line.slice(line.indexOf("\\n") + 1)
-        : "";
-    } else {
-      const index = [" ", "/", ".", ",", "-", ":", "|", "@", "+"].reduce((ret, split) => {
-        let current = ret;
-        while (stripAnsi(line).indexOf(split, current + 1) !== -1 && stripAnsi(line).indexOf(split, current + 1) <= calculatedMaxLength) {
-          current = line.indexOf(split, adjustIndex(line, current + 1));
+			children: code`const timeout = setTimeout(() => {
+          throw new Error("Text splitting took too long, likely due to a very long line without spaces or a very small maxLength. Please ensure that the input text contains reasonable break points and that maxLength is set to a reasonable value.");
+        }, 1000);
+
+        try {
+          return innerSplitText(text, maxLength);
+        } finally {
+          clearTimeout(timeout);
         }
-
-        return current;
-      }, -1);
-      if (index === -1) {
-        break;
-      }
-
-      const lines = breakLine(line, index);
-      result.push(lines[0]);
-      line = lines[1];
-    }
-  }
-
-  while (stripAnsi(line).length > calculatedMaxLength) {
-    const lines = breakLine(line, calculatedMaxLength);
-    result.push(lines[0]);
-    line = lines[1];
-  }
-
-  result.push(line);
-  return result;
-`
+         `
 		})
 	];
 }
@@ -1025,65 +1057,86 @@ function DividerFunctionDeclaration() {
 */
 function LinkFunctionDeclaration() {
 	const theme = useTheme();
-	return [createComponent(TSDoc, {
-		heading: "Render a hyperlink in the console.",
-		get children() {
-			return [
-				createComponent(TSDocParam, {
-					name: "url",
-					children: `The URL to render as a hyperlink.`
-				}),
-				createComponent(TSDocParam, {
-					name: "textOrExternal",
-					children: `The text to display for the link or a boolean indicating whether the link is external. If no text is provided, the URL will be used as the text. If a boolean is provided and is true, the URL will be used as the text and the link will be rendered as an external link.`
-				}),
-				createComponent(TSDocParam, {
-					name: "external",
-					children: `A boolean indicating whether the link is external. If true, the link will be rendered as an external link.`
-				}),
-				createComponent(TSDocReturns, { children: `The formatted hyperlink string.` })
-			];
-		}
-	}), createComponent(FunctionDeclaration, {
-		"export": true,
-		name: "link",
-		parameters: [
-			{
+	return [
+		createComponent(InterfaceDeclaration, {
+			"export": true,
+			name: "LinkOptions",
+			doc: "Options for formatting a hyperlink in the console.",
+			get children() {
+				return [
+					createComponent(InterfaceMember, {
+						name: "external",
+						optional: true,
+						type: "boolean",
+						doc: "Whether the link is external. If true, an external link icon will be displayed next to the link text (if supported by the terminal) and the link may be styled differently based on the current theme configuration."
+					}),
+					createComponent(Spacing, {}),
+					createComponent(InterfaceMember, {
+						name: "text",
+						optional: true,
+						type: "string",
+						doc: "The text to display for the link. If not provided, the URL will be used as the text."
+					}),
+					createComponent(Spacing, {}),
+					createComponent(InterfaceMember, {
+						name: "useTextWhenUnsupported",
+						optional: true,
+						type: "boolean",
+						doc: "Whether to use the text when the hyperlink is not supported. If true, the text will be displayed even if the terminal does not support hyperlinks."
+					})
+				];
+			}
+		}),
+		createComponent(Spacing, {}),
+		createComponent(TSDoc, {
+			heading: "Render a hyperlink in the console.",
+			get children() {
+				return [
+					createComponent(TSDocParam, {
+						name: "url",
+						children: `The URL to render as a hyperlink.`
+					}),
+					createComponent(TSDocParam, {
+						name: "options",
+						children: `Options for formatting the hyperlink.`
+					}),
+					createComponent(TSDocReturns, { children: `The formatted hyperlink string for display in the console.` })
+				];
+			}
+		}),
+		createComponent(FunctionDeclaration, {
+			"export": true,
+			name: "link",
+			parameters: [{
 				name: "url",
 				type: "string",
 				optional: false
-			},
-			{
-				name: "textOrExternal",
-				type: "string | boolean",
-				optional: true
-			},
-			{
-				name: "external",
-				type: "boolean",
-				optional: true
+			}, {
+				name: "options",
+				type: "LinkOptions",
+				default: "{}"
+			}],
+			get children() {
+				return [
+					createComponent(IfStatement, {
+						condition: code`isHyperlinkSupported()`,
+						get children() {
+							return code`return \`\\x1b]8;;\${url}\\u0007\${options.text ? options.text : url}\\x1b]8;;\\u0007\${options.external === true ? "${theme.icons.link.external}" : ""}\`;`;
+						}
+					}),
+					createIntrinsic("hbr", {}),
+					createComponent(IfStatement, {
+						condition: code`isColorSupported`,
+						get children() {
+							return code`return \`\${underline(textColors.body.link(\`\${options.useTextWhenUnsupported && options.text ? options.text : url}\`))}\${options.external === true ? "${theme.icons.link.external}" : ""}\`;`;
+						}
+					}),
+					createIntrinsic("hbr", {}),
+					memo(() => code`return \`\${options.useTextWhenUnsupported && options.text ? options.text : url}\${options.external === true ? "${theme.icons.link.external}" : ""}\`;`)
+				];
 			}
-		],
-		get children() {
-			return [
-				createComponent(IfStatement, {
-					condition: code`isHyperlinkSupported()`,
-					get children() {
-						return code`return \`\\x1b]8;;\${url}\\u0007\${typeof textOrExternal === "string" && textOrExternal ? textOrExternal : url}\\x1b]8;;\\u0007\${external === true || textOrExternal === true ? "${theme.icons.link.external}" : ""}\`;`;
-					}
-				}),
-				createIntrinsic("hbr", {}),
-				createComponent(IfStatement, {
-					condition: code`isColorSupported`,
-					get children() {
-						return code`return \`\${underline(textColors.body.link(\`\${url}\`))}\${external === true || textOrExternal === true ? "${theme.icons.link.external}" : ""}\`;`;
-					}
-				}),
-				createIntrinsic("hbr", {}),
-				memo(() => code`return \`\${url}\${external === true || textOrExternal === true ? "${theme.icons.link.external}" : ""}\`;`)
-			];
-		}
-	})];
+		})
+	];
 }
 /**
 * A component to generate the `blockquote` function declaration
@@ -2450,25 +2503,14 @@ function ConsoleBuiltin(props) {
 		description: "A collection of helper utilities to assist in generating content meant for display in the console.",
 		get imports() {
 			return defu(imports, {
-				"@shell-shock/plugin-theme/types/theme": [{
-					name: "ThemeColorsResolvedConfig",
-					type: true
-				}, {
-					name: "ThemeSpinnerResolvedConfig",
-					type: true
-				}],
-				"@shell-shock/plugin-theme/helpers/spinners": [{
-					name: "SpinnerPreset",
-					type: true
-				}, { name: "resolveSpinner" }],
-				"node:buffer": ["WithImplicitCoercion"],
+				"@shell-shock/plugin-theme/types/theme": ["ThemeSpinnerResolvedConfig"],
+				"@shell-shock/plugin-theme/helpers/spinners": ["SpinnerPreset", "resolveSpinner"],
 				"node:util": ["stripVTControlCharacters"]
 			});
 		},
 		get builtinImports() {
 			return defu(builtinImports, {
 				utils: [
-					"isMinimal",
 					"isInteractive",
 					"isColorSupported",
 					"colorSupportLevels",
@@ -2582,7 +2624,7 @@ function ConsoleBuiltin(props) {
 					timestamp: true,
 					parameters: [{
 						name: "err",
-						type: "string | Error",
+						type: "string | { message: string; stack?: string }",
 						optional: false
 					}, {
 						name: "header",
@@ -2598,19 +2640,26 @@ function ConsoleBuiltin(props) {
 							}),
 							createComponent(Spacing, {}),
 							createComponent(IfStatement, {
-								condition: code`(err as Error)?.message`,
-								children: code`message = (err as Error).message;`
+								condition: code`(err as { message: string; stack?: string })?.message`,
+								children: code`message = (err as { message: string; stack?: string }).message;`
 							}),
 							createComponent(ElseClause, { children: code`message = String(err);` }),
 							createComponent(Spacing, {}),
 							createComponent(IfStatement, {
-								condition: code`env.STACKTRACE`,
-								get children() {
-									return [createComponent(IfStatement, {
-										condition: code`(err as Error)?.stack`,
-										children: code`message += " \\n\\n" + ((err as Error).stack || "");`
-									}), createComponent(ElseClause, { children: code`message += " \\n\\n" + ((new Error(" ")).stack || "").split("\\n").slice(2).map(line => line.trim()).join("\\n");` })];
-								}
+								condition: code`env.STACKTRACE && typeof err === "object" && (err as { stack?: string })?.stack`,
+								children: code`message += " \\n\\n" + (err as { stack?: string })?.stack
+                .split("\\n")
+                .slice(1)
+                .map(line => {
+                  const match = line.match(/at (?:(.+?)\\s+\\()?(?:(.+?):(\\d+)(?::(\\d+))?|([^)]+))\\)?/);
+                  if (match) {
+                    const filePath = match[2] || match[5] || "<unknown>";
+                    return \`at \${match[1] || "<anonymous>"} (\${filePath === "<anonymous>" || filePath === "<unknown>" ? filePath : link(filePath, { text: \`\${filePath.replace(/^.*file:\\/\\//, "")}\${match[3] ? \`:\${match[3]}\${match[4] ? \`:\${match[4]}\` : ""}\` : ""}\`, useTextWhenUnsupported: true })})\`;
+                  }
+
+                  return line.trim();
+                })
+                .join("\\n"); `
 							})
 						];
 					}