blessed-components 0.0.1 → 1.1.0

package/dist/sparkline/index.d.ts

@@ -0,0 +1,123 @@
+/**
+ * Options accepted by {@link renderSparkline}.
+ *
+ * Samples are kept in input order, scaled into `characters`, and reduced to at
+ * most `width` cells. Values outside an explicit domain are clamped.
+ */
+interface RenderSparklineOptions {
+    /**
+     * Ordered glyph scale from lowest to highest intensity.
+     *
+     * At least two non-empty strings are required. Glyphs should occupy one
+     * terminal cell to keep output width predictable.
+     *
+     * @defaultValue `['▁', '▂', '▃', '▄', '▅', '▆', '▇', '█']`
+     */
+    characters?: readonly string[];
+    /**
+     * Text returned when `values` is empty.
+     *
+     * Metadata is not rendered for an empty series.
+     *
+     * @defaultValue `'No data'`
+     */
+    emptyText?: string;
+    /** Optional heading label rendered above the graph. */
+    label?: string;
+    /**
+     * Explicit upper domain bound.
+     *
+     * When omitted, the largest input value is used. If either explicit bound is
+     * supplied, the resolved `max` must be greater than the resolved `min`.
+     */
+    max?: number;
+    /**
+     * Explicit lower domain bound.
+     *
+     * When omitted, the smallest input value is used.
+     */
+    min?: number;
+    /** Optional text appended to the graph line after one space. */
+    summary?: string;
+    /**
+     * Optional primary value rendered next to `label`.
+     *
+     * This value is presentation metadata and does not affect graph scaling.
+     */
+    value?: number | string;
+    /**
+     * Ordered finite numeric samples.
+     *
+     * The input array is never mutated.
+     */
+    values: readonly number[];
+    /**
+     * Positive integer maximum number of graph cells.
+     *
+     * Longer series are downsampled. Shorter series are not padded.
+     */
+    width: number;
+}
+/**
+ * Renders a deterministic terminal sparkline.
+ *
+ * This pure renderer does not import Blessed. Use the
+ * `blessed-components/sparkline` subpath to keep the Blessed adapter outside
+ * the module graph.
+ *
+ * When downsampling is required, the series is divided into ordered buckets
+ * and each bucket keeps its maximum value. This preserves narrow peaks. A
+ * constant series uses the middle glyph to avoid division by zero.
+ *
+ * Output shape:
+ *
+ * ```text
+ * [optional label and value]
+ * [graph][optional summary]
+ * ```
+ *
+ * With no metadata, only the graph line is returned.
+ *
+ * @param options - Series, domain, width, glyphs, and optional metadata.
+ * @returns Plain text without ANSI sequences or Blessed tags.
+ *
+ * @throws `RangeError`
+ * Thrown when `width` is not a positive integer.
+ *
+ * @throws `RangeError`
+ * Thrown when fewer than two non-empty characters are provided.
+ *
+ * @throws `RangeError`
+ * Thrown when any sample or domain bound is not finite.
+ *
+ * @throws `RangeError`
+ * Thrown when an explicit domain does not have `max > min`.
+ *
+ * @example Basic series
+ *
+ * ```ts
+ * import { renderSparkline } from 'blessed-components/sparkline';
+ *
+ * renderSparkline({
+ *   values: [1, 2, 3, 4, 5, 6, 7, 8],
+ *   width: 8,
+ * });
+ * // "▁▂▃▄▅▆▇█"
+ * ```
+ *
+ * @example Metadata and summary
+ *
+ * ```ts
+ * renderSparkline({
+ *   label: 'Downloads',
+ *   value: '25.2M',
+ *   values: [1, 3, 2, 8],
+ *   width: 4,
+ *   summary: 'peak: 8M',
+ * });
+ * // "Downloads 25.2M\n▁▃▂█ peak: 8M"
+ * ```
+ */
+declare function renderSparkline({ characters, emptyText, label, max: configuredMax, min: configuredMin, summary, value: displayValue, values, width, }: RenderSparklineOptions): string;
+
+export { type RenderSparklineOptions, renderSparkline };

package/dist/sparkline/index.js

@@ -0,0 +1,57 @@
+// src/components/sparkline/index.ts
+var DEFAULT_CHARACTERS = ["\u2581", "\u2582", "\u2583", "\u2584", "\u2585", "\u2586", "\u2587", "\u2588"];
+function renderSparkline({
+  characters = DEFAULT_CHARACTERS,
+  emptyText = "No data",
+  label,
+  max: configuredMax,
+  min: configuredMin,
+  summary,
+  value: displayValue,
+  values,
+  width
+}) {
+  if (!Number.isInteger(width) || width < 1) {
+    throw new RangeError("Sparkline width must be a positive integer.");
+  }
+  if (characters.length < 2 || characters.some((character) => character.length === 0)) {
+    throw new RangeError("Sparkline characters must contain at least two non-empty strings.");
+  }
+  if (values.some((value) => !Number.isFinite(value))) {
+    throw new RangeError("Sparkline values must be finite.");
+  }
+  if (values.length === 0) {
+    return emptyText;
+  }
+  const min = configuredMin ?? Math.min(...values);
+  const max = configuredMax ?? Math.max(...values);
+  if (!Number.isFinite(min) || !Number.isFinite(max) || max < min) {
+    throw new RangeError("Sparkline max must be greater than or equal to min.");
+  }
+  if ((configuredMin !== void 0 || configuredMax !== void 0) && max === min) {
+    throw new RangeError("Sparkline explicit max must be greater than min.");
+  }
+  const constantIndex = Math.floor((characters.length - 1) / 2);
+  const samples = values.length <= width ? values : Array.from({ length: width }, (_, index) => {
+    const start = Math.floor(index * values.length / width);
+    const end = Math.floor((index + 1) * values.length / width);
+    return Math.max(...values.slice(start, end));
+  });
+  const sparkline = samples.map((value) => {
+    if (min === max) {
+      return characters[constantIndex];
+    }
+    const clampedValue = Math.min(max, Math.max(min, value));
+    const ratio = (clampedValue - min) / (max - min);
+    const index = clampedValue >= max ? characters.length - 1 : Math.floor(ratio * (characters.length - 1));
+    return characters[index];
+  }).join("");
+  const heading = [label, displayValue].filter((part) => part !== void 0).join(" ");
+  const chartLine = summary === void 0 ? sparkline : `${sparkline} ${summary}`;
+  return heading.length === 0 ? chartLine : `${heading}
+${chartLine}`;
+}
+
+export { renderSparkline };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/sparkline/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/components/sparkline/index.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["const DEFAULT_CHARACTERS = ['▁', '▂', '▃', '▄', '▅', '▆', '▇', '█'] as const;\n\n/**\n * Options accepted by {@link renderSparkline}.\n *\n * Samples are kept in input order, scaled into `characters`, and reduced to at\n * most `width` cells. Values outside an explicit domain are clamped.\n */\nexport interface RenderSparklineOptions {\n  /**\n   * Ordered glyph scale from lowest to highest intensity.\n   *\n   * At least two non-empty strings are required. Glyphs should occupy one\n   * terminal cell to keep output width predictable.\n   *\n   * @defaultValue `['▁', '▂', '▃', '▄', '▅', '▆', '▇', '█']`\n   */\n  characters?: readonly string[];\n\n  /**\n   * Text returned when `values` is empty.\n   *\n   * Metadata is not rendered for an empty series.\n   *\n   * @defaultValue `'No data'`\n   */\n  emptyText?: string;\n\n  /** Optional heading label rendered above the graph. */\n  label?: string;\n\n  /**\n   * Explicit upper domain bound.\n   *\n   * When omitted, the largest input value is used. If either explicit bound is\n   * supplied, the resolved `max` must be greater than the resolved `min`.\n   */\n  max?: number;\n\n  /**\n   * Explicit lower domain bound.\n   *\n   * When omitted, the smallest input value is used.\n   */\n  min?: number;\n\n  /** Optional text appended to the graph line after one space. */\n  summary?: string;\n\n  /**\n   * Optional primary value rendered next to `label`.\n   *\n   * This value is presentation metadata and does not affect graph scaling.\n   */\n  value?: number | string;\n\n  /**\n   * Ordered finite numeric samples.\n   *\n   * The input array is never mutated.\n   */\n  values: readonly number[];\n\n  /**\n   * Positive integer maximum number of graph cells.\n   *\n   * Longer series are downsampled. Shorter series are not padded.\n   */\n  width: number;\n}\n\n/**\n * Renders a deterministic terminal sparkline.\n *\n * This pure renderer does not import Blessed. Use the\n * `blessed-components/sparkline` subpath to keep the Blessed adapter outside\n * the module graph.\n *\n * When downsampling is required, the series is divided into ordered buckets\n * and each bucket keeps its maximum value. This preserves narrow peaks. A\n * constant series uses the middle glyph to avoid division by zero.\n *\n * Output shape:\n *\n * ```text\n * [optional label and value]\n * [graph][optional summary]\n * ```\n *\n * With no metadata, only the graph line is returned.\n *\n * @param options - Series, domain, width, glyphs, and optional metadata.\n * @returns Plain text without ANSI sequences or Blessed tags.\n *\n * @throws `RangeError`\n * Thrown when `width` is not a positive integer.\n *\n * @throws `RangeError`\n * Thrown when fewer than two non-empty characters are provided.\n *\n * @throws `RangeError`\n * Thrown when any sample or domain bound is not finite.\n *\n * @throws `RangeError`\n * Thrown when an explicit domain does not have `max > min`.\n *\n * @example Basic series\n *\n * ```ts\n * import { renderSparkline } from 'blessed-components/sparkline';\n *\n * renderSparkline({\n *   values: [1, 2, 3, 4, 5, 6, 7, 8],\n *   width: 8,\n * });\n * // \"▁▂▃▄▅▆▇█\"\n * ```\n *\n * @example Metadata and summary\n *\n * ```ts\n * renderSparkline({\n *   label: 'Downloads',\n *   value: '25.2M',\n *   values: [1, 3, 2, 8],\n *   width: 4,\n *   summary: 'peak: 8M',\n * });\n * // \"Downloads 25.2M\\n▁▃▂█ peak: 8M\"\n * ```\n */\nexport function renderSparkline({\n  characters = DEFAULT_CHARACTERS,\n  emptyText = 'No data',\n  label,\n  max: configuredMax,\n  min: configuredMin,\n  summary,\n  value: displayValue,\n  values,\n  width,\n}: RenderSparklineOptions): string {\n  if (!Number.isInteger(width) || width < 1) {\n    throw new RangeError('Sparkline width must be a positive integer.');\n  }\n\n  if (characters.length < 2 || characters.some((character) => character.length === 0)) {\n    throw new RangeError('Sparkline characters must contain at least two non-empty strings.');\n  }\n\n  if (values.some((value) => !Number.isFinite(value))) {\n    throw new RangeError('Sparkline values must be finite.');\n  }\n\n  if (values.length === 0) {\n    return emptyText;\n  }\n\n  const min = configuredMin ?? Math.min(...values);\n  const max = configuredMax ?? Math.max(...values);\n\n  if (!Number.isFinite(min) || !Number.isFinite(max) || max < min) {\n    throw new RangeError('Sparkline max must be greater than or equal to min.');\n  }\n\n  if ((configuredMin !== undefined || configuredMax !== undefined) && max === min) {\n    throw new RangeError('Sparkline explicit max must be greater than min.');\n  }\n\n  const constantIndex = Math.floor((characters.length - 1) / 2);\n  const samples =\n    values.length <= width\n      ? values\n      : Array.from({ length: width }, (_, index) => {\n          const start = Math.floor((index * values.length) / width);\n          const end = Math.floor(((index + 1) * values.length) / width);\n\n          return Math.max(...values.slice(start, end));\n        });\n  const sparkline = samples\n    .map((value) => {\n      if (min === max) {\n        return characters[constantIndex];\n      }\n\n      const clampedValue = Math.min(max, Math.max(min, value));\n      const ratio = (clampedValue - min) / (max - min);\n      const index =\n        clampedValue >= max ? characters.length - 1 : Math.floor(ratio * (characters.length - 1));\n\n      return characters[index];\n    })\n    .join('');\n  const heading = [label, displayValue].filter((part) => part !== undefined).join(' ');\n  const chartLine = summary === undefined ? sparkline : `${sparkline} ${summary}`;\n\n  return heading.length === 0 ? chartLine : `${heading}\\n${chartLine}`;\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "blessed-components",
-  "version": "0.0.1",
+  "version": "1.1.0",
   "description": "Composable, typed terminal UI components for Blessed.",
   "keywords": [
     "blessed",
@@ -28,13 +28,34 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js",
       "require": "./dist/index.cjs"
+    },
+    "./progress-bar": {
+      "types": "./dist/progress-bar/index.d.ts",
+      "import": "./dist/progress-bar/index.js",
+      "require": "./dist/progress-bar/index.cjs"
+    },
+    "./progress-bar/blessed": {
+      "types": "./dist/progress-bar/blessed.d.ts",
+      "import": "./dist/progress-bar/blessed.js",
+      "require": "./dist/progress-bar/blessed.cjs"
+    },
+    "./sparkline": {
+      "types": "./dist/sparkline/index.d.ts",
+      "import": "./dist/sparkline/index.js",
+      "require": "./dist/sparkline/index.cjs"
+    },
+    "./sparkline/blessed": {
+      "types": "./dist/sparkline/blessed.d.ts",
+      "import": "./dist/sparkline/blessed.js",
+      "require": "./dist/sparkline/blessed.cjs"
     }
   },
   "files": [
     "dist",
     "LICENSE",
     "README.md",
-    "ROADMAP.md"
+    "ROADMAP.md",
+    "src/components/*/README.md"
   ],
   "sideEffects": false,
   "engines": {
@@ -47,35 +68,42 @@
   "scripts": {
     "build": "tsup",
     "clean": "rm -rf coverage dist",
-    "format": "prettier --write .",
-    "format:check": "prettier --check .",
+    "docs": "typedoc --options typedoc.json",
+    "docs:check": "typedoc --options typedoc.json --emit none",
+    "biome:check": "biome check .",
+    "format": "biome check --write .",
+    "format:check": "biome check .",
     "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "preview": "tsx examples/preview-prototype/app.ts",
     "release": "semantic-release",
-    "test": "vitest run --passWithNoTests",
+    "test": "vitest run",
+    "test:package": "node tests/package-exports.mjs",
     "test:watch": "vitest",
     "typecheck": "tsc --noEmit",
-    "validate": "npm run format:check && npm run lint && npm run typecheck && npm test && npm run build",
+    "validate": "npm run format:check && npm run lint && npm run typecheck && npm test && npm run docs:check && npm run build && npm run test:package",
     "prepublishOnly": "npm run validate"
   },
   "peerDependencies": {
     "blessed": "^0.1.81"
   },
   "devDependencies": {
-    "@eslint/js": "^10.0.1",
+    "@biomejs/biome": "^2.5.0",
     "@semantic-release/commit-analyzer": "^13.0.1",
+    "@semantic-release/exec": "^7.1.0",
     "@semantic-release/github": "^12.0.8",
     "@semantic-release/npm": "^13.1.5",
     "@semantic-release/release-notes-generator": "^14.1.1",
     "@types/blessed": "^0.1.27",
     "@types/node": "^22.20.0",
     "conventional-changelog-conventionalcommits": "^9.3.1",
-    "eslint": "^10.5.0",
-    "eslint-config-prettier": "^10.1.8",
-    "prettier": "^3.8.4",
+    "eslint": "^9.39.4",
     "semantic-release": "^25.0.5",
+    "super-configs": "^1.15.0",
+    "tsx": "^4.21.0",
     "tsup": "^8.5.1",
+    "typedoc": "^0.28.19",
     "typescript": "^6.0.3",
-    "typescript-eslint": "^8.61.1",
     "vitest": "^4.1.9"
   }
-}
+}

package/src/components/progress-bar/README.md

@@ -0,0 +1,193 @@
+# ProgressBar
+
+Render a bounded numeric value as a fixed-width terminal progress track.
+
+## Features
+
+- Pure renderer usable without a live terminal.
+- Blessed adapter with explicit update and destroy methods.
+- Custom numeric ranges.
+- Automatic clamping.
+- Unicode defaults and custom ASCII characters.
+- Custom labels and value formatting.
+- Dedicated subpath exports for tree shaking.
+- No automatic `screen.render()` calls.
+
+## Installation
+
+```sh
+npm install blessed blessed-components
+```
+
+`blessed` is a peer dependency.
+
+## Pure renderer
+
+Importing this entry does not load Blessed:
+
+```ts
+import { renderProgressBar } from 'blessed-components/progress-bar';
+
+const output = renderProgressBar({
+  label: 'Quality',
+  value: 78,
+  width: 16,
+});
+
+// Quality ████████████░░░░ 78%
+```
+
+### Custom range
+
+```ts
+renderProgressBar({
+  min: 10,
+  max: 20,
+  value: 15,
+  width: 10,
+});
+
+// █████░░░░░ 50%
+```
+
+### ASCII mode
+
+```ts
+renderProgressBar({
+  characters: {
+    filled: '#',
+    empty: '-',
+  },
+  value: 50,
+  width: 10,
+});
+
+// #####----- 50%
+```
+
+### Custom value
+
+```ts
+renderProgressBar({
+  formatValue: ({ value }) => `${value} files`,
+  label: 'Uploaded',
+  value: 25,
+  width: 8,
+});
+
+// Uploaded ██░░░░░░ 25 files
+```
+
+## Blessed adapter
+
+Use the separate Blessed entry when an element is needed:
+
+```ts
+import blessed from 'blessed';
+import { progressBar } from 'blessed-components/progress-bar/blessed';
+
+const screen = blessed.screen({ smartCSR: true });
+
+const upload = progressBar({
+  parent: screen,
+  box: {
+    top: 0,
+    left: 0,
+    width: 40,
+    height: 1,
+  },
+  data: {
+    label: 'Uploaded',
+    value: 25,
+    width: 20,
+  },
+});
+
+screen.render();
+
+upload.setData({
+  label: 'Uploaded',
+  value: 75,
+  width: 20,
+});
+
+screen.render();
+
+upload.destroy();
+```
+
+The adapter owns only its `BoxElement`. It updates content through `setData`
+and detaches the element through `destroy`. Rendering remains the caller's
+responsibility, allowing multiple updates to be batched.
+
+## Renderer API
+
+### `renderProgressBar(options)`
+
+Returns a plain string.
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `value` | `number` | Required | Current numeric value. |
+| `width` | `number` | Required | Positive integer track width in characters. |
+| `min` | `number` | `0` | Lower bound. |
+| `max` | `number` | `100` | Upper bound. |
+| `label` | `string` | — | Text rendered before the track. |
+| `characters` | `{ filled: string; empty: string }` | `█`, `░` | Single-cell track characters. |
+| `formatValue` | `(context) => string` | Percentage | Formats trailing value text. |
+
+`value` is clamped to `[min, max]`. `max` must be greater than `min`.
+
+`formatValue` receives:
+
+```ts
+interface ProgressBarValueContext {
+  percentage: number;
+  value: number;
+}
+```
+
+`value` in this context is the clamped value.
+
+## Adapter API
+
+### `progressBar(options)`
+
+| Option | Type | Description |
+| --- | --- | --- |
+| `parent` | `blessed.Widgets.Node` | Parent Blessed node. |
+| `data` | `RenderProgressBarOptions` | Renderer data. |
+| `box` | `ProgressBarBoxOptions` | Blessed box options except `parent`, `content`, and `tags`. |
+
+Returns:
+
+```ts
+interface ProgressBarHandle {
+  readonly element: blessed.Widgets.BoxElement;
+  setData(data: RenderProgressBarOptions): void;
+  destroy(): void;
+}
+```
+
+## Accessibility and terminal compatibility
+
+- Do not communicate state through color alone; percentage text is enabled by
+  default.
+- Use ASCII characters when Unicode block glyphs are unavailable.
+- Keep labels concise for narrow terminals.
+- The component is display-only and does not receive focus or keyboard input.
+- Call `screen.render()` after updates when visible output should be flushed.
+
+## Tree shaking
+
+Prefer the narrowest import:
+
+```ts
+import { renderProgressBar } from 'blessed-components/progress-bar';
+```
+
+The pure entry contains no Blessed import. Import the adapter only when needed:
+
+```ts
+import { progressBar } from 'blessed-components/progress-bar/blessed';
+```

package/src/components/sparkline/README.md

@@ -0,0 +1,171 @@
+# Sparkline
+
+Render compact numeric trends with Unicode or custom terminal glyphs.
+
+## Features
+
+- Pure renderer with no Blessed import.
+- Blessed adapter with `setData()` and `destroy()`.
+- Automatic or explicit numeric domains.
+- Peak-preserving downsampling for narrow terminals.
+- Stable rendering for constant series.
+- Empty-state text.
+- Optional label, primary value, and summary.
+- Custom glyph scales for Unicode or ASCII terminals.
+- Dedicated tree-shakable subpath exports.
+
+## Installation
+
+```sh
+npm install blessed blessed-components
+```
+
+## Pure renderer
+
+```ts
+import { renderSparkline } from 'blessed-components/sparkline';
+
+renderSparkline({
+  values: [1, 2, 3, 4, 5, 6, 7, 8],
+  width: 8,
+});
+
+// ▁▂▃▄▅▆▇█
+```
+
+### Metadata
+
+```ts
+renderSparkline({
+  label: 'Weekly downloads',
+  value: '25.2M',
+  values: [1, 3, 2, 5, 8, 6],
+  width: 6,
+  summary: 'peak: 8M',
+});
+
+// Weekly downloads 25.2M
+// ▁▃▂▅█▆ peak: 8M
+```
+
+### Explicit domain
+
+```ts
+renderSparkline({
+  min: 0,
+  max: 100,
+  values: [0, 50, 100],
+  width: 3,
+});
+
+// ▁▄█
+```
+
+### ASCII mode
+
+```ts
+renderSparkline({
+  characters: ['.', ':', '*', '#'],
+  values: [0, 30, 60, 100],
+  width: 4,
+});
+```
+
+## Downsampling
+
+`width` is the maximum number of samples rendered. When the source series is
+wider, values are divided into ordered buckets and the maximum value from each
+bucket is retained. This preserves short peaks that uniform point sampling can
+hide.
+
+Series shorter than `width` are not padded or interpolated.
+
+## Empty and constant series
+
+Empty arrays render `No data` by default:
+
+```ts
+renderSparkline({ values: [], width: 10 });
+```
+
+Override with `emptyText`. Constant series use the middle glyph instead of
+dividing by zero:
+
+```ts
+renderSparkline({ values: [4, 4, 4], width: 3 });
+// ▄▄▄
+```
+
+## Blessed adapter
+
+```ts
+import blessed from 'blessed';
+import { sparkline } from 'blessed-components/sparkline/blessed';
+
+const screen = blessed.screen({ smartCSR: true });
+const downloads = sparkline({
+  parent: screen,
+  box: {
+    top: 0,
+    left: 0,
+    width: 40,
+    height: 2,
+  },
+  data: {
+    label: 'Downloads',
+    values: [1, 3, 2, 5, 8, 6],
+    width: 20,
+  },
+});
+
+screen.render();
+
+downloads.setData({
+  label: 'Downloads',
+  values: [2, 4, 6, 8],
+  width: 20,
+});
+screen.render();
+
+downloads.destroy();
+```
+
+The adapter never calls `screen.render()`. This lets applications batch
+multiple component updates.
+
+## Renderer API
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `values` | `readonly number[]` | Required | Ordered finite numeric samples. |
+| `width` | `number` | Required | Positive integer maximum sample count. |
+| `min` | `number` | Series minimum | Lower domain bound. |
+| `max` | `number` | Series maximum | Upper domain bound. |
+| `characters` | `readonly string[]` | `▁▂▃▄▅▆▇█` | Ordered low-to-high glyph scale. |
+| `emptyText` | `string` | `No data` | Output for an empty series. |
+| `label` | `string` | — | Heading label. |
+| `value` | `string \| number` | — | Primary heading value. |
+| `summary` | `string` | — | Text appended after the graph. |
+
+## Terminal compatibility
+
+- Glyphs should occupy one terminal cell.
+- Use custom ASCII glyphs when Unicode support is unavailable.
+- Text remains literal because the Blessed adapter disables tags.
+- The component is display-only and never receives focus.
+- Do not communicate meaning through glyph height or color alone; include
+  labels, values, or summaries when context matters.
+
+## Tree shaking
+
+Use the pure entry when no Blessed element is needed:
+
+```ts
+import { renderSparkline } from 'blessed-components/sparkline';
+```
+
+Import the adapter separately:
+
+```ts
+import { sparkline } from 'blessed-components/sparkline/blessed';
+```