@fundar/data-chart-telling 1.18.0 → 1.20.0

package/dist/layout/styles/ValueLabels.d.ts

@@ -2,16 +2,22 @@ import { Box } from '../margins/Box';
 import { PlotAxes } from '../../phases/data/PlotAxes';
 import type { PlotRowContext } from '../../types/layout/context';
 import type { PlotStylesConfig } from '../../types/configuration/styling';
-import type { ValuesStyle } from '../../types/layout/styles';
+import type { ValuesFontStyle, ValuesStyle } from '../../types/layout/styles';
 import type { ValueLabelsOptions } from '../../types/phases/styles/phase';
 import type { Series } from '../../types/plots/data/common';
 import type { FontStyle, StrokeStyle } from '../../types/plots/styling';
-import type { LabelAnchor, TextAnchor, ValueAnchor } from '../../types/plots/constants';
 import type { BoxAnchors, EdgeBox } from '../../types/layout/box';
 import type { MarginSide } from '../../types/plots/props';
 import type { AxisPlotEnv, AxisPlotState, ProcessedData, ProcessedRow } from '../../types/phases';
 import type { TextMarkerConfig } from '../../types/markers/common';
-import type { TextLabelConfig } from '../../types/markers/basic/text';
+import type { LabelLayout, MarkerLabelConfig } from '../../types/markers/labels/common';
+import type { PointGeometryOf, PointLabelConfig, PointSide } from '../../types/markers/labels/point';
+/** One part of each row a plot labels, with where its label sits and how it writes it. */
+type ValuePart = {
+    name: string;
+    placement: Record<string, unknown>;
+    format: (value: number, row?: object, series?: string, part?: string) => string;
+};
 /**
  * A plot's value labels: the author's `styles.values` over the plot kind's
  * own defaults, how their text measures, where they are expected to sit
@@ -21,15 +27,24 @@ import type { TextLabelConfig } from '../../types/markers/basic/text';
 export declare class ValueLabels {
     #private;
     readonly show: boolean;
-    readonly anchor: ValueAnchor;
+    /** How the labels are laid out on their shapes: the author's `layout`, else the kind's. */
+    readonly layout: LabelLayout;
+    /** The options that place a label in its {@link layout}: the author's over the kind's own for it. */
+    readonly placement: Record<string, unknown>;
+    /** The parts of each row labelled - a simple plot's one `value`, a box's `median`... - each with its own options. */
+    readonly parts: ValuePart[];
+    /** The series whose rows are labelled, when `styles.values.series` names some; every series else. */
+    readonly series: string[] | undefined;
+    /** Whether the author gave the labels a text of their own, beyond the value. */
+    readonly formatted: boolean;
     /**
      * A label's text for `value`: the author's `format`, else the kind's, else the value as the display fields ask.
      * `row` is the row it labels, whose context the format reads; `series` names its series where there is no row
-     * (a label measured ahead of the rows).
+     * (a label measured ahead of the rows); `part`, which of the row's values it writes.
      */
-    readonly format: (value: number, row?: object, series?: string) => string;
+    readonly format: (value: number, row?: object, series?: string, part?: string) => string;
     readonly hoverIsolate: boolean;
-    readonly font: FontStyle | undefined;
+    readonly font: ValuesFontStyle | undefined;
     readonly fontSize: number;
     /** The connectors of labels that had to move apart. */
     readonly strokeStyle: StrokeStyle | undefined;
@@ -39,11 +54,45 @@ export declare class ValueLabels {
     readonly declutter: PlotStylesConfig['text']['declutter'];
     /** Where the labels are expected to sit: boxes around their points, on the edges those can reach. */
     readonly reach: EdgeBox[];
-    constructor(values: ValuesStyle | undefined, cfg: PlotStylesConfig, options?: Omit<ValueLabelsOptions<never>, 'reach'>, reach?: (labels: ValueLabels) => EdgeBox[]);
+    constructor(values: ValuesStyle | undefined, cfg: PlotStylesConfig, options?: Omit<ValueLabelsOptions<never>, 'reach' | 'layout' | 'layouts' | 'parts' | 'formatFor'> & {
+        layout?: LabelLayout;
+        layouts?: Partial<Record<LabelLayout, Record<string, unknown>>>;
+        parts?: {
+            placements: Record<string, Record<string, unknown>>;
+            default: string[];
+        };
+    }, reach?: (labels: ValueLabels) => EdgeBox[]);
+    /** Whether the part named `name` is labelled: a plot writing its `value` on its own shapes asks first. */
+    writes(name: string): boolean;
+    /** Whether the labels draw: `show` as set, else when any other option of them is set, else the kind's default. */
+    static shows(values: ValuesStyle | undefined, fallback?: boolean): boolean;
     /** The context a label's `format` reads: its row's, with `series` when the row gives none. */
     static contextOf(row: object | undefined, series?: string): PlotRowContext;
+    /**
+     * The value a label writes for `row`, read off its context: its `value`, or one `part` of it on a plot whose rows
+     * have several. `undefined` when it is not a number.
+     */
+    static valueIn(row: object | undefined, part?: string): number | undefined;
+    /** A label's text for `row`: its context's `part` (its `value` by default), as that part's format writes it. */
+    text(row: object, part?: string): string;
     /** A plot's value labels: `values` over `options`, the kind's own defaults, their reach read off `state`. */
     static build<TState>(values: ValuesStyle | undefined, cfg: PlotStylesConfig, options: ValueLabelsOptions<TState>, state: TState): ValueLabels;
+    /** Whether the labels sit past the tip of their shapes, where the plot's margins keep room for them. */
+    get pastTip(): boolean;
+    /**
+     * The `label` a plot kind's shapes write their value in, in this plot's {@link layout}: `text`, over what every
+     * label shares ({@link hooks}). Inside its shape a label takes no `fill` of its own, so it is written in the color
+     * that reads best on the shape; past it, the plot's `fill`.
+     */
+    label<TLabel extends MarkerLabelConfig = MarkerLabelConfig>(env: AxisPlotEnv, text: (row: ProcessedRow) => string, defaults?: {
+        fill?: string;
+        fontSize?: number;
+        fontWeight?: FontStyle['fontWeight'];
+        /** The rows `styles.values.select` picks: a `'point'` label writes only theirs. */
+        labelled?: readonly ProcessedRow[];
+        /** A row's series color, which `color: 'series'` writes a label off its shape in. */
+        seriesColor?: (row: ProcessedRow) => string | undefined;
+    }): TLabel;
     /** The configuration the labels were built under, for a plot kind's own label defaults. */
     get config(): PlotStylesConfig;
     /**
@@ -56,8 +105,8 @@ export declare class ValueLabels {
     get lineHeight(): number;
     /** The box one label's `text` takes. */
     textBox(text: string): Box;
-    /** The labels' gap (px) from their mark along `axis`: their own `dx`/`dy`, else `fallback`. */
-    offset(axis: 'x' | 'y', fallback?: number): number;
+    /** The labels' gap (px) from their mark: the layout's `gap`, else `fallback`. */
+    offset(fallback?: number): number;
     /**
      * Where a label reading `text` sits around its point: anchored `at` that
      * offset from it (its `dx`/`dy`), on `side` of that anchor per axis - the
@@ -76,48 +125,12 @@ export declare class ValueLabels {
         series: S;
         value: number;
     }[];
-    /**
-     * The author's own `textAnchor`, if any. `'outside'` is a hover marker's
-     * per-point anchor; a label's own `anchor` already places it, so here it
-     * counts as unset.
-     */
-    get textAnchor(): Exclude<TextAnchor, 'outside'> | undefined;
     /**
      * What every label marker shares: the plot's margins grow to fit it, it
      * dims with its row's series, and with `hoverIsolate`, hovering it
      * isolates that series. A row without a series gets the margins only.
      */
     hooks(env: AxisPlotEnv): Pick<TextMarkerConfig, 'fitMargins' | 'onpointerenter' | 'onpointerleave' | 'styles'>;
-    /**
-     * Where in a bar a label goes, from the `anchor` of `styles.values`: its `label` anchor, and whether it is beyond
-     * the bar. `negative` tells a bar that runs to the left (or down) from its base from one that runs right (or up),
-     * which `'tip'`, `'base'` and `'outside'` follow; the others are the edges of the page. A `stacked` bar's label is
-     * always in the middle. An anchor the shapes do not read (`'start'`, `'end'`) is taken for `'outside'`, the default.
-     */
-    static boxAnchor(anchor: ValueAnchor, shape: {
-        isHorizontal: boolean;
-        negative?: boolean;
-        stacked?: boolean;
-    }): {
-        anchor: LabelAnchor;
-        outside?: boolean;
-    };
-    /** Whether a label at `anchor` goes to one side or the other of a bar with the sign of its value. */
-    static followsSign(anchor: ValueAnchor): boolean;
-    /**
-     * The `label` the shapes of a plot kind write their value in: this plot's `styles.values` over the `defaults` the kind
-     * sets, with what every label shares ({@link hooks}) - its dimming and isolating of a series. A label inside its shape
-     * never reaches out of the plot, so only one `outside` has the margins grow to hold it; and it takes the default
-     * `fill` only `outside`, for inside it is written in the color that contrasts with its shape.
-     */
-    shapeLabel(env: AxisPlotEnv, text: (row: ProcessedRow) => string, defaults?: {
-        fill?: string;
-        fontSize?: number;
-        fontWeight?: FontStyle['fontWeight'];
-        anchor?: LabelAnchor;
-        outside?: boolean;
-        gap?: number;
-    }): TextLabelConfig;
     /**
      * A processed row's own value, read through its series' own value channel
      * (`y`, or `x` on a horizontal plot) - what a label shows, even where a
@@ -129,24 +142,61 @@ export declare class ValueLabels {
         axes?: PlotAxes;
     }): (d: ProcessedRow) => unknown;
     /**
-     * A series-over-`x` plot's (line, area) labels: one `'text'` marker over
-     * the processed rows, each visible series' last row with a value
-     * (`filter` + `selectLast`, per series), at its top (a stacked row's
-     * `y2`), labelled with its own value and placed by `anchor`. Labels that
-     * would overlap fan out into a shared column (`declutter`), colored by the
-     * segment the row falls in. A plot that labels each end of its series apart
-     * passes the `rows` and `anchor` of one end, and `lane` to route its labels
-     * out to a lane whether or not they overlap (`flip: false` keeps one on the
-     * left in the margin instead of flipping it over its points).
+     * A series-over-`x` plot's (line, area) labels, for its line or area markers: each labelled row (by default its
+     * series' last) with its own value, on the `side` of it its placement asks, colored by the segment it falls in.
+     * Labels that would overlap fan out into a shared column. A plot that labels each end of its series apart passes
+     * the `rows` and `side` of one end, and `lane` to route them out to a lane whether or not they overlap.
      */
-    atSeriesEnds<TData extends Record<string, unknown>>(state: AxisPlotState<TData, object>, end?: {
+    atSeriesEnds<TData extends Record<string, unknown>>(state: AxisPlotState<TData, object>, env: AxisPlotEnv, end?: {
         rows?: ProcessedRow[];
-        anchor?: ValueAnchor;
+        side?: PointSide;
         lane?: boolean | {
             elbowGap: number;
         };
         flip?: boolean;
+    }): PointLabelConfig[];
+    /**
+     * The labels of a plot whose rows have several values (a box's quartiles, a bullet's target): one `text` marker per
+     * part labelled, each of `rows` written at that part's value in its context - one label per value, for a part
+     * holding several (a box's outliers). `at` places a label at a value: its point, and the shape around it its
+     * `anchor` reads.
+     */
+    partMarkers(env: AxisPlotEnv, rows: readonly ProcessedRow[], at: (value: symbol) => PointGeometryOf, defaults?: {
+        seriesColor?: (row: ProcessedRow) => string | undefined;
+        /** The parts the kind writes on its own shapes, left out here: a bar's `value`. */
+        skip?: string[];
     }): TextMarkerConfig[];
+    /**
+     * Where a part label of a row sits on a plot of categories: at the row's `category` (a field or a function of
+     * it), level with the part's value, across the category's band - which an `anchor` reads, to write it beside.
+     */
+    static bandPoint(state: {
+        axes?: PlotAxes;
+    }, category: unknown, 
+    /** How wide the shape is across its band, in pixels, when it does not fill it: a violin's inner box. */
+    across?: number, 
+    /** A row's slot of its band, when its series share it side by side. */
+    slot?: (row: ProcessedRow) => {
+        index: number;
+        count: number;
+    } | undefined): (value: symbol) => PointGeometryOf;
+    /** The placement that writes each of `parts` beside its category's band: to its right, or above sideways bands. */
+    static besideBand(state: {
+        axes?: PlotAxes;
+    }, parts: string[]): Record<string, Record<string, unknown>>;
+    /** A series-over-`x` plot's labels in its {@link layout}: at its series' ends, or along its lines. */
+    forSeries<TData extends Record<string, unknown>>(state: AxisPlotState<TData, object>, env: AxisPlotEnv): MarkerLabelConfig[];
+    /** The side of its point a `'point'` label is written on: its placement's, else after it. */
+    get side(): PointSide;
+    /**
+     * A series-over-`x` plot's `'path'` labels, for its line or area markers: each series' name - or, with a `format`,
+     * the text it writes for the series' first row - along its line, colored by the series.
+     */
+    alongSeries<TData extends Record<string, unknown>>(state: AxisPlotState<TData, object>, env: AxisPlotEnv): MarkerLabelConfig[];
+    /** `markers` with `labels` on each one of `type`: the shapes of a series carry its labels. */
+    static onMarkers<T extends {
+        type: string;
+    }>(markers: T[], type: string, labels: MarkerLabelConfig[] | undefined): T[];
     /** How far (px) a lane takes the label of a series' first point from it - clear of the line that leaves it. */
     static readonly FIRST_LANE_GAP = 28;
     /** The rows of a series-over-`x` plot that cannot be labelled: a gap, or a stack with no top. For the "transforms" phase's `labels.skip`. */
@@ -163,5 +213,6 @@ export declare class ValueLabels {
      * domain when the scales set one, so it holds across a timeline; else off
      * every value.
      */
-    reachAtSeriesEnds<TData extends Record<string, unknown>>(state: AxisPlotState<TData, object>, anchor?: ValueAnchor): EdgeBox[];
+    reachAtSeriesEnds<TData extends Record<string, unknown>>(state: AxisPlotState<TData, object>, pointSide?: PointSide): EdgeBox[];
 }
+export {};