@bicharts/chart-host 0.5.94 → 0.5.95

package/dist/index.mjs

@@ -1941,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();
@@ -1952,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();
@@ -1977,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();
@@ -1999,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) {
@@ -2120,6 +2128,7 @@ export {
   LABEL_CONTRAST_CAP,
   LABEL_CONTRAST_DONE_ATTR,
   LEGEND_MARK_CLASS,
+  LEGIBLE_LIGHTNESS,
   LIFT_SELECTED_CLASS,
   LIGHT_TEXT,
   MARK_CLASS,

package/dist/types/index.d.ts

@@ -27,5 +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, orderMostDistinct, 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,7 +99,7 @@ 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.
  *

package/package.json

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