blessed-components 0.0.1 → 1.0.0

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

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/components/progress-bar/index.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","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"]}

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

@@ -0,0 +1,181 @@
+/**
+ * Options accepted by {@link renderProgressBar}.
+ *
+ * The renderer maps `value` from the inclusive numeric range defined by
+ * `min` and `max` into a fixed-width terminal track. Values outside the range
+ * are clamped before rendering.
+ *
+ * @example Basic percentage bar
+ *
+ * ```ts
+ * renderProgressBar({
+ *   value: 50,
+ *   width: 10,
+ * });
+ * // "█████░░░░░ 50%"
+ * ```
+ *
+ * @example Custom range and label
+ *
+ * ```ts
+ * renderProgressBar({
+ *   label: 'Workers',
+ *   min: 0,
+ *   max: 8,
+ *   value: 6,
+ *   width: 8,
+ * });
+ * // "Workers ██████░░ 75%"
+ * ```
+ */
+interface RenderProgressBarOptions {
+    /**
+     * Characters used to render filled and empty cells.
+     *
+     * Each character should occupy one terminal cell. Multi-cell or combining
+     * characters can make the visible track wider than `width`.
+     *
+     * @defaultValue `{ filled: '█', empty: '░' }`
+     */
+    characters?: ProgressBarCharacters;
+    /**
+     * Formats the value text appended after the track.
+     *
+     * The callback receives the clamped numeric value and its rounded
+     * percentage. Returning an empty string leaves the trailing separator in
+     * place; callers that need a track-only representation should account for
+     * that when composing output.
+     *
+     * @defaultValue `({ percentage }) => `${percentage}%``
+     */
+    formatValue?: (context: ProgressBarValueContext) => string;
+    /**
+     * Optional text rendered before the track.
+     *
+     * Dynamic values must be escaped by the caller if the returned string will
+     * later be inserted into a Blessed element with tags enabled. The bundled
+     * Blessed adapter disables tags.
+     */
+    label?: string;
+    /**
+     * Upper bound of the numeric range.
+     *
+     * Must be finite and greater than `min`.
+     *
+     * @defaultValue `100`
+     */
+    max?: number;
+    /**
+     * Lower bound of the numeric range.
+     *
+     * Must be finite and lower than `max`.
+     *
+     * @defaultValue `0`
+     */
+    min?: number;
+    /**
+     * Current numeric value.
+     *
+     * The value must be finite. Values below `min` or above `max` are clamped
+     * before the percentage and formatted value are calculated.
+     */
+    value: number;
+    /**
+     * Number of characters reserved for the progress track.
+     *
+     * This excludes the optional label, spaces, and formatted value. It must be
+     * a positive integer.
+     */
+    width: number;
+}
+/**
+ * Character pair used to draw a progress track.
+ *
+ * Use ASCII characters when the target terminal cannot display Unicode block
+ * glyphs reliably.
+ *
+ * @example
+ *
+ * ```ts
+ * const asciiCharacters: ProgressBarCharacters = {
+ *   filled: '#',
+ *   empty: '-',
+ * };
+ * ```
+ */
+interface ProgressBarCharacters {
+    /** Character repeated for unfilled track cells. */
+    empty: string;
+    /** Character repeated for filled track cells. */
+    filled: string;
+}
+/**
+ * Normalized value information passed to a progress value formatter.
+ */
+interface ProgressBarValueContext {
+    /**
+     * Rounded progress in the inclusive range from `0` to `100`.
+     */
+    percentage: number;
+    /**
+     * Numeric value after it has been clamped to the configured range.
+     */
+    value: number;
+}
+/**
+ * Renders a deterministic, single-line progress bar.
+ *
+ * This function is framework-independent and does not import Blessed. Import
+ * it from `blessed-components/progress-bar` when only string rendering is
+ * needed; that subpath keeps the Blessed adapter out of the module graph.
+ *
+ * The result has this structure:
+ *
+ * ```text
+ * [label + space][fixed-width track][space][formatted value]
+ * ```
+ *
+ * @param options - Numeric range, track width, characters, and text formatting.
+ * @returns A plain terminal string. No ANSI sequences or Blessed tags are added.
+ *
+ * @throws `RangeError`
+ * Thrown when `width` is not a positive integer.
+ *
+ * @throws `RangeError`
+ * Thrown when `min` or `max` is not finite, or when `max` is not greater than
+ * `min`.
+ *
+ * @throws `RangeError`
+ * Thrown when `value` is not finite.
+ *
+ * @example Unicode output
+ *
+ * ```ts
+ * import { renderProgressBar } from 'blessed-components/progress-bar';
+ *
+ * const output = renderProgressBar({
+ *   label: 'Quality',
+ *   value: 78,
+ *   width: 16,
+ * });
+ *
+ * // "Quality ████████████░░░░ 78%"
+ * ```
+ *
+ * @example ASCII output with a custom value
+ *
+ * ```ts
+ * const output = renderProgressBar({
+ *   characters: { filled: '#', empty: '-' },
+ *   formatValue: ({ value }) => `${value} files`,
+ *   label: 'Uploaded',
+ *   value: 25,
+ *   width: 8,
+ * });
+ *
+ * // "Uploaded ##------ 25 files"
+ * ```
+ */
+declare function renderProgressBar({ characters, formatValue, label, max, min, value, width, }: RenderProgressBarOptions): string;
+
+export { type ProgressBarCharacters, type ProgressBarValueContext, type RenderProgressBarOptions, renderProgressBar };

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

@@ -0,0 +1,181 @@
+/**
+ * Options accepted by {@link renderProgressBar}.
+ *
+ * The renderer maps `value` from the inclusive numeric range defined by
+ * `min` and `max` into a fixed-width terminal track. Values outside the range
+ * are clamped before rendering.
+ *
+ * @example Basic percentage bar
+ *
+ * ```ts
+ * renderProgressBar({
+ *   value: 50,
+ *   width: 10,
+ * });
+ * // "█████░░░░░ 50%"
+ * ```
+ *
+ * @example Custom range and label
+ *
+ * ```ts
+ * renderProgressBar({
+ *   label: 'Workers',
+ *   min: 0,
+ *   max: 8,
+ *   value: 6,
+ *   width: 8,
+ * });
+ * // "Workers ██████░░ 75%"
+ * ```
+ */
+interface RenderProgressBarOptions {
+    /**
+     * Characters used to render filled and empty cells.
+     *
+     * Each character should occupy one terminal cell. Multi-cell or combining
+     * characters can make the visible track wider than `width`.
+     *
+     * @defaultValue `{ filled: '█', empty: '░' }`
+     */
+    characters?: ProgressBarCharacters;
+    /**
+     * Formats the value text appended after the track.
+     *
+     * The callback receives the clamped numeric value and its rounded
+     * percentage. Returning an empty string leaves the trailing separator in
+     * place; callers that need a track-only representation should account for
+     * that when composing output.
+     *
+     * @defaultValue `({ percentage }) => `${percentage}%``
+     */
+    formatValue?: (context: ProgressBarValueContext) => string;
+    /**
+     * Optional text rendered before the track.
+     *
+     * Dynamic values must be escaped by the caller if the returned string will
+     * later be inserted into a Blessed element with tags enabled. The bundled
+     * Blessed adapter disables tags.
+     */
+    label?: string;
+    /**
+     * Upper bound of the numeric range.
+     *
+     * Must be finite and greater than `min`.
+     *
+     * @defaultValue `100`
+     */
+    max?: number;
+    /**
+     * Lower bound of the numeric range.
+     *
+     * Must be finite and lower than `max`.
+     *
+     * @defaultValue `0`
+     */
+    min?: number;
+    /**
+     * Current numeric value.
+     *
+     * The value must be finite. Values below `min` or above `max` are clamped
+     * before the percentage and formatted value are calculated.
+     */
+    value: number;
+    /**
+     * Number of characters reserved for the progress track.
+     *
+     * This excludes the optional label, spaces, and formatted value. It must be
+     * a positive integer.
+     */
+    width: number;
+}
+/**
+ * Character pair used to draw a progress track.
+ *
+ * Use ASCII characters when the target terminal cannot display Unicode block
+ * glyphs reliably.
+ *
+ * @example
+ *
+ * ```ts
+ * const asciiCharacters: ProgressBarCharacters = {
+ *   filled: '#',
+ *   empty: '-',
+ * };
+ * ```
+ */
+interface ProgressBarCharacters {
+    /** Character repeated for unfilled track cells. */
+    empty: string;
+    /** Character repeated for filled track cells. */
+    filled: string;
+}
+/**
+ * Normalized value information passed to a progress value formatter.
+ */
+interface ProgressBarValueContext {
+    /**
+     * Rounded progress in the inclusive range from `0` to `100`.
+     */
+    percentage: number;
+    /**
+     * Numeric value after it has been clamped to the configured range.
+     */
+    value: number;
+}
+/**
+ * Renders a deterministic, single-line progress bar.
+ *
+ * This function is framework-independent and does not import Blessed. Import
+ * it from `blessed-components/progress-bar` when only string rendering is
+ * needed; that subpath keeps the Blessed adapter out of the module graph.
+ *
+ * The result has this structure:
+ *
+ * ```text
+ * [label + space][fixed-width track][space][formatted value]
+ * ```
+ *
+ * @param options - Numeric range, track width, characters, and text formatting.
+ * @returns A plain terminal string. No ANSI sequences or Blessed tags are added.
+ *
+ * @throws `RangeError`
+ * Thrown when `width` is not a positive integer.
+ *
+ * @throws `RangeError`
+ * Thrown when `min` or `max` is not finite, or when `max` is not greater than
+ * `min`.
+ *
+ * @throws `RangeError`
+ * Thrown when `value` is not finite.
+ *
+ * @example Unicode output
+ *
+ * ```ts
+ * import { renderProgressBar } from 'blessed-components/progress-bar';
+ *
+ * const output = renderProgressBar({
+ *   label: 'Quality',
+ *   value: 78,
+ *   width: 16,
+ * });
+ *
+ * // "Quality ████████████░░░░ 78%"
+ * ```
+ *
+ * @example ASCII output with a custom value
+ *
+ * ```ts
+ * const output = renderProgressBar({
+ *   characters: { filled: '#', empty: '-' },
+ *   formatValue: ({ value }) => `${value} files`,
+ *   label: 'Uploaded',
+ *   value: 25,
+ *   width: 8,
+ * });
+ *
+ * // "Uploaded ##------ 25 files"
+ * ```
+ */
+declare function renderProgressBar({ characters, formatValue, label, max, min, value, width, }: RenderProgressBarOptions): string;
+
+export { type ProgressBarCharacters, type ProgressBarValueContext, type RenderProgressBarOptions, renderProgressBar };

package/dist/progress-bar/index.js

@@ -0,0 +1,31 @@
+// 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}`;
+}
+
+export { renderProgressBar };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/components/progress-bar/index.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","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"]}

package/package.json

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