@martinomagnifico/tablechart 1.2.6 → 1.4.0

package/dist/tablechart-shared.d.mts

@@ -38,14 +38,14 @@ interface Config {
   shape: "straight" | "step" | "smooth";
   /** Names of several lines in a legend instead of at the end of each line. A figure overrides it with `data-chart-legend`. */
   legend: boolean;
-  /** Numbers along the value axis of a column, bar, line, area or waterfall chart. A figure overrides it with `data-chart-axis`. */
-  axis: boolean;
+  /** Numbers along the value axis of a column, bar, line, area or waterfall chart; `"right"` puts them on the right of an upright chart. A figure overrides it with `data-chart-axis`. */
+  axis: boolean | "right";
   /** Gridlines across the plot at each number of the axis. A figure overrides it with `data-chart-grid`. */
   grid: boolean;
   /** The name of each marker beside it, on a scatter chart. A figure overrides it with `data-chart-names`. */
   names: boolean;
-  /** A tooltip with the values of a row that is pointed at or tapped: `"auto"`, the default, only on a chart that does not show all its numbers; `true` always; `false` never. A figure overrides it with `data-chart-tooltip`. */
-  tooltip: boolean | "auto";
+  /** A tooltip with the values of a row that is pointed at or tapped: `"auto"`, the default, only on a chart that does not show all its numbers; `true` always; `false` never. `"crosshair"`, on a line or area chart, shows a line through the row with its values at the side. A figure overrides it with `data-chart-tooltip`. */
+  tooltip: boolean | "auto" | "crosshair";
   /** Where the tooltip goes in the page: an element or a selector, `body` by default. In a scaled element, such as the slides of a presentation, the tooltip has their scale. */
   tooltipparent: HTMLElement | string | null;
   /** The table under the chart: `"always"`, only in `"print"`, in print when numbers are left out (`"auto"`), or `"never"`. A figure overrides it with `data-chart-table`. */
@@ -180,6 +180,10 @@ interface Geometry {
   rowAt?: (x: number, y: number) => number | null;
   /** Where the tooltip of a row points, in viewBox units, for a row whose mark may not be drawn, such as a point of a long line. */
   pointOf?: (index: number) => [number, number] | null;
+  /** The crosshair of a row, on a line or area chart. */
+  crossingOf?: (index: number) => Crossing | null;
+  /** The side of the numbers of the value axis; null without them. */
+  axisSide: "left" | "right" | null;
   /** A CSS length set on the figure, such as `--tablechart-marker-size`, in viewBox units. */
   length: (name: string, fallback: string) => number | null;
   barWidth: number;
@@ -269,6 +273,14 @@ interface ChartType {
   groups?: boolean;
   /** False: no numbers on the chart. They stay out of the layout, which costs a lot with many rows. */
   numbers?: false;
+  /** The scale fits the values without reaching zero, as for prices. */
+  floats?: boolean;
+  /** The value axis is shown unless the figure has `data-chart-axis="false"`. */
+  valueAxis?: boolean;
+  /** A tick above each name under the chart, as under a line. */
+  ticks?: boolean;
+  /** A crosshair with `tooltip: "crosshair"`; the drawing sets `crossingOf`. */
+  crosshair?: boolean;
   /** Text of its own, made with the rest of the text so a translation script finds it, such as a legend. */
   text?: (input: {
     figure: HTMLElement;
@@ -299,6 +311,31 @@ interface ChartType {
   /** Annotations that come with this type, such as `quadrant` with `scatter`; `addType` adds them. */
   annotations?: Record<string, AnnotationType>;
 }
+/** The crosshair of a row, in viewBox units: a line down at `x` from `from` to `to`, and a dot on each line where it crosses. */
+interface Crossing {
+  x: number;
+  from: number;
+  to: number;
+  /** Where the value labels go: at the value axis, or the left edge of the plot without one. */
+  edge: number;
+  /** Where a line across the plot ends: at the row farthest from the axis. */
+  end: number;
+  /** The side of the axis numbers that the value labels go over. */
+  axis: "left" | "right" | null;
+  height: number;
+  /** `colour` is the colour of the label, if not the colour of the line. */
+  points: {
+    series: number;
+    y: number;
+    dot: SVGElement;
+    colour?: string;
+  }[];
+  /** With it, the line across follows the pointer, with the value of the scale there; within `snap` pixels of a point, it goes through that point. */
+  textAt?: (y: number) => string;
+  snap?: number;
+  /** The top and bottom of a mark that the line down leaves free, such as a candle with its wick. */
+  around?: [number, number];
+}
 /** One line of a tooltip, under the name of the row. */
 interface TooltipLine {
   /** The name of the series; empty for a chart with one series. */
@@ -323,6 +360,8 @@ interface HeadroomInput {
   series: number;
   focused: boolean;
   stacked: boolean;
+  /** False with `data-chart-values="none"` and no row with `data-value="show"`: a line then needs no room for numbers. */
+  numbers: boolean;
 }
 /** `create` runs before layout, so a translation script finds its text; `draw` only places it. */
 interface AnnotationType {
@@ -330,6 +369,22 @@ interface AnnotationType {
   draw: (spec: HTMLElement, badge: HTMLElement | null, geo: Geometry) => void;
 }
 interface ChartState {
+  /** What the chart needs by itself, for a group that shares a scale; null for a chart that cannot share one. */
+  measured?: {
+    height: number;
+    room: number;
+    floor: number;
+    ceiling: number;
+    bottom: number;
+  } | null;
+  /** What its group with `data-chart-group-scale` agreed on. */
+  agreed?: {
+    height: number;
+    room: number;
+    floor: number;
+    ceiling: number;
+    bottom: number;
+  };
   figure: HTMLElement;
   plot: HTMLElement;
   svg: SVGSVGElement;
@@ -347,6 +402,7 @@ interface ChartState {
     titles: HTMLElement[];
     ticks: HTMLElement;
     numbers: boolean;
+    right: boolean;
   } | null;
   stacked: boolean;
   totals: HTMLElement[];
@@ -357,6 +413,12 @@ interface ChartState {
   rowBox: ((index: number) => [number, number, number, number]) | null;
   /** Where the tooltip of a row points, in viewBox units; set by a chart such as a line. */
   pointOf: ((index: number) => [number, number] | null) | null;
+  /** The crosshair of a row, on a line or area chart. */
+  crossingOf: ((index: number) => Crossing | null) | null;
+  /** The crosshair, once it is attached, so a new layout can take it away. */
+  crosshair: {
+    hide: () => void;
+  } | null;
   annotations: {
     spec: HTMLElement;
     type: AnnotationType;
@@ -373,18 +435,20 @@ interface ChartState {
   controls: HTMLElement | null;
   checks: Check[];
 }
+/** One candle per row: a body from open to close, and a wick from low to high. A rising candle is hollow, a falling one filled. */
+declare const candlestick: ChartType;
 /** One marker per row, across by its first value and up by its second; a third value makes it a bubble. */
 declare const scatter: ChartType;
 /** Adds a chart type for `data-chart="name"`, such as one from `@martinomagnifico/tablechart/additional-types`, before `init()`. */
 declare const addType: (name: string, type: ChartType) => void;
 /** Pass 2: everything a reader will read, before a translation script looks. */
 declare const build: (figure: HTMLElement, config: Config, asKind?: string | null) => ChartState | null;
-/** Pass 3. Needs layout; makes no text, only places it. */
-declare const layout: (state: ChartState, config: Config) => boolean;
 /** Numbers are reformatted in place, so a language change costs no redraw. */
 declare const relabel: (state: ChartState, config: Config) => void;
 /** Removes what `build` added, so the chart can be built again. */
 declare const unbuild: (state: ChartState) => void;
+/** Pass 3. Needs layout; makes no text, only places it. */
+declare const layout: (state: ChartState, config: Config) => boolean;
 /**
  * One class, `is-shown`, starts the whole build. `atOnce` skips it: the chart lands at its end, or back at its start,
  * without transitions, such as a chart in view when the page opens, or one hidden where nobody sees it.
@@ -402,6 +466,10 @@ interface TablechartChart {
   previous(): void;
   /** On a chart that steps: shows the chart up to `step`, from 0 to `steps`. */
   stepTo(step: number): void;
+  /** Builds the chart again, with its animation. A chart with steps goes back to its first step. */
+  replay(): void;
+  /** Takes the chart back to its start, to build when it scrolls into view. */
+  reset(): void;
   /** How many steps are shown. */
   readonly step: number;
   /** How many steps the chart has; 0 for a chart that does not step. */
@@ -425,8 +493,7 @@ declare const entranceOf: (figure: HTMLElement, config: Config) => number;
 declare const prepare: (found: HTMLElement[], config: Config) => Promise<HTMLElement[]>;
 /** Makes a chart of one figure; returns the existing chart if there is one, or null without data. */
 declare const create: (element: HTMLElement, options?: Partial<Config>) => Promise<TablechartChart | null>;
-/** Makes a chart of every figure in `root` that matches the selector, skipping existing charts. */
-declare const init: (options?: Partial<Config>, root?: ParentNode) => Promise<TablechartInstance>;
+declare const init$1: (options?: Partial<Config>, root?: ParentNode) => Promise<TablechartInstance>;
 /** A Markdown table, or a caption with chart attributes, is wrapped in a figure with the caption and annotations beside it. */
 declare const adoptTables: (figures: HTMLElement[]) => HTMLElement[];
 /** `data-chart-src` fills the figure's table with the rows of a JSON file, keeping a header row the author wrote; a file that fails is reported. */
@@ -439,4 +506,36 @@ declare const assignKeys: (figures: HTMLElement[], langattribute: string | false
 declare const checkContrast: (figure: HTMLElement) => void;
 /** Warns about text that does not stand out enough: a number inside a bar from that bar, other text from the background, once the chart is built. */
 declare const checkTextContrast: (figure: HTMLElement) => void;
-export { PRINTING_CLASS as A, Series as C, Config as D, AT_ONCE_CLASS as E, SHOWN_CLASS as M, defaultConfig as N, PLACED_CLASS as O, Row as S, stepTo as T, setShown as _, loadSources as a, ChartState as b, TablechartInstance as c, init as d, prepare as f, relabel as g, layout as h, adoptTables as i, QUEUED_CLASS as j, PLOT_CLASS as k, create as l, build as m, checkTextContrast as n, readMarkdownRows as o, addType as p, assignKeys as r, TablechartChart as s, checkContrast as t, entranceOf as u, unbuild as v, StepPlan as w, ChartType as x, scatter as y };
+/** The words that `{trend}`, `{change}` and `{side}` become. */
+interface SummaryWords {
+  up: string;
+  down: string;
+  flat: string;
+  unclear: string;
+  above: string;
+  below: string;
+}
+interface SummaryConfig {
+  /** The charts that may have a summary. */
+  selector: string;
+  /** Around a placeholder, such as `{highest.value}`. A template engine that uses single braces needs others, such as `["[[", "]]"]`. */
+  delimiters: [string, string];
+  /** The attribute for translation keys, as in Tablechart. A name in a sentence keeps its key. */
+  langattribute: string | false;
+  /** Locale for numbers and lists. Unset, the language of the page is used and followed when it changes. */
+  locale?: string;
+  /** A trend or a change of less than this percentage is flat. */
+  flat: number;
+  /** A value more than this percentage away from the trend is an outlier. */
+  outliers: number;
+  /** For `{trend}`, `{change}` and `{side}`. A sentence per outcome, with `data-when`, translates better. */
+  words: SummaryWords;
+  /** The number of groups of rows in `groups`, for an overview of a long table. */
+  groups: number;
+}
+declare const summaryDefaults: SummaryConfig;
+/** Fills the sentences of one chart again, from its table as it is now. */
+declare const fill: (figure: HTMLElement, options?: Partial<SummaryConfig>) => void;
+/** Fills the summary of every chart now, again when its table is ready or changes, and when a translation changes a sentence or the language. */
+declare const init: (options?: Partial<SummaryConfig>) => void;
+export { StepPlan as A, addType as C, ChartType as D, ChartState as E, PLOT_CLASS as F, PRINTING_CLASS as I, QUEUED_CLASS as L, AT_ONCE_CLASS as M, Config as N, Row as O, PLACED_CLASS as P, SHOWN_CLASS as R, unbuild as S, candlestick as T, prepare as _, summaryDefaults as a, build as b, assignKeys as c, readMarkdownRows as d, TablechartChart as f, init$1 as g, entranceOf as h, SummaryWords as i, stepTo as j, Series as k, adoptTables as l, create as m, fill as n, checkContrast as o, TablechartInstance as p, SummaryConfig as r, checkTextContrast as s, init as t, loadSources as u, setShown as v, scatter as w, relabel as x, layout as y, defaultConfig as z };