@object-ui/core 17.5.0 → 17.6.0

package/dist/utils/chart-presentation.js

@@ -0,0 +1,280 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+const isRecord = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
+/**
+ * An i18n label is a plain string or a `{ en, zh-CN, … }` record; charts render
+ * a string. Same pick `normalizeChartSchema` makes, so a label reads the same
+ * on both paths.
+ *
+ * **First-string-wins, deliberately, and deliberately NOT locale-aware** — this
+ * package is React-free and holds no i18n provider, so it cannot know which
+ * limb a console wants. A caller that CAN resolve the language (the report
+ * renderer, via `pickLocalized`) resolves the label itself and overrides the
+ * merged one; see objectui#4020, whose whole point is that picking the first
+ * limb paints English on a zh console.
+ */
+function labelText(v) {
+    if (typeof v === 'string' && v)
+        return v;
+    if (isRecord(v)) {
+        const first = Object.values(v).find((x) => typeof x === 'string' && x);
+        return first;
+    }
+    return undefined;
+}
+/**
+ * One authored `ChartSeries`, minus its `name` — i.e. everything about it that
+ * is presentation rather than membership.
+ *
+ * `type` is narrowed to the three families that COMPOSE on one cartesian plot,
+ * because this array reaches the renderer already speaking the internal shape
+ * (`ChartRenderer` forwards a `dataKey`-shaped array untouched, so
+ * `normalizeChartSchema`'s own identical narrowing never sees it). Without the
+ * narrowing a `type: 'pie'` would not merely be inert — it would count as a
+ * family disagreement in `effectiveChartFamily`, flip the whole chart into a
+ * combo, and then draw that series as a bar anyway.
+ */
+export function seriesPresentation(raw) {
+    const out = {};
+    const family = raw.type;
+    if (family === 'bar' || family === 'line' || family === 'area')
+        out.chartType = family;
+    if (raw.yAxis === 'left' || raw.yAxis === 'right')
+        out.yAxis = raw.yAxis;
+    const label = labelText(raw.label);
+    if (label)
+        out.label = label;
+    if (typeof raw.color === 'string' && raw.color)
+        out.color = raw.color;
+    if (typeof raw.stack === 'string' && raw.stack)
+        out.stack = raw.stack;
+    if (raw.variant === 'primary' || raw.variant === 'comparison')
+        out.variant = raw.variant;
+    if (typeof raw.dashArray === 'string' && raw.dashArray)
+        out.dashArray = raw.dashArray;
+    if (typeof raw.opacity === 'number' && Number.isFinite(raw.opacity))
+        out.opacity = raw.opacity;
+    return out;
+}
+/**
+ * One authored `ChartAxis`, minus its `field` — the axis's presentation.
+ *
+ * `field` is the one DATA key on an axis (it names the plotted column), and
+ * dropping it here is what keeps membership with the dataset **structurally**
+ * rather than by a guard: `normalizeChartSchema` synthesises series out of
+ * `yAxis[].field` when a chart declares no series, so a forwarded `field`
+ * would be a live membership channel on an empty selection. With it gone the
+ * axis carries scale and chrome only, and the count of entries — which is what
+ * turns on the secondary axis (`yAxes.length > 1`) — survives, including for
+ * an entry that declares nothing but its own existence.
+ *
+ * Keys the renderer does not read on a given axis are dropped by
+ * `normalizeChartSchema`, the ONE normalization layer (#2880 S1): today it
+ * keeps `format`/`title`/`showGridLines` on the x-axis and the full set on the
+ * y-axes. That narrowing is deliberately NOT mirrored here — a second copy
+ * would drift from the renderer's real capability the moment it grew.
+ */
+export function axisPresentation(raw) {
+    const out = {};
+    if (!isRecord(raw))
+        return out;
+    const title = labelText(raw.title);
+    if (title)
+        out.title = title;
+    if (typeof raw.format === 'string' && raw.format)
+        out.format = raw.format;
+    if (typeof raw.min === 'number' && Number.isFinite(raw.min))
+        out.min = raw.min;
+    if (typeof raw.max === 'number' && Number.isFinite(raw.max))
+        out.max = raw.max;
+    if (typeof raw.stepSize === 'number' && Number.isFinite(raw.stepSize) && raw.stepSize > 0) {
+        out.stepSize = raw.stepSize;
+    }
+    if (typeof raw.showGridLines === 'boolean')
+        out.showGridLines = raw.showGridLines;
+    if (raw.position === 'left' || raw.position === 'right' || raw.position === 'top' || raw.position === 'bottom') {
+        out.position = raw.position;
+    }
+    if (typeof raw.logarithmic === 'boolean')
+        out.logarithmic = raw.logarithmic;
+    return out;
+}
+/**
+ * Merge an authored `series[]` array's PRESENTATION onto the bindings the
+ * dataset selection derived — the series half of #4229's split, and the whole
+ * of it for a surface whose axes are names rather than objects (see the file
+ * header).
+ *
+ * The match rule is **by name/key**: an authored `series[].name` is paired with
+ * the derived binding whose `dataKey` it equals, and the pairing decides
+ * nothing but presentation:
+ *
+ *  - an authored entry naming a measure that is NOT in the dataset selection is
+ *    **ignored** — membership belongs to the dataset, so an author cannot add,
+ *    remove or re-point a series from the chart config;
+ *  - a derived series with no authored entry keeps the family default, so every
+ *    surface that never wrote `series` renders byte-for-byte as before;
+ *  - where both exist the **explicit binding wins** (#2880 S2), which is the
+ *    whole point: `type: 'line'` + `yAxis: 'right'` is how the spec says "this
+ *    measure is a line on the secondary axis".
+ *
+ * Matching on `name` only is deliberate: `name` is the spec's authorable key
+ * for a series (`dataKey` is a declared ALIAS of it, resolved where the
+ * metadata is parsed), so reading a second spelling here would fossilize a
+ * dialect this renderer has no business accepting (AGENTS.md #0.1).
+ *
+ * The FIRST entry naming a measure wins; a later duplicate cannot silently
+ * reconfigure a series the author already described.
+ *
+ * @param derived the bindings {@link buildChartSeries} produced from the selection
+ * @param authoredSeries the authored `series` array (anything, incl. absent)
+ */
+export function mergeAuthoredSeries(derived, authoredSeries) {
+    const authored = new Map();
+    for (const entry of Array.isArray(authoredSeries) ? authoredSeries : []) {
+        if (!isRecord(entry))
+            continue;
+        const name = typeof entry.name === 'string' ? entry.name : undefined;
+        if (name && !authored.has(name))
+            authored.set(name, entry);
+    }
+    return derived.map((s) => {
+        const entry = authored.get(s.dataKey);
+        return entry ? { ...s, ...seriesPresentation(entry) } : s;
+    });
+}
+/**
+ * Merge an authored chart config's PRESENTATION onto the series and axes the
+ * dataset selection derived — the one place that happens for a surface whose
+ * axes are spec `ChartAxis` OBJECTS (#4229).
+ *
+ * The series half is {@link mergeAuthoredSeries}; see it for the match rule and
+ * for why membership is safe. The axes half reads `xAxis` / `yAxis` through
+ * {@link axisPresentation}, which is why a surface spelling those as bare NAME
+ * strings must call `mergeAuthoredSeries` directly instead (file header).
+ *
+ * @param derived the bindings {@link buildChartSeries} produced from the selection
+ * @param raw the authored chart config (anything, incl. absent)
+ * @returns the merged series, plus the presentation-only axes to spread onto
+ *   the chart schema (absent when the author declared none)
+ */
+export function mergeAuthoredPresentation(derived, raw) {
+    const config = isRecord(raw) ? raw : {};
+    const series = mergeAuthoredSeries(derived, config.series);
+    const axes = {};
+    const xAxis = axisPresentation(config.xAxis);
+    if (Object.keys(xAxis).length > 0)
+        axes.xAxis = xAxis;
+    // The COUNT of y-axis entries is itself presentation — it is what declares a
+    // secondary axis — so every declared entry keeps its slot even when it
+    // carries nothing but `field` (which is data and does not travel).
+    const yAxisRaw = Array.isArray(config.yAxis)
+        ? config.yAxis
+        : config.yAxis !== undefined
+            ? [config.yAxis]
+            : [];
+    if (yAxisRaw.length > 0)
+        axes.yAxis = yAxisRaw.map(axisPresentation);
+    return { series, axes };
+}
+/**
+ * Lower an authored chart config's CHROME (spec `ChartConfigSchema` /
+ * `ReportChartSchema` — the same keys on both) onto the chart schema a
+ * dataset-bound surface hands the renderer.
+ *
+ * ## Why this is a whitelist and not a spread
+ *
+ * Until #3135 NONE of a dashboard widget's `chartConfig` reached the renderer:
+ * the widget read `options` and nothing else, so an author who wrote
+ * `showLegend: false` still got a legend and one who wrote `true` only got one
+ * because "on" is the renderer's default. #3135 lowered that single flag and
+ * left the rest declared and inert. objectstack#7016 lowered the rest of the
+ * keys that are actually DELIVERED, admitting a key only when both of these
+ * hold:
+ *
+ *  1. **The chart block draws it end to end.** `{ type: 'chart' }` resolves to
+ *     `ChartRenderer` → `AdvancedChartImpl`, which draws `title`/`subtitle` in
+ *     its ChartFrame, turns `description` into the chart container's
+ *     `role="img"` + `aria-label`, applies `height` as that container's inline
+ *     height, reads `colors` as the positional palette, prints
+ *     `showDataLabels` as a Recharts `LabelList`, draws `annotations` as
+ *     ReferenceLine/ReferenceArea and honours `interaction` as the tooltip
+ *     toggle plus `Brush`. Forwarding a key the renderer ignores would only
+ *     move declared-but-not-delivered one layer down, which is the failure this
+ *     exists to remove.
+ *  2. **It does not fight the dataset derivation.** `type` stays out: the
+ *     calling surface's own type already picks the chart family, which is the
+ *     dataset path's chart-family channel.
+ *
+ * `aria` is the one declared key with **no reader at all**: `AdvancedChartImpl`
+ * has no `aria` prop, and `SchemaRenderer`'s ARIA injection reads the FLAT
+ * `ariaLabel`/`ariaDescribedBy`/`role`, never a nested `aria` object. It is
+ * therefore left unforwarded on purpose (criterion 1) rather than papered over
+ * with a caller-side flattening that would also collide with the accessible
+ * name `description` already sets — reported back to objectstack#5175's
+ * narrowing half instead.
+ *
+ * `title` IS emitted here. A caller that paints the title itself (the report
+ * renderer's own `h3` above the chart) must drop it from the result, or the
+ * chart draws a second one.
+ *
+ * @param raw the authored chart config (anything, incl. absent)
+ * @param fieldCategoryColors per-category colours resolved from the category
+ *   dimension's own select/lookup option colours, merged UNDER an explicit
+ *   author map (see the `colors` note below)
+ * @returns only the keys that resolved, so the caller can spread it over the
+ *   derived chart schema and every undeclared key keeps the renderer's default
+ */
+export function chartConfigPresentation(raw, fieldCategoryColors) {
+    const config = isRecord(raw) ? raw : {};
+    const out = {};
+    const text = (v) => (typeof v === 'string' && v ? v : undefined);
+    if (typeof config.showLegend === 'boolean')
+        out.showLegend = config.showLegend;
+    if (typeof config.showDataLabels === 'boolean')
+        out.showDataLabels = config.showDataLabels;
+    const title = text(config.title);
+    if (title)
+        out.title = title;
+    const subtitle = text(config.subtitle);
+    if (subtitle)
+        out.subtitle = subtitle;
+    const description = text(config.description);
+    if (description)
+        out.description = description;
+    // A non-positive height would collapse the plot; the container default is the
+    // more honest answer than an invisible chart.
+    if (typeof config.height === 'number' && Number.isFinite(config.height) && config.height > 0) {
+        out.height = config.height;
+    }
+    if (Array.isArray(config.annotations) && config.annotations.length > 0)
+        out.annotations = config.annotations;
+    if (config.interaction && typeof config.interaction === 'object' && !Array.isArray(config.interaction)) {
+        out.interaction = config.interaction;
+    }
+    // `colors` is overloaded kanban-style — and the two arms reach the renderer
+    // through two DIFFERENT props, so the split has to happen here (the react
+    // tier's ObjectChart splits it the same way): a `string[]` is the positional
+    // palette (`colors`), a `{ value: color }` record is an explicit per-category
+    // map (`categoryColors`). The author's map is merged OVER the dimension
+    // field's own option colours, which is the precedence the spec field comment
+    // states ("a value→color map — and a select/lookup dimension's option colors
+    // — take precedence over the positional palette per category").
+    const palette = Array.isArray(config.colors)
+        ? config.colors.filter((c) => typeof c === 'string' && !!c)
+        : undefined;
+    if (palette?.length)
+        out.colors = palette;
+    const authorCategoryColors = config.colors && typeof config.colors === 'object' && !Array.isArray(config.colors)
+        ? config.colors
+        : undefined;
+    if (fieldCategoryColors || authorCategoryColors) {
+        out.categoryColors = { ...(fieldCategoryColors ?? {}), ...(authorCategoryColors ?? {}) };
+    }
+    return out;
+}

package/dist/utils/chart-series.d.ts

@@ -5,27 +5,6 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-/**
- * chart-series — shape a semantic-layer `queryDataset` result into the
- * `{ data, xAxisKey, series }` triple a chart renderer consumes (ADR-0021, #1759).
- *
- * Shared by `ObjectChart` (plugin-charts) and `DatasetWidget` (plugin-dashboard)
- * so multi-dimension charts visualise identically across surfaces.
- *
- * Rules:
- *  - **2+ dimensions, single measure** → pivot the SECOND dimension into one
- *    series per distinct value (grouped/coloured bars). `xAxisKey` = first
- *    dimension; each output row is one first-dimension bucket with a column per
- *    second-dimension value holding the measure. This makes the second dimension
- *    visible instead of just repeating the x-axis label.
- *  - **otherwise** (single dimension, or multiple measures) → first dimension is
- *    the x-axis and each measure is its own series (long format passes through).
- *
- * BOTH branches map a NULL first-dimension VALUE to an explicit bucket label
- * ({@link NULL_CATEGORY_LABEL}) so the group renders instead of vanishing —
- * objectui#4466 for the single-dimension branch, objectui#4497 for the pivot.
- * One doctrine, one predicate (`isNullCategory`), two call sites.
- */
 export interface ChartResultField {
     name: string;
     label?: string;
@@ -69,6 +48,57 @@ export interface ChartSeriesResult {
  * clicked bucket bar resolve back to its (raw null) dataset row.
  */
 export declare const NULL_CATEGORY_LABEL = "(None)";
+/**
+ * The IDENTITY of the chart bucket a first-dimension raw value falls in —
+ * distinct from the string that bucket DISPLAYS (objectui#4508).
+ *
+ * Deliberately the SAME encoder the pivot TABLE already keys its buckets with
+ * (`pivotBucketId` over a `pivotDimensionValue`-normalized value), because the
+ * two surfaces answer the same question about the same dataset rows and were
+ * answering it differently: `buildPivot` gives a null dimension value a bucket
+ * id no string can spell, while the chart used the display label as its own
+ * key. That gap is the whole of objectui#4508 — see `dataset-pivot.ts` for why
+ * the encoding is JSON rather than a delimiter or a placeholder character.
+ *
+ * Two collisions follow from a label-as-key, and one encoder closes both:
+ *  - `null` and `''` are different groups. `String(x ?? '')` made them one
+ *    bucket, so two groups drew ONE bar and one of them lost its drill.
+ *    `[null]` and `[""]` are different ids.
+ *  - a stored value that literally spells the bucket label (`'(None)'`, or any
+ *    localized `nullCategoryLabel` — `'(未指定)'` and the other nine packs) is
+ *    not the null group. `["(None)"]` and `[null]` are different ids, so the
+ *    click resolves to the rows its own bar was drawn from.
+ */
+export declare function chartBucketId(rawValue: unknown): string;
+/**
+ * The key an emitted chart row carries its {@link chartBucketId} under, when it
+ * carries one — the "alongside the display label" half of objectui#4508.
+ *
+ * **Written exactly when the display string does not name one bucket**, i.e.
+ * when two or more DISTINCT buckets render the same axis text. That is not a
+ * cost-saving heuristic, it is the complete condition: with the reader's
+ * matching made exact (see {@link findChartSeriesRow}), a display string that
+ * one bucket alone produces already identifies it, and the rows a chart is
+ * drawn from are also an authoring-visible surface (`data` on a `chart`
+ * schema) that renderer-internal metadata should not appear in for every
+ * ordinary chart. Rows that do not carry the category key at all never get one
+ * — they have no bucket, and that shape belongs to `hasNoCategoryKey`
+ * (framework#4033), not here.
+ *
+ * Read it with {@link chartRowBucketId} rather than the literal key.
+ */
+export declare const CHART_BUCKET_ID_KEY = "__bucketId";
+/**
+ * Read the bucket identity off a row a chart was drawn from, or `undefined`
+ * when the row carries none (an unambiguous bucket, or rows a caller built
+ * itself rather than through {@link buildChartSeries}).
+ *
+ * Takes `unknown` because its callers hold a click payload, not a typed row:
+ * recharts hands a pie/funnel click a SPREAD COPY of the data item, which is
+ * why the identity is an ordinary enumerable property and not a symbol or a
+ * non-enumerable one — either of those would silently not survive the copy.
+ */
+export declare function chartRowBucketId(row: unknown): string | undefined;
 /** Per-call knobs shared by {@link buildChartSeries} / {@link findChartSeriesRow}. */
 export interface ChartSeriesOptions {
     /**
@@ -81,6 +111,69 @@ export interface ChartSeriesOptions {
      */
     nullCategoryLabel?: string;
 }
+/** Per-CLICK knobs for {@link findChartSeriesRow}, on top of the shared ones. */
+export interface ChartDrillLookupOptions extends ChartSeriesOptions {
+    /**
+     * The clicked bucket's {@link chartBucketId}, when the renderer could read one
+     * off the row the segment was drawn from ({@link chartRowBucketId} over
+     * {@link CHART_BUCKET_ID_KEY}) — objectui#4508.
+     *
+     * Supplied ⇒ AUTHORITATIVE: the lookup matches on identity and ignores
+     * `category` entirely, which is what lets two bars painting the same axis
+     * text drill to their own rows instead of both resolving to the first.
+     * Absent ⇒ the bucket's display string identified it on its own (that is
+     * exactly when `buildChartSeries` writes no id), or the rows were not built
+     * by `buildChartSeries` at all, and the display match answers.
+     */
+    bucketId?: string;
+}
+/**
+ * What a chart renderer hands a drill handler when a segment is clicked.
+ *
+ * Declared HERE, beside the two helpers that write and read a bucket, rather
+ * than re-spelled inline in each of the three packages that pass it along
+ * (`AdvancedChartImpl` builds it, `ChartRenderer` and `ObjectChart` forward it,
+ * `DatasetWidget` consumes it). It was three inline literals when
+ * {@link ChartDrillLookupOptions.bucketId} needed a carrier, and a field added
+ * to one of three copies reaches the consumer as `undefined` with nothing red.
+ */
+export interface ChartSegmentClickEvent {
+    /** The clicked bucket's axis TEXT — what the user sees on the tick. */
+    category?: string;
+    /**
+     * The clicked bucket's IDENTITY, when its row carried one (objectui#4508).
+     * Feed it straight to {@link ChartDrillLookupOptions.bucketId}; it is the
+     * only field that survives two buckets painting the same `category`.
+     */
+    categoryId?: string;
+    /** The clicked series' key — a measure, or a pivoted second-dimension value. */
+    series?: string;
+    /**
+     * The clicked series' DISPLAY LABEL, when the renderer knew one
+     * (objectui#4682) — `series[].label` as {@link buildChartSeries} assigned it.
+     *
+     * {@link ChartSegmentClickEvent.series} stays the LOOKUP key and this never
+     * substitutes for it: {@link findChartSeriesRow} resolves a key through the
+     * same assignment `buildChartSeries` made, and a label cannot be resolved
+     * that way — it is not unique (that is precisely why the colliding groups key
+     * by identity instead). This field exists for what a key cannot do: be SHOWN.
+     *
+     * The two strings are equal for every ordinary group, which is why reading
+     * the key as a title went unnoticed. They part company when a group's label
+     * cannot name it — objectui#4508's collision on the series axis — and the key
+     * becomes an opaque `chartBucketId`. A drawer titled `Backlog / [null]` over
+     * a segment the user saw labelled `(None)` reads as broken DATA rather than
+     * as a broken title, which is why the label travels with the click rather
+     * than being re-derived by the consumer.
+     *
+     * Absent when the renderer resolved no series, or when the series carries no
+     * label distinct from its key; a consumer titles itself from
+     * `seriesLabel ?? series` and so is unchanged wherever it is absent.
+     */
+    seriesLabel?: string;
+    /** The measure value at the click point. */
+    value?: number;
+}
 export declare function buildChartSeries(rows: Array<Record<string, unknown>> | null | undefined, dimensions: string[] | null | undefined, values: string[] | null | undefined, fields?: ChartResultField[] | null, options?: ChartSeriesOptions): ChartSeriesResult;
 /**
  * Resolve select/enum dimension VALUES to display LABELS in chart rows.
@@ -117,16 +210,37 @@ export declare function relabelDimensions(rows: Array<Record<string, unknown>> |
  *    BOTH the x-axis dimension (`category`) and the series dimension (`seriesKey`).
  *  - **otherwise** → match the x-axis (first) dimension only.
  *
- * Comparison is string-wise on the rows' display values (which is what the chart
- * surfaces as `category` / series key). Returns `-1` when nothing matches.
+ * The x-axis comparison is string-wise on the rows' display values (which is
+ * what the chart surfaces as `category`), unless the click carried a bucket
+ * IDENTITY — {@link ChartDrillLookupOptions.bucketId} — in which case that is
+ * authoritative and the display string is not consulted at all. Returns `-1`
+ * when nothing matches.
+ *
+ * The SERIES comparison is not string-wise at all as of objectui#4673: a series
+ * key is a `dataKey` {@link buildChartSeries} assigned, so it is resolved back
+ * through the same {@link pivotSeriesBuckets} assignment (same rows, same
+ * `nullCategoryLabel`) to the group IDENTITY it names, and rows are matched on
+ * that. A null-valued second dimension had no series at all before, so its
+ * segment could not be clicked; now it can, and `String(r[gDim] ?? '')` would
+ * have answered that click with an empty-string group's rows — the same
+ * conflation objectui#4508 removed on the x-axis.
  *
  * The NULL-category bucket {@link buildChartSeries} renders (objectui#4466) is
  * matched back to its row here, and it has to be: the caller passes the rows it
  * charted FROM (still carrying the raw null) while the click event carries the
  * bucket LABEL, so without this the one bar the fix made visible would resolve
  * to `-1` and its drill-through would silently no-op. Pass the same
- * `nullCategoryLabel` both helpers were given. The pre-existing `''` spelling
- * of "no group value" still matches too — `computeDrillFilter` writes that one.
+ * `nullCategoryLabel` both helpers were given.
+ *
+ * **A null category reads as its bucket LABEL and nothing else** (objectui#4508).
+ * It used to read as the label OR the empty string, on the stated grounds that
+ * `''` is the drill layer's own spelling of "no group value" — but no producer
+ * of this function's `category` argument writes that spelling (the one
+ * production caller feeds it a chart click's category, and `computeDrillFilter`
+ * is downstream of the drill, not upstream of this lookup), while `''` IS what
+ * a genuine empty-string group paints. So the tolerance cost that group its own
+ * drill and gave it a null group's records instead — a WRONG click, not a dead
+ * one. `''` now means the empty-string group, which is what it says.
  *
  * **`xOf` covers BOTH arms, which is what let objectui#4497 bucket the pivot
  * branch without touching this function.** Worth stating because the reverse
@@ -140,7 +254,7 @@ export declare function relabelDimensions(rows: Array<Record<string, unknown>> |
  * searches still carry their null either way, and `xOf` reads the label back to
  * them in the multi-dimension arm exactly as in the single-dimension one.
  */
-export declare function findChartSeriesRow(rows: Array<Record<string, unknown>> | null | undefined, dimensions: string[] | null | undefined, values: string[] | null | undefined, category: string | undefined, seriesKey?: string, options?: ChartSeriesOptions): number;
+export declare function findChartSeriesRow(rows: Array<Record<string, unknown>> | null | undefined, dimensions: string[] | null | undefined, values: string[] | null | undefined, category: string | undefined, seriesKey?: string, options?: ChartDrillLookupOptions): number;
 /**
  * Build a per-category colour map from a select/lookup field's `options`.
  *