blessed-components 0.0.1 → 1.0.0

package/dist/index.cjs

@@ -1,4 +1,61 @@
 '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/progress-bar.ts
+
+// src/components/progress-bar/index.ts
+function renderProgressBar({
+  characters = { empty: "\u2591", filled: "\u2588" },
+  formatValue = ({ percentage }) => `${percentage}%`,
+  label,
+  max = 100,
+  min = 0,
+  value,
+  width
+}) {
+  if (!Number.isInteger(width) || width < 1) {
+    throw new RangeError("ProgressBar width must be a positive integer.");
+  }
+  if (!Number.isFinite(min) || !Number.isFinite(max) || max <= min) {
+    throw new RangeError("ProgressBar max must be greater than min.");
+  }
+  if (!Number.isFinite(value)) {
+    throw new RangeError("ProgressBar value must be finite.");
+  }
+  const clampedValue = Math.min(max, Math.max(min, value));
+  const percentage = Math.round((clampedValue - min) / (max - min) * 100);
+  const filledWidth = Math.round(percentage / 100 * width);
+  const track = characters.filled.repeat(filledWidth) + characters.empty.repeat(width - filledWidth);
+  const prefix = label === void 0 ? "" : `${label} `;
+  const valueText = formatValue({ percentage, value: clampedValue });
+  return `${prefix}${track} ${valueText}`;
+}
+
+// src/adapters/blessed/progress-bar.ts
+function progressBar({ box, data, parent }) {
+  const element = blessed__default.default.box({
+    ...box,
+    content: renderProgressBar(data),
+    parent,
+    tags: false
+  });
+  return {
+    element,
+    destroy() {
+      element.destroy();
+    },
+    setData(nextData) {
+      element.setContent(renderProgressBar(nextData));
+    }
+  };
+}
+
+exports.progressBar = progressBar;
+exports.renderProgressBar = renderProgressBar;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":[],"names":[],"mappings":"","file":"index.cjs"}
+{"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"]}

package/dist/index.d.cts

@@ -1,2 +1,3 @@
-
-export {  }
+export { ProgressBarBoxOptions, ProgressBarHandle, ProgressBarOptions, progressBar } from './progress-bar/blessed.cjs';
+export { ProgressBarCharacters, ProgressBarValueContext, RenderProgressBarOptions, renderProgressBar } from './progress-bar/index.cjs';
+import 'blessed';

package/dist/index.d.ts

@@ -1,2 +1,3 @@
-
-export {  }
+export { ProgressBarBoxOptions, ProgressBarHandle, ProgressBarOptions, progressBar } from './progress-bar/blessed.js';
+export { ProgressBarCharacters, ProgressBarValueContext, RenderProgressBarOptions, renderProgressBar } from './progress-bar/index.js';
+import 'blessed';

package/dist/index.js

@@ -1,3 +1,54 @@
+import blessed from 'blessed';
 
+// src/adapters/blessed/progress-bar.ts
+
+// src/components/progress-bar/index.ts
+function renderProgressBar({
+  characters = { empty: "\u2591", filled: "\u2588" },
+  formatValue = ({ percentage }) => `${percentage}%`,
+  label,
+  max = 100,
+  min = 0,
+  value,
+  width
+}) {
+  if (!Number.isInteger(width) || width < 1) {
+    throw new RangeError("ProgressBar width must be a positive integer.");
+  }
+  if (!Number.isFinite(min) || !Number.isFinite(max) || max <= min) {
+    throw new RangeError("ProgressBar max must be greater than min.");
+  }
+  if (!Number.isFinite(value)) {
+    throw new RangeError("ProgressBar value must be finite.");
+  }
+  const clampedValue = Math.min(max, Math.max(min, value));
+  const percentage = Math.round((clampedValue - min) / (max - min) * 100);
+  const filledWidth = Math.round(percentage / 100 * width);
+  const track = characters.filled.repeat(filledWidth) + characters.empty.repeat(width - filledWidth);
+  const prefix = label === void 0 ? "" : `${label} `;
+  const valueText = formatValue({ percentage, value: clampedValue });
+  return `${prefix}${track} ${valueText}`;
+}
+
+// src/adapters/blessed/progress-bar.ts
+function progressBar({ box, data, parent }) {
+  const element = blessed.box({
+    ...box,
+    content: renderProgressBar(data),
+    parent,
+    tags: false
+  });
+  return {
+    element,
+    destroy() {
+      element.destroy();
+    },
+    setData(nextData) {
+      element.setContent(renderProgressBar(nextData));
+    }
+  };
+}
+
+export { progressBar, renderProgressBar };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":[],"names":[],"mappings":"","file":"index.js"}
+{"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"]}

package/dist/progress-bar/blessed.cjs

@@ -0,0 +1,60 @@
+'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/progress-bar.ts
+
+// src/components/progress-bar/index.ts
+function renderProgressBar({
+  characters = { empty: "\u2591", filled: "\u2588" },
+  formatValue = ({ percentage }) => `${percentage}%`,
+  label,
+  max = 100,
+  min = 0,
+  value,
+  width
+}) {
+  if (!Number.isInteger(width) || width < 1) {
+    throw new RangeError("ProgressBar width must be a positive integer.");
+  }
+  if (!Number.isFinite(min) || !Number.isFinite(max) || max <= min) {
+    throw new RangeError("ProgressBar max must be greater than min.");
+  }
+  if (!Number.isFinite(value)) {
+    throw new RangeError("ProgressBar value must be finite.");
+  }
+  const clampedValue = Math.min(max, Math.max(min, value));
+  const percentage = Math.round((clampedValue - min) / (max - min) * 100);
+  const filledWidth = Math.round(percentage / 100 * width);
+  const track = characters.filled.repeat(filledWidth) + characters.empty.repeat(width - filledWidth);
+  const prefix = label === void 0 ? "" : `${label} `;
+  const valueText = formatValue({ percentage, value: clampedValue });
+  return `${prefix}${track} ${valueText}`;
+}
+
+// src/adapters/blessed/progress-bar.ts
+function progressBar({ box, data, parent }) {
+  const element = blessed__default.default.box({
+    ...box,
+    content: renderProgressBar(data),
+    parent,
+    tags: false
+  });
+  return {
+    element,
+    destroy() {
+      element.destroy();
+    },
+    setData(nextData) {
+      element.setContent(renderProgressBar(nextData));
+    }
+  };
+}
+
+exports.progressBar = progressBar;
+//# sourceMappingURL=blessed.cjs.map
+//# sourceMappingURL=blessed.cjs.map

package/dist/progress-bar/blessed.cjs.map

@@ -0,0 +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":"blessed.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"]}

package/dist/progress-bar/blessed.d.cts

@@ -0,0 +1,129 @@
+import blessed from 'blessed';
+import { RenderProgressBarOptions } from './index.cjs';
+
+/**
+ * Blessed box options supported by the ProgressBar adapter.
+ *
+ * `parent`, `content`, and `tags` are managed by {@link progressBar}:
+ *
+ * - `parent` comes from {@link ProgressBarOptions.parent}.
+ * - `content` comes from {@link renderProgressBar}.
+ * - `tags` is always disabled so labels and formatter output remain literal.
+ */
+type ProgressBarBoxOptions = Omit<blessed.Widgets.BoxOptions, 'content' | 'parent' | 'tags'>;
+/**
+ * Options accepted by the Blessed {@link progressBar} adapter.
+ */
+interface ProgressBarOptions {
+    /**
+     * Optional Blessed box configuration.
+     *
+     * Position, dimensions, style, visibility, and other regular box options
+     * can be supplied here.
+     */
+    box?: ProgressBarBoxOptions;
+    /**
+     * Data passed to the pure {@link renderProgressBar} renderer.
+     */
+    data: RenderProgressBarOptions;
+    /**
+     * Blessed node that receives the created box as a child.
+     *
+     * Usually this is a `Screen` or another `BoxElement`.
+     */
+    parent: blessed.Widgets.Node;
+}
+/**
+ * Imperative handle returned by {@link progressBar}.
+ *
+ * The handle owns one Blessed `BoxElement`. It does not own the parent screen
+ * and never calls `screen.render()`, allowing callers to batch several updates
+ * into one terminal render.
+ */
+interface ProgressBarHandle {
+    /**
+     * Underlying Blessed box.
+     *
+     * Use this for standard Blessed operations such as positioning, showing,
+     * hiding, or applying styles.
+     */
+    readonly element: blessed.Widgets.BoxElement;
+    /**
+     * Destroys and detaches the owned box from its parent.
+     *
+     * This does not destroy the parent or screen. Do not use the handle after
+     * calling this method.
+     */
+    destroy(): void;
+    /**
+     * Re-renders component content using new data.
+     *
+     * The underlying element is preserved. This method does not call
+     * `screen.render()`; call it explicitly when updates should become visible.
+     *
+     * @param data - Complete renderer data replacing the previous data.
+     *
+     * @throws `RangeError`
+     * Propagates validation errors from {@link renderProgressBar}.
+     */
+    setData(data: RenderProgressBarOptions): void;
+}
+/**
+ * Creates a display-only ProgressBar backed by a Blessed `BoxElement`.
+ *
+ * Import this adapter from `blessed-components/progress-bar/blessed`. Use
+ * {@link renderProgressBar} from `blessed-components/progress-bar` when a
+ * Blessed element is unnecessary.
+ *
+ * The adapter:
+ *
+ * - renders initial content through {@link renderProgressBar};
+ * - disables Blessed tags to keep dynamic text literal;
+ * - updates the existing element through {@link ProgressBarHandle.setData};
+ * - leaves screen rendering under caller control;
+ * - detaches its element through {@link ProgressBarHandle.destroy}.
+ *
+ * @param options - Parent node, renderer data, and optional box settings.
+ * @returns A handle for the created element, updates, and cleanup.
+ *
+ * @throws `RangeError`
+ * Propagates validation errors from {@link renderProgressBar}.
+ *
+ * @example
+ *
+ * ```ts
+ * import blessed from 'blessed';
+ * import { progressBar } from 'blessed-components/progress-bar/blessed';
+ *
+ * const screen = blessed.screen({ smartCSR: true });
+ * const upload = progressBar({
+ *   parent: screen,
+ *   box: {
+ *     top: 0,
+ *     left: 0,
+ *     width: 40,
+ *     height: 1,
+ *   },
+ *   data: {
+ *     label: 'Uploaded',
+ *     value: 25,
+ *     width: 20,
+ *   },
+ * });
+ *
+ * screen.render();
+ *
+ * upload.setData({
+ *   label: 'Uploaded',
+ *   value: 75,
+ *   width: 20,
+ * });
+ * screen.render();
+ *
+ * upload.destroy();
+ * screen.destroy();
+ * ```
+ */
+declare function progressBar({ box, data, parent }: ProgressBarOptions): ProgressBarHandle;
+
+export { type ProgressBarBoxOptions, type ProgressBarHandle, type ProgressBarOptions, progressBar };

package/dist/progress-bar/blessed.d.ts

@@ -0,0 +1,129 @@
+import blessed from 'blessed';
+import { RenderProgressBarOptions } from './index.js';
+
+/**
+ * Blessed box options supported by the ProgressBar adapter.
+ *
+ * `parent`, `content`, and `tags` are managed by {@link progressBar}:
+ *
+ * - `parent` comes from {@link ProgressBarOptions.parent}.
+ * - `content` comes from {@link renderProgressBar}.
+ * - `tags` is always disabled so labels and formatter output remain literal.
+ */
+type ProgressBarBoxOptions = Omit<blessed.Widgets.BoxOptions, 'content' | 'parent' | 'tags'>;
+/**
+ * Options accepted by the Blessed {@link progressBar} adapter.
+ */
+interface ProgressBarOptions {
+    /**
+     * Optional Blessed box configuration.
+     *
+     * Position, dimensions, style, visibility, and other regular box options
+     * can be supplied here.
+     */
+    box?: ProgressBarBoxOptions;
+    /**
+     * Data passed to the pure {@link renderProgressBar} renderer.
+     */
+    data: RenderProgressBarOptions;
+    /**
+     * Blessed node that receives the created box as a child.
+     *
+     * Usually this is a `Screen` or another `BoxElement`.
+     */
+    parent: blessed.Widgets.Node;
+}
+/**
+ * Imperative handle returned by {@link progressBar}.
+ *
+ * The handle owns one Blessed `BoxElement`. It does not own the parent screen
+ * and never calls `screen.render()`, allowing callers to batch several updates
+ * into one terminal render.
+ */
+interface ProgressBarHandle {
+    /**
+     * Underlying Blessed box.
+     *
+     * Use this for standard Blessed operations such as positioning, showing,
+     * hiding, or applying styles.
+     */
+    readonly element: blessed.Widgets.BoxElement;
+    /**
+     * Destroys and detaches the owned box from its parent.
+     *
+     * This does not destroy the parent or screen. Do not use the handle after
+     * calling this method.
+     */
+    destroy(): void;
+    /**
+     * Re-renders component content using new data.
+     *
+     * The underlying element is preserved. This method does not call
+     * `screen.render()`; call it explicitly when updates should become visible.
+     *
+     * @param data - Complete renderer data replacing the previous data.
+     *
+     * @throws `RangeError`
+     * Propagates validation errors from {@link renderProgressBar}.
+     */
+    setData(data: RenderProgressBarOptions): void;
+}
+/**
+ * Creates a display-only ProgressBar backed by a Blessed `BoxElement`.
+ *
+ * Import this adapter from `blessed-components/progress-bar/blessed`. Use
+ * {@link renderProgressBar} from `blessed-components/progress-bar` when a
+ * Blessed element is unnecessary.
+ *
+ * The adapter:
+ *
+ * - renders initial content through {@link renderProgressBar};
+ * - disables Blessed tags to keep dynamic text literal;
+ * - updates the existing element through {@link ProgressBarHandle.setData};
+ * - leaves screen rendering under caller control;
+ * - detaches its element through {@link ProgressBarHandle.destroy}.
+ *
+ * @param options - Parent node, renderer data, and optional box settings.
+ * @returns A handle for the created element, updates, and cleanup.
+ *
+ * @throws `RangeError`
+ * Propagates validation errors from {@link renderProgressBar}.
+ *
+ * @example
+ *
+ * ```ts
+ * import blessed from 'blessed';
+ * import { progressBar } from 'blessed-components/progress-bar/blessed';
+ *
+ * const screen = blessed.screen({ smartCSR: true });
+ * const upload = progressBar({
+ *   parent: screen,
+ *   box: {
+ *     top: 0,
+ *     left: 0,
+ *     width: 40,
+ *     height: 1,
+ *   },
+ *   data: {
+ *     label: 'Uploaded',
+ *     value: 25,
+ *     width: 20,
+ *   },
+ * });
+ *
+ * screen.render();
+ *
+ * upload.setData({
+ *   label: 'Uploaded',
+ *   value: 75,
+ *   width: 20,
+ * });
+ * screen.render();
+ *
+ * upload.destroy();
+ * screen.destroy();
+ * ```
+ */
+declare function progressBar({ box, data, parent }: ProgressBarOptions): ProgressBarHandle;
+
+export { type ProgressBarBoxOptions, type ProgressBarHandle, type ProgressBarOptions, progressBar };

package/dist/progress-bar/blessed.js

@@ -0,0 +1,54 @@
+import blessed from 'blessed';
+
+// src/adapters/blessed/progress-bar.ts
+
+// src/components/progress-bar/index.ts
+function renderProgressBar({
+  characters = { empty: "\u2591", filled: "\u2588" },
+  formatValue = ({ percentage }) => `${percentage}%`,
+  label,
+  max = 100,
+  min = 0,
+  value,
+  width
+}) {
+  if (!Number.isInteger(width) || width < 1) {
+    throw new RangeError("ProgressBar width must be a positive integer.");
+  }
+  if (!Number.isFinite(min) || !Number.isFinite(max) || max <= min) {
+    throw new RangeError("ProgressBar max must be greater than min.");
+  }
+  if (!Number.isFinite(value)) {
+    throw new RangeError("ProgressBar value must be finite.");
+  }
+  const clampedValue = Math.min(max, Math.max(min, value));
+  const percentage = Math.round((clampedValue - min) / (max - min) * 100);
+  const filledWidth = Math.round(percentage / 100 * width);
+  const track = characters.filled.repeat(filledWidth) + characters.empty.repeat(width - filledWidth);
+  const prefix = label === void 0 ? "" : `${label} `;
+  const valueText = formatValue({ percentage, value: clampedValue });
+  return `${prefix}${track} ${valueText}`;
+}
+
+// src/adapters/blessed/progress-bar.ts
+function progressBar({ box, data, parent }) {
+  const element = blessed.box({
+    ...box,
+    content: renderProgressBar(data),
+    parent,
+    tags: false
+  });
+  return {
+    element,
+    destroy() {
+      element.destroy();
+    },
+    setData(nextData) {
+      element.setContent(renderProgressBar(nextData));
+    }
+  };
+}
+
+export { progressBar };
+//# sourceMappingURL=blessed.js.map
+//# sourceMappingURL=blessed.js.map

package/dist/progress-bar/blessed.js.map

@@ -0,0 +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":"blessed.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"]}

package/dist/progress-bar/index.cjs

@@ -0,0 +1,33 @@
+'use strict';
+
+// src/components/progress-bar/index.ts
+function renderProgressBar({
+  characters = { empty: "\u2591", filled: "\u2588" },
+  formatValue = ({ percentage }) => `${percentage}%`,
+  label,
+  max = 100,
+  min = 0,
+  value,
+  width
+}) {
+  if (!Number.isInteger(width) || width < 1) {
+    throw new RangeError("ProgressBar width must be a positive integer.");
+  }
+  if (!Number.isFinite(min) || !Number.isFinite(max) || max <= min) {
+    throw new RangeError("ProgressBar max must be greater than min.");
+  }
+  if (!Number.isFinite(value)) {
+    throw new RangeError("ProgressBar value must be finite.");
+  }
+  const clampedValue = Math.min(max, Math.max(min, value));
+  const percentage = Math.round((clampedValue - min) / (max - min) * 100);
+  const filledWidth = Math.round(percentage / 100 * width);
+  const track = characters.filled.repeat(filledWidth) + characters.empty.repeat(width - filledWidth);
+  const prefix = label === void 0 ? "" : `${label} `;
+  const valueText = formatValue({ percentage, value: clampedValue });
+  return `${prefix}${track} ${valueText}`;
+}
+
+exports.renderProgressBar = renderProgressBar;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map