blessed-components 0.0.1 → 1.1.0

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":";;;;;;;;;;;AAAA,IAAM,kBAAA,GAAqB,CAAC,QAAA,EAAK,QAAA,EAAK,UAAK,QAAA,EAAK,QAAA,EAAK,QAAA,EAAK,QAAA,EAAK,QAAG,CAAA;AAmI3D,SAAS,eAAA,CAAgB;AAAA,EAC9B,UAAA,GAAa,kBAAA;AAAA,EACb,SAAA,GAAY,SAAA;AAAA,EACZ,KAAA;AAAA,EACA,GAAA,EAAK,aAAA;AAAA,EACL,GAAA,EAAK,aAAA;AAAA,EACL,OAAA;AAAA,EACA,KAAA,EAAO,YAAA;AAAA,EACP,MAAA;AAAA,EACA;AACF,CAAA,EAAmC;AACjC,EAAA,IAAI,CAAC,MAAA,CAAO,SAAA,CAAU,KAAK,CAAA,IAAK,QAAQ,CAAA,EAAG;AACzC,IAAA,MAAM,IAAI,WAAW,6CAA6C,CAAA;AAAA,EACpE;AAEA,EAAA,IAAI,UAAA,CAAW,MAAA,GAAS,CAAA,IAAK,UAAA,CAAW,IAAA,CAAK,CAAC,SAAA,KAAc,SAAA,CAAU,MAAA,KAAW,CAAC,CAAA,EAAG;AACnF,IAAA,MAAM,IAAI,WAAW,mEAAmE,CAAA;AAAA,EAC1F;AAEA,EAAA,IAAI,MAAA,CAAO,KAAK,CAAC,KAAA,KAAU,CAAC,MAAA,CAAO,QAAA,CAAS,KAAK,CAAC,CAAA,EAAG;AACnD,IAAA,MAAM,IAAI,WAAW,kCAAkC,CAAA;AAAA,EACzD;AAEA,EAAA,IAAI,MAAA,CAAO,WAAW,CAAA,EAAG;AACvB,IAAA,OAAO,SAAA;AAAA,EACT;AAEA,EAAA,MAAM,GAAA,GAAM,aAAA,IAAiB,IAAA,CAAK,GAAA,CAAI,GAAG,MAAM,CAAA;AAC/C,EAAA,MAAM,GAAA,GAAM,aAAA,IAAiB,IAAA,CAAK,GAAA,CAAI,GAAG,MAAM,CAAA;AAE/C,EAAA,IAAI,CAAC,MAAA,CAAO,QAAA,CAAS,GAAG,CAAA,IAAK,CAAC,MAAA,CAAO,QAAA,CAAS,GAAG,CAAA,IAAK,GAAA,GAAM,GAAA,EAAK;AAC/D,IAAA,MAAM,IAAI,WAAW,qDAAqD,CAAA;AAAA,EAC5E;AAEA,EAAA,IAAA,CAAK,aAAA,KAAkB,MAAA,IAAa,aAAA,KAAkB,MAAA,KAAc,QAAQ,GAAA,EAAK;AAC/E,IAAA,MAAM,IAAI,WAAW,kDAAkD,CAAA;AAAA,EACzE;AAEA,EAAA,MAAM,gBAAgB,IAAA,CAAK,KAAA,CAAA,CAAO,UAAA,CAAW,MAAA,GAAS,KAAK,CAAC,CAAA;AAC5D,EAAA,MAAM,OAAA,GACJ,MAAA,CAAO,MAAA,IAAU,KAAA,GACb,MAAA,GACA,KAAA,CAAM,IAAA,CAAK,EAAE,MAAA,EAAQ,KAAA,EAAM,EAAG,CAAC,GAAG,KAAA,KAAU;AAC1C,IAAA,MAAM,QAAQ,IAAA,CAAK,KAAA,CAAO,KAAA,GAAQ,MAAA,CAAO,SAAU,KAAK,CAAA;AACxD,IAAA,MAAM,MAAM,IAAA,CAAK,KAAA,CAAA,CAAQ,QAAQ,CAAA,IAAK,MAAA,CAAO,SAAU,KAAK,CAAA;AAE5D,IAAA,OAAO,KAAK,GAAA,CAAI,GAAG,OAAO,KAAA,CAAM,KAAA,EAAO,GAAG,CAAC,CAAA;AAAA,EAC7C,CAAC,CAAA;AACP,EAAA,MAAMA,UAAAA,GAAY,OAAA,CACf,GAAA,CAAI,CAAC,KAAA,KAAU;AACd,IAAA,IAAI,QAAQ,GAAA,EAAK;AACf,MAAA,OAAO,WAAW,aAAa,CAAA;AAAA,IACjC;AAEA,IAAA,MAAM,YAAA,GAAe,KAAK,GAAA,CAAI,GAAA,EAAK,KAAK,GAAA,CAAI,GAAA,EAAK,KAAK,CAAC,CAAA;AACvD,IAAA,MAAM,KAAA,GAAA,CAAS,YAAA,GAAe,GAAA,KAAQ,GAAA,GAAM,GAAA,CAAA;AAC5C,IAAA,MAAM,KAAA,GACJ,YAAA,IAAgB,GAAA,GAAM,UAAA,CAAW,MAAA,GAAS,CAAA,GAAI,IAAA,CAAK,KAAA,CAAM,KAAA,IAAS,UAAA,CAAW,MAAA,GAAS,CAAA,CAAE,CAAA;AAE1F,IAAA,OAAO,WAAW,KAAK,CAAA;AAAA,EACzB,CAAC,CAAA,CACA,IAAA,CAAK,EAAE,CAAA;AACV,EAAA,MAAM,OAAA,GAAU,CAAC,KAAA,EAAO,YAAY,CAAA,CAAE,MAAA,CAAO,CAAC,IAAA,KAAS,IAAA,KAAS,MAAS,CAAA,CAAE,IAAA,CAAK,GAAG,CAAA;AACnF,EAAA,MAAM,YAAY,OAAA,KAAY,MAAA,GAAYA,aAAY,CAAA,EAAGA,UAAS,IAAI,OAAO,CAAA,CAAA;AAE7E,EAAA,OAAO,OAAA,CAAQ,MAAA,KAAW,CAAA,GAAI,SAAA,GAAY,GAAG,OAAO;AAAA,EAAK,SAAS,CAAA,CAAA;AACpE;;;ACtGO,SAAS,SAAA,CAAU,EAAE,GAAA,EAAK,IAAA,EAAM,QAAO,EAAsC;AAClF,EAAA,MAAM,OAAA,GAAUC,yBAAQ,GAAA,CAAI;AAAA,IAC1B,GAAG,GAAA;AAAA,IACH,OAAA,EAAS,gBAAgB,IAAI,CAAA;AAAA,IAC7B,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,eAAA,CAAgB,QAAQ,CAAC,CAAA;AAAA,IAC9C;AAAA,GACF;AACF","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 };

package/dist/sparkline/blessed.d.ts

@@ -0,0 +1,90 @@
+import blessed from 'blessed';
+import { RenderSparklineOptions } from './index.js';
+
+/**
+ * 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 };

package/dist/sparkline/blessed.js

@@ -0,0 +1,80 @@
+import blessed from '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.box({
+    ...box,
+    content: renderSparkline(data),
+    parent,
+    tags: false
+  });
+  return {
+    element,
+    destroy() {
+      element.destroy();
+    },
+    setData(nextData) {
+      element.setContent(renderSparkline(nextData));
+    }
+  };
+}
+
+export { sparkline };
+//# sourceMappingURL=blessed.js.map
+//# sourceMappingURL=blessed.js.map

package/dist/sparkline/blessed.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/components/sparkline/index.ts","../../src/adapters/blessed/sparkline.ts"],"names":["sparkline"],"mappings":"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","file":"blessed.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","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/index.cjs

@@ -0,0 +1,59 @@
+'use strict';
+
+// 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}`;
+}
+
+exports.renderSparkline = renderSparkline;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/sparkline/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/components/sparkline/index.ts"],"names":[],"mappings":"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","file":"index.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"]}

package/dist/sparkline/index.d.cts

@@ -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 };