@bicharts/chart-host 0.5.87 → 0.5.89

package/dist/types/index.d.ts

@@ -25,3 +25,4 @@ export { SCROLL_SLACK_PX, MAX_FRAME_GROW_FACTOR, PHANTOM_FRACTION, FIT_CONTENT_S
 export { fitRenderedChart, fitReadingFor, measureContainerBoxes, svgInkReach, ctmScaleOf, type FitReading, type InkReach, type FitRenderedChartOptions, type FitRenderedChartResult, } from "./fitDom";
 export { AXIS_PIN_MIN_LABELS, AXIS_PIN_BAND_PAD_PX, AXIS_PIN_MAX_BAND_FRACTION, AXIS_PIN_TRACK_REACH_PX, isHorizontalLabelRow, labelBand, planAxisPin, axisPinPlacement, type LabelRowBox, type AxisBand, type AxisPinCandidate, type AxisPinPlan, type AxisPinEdge, } from "./fit";
 export { pinScrolledAxis, unpinScrolledAxis, type AxisPinReport } from "./fitDom";
+export { MIN_DELTA_E, pickDistinctColorFromSeed, buildPalette, buildPaletteFromSeed, type PaletteResult, type SeedForSlot, } from "./palette";

package/dist/types/palette.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Minimum perceptual distance (CIE2000 deltaE) that any returned color must
+ * achieve from every previously-issued color. Picked for chart-readable
+ * swatches; JND (just-noticeable-difference) at this scale is ≈5.
+ */
+export declare const MIN_DELTA_E = 10;
+/**
+ * Pick a hex color for a palette slot.
+ *
+ * Strategy (ordered from "closest to theme" to "furthest from theme"):
+ *   1. The seed itself if it's already distant enough.
+ *   2. Saturation walk around the seed (same hue family, in-theme).
+ *   3. Lightness walk around the seed (same hue family, in-theme).
+ *   4. Hue rotation around the seed (drifts off-theme but still tied).
+ *   5. Give up — return the seed. Never random: a slightly-colliding theme
+ *      color reads better than a stranger color.
+ *
+ * The set of `existing` colors is treated as readonly — the caller is
+ * responsible for adding the returned color (and possibly the best-effort
+ * fallback) to their own set when this function returns. We return BOTH the
+ * chosen color AND the colorSet-entry to register, because the give-up case
+ * registers a DIFFERENT value (the best-so-far candidate) than what it
+ * returns (the seed): registering the seed would make a later call think
+ * its slot is empty, but returning the best-so-far would lose theme
+ * fidelity.
+ */
+export interface PaletteResult {
+    /** Hex color to use for this slot. */
+    readonly hex: string;
+    /** Hex color to register in the palette-issued set (may differ from `hex` on the give-up fallback). */
+    readonly registerHex: string;
+}
+export declare function pickDistinctColorFromSeed(seedHex: string, existing: ReadonlySet<string>, minDistance?: number): PaletteResult;
+/**
+ * A whole categorical palette from ONE seed colour.
+ *
+ * THE DIFFERENCE BETWEEN THE TWO HOSTS, and the reason this wrapper exists rather than each
+ * host looping for itself. Power BI hands the visual a DIFFERENT theme colour per slot
+ * (`getColor("1")`, `getColor("2")`, ...), so its loop varies the seed and the walk mostly
+ * settles at step 1. Excel has no such API: a workbook offers ONE resolvable accent - the fill
+ * a themed table style actually painted - so every slot is seeded from the SAME colour and the
+ * walk does the spreading, saturation first, then lightness, then hue.
+ *
+ * That ordering is why one accent is enough to be worth doing. The early slots stay in the
+ * seed's own hue family, so a two- or three-series chart reads as the workbook's colour rather
+ * than as a stranger's; only once those are exhausted does it rotate away. A host with one
+ * brand colour gets a palette that still looks like the brand.
+ *
+ * Deterministic: same seed and count in, same array out, which is what lets a host PERSIST the
+ * result and re-derive it later without the colours shifting under a saved chart.
+ */
+export declare function buildPaletteFromSeed(seedHex: string, count: number, minDistance?: number): string[];
+/**
+ * WHERE EACH SLOT'S BASE COLOUR COMES FROM. Called with the slot index, 0-based.
+ *
+ * Returning a blank or nothing means "no base colour for this slot" - the builder then falls
+ * back to the last one that WAS supplied, so a host whose colour source runs dry degrades into
+ * spreading rather than into a gap.
+ */
+export type SeedForSlot = (slot: number) => string | null | undefined;
+/**
+ * The general form: a palette whose BASE COLOURS the host decides, slot by slot.
+ *
+ * THIS IS THE RICH FORM AND `buildPaletteFromSeed` IS THE DEGENERATE ONE. Read that sentence
+ * before "simplifying" a host onto the single-seed call, because the difference is a real loss
+ * and it is invisible in the output - both return a plausible list of distinct colours.
+ *
+ * Power BI hands a visual a DIFFERENT theme colour per slot (`colorPalette.getColor("1")`,
+ * `getColor("2")`, ...). Every one of those is a deliberate choice by whoever built the report
+ * theme, and feeding them in per slot means the walk usually settles at step 1 and RETURNS THEM
+ * UNCHANGED - the chart is coloured by the theme, not by our arithmetic. Collapse that host onto
+ * one seed and twenty authored colours become one authored colour plus nineteen derived ones:
+ * still distinct, still pretty, and no longer the report's.
+ *
+ * A host with no such API - an Excel workbook offers exactly one resolvable accent - passes a
+ * constant provider and the walk does the spreading. That is a fallback, not the design.
+ */
+export declare function buildPalette(seedFor: SeedForSlot, count: number, minDistance?: number): string[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bicharts/chart-host",
-  "version": "0.5.87",
+  "version": "0.5.89",
   "description": "Run a BIC-generated D3 chart in any web host: compiles the generated render() function, applies the shared option defaults, resolves mark clicks (through tooltip overlays), owns the selection affordance, and translates row indices between cross-filtered charts. The same contract the BIC Power BI visual implements, minus Power BI. React bindings at @bicharts/chart-host/react.",
   "license": "Apache-2.0",
   "type": "module",
@@ -68,6 +68,7 @@
   "// devDependencies": "@bicharts/shape-core is deliberately NOT declared. It is a workspace sibling that npm links regardless, and its code is BUNDLED into dist, so a consumer never installs it. Declaring it made this package a registry DEPENDENT of shape-core, which blocks lifecycle operations on that package in exchange for nothing. Do not add it back; if the build stops resolving it, fix the workspace, not the manifest.",
   "devDependencies": {
     "@types/react": "^19.2.17",
+    "colorsea": "^1.2.2",
     "esbuild": "^0.28.1",
     "react": "^19.2.8",
     "react-dom": "^19.2.8",