@seekalfred/primitives 0.6.0 → 0.7.3

package/dist/line-chart/line-chart.d.ts

@@ -0,0 +1,116 @@
+//#region src/line-chart/line-chart.d.ts
+/**
+ * LineChart: one or more measures over time, when the shape of the trend
+ * matters more than any single value.
+ *
+ * The lines draw left to right the first time the chart is seen. New data
+ * morphs every line from the shape on screen, and the value axis slides to its
+ * new range while gridlines fade in and out. Hiding a series flattens it into
+ * the baseline as it fades and the rest rescale. Hover, drag or the arrow keys
+ * scrub: a crosshair glides between points with a dot on each line and a
+ * tooltip that follows on its own spring and flips before it leaves the plot.
+ * `loading` keeps the current lines on screen, dimmed and breathing.
+ *
+ * Plain SVG and CSS; one small spring tween drives the shapes, the scale and
+ * the crosshair. A visually hidden table carries every value for assistive
+ * technology, and the plot itself is a slider.
+ */
+export interface LineChartSeries {
+  /** Stable identity. A series keeps its line across data changes, so switching ranges morphs it. */
+  key: string;
+  /** Name in the legend, the tooltip and the data table. */
+  label: string;
+  /** Any CSS colour. Defaults to chart-1 for the first series, then quieter neutral steps. */
+  color?: string;
+  /** A dashed stroke, for a previous period or a target. */
+  dashed?: boolean;
+  /** A faint fill under the line. Defaults to true for the first series. */
+  area?: boolean;
+}
+export interface LineChartDatum {
+  /** Stable identity, such as an ISO date. */
+  key: string;
+  /** Full label for the tooltip and screen readers, such as "Tue, Sep 15". */
+  label: string;
+  /** Short label on the x axis. Leave it out to keep the axis quiet at that point. */
+  axisLabel?: string;
+  /**
+   * One value per series key. A missing value (`undefined` or `null`) counts as
+   * zero, unless the chart's `missing` is `"gap"`.
+   */
+  values: Record<string, number | null | undefined>;
+}
+/**
+ * A reference line: a horizontal line at a value (a target, a threshold), or a
+ * vertical line at one datum (today, a launch). Drawn dashed and quiet, behind
+ * the series, with its label at the line's end.
+ */
+export type LineChartReference = {
+  /** Stable identity. */
+  key: string;
+  /** Short text beside the line, such as "Target" or "Today". Also read to screen readers. */
+  label: string;
+} & ({
+  /**
+   * A value on the value axis: a horizontal line. The scale grows to keep it
+   * in view, even when every value is missing. A value that is not finite
+   * draws nothing. Read with `formatValue` (given the chart's first series)
+   * and `unit`, like the series.
+   */
+  value: number;
+  at?: never;
+} | {
+  /** The `key` of a datum: a vertical line at that point. A key not in `data` draws nothing. */
+  at: string;
+  value?: never;
+});
+export interface LineChartProps {
+  data: LineChartDatum[];
+  series: LineChartSeries[];
+  /** What is measured, such as "Signups". Names the chart for assistive technology. */
+  label: string;
+  /** Unit after each value in the tooltip, such as "ms". */
+  unit?: string;
+  /** Plot height in pixels. The width follows the container. @default 220 */
+  height?: number;
+  /** Formats values in the tooltip and data table. */
+  formatValue?: (value: number, series: LineChartSeries) => string;
+  /** Formats the value axis. Defaults to a compact number, such as 1.2K. */
+  formatTick?: (value: number) => string;
+  /** Controlled hidden series keys. */
+  hiddenSeries?: string[];
+  defaultHiddenSeries?: string[];
+  onHiddenSeriesChange?: (hidden: string[]) => void;
+  /** Called as the crosshair moves, and with null when it leaves. */
+  onActiveChange?: (index: number | null, datum: LineChartDatum | null) => void;
+  /** Keeps the current lines on screen, dimmed, while the next range loads. */
+  loading?: boolean;
+  /** Shown when there are no points. @default "No data for this range" */
+  emptyLabel?: string;
+  /** Series toggles above the plot. Shown by default when there is more than one series. */
+  legend?: boolean;
+  /** Header of the first column in the data table read by screen readers. @default "Date" */
+  categoryLabel?: string;
+  /** Smooth monotone curves that never swing past the data, or straight segments. @default "smooth" */
+  curve?: "smooth" | "linear";
+  /**
+   * How a missing value (`undefined`, `null` or not a finite number) is drawn.
+   * `"zero"` counts it as zero, as before. `"gap"` breaks the line (and its
+   * area) there, leaves it out of the scale, hides the crosshair dot on it and
+   * reads it as `missingLabel` in the tooltip and the data table. A point with
+   * missing neighbours on both sides is drawn as a dot.
+   * @default "zero"
+   */
+  missing?: "zero" | "gap";
+  /** Read in place of a missing value when `missing` is `"gap"`. @default "No data" */
+  missingLabel?: string;
+  /** Reference lines: targets at a value, or markers such as "today" at a datum. */
+  references?: LineChartReference[];
+  /** Extra classes for the root. Merged last. */
+  className?: string;
+}
+/** The first draw: 480ms x 1.75, slow at both ends. */
+export declare const LINE_CHART_DRAW_MS = 840;
+export declare const LineChart: import("react").ForwardRefExoticComponent<LineChartProps & import("react").RefAttributes<HTMLElement>>;
+//#endregion
+//# sourceMappingURL=line-chart.d.ts.map