blessed-components 1.0.0 → 1.1.0

package/src/components/sparkline/README.md

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