@sophistry/charts 0.0.0-stage → 0.1.0

package/dist/series.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Shared by marks with a `series` channel: reading it, grouping data by it,
+ * the colour-scale and legend report, and per-datum keys. Colours come from
+ * the enclosing chart's scale (or the layer's own) unless an explicit colour
+ * prop overrides it; an overridden layer adds nothing to the legend.
+ * Internal.
+ */
+import type { BandKey } from "@sophistry/core/geometry";
+import type { ChartLayer } from "./context.js";
+import type { Channel, DateSink } from "./data/channels.js";
+import type { ColorExtent, LegendMark } from "./frame/types.js";
+import type { OrdinalColorScale } from "./math/ordinal.js";
+/** The one group of a grouped mark drawn without a `series`. */
+export declare const WHOLE: unique symbol;
+/** A group of a grouped mark: a category, or {@link WHOLE}. */
+export type GroupKey = BandKey | typeof WHOLE;
+/** A datum's category, as read: nullish when the channel gives none. */
+export type Category = BandKey | null | undefined;
+/** One update's view of a layer's `series`. See {@link createSeries}. */
+export interface SeriesState {
+    /** Each datum's category, or undefined without a `series`. */
+    of: Category[] | undefined;
+    /** The categories, in first-seen order (empty without a `series`). */
+    categories: readonly BandKey[];
+    /** True when colours come from the scale: a `series`, and no override. */
+    scaled: boolean;
+    /** The layer's `color` report, or undefined when not scaled. */
+    extent: ColorExtent | undefined;
+    /** The scale (the frame's inside a chart, else the layer's own). */
+    scale: OrdinalColorScale;
+    /** A category's colour, or undefined when not scaled. */
+    colorOf(category: Category): string | undefined;
+}
+/** What {@link createSeries}'s function takes on each update. */
+export interface SeriesSpec<T> {
+    data: readonly T[];
+    series: Channel<T, BandKey> | undefined;
+    /** An explicit colour prop is set: the scale (and legend) step aside. */
+    overridden: boolean;
+    mark: LegendMark;
+    /** Only these indices count towards the categories. */
+    counted?: readonly number[] | undefined;
+    dates?: DateSink | null;
+}
+/**
+ * Reads a layer's `series` channel and its colour scale. Call once, in
+ * `setup`; call the result in each `update`. Caches the per-datum read by
+ * `data` and channel identity, and the categories by value.
+ */
+export declare function createSeries<T>(layer: ChartLayer): (spec: SeriesSpec<T>) => SeriesState;
+/**
+ * The indices of each group, in first-seen order: one {@link WHOLE} group of
+ * every index without a `series`, else one per category (nullish and NaN
+ * categories dropped).
+ */
+export declare function groupIndices(count: number, of: readonly Category[] | undefined): Map<GroupKey, number[]>;
+/**
+ * Each datum's key: the `key` channel, else its place within its series,
+ * else its index.
+ */
+export declare function datumKeysOf<T>(data: readonly T[], key: Channel<T, BandKey> | undefined, of: readonly Category[] | undefined, dates?: DateSink | null): BandKey[];
+/**
+ * Dodge slots for a `series`: each category's slot in the colour scale's
+ * order (categories the scale lacks go last).
+ */
+export declare function dodgeSlotsFor(of: readonly Category[], categories: readonly BandKey[], scale: OrdinalColorScale): {
+    count: number;
+    of: (index: number) => number | undefined;
+};
+/** Each key's position in `keys`. */
+export declare function slotsOf(keys: readonly BandKey[]): Map<BandKey, number>;