@rowsncolumns/charts 27.0.30

package/dist/esm/utils/region-map-loader.js

@@ -0,0 +1,141 @@
+/**
+ * Lazy loader + registry for region-map (choropleth) geo data.
+ *
+ * echarts ships no map geometry, and the world GeoJSON plus the map
+ * chart module are dead weight for every non-map chart — so nothing
+ * here is imported eagerly. The renderer calls `loadRegionMapGeo(scope)`
+ * the first time a region-map spec is actually about to render:
+ *
+ *   - the echarts `MapChart` / `GeoComponent` / `VisualMapComponent`
+ *     modules are dynamically imported and registered once
+ *   - the default `"world"` scope is built by dynamically importing the
+ *     `world-atlas` countries TopoJSON (~110 KB) and converting it with
+ *     `topojson-client`
+ *   - any other scope must have been provided by the host through
+ *     `registerChartGeoMap(name, geoJson)` (e.g. a US-states GeoJSON)
+ *
+ * Failures latch (mirroring `echarts-gl-loader.ts`): a failed import
+ * warns once and keeps resolving null, so the renderer draws an empty
+ * chart instead of crashing or re-fetching on every update. Everything
+ * is SSR-safe — no window/document access.
+ */
+import * as echarts from "echarts/core";
+import { WORLD_GEO_SCOPE } from "./region-map";
+const registeredMaps = new Map();
+let modulesPromise = null;
+let worldPromise = null;
+const warnedScopes = new Set();
+const extractRegionNames = (geoJson) => {
+    const features = geoJson?.features;
+    if (!Array.isArray(features))
+        return [];
+    const names = [];
+    for (const feature of features) {
+        const name = feature?.properties?.name;
+        if (typeof name === "string" && name.length > 0) {
+            names.push(name);
+        }
+    }
+    return names;
+};
+const warnOnce = (scope, message) => {
+    if (warnedScopes.has(scope))
+        return;
+    warnedScopes.add(scope);
+    // eslint-disable-next-line no-console
+    console.warn(message);
+};
+/**
+ * Register the echarts modules the choropleth needs (map series, geo
+ * coordinate system, visualMap). Dynamically imported so non-map
+ * charts never pay for them; a failed import latches as unavailable.
+ */
+const ensureEchartsMapModules = () => {
+    if (!modulesPromise) {
+        modulesPromise = Promise.all([
+            import("echarts/charts"),
+            import("echarts/components"),
+        ])
+            .then(([charts, components]) => {
+            echarts.use([
+                charts.MapChart,
+                components.GeoComponent,
+                components.VisualMapComponent,
+            ]);
+            return true;
+        })
+            .catch(() => false);
+    }
+    return modulesPromise;
+};
+/**
+ * Host-provided geo data: register `geoJson` under `name` so region-map
+ * specs with `geoScope: name` can render on it (e.g. a US-states map).
+ * Region matching targets each feature's `properties.name`. The actual
+ * `echarts.registerMap` call is deferred until the map modules have
+ * loaded, so this is safe to call at module scope.
+ */
+export const registerChartGeoMap = (name, geoJson) => {
+    registeredMaps.set(name, {
+        geoJson,
+        regionNames: extractRegionNames(geoJson),
+        applied: false,
+    });
+};
+const loadWorldGeoMap = () => {
+    if (!worldPromise) {
+        worldPromise = Promise.all([
+            import("world-atlas/countries-110m.json"),
+            import("topojson-client"),
+        ])
+            .then(([topologyModule, topojson]) => {
+            const topology = topologyModule.default ?? topologyModule;
+            const geoJson = topojson.feature(topology, topology.objects.countries);
+            const entry = {
+                geoJson,
+                regionNames: extractRegionNames(geoJson),
+                applied: false,
+            };
+            registeredMaps.set(WORLD_GEO_SCOPE, entry);
+            return entry;
+        })
+            .catch(() => {
+            warnOnce(WORLD_GEO_SCOPE, "[charts] Failed to load the world map geometry for region-map charts; the chart will render empty.");
+            return null;
+        });
+    }
+    return worldPromise;
+};
+/**
+ * Resolve the geo data for a scope, loading the echarts map modules
+ * (and, for "world", the bundled world GeoJSON) on first use. Resolves
+ * null — never throws — when the scope is unknown or an asset failed
+ * to load; the renderer then draws an empty chart.
+ */
+export const loadRegionMapGeo = async (scope) => {
+    const modulesReady = await ensureEchartsMapModules();
+    if (!modulesReady) {
+        warnOnce("echarts-map-modules", "[charts] Failed to load the echarts map modules for region-map charts; the chart will render empty.");
+        return null;
+    }
+    let entry = registeredMaps.get(scope) ?? null;
+    if (!entry && scope === WORLD_GEO_SCOPE) {
+        entry = await loadWorldGeoMap();
+    }
+    if (!entry) {
+        warnOnce(scope, `[charts] Region map: no geo data registered for scope "${scope}". Register one with registerChartGeoMap("${scope}", geoJson).`);
+        return null;
+    }
+    if (!entry.applied) {
+        echarts.registerMap(scope, entry.geoJson);
+        entry.applied = true;
+    }
+    return { regionNames: entry.regionNames };
+};
+/** Test hook — resets the module-level registries and latches. */
+export const __resetRegionMapLoaderForTests = () => {
+    registeredMaps.clear();
+    modulesPromise = null;
+    worldPromise = null;
+    warnedScopes.clear();
+};

package/dist/esm/utils/region-map.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Region map / filled map (OOXML chartex `<cx:regionMap>`) helpers.
+ *
+ * Excel's filled map paints a choropleth: values keyed by geography
+ * (country/state names) shade regions on a map. The spec reuses the
+ * existing series/domain data model — the category domain carries the
+ * region labels and the first series carries the values — plus an
+ * optional `geoScope` naming the registered echarts map ("world" by
+ * default).
+ *
+ * Everything here is pure: region-name normalization + alias matching,
+ * choropleth data assembly, and the sequential color ramp for the value
+ * scale. The geo asset loading lives in `region-map-loader.ts`.
+ */
+type MaybeLike<T> = T | null | undefined;
+/** Default geo scope — the lazily loaded world map. */
+export declare const WORLD_GEO_SCOPE = "world";
+/**
+ * True when a basic-chart spec should render as a region-map
+ * choropleth: the first-class `"regionMap"` chart type, or any payload
+ * degraded to another `chartType` that preserves the authored class as
+ * `sourceChartType: "REGION_MAP"` (case-insensitive, mirroring
+ * `isParetoSpec` / `isOfPieChartSpec`).
+ */
+export declare const isRegionMapSpec: (spec: {
+    chartType?: string;
+    sourceChartType?: MaybeLike<string>;
+}) => boolean;
+/** Coerce a `geoScope` value to a usable map name (default "world"). */
+export declare const resolveGeoScope: (raw: MaybeLike<string>) => string;
+/**
+ * Normalize a region label for matching: trim, collapse whitespace,
+ * casefold, strip diacritics ("Côte d'Ivoire" → "cote d'ivoire"),
+ * unify curly apostrophes, and drop periods ("U.S." → "us").
+ */
+export declare const normalizeRegionKey: (name: MaybeLike<string>) => string;
+/**
+ * Groups of equivalent region names. Members are matched through
+ * `normalizeRegionKey`, so casing/diacritics/periods don't matter.
+ * Each group binds only when one of its members actually exists on the
+ * loaded map, so the table is map-agnostic: the canonical spellings
+ * below cover both the bundled world map's Natural Earth names
+ * ("United States of America", "Dem. Rep. Congo", …) and the long-form
+ * names hosts commonly author.
+ */
+export declare const REGION_NAME_ALIASES: readonly (readonly string[])[];
+/**
+ * Build a lookup from normalized label → the map's own region name.
+ * Exact (normalized) names always win; alias-group members resolve to
+ * whichever member exists on the map, and never shadow a real region
+ * name.
+ */
+export declare const buildRegionNameIndex: (regionNames: readonly string[]) => Map<string, string>;
+export type RegionMapDatum = {
+    /** The map's own region name (echarts matches `data[].name` on it). */
+    name: string;
+    value: number;
+};
+export type RegionMapData = {
+    /** Matched regions, deduped by region (last value wins). */
+    data: RegionMapDatum[];
+    /** Labels that matched no region on the map — skipped, never fatal. */
+    unmatched: string[];
+    /** visualMap extent derived from the matched values. */
+    min: number;
+    max: number;
+};
+/**
+ * Assemble echarts `map`-series data from parallel label/value arrays
+ * (category domain = region labels, first series = values).
+ *
+ * - labels are matched exactly first, then through the normalization +
+ *   alias layer; unmatched labels are collected (not thrown)
+ * - blank labels and non-finite values are skipped
+ * - duplicate labels collapse onto one region (last value wins)
+ * - min/max span the matched values; degenerate extents are widened so
+ *   the visualMap ramp stays valid (no data → 0..1, all-equal → the
+ *   value against 0, all-zero → 0..1)
+ */
+export declare const buildRegionMapData: (labels: readonly MaybeLike<string | number>[], values: readonly MaybeLike<string | number | boolean>[], regionNames: readonly string[]) => RegionMapData;
+/** Linear RGB mix of two 6-digit hex colors; `t` 0 → a, 1 → b. */
+export declare const mixHexColors: (a: string, b: string, t: number) => string;
+/**
+ * Sequential (single-hue, light→dark) color ramp for the choropleth's
+ * value scale, derived from the theme accent. Dark mode gets its own
+ * steps mixed toward the dark chart surface rather than a flipped
+ * light ramp, so low values stay legible on a dark background.
+ */
+export declare const buildSequentialColorRamp: (accentColor: MaybeLike<string>, isDarkMode: boolean) => string[];
+/**
+ * `console.warn` the unmatched region labels for a scope once — the
+ * chart re-renders on every data tick, so an unguarded warn would spam
+ * the console. Keyed by scope + label set; a different set of
+ * unmatched labels warns again.
+ */
+export declare const warnOnceForUnmatchedRegions: (scope: string, unmatched: readonly string[]) => void;
+/** Test hook — resets the warn-once registry. */
+export declare const __resetRegionMapWarningsForTests: () => void;
+export {};
+//# sourceMappingURL=region-map.d.ts.map

package/dist/esm/utils/region-map.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"region-map.d.ts","sourceRoot":"","sources":["../../../utils/region-map.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,KAAK,SAAS,CAAC,CAAC,IAAI,CAAC,GAAG,IAAI,GAAG,SAAS,CAAC;AAEzC,uDAAuD;AACvD,eAAO,MAAM,eAAe,UAAU,CAAC;AAEvC;;;;;;GAMG;AACH,eAAO,MAAM,eAAe,GAAI,MAAM;IACpC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,eAAe,CAAC,EAAE,SAAS,CAAC,MAAM,CAAC,CAAC;CACrC,KAAG,OAGoD,CAAC;AAEzD,wEAAwE;AACxE,eAAO,MAAM,eAAe,GAAI,KAAK,SAAS,CAAC,MAAM,CAAC,KAAG,MAGxD,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,GAAI,MAAM,SAAS,CAAC,MAAM,CAAC,KAAG,MAS3C,CAAC;AAEnB;;;;;;;;GAQG;AACH,eAAO,MAAM,mBAAmB,EAAE,SAAS,CAAC,SAAS,MAAM,EAAE,CAAC,EAqDpD,CAAC;AAEX;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,GAC/B,aAAa,SAAS,MAAM,EAAE,KAC7B,GAAG,CAAC,MAAM,EAAE,MAAM,CA2BpB,CAAC;AAEF,MAAM,MAAM,cAAc,GAAG;IAC3B,uEAAuE;IACvE,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG;IAC1B,4DAA4D;IAC5D,IAAI,EAAE,cAAc,EAAE,CAAC;IACvB,uEAAuE;IACvE,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,wDAAwD;IACxD,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;CACb,CAAC;AAOF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,kBAAkB,GAC7B,QAAQ,SAAS,SAAS,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,EAC7C,QAAQ,SAAS,SAAS,CAAC,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,EAAE,EACvD,aAAa,SAAS,MAAM,EAAE,KAC7B,aAiCF,CAAC;AAeF,kEAAkE;AAClE,eAAO,MAAM,YAAY,GAAI,GAAG,MAAM,EAAE,GAAG,MAAM,EAAE,GAAG,MAAM,KAAG,MAU9D,CAAC;AAOF;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB,GACnC,aAAa,SAAS,CAAC,MAAM,CAAC,EAC9B,YAAY,OAAO,KAClB,MAAM,EAWR,CAAC;AAMF;;;;;GAKG;AACH,eAAO,MAAM,2BAA2B,GACtC,OAAO,MAAM,EACb,WAAW,SAAS,MAAM,EAAE,KAC3B,IAUF,CAAC;AAEF,iDAAiD;AACjD,eAAO,MAAM,gCAAgC,QAAO,IAEnD,CAAC"}

package/dist/esm/utils/region-map.js

@@ -0,0 +1,266 @@
+/**
+ * Region map / filled map (OOXML chartex `<cx:regionMap>`) helpers.
+ *
+ * Excel's filled map paints a choropleth: values keyed by geography
+ * (country/state names) shade regions on a map. The spec reuses the
+ * existing series/domain data model — the category domain carries the
+ * region labels and the first series carries the values — plus an
+ * optional `geoScope` naming the registered echarts map ("world" by
+ * default).
+ *
+ * Everything here is pure: region-name normalization + alias matching,
+ * choropleth data assembly, and the sequential color ramp for the value
+ * scale. The geo asset loading lives in `region-map-loader.ts`.
+ */
+/** Default geo scope — the lazily loaded world map. */
+export const WORLD_GEO_SCOPE = "world";
+/**
+ * True when a basic-chart spec should render as a region-map
+ * choropleth: the first-class `"regionMap"` chart type, or any payload
+ * degraded to another `chartType` that preserves the authored class as
+ * `sourceChartType: "REGION_MAP"` (case-insensitive, mirroring
+ * `isParetoSpec` / `isOfPieChartSpec`).
+ */
+export const isRegionMapSpec = (spec) => spec?.chartType === "regionMap" ||
+    (typeof spec?.sourceChartType === "string" &&
+        spec.sourceChartType.toUpperCase() === "REGION_MAP");
+/** Coerce a `geoScope` value to a usable map name (default "world"). */
+export const resolveGeoScope = (raw) => {
+    const scope = typeof raw === "string" ? raw.trim() : "";
+    return scope.length > 0 ? scope : WORLD_GEO_SCOPE;
+};
+/**
+ * Normalize a region label for matching: trim, collapse whitespace,
+ * casefold, strip diacritics ("Côte d'Ivoire" → "cote d'ivoire"),
+ * unify curly apostrophes, and drop periods ("U.S." → "us").
+ */
+export const normalizeRegionKey = (name) => String(name ?? "")
+    .normalize("NFD")
+    // Combining diacritical marks left behind by NFD decomposition.
+    .replace(/[\u0300-\u036f]/g, "")
+    .replace(/[\u2018\u2019]/g, "'")
+    .replace(/\./g, "")
+    .replace(/\s+/g, " ")
+    .trim()
+    .toLowerCase();
+/**
+ * Groups of equivalent region names. Members are matched through
+ * `normalizeRegionKey`, so casing/diacritics/periods don't matter.
+ * Each group binds only when one of its members actually exists on the
+ * loaded map, so the table is map-agnostic: the canonical spellings
+ * below cover both the bundled world map's Natural Earth names
+ * ("United States of America", "Dem. Rep. Congo", …) and the long-form
+ * names hosts commonly author.
+ */
+export const REGION_NAME_ALIASES = [
+    ["United States of America", "United States", "USA", "US", "America"],
+    ["United Kingdom", "UK", "Great Britain", "Britain"],
+    ["Russia", "Russian Federation"],
+    ["South Korea", "Republic of Korea", "Korea, South", "Korea"],
+    [
+        "North Korea",
+        "Democratic People's Republic of Korea",
+        "Korea, North",
+    ],
+    ["Czechia", "Czech Republic"],
+    ["Côte d'Ivoire", "Ivory Coast", "Cote d'Ivoire"],
+    [
+        "Dem. Rep. Congo",
+        "Democratic Republic of the Congo",
+        "DR Congo",
+        "DRC",
+        "Congo-Kinshasa",
+        "Congo (Kinshasa)",
+    ],
+    [
+        "Congo",
+        "Republic of the Congo",
+        "Congo-Brazzaville",
+        "Congo (Brazzaville)",
+    ],
+    ["Myanmar", "Burma"],
+    ["Vietnam", "Viet Nam"],
+    ["Syria", "Syrian Arab Republic"],
+    ["Iran", "Islamic Republic of Iran"],
+    ["Laos", "Lao PDR", "Lao People's Democratic Republic"],
+    ["Bolivia", "Plurinational State of Bolivia"],
+    ["Venezuela", "Bolivarian Republic of Venezuela"],
+    ["Tanzania", "United Republic of Tanzania"],
+    ["Moldova", "Republic of Moldova"],
+    ["Brunei", "Brunei Darussalam"],
+    ["United Arab Emirates", "UAE"],
+    ["Bahamas", "The Bahamas"],
+    ["Gambia", "The Gambia"],
+    ["Timor-Leste", "East Timor"],
+    ["eSwatini", "Eswatini", "Swaziland"],
+    ["Macedonia", "North Macedonia"],
+    ["Bosnia and Herz.", "Bosnia and Herzegovina", "Bosnia"],
+    ["Central African Rep.", "Central African Republic"],
+    ["Dominican Rep.", "Dominican Republic"],
+    ["Eq. Guinea", "Equatorial Guinea"],
+    ["S. Sudan", "South Sudan"],
+    ["Solomon Is.", "Solomon Islands"],
+    ["W. Sahara", "Western Sahara"],
+    ["Falkland Is.", "Falkland Islands"],
+    ["Turkey", "Türkiye"],
+    ["Netherlands", "The Netherlands", "Holland"],
+    ["Palestine", "State of Palestine", "Palestinian Territories"],
+];
+/**
+ * Build a lookup from normalized label → the map's own region name.
+ * Exact (normalized) names always win; alias-group members resolve to
+ * whichever member exists on the map, and never shadow a real region
+ * name.
+ */
+export const buildRegionNameIndex = (regionNames) => {
+    const index = new Map();
+    for (const name of regionNames) {
+        const key = normalizeRegionKey(name);
+        if (key && !index.has(key)) {
+            index.set(key, name);
+        }
+    }
+    for (const group of REGION_NAME_ALIASES) {
+        // The group's target is the member that exists on the map.
+        let target;
+        for (const member of group) {
+            const existing = index.get(normalizeRegionKey(member));
+            if (existing !== undefined) {
+                target = existing;
+                break;
+            }
+        }
+        if (target === undefined)
+            continue;
+        for (const member of group) {
+            const key = normalizeRegionKey(member);
+            if (key && !index.has(key)) {
+                index.set(key, target);
+            }
+        }
+    }
+    return index;
+};
+const toFiniteNumber = (value) => {
+    const n = typeof value === "number" ? value : Number(value);
+    return Number.isFinite(n) ? n : undefined;
+};
+/**
+ * Assemble echarts `map`-series data from parallel label/value arrays
+ * (category domain = region labels, first series = values).
+ *
+ * - labels are matched exactly first, then through the normalization +
+ *   alias layer; unmatched labels are collected (not thrown)
+ * - blank labels and non-finite values are skipped
+ * - duplicate labels collapse onto one region (last value wins)
+ * - min/max span the matched values; degenerate extents are widened so
+ *   the visualMap ramp stays valid (no data → 0..1, all-equal → the
+ *   value against 0, all-zero → 0..1)
+ */
+export const buildRegionMapData = (labels, values, regionNames) => {
+    const index = buildRegionNameIndex(regionNames);
+    const byRegion = new Map();
+    const unmatched = [];
+    for (let i = 0; i < labels.length; i++) {
+        const label = String(labels[i] ?? "").trim();
+        if (!label)
+            continue;
+        const value = toFiniteNumber(values[i]);
+        if (value === undefined)
+            continue;
+        const region = index.get(normalizeRegionKey(label));
+        if (region === undefined) {
+            unmatched.push(label);
+            continue;
+        }
+        byRegion.set(region, value);
+    }
+    const data = [];
+    let min = Number.POSITIVE_INFINITY;
+    let max = Number.NEGATIVE_INFINITY;
+    byRegion.forEach((value, name) => {
+        data.push({ name, value });
+        if (value < min)
+            min = value;
+        if (value > max)
+            max = value;
+    });
+    if (data.length === 0) {
+        min = 0;
+        max = 1;
+    }
+    else if (min === max) {
+        if (min > 0)
+            min = 0;
+        else if (max < 0)
+            max = 0;
+        else
+            max = 1;
+    }
+    return { data, unmatched, min, max };
+};
+// ------------------------- Sequential ramp -------------------------
+const HEX_COLOR_RE = /^#?([0-9a-f]{6})$/i;
+const parseHexColor = (color) => {
+    const match = HEX_COLOR_RE.exec(String(color ?? "").trim());
+    if (!match)
+        return undefined;
+    const n = parseInt(match[1], 16);
+    return [(n >> 16) & 0xff, (n >> 8) & 0xff, n & 0xff];
+};
+/** Linear RGB mix of two 6-digit hex colors; `t` 0 → a, 1 → b. */
+export const mixHexColors = (a, b, t) => {
+    const ca = parseHexColor(a);
+    const cb = parseHexColor(b);
+    if (!ca || !cb)
+        return b;
+    const clamped = Math.min(1, Math.max(0, t));
+    const channel = (i) => Math.round(ca[i] + (cb[i] - ca[i]) * clamped);
+    return `#${[channel(0), channel(1), channel(2)]
+        .map((c) => c.toString(16).padStart(2, "0"))
+        .join("")}`;
+};
+/** Fallback hue when the theme accent isn't a parseable hex color. */
+const DEFAULT_RAMP_ACCENT = "#4472c4";
+const LIGHT_RAMP_BASE = "#ffffff";
+const DARK_RAMP_BASE = "#1f2733";
+/**
+ * Sequential (single-hue, light→dark) color ramp for the choropleth's
+ * value scale, derived from the theme accent. Dark mode gets its own
+ * steps mixed toward the dark chart surface rather than a flipped
+ * light ramp, so low values stay legible on a dark background.
+ */
+export const buildSequentialColorRamp = (accentColor, isDarkMode) => {
+    const accent = parseHexColor(accentColor)
+        ? String(accentColor).trim()
+        : DEFAULT_RAMP_ACCENT;
+    const base = isDarkMode ? DARK_RAMP_BASE : LIGHT_RAMP_BASE;
+    // Low end keeps a visible trace of the hue (never the bare surface,
+    // so "has a small value" and "has no data" read differently).
+    const stops = isDarkMode
+        ? [0.25, 0.44, 0.63, 0.81, 1]
+        : [0.12, 0.34, 0.56, 0.78, 1];
+    return stops.map((t) => mixHexColors(base, accent, t));
+};
+// --------------------------- Warn-once ---------------------------
+const warnedUnmatched = new Set();
+/**
+ * `console.warn` the unmatched region labels for a scope once — the
+ * chart re-renders on every data tick, so an unguarded warn would spam
+ * the console. Keyed by scope + label set; a different set of
+ * unmatched labels warns again.
+ */
+export const warnOnceForUnmatchedRegions = (scope, unmatched) => {
+    if (unmatched.length === 0)
+        return;
+    const key = `${scope}|${[...unmatched].sort().join("")}`;
+    if (warnedUnmatched.has(key))
+        return;
+    warnedUnmatched.add(key);
+    // eslint-disable-next-line no-console
+    console.warn(`[charts] Region map ("${scope}"): skipped ${unmatched.length} label(s) that match no region on the map:`, unmatched);
+};
+/** Test hook — resets the warn-once registry. */
+export const __resetRegionMapWarningsForTests = () => {
+    warnedUnmatched.clear();
+};

package/dist/esm/utils/stock.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Stock-chart shaping shared by chart renderers.
+ *
+ * Excel stock charts come in four variants distinguished by the ordered
+ * set of value series they carry:
+ *   - HLC   : High, Low, Close
+ *   - OHLC  : Open, High, Low, Close
+ *   - VHLC  : Volume, High, Low, Close
+ *   - VOHLC : Volume, Open, High, Low, Close
+ *
+ * We render stock as a "line-derived" chart: each price role becomes its
+ * own line series (volume is kept out of the price plot — it lives on a
+ * different scale and would flatten the price lines — and is instead
+ * surfaced via `toVolumeSeries` for renderers to draw as a column
+ * sub-pane on its own value axis). The candlestick transform is also
+ * provided for renderers that prefer a true OHLC body (echarts
+ * CandlestickChart / plotly candlestick).
+ */
+export type StockVariant = "HLC" | "OHLC" | "VHLC" | "VOHLC";
+export type StockRole = "volume" | "open" | "high" | "low" | "close";
+/**
+ * The ordered roles for each variant. Series are matched to roles by
+ * position — series[0] takes role[0], etc.
+ */
+export declare const STOCK_ROLES: Record<StockVariant, StockRole[]>;
+/**
+ * Map positional series to their stock roles for a given variant.
+ * Series beyond the variant's role count are ignored.
+ */
+export declare const assignStockRoles: (seriesValues: (number | null | undefined)[][], variant?: StockVariant) => Partial<Record<StockRole, (number | null)[]>>;
+/**
+ * Line-derived view: emit one line series per PRICE role (open/high/low/
+ * close), preserving variant order and dropping volume. Each returned
+ * series carries a role-derived display name and its value vector.
+ */
+export declare const toLineSeries: (seriesValues: (number | null | undefined)[][], variant?: StockVariant) => Array<{
+    role: StockRole;
+    name: string;
+    values: (number | null)[];
+}>;
+export interface StockVolumePoint {
+    /** Volume value at the category index (null when missing). */
+    value: number | null;
+    /** True on an up day — used to color the volume column. */
+    up: boolean;
+}
+/**
+ * Volume view: extract the volume series for the V-variants and flag
+ * each point as an up/down day so renderers can color the columns to
+ * match the price plot. Up/down follows convention: close vs open where
+ * the point carries an open, otherwise close vs the previous close. A
+ * point with nothing to compare against (e.g. the first) counts as up.
+ * Returns null for variants without a volume role (HLC / OHLC) or when
+ * the volume series is absent.
+ */
+export declare const toVolumeSeries: (seriesValues: (number | null | undefined)[][], variant?: StockVariant) => StockVolumePoint[] | null;
+/**
+ * Candlestick view: produce [open, close, low, high] tuples (echarts'
+ * candlestick data order) per category index. When the variant has no
+ * `open` (HLC / VHLC) the close value is used as the open so the body
+ * collapses to a tick — matching how Excel renders HLC stock bars.
+ */
+export declare const toCandlestick: (seriesValues: (number | null | undefined)[][], variant?: StockVariant) => Array<[number, number, number, number]>;
+//# sourceMappingURL=stock.d.ts.map

package/dist/esm/utils/stock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stock.d.ts","sourceRoot":"","sources":["../../../utils/stock.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,MAAM,MAAM,YAAY,GAAG,KAAK,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;AAE7D,MAAM,MAAM,SAAS,GAAG,QAAQ,GAAG,MAAM,GAAG,MAAM,GAAG,KAAK,GAAG,OAAO,CAAC;AAErE;;;GAGG;AACH,eAAO,MAAM,WAAW,EAAE,MAAM,CAAC,YAAY,EAAE,SAAS,EAAE,CAKzD,CAAC;AAQF;;;GAGG;AACH,eAAO,MAAM,gBAAgB,GAC3B,cAAc,CAAC,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC,EAAE,EAAE,EAC7C,UAAS,YAAoB,KAC5B,OAAO,CAAC,MAAM,CAAC,SAAS,EAAE,CAAC,MAAM,GAAG,IAAI,CAAC,EAAE,CAAC,CAS9C,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,YAAY,GACvB,cAAc,CAAC,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC,EAAE,EAAE,EAC7C,UAAS,YAAoB,KAC5B,KAAK,CAAC;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,CAAC,MAAM,GAAG,IAAI,CAAC,EAAE,CAAA;CAAE,CAoBpE,CAAC;AAEF,MAAM,WAAW,gBAAgB;IAC/B,8DAA8D;IAC9D,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,2DAA2D;IAC3D,EAAE,EAAE,OAAO,CAAC;CACb;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,cAAc,GACzB,cAAc,CAAC,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC,EAAE,EAAE,EAC7C,UAAS,YAAoB,KAC5B,gBAAgB,EAAE,GAAG,IAkBvB,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,aAAa,GACxB,cAAc,CAAC,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC,EAAE,EAAE,EAC7C,UAAS,YAAoB,KAC5B,KAAK,CAAC,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAgBxC,CAAC"}