@lewishowles/cli-style 0.4.1 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## Unreleased
+
+## 0.6.0 - 2026-07-03
+
+### Added
+
+- Added result-state support to `row()` and `cli_style_row`, so label/value rows can render failed, warning, success, or other status cues while keeping column alignment.
+- Added the `span()` inline emphasis primitive and `cli_style_span` Bash helper for highlighting commands, files, or values inside existing line renderers such as `hint()`.
+- Added `span` support to `cli-style render` and the public JavaScript export.
+
+### Changed
+
+- Reworked the README around integration paths, available renderers, primitive data shapes, patterns, options, profiles, result types, and gallery commands.
+
+## 0.5.0 - 2026-07-02
+
+### Added
+
+- Added Bash adapter convenience functions for common renderers: `cli_style_status`, `cli_style_row`, `cli_style_divider`, and `cli_style_hint`.
+- Added Bash adapter escaping for dynamic string values, so scripts can pass quotes, backslashes, paths, and messages without hand-building JSON.
+- Added README examples for JS CLI entrypoint wiring with `createCliStyle({ argv, env, stdout })` and helper-first Bash adapter usage.
+
+### Changed
+
+- Lightened the muted colour token so secondary text stays readable on dark surfaces.
+
 ## 0.4.1 - 2026-07-01
 
 ### Fixed

package/README.md

@@ -1,11 +1,13 @@
 # CLI style
 
-Shared terminal output styles for tools, diagnostics, and package CLIs.
+Shared terminal output styles for local tools, diagnostics, agent-facing reports, and package CLIs.
+
+Use it directly from JavaScript, or call the same renderers from Bash and Python through the `cli-style` binary.
 
 ## Requirements
 
 - Bun and Node.js 20 or newer for JavaScript projects and local binary builds
-- The standalone binary for Bash or Python projects that should not install Bun
+- The standalone `cli-style` binary for Bash or Python projects that should not install Bun
 
 ## Install
 
@@ -21,14 +23,37 @@ Bash and Python projects call the `cli-style` binary through thin adapters. If t
 export PATH="/path/to/cli-style/bin:$PATH"
 ```
 
-## JavaScript
+Build a standalone binary when a repo should not need Bun at runtime:
+
+```bash
+bun run build:binary
+bun run smoke:binary
+```
+
+Create a binary install tarball:
+
+```bash
+bun run package:binary
+tar -tzf dist/release/cli-style-*.tar.gz
+```
+
+The package contains `bin/cli-style` and `adapters/`.
+
+## Choose an integration
+
+All renderers return text. JavaScript imports functions directly. CLI, Bash, and Python integrations pass JSON-compatible data to a named renderer.
+
+### JavaScript
+
+Create the `ui` instance at the CLI entrypoint, then pass `ui.options` to renderers. That keeps flag, environment, stream, colour, Unicode, and width detection in one place.
 
 ```js
 import { createCliStyle, status } from "@lewishowles/cli-style";
 
 const ui = createCliStyle({
-	profile: "human",
-	width: 80,
+	argv: process.argv.slice(2),
+	env: process.env,
+	stdout: process.stdout,
 });
 
 const output = status("success", "184 tests", {
@@ -41,52 +66,9 @@ ui.print(output);
 
 Renderer methods return strings. `ui.print()`, `ui.write()`, and CLI commands handle stdout and stderr.
 
-## Reporter
-
-Use a reporter when a script needs grouped output rather than one row per file.
-
-```js
-import { createReporter } from "@lewishowles/cli-style";
-
-const reporter = createReporter({
-	colour: false,
-});
-
-reporter.divider("Project setup", "Claude + Codex");
-reporter.group(
-	"Agent scripts",
-	[
-		{
-			label: "project-diagnostics.py",
-			result: "unchanged",
-		},
-		{
-			label: "repo-context.py",
-			result: "unchanged",
-		},
-	],
-	{
-		summary: "2 already linked",
-	},
-);
-reporter.status("success", "Done.");
-
-console.log(reporter.render());
-```
-
-Use `reporter.divider()` for major phases. Use `reporter.section()` when you want a normal `info` status row inside a phase. Panels are for framed content blocks, not headings.
-
-Groups can include verbose detail rows when a caller opts in:
-
-```js
-const reporter = createReporter({
-	verbose: process.env.AGENTS_VERBOSE === "1",
-});
-```
-
-## CLI
+### CLI render
 
-Use `cli-style render <renderer>` when a script needs rendered text from JSON input.
+Use `cli-style render <renderer>` when a script needs rendered text from JSON input:
 
 ```bash
 cli-style render status --profile diagnostic <<'JSON'
@@ -98,62 +80,53 @@ cli-style render status --profile diagnostic <<'JSON'
 JSON
 ```
 
-```bash
-cli-style render task-summary --plain <<'JSON'
-{
-  "title": "Task summary",
-  "completed": ["Added render command"],
-  "remaining": ["Add adapters"]
-}
-JSON
-```
+Use renderer names from the tables below, for example `status`, `row`, `diagnostic-report`, or `task-summary`.
 
-`render` supports `--profile`, `--plain`, `--no-colour`, `--no-color`, `--no-unicode`, and `--width`. It rejects `--json`; JSON profile behaviour is for library calls and machine-readable commands.
+### Bash
 
-Build a local standalone binary when a repo should not need Bun at runtime:
+Source the Bash adapter, then use convenience helpers for common primitive renderers:
 
 ```bash
-bun run build:binary
-bun run smoke:binary
-```
+source "$(cli-style adapter-path bash)"
 
-Create a binary install tarball:
+label='Build "passed"'
+detail="/path/to/project"
 
-```bash
-bun run package:binary
-tar -tzf dist/release/cli-style-*.tar.gz
+cli_style_status success "$label" "$detail" --profile diagnostic
+cli_style_row "Workspace" "$detail" --plain
+cli_style_row "Bundle" "is 22.3 KB, above the 12.0 KB budget" failed --plain
+command="$(cli_style_span "npm run docs:readme" info --plain)"
+cli_style_hint "Run $command before release" --plain
+cli_style_divider "Project setup" --plain
 ```
 
-The package contains `bin/cli-style` and `adapters/`. Install it into a repo-local tools directory, then call that repo-local `bin/cli-style` from scripts.
+The convenience functions build JSON internally, so callers do not need to escape quotes, backslashes, or paths by hand.
 
-## Bash
+Set `CLI_STYLE_BIN` when `cli-style` is not on `PATH`:
 
 ```bash
-source "$(cli-style adapter-path bash)"
-
-cli_style_render status --profile diagnostic <<'JSON'
-{
-  "type": "success",
-  "label": "Build passed",
-  "detail": "184 tests"
-}
-JSON
+CLI_STYLE_BIN="/path/to/cli-style" cli_style_status success "Build passed" "" --plain
 ```
 
-Set `CLI_STYLE_BIN` when `cli-style` is not on `PATH`:
+Use `cli_style_render` for literal or prebuilt JSON, especially for structured patterns:
 
 ```bash
-CLI_STYLE_BIN="/path/to/cli-style" cli_style_render status --plain <<'JSON'
+cli_style_render diagnostic-report --profile diagnostic <<'JSON'
 {
-  "type": "success",
-  "label": "Build passed"
+  "title": "Release checks",
+  "checks": [
+    {
+      "name": "README",
+      "result": "success"
+    }
+  ]
 }
 JSON
 ```
 
-## Python
+### Python
 
-Add the adapter directory to `PYTHONPATH`, then import the helper:
+Add the adapter directory to `PYTHONPATH`, then import the generic `render()` helper:
 
 ```bash
 export PYTHONPATH="$(cli-style adapter-path python):$PYTHONPATH"
@@ -189,6 +162,308 @@ output = render(
 )
 ```
 
+## Available renderers
+
+Renderer names are stable for `cli-style render`, `cli_style_render`, and Python `render()`. JavaScript uses camel-case function names.
+
+| Renderer        | JavaScript                            | Bash helper                          | Purpose                                                         |
+| --------------- | ------------------------------------- | ------------------------------------ | --------------------------------------------------------------- |
+| `status`        | `status(resultType, detail, options)` | `cli_style_status type label detail` | Result line with symbol, label, and detail.                     |
+| `row`           | `row(label, value, options)`          | `cli_style_row label value [result]` | Aligned label/value row, optionally marked with a result state. |
+| `span`          | `span(value, tone, options)`          | `cli_style_span value [tone]`        | Inline colour or weight for a word, command, file, or value.    |
+| `hint`          | `hint(message, options)`              | `cli_style_hint message`             | Informational hint line.                                        |
+| `divider`       | `divider(options)`                    | `cli_style_divider label`            | Section divider with an optional label.                         |
+| `chip`          | `chip(label, tone, options)`          | Use `cli_style_render`               | Compact labelled state.                                         |
+| `panel`         | `panel(options)`                      | Use `cli_style_render`               | Framed content block for grouped output.                        |
+| `table`         | `table(options)`                      | Use `cli_style_render`               | Tabular records with narrow-width fallback.                     |
+| `progress-bar`  | `progressBar(options)`                | Use `cli_style_render`               | Single progress value with numeric text.                        |
+| `bar-chart`     | `barChart(options)`                   | Use `cli_style_render`               | Multi-row bar chart.                                            |
+| `step`          | `step(label, state, options)`         | Use `cli_style_render`               | One workflow step.                                              |
+| `step-progress` | `stepProgress(options)`               | Use `cli_style_render`               | Numbered workflow steps.                                        |
+| `empty-state`   | `emptyState(title, detail, options)`  | Use `cli_style_render`               | Empty result message.                                           |
+| `error-block`   | `errorBlock(title, lines, options)`   | Use `cli_style_render`               | Structured error block.                                         |
+
+Python uses `render("<renderer>", data, ...)` for every renderer.
+
+## Primitive data shapes
+
+Use these shapes with `cli-style render`, `cli_style_render`, or Python `render()`. JavaScript callers pass the listed function arguments directly.
+
+### `status`
+
+```json
+{
+	"type": "success",
+	"label": "Build passed",
+	"detail": "184 tests"
+}
+```
+
+- `type`: one of the result types listed below
+- `label`: optional label override
+- `detail`: optional text after the label
+
+### `row`
+
+```json
+{
+	"label": "Bundle",
+	"value": "is 22.3 KB, above the 12.0 KB budget",
+	"result": "failed",
+	"labelWidth": 8
+}
+```
+
+- `label`: left-hand label
+- `value`: right-hand value
+- `result`: optional result type for a symbol and tone
+- `labelWidth`: optional minimum label width
+- `labelColour`, `valueColour`, `separator`: optional presentation overrides
+
+### `span`
+
+```json
+{
+	"value": "npm run docs:readme",
+	"tone": "info"
+}
+```
+
+- `value`: inline text to emphasise
+- `tone`: optional tone, defaulting to `info`
+- `weight`: optional ANSI style, defaulting to `bold`
+
+### `hint`
+
+```json
+{
+	"message": "Run npm run docs:readme before release"
+}
+```
+
+Pre-render a `span` when only part of the hint needs emphasis.
+
+### Structured primitives
+
+| Renderer        | Main fields                            |
+| --------------- | -------------------------------------- |
+| `divider`       | `label`, `dividerWidth`, `character`   |
+| `chip`          | `label`, `tone`                        |
+| `panel`         | `title`, `lines`, `tone`, `panelWidth` |
+| `table`         | `columns`, `rows`, `width`             |
+| `progress-bar`  | `value`, `max`, `barWidth`, `tone`     |
+| `bar-chart`     | `rows`, `barWidth`                     |
+| `step`          | `label`, `state`                       |
+| `step-progress` | `steps`, `current`                     |
+| `empty-state`   | `title`, `detail`                      |
+| `error-block`   | `title`, `lines`                       |
+
+For visual examples, run `cli-style gallery --section primitives`.
+
+## Patterns
+
+Patterns are built-in composite renderers for common report shapes. They use the same lower-level primitives internally, but accept structured objects so callers do not need to assemble panels, statuses, tables, and rows by hand.
+
+| Renderer              | JavaScript                                  | Purpose                               | Main fields                                                                          |
+| --------------------- | ------------------------------------------- | ------------------------------------- | ------------------------------------------------------------------------------------ |
+| `diagnostic-report`   | `diagnosticReport(report, options)`         | Aggregate check report.               | `title`, `checks`, `findings`, `skippedChecks`, `nextActions`                        |
+| `command-result`      | `commandResult(result, options)`            | Single command outcome with metadata. | `title`, `result`, `summary`, `command`, `exitCode`, `duration`, `details`           |
+| `audit-finding`       | `auditFinding(finding, options)`            | Single audit finding.                 | `title`, `result`, `finding`, `location`, `evidence`, `recommendation`, `references` |
+| `task-summary`        | `taskSummary(summary, options)`             | Completed and remaining task summary. | `title`, `task`, `result`, `summary`, `completed`, `remaining`                       |
+| `agent-transcript`    | `agentTranscript(transcript, options)`      | User, agent, and tool transcript.     | `title`, `entries`                                                                   |
+| `confirmation-result` | `confirmationResult(confirmation, options)` | Confirmation outcome with detail.     | `title`, `state`, `action`, `item`, `detail`                                         |
+| `next-step-block`     | `nextStepBlock(nextStep, options)`          | Next-step guidance.                   | `title`, `next`, `reason`, `commands`, `alternatives`                                |
+| `compact-data-table`  | `compactDataTable(data, options)`           | Titled compact data table.            | `title`, `summary`, `columns`, `rows`                                                |
+
+For visual examples, run `cli-style gallery --section patterns`.
+
+### Pattern example
+
+JavaScript:
+
+```js
+import { createCliStyle, diagnosticReport } from "@lewishowles/cli-style";
+
+const ui = createCliStyle({
+	argv: process.argv.slice(2),
+	env: process.env,
+	stdout: process.stdout,
+});
+
+const output = diagnosticReport(
+	{
+		title: "Release checks",
+		checks: [
+			{
+				name: "README",
+				result: "success",
+			},
+			{
+				detail: "object-BmsQavd_.js over budget",
+				name: "Package size",
+				result: "failed",
+			},
+		],
+		findings: [
+			{
+				message: "dist/object-BmsQavd_.js is 22.3 KB, above the 12.0 KB budget",
+				result: "failed",
+			},
+		],
+		nextActions: ["Reduce package size, or raise the budget with a release-note-worthy reason."],
+	},
+	ui.options,
+);
+
+ui.print(output);
+```
+
+CLI:
+
+```bash
+cli-style render diagnostic-report --profile diagnostic <<'JSON'
+{
+  "title": "Release checks",
+  "checks": [
+    {
+      "name": "README",
+      "result": "success"
+    },
+    {
+      "name": "Package size",
+      "result": "failed",
+      "detail": "object-BmsQavd_.js over budget"
+    }
+  ],
+  "findings": [
+    {
+      "result": "failed",
+      "message": "dist/object-BmsQavd_.js is 22.3 KB, above the 12.0 KB budget"
+    }
+  ],
+  "nextActions": [
+    "Reduce package size, or raise the budget with a release-note-worthy reason."
+  ]
+}
+JSON
+```
+
+Python:
+
+```python
+from cli_style import render
+
+output = render(
+	"diagnostic-report",
+	{
+		"title": "Release checks",
+		"checks": [
+			{
+				"name": "README",
+				"result": "success",
+			},
+			{
+				"name": "Package size",
+				"result": "failed",
+				"detail": "object-BmsQavd_.js over budget",
+			},
+		],
+		"findings": [
+			{
+				"result": "failed",
+				"message": "dist/object-BmsQavd_.js is 22.3 KB, above the 12.0 KB budget",
+			},
+		],
+		"nextActions": [
+			"Reduce package size, or raise the budget with a release-note-worthy reason.",
+		],
+	},
+	profile="diagnostic",
+)
+```
+
+## Reporter
+
+Use a reporter when a JavaScript script needs grouped output built over time.
+
+```js
+import { createReporter } from "@lewishowles/cli-style";
+
+const reporter = createReporter({
+	colour: false,
+});
+
+reporter.divider("Project setup", "Claude + Codex");
+reporter.group(
+	"Agent scripts",
+	[
+		{
+			label: "project-diagnostics.py",
+			result: "unchanged",
+		},
+		{
+			label: "repo-context.py",
+			result: "unchanged",
+		},
+	],
+	{
+		summary: "2 already linked",
+	},
+);
+reporter.status("success", "Done.");
+
+console.log(reporter.render());
+```
+
+Use `reporter.divider()` for major phases. Use `reporter.section()` for a normal `info` status row inside a phase. Panels are for framed content blocks, not headings.
+
+Groups can include verbose detail rows when a caller opts in:
+
+```js
+const reporter = createReporter({
+	verbose: process.env.AGENTS_VERBOSE === "1",
+});
+```
+
+## Options and flags
+
+### JavaScript options
+
+Most renderers accept the same output options:
+
+| Option    | Purpose                                                                   |
+| --------- | ------------------------------------------------------------------------- |
+| `profile` | Output profile: `human`, `agent`, `diagnostic`, `ci`, `plain`, or `json`. |
+| `colour`  | Whether ANSI colour should be applied.                                    |
+| `unicode` | Whether Unicode symbols should be used.                                   |
+| `width`   | Available output width for renderers that adapt layout.                   |
+
+Use `createCliStyle()` to resolve these options from `argv`, `env`, `stdout`, CI, TTY, `NO_COLOR`, and terminal capability.
+
+### CLI and Bash flags
+
+| Flag                         | Purpose                                |
+| ---------------------------- | -------------------------------------- |
+| `--profile <name>`           | Render with a named profile.           |
+| `--plain`                    | Disable colour and Unicode decoration. |
+| `--no-colour` / `--no-color` | Disable ANSI colour.                   |
+| `--no-unicode`               | Use ASCII symbols.                     |
+| `--width <columns>`          | Override detected output width.        |
+
+`cli-style render` rejects `--json`. JSON profile behaviour is for library calls and machine-readable commands.
+
+### Python options
+
+| Argument     | Purpose                                          |
+| ------------ | ------------------------------------------------ |
+| `profile`    | Render with a named profile.                     |
+| `width`      | Override detected output width.                  |
+| `plain`      | Disable colour and Unicode decoration.           |
+| `no_colour`  | Disable ANSI colour.                             |
+| `no_unicode` | Use ASCII symbols.                               |
+| `binary`     | Path or command name for the `cli-style` binary. |
+| `extra_args` | Extra CLI arguments to pass through.             |
+
 ## Profiles
 
 | Profile      | Behaviour                                                                         |
@@ -200,11 +475,31 @@ output = render(
 | `plain`      | No ANSI, no Unicode dependency, simple text layout.                               |
 | `json`       | Machine-readable only; library calls return structured data unchanged.            |
 
+## Result types and tones
+
+Result types drive symbols, labels, priority, and semantic colour:
+
+| Result      | Label     | Unicode | ASCII | Tone      |
+| ----------- | --------- | ------- | ----- | --------- |
+| `success`   | Success   | `✓`     | `OK`  | `success` |
+| `info`      | Info      | `→`     | `>`   | `info`    |
+| `warning`   | Warning   | `⚠`     | `!`   | `warning` |
+| `partial`   | Partial   | `◐`     | `!`   | `warning` |
+| `unchanged` | Unchanged | `↪`     | `-`   | `muted`   |
+| `skipped`   | Skipped   | `–`     | `-`   | `muted`   |
+| `unknown`   | Unknown   | `?`     | `?`   | `muted`   |
+| `failed`    | Failed    | `×`     | `x`   | `danger`  |
+
+Tone values used by public APIs include `info`, `success`, `warning`, `danger`, and `muted`.
+
 ## Gallery
 
+Use the gallery to review current renderer output:
+
 ```bash
 cli-style gallery
 cli-style gallery no-colour
+cli-style gallery --section primitives
 cli-style gallery --section patterns
 cli-style gallery --fixture audit-finding
 cli-style gallery --profile agent
@@ -212,4 +507,4 @@ cli-style gallery --width 64
 cli-style gallery --variants
 ```
 
-Use the gallery to review current renderer output. Use `--interactive` to select a section or fixture with `fzf` when it is installed.
+Use `--interactive` to select a section or fixture with `fzf` when it is installed.

package/adapters/bash/cli-style.sh

@@ -23,6 +23,40 @@ cli_style_has_binary() {
 	command -v "$binary" >/dev/null 2>&1
 }
 
+# Escape a Bash string for JSON string values.
+#
+# @param  {string}  value
+#     String value to encode.
+cli_style_json_string() {
+	local value="${1:-}"
+
+	value="${value//\\/\\\\}"
+	value="${value//\"/\\\"}"
+	value="${value//$'\b'/\\b}"
+	value="${value//$'\f'/\\f}"
+	value="${value//$'\n'/\\n}"
+	value="${value//$'\r'/\\r}"
+	value="${value//$'\t'/\\t}"
+
+	printf '"%s"' "$value"
+}
+
+# Render a JSON object through the shared cli-style command.
+#
+# @param  {string}  renderer
+#     Stable renderer name accepted by `cli-style render`.
+# @param  {string}  json
+#     Prebuilt JSON object.
+# @param  {string}  ...
+#     Render flags passed through to `cli-style render`.
+cli_style_render_json() {
+	local renderer="${1:-}"
+	local json="${2:-}"
+
+	shift 2
+	printf '%s\n' "$json" | cli_style_render "$renderer" "$@"
+}
+
 # Render stdin JSON through the shared cli-style command.
 #
 # @param  {string}  renderer
@@ -48,3 +82,129 @@ cli_style_render() {
 
 	"$binary" render "$renderer" "$@"
 }
+
+# Render a result status line from Bash string values.
+#
+# @param  {string}  type
+#     Result type such as success, failed, warning, or skipped.
+# @param  {string}  label
+#     Status label.
+# @param  {string}  detail
+#     Optional detail text.
+# @param  {string}  ...
+#     Render flags passed through to `cli-style render`.
+cli_style_status() {
+	local type="${1:-}"
+	local label="${2:-}"
+	local detail="${3:-}"
+	local json
+
+	if (($# >= 3)); then
+		shift 3
+	else
+		set --
+	fi
+
+	json="{\"type\":$(cli_style_json_string "$type"),\"label\":$(cli_style_json_string "$label"),\"detail\":$(cli_style_json_string "$detail")}"
+
+	cli_style_render_json status "$json" "$@"
+}
+
+# Render a labelled value row from Bash string values.
+#
+# @param  {string}  label
+#     Row label.
+# @param  {string}  value
+#     Row value.
+# @param  {string}  result
+#     Optional result type before render flags.
+# @param  {string}  ...
+#     Render flags passed through to `cli-style render`.
+cli_style_row() {
+	local label="${1:-}"
+	local value="${2:-}"
+	local result=""
+	local json
+
+	if (($# >= 3)) && [[ "${3:-}" != --* ]]; then
+		result="${3:-}"
+		shift 3
+	elif (($# >= 2)); then
+		shift 2
+	else
+		set --
+	fi
+
+	json="{\"label\":$(cli_style_json_string "$label"),\"value\":$(cli_style_json_string "$value"),\"result\":$(cli_style_json_string "$result")}"
+
+	cli_style_render_json row "$json" "$@"
+}
+
+# Render an inline span from Bash string values.
+#
+# @param  {string}  value
+#     Span text.
+# @param  {string}  tone
+#     Optional colour tone.
+# @param  {string}  ...
+#     Render flags passed through to `cli-style render`.
+cli_style_span() {
+	local value="${1:-}"
+	local tone="info"
+	local json
+
+	if (($# >= 2)) && [[ "${2:-}" != --* ]]; then
+		tone="${2:-}"
+		shift 2
+	elif (($# >= 1)); then
+		shift
+	else
+		set --
+	fi
+
+	json="{\"value\":$(cli_style_json_string "$value"),\"tone\":$(cli_style_json_string "$tone")}"
+
+	cli_style_render_json span "$json" "$@"
+}
+
+# Render a divider from a Bash string value.
+#
+# @param  {string}  label
+#     Optional divider label.
+# @param  {string}  ...
+#     Render flags passed through to `cli-style render`.
+cli_style_divider() {
+	local label="${1:-}"
+	local json
+
+	if (($# >= 1)); then
+		shift
+	else
+		set --
+	fi
+
+	json="{\"label\":$(cli_style_json_string "$label")}"
+
+	cli_style_render_json divider "$json" "$@"
+}
+
+# Render a hint from a Bash string value.
+#
+# @param  {string}  message
+#     Hint message.
+# @param  {string}  ...
+#     Render flags passed through to `cli-style render`.
+cli_style_hint() {
+	local message="${1:-}"
+	local json
+
+	if (($# >= 1)); then
+		shift
+	else
+		set --
+	fi
+
+	json="{\"message\":$(cli_style_json_string "$message")}"
+
+	cli_style_render_json hint "$json" "$@"
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@lewishowles/cli-style",
-	"version": "0.4.1",
+	"version": "0.6.0",
 	"description": "Shared terminal output styles for Lewis Howles tools, diagnostics, and package CLIs.",
 	"license": "MIT",
 	"repository": {

package/src/cli/render-command.js

@@ -13,6 +13,7 @@ import { emptyState, errorBlock, hint } from "../primitives/feedback.js";
 import { panel } from "../primitives/panel.js";
 import { progressBar } from "../primitives/progress-bar.js";
 import { row } from "../primitives/row.js";
+import { span } from "../primitives/span.js";
 import { status } from "../primitives/status.js";
 import { step, stepProgress } from "../primitives/step-progress.js";
 import { table } from "../primitives/table.js";
@@ -72,6 +73,11 @@ const renderers = {
 			...input,
 			...options,
 		}),
+	span: (input, options) =>
+		span(input.value, input.tone, {
+			...input,
+			...options,
+		}),
 	status: (input, options) =>
 		status(input.type, input.detail, {
 			...input,

package/src/gallery/render-gallery.js

@@ -14,6 +14,7 @@ import { emptyState, errorBlock, hint } from "../primitives/feedback.js";
 import { panel } from "../primitives/panel.js";
 import { progressBar } from "../primitives/progress-bar.js";
 import { row } from "../primitives/row.js";
+import { span } from "../primitives/span.js";
 import { status } from "../primitives/status.js";
 import { step, stepProgress, stepStates } from "../primitives/step-progress.js";
 import { table } from "../primitives/table.js";
@@ -676,7 +677,7 @@ function renderPrimitives(options) {
 		}),
 		"",
 		"Feedback",
-		hint("tone: info", options),
+		hint(`Run ${span("npm run docs:readme", "info", options)}`, options),
 		emptyState("No results", "tone: muted", options),
 		errorBlock("Failed", ["tone: danger"], {
 			...options,
@@ -709,6 +710,11 @@ function renderPrimitives(options) {
 			...options,
 			labelWidth: 8,
 		}),
+		row("Bundle", "is 22.3 KB, above the 12.0 KB budget", {
+			...options,
+			labelWidth: 8,
+			result: resultTypes.FAILED,
+		}),
 	].join("\n");
 }
 

package/src/index.js

@@ -35,6 +35,7 @@ export { emptyState, errorBlock, hint } from "./primitives/feedback.js";
 export { panel } from "./primitives/panel.js";
 export { progressBar } from "./primitives/progress-bar.js";
 export { row } from "./primitives/row.js";
+export { span } from "./primitives/span.js";
 export { status } from "./primitives/status.js";
 export { step, stepProgress, stepStates } from "./primitives/step-progress.js";
 export { table } from "./primitives/table.js";

package/src/primitives/row.js

@@ -1,4 +1,5 @@
 import { foreground } from "../formatters/ansi.js";
+import { getResultSymbol, getResultToken } from "../theme/results.js";
 
 // Row labels use the same subdued tone as table headers by default.
 const defaultLabelColour = "muted";
@@ -21,6 +22,8 @@ const defaultSeparator = "  ";
  *     Colour token for the label.
  * @param  {number}  options.labelWidth
  *     Minimum label width before the separator.
+ * @param  {string}  options.result
+ *     Optional semantic result state for the row.
  * @param  {string}  options.separator
  *     Text between label and value.
  * @param  {string}  options.valueColour
@@ -29,8 +32,10 @@ const defaultSeparator = "  ";
  *     Rendered row.
  */
 export function row(label, value = "", options = {}) {
-	const labelWidth = Math.max(label.length, options.labelWidth ?? 0);
-	const labelText = label.padEnd(labelWidth, " ");
+	const resultToken = resolveResultToken(options);
+	const displayLabel = renderDisplayLabel(label, resultToken, options);
+	const labelWidth = Math.max(displayLabel.length, options.labelWidth ?? 0);
+	const labelText = displayLabel.padEnd(labelWidth, " ");
 	const renderedLabel = renderLabel(labelText, options);
 
 	if (value === "") {
@@ -43,6 +48,44 @@ export function row(label, value = "", options = {}) {
 	return `${renderedLabel}${separator}${renderedValue}`;
 }
 
+/**
+ * Resolve the row's optional result token.
+ *
+ * @param  {object}  options
+ *     Rendering options.
+ * @returns  {object|null}
+ *     Result token when a row result is provided.
+ */
+function resolveResultToken(options) {
+	if (typeof options.result !== "string" || options.result === "") {
+		return null;
+	}
+
+	return getResultToken(options.result);
+}
+
+/**
+ * Render the visible row label, including any result symbol.
+ *
+ * @param  {string}  label
+ *     Label text to render.
+ * @param  {object|null}  resultToken
+ *     Optional result token.
+ * @param  {object}  options
+ *     Rendering options.
+ * @returns  {string}
+ *     Label text with any result prefix.
+ */
+function renderDisplayLabel(label, resultToken, options) {
+	if (resultToken === null) {
+		return label;
+	}
+
+	const symbol = getResultSymbol(options.result, options);
+
+	return `${symbol} ${label}`;
+}
+
 /**
  * Render a row label.
  *
@@ -58,7 +101,7 @@ function renderLabel(label, options) {
 		return label;
 	}
 
-	return foreground(label, options.labelColour ?? defaultLabelColour, options);
+	return foreground(label, getLabelColour(options), options);
 }
 
 /**
@@ -72,9 +115,55 @@ function renderLabel(label, options) {
  *     Rendered value.
  */
 function renderValue(value, options) {
-	if (options.colour !== true || options.valueColour === undefined) {
+	if (options.colour !== true) {
+		return value;
+	}
+
+	const colour = getValueColour(options);
+
+	if (colour === undefined) {
 		return value;
 	}
 
-	return foreground(value, options.valueColour, options);
+	return foreground(value, colour, options);
+}
+
+/**
+ * Resolve the colour token for the row label.
+ *
+ * @param  {object}  options
+ *     Rendering options.
+ * @returns  {string}
+ *     Colour token for the label.
+ */
+function getLabelColour(options) {
+	if (options.labelColour !== undefined) {
+		return options.labelColour;
+	}
+
+	if (typeof options.result === "string" && options.result !== "") {
+		return getResultToken(options.result).tone;
+	}
+
+	return defaultLabelColour;
+}
+
+/**
+ * Resolve the colour token for the row value.
+ *
+ * @param  {object}  options
+ *     Rendering options.
+ * @returns  {string|undefined}
+ *     Colour token for the value.
+ */
+function getValueColour(options) {
+	if (options.valueColour !== undefined) {
+		return options.valueColour;
+	}
+
+	if (typeof options.result === "string" && options.result !== "") {
+		return getResultToken(options.result).tone;
+	}
+
+	return undefined;
 }

package/src/primitives/span.js

@@ -0,0 +1,33 @@
+import { foreground, style } from "../formatters/ansi.js";
+
+// Inline spans use the same informational tone as hints by default.
+const defaultTone = "info";
+
+// Inline emphasis should remain visible without forcing a block-level renderer.
+const defaultWeight = "bold";
+
+/**
+ * Render an inline text span.
+ *
+ * @param  {string}  value
+ *     Text to render.
+ * @param  {string}  tone
+ *     Colour tone for the span.
+ * @param  {object}  options
+ *     Rendering options.
+ * @param  {boolean}  options.colour
+ *     Whether ANSI colour should be applied.
+ * @param  {string}  options.weight
+ *     Optional ANSI text weight.
+ * @returns  {string}
+ *     Rendered span.
+ */
+export function span(value = "", tone = defaultTone, options = {}) {
+	if (options.colour !== true) {
+		return value;
+	}
+
+	const renderedValue = foreground(value, tone, options);
+
+	return style(renderedValue, options.weight ?? defaultWeight, options);
+}

package/src/theme/colours.js

@@ -5,7 +5,7 @@ export const colourTokens = {
 	border: "#2a3a42",
 	danger: "#ff7272",
 	info: "#8bbdff",
-	muted: "#6f7f87",
+	muted: "#7a8a92",
 	success: "#8fdf72",
 	surface: "#0f181b",
 	surfaceRaised: "#132024",