@bicharts/chart-host 0.5.93 → 0.5.95

package/dist/{chunk-BWOY6GDX.mjs → chunk-IIBDCQJM.mjs}

@@ -1868,6 +1868,10 @@ function deltaE2000(c1, c2) {
   const tL = dLp / SL, tC = dCp / SC, tH = dHp / SH;
   return Math.sqrt(tL * tL + tC * tC + tH * tH + RT * tC * tH);
 }
+function deltaEHex(a4, b2) {
+  const la = hexToLab(a4), lb = hexToLab(b2);
+  return la && lb ? deltaE2000(la, lb) : NaN;
+}
 
 // src/colourSpread.ts
 var SAME_SHADE_DELTA_E = 5;
@@ -3223,6 +3227,7 @@ export {
   MIN_HIT_BAND_PX,
   censusHitBands,
   hitBandFlag,
+  deltaEHex,
   SAME_SHADE_DELTA_E,
   MIN_RAMP_FILLS,
   censusColourSpread,

package/dist/index.mjs

@@ -81,6 +81,7 @@ import {
   createMarkResolver,
   ctmScaleOf,
   decideLabelColor,
+  deltaEHex,
   ensureCrossfilterHitTargets,
   explainRenderFailure,
   fitReadingFor,
@@ -116,7 +117,7 @@ import {
   toRGBA,
   u,
   unpinScrolledAxis
-} from "./chunk-BWOY6GDX.mjs";
+} from "./chunk-IIBDCQJM.mjs";
 import "./chunk-A2GMXZP7.mjs";
 import "./chunk-GHODWOAL.mjs";
 
@@ -1940,9 +1941,16 @@ Mt.config = function(t2) {
 
 // src/palette.ts
 var MIN_DELTA_E = 10;
-function pickDistinctColorFromSeed(seedHex, existing, minDistance = MIN_DELTA_E) {
+var LEGIBLE_LIGHTNESS = [15, 85];
+function pickDistinctColorFromSeed(seedHex, existing, minDistance = MIN_DELTA_E, options = {}) {
   const existingCs = [...existing].map((c2) => Mt(c2));
   const seed = Mt(seedHex);
+  const band = options.lightnessBand === void 0 ? LEGIBLE_LIGHTNESS : options.lightnessBand;
+  const legible = (c2) => {
+    if (!band) return true;
+    const l2 = c2.hsl()[2];
+    return l2 > band[0] && l2 < band[1];
+  };
   const minDeltaE = (c2) => existingCs.length === 0 ? Number.POSITIVE_INFINITY : Math.min(...existingCs.map((c22) => c2.deltaE(c22, "CIE2000")));
   if (minDeltaE(seed) >= minDistance) {
     const hex = seed.hex();
@@ -1951,6 +1959,7 @@ function pickDistinctColorFromSeed(seedHex, existing, minDistance = MIN_DELTA_E)
   let bestCandidate = seed;
   let bestMinDist = minDeltaE(seed);
   const tryVariant = (c2) => {
+    if (!legible(c2)) return null;
     const d2 = minDeltaE(c2);
     if (d2 >= minDistance) {
       const hex = c2.hex();
@@ -1976,10 +1985,10 @@ function pickDistinctColorFromSeed(seedHex, existing, minDistance = MIN_DELTA_E)
   }
   return { hex: seed.hex(), registerHex: bestCandidate.hex() };
 }
-function buildPaletteFromSeed(seedHex, count, minDistance = MIN_DELTA_E) {
-  return buildPalette(() => seedHex, count, minDistance);
+function buildPaletteFromSeed(seedHex, count, minDistance = MIN_DELTA_E, options = {}) {
+  return buildPalette(() => seedHex, count, minDistance, options);
 }
-function buildPalette(seedFor, count, minDistance = MIN_DELTA_E) {
+function buildPalette(seedFor, count, minDistance = MIN_DELTA_E, options = {}) {
   const out = [];
   if (!(count > 0)) return out;
   const issued = /* @__PURE__ */ new Set();
@@ -1998,7 +2007,7 @@ function buildPalette(seedFor, count, minDistance = MIN_DELTA_E) {
     if (!seedHex) seedHex = lastSeed;
     if (!seedHex) break;
     lastSeed = seedHex;
-    const { hex, registerHex } = pickDistinctColorFromSeed(seedHex, issued, minDistance);
+    const { hex, registerHex } = pickDistinctColorFromSeed(seedHex, issued, minDistance, options);
     let chosen = hex;
     let register = registerHex;
     if (distance(chosen) < minDistance) {
@@ -2027,6 +2036,33 @@ function buildPalette(seedFor, count, minDistance = MIN_DELTA_E) {
   }
   return out;
 }
+function orderMostDistinct(lead, pool) {
+  const seen = /* @__PURE__ */ new Set();
+  const valid = [];
+  const take = (c2) => {
+    const s2 = typeof c2 === "string" ? c2.trim() : "";
+    if (!s2 || !Number.isFinite(deltaEHex(s2, s2))) return;
+    const key = s2.toLowerCase();
+    if (seen.has(key)) return;
+    seen.add(key);
+    valid.push(s2);
+  };
+  take(lead);
+  for (const c2 of pool ?? []) take(c2);
+  if (!valid.length) return [];
+  const out = [valid[0]];
+  const rest = valid.slice(1);
+  const nearest = rest.map((c2) => deltaEHex(c2, out[0]));
+  while (rest.length) {
+    let best = 0;
+    for (let i2 = 1; i2 < rest.length; i2++) if (nearest[i2] > nearest[best]) best = i2;
+    const picked = rest.splice(best, 1)[0];
+    nearest.splice(best, 1);
+    out.push(picked);
+    for (let i2 = 0; i2 < rest.length; i2++) nearest[i2] = Math.min(nearest[i2], deltaEHex(rest[i2], picked));
+  }
+  return out;
+}
 function normalise(seed) {
   return typeof seed === "string" ? seed.trim() : "";
 }
@@ -2092,6 +2128,7 @@ export {
   LABEL_CONTRAST_CAP,
   LABEL_CONTRAST_DONE_ATTR,
   LEGEND_MARK_CLASS,
+  LEGIBLE_LIGHTNESS,
   LIFT_SELECTED_CLASS,
   LIGHT_TEXT,
   MARK_CLASS,
@@ -2149,6 +2186,7 @@ export {
   createMarkResolver,
   ctmScaleOf,
   decideLabelColor,
+  deltaEHex,
   ensureCrossfilterHitTargets,
   explainRenderFailure,
   filterFitsChooser,
@@ -2179,6 +2217,7 @@ export {
   noopViewStateProvider,
   normaliseAggregation,
   normalizeFilterTerm,
+  orderMostDistinct,
   orderRefusalsForDisplay,
   periodTickSuppressesFeedback,
   pickDistinctColorFromSeed,

package/dist/react.mjs

@@ -4,7 +4,7 @@ import {
   createChartHost,
   geoFromCache,
   loadGeo
-} from "./chunk-BWOY6GDX.mjs";
+} from "./chunk-IIBDCQJM.mjs";
 import "./chunk-A2GMXZP7.mjs";
 import "./chunk-GHODWOAL.mjs";
 

package/dist/types/index.d.ts

@@ -27,4 +27,5 @@ 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";
+export { MIN_DELTA_E, pickDistinctColorFromSeed, buildPalette, buildPaletteFromSeed, orderMostDistinct, LEGIBLE_LIGHTNESS, type PaletteResult, type SeedForSlot, type PaletteOptions, } from "./palette";
+export { deltaEHex } from "./deltaE";

package/dist/types/palette.d.ts

@@ -4,6 +4,30 @@
  * swatches; JND (just-noticeable-difference) at this scale is ≈5.
  */
 export declare const MIN_DELTA_E = 10;
+/**
+ * THE LIGHTNESS A COLOUR THE WALK INVENTS MUST FALL INSIDE (HSL lightness, 0-100, exclusive).
+ *
+ * The walk's lightness step moves the seed up to 45 points, so from a light seed it could land on
+ * a near-white - and a categorical mark that is near-white on a white page, or near-black on a dark
+ * one, is not a colour a reader can find. Measured before this band existed: a green seed's
+ * twenty-slot palette put `#ebf4e5` (lightness 93) in slot 7, and a pool of Office theme colours led
+ * by a red put `#d5e5f4` (90) in slot 17.
+ *
+ * INVENTED COLOURS ONLY. A seed the host supplied comes back as supplied, however light or dark -
+ * that is a report author's decision - and the spare-colour sweep keeps its own, narrower band.
+ */
+export declare const LEGIBLE_LIGHTNESS: readonly [number, number];
+export interface PaletteOptions {
+    /**
+     * The lightness band invented colours must sit in. Defaults to `LEGIBLE_LIGHTNESS`.
+     *
+     * `null` walks as the package did before the band existed, colour for colour. It exists for a
+     * host that STORED palettes the older walk produced and has to recognise one again by
+     * re-deriving it: change the walk under such a host and every stored palette silently stops
+     * matching. Nothing should draw with it.
+     */
+    lightnessBand?: readonly [number, number] | null;
+}
 /**
  * Pick a hex color for a palette slot.
  *
@@ -30,7 +54,7 @@ export interface PaletteResult {
     /** 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;
+export declare function pickDistinctColorFromSeed(seedHex: string, existing: ReadonlySet<string>, minDistance?: number, options?: PaletteOptions): PaletteResult;
 /**
  * A whole categorical palette from ONE seed colour.
  *
@@ -49,7 +73,7 @@ export declare function pickDistinctColorFromSeed(seedHex: string, existing: Rea
  * 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[];
+export declare function buildPaletteFromSeed(seedHex: string, count: number, minDistance?: number, options?: PaletteOptions): string[];
 /**
  * WHERE EACH SLOT'S BASE COLOUR COMES FROM. Called with the slot index, 0-based.
  *
@@ -75,4 +99,32 @@ export type SeedForSlot = (slot: number) => string | null | undefined;
  * 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[];
+export declare function buildPalette(seedFor: SeedForSlot, count: number, minDistance?: number, options?: PaletteOptions): string[];
+/**
+ * A POOL OF ACCEPTABLE COLOURS, ORDERED SO THE MOST DISTINCT COME FIRST.
+ *
+ * For a host that knows WHICH colours belong to the surface but not in what ORDER to use them.
+ * Excel is the case that needed it: a workbook's theme offers a grid of accents and their tints,
+ * none of which is ranked, and the order a host invents decides what a two- or five-series chart
+ * looks like. The order Office itself lists its accents in puts two blues four slots apart, so a
+ * five-series chart following that list gives two of its series nearly the same colour - which
+ * reads as one series.
+ *
+ * NEVER USE THIS ON AN AUTHORED ORDER. A report theme's slot order is somebody's decision, and
+ * `buildPalette` exists to honour it verbatim; re-sorting it here would override the author with
+ * arithmetic. This is only for a pool a host assembled itself.
+ *
+ * The method is greedy max-min (the farthest-point walk used for categorical colour sets): keep
+ * the lead, then repeatedly take the pool colour whose NEAREST already-chosen colour is farthest
+ * away, by CIEDE2000. Two properties follow and the tests pin both. The distance each pick adds is
+ * never larger than the one before it, so the early slots, which every chart uses, are the best
+ * separated. And every input colour is returned unchanged, so the palette is still the surface's
+ * own colours, only re-ordered.
+ *
+ * Deterministic: ties go to the colour listed earlier in the pool. Duplicates (case-insensitive)
+ * and anything that is not `#rgb` / `#rrggbb` are dropped, because a colour that cannot be
+ * measured cannot be placed. A blank or unmeasurable lead means "start from the pool's first
+ * colour". Feed the result to `buildPalette`, which still guarantees the minimum separation when
+ * two pool colours are too close to share a legend.
+ */
+export declare function orderMostDistinct(lead: string | null | undefined, pool: readonly string[]): string[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bicharts/chart-host",
-  "version": "0.5.93",
+  "version": "0.5.95",
   "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",