blessed-components 1.0.0 → 1.1.0

package/README.md

@@ -3,8 +3,8 @@
 Composable, typed terminal UI components for
 [Blessed](https://github.com/chjj/blessed).
 
-> **Project status:** early development. `ProgressBar` is available; more
-> components are coming soon.
+> **Project status:** early development. `ProgressBar` and `Sparkline` are
+> available; more components are coming soon.
 
 ## Goals
 
@@ -30,7 +30,7 @@ npm install blessed blessed-components
 | Component     | Purpose                                              | Priority |
 | ------------- | ---------------------------------------------------- | -------- |
 | [`ProgressBar`](./src/components/progress-bar/README.md) | Render one bounded horizontal progress bar. | Available |
-| `Sparkline`   | Render compact time-series data with Unicode blocks. | P0       |
+| [`Sparkline`](./src/components/sparkline/README.md) | Render compact time-series data with Unicode blocks. | Available |
 | `MetricBars`  | Render labeled metrics as aligned progress bars.     | P0       |
 | `Stat`        | Display a label and highlighted value.               | P0       |
 
@@ -115,6 +115,7 @@ npm run test:watch
 npm run lint
 npm run lint:fix
 npm run biome:check
+npm run preview
 npm run typecheck
 npm run format
 npm run format:check
@@ -123,6 +124,18 @@ npm run format:check
 ESLint and Biome extend the shared `super-configs` presets. Biome owns
 formatting and import organization; Prettier is not used.
 
+### Terminal component preview
+
+Run the prototype component workbench:
+
+```sh
+npm run preview
+```
+
+Use arrow keys and Enter to select stories, `r` to reload, `Tab` to move
+focus, and `q` to quit. The prototype currently previews ProgressBar and
+Sparkline stories through their public Blessed adapters.
+
 ## Testing
 
 Development follows vertical TDD slices:

package/dist/index.cjs

@@ -55,7 +55,82 @@ function progressBar({ box, data, parent }) {
   };
 }
 
+// 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 sparkline2 = 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 ? sparkline2 : `${sparkline2} ${summary}`;
+  return heading.length === 0 ? chartLine : `${heading}
+${chartLine}`;
+}
+
+// src/adapters/blessed/sparkline.ts
+function sparkline({ box, data, parent }) {
+  const element = blessed__default.default.box({
+    ...box,
+    content: renderSparkline(data),
+    parent,
+    tags: false
+  });
+  return {
+    element,
+    destroy() {
+      element.destroy();
+    },
+    setData(nextData) {
+      element.setContent(renderSparkline(nextData));
+    }
+  };
+}
+
 exports.progressBar = progressBar;
 exports.renderProgressBar = renderProgressBar;
+exports.renderSparkline = renderSparkline;
+exports.sparkline = sparkline;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/components/progress-bar/index.ts","../src/adapters/blessed/progress-bar.ts"],"names":["blessed"],"mappings":";;;;;;;;;;;AA6LO,SAAS,iBAAA,CAAkB;AAAA,EAChC,UAAA,GAAa,EAAE,KAAA,EAAO,QAAA,EAAK,QAAQ,QAAA,EAAI;AAAA,EACvC,cAAc,CAAC,EAAE,UAAA,EAAW,KAAM,GAAG,UAAU,CAAA,CAAA,CAAA;AAAA,EAC/C,KAAA;AAAA,EACA,GAAA,GAAM,GAAA;AAAA,EACN,GAAA,GAAM,CAAA;AAAA,EACN,KAAA;AAAA,EACA;AACF,CAAA,EAAqC;AACnC,EAAA,IAAI,CAAC,MAAA,CAAO,SAAA,CAAU,KAAK,CAAA,IAAK,QAAQ,CAAA,EAAG;AACzC,IAAA,MAAM,IAAI,WAAW,+CAA+C,CAAA;AAAA,EACtE;AAEA,EAAA,IAAI,CAAC,MAAA,CAAO,QAAA,CAAS,GAAG,CAAA,IAAK,CAAC,MAAA,CAAO,QAAA,CAAS,GAAG,CAAA,IAAK,GAAA,IAAO,GAAA,EAAK;AAChE,IAAA,MAAM,IAAI,WAAW,2CAA2C,CAAA;AAAA,EAClE;AAEA,EAAA,IAAI,CAAC,MAAA,CAAO,QAAA,CAAS,KAAK,CAAA,EAAG;AAC3B,IAAA,MAAM,IAAI,WAAW,mCAAmC,CAAA;AAAA,EAC1D;AAEA,EAAA,MAAM,YAAA,GAAe,KAAK,GAAA,CAAI,GAAA,EAAK,KAAK,GAAA,CAAI,GAAA,EAAK,KAAK,CAAC,CAAA;AACvD,EAAA,MAAM,aAAa,IAAA,CAAK,KAAA,CAAA,CAAQ,eAAe,GAAA,KAAQ,GAAA,GAAM,OAAQ,GAAG,CAAA;AACxE,EAAA,MAAM,WAAA,GAAc,IAAA,CAAK,KAAA,CAAO,UAAA,GAAa,MAAO,KAAK,CAAA;AACzD,EAAA,MAAM,KAAA,GACJ,UAAA,CAAW,MAAA,CAAO,MAAA,CAAO,WAAW,IAAI,UAAA,CAAW,KAAA,CAAM,MAAA,CAAO,KAAA,GAAQ,WAAW,CAAA;AACrF,EAAA,MAAM,MAAA,GAAS,KAAA,KAAU,MAAA,GAAY,EAAA,GAAK,GAAG,KAAK,CAAA,CAAA,CAAA;AAClD,EAAA,MAAM,YAAY,WAAA,CAAY,EAAE,UAAA,EAAY,KAAA,EAAO,cAAc,CAAA;AAEjE,EAAA,OAAO,CAAA,EAAG,MAAM,CAAA,EAAG,KAAK,IAAI,SAAS,CAAA,CAAA;AACvC;;;AClFO,SAAS,WAAA,CAAY,EAAE,GAAA,EAAK,IAAA,EAAM,QAAO,EAA0C;AACxF,EAAA,MAAM,OAAA,GAAUA,yBAAQ,GAAA,CAAI;AAAA,IAC1B,GAAG,GAAA;AAAA,IACH,OAAA,EAAS,kBAAkB,IAAI,CAAA;AAAA,IAC/B,MAAA;AAAA,IACA,IAAA,EAAM;AAAA,GACP,CAAA;AAED,EAAA,OAAO;AAAA,IACL,OAAA;AAAA,IACA,OAAA,GAAU;AACR,MAAA,OAAA,CAAQ,OAAA,EAAQ;AAAA,IAClB,CAAA;AAAA,IACA,QAAQ,QAAA,EAAU;AAChB,MAAA,OAAA,CAAQ,UAAA,CAAW,iBAAA,CAAkB,QAAQ,CAAC,CAAA;AAAA,IAChD;AAAA,GACF;AACF","file":"index.cjs","sourcesContent":["/**\n * Options accepted by {@link renderProgressBar}.\n *\n * The renderer maps `value` from the inclusive numeric range defined by\n * `min` and `max` into a fixed-width terminal track. Values outside the range\n * are clamped before rendering.\n *\n * @example Basic percentage bar\n *\n * ```ts\n * renderProgressBar({\n *   value: 50,\n *   width: 10,\n * });\n * // \"█████░░░░░ 50%\"\n * ```\n *\n * @example Custom range and label\n *\n * ```ts\n * renderProgressBar({\n *   label: 'Workers',\n *   min: 0,\n *   max: 8,\n *   value: 6,\n *   width: 8,\n * });\n * // \"Workers ██████░░ 75%\"\n * ```\n */\nexport interface RenderProgressBarOptions {\n  /**\n   * Characters used to render filled and empty cells.\n   *\n   * Each character should occupy one terminal cell. Multi-cell or combining\n   * characters can make the visible track wider than `width`.\n   *\n   * @defaultValue `{ filled: '█', empty: '░' }`\n   */\n  characters?: ProgressBarCharacters;\n\n  /**\n   * Formats the value text appended after the track.\n   *\n   * The callback receives the clamped numeric value and its rounded\n   * percentage. Returning an empty string leaves the trailing separator in\n   * place; callers that need a track-only representation should account for\n   * that when composing output.\n   *\n   * @defaultValue `({ percentage }) => `${percentage}%``\n   */\n  formatValue?: (context: ProgressBarValueContext) => string;\n\n  /**\n   * Optional text rendered before the track.\n   *\n   * Dynamic values must be escaped by the caller if the returned string will\n   * later be inserted into a Blessed element with tags enabled. The bundled\n   * Blessed adapter disables tags.\n   */\n  label?: string;\n\n  /**\n   * Upper bound of the numeric range.\n   *\n   * Must be finite and greater than `min`.\n   *\n   * @defaultValue `100`\n   */\n  max?: number;\n\n  /**\n   * Lower bound of the numeric range.\n   *\n   * Must be finite and lower than `max`.\n   *\n   * @defaultValue `0`\n   */\n  min?: number;\n\n  /**\n   * Current numeric value.\n   *\n   * The value must be finite. Values below `min` or above `max` are clamped\n   * before the percentage and formatted value are calculated.\n   */\n  value: number;\n\n  /**\n   * Number of characters reserved for the progress track.\n   *\n   * This excludes the optional label, spaces, and formatted value. It must be\n   * a positive integer.\n   */\n  width: number;\n}\n\n/**\n * Character pair used to draw a progress track.\n *\n * Use ASCII characters when the target terminal cannot display Unicode block\n * glyphs reliably.\n *\n * @example\n *\n * ```ts\n * const asciiCharacters: ProgressBarCharacters = {\n *   filled: '#',\n *   empty: '-',\n * };\n * ```\n */\nexport interface ProgressBarCharacters {\n  /** Character repeated for unfilled track cells. */\n  empty: string;\n\n  /** Character repeated for filled track cells. */\n  filled: string;\n}\n\n/**\n * Normalized value information passed to a progress value formatter.\n */\nexport interface ProgressBarValueContext {\n  /**\n   * Rounded progress in the inclusive range from `0` to `100`.\n   */\n  percentage: number;\n\n  /**\n   * Numeric value after it has been clamped to the configured range.\n   */\n  value: number;\n}\n\n/**\n * Renders a deterministic, single-line progress bar.\n *\n * This function is framework-independent and does not import Blessed. Import\n * it from `blessed-components/progress-bar` when only string rendering is\n * needed; that subpath keeps the Blessed adapter out of the module graph.\n *\n * The result has this structure:\n *\n * ```text\n * [label + space][fixed-width track][space][formatted value]\n * ```\n *\n * @param options - Numeric range, track width, characters, and text formatting.\n * @returns A plain terminal string. No ANSI sequences or Blessed tags are added.\n *\n * @throws `RangeError`\n * Thrown when `width` is not a positive integer.\n *\n * @throws `RangeError`\n * Thrown when `min` or `max` is not finite, or when `max` is not greater than\n * `min`.\n *\n * @throws `RangeError`\n * Thrown when `value` is not finite.\n *\n * @example Unicode output\n *\n * ```ts\n * import { renderProgressBar } from 'blessed-components/progress-bar';\n *\n * const output = renderProgressBar({\n *   label: 'Quality',\n *   value: 78,\n *   width: 16,\n * });\n *\n * // \"Quality ████████████░░░░ 78%\"\n * ```\n *\n * @example ASCII output with a custom value\n *\n * ```ts\n * const output = renderProgressBar({\n *   characters: { filled: '#', empty: '-' },\n *   formatValue: ({ value }) => `${value} files`,\n *   label: 'Uploaded',\n *   value: 25,\n *   width: 8,\n * });\n *\n * // \"Uploaded ##------ 25 files\"\n * ```\n */\nexport function renderProgressBar({\n  characters = { empty: '░', filled: '█' },\n  formatValue = ({ percentage }) => `${percentage}%`,\n  label,\n  max = 100,\n  min = 0,\n  value,\n  width,\n}: RenderProgressBarOptions): string {\n  if (!Number.isInteger(width) || width < 1) {\n    throw new RangeError('ProgressBar width must be a positive integer.');\n  }\n\n  if (!Number.isFinite(min) || !Number.isFinite(max) || max <= min) {\n    throw new RangeError('ProgressBar max must be greater than min.');\n  }\n\n  if (!Number.isFinite(value)) {\n    throw new RangeError('ProgressBar value must be finite.');\n  }\n\n  const clampedValue = Math.min(max, Math.max(min, value));\n  const percentage = Math.round(((clampedValue - min) / (max - min)) * 100);\n  const filledWidth = Math.round((percentage / 100) * width);\n  const track =\n    characters.filled.repeat(filledWidth) + characters.empty.repeat(width - filledWidth);\n  const prefix = label === undefined ? '' : `${label} `;\n  const valueText = formatValue({ percentage, value: clampedValue });\n\n  return `${prefix}${track} ${valueText}`;\n}\n","import blessed from 'blessed';\n\nimport {\n  type RenderProgressBarOptions,\n  renderProgressBar,\n} from '../../components/progress-bar/index.js';\n\n/**\n * Blessed box options supported by the ProgressBar adapter.\n *\n * `parent`, `content`, and `tags` are managed by {@link progressBar}:\n *\n * - `parent` comes from {@link ProgressBarOptions.parent}.\n * - `content` comes from {@link renderProgressBar}.\n * - `tags` is always disabled so labels and formatter output remain literal.\n */\nexport type ProgressBarBoxOptions = Omit<blessed.Widgets.BoxOptions, 'content' | 'parent' | 'tags'>;\n\n/**\n * Options accepted by the Blessed {@link progressBar} adapter.\n */\nexport interface ProgressBarOptions {\n  /**\n   * Optional Blessed box configuration.\n   *\n   * Position, dimensions, style, visibility, and other regular box options\n   * can be supplied here.\n   */\n  box?: ProgressBarBoxOptions;\n\n  /**\n   * Data passed to the pure {@link renderProgressBar} renderer.\n   */\n  data: RenderProgressBarOptions;\n\n  /**\n   * Blessed node that receives the created box as a child.\n   *\n   * Usually this is a `Screen` or another `BoxElement`.\n   */\n  parent: blessed.Widgets.Node;\n}\n\n/**\n * Imperative handle returned by {@link progressBar}.\n *\n * The handle owns one Blessed `BoxElement`. It does not own the parent screen\n * and never calls `screen.render()`, allowing callers to batch several updates\n * into one terminal render.\n */\nexport interface ProgressBarHandle {\n  /**\n   * Underlying Blessed box.\n   *\n   * Use this for standard Blessed operations such as positioning, showing,\n   * hiding, or applying styles.\n   */\n  readonly element: blessed.Widgets.BoxElement;\n\n  /**\n   * Destroys and detaches the owned box from its parent.\n   *\n   * This does not destroy the parent or screen. Do not use the handle after\n   * calling this method.\n   */\n  destroy(): void;\n\n  /**\n   * Re-renders component content using new data.\n   *\n   * The underlying element is preserved. This method does not call\n   * `screen.render()`; call it explicitly when updates should become visible.\n   *\n   * @param data - Complete renderer data replacing the previous data.\n   *\n   * @throws `RangeError`\n   * Propagates validation errors from {@link renderProgressBar}.\n   */\n  setData(data: RenderProgressBarOptions): void;\n}\n\n/**\n * Creates a display-only ProgressBar backed by a Blessed `BoxElement`.\n *\n * Import this adapter from `blessed-components/progress-bar/blessed`. Use\n * {@link renderProgressBar} from `blessed-components/progress-bar` when a\n * Blessed element is unnecessary.\n *\n * The adapter:\n *\n * - renders initial content through {@link renderProgressBar};\n * - disables Blessed tags to keep dynamic text literal;\n * - updates the existing element through {@link ProgressBarHandle.setData};\n * - leaves screen rendering under caller control;\n * - detaches its element through {@link ProgressBarHandle.destroy}.\n *\n * @param options - Parent node, renderer data, and optional box settings.\n * @returns A handle for the created element, updates, and cleanup.\n *\n * @throws `RangeError`\n * Propagates validation errors from {@link renderProgressBar}.\n *\n * @example\n *\n * ```ts\n * import blessed from 'blessed';\n * import { progressBar } from 'blessed-components/progress-bar/blessed';\n *\n * const screen = blessed.screen({ smartCSR: true });\n * const upload = progressBar({\n *   parent: screen,\n *   box: {\n *     top: 0,\n *     left: 0,\n *     width: 40,\n *     height: 1,\n *   },\n *   data: {\n *     label: 'Uploaded',\n *     value: 25,\n *     width: 20,\n *   },\n * });\n *\n * screen.render();\n *\n * upload.setData({\n *   label: 'Uploaded',\n *   value: 75,\n *   width: 20,\n * });\n * screen.render();\n *\n * upload.destroy();\n * screen.destroy();\n * ```\n */\nexport function progressBar({ box, data, parent }: ProgressBarOptions): ProgressBarHandle {\n  const element = blessed.box({\n    ...box,\n    content: renderProgressBar(data),\n    parent,\n    tags: false,\n  });\n\n  return {\n    element,\n    destroy() {\n      element.destroy();\n    },\n    setData(nextData) {\n      element.setContent(renderProgressBar(nextData));\n    },\n  };\n}\n"]}
+{"version":3,"sources":["../src/components/progress-bar/index.ts","../src/adapters/blessed/progress-bar.ts","../src/components/sparkline/index.ts","../src/adapters/blessed/sparkline.ts"],"names":["blessed","sparkline"],"mappings":"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","file":"index.cjs","sourcesContent":["/**\n * Options accepted by {@link renderProgressBar}.\n *\n * The renderer maps `value` from the inclusive numeric range defined by\n * `min` and `max` into a fixed-width terminal track. Values outside the range\n * are clamped before rendering.\n *\n * @example Basic percentage bar\n *\n * ```ts\n * renderProgressBar({\n *   value: 50,\n *   width: 10,\n * });\n * // \"█████░░░░░ 50%\"\n * ```\n *\n * @example Custom range and label\n *\n * ```ts\n * renderProgressBar({\n *   label: 'Workers',\n *   min: 0,\n *   max: 8,\n *   value: 6,\n *   width: 8,\n * });\n * // \"Workers ██████░░ 75%\"\n * ```\n */\nexport interface RenderProgressBarOptions {\n  /**\n   * Characters used to render filled and empty cells.\n   *\n   * Each character should occupy one terminal cell. Multi-cell or combining\n   * characters can make the visible track wider than `width`.\n   *\n   * @defaultValue `{ filled: '█', empty: '░' }`\n   */\n  characters?: ProgressBarCharacters;\n\n  /**\n   * Formats the value text appended after the track.\n   *\n   * The callback receives the clamped numeric value and its rounded\n   * percentage. Returning an empty string leaves the trailing separator in\n   * place; callers that need a track-only representation should account for\n   * that when composing output.\n   *\n   * @defaultValue `({ percentage }) => `${percentage}%``\n   */\n  formatValue?: (context: ProgressBarValueContext) => string;\n\n  /**\n   * Optional text rendered before the track.\n   *\n   * Dynamic values must be escaped by the caller if the returned string will\n   * later be inserted into a Blessed element with tags enabled. The bundled\n   * Blessed adapter disables tags.\n   */\n  label?: string;\n\n  /**\n   * Upper bound of the numeric range.\n   *\n   * Must be finite and greater than `min`.\n   *\n   * @defaultValue `100`\n   */\n  max?: number;\n\n  /**\n   * Lower bound of the numeric range.\n   *\n   * Must be finite and lower than `max`.\n   *\n   * @defaultValue `0`\n   */\n  min?: number;\n\n  /**\n   * Current numeric value.\n   *\n   * The value must be finite. Values below `min` or above `max` are clamped\n   * before the percentage and formatted value are calculated.\n   */\n  value: number;\n\n  /**\n   * Number of characters reserved for the progress track.\n   *\n   * This excludes the optional label, spaces, and formatted value. It must be\n   * a positive integer.\n   */\n  width: number;\n}\n\n/**\n * Character pair used to draw a progress track.\n *\n * Use ASCII characters when the target terminal cannot display Unicode block\n * glyphs reliably.\n *\n * @example\n *\n * ```ts\n * const asciiCharacters: ProgressBarCharacters = {\n *   filled: '#',\n *   empty: '-',\n * };\n * ```\n */\nexport interface ProgressBarCharacters {\n  /** Character repeated for unfilled track cells. */\n  empty: string;\n\n  /** Character repeated for filled track cells. */\n  filled: string;\n}\n\n/**\n * Normalized value information passed to a progress value formatter.\n */\nexport interface ProgressBarValueContext {\n  /**\n   * Rounded progress in the inclusive range from `0` to `100`.\n   */\n  percentage: number;\n\n  /**\n   * Numeric value after it has been clamped to the configured range.\n   */\n  value: number;\n}\n\n/**\n * Renders a deterministic, single-line progress bar.\n *\n * This function is framework-independent and does not import Blessed. Import\n * it from `blessed-components/progress-bar` when only string rendering is\n * needed; that subpath keeps the Blessed adapter out of the module graph.\n *\n * The result has this structure:\n *\n * ```text\n * [label + space][fixed-width track][space][formatted value]\n * ```\n *\n * @param options - Numeric range, track width, characters, and text formatting.\n * @returns A plain terminal string. No ANSI sequences or Blessed tags are added.\n *\n * @throws `RangeError`\n * Thrown when `width` is not a positive integer.\n *\n * @throws `RangeError`\n * Thrown when `min` or `max` is not finite, or when `max` is not greater than\n * `min`.\n *\n * @throws `RangeError`\n * Thrown when `value` is not finite.\n *\n * @example Unicode output\n *\n * ```ts\n * import { renderProgressBar } from 'blessed-components/progress-bar';\n *\n * const output = renderProgressBar({\n *   label: 'Quality',\n *   value: 78,\n *   width: 16,\n * });\n *\n * // \"Quality ████████████░░░░ 78%\"\n * ```\n *\n * @example ASCII output with a custom value\n *\n * ```ts\n * const output = renderProgressBar({\n *   characters: { filled: '#', empty: '-' },\n *   formatValue: ({ value }) => `${value} files`,\n *   label: 'Uploaded',\n *   value: 25,\n *   width: 8,\n * });\n *\n * // \"Uploaded ##------ 25 files\"\n * ```\n */\nexport function renderProgressBar({\n  characters = { empty: '░', filled: '█' },\n  formatValue = ({ percentage }) => `${percentage}%`,\n  label,\n  max = 100,\n  min = 0,\n  value,\n  width,\n}: RenderProgressBarOptions): string {\n  if (!Number.isInteger(width) || width < 1) {\n    throw new RangeError('ProgressBar width must be a positive integer.');\n  }\n\n  if (!Number.isFinite(min) || !Number.isFinite(max) || max <= min) {\n    throw new RangeError('ProgressBar max must be greater than min.');\n  }\n\n  if (!Number.isFinite(value)) {\n    throw new RangeError('ProgressBar value must be finite.');\n  }\n\n  const clampedValue = Math.min(max, Math.max(min, value));\n  const percentage = Math.round(((clampedValue - min) / (max - min)) * 100);\n  const filledWidth = Math.round((percentage / 100) * width);\n  const track =\n    characters.filled.repeat(filledWidth) + characters.empty.repeat(width - filledWidth);\n  const prefix = label === undefined ? '' : `${label} `;\n  const valueText = formatValue({ percentage, value: clampedValue });\n\n  return `${prefix}${track} ${valueText}`;\n}\n","import blessed from 'blessed';\n\nimport {\n  type RenderProgressBarOptions,\n  renderProgressBar,\n} from '../../components/progress-bar/index.js';\n\n/**\n * Blessed box options supported by the ProgressBar adapter.\n *\n * `parent`, `content`, and `tags` are managed by {@link progressBar}:\n *\n * - `parent` comes from {@link ProgressBarOptions.parent}.\n * - `content` comes from {@link renderProgressBar}.\n * - `tags` is always disabled so labels and formatter output remain literal.\n */\nexport type ProgressBarBoxOptions = Omit<blessed.Widgets.BoxOptions, 'content' | 'parent' | 'tags'>;\n\n/**\n * Options accepted by the Blessed {@link progressBar} adapter.\n */\nexport interface ProgressBarOptions {\n  /**\n   * Optional Blessed box configuration.\n   *\n   * Position, dimensions, style, visibility, and other regular box options\n   * can be supplied here.\n   */\n  box?: ProgressBarBoxOptions;\n\n  /**\n   * Data passed to the pure {@link renderProgressBar} renderer.\n   */\n  data: RenderProgressBarOptions;\n\n  /**\n   * Blessed node that receives the created box as a child.\n   *\n   * Usually this is a `Screen` or another `BoxElement`.\n   */\n  parent: blessed.Widgets.Node;\n}\n\n/**\n * Imperative handle returned by {@link progressBar}.\n *\n * The handle owns one Blessed `BoxElement`. It does not own the parent screen\n * and never calls `screen.render()`, allowing callers to batch several updates\n * into one terminal render.\n */\nexport interface ProgressBarHandle {\n  /**\n   * Underlying Blessed box.\n   *\n   * Use this for standard Blessed operations such as positioning, showing,\n   * hiding, or applying styles.\n   */\n  readonly element: blessed.Widgets.BoxElement;\n\n  /**\n   * Destroys and detaches the owned box from its parent.\n   *\n   * This does not destroy the parent or screen. Do not use the handle after\n   * calling this method.\n   */\n  destroy(): void;\n\n  /**\n   * Re-renders component content using new data.\n   *\n   * The underlying element is preserved. This method does not call\n   * `screen.render()`; call it explicitly when updates should become visible.\n   *\n   * @param data - Complete renderer data replacing the previous data.\n   *\n   * @throws `RangeError`\n   * Propagates validation errors from {@link renderProgressBar}.\n   */\n  setData(data: RenderProgressBarOptions): void;\n}\n\n/**\n * Creates a display-only ProgressBar backed by a Blessed `BoxElement`.\n *\n * Import this adapter from `blessed-components/progress-bar/blessed`. Use\n * {@link renderProgressBar} from `blessed-components/progress-bar` when a\n * Blessed element is unnecessary.\n *\n * The adapter:\n *\n * - renders initial content through {@link renderProgressBar};\n * - disables Blessed tags to keep dynamic text literal;\n * - updates the existing element through {@link ProgressBarHandle.setData};\n * - leaves screen rendering under caller control;\n * - detaches its element through {@link ProgressBarHandle.destroy}.\n *\n * @param options - Parent node, renderer data, and optional box settings.\n * @returns A handle for the created element, updates, and cleanup.\n *\n * @throws `RangeError`\n * Propagates validation errors from {@link renderProgressBar}.\n *\n * @example\n *\n * ```ts\n * import blessed from 'blessed';\n * import { progressBar } from 'blessed-components/progress-bar/blessed';\n *\n * const screen = blessed.screen({ smartCSR: true });\n * const upload = progressBar({\n *   parent: screen,\n *   box: {\n *     top: 0,\n *     left: 0,\n *     width: 40,\n *     height: 1,\n *   },\n *   data: {\n *     label: 'Uploaded',\n *     value: 25,\n *     width: 20,\n *   },\n * });\n *\n * screen.render();\n *\n * upload.setData({\n *   label: 'Uploaded',\n *   value: 75,\n *   width: 20,\n * });\n * screen.render();\n *\n * upload.destroy();\n * screen.destroy();\n * ```\n */\nexport function progressBar({ box, data, parent }: ProgressBarOptions): ProgressBarHandle {\n  const element = blessed.box({\n    ...box,\n    content: renderProgressBar(data),\n    parent,\n    tags: false,\n  });\n\n  return {\n    element,\n    destroy() {\n      element.destroy();\n    },\n    setData(nextData) {\n      element.setContent(renderProgressBar(nextData));\n    },\n  };\n}\n","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","import blessed from 'blessed';\n\nimport { type RenderSparklineOptions, renderSparkline } from '../../components/sparkline/index.js';\n\n/**\n * Blessed box options supported by the Sparkline adapter.\n *\n * `parent`, `content`, and `tags` are controlled by {@link sparkline}.\n */\nexport type SparklineBoxOptions = Omit<blessed.Widgets.BoxOptions, 'content' | 'parent' | 'tags'>;\n\n/** Options accepted by the Blessed {@link sparkline} adapter. */\nexport interface SparklineOptions {\n  /** Optional position, dimensions, style, and other Blessed box settings. */\n  box?: SparklineBoxOptions;\n\n  /** Data passed to the pure {@link renderSparkline} renderer. */\n  data: RenderSparklineOptions;\n\n  /** Blessed screen or node that receives the created box. */\n  parent: blessed.Widgets.Node;\n}\n\n/**\n * Imperative handle returned by {@link sparkline}.\n *\n * The handle owns one box, never owns the parent screen, and never calls\n * `screen.render()`.\n */\nexport interface SparklineHandle {\n  /** Underlying Blessed box used for standard element operations. */\n  readonly element: blessed.Widgets.BoxElement;\n\n  /**\n   * Destroys and detaches the owned box.\n   *\n   * The parent and screen remain alive.\n   */\n  destroy(): void;\n\n  /**\n   * Replaces renderer data while preserving the Blessed element.\n   *\n   * Call `screen.render()` after one or more updates to flush visible output.\n   *\n   * @param data - Complete renderer data replacing the previous data.\n   *\n   * @throws `RangeError`\n   * Propagates validation errors from {@link renderSparkline}.\n   */\n  setData(data: RenderSparklineOptions): void;\n}\n\n/**\n * Creates a display-only Sparkline backed by a Blessed `BoxElement`.\n *\n * Import from `blessed-components/sparkline/blessed`. The adapter disables\n * Blessed tags, renders through {@link renderSparkline}, and leaves terminal\n * rendering under caller control.\n *\n * @param options - Parent node, renderer data, and optional box settings.\n * @returns Handle for the created box, updates, and cleanup.\n *\n * @throws `RangeError`\n * Propagates validation errors from {@link renderSparkline}.\n *\n * @example\n *\n * ```ts\n * import blessed from 'blessed';\n * import { sparkline } from 'blessed-components/sparkline/blessed';\n *\n * const screen = blessed.screen({ smartCSR: true });\n * const downloads = sparkline({\n *   parent: screen,\n *   box: { top: 0, left: 0, width: 40, height: 2 },\n *   data: {\n *     label: 'Downloads',\n *     values: [1, 3, 2, 8],\n *     width: 20,\n *   },\n * });\n *\n * screen.render();\n * downloads.setData({\n *   label: 'Downloads',\n *   values: [2, 4, 6, 8],\n *   width: 20,\n * });\n * screen.render();\n *\n * downloads.destroy();\n * screen.destroy();\n * ```\n */\nexport function sparkline({ box, data, parent }: SparklineOptions): SparklineHandle {\n  const element = blessed.box({\n    ...box,\n    content: renderSparkline(data),\n    parent,\n    tags: false,\n  });\n\n  return {\n    element,\n    destroy() {\n      element.destroy();\n    },\n    setData(nextData) {\n      element.setContent(renderSparkline(nextData));\n    },\n  };\n}\n"]}

package/dist/index.d.cts

@@ -1,3 +1,5 @@
 export { ProgressBarBoxOptions, ProgressBarHandle, ProgressBarOptions, progressBar } from './progress-bar/blessed.cjs';
+export { SparklineBoxOptions, SparklineHandle, SparklineOptions, sparkline } from './sparkline/blessed.cjs';
 export { ProgressBarCharacters, ProgressBarValueContext, RenderProgressBarOptions, renderProgressBar } from './progress-bar/index.cjs';
+export { RenderSparklineOptions, renderSparkline } from './sparkline/index.cjs';
 import 'blessed';

package/dist/index.d.ts

@@ -1,3 +1,5 @@
 export { ProgressBarBoxOptions, ProgressBarHandle, ProgressBarOptions, progressBar } from './progress-bar/blessed.js';
+export { SparklineBoxOptions, SparklineHandle, SparklineOptions, sparkline } from './sparkline/blessed.js';
 export { ProgressBarCharacters, ProgressBarValueContext, RenderProgressBarOptions, renderProgressBar } from './progress-bar/index.js';
+export { RenderSparklineOptions, renderSparkline } from './sparkline/index.js';
 import 'blessed';

package/dist/index.js

@@ -49,6 +49,79 @@ function progressBar({ box, data, parent }) {
   };
 }
 
-export { progressBar, renderProgressBar };
+// 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 sparkline2 = 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 ? sparkline2 : `${sparkline2} ${summary}`;
+  return heading.length === 0 ? chartLine : `${heading}
+${chartLine}`;
+}
+
+// src/adapters/blessed/sparkline.ts
+function sparkline({ box, data, parent }) {
+  const element = blessed.box({
+    ...box,
+    content: renderSparkline(data),
+    parent,
+    tags: false
+  });
+  return {
+    element,
+    destroy() {
+      element.destroy();
+    },
+    setData(nextData) {
+      element.setContent(renderSparkline(nextData));
+    }
+  };
+}
+
+export { progressBar, renderProgressBar, renderSparkline, sparkline };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/components/progress-bar/index.ts","../src/adapters/blessed/progress-bar.ts"],"names":[],"mappings":";;;;;AA6LO,SAAS,iBAAA,CAAkB;AAAA,EAChC,UAAA,GAAa,EAAE,KAAA,EAAO,QAAA,EAAK,QAAQ,QAAA,EAAI;AAAA,EACvC,cAAc,CAAC,EAAE,UAAA,EAAW,KAAM,GAAG,UAAU,CAAA,CAAA,CAAA;AAAA,EAC/C,KAAA;AAAA,EACA,GAAA,GAAM,GAAA;AAAA,EACN,GAAA,GAAM,CAAA;AAAA,EACN,KAAA;AAAA,EACA;AACF,CAAA,EAAqC;AACnC,EAAA,IAAI,CAAC,MAAA,CAAO,SAAA,CAAU,KAAK,CAAA,IAAK,QAAQ,CAAA,EAAG;AACzC,IAAA,MAAM,IAAI,WAAW,+CAA+C,CAAA;AAAA,EACtE;AAEA,EAAA,IAAI,CAAC,MAAA,CAAO,QAAA,CAAS,GAAG,CAAA,IAAK,CAAC,MAAA,CAAO,QAAA,CAAS,GAAG,CAAA,IAAK,GAAA,IAAO,GAAA,EAAK;AAChE,IAAA,MAAM,IAAI,WAAW,2CAA2C,CAAA;AAAA,EAClE;AAEA,EAAA,IAAI,CAAC,MAAA,CAAO,QAAA,CAAS,KAAK,CAAA,EAAG;AAC3B,IAAA,MAAM,IAAI,WAAW,mCAAmC,CAAA;AAAA,EAC1D;AAEA,EAAA,MAAM,YAAA,GAAe,KAAK,GAAA,CAAI,GAAA,EAAK,KAAK,GAAA,CAAI,GAAA,EAAK,KAAK,CAAC,CAAA;AACvD,EAAA,MAAM,aAAa,IAAA,CAAK,KAAA,CAAA,CAAQ,eAAe,GAAA,KAAQ,GAAA,GAAM,OAAQ,GAAG,CAAA;AACxE,EAAA,MAAM,WAAA,GAAc,IAAA,CAAK,KAAA,CAAO,UAAA,GAAa,MAAO,KAAK,CAAA;AACzD,EAAA,MAAM,KAAA,GACJ,UAAA,CAAW,MAAA,CAAO,MAAA,CAAO,WAAW,IAAI,UAAA,CAAW,KAAA,CAAM,MAAA,CAAO,KAAA,GAAQ,WAAW,CAAA;AACrF,EAAA,MAAM,MAAA,GAAS,KAAA,KAAU,MAAA,GAAY,EAAA,GAAK,GAAG,KAAK,CAAA,CAAA,CAAA;AAClD,EAAA,MAAM,YAAY,WAAA,CAAY,EAAE,UAAA,EAAY,KAAA,EAAO,cAAc,CAAA;AAEjE,EAAA,OAAO,CAAA,EAAG,MAAM,CAAA,EAAG,KAAK,IAAI,SAAS,CAAA,CAAA;AACvC;;;AClFO,SAAS,WAAA,CAAY,EAAE,GAAA,EAAK,IAAA,EAAM,QAAO,EAA0C;AACxF,EAAA,MAAM,OAAA,GAAU,QAAQ,GAAA,CAAI;AAAA,IAC1B,GAAG,GAAA;AAAA,IACH,OAAA,EAAS,kBAAkB,IAAI,CAAA;AAAA,IAC/B,MAAA;AAAA,IACA,IAAA,EAAM;AAAA,GACP,CAAA;AAED,EAAA,OAAO;AAAA,IACL,OAAA;AAAA,IACA,OAAA,GAAU;AACR,MAAA,OAAA,CAAQ,OAAA,EAAQ;AAAA,IAClB,CAAA;AAAA,IACA,QAAQ,QAAA,EAAU;AAChB,MAAA,OAAA,CAAQ,UAAA,CAAW,iBAAA,CAAkB,QAAQ,CAAC,CAAA;AAAA,IAChD;AAAA,GACF;AACF","file":"index.js","sourcesContent":["/**\n * Options accepted by {@link renderProgressBar}.\n *\n * The renderer maps `value` from the inclusive numeric range defined by\n * `min` and `max` into a fixed-width terminal track. Values outside the range\n * are clamped before rendering.\n *\n * @example Basic percentage bar\n *\n * ```ts\n * renderProgressBar({\n *   value: 50,\n *   width: 10,\n * });\n * // \"█████░░░░░ 50%\"\n * ```\n *\n * @example Custom range and label\n *\n * ```ts\n * renderProgressBar({\n *   label: 'Workers',\n *   min: 0,\n *   max: 8,\n *   value: 6,\n *   width: 8,\n * });\n * // \"Workers ██████░░ 75%\"\n * ```\n */\nexport interface RenderProgressBarOptions {\n  /**\n   * Characters used to render filled and empty cells.\n   *\n   * Each character should occupy one terminal cell. Multi-cell or combining\n   * characters can make the visible track wider than `width`.\n   *\n   * @defaultValue `{ filled: '█', empty: '░' }`\n   */\n  characters?: ProgressBarCharacters;\n\n  /**\n   * Formats the value text appended after the track.\n   *\n   * The callback receives the clamped numeric value and its rounded\n   * percentage. Returning an empty string leaves the trailing separator in\n   * place; callers that need a track-only representation should account for\n   * that when composing output.\n   *\n   * @defaultValue `({ percentage }) => `${percentage}%``\n   */\n  formatValue?: (context: ProgressBarValueContext) => string;\n\n  /**\n   * Optional text rendered before the track.\n   *\n   * Dynamic values must be escaped by the caller if the returned string will\n   * later be inserted into a Blessed element with tags enabled. The bundled\n   * Blessed adapter disables tags.\n   */\n  label?: string;\n\n  /**\n   * Upper bound of the numeric range.\n   *\n   * Must be finite and greater than `min`.\n   *\n   * @defaultValue `100`\n   */\n  max?: number;\n\n  /**\n   * Lower bound of the numeric range.\n   *\n   * Must be finite and lower than `max`.\n   *\n   * @defaultValue `0`\n   */\n  min?: number;\n\n  /**\n   * Current numeric value.\n   *\n   * The value must be finite. Values below `min` or above `max` are clamped\n   * before the percentage and formatted value are calculated.\n   */\n  value: number;\n\n  /**\n   * Number of characters reserved for the progress track.\n   *\n   * This excludes the optional label, spaces, and formatted value. It must be\n   * a positive integer.\n   */\n  width: number;\n}\n\n/**\n * Character pair used to draw a progress track.\n *\n * Use ASCII characters when the target terminal cannot display Unicode block\n * glyphs reliably.\n *\n * @example\n *\n * ```ts\n * const asciiCharacters: ProgressBarCharacters = {\n *   filled: '#',\n *   empty: '-',\n * };\n * ```\n */\nexport interface ProgressBarCharacters {\n  /** Character repeated for unfilled track cells. */\n  empty: string;\n\n  /** Character repeated for filled track cells. */\n  filled: string;\n}\n\n/**\n * Normalized value information passed to a progress value formatter.\n */\nexport interface ProgressBarValueContext {\n  /**\n   * Rounded progress in the inclusive range from `0` to `100`.\n   */\n  percentage: number;\n\n  /**\n   * Numeric value after it has been clamped to the configured range.\n   */\n  value: number;\n}\n\n/**\n * Renders a deterministic, single-line progress bar.\n *\n * This function is framework-independent and does not import Blessed. Import\n * it from `blessed-components/progress-bar` when only string rendering is\n * needed; that subpath keeps the Blessed adapter out of the module graph.\n *\n * The result has this structure:\n *\n * ```text\n * [label + space][fixed-width track][space][formatted value]\n * ```\n *\n * @param options - Numeric range, track width, characters, and text formatting.\n * @returns A plain terminal string. No ANSI sequences or Blessed tags are added.\n *\n * @throws `RangeError`\n * Thrown when `width` is not a positive integer.\n *\n * @throws `RangeError`\n * Thrown when `min` or `max` is not finite, or when `max` is not greater than\n * `min`.\n *\n * @throws `RangeError`\n * Thrown when `value` is not finite.\n *\n * @example Unicode output\n *\n * ```ts\n * import { renderProgressBar } from 'blessed-components/progress-bar';\n *\n * const output = renderProgressBar({\n *   label: 'Quality',\n *   value: 78,\n *   width: 16,\n * });\n *\n * // \"Quality ████████████░░░░ 78%\"\n * ```\n *\n * @example ASCII output with a custom value\n *\n * ```ts\n * const output = renderProgressBar({\n *   characters: { filled: '#', empty: '-' },\n *   formatValue: ({ value }) => `${value} files`,\n *   label: 'Uploaded',\n *   value: 25,\n *   width: 8,\n * });\n *\n * // \"Uploaded ##------ 25 files\"\n * ```\n */\nexport function renderProgressBar({\n  characters = { empty: '░', filled: '█' },\n  formatValue = ({ percentage }) => `${percentage}%`,\n  label,\n  max = 100,\n  min = 0,\n  value,\n  width,\n}: RenderProgressBarOptions): string {\n  if (!Number.isInteger(width) || width < 1) {\n    throw new RangeError('ProgressBar width must be a positive integer.');\n  }\n\n  if (!Number.isFinite(min) || !Number.isFinite(max) || max <= min) {\n    throw new RangeError('ProgressBar max must be greater than min.');\n  }\n\n  if (!Number.isFinite(value)) {\n    throw new RangeError('ProgressBar value must be finite.');\n  }\n\n  const clampedValue = Math.min(max, Math.max(min, value));\n  const percentage = Math.round(((clampedValue - min) / (max - min)) * 100);\n  const filledWidth = Math.round((percentage / 100) * width);\n  const track =\n    characters.filled.repeat(filledWidth) + characters.empty.repeat(width - filledWidth);\n  const prefix = label === undefined ? '' : `${label} `;\n  const valueText = formatValue({ percentage, value: clampedValue });\n\n  return `${prefix}${track} ${valueText}`;\n}\n","import blessed from 'blessed';\n\nimport {\n  type RenderProgressBarOptions,\n  renderProgressBar,\n} from '../../components/progress-bar/index.js';\n\n/**\n * Blessed box options supported by the ProgressBar adapter.\n *\n * `parent`, `content`, and `tags` are managed by {@link progressBar}:\n *\n * - `parent` comes from {@link ProgressBarOptions.parent}.\n * - `content` comes from {@link renderProgressBar}.\n * - `tags` is always disabled so labels and formatter output remain literal.\n */\nexport type ProgressBarBoxOptions = Omit<blessed.Widgets.BoxOptions, 'content' | 'parent' | 'tags'>;\n\n/**\n * Options accepted by the Blessed {@link progressBar} adapter.\n */\nexport interface ProgressBarOptions {\n  /**\n   * Optional Blessed box configuration.\n   *\n   * Position, dimensions, style, visibility, and other regular box options\n   * can be supplied here.\n   */\n  box?: ProgressBarBoxOptions;\n\n  /**\n   * Data passed to the pure {@link renderProgressBar} renderer.\n   */\n  data: RenderProgressBarOptions;\n\n  /**\n   * Blessed node that receives the created box as a child.\n   *\n   * Usually this is a `Screen` or another `BoxElement`.\n   */\n  parent: blessed.Widgets.Node;\n}\n\n/**\n * Imperative handle returned by {@link progressBar}.\n *\n * The handle owns one Blessed `BoxElement`. It does not own the parent screen\n * and never calls `screen.render()`, allowing callers to batch several updates\n * into one terminal render.\n */\nexport interface ProgressBarHandle {\n  /**\n   * Underlying Blessed box.\n   *\n   * Use this for standard Blessed operations such as positioning, showing,\n   * hiding, or applying styles.\n   */\n  readonly element: blessed.Widgets.BoxElement;\n\n  /**\n   * Destroys and detaches the owned box from its parent.\n   *\n   * This does not destroy the parent or screen. Do not use the handle after\n   * calling this method.\n   */\n  destroy(): void;\n\n  /**\n   * Re-renders component content using new data.\n   *\n   * The underlying element is preserved. This method does not call\n   * `screen.render()`; call it explicitly when updates should become visible.\n   *\n   * @param data - Complete renderer data replacing the previous data.\n   *\n   * @throws `RangeError`\n   * Propagates validation errors from {@link renderProgressBar}.\n   */\n  setData(data: RenderProgressBarOptions): void;\n}\n\n/**\n * Creates a display-only ProgressBar backed by a Blessed `BoxElement`.\n *\n * Import this adapter from `blessed-components/progress-bar/blessed`. Use\n * {@link renderProgressBar} from `blessed-components/progress-bar` when a\n * Blessed element is unnecessary.\n *\n * The adapter:\n *\n * - renders initial content through {@link renderProgressBar};\n * - disables Blessed tags to keep dynamic text literal;\n * - updates the existing element through {@link ProgressBarHandle.setData};\n * - leaves screen rendering under caller control;\n * - detaches its element through {@link ProgressBarHandle.destroy}.\n *\n * @param options - Parent node, renderer data, and optional box settings.\n * @returns A handle for the created element, updates, and cleanup.\n *\n * @throws `RangeError`\n * Propagates validation errors from {@link renderProgressBar}.\n *\n * @example\n *\n * ```ts\n * import blessed from 'blessed';\n * import { progressBar } from 'blessed-components/progress-bar/blessed';\n *\n * const screen = blessed.screen({ smartCSR: true });\n * const upload = progressBar({\n *   parent: screen,\n *   box: {\n *     top: 0,\n *     left: 0,\n *     width: 40,\n *     height: 1,\n *   },\n *   data: {\n *     label: 'Uploaded',\n *     value: 25,\n *     width: 20,\n *   },\n * });\n *\n * screen.render();\n *\n * upload.setData({\n *   label: 'Uploaded',\n *   value: 75,\n *   width: 20,\n * });\n * screen.render();\n *\n * upload.destroy();\n * screen.destroy();\n * ```\n */\nexport function progressBar({ box, data, parent }: ProgressBarOptions): ProgressBarHandle {\n  const element = blessed.box({\n    ...box,\n    content: renderProgressBar(data),\n    parent,\n    tags: false,\n  });\n\n  return {\n    element,\n    destroy() {\n      element.destroy();\n    },\n    setData(nextData) {\n      element.setContent(renderProgressBar(nextData));\n    },\n  };\n}\n"]}
+{"version":3,"sources":["../src/components/progress-bar/index.ts","../src/adapters/blessed/progress-bar.ts","../src/components/sparkline/index.ts","../src/adapters/blessed/sparkline.ts"],"names":["sparkline","blessed"],"mappings":"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","file":"index.js","sourcesContent":["/**\n * Options accepted by {@link renderProgressBar}.\n *\n * The renderer maps `value` from the inclusive numeric range defined by\n * `min` and `max` into a fixed-width terminal track. Values outside the range\n * are clamped before rendering.\n *\n * @example Basic percentage bar\n *\n * ```ts\n * renderProgressBar({\n *   value: 50,\n *   width: 10,\n * });\n * // \"█████░░░░░ 50%\"\n * ```\n *\n * @example Custom range and label\n *\n * ```ts\n * renderProgressBar({\n *   label: 'Workers',\n *   min: 0,\n *   max: 8,\n *   value: 6,\n *   width: 8,\n * });\n * // \"Workers ██████░░ 75%\"\n * ```\n */\nexport interface RenderProgressBarOptions {\n  /**\n   * Characters used to render filled and empty cells.\n   *\n   * Each character should occupy one terminal cell. Multi-cell or combining\n   * characters can make the visible track wider than `width`.\n   *\n   * @defaultValue `{ filled: '█', empty: '░' }`\n   */\n  characters?: ProgressBarCharacters;\n\n  /**\n   * Formats the value text appended after the track.\n   *\n   * The callback receives the clamped numeric value and its rounded\n   * percentage. Returning an empty string leaves the trailing separator in\n   * place; callers that need a track-only representation should account for\n   * that when composing output.\n   *\n   * @defaultValue `({ percentage }) => `${percentage}%``\n   */\n  formatValue?: (context: ProgressBarValueContext) => string;\n\n  /**\n   * Optional text rendered before the track.\n   *\n   * Dynamic values must be escaped by the caller if the returned string will\n   * later be inserted into a Blessed element with tags enabled. The bundled\n   * Blessed adapter disables tags.\n   */\n  label?: string;\n\n  /**\n   * Upper bound of the numeric range.\n   *\n   * Must be finite and greater than `min`.\n   *\n   * @defaultValue `100`\n   */\n  max?: number;\n\n  /**\n   * Lower bound of the numeric range.\n   *\n   * Must be finite and lower than `max`.\n   *\n   * @defaultValue `0`\n   */\n  min?: number;\n\n  /**\n   * Current numeric value.\n   *\n   * The value must be finite. Values below `min` or above `max` are clamped\n   * before the percentage and formatted value are calculated.\n   */\n  value: number;\n\n  /**\n   * Number of characters reserved for the progress track.\n   *\n   * This excludes the optional label, spaces, and formatted value. It must be\n   * a positive integer.\n   */\n  width: number;\n}\n\n/**\n * Character pair used to draw a progress track.\n *\n * Use ASCII characters when the target terminal cannot display Unicode block\n * glyphs reliably.\n *\n * @example\n *\n * ```ts\n * const asciiCharacters: ProgressBarCharacters = {\n *   filled: '#',\n *   empty: '-',\n * };\n * ```\n */\nexport interface ProgressBarCharacters {\n  /** Character repeated for unfilled track cells. */\n  empty: string;\n\n  /** Character repeated for filled track cells. */\n  filled: string;\n}\n\n/**\n * Normalized value information passed to a progress value formatter.\n */\nexport interface ProgressBarValueContext {\n  /**\n   * Rounded progress in the inclusive range from `0` to `100`.\n   */\n  percentage: number;\n\n  /**\n   * Numeric value after it has been clamped to the configured range.\n   */\n  value: number;\n}\n\n/**\n * Renders a deterministic, single-line progress bar.\n *\n * This function is framework-independent and does not import Blessed. Import\n * it from `blessed-components/progress-bar` when only string rendering is\n * needed; that subpath keeps the Blessed adapter out of the module graph.\n *\n * The result has this structure:\n *\n * ```text\n * [label + space][fixed-width track][space][formatted value]\n * ```\n *\n * @param options - Numeric range, track width, characters, and text formatting.\n * @returns A plain terminal string. No ANSI sequences or Blessed tags are added.\n *\n * @throws `RangeError`\n * Thrown when `width` is not a positive integer.\n *\n * @throws `RangeError`\n * Thrown when `min` or `max` is not finite, or when `max` is not greater than\n * `min`.\n *\n * @throws `RangeError`\n * Thrown when `value` is not finite.\n *\n * @example Unicode output\n *\n * ```ts\n * import { renderProgressBar } from 'blessed-components/progress-bar';\n *\n * const output = renderProgressBar({\n *   label: 'Quality',\n *   value: 78,\n *   width: 16,\n * });\n *\n * // \"Quality ████████████░░░░ 78%\"\n * ```\n *\n * @example ASCII output with a custom value\n *\n * ```ts\n * const output = renderProgressBar({\n *   characters: { filled: '#', empty: '-' },\n *   formatValue: ({ value }) => `${value} files`,\n *   label: 'Uploaded',\n *   value: 25,\n *   width: 8,\n * });\n *\n * // \"Uploaded ##------ 25 files\"\n * ```\n */\nexport function renderProgressBar({\n  characters = { empty: '░', filled: '█' },\n  formatValue = ({ percentage }) => `${percentage}%`,\n  label,\n  max = 100,\n  min = 0,\n  value,\n  width,\n}: RenderProgressBarOptions): string {\n  if (!Number.isInteger(width) || width < 1) {\n    throw new RangeError('ProgressBar width must be a positive integer.');\n  }\n\n  if (!Number.isFinite(min) || !Number.isFinite(max) || max <= min) {\n    throw new RangeError('ProgressBar max must be greater than min.');\n  }\n\n  if (!Number.isFinite(value)) {\n    throw new RangeError('ProgressBar value must be finite.');\n  }\n\n  const clampedValue = Math.min(max, Math.max(min, value));\n  const percentage = Math.round(((clampedValue - min) / (max - min)) * 100);\n  const filledWidth = Math.round((percentage / 100) * width);\n  const track =\n    characters.filled.repeat(filledWidth) + characters.empty.repeat(width - filledWidth);\n  const prefix = label === undefined ? '' : `${label} `;\n  const valueText = formatValue({ percentage, value: clampedValue });\n\n  return `${prefix}${track} ${valueText}`;\n}\n","import blessed from 'blessed';\n\nimport {\n  type RenderProgressBarOptions,\n  renderProgressBar,\n} from '../../components/progress-bar/index.js';\n\n/**\n * Blessed box options supported by the ProgressBar adapter.\n *\n * `parent`, `content`, and `tags` are managed by {@link progressBar}:\n *\n * - `parent` comes from {@link ProgressBarOptions.parent}.\n * - `content` comes from {@link renderProgressBar}.\n * - `tags` is always disabled so labels and formatter output remain literal.\n */\nexport type ProgressBarBoxOptions = Omit<blessed.Widgets.BoxOptions, 'content' | 'parent' | 'tags'>;\n\n/**\n * Options accepted by the Blessed {@link progressBar} adapter.\n */\nexport interface ProgressBarOptions {\n  /**\n   * Optional Blessed box configuration.\n   *\n   * Position, dimensions, style, visibility, and other regular box options\n   * can be supplied here.\n   */\n  box?: ProgressBarBoxOptions;\n\n  /**\n   * Data passed to the pure {@link renderProgressBar} renderer.\n   */\n  data: RenderProgressBarOptions;\n\n  /**\n   * Blessed node that receives the created box as a child.\n   *\n   * Usually this is a `Screen` or another `BoxElement`.\n   */\n  parent: blessed.Widgets.Node;\n}\n\n/**\n * Imperative handle returned by {@link progressBar}.\n *\n * The handle owns one Blessed `BoxElement`. It does not own the parent screen\n * and never calls `screen.render()`, allowing callers to batch several updates\n * into one terminal render.\n */\nexport interface ProgressBarHandle {\n  /**\n   * Underlying Blessed box.\n   *\n   * Use this for standard Blessed operations such as positioning, showing,\n   * hiding, or applying styles.\n   */\n  readonly element: blessed.Widgets.BoxElement;\n\n  /**\n   * Destroys and detaches the owned box from its parent.\n   *\n   * This does not destroy the parent or screen. Do not use the handle after\n   * calling this method.\n   */\n  destroy(): void;\n\n  /**\n   * Re-renders component content using new data.\n   *\n   * The underlying element is preserved. This method does not call\n   * `screen.render()`; call it explicitly when updates should become visible.\n   *\n   * @param data - Complete renderer data replacing the previous data.\n   *\n   * @throws `RangeError`\n   * Propagates validation errors from {@link renderProgressBar}.\n   */\n  setData(data: RenderProgressBarOptions): void;\n}\n\n/**\n * Creates a display-only ProgressBar backed by a Blessed `BoxElement`.\n *\n * Import this adapter from `blessed-components/progress-bar/blessed`. Use\n * {@link renderProgressBar} from `blessed-components/progress-bar` when a\n * Blessed element is unnecessary.\n *\n * The adapter:\n *\n * - renders initial content through {@link renderProgressBar};\n * - disables Blessed tags to keep dynamic text literal;\n * - updates the existing element through {@link ProgressBarHandle.setData};\n * - leaves screen rendering under caller control;\n * - detaches its element through {@link ProgressBarHandle.destroy}.\n *\n * @param options - Parent node, renderer data, and optional box settings.\n * @returns A handle for the created element, updates, and cleanup.\n *\n * @throws `RangeError`\n * Propagates validation errors from {@link renderProgressBar}.\n *\n * @example\n *\n * ```ts\n * import blessed from 'blessed';\n * import { progressBar } from 'blessed-components/progress-bar/blessed';\n *\n * const screen = blessed.screen({ smartCSR: true });\n * const upload = progressBar({\n *   parent: screen,\n *   box: {\n *     top: 0,\n *     left: 0,\n *     width: 40,\n *     height: 1,\n *   },\n *   data: {\n *     label: 'Uploaded',\n *     value: 25,\n *     width: 20,\n *   },\n * });\n *\n * screen.render();\n *\n * upload.setData({\n *   label: 'Uploaded',\n *   value: 75,\n *   width: 20,\n * });\n * screen.render();\n *\n * upload.destroy();\n * screen.destroy();\n * ```\n */\nexport function progressBar({ box, data, parent }: ProgressBarOptions): ProgressBarHandle {\n  const element = blessed.box({\n    ...box,\n    content: renderProgressBar(data),\n    parent,\n    tags: false,\n  });\n\n  return {\n    element,\n    destroy() {\n      element.destroy();\n    },\n    setData(nextData) {\n      element.setContent(renderProgressBar(nextData));\n    },\n  };\n}\n","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","import blessed from 'blessed';\n\nimport { type RenderSparklineOptions, renderSparkline } from '../../components/sparkline/index.js';\n\n/**\n * Blessed box options supported by the Sparkline adapter.\n *\n * `parent`, `content`, and `tags` are controlled by {@link sparkline}.\n */\nexport type SparklineBoxOptions = Omit<blessed.Widgets.BoxOptions, 'content' | 'parent' | 'tags'>;\n\n/** Options accepted by the Blessed {@link sparkline} adapter. */\nexport interface SparklineOptions {\n  /** Optional position, dimensions, style, and other Blessed box settings. */\n  box?: SparklineBoxOptions;\n\n  /** Data passed to the pure {@link renderSparkline} renderer. */\n  data: RenderSparklineOptions;\n\n  /** Blessed screen or node that receives the created box. */\n  parent: blessed.Widgets.Node;\n}\n\n/**\n * Imperative handle returned by {@link sparkline}.\n *\n * The handle owns one box, never owns the parent screen, and never calls\n * `screen.render()`.\n */\nexport interface SparklineHandle {\n  /** Underlying Blessed box used for standard element operations. */\n  readonly element: blessed.Widgets.BoxElement;\n\n  /**\n   * Destroys and detaches the owned box.\n   *\n   * The parent and screen remain alive.\n   */\n  destroy(): void;\n\n  /**\n   * Replaces renderer data while preserving the Blessed element.\n   *\n   * Call `screen.render()` after one or more updates to flush visible output.\n   *\n   * @param data - Complete renderer data replacing the previous data.\n   *\n   * @throws `RangeError`\n   * Propagates validation errors from {@link renderSparkline}.\n   */\n  setData(data: RenderSparklineOptions): void;\n}\n\n/**\n * Creates a display-only Sparkline backed by a Blessed `BoxElement`.\n *\n * Import from `blessed-components/sparkline/blessed`. The adapter disables\n * Blessed tags, renders through {@link renderSparkline}, and leaves terminal\n * rendering under caller control.\n *\n * @param options - Parent node, renderer data, and optional box settings.\n * @returns Handle for the created box, updates, and cleanup.\n *\n * @throws `RangeError`\n * Propagates validation errors from {@link renderSparkline}.\n *\n * @example\n *\n * ```ts\n * import blessed from 'blessed';\n * import { sparkline } from 'blessed-components/sparkline/blessed';\n *\n * const screen = blessed.screen({ smartCSR: true });\n * const downloads = sparkline({\n *   parent: screen,\n *   box: { top: 0, left: 0, width: 40, height: 2 },\n *   data: {\n *     label: 'Downloads',\n *     values: [1, 3, 2, 8],\n *     width: 20,\n *   },\n * });\n *\n * screen.render();\n * downloads.setData({\n *   label: 'Downloads',\n *   values: [2, 4, 6, 8],\n *   width: 20,\n * });\n * screen.render();\n *\n * downloads.destroy();\n * screen.destroy();\n * ```\n */\nexport function sparkline({ box, data, parent }: SparklineOptions): SparklineHandle {\n  const element = blessed.box({\n    ...box,\n    content: renderSparkline(data),\n    parent,\n    tags: false,\n  });\n\n  return {\n    element,\n    destroy() {\n      element.destroy();\n    },\n    setData(nextData) {\n      element.setContent(renderSparkline(nextData));\n    },\n  };\n}\n"]}

package/dist/sparkline/blessed.cjs

@@ -0,0 +1,86 @@
+'use strict';
+
+var blessed = require('blessed');
+
+function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
+
+var blessed__default = /*#__PURE__*/_interopDefault(blessed);
+
+// src/adapters/blessed/sparkline.ts
+
+// 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 sparkline2 = 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 ? sparkline2 : `${sparkline2} ${summary}`;
+  return heading.length === 0 ? chartLine : `${heading}
+${chartLine}`;
+}
+
+// src/adapters/blessed/sparkline.ts
+function sparkline({ box, data, parent }) {
+  const element = blessed__default.default.box({
+    ...box,
+    content: renderSparkline(data),
+    parent,
+    tags: false
+  });
+  return {
+    element,
+    destroy() {
+      element.destroy();
+    },
+    setData(nextData) {
+      element.setContent(renderSparkline(nextData));
+    }
+  };
+}
+
+exports.sparkline = sparkline;
+//# sourceMappingURL=blessed.cjs.map
+//# sourceMappingURL=blessed.cjs.map

package/dist/sparkline/blessed.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/components/sparkline/index.ts","../../src/adapters/blessed/sparkline.ts"],"names":["sparkline","blessed"],"mappings":"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","file":"blessed.cjs","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","import blessed from 'blessed';\n\nimport { type RenderSparklineOptions, renderSparkline } from '../../components/sparkline/index.js';\n\n/**\n * Blessed box options supported by the Sparkline adapter.\n *\n * `parent`, `content`, and `tags` are controlled by {@link sparkline}.\n */\nexport type SparklineBoxOptions = Omit<blessed.Widgets.BoxOptions, 'content' | 'parent' | 'tags'>;\n\n/** Options accepted by the Blessed {@link sparkline} adapter. */\nexport interface SparklineOptions {\n  /** Optional position, dimensions, style, and other Blessed box settings. */\n  box?: SparklineBoxOptions;\n\n  /** Data passed to the pure {@link renderSparkline} renderer. */\n  data: RenderSparklineOptions;\n\n  /** Blessed screen or node that receives the created box. */\n  parent: blessed.Widgets.Node;\n}\n\n/**\n * Imperative handle returned by {@link sparkline}.\n *\n * The handle owns one box, never owns the parent screen, and never calls\n * `screen.render()`.\n */\nexport interface SparklineHandle {\n  /** Underlying Blessed box used for standard element operations. */\n  readonly element: blessed.Widgets.BoxElement;\n\n  /**\n   * Destroys and detaches the owned box.\n   *\n   * The parent and screen remain alive.\n   */\n  destroy(): void;\n\n  /**\n   * Replaces renderer data while preserving the Blessed element.\n   *\n   * Call `screen.render()` after one or more updates to flush visible output.\n   *\n   * @param data - Complete renderer data replacing the previous data.\n   *\n   * @throws `RangeError`\n   * Propagates validation errors from {@link renderSparkline}.\n   */\n  setData(data: RenderSparklineOptions): void;\n}\n\n/**\n * Creates a display-only Sparkline backed by a Blessed `BoxElement`.\n *\n * Import from `blessed-components/sparkline/blessed`. The adapter disables\n * Blessed tags, renders through {@link renderSparkline}, and leaves terminal\n * rendering under caller control.\n *\n * @param options - Parent node, renderer data, and optional box settings.\n * @returns Handle for the created box, updates, and cleanup.\n *\n * @throws `RangeError`\n * Propagates validation errors from {@link renderSparkline}.\n *\n * @example\n *\n * ```ts\n * import blessed from 'blessed';\n * import { sparkline } from 'blessed-components/sparkline/blessed';\n *\n * const screen = blessed.screen({ smartCSR: true });\n * const downloads = sparkline({\n *   parent: screen,\n *   box: { top: 0, left: 0, width: 40, height: 2 },\n *   data: {\n *     label: 'Downloads',\n *     values: [1, 3, 2, 8],\n *     width: 20,\n *   },\n * });\n *\n * screen.render();\n * downloads.setData({\n *   label: 'Downloads',\n *   values: [2, 4, 6, 8],\n *   width: 20,\n * });\n * screen.render();\n *\n * downloads.destroy();\n * screen.destroy();\n * ```\n */\nexport function sparkline({ box, data, parent }: SparklineOptions): SparklineHandle {\n  const element = blessed.box({\n    ...box,\n    content: renderSparkline(data),\n    parent,\n    tags: false,\n  });\n\n  return {\n    element,\n    destroy() {\n      element.destroy();\n    },\n    setData(nextData) {\n      element.setContent(renderSparkline(nextData));\n    },\n  };\n}\n"]}

package/dist/sparkline/blessed.d.cts

@@ -0,0 +1,90 @@
+import blessed from 'blessed';
+import { RenderSparklineOptions } from './index.cjs';
+
+/**
+ * Blessed box options supported by the Sparkline adapter.
+ *
+ * `parent`, `content`, and `tags` are controlled by {@link sparkline}.
+ */
+type SparklineBoxOptions = Omit<blessed.Widgets.BoxOptions, 'content' | 'parent' | 'tags'>;
+/** Options accepted by the Blessed {@link sparkline} adapter. */
+interface SparklineOptions {
+    /** Optional position, dimensions, style, and other Blessed box settings. */
+    box?: SparklineBoxOptions;
+    /** Data passed to the pure {@link renderSparkline} renderer. */
+    data: RenderSparklineOptions;
+    /** Blessed screen or node that receives the created box. */
+    parent: blessed.Widgets.Node;
+}
+/**
+ * Imperative handle returned by {@link sparkline}.
+ *
+ * The handle owns one box, never owns the parent screen, and never calls
+ * `screen.render()`.
+ */
+interface SparklineHandle {
+    /** Underlying Blessed box used for standard element operations. */
+    readonly element: blessed.Widgets.BoxElement;
+    /**
+     * Destroys and detaches the owned box.
+     *
+     * The parent and screen remain alive.
+     */
+    destroy(): void;
+    /**
+     * Replaces renderer data while preserving the Blessed element.
+     *
+     * Call `screen.render()` after one or more updates to flush visible output.
+     *
+     * @param data - Complete renderer data replacing the previous data.
+     *
+     * @throws `RangeError`
+     * Propagates validation errors from {@link renderSparkline}.
+     */
+    setData(data: RenderSparklineOptions): void;
+}
+/**
+ * Creates a display-only Sparkline backed by a Blessed `BoxElement`.
+ *
+ * Import from `blessed-components/sparkline/blessed`. The adapter disables
+ * Blessed tags, renders through {@link renderSparkline}, and leaves terminal
+ * rendering under caller control.
+ *
+ * @param options - Parent node, renderer data, and optional box settings.
+ * @returns Handle for the created box, updates, and cleanup.
+ *
+ * @throws `RangeError`
+ * Propagates validation errors from {@link renderSparkline}.
+ *
+ * @example
+ *
+ * ```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, 8],
+ *     width: 20,
+ *   },
+ * });
+ *
+ * screen.render();
+ * downloads.setData({
+ *   label: 'Downloads',
+ *   values: [2, 4, 6, 8],
+ *   width: 20,
+ * });
+ * screen.render();
+ *
+ * downloads.destroy();
+ * screen.destroy();
+ * ```
+ */
+declare function sparkline({ box, data, parent }: SparklineOptions): SparklineHandle;
+
+export { type SparklineBoxOptions, type SparklineHandle, type SparklineOptions, sparkline };