@rowsncolumns/charts 27.0.30

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

@@ -0,0 +1,327 @@
+"use strict";
+/**
+ * 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`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.__resetRegionMapWarningsForTests = exports.warnOnceForUnmatchedRegions = exports.buildSequentialColorRamp = exports.mixHexColors = exports.buildRegionMapData = exports.buildRegionNameIndex = exports.REGION_NAME_ALIASES = exports.normalizeRegionKey = exports.resolveGeoScope = exports.isRegionMapSpec = exports.WORLD_GEO_SCOPE = void 0;
+var tslib_1 = require("tslib");
+/** Default geo scope — the lazily loaded world map. */
+exports.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`).
+ */
+var isRegionMapSpec = function (spec) {
+    return (spec === null || spec === void 0 ? void 0 : spec.chartType) === "regionMap" ||
+        (typeof (spec === null || spec === void 0 ? void 0 : spec.sourceChartType) === "string" &&
+            spec.sourceChartType.toUpperCase() === "REGION_MAP");
+};
+exports.isRegionMapSpec = isRegionMapSpec;
+/** Coerce a `geoScope` value to a usable map name (default "world"). */
+var resolveGeoScope = function (raw) {
+    var scope = typeof raw === "string" ? raw.trim() : "";
+    return scope.length > 0 ? scope : exports.WORLD_GEO_SCOPE;
+};
+exports.resolveGeoScope = resolveGeoScope;
+/**
+ * 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").
+ */
+var normalizeRegionKey = function (name) {
+    return String(name !== null && name !== void 0 ? 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();
+};
+exports.normalizeRegionKey = normalizeRegionKey;
+/**
+ * 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.
+ */
+exports.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.
+ */
+var buildRegionNameIndex = function (regionNames) {
+    var e_1, _a, e_2, _b, e_3, _c, e_4, _d;
+    var index = new Map();
+    try {
+        for (var regionNames_1 = tslib_1.__values(regionNames), regionNames_1_1 = regionNames_1.next(); !regionNames_1_1.done; regionNames_1_1 = regionNames_1.next()) {
+            var name_1 = regionNames_1_1.value;
+            var key = (0, exports.normalizeRegionKey)(name_1);
+            if (key && !index.has(key)) {
+                index.set(key, name_1);
+            }
+        }
+    }
+    catch (e_1_1) { e_1 = { error: e_1_1 }; }
+    finally {
+        try {
+            if (regionNames_1_1 && !regionNames_1_1.done && (_a = regionNames_1.return)) _a.call(regionNames_1);
+        }
+        finally { if (e_1) throw e_1.error; }
+    }
+    try {
+        for (var REGION_NAME_ALIASES_1 = tslib_1.__values(exports.REGION_NAME_ALIASES), REGION_NAME_ALIASES_1_1 = REGION_NAME_ALIASES_1.next(); !REGION_NAME_ALIASES_1_1.done; REGION_NAME_ALIASES_1_1 = REGION_NAME_ALIASES_1.next()) {
+            var group = REGION_NAME_ALIASES_1_1.value;
+            // The group's target is the member that exists on the map.
+            var target = void 0;
+            try {
+                for (var group_1 = (e_3 = void 0, tslib_1.__values(group)), group_1_1 = group_1.next(); !group_1_1.done; group_1_1 = group_1.next()) {
+                    var member = group_1_1.value;
+                    var existing = index.get((0, exports.normalizeRegionKey)(member));
+                    if (existing !== undefined) {
+                        target = existing;
+                        break;
+                    }
+                }
+            }
+            catch (e_3_1) { e_3 = { error: e_3_1 }; }
+            finally {
+                try {
+                    if (group_1_1 && !group_1_1.done && (_c = group_1.return)) _c.call(group_1);
+                }
+                finally { if (e_3) throw e_3.error; }
+            }
+            if (target === undefined)
+                continue;
+            try {
+                for (var group_2 = (e_4 = void 0, tslib_1.__values(group)), group_2_1 = group_2.next(); !group_2_1.done; group_2_1 = group_2.next()) {
+                    var member = group_2_1.value;
+                    var key = (0, exports.normalizeRegionKey)(member);
+                    if (key && !index.has(key)) {
+                        index.set(key, target);
+                    }
+                }
+            }
+            catch (e_4_1) { e_4 = { error: e_4_1 }; }
+            finally {
+                try {
+                    if (group_2_1 && !group_2_1.done && (_d = group_2.return)) _d.call(group_2);
+                }
+                finally { if (e_4) throw e_4.error; }
+            }
+        }
+    }
+    catch (e_2_1) { e_2 = { error: e_2_1 }; }
+    finally {
+        try {
+            if (REGION_NAME_ALIASES_1_1 && !REGION_NAME_ALIASES_1_1.done && (_b = REGION_NAME_ALIASES_1.return)) _b.call(REGION_NAME_ALIASES_1);
+        }
+        finally { if (e_2) throw e_2.error; }
+    }
+    return index;
+};
+exports.buildRegionNameIndex = buildRegionNameIndex;
+var toFiniteNumber = function (value) {
+    var 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)
+ */
+var buildRegionMapData = function (labels, values, regionNames) {
+    var _a;
+    var index = (0, exports.buildRegionNameIndex)(regionNames);
+    var byRegion = new Map();
+    var unmatched = [];
+    for (var i = 0; i < labels.length; i++) {
+        var label = String((_a = labels[i]) !== null && _a !== void 0 ? _a : "").trim();
+        if (!label)
+            continue;
+        var value = toFiniteNumber(values[i]);
+        if (value === undefined)
+            continue;
+        var region = index.get((0, exports.normalizeRegionKey)(label));
+        if (region === undefined) {
+            unmatched.push(label);
+            continue;
+        }
+        byRegion.set(region, value);
+    }
+    var data = [];
+    var min = Number.POSITIVE_INFINITY;
+    var max = Number.NEGATIVE_INFINITY;
+    byRegion.forEach(function (value, name) {
+        data.push({ name: name, value: 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: data, unmatched: unmatched, min: min, max: max };
+};
+exports.buildRegionMapData = buildRegionMapData;
+// ------------------------- Sequential ramp -------------------------
+var HEX_COLOR_RE = /^#?([0-9a-f]{6})$/i;
+var parseHexColor = function (color) {
+    var match = HEX_COLOR_RE.exec(String(color !== null && color !== void 0 ? color : "").trim());
+    if (!match)
+        return undefined;
+    var 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. */
+var mixHexColors = function (a, b, t) {
+    var ca = parseHexColor(a);
+    var cb = parseHexColor(b);
+    if (!ca || !cb)
+        return b;
+    var clamped = Math.min(1, Math.max(0, t));
+    var channel = function (i) {
+        return Math.round(ca[i] + (cb[i] - ca[i]) * clamped);
+    };
+    return "#".concat([channel(0), channel(1), channel(2)]
+        .map(function (c) { return c.toString(16).padStart(2, "0"); })
+        .join(""));
+};
+exports.mixHexColors = mixHexColors;
+/** Fallback hue when the theme accent isn't a parseable hex color. */
+var DEFAULT_RAMP_ACCENT = "#4472c4";
+var LIGHT_RAMP_BASE = "#ffffff";
+var 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.
+ */
+var buildSequentialColorRamp = function (accentColor, isDarkMode) {
+    var accent = parseHexColor(accentColor)
+        ? String(accentColor).trim()
+        : DEFAULT_RAMP_ACCENT;
+    var 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).
+    var stops = isDarkMode
+        ? [0.25, 0.44, 0.63, 0.81, 1]
+        : [0.12, 0.34, 0.56, 0.78, 1];
+    return stops.map(function (t) { return (0, exports.mixHexColors)(base, accent, t); });
+};
+exports.buildSequentialColorRamp = buildSequentialColorRamp;
+// --------------------------- Warn-once ---------------------------
+var 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.
+ */
+var warnOnceForUnmatchedRegions = function (scope, unmatched) {
+    if (unmatched.length === 0)
+        return;
+    var key = "".concat(scope, "|").concat(tslib_1.__spreadArray([], tslib_1.__read(unmatched), false).sort().join(""));
+    if (warnedUnmatched.has(key))
+        return;
+    warnedUnmatched.add(key);
+    // eslint-disable-next-line no-console
+    console.warn("[charts] Region map (\"".concat(scope, "\"): skipped ").concat(unmatched.length, " label(s) that match no region on the map:"), unmatched);
+};
+exports.warnOnceForUnmatchedRegions = warnOnceForUnmatchedRegions;
+/** Test hook — resets the warn-once registry. */
+var __resetRegionMapWarningsForTests = function () {
+    warnedUnmatched.clear();
+};
+exports.__resetRegionMapWarningsForTests = __resetRegionMapWarningsForTests;

package/dist/cjs/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/cjs/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"}

package/dist/cjs/utils/stock.js

@@ -0,0 +1,153 @@
+"use strict";
+/**
+ * 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).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toCandlestick = exports.toVolumeSeries = exports.toLineSeries = exports.assignStockRoles = exports.STOCK_ROLES = void 0;
+var tslib_1 = require("tslib");
+/**
+ * The ordered roles for each variant. Series are matched to roles by
+ * position — series[0] takes role[0], etc.
+ */
+exports.STOCK_ROLES = {
+    HLC: ["high", "low", "close"],
+    OHLC: ["open", "high", "low", "close"],
+    VHLC: ["volume", "high", "low", "close"],
+    VOHLC: ["volume", "open", "high", "low", "close"],
+};
+var isFiniteNum = function (v) {
+    return typeof v === "number" && Number.isFinite(v);
+};
+var toNumber = function (v) {
+    return isFiniteNum(v) ? v : null;
+};
+/**
+ * Map positional series to their stock roles for a given variant.
+ * Series beyond the variant's role count are ignored.
+ */
+var assignStockRoles = function (seriesValues, variant) {
+    var _a;
+    if (variant === void 0) { variant = "HLC"; }
+    var roles = (_a = exports.STOCK_ROLES[variant]) !== null && _a !== void 0 ? _a : exports.STOCK_ROLES.HLC;
+    var result = {};
+    for (var i = 0; i < roles.length; i++) {
+        var role = roles[i];
+        var values = seriesValues[i];
+        if (values)
+            result[role] = values.map(toNumber);
+    }
+    return result;
+};
+exports.assignStockRoles = assignStockRoles;
+/**
+ * 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.
+ */
+var toLineSeries = function (seriesValues, variant) {
+    var e_1, _a;
+    if (variant === void 0) { variant = "HLC"; }
+    var byRole = (0, exports.assignStockRoles)(seriesValues, variant);
+    var order = ["open", "high", "low", "close"];
+    var labels = {
+        volume: "Volume",
+        open: "Open",
+        high: "High",
+        low: "Low",
+        close: "Close",
+    };
+    var out = [];
+    try {
+        for (var order_1 = tslib_1.__values(order), order_1_1 = order_1.next(); !order_1_1.done; order_1_1 = order_1.next()) {
+            var role = order_1_1.value;
+            var values = byRole[role];
+            if (values)
+                out.push({ role: role, name: labels[role], values: values });
+        }
+    }
+    catch (e_1_1) { e_1 = { error: e_1_1 }; }
+    finally {
+        try {
+            if (order_1_1 && !order_1_1.done && (_a = order_1.return)) _a.call(order_1);
+        }
+        finally { if (e_1) throw e_1.error; }
+    }
+    return out;
+};
+exports.toLineSeries = toLineSeries;
+/**
+ * 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.
+ */
+var toVolumeSeries = function (seriesValues, variant) {
+    var _a, _b, _c, _d, _e;
+    if (variant === void 0) { variant = "HLC"; }
+    var byRole = (0, exports.assignStockRoles)(seriesValues, variant);
+    var volume = byRole.volume;
+    if (!volume)
+        return null;
+    var open = (_a = byRole.open) !== null && _a !== void 0 ? _a : [];
+    var close = (_b = byRole.close) !== null && _b !== void 0 ? _b : [];
+    var prevClose = null;
+    var out = [];
+    for (var i = 0; i < volume.length; i++) {
+        var c = (_c = close[i]) !== null && _c !== void 0 ? _c : null;
+        var o = (_d = open[i]) !== null && _d !== void 0 ? _d : null;
+        var up = true;
+        if (o !== null && c !== null)
+            up = c >= o;
+        else if (prevClose !== null && c !== null)
+            up = c >= prevClose;
+        out.push({ value: (_e = volume[i]) !== null && _e !== void 0 ? _e : null, up: up });
+        if (c !== null)
+            prevClose = c;
+    }
+    return out;
+};
+exports.toVolumeSeries = toVolumeSeries;
+/**
+ * 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.
+ */
+var toCandlestick = function (seriesValues, variant) {
+    var _a, _b, _c, _d, _e, _f, _g, _h;
+    if (variant === void 0) { variant = "HLC"; }
+    var byRole = (0, exports.assignStockRoles)(seriesValues, variant);
+    var high = (_a = byRole.high) !== null && _a !== void 0 ? _a : [];
+    var low = (_b = byRole.low) !== null && _b !== void 0 ? _b : [];
+    var close = (_c = byRole.close) !== null && _c !== void 0 ? _c : [];
+    var open = (_d = byRole.open) !== null && _d !== void 0 ? _d : [];
+    var len = Math.max(high.length, low.length, close.length, open.length);
+    var result = [];
+    for (var i = 0; i < len; i++) {
+        var c = (_e = close[i]) !== null && _e !== void 0 ? _e : 0;
+        var o = (_f = open[i]) !== null && _f !== void 0 ? _f : c;
+        var l = (_g = low[i]) !== null && _g !== void 0 ? _g : 0;
+        var h = (_h = high[i]) !== null && _h !== void 0 ? _h : 0;
+        result.push([o, c, l, h]);
+    }
+    return result;
+};
+exports.toCandlestick = toCandlestick;

package/dist/cjs/utils/three-d.d.ts

@@ -0,0 +1,96 @@
+/**
+ * 3-D / surface chart helpers.
+ *
+ * Excel's 3-D chart classes (Bar3D / Line3D / Pie3D / Area3D / Surface /
+ * Surface3D) degrade to a 2-D fallback `chartType` when imported, with the
+ * authored type preserved verbatim on the spec as `sourceChartType`. These
+ * helpers gate the renderer's 3-D pipeline off that token and shape the
+ * category/series value matrix into the data layouts the echarts-gl
+ * `bar3D` / `line3D` / `surface` series expect.
+ *
+ * Everything in this module is pure and independent of echarts-gl so it can
+ * be unit-tested without loading (or even installing a working) WebGL stack.
+ *
+ * Mapping decisions (see also basic-chart.tsx):
+ * - BAR_3D    -> `bar3D`   (x = category, y = series index, z = value)
+ * - LINE_3D   -> `line3D`  (one polyline per series at its series-index depth)
+ * - AREA_3D   -> `line3D`  (echarts-gl has no area3D; the polyline keeps the
+ *                          authored depth layout)
+ * - SURFACE / SURFACE_3D -> `surface` (values grid as z-heights over the
+ *                          categories × series plane)
+ * - PIE_3D    -> null      (echarts-gl has no pie3D; the renderer keeps the
+ *                          existing 2-D pie fallback rather than faking it)
+ */
+declare const THREE_D_TOKENS: readonly ["BAR_3D", "LINE_3D", "PIE_3D", "AREA_3D", "SURFACE", "SURFACE_3D"];
+export type ThreeDSourceType = (typeof THREE_D_TOKENS)[number];
+/** The echarts-gl series type a 3-D spec renders as. */
+export type ThreeDRenderKind = "bar3D" | "line3D" | "surface";
+/**
+ * Normalize a raw `sourceChartType` value to one of the known 3-D tokens.
+ * Matching is case-insensitive and whitespace-tolerant; anything else
+ * (including null/undefined) returns null.
+ */
+export declare const normalize3DSourceType: (sourceChartType?: string | null) => ThreeDSourceType | null;
+/**
+ * True when the spec was authored as one of the six 3-D / surface chart
+ * classes (its `sourceChartType` is one of the degraded-payload tokens).
+ * Note PIE_3D is included here even though it renders as the 2-D pie —
+ * use `resolve3DRenderKind` to decide whether the 3-D pipeline runs.
+ */
+export declare const is3DSpec: (spec: {
+    sourceChartType?: string | null;
+} | null | undefined) => boolean;
+/**
+ * Map a `sourceChartType` token to the echarts-gl series kind it renders
+ * as, or null when the 3-D pipeline should not run:
+ * - PIE_3D — echarts-gl has no pie3D, so the 2-D pie fallback stays.
+ * - AREA_3D — echarts-gl has no area3D; rendered as line3D.
+ * - non-3-D / unknown tokens.
+ */
+export declare const resolve3DRenderKind: (sourceChartType?: string | null) => ThreeDRenderKind | null;
+export type ThreeDSeriesInput = {
+    /** Resolved series display name (legend / y-axis label). */
+    name: string;
+    /** Sanitized numeric values, one per category (gaps allowed). */
+    values: (number | null | undefined)[];
+};
+/** [x = category index, y = series index, z = value] */
+export type ThreeDPoint = [number, number, number];
+/** Number of categories = the longest series' value count. */
+export declare const getCategoryCount: (series: ThreeDSeriesInput[]) => number;
+/**
+ * Shape series values into a single bar3D data array: one point per
+ * (category, series) cell — x is the category index, y the series index
+ * (depth row), z the value. Non-finite values are skipped (no bar).
+ */
+export declare const buildBar3DData: (series: ThreeDSeriesInput[]) => ThreeDPoint[];
+/**
+ * Shape series values into one line3D polyline per series, laid out at the
+ * series' index on the depth (y) axis. Non-finite values are skipped, so
+ * the polyline simply bridges gaps.
+ */
+export declare const buildLine3DSeries: (series: ThreeDSeriesInput[]) => {
+    name: string;
+    data: ThreeDPoint[];
+}[];
+/**
+ * Shape series values into a complete surface grid over the categories (x)
+ * × series (y) plane with the values as z-heights. Surfaces require a
+ * complete grid, so ragged series are padded and non-finite values are
+ * flattened to 0. Points are emitted row-major (per series row, categories
+ * in order), the layout echarts-gl's surface parser expects.
+ */
+export declare const buildSurfaceData: (series: ThreeDSeriesInput[]) => ThreeDPoint[];
+/**
+ * [min, max] of the z values, for the surface visualMap range. Returns
+ * [0, 1] for an empty grid and pads a flat grid (min === max) by 1 so the
+ * visualMap never has a zero-width range.
+ */
+export declare const getValueExtent: (points: ThreeDPoint[]) => [number, number];
+/**
+ * Default z-height color ramp for surface plots (the classic echarts-gl
+ * blue → yellow → red diverging ramp). Used via visualMap.inRange.
+ */
+export declare const SURFACE_COLOR_RAMP: readonly string[];
+export {};
+//# sourceMappingURL=three-d.d.ts.map

package/dist/cjs/utils/three-d.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"three-d.d.ts","sourceRoot":"","sources":["../../../utils/three-d.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,QAAA,MAAM,cAAc,8EAOV,CAAC;AAEX,MAAM,MAAM,gBAAgB,GAAG,CAAC,OAAO,cAAc,CAAC,CAAC,MAAM,CAAC,CAAC;AAE/D,wDAAwD;AACxD,MAAM,MAAM,gBAAgB,GAAG,OAAO,GAAG,QAAQ,GAAG,SAAS,CAAC;AAI9D;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,GAChC,kBAAkB,MAAM,GAAG,IAAI,KAC9B,gBAAgB,GAAG,IAIrB,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,QAAQ,GACnB,MAAM;IAAE,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,GAAG,IAAI,GAAG,SAAS,KAC3D,OAAgE,CAAC;AAEpE;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB,GAC9B,kBAAkB,MAAM,GAAG,IAAI,KAC9B,gBAAgB,GAAG,IAcrB,CAAC;AAEF,MAAM,MAAM,iBAAiB,GAAG;IAC9B,4DAA4D;IAC5D,IAAI,EAAE,MAAM,CAAC;IACb,iEAAiE;IACjE,MAAM,EAAE,CAAC,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC,EAAE,CAAC;CACvC,CAAC;AAEF,wDAAwD;AACxD,MAAM,MAAM,WAAW,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;AAKnD,8DAA8D;AAC9D,eAAO,MAAM,gBAAgB,GAAI,QAAQ,iBAAiB,EAAE,KAAG,MACO,CAAC;AAEvE;;;;GAIG;AACH,eAAO,MAAM,cAAc,GAAI,QAAQ,iBAAiB,EAAE,KAAG,WAAW,EAUvE,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,GAC5B,QAAQ,iBAAiB,EAAE,KAC1B;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,WAAW,EAAE,CAAA;CAAE,EASpC,CAAC;AAEL;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB,GAC3B,QAAQ,iBAAiB,EAAE,KAC1B,WAAW,EAcb,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,cAAc,GAAI,QAAQ,WAAW,EAAE,KAAG,CAAC,MAAM,EAAE,MAAM,CASrE,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,kBAAkB,EAAE,SAAS,MAAM,EAY/C,CAAC"}