@linxiraos/pi-tui 1.1.26 → 1.2.0

package/src/charts/chart-svg.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Draws a {@link ChartSpec} as a standalone SVG document colored only with
+ * figure tokens — `var(--fg)`, `var(--muted)`, `var(--border)`,
+ * `var(--accent)`, `var(--surface)`, `var(--c1)`…`var(--c6)` — on a
+ * transparent background — the token vocabulary of assistant ```svg figures —
+ * so the host resolves them against the live theme (`prepareSvg`) for both
+ * the rasterized terminal image and the native TSP blob.
+ *
+ * Styled after Apple's charts and Tern's UI: a UI sans (Geist where Tern
+ * provides it), muted labels, hairline gridlines that recede behind the
+ * marks, bars and cells with rounded corners, smooth lines (over a soft area
+ * fill where the axis starts at zero), dot legends, one hue across small
+ * multiples' columns with gray for context. 13-unit labels land near the terminal's own glyph size
+ * at 16 user units per row; bolded table cells draw at full strength while
+ * their neighbours recede. Grouped categories ({@link ChartSpec.groups}) name
+ * each group once beside its members, the groups parted by a gap; a name too
+ * long for its column wraps to two lines ({@link categoryLabels}). A few
+ * outliers far above the rest break a bar axis instead of flattening it
+ * ({@link outlierTier}); reference rows ({@link ChartSpec.reference}) draw a
+ * dashed rule through their group.
+ *
+ * Every chart opens with a header ({@link drawHeader}): the semibold title a
+ * planner set ({@link ChartSpec.title}, the one fact worth stating; its key
+ * figure in the accent), a muted
+ * note on how the data is encoded, and the series key right-aligned on the
+ * title's line when it fits. Marks size to
+ * the row count ({@link barMetrics}); strong heat cells and share segments
+ * print their figures in a theme-adaptive dark {@link ink}. Reusable
+ * annotation primitives — {@link band}, {@link referenceRule},
+ * {@link callout} — draw the {@link ChartSpec.annotations} a planner lays on.
+ *
+ * Axes tick on round steps in one unit (`0, 2, 4` for counts, `50s, 100s`,
+ * `25 GiB` where the table wrote binary sizes, thousands separated). Meaning
+ * layers on top: each contest's best value carries a quiet `best` tag (an
+ * outline in a heatmap), estimates (`~15`) among measured figures draw as
+ * dashed, faint bars ({@link barRect}), moves of a measure with a polarity read in `success`
+ * or `error` (transitions, factors, signed deltas), and status cells badge
+ * their row's name with a colored dot keyed under the chart.
+ */
+import { type ChartSpec } from "./chart-plan";
+import { type Dimension } from "./table-data";
+/** A drawn chart: the SVG document and its size in user units. */
+export interface ChartSvg {
+    readonly svg: string;
+    readonly width: number;
+    readonly height: number;
+}
+/** The SVG document for `spec`. */
+export declare function renderChartSvg(spec: ChartSpec): ChartSvg;
+/** One-line description of the chart, for screen readers and terminals that show the alt text. */
+export declare function chartAlt(spec: ChartSpec): string;
+/**
+ * A value in base units as an axis label: durations and sizes in the unit,
+ * counts compacted under the suffix (`12k`, `3.4M`), that `magnitude` reads
+ * best in — the value's own size by default, an axis' largest tick to keep
+ * its labels in one unit. Sizes read in decimal units (`20 GB`), or binary
+ * ones (`16 GiB`) when `unit` is `iB`.
+ */
+export declare function formatValue(value: number, dim: Dimension, unit: string, magnitude?: number): string;