@bicharts/chart-host 0.5.98 → 0.5.99

package/dist/index.mjs

@@ -11,13 +11,15 @@ import {
   ANIM_PLAY_SPEED_MAX,
   ANIM_PLAY_SPEED_MIN,
   APPROXIMATE_POSITIONS_DEFAULT,
+  AUTO_RAMP_CLASSES,
+  AUTO_RAMP_DRAWN_OPACITY,
+  AUTO_RAMP_MIN_STEP_DELTA_E,
   AXIS_FILTER_CLASS,
   AXIS_PIN_BAND_PAD_PX,
   AXIS_PIN_MAX_BAND_FRACTION,
   AXIS_PIN_MIN_LABELS,
   AXIS_PIN_TRACK_REACH_PX,
   BACKING_MAJORITY,
-  Bt,
   COLOR_SCALE_SELF_CLAMP_PCT_DEFAULT,
   COLOR_SCALE_SELF_CLAMP_PCT_MAX,
   COLOR_SCALE_SELF_CLAMP_PCT_MIN,
@@ -28,20 +30,20 @@ import {
   DARK_TEXT,
   DIM_OPACITY_DEFAULT,
   DIM_OPACITY_VAR,
-  De,
-  Ee,
   FIT_CONTENT_SELECTOR,
   FLIP_MODE_DEFAULT,
   GEO_POINT_PRECISIONS,
   GLYPH_SAMPLE_N,
   HOST_CONTAINER_CLASS,
   HOST_CONTRACT_VERSION,
+  Kt,
   L3,
   LABEL_CONTRAST_CAP,
   LABEL_CONTRAST_DONE_ATTR,
   LEGEND_MARK_CLASS,
   LIFT_SELECTED_CLASS,
   LIGHT_TEXT,
+  Le,
   MARK_CLASS,
   MARK_SELECTED_CLASS,
   MAX_FRAME_GROW_FACTOR,
@@ -49,6 +51,7 @@ import {
   MIN_CONTRAST,
   MIN_HIT_BAND_PX,
   MIN_RAMP_FILLS,
+  Oe,
   PAGE_MATCH_TOLERANCE,
   PHANTOM_FRACTION,
   PILL_MIN_ALPHA,
@@ -60,10 +63,13 @@ import {
   SEASONAL_MARKERS_DEFAULT,
   SELECTION_ACTIVE_CLASS,
   VALUE_AXIS_BASELINE_DEFAULT,
+  VALUE_AXIS_MIN_FIT,
   WHITE_TEXT_BG_LUM,
   XFILTER_REFRESH_EVENT,
   Yt,
   applyLabelContrast,
+  autoRampCanvas,
+  autoRampMinStep,
   axisPinPlacement,
   backingHoldsGlyph,
   blankRenderFlag,
@@ -72,6 +78,7 @@ import {
   censusColourSpread,
   censusHitBands,
   censusMarks,
+  censusValuePlacement,
   chartOwnsTimeline,
   clearGeoCache,
   colourSpreadFlag,
@@ -111,6 +118,7 @@ import {
   registerGeoAsset,
   relativeLuminance,
   requiredD3Plugins,
+  resolveAutoColorScale,
   resolveOptions,
   scrollFitFor,
   sessionViewStateProvider,
@@ -118,8 +126,9 @@ import {
   svgInkReach,
   toRGBA,
   u,
-  unpinScrolledAxis
-} from "./chunk-TORJ77G7.mjs";
+  unpinScrolledAxis,
+  valuePlacementFlag
+} from "./chunk-B2DWID7P.mjs";
 import "./chunk-A2GMXZP7.mjs";
 import "./chunk-GHODWOAL.mjs";
 
@@ -1239,15 +1248,15 @@ function displayText(col, raw, opts) {
   return String(raw);
 }
 function isSuppressed(col) {
-  return Ee(col).suppressed;
+  return Oe(col).suppressed;
 }
 function resolveAgg(col, requested, auto) {
   const fallback = () => {
-    const d2 = Bt(col);
+    const d2 = Yt(col);
     return d2 === "first" ? "count" : d2;
   };
   if (auto) return fallback();
-  return De(col).indexOf(requested) >= 0 ? requested : fallback();
+  return Le(col).indexOf(requested) >= 0 ? requested : fallback();
 }
 function toNumber(v2) {
   if (v2 == null || v2 === "") return null;
@@ -1350,7 +1359,7 @@ function computeSelectionCard(payload, selectedRowIdxs, opts = {}) {
     }
     const value = reduce(selVals, colAgg, selRaw);
     let sharePct = null;
-    if (Yt(col, colAgg) && value != null) {
+    if (Kt(col, colAgg) && value != null) {
       const allVals = [];
       const allRaw = [];
       for (let r2 = 0; r2 < rows.length; r2++) {
@@ -2099,6 +2108,9 @@ export {
   ANIM_PLAY_SPEED_MAX,
   ANIM_PLAY_SPEED_MIN,
   APPROXIMATE_POSITIONS_DEFAULT,
+  AUTO_RAMP_CLASSES,
+  AUTO_RAMP_DRAWN_OPACITY,
+  AUTO_RAMP_MIN_STEP_DELTA_E,
   AXIS_FILTER_CLASS,
   AXIS_PIN_BAND_PAD_PX,
   AXIS_PIN_MAX_BAND_FRACTION,
@@ -2154,11 +2166,14 @@ export {
   SEASONAL_MARKERS_DEFAULT,
   SELECTION_ACTIVE_CLASS,
   VALUE_AXIS_BASELINE_DEFAULT,
+  VALUE_AXIS_MIN_FIT,
   WHITE_TEXT_BG_LUM,
   XFILTER_REFRESH_EVENT,
   actionFor,
   applyLabelContrast,
   askApplyImprovements,
+  autoRampCanvas,
+  autoRampMinStep,
   axisPinPlacement,
   backingHoldsGlyph,
   bareBase64,
@@ -2173,6 +2188,7 @@ export {
   censusColourSpread,
   censusHitBands,
   censusMarks,
+  censusValuePlacement,
   chartOwnsTimeline,
   chooserFitsViewport,
   clearGeoCache,
@@ -2248,6 +2264,7 @@ export {
   registerGeoAsset,
   relativeLuminance,
   requiredD3Plugins,
+  resolveAutoColorScale,
   resolveOptions,
   scrollFitFor,
   sessionViewStateProvider,
@@ -2259,5 +2276,6 @@ export {
   svgNaturalSize,
   svgToDataUrl,
   toRGBA,
-  unpinScrolledAxis
+  unpinScrolledAxis,
+  valuePlacementFlag
 };

package/dist/react.mjs

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

package/dist/types/autoRamp.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Classes the automatic ramp must keep apart. A binned legend rarely carries more than seven, and
+ * the chart that raised this drew six; ColorBrewer's sequential schemes stop at nine because past
+ * that no ramp of one hue separates its neighbours. A chart drawing fewer classes gets wider steps.
+ */
+export declare const AUTO_RAMP_CLASSES = 7;
+/**
+ * The fill-opacity the guarantee is made at. Dense dot charts paint at 0.5 so overlaps stay
+ * readable, and that halves every colour difference against a light canvas; a guarantee made at
+ * full opacity would be broken by exactly the charts that need it most. Opaque fills get more.
+ */
+export declare const AUTO_RAMP_DRAWN_OPACITY = 0.5;
+/**
+ * Minimum CIEDE2000 between neighbouring classes as painted: 2.3, the just-noticeable difference
+ * usually quoted for colour patches side by side. CIEDE2000 was fitted so that its own threshold
+ * sits nearer 1, so this errs towards more separation, which is the safe direction for a legend.
+ */
+export declare const AUTO_RAMP_MIN_STEP_DELTA_E = 2.3;
+export interface AutoColorScaleInput {
+    palette?: string[] | null;
+    backgroundColor?: string | null;
+    themeBg?: string | null;
+    themeFg?: string | null;
+    themeAccent?: string | null;
+    isHighContrast?: boolean | null;
+}
+export interface AutoColorScale {
+    low: string;
+    high: string;
+}
+/** The smallest neighbour-to-neighbour distance of the ramp, as painted. */
+export declare function autoRampMinStep(low: string, high: string, canvas: string, classes?: number, opacity?: number): number;
+/** The canvas the ramp is painted on: the visual's own background, else the theme's, else white. */
+export declare function autoRampCanvas(p: AutoColorScaleInput): string;
+/**
+ * The automatic Low and High colours for a continuous colour scale. Deterministic, never throws,
+ * and cheap enough to call on every render (the last answer is kept for the same inputs).
+ */
+export declare function resolveAutoColorScale(p: AutoColorScaleInput): AutoColorScale;

package/dist/types/contract.d.ts

@@ -1,4 +1,4 @@
-export declare const HOST_CONTRACT_VERSION = "1.7.0";
+export declare const HOST_CONTRACT_VERSION = "1.8.0";
 export type GeoPointPrecision = "latlon" | "city" | "zip3" | "state" | "country";
 /** Every valid tier, ordered most precise → coarsest. Runtime form of GeoPointPrecision. */
 export declare const GEO_POINT_PRECISIONS: readonly GeoPointPrecision[];
@@ -111,6 +111,8 @@ export interface RenderOptions {
     seasonalMarkers?: SeasonalMarkers;
     colorScaleLow?: string;
     colorScaleHigh?: string;
+    colorScaleAutoLow?: string;
+    colorScaleAutoHigh?: string;
     colorScaleScope?: ColorScaleScope;
     colorScaleSelfClampPct?: number;
     geoLandColor?: string;

package/dist/types/deltaE.d.ts

@@ -20,5 +20,11 @@ export declare function hexToLab(hex: string): Lab | null;
  * sequential ramp spends most of its length in.
  */
 export declare function deltaE2000(c1: Lab, c2: Lab): number;
+/**
+ * CIE L*a*b* (D65) back to `#rrggbb`: the exact inverse of `rgbToLab`, with each channel clipped
+ * into the sRGB gamut. A Lab point outside the gamut comes back as the nearest channel-clipped
+ * colour, which is what a browser would paint anyway.
+ */
+export declare function labToHex(lab: Lab): string;
 /** CIEDE2000 between two `#rrggbb` colours. NaN when either cannot be parsed. */
 export declare function deltaEHex(a: string, b: string): number;

package/dist/types/host.d.ts

@@ -3,6 +3,7 @@ import { type ResolveOptionsInput } from "./defaults";
 import { type MarkCensus } from "./blankRender";
 import { type HitBandCensus } from "./hitBands";
 import { type ColourSpreadCensus } from "./colourSpread";
+import { type ValuePlacementCensus } from "./valuePlacement";
 import { type FitRenderedChartOptions, type FitRenderedChartResult } from "./fitDom";
 import { type LabelContrastOptions, type LabelContrastReport } from "./labelContrastDom";
 export type RenderFn = (container: HTMLElement, data: any, options: RenderOptions) => void;
@@ -108,6 +109,17 @@ export interface ChartHostConfig {
      * own skew is measured on the raw column while the ramp encodes an aggregate.
      */
     onColourSpreadCensus?: (census: ColourSpreadCensus) => void;
+    /**
+     * IS EACH DOT DRAWN AT ITS VALUE? Runs after every render, counts only.
+     *
+     * A chart drawing one dot per row along a value axis promises that a dot's position IS its
+     * value, and a force layout breaks that promise without a trace in the code: collision pushes
+     * dots along both axes, so on a dense column they drift off their values and pile against the
+     * band walls. This reads each single-row circle back to its row, finds the value axis as the
+     * column a straight line through the positions explains, and reports the share of dots more than
+     * a radius off it. It declines on anything that is not that shape.
+     */
+    onValuePlacementCensus?: (census: ValuePlacementCensus) => void;
     /** This chart declares time keyframes: frame one is allowed to be empty, so no blank verdict
      *  is issued for it. */
     animated?: boolean;

package/dist/types/index.d.ts

@@ -23,9 +23,11 @@ export { decideLabelColor, toRGBA, compositeOver, relativeLuminance, contrastRat
 export { censusMarks, isBlankRender, blankRenderFlag, type MarkCensus, type BlankVerdictInput } from "./blankRender";
 export { censusHitBands, hitBandFlag, MIN_HIT_BAND_PX, type HitBandCensus } from "./hitBands";
 export { censusColourSpread, colourSpreadFlag, SAME_SHADE_DELTA_E, MIN_RAMP_FILLS, type ColourSpreadCensus } from "./colourSpread";
+export { censusValuePlacement, valuePlacementFlag, VALUE_AXIS_MIN_FIT, type ValuePlacementCensus } from "./valuePlacement";
 export { SCROLL_SLACK_PX, MAX_FRAME_GROW_FACTOR, PHANTOM_FRACTION, FIT_CONTENT_SELECTOR, needsScroll, contentExtentOf, scrollFitFor, planFrameGrow, isPhantomBox, type MeasuredBox, type ContentExtent, type ScrollFit, type FrameGrowPlan, } from "./fit";
 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, LEGIBLE_LIGHTNESS, type PaletteResult, type SeedForSlot, type PaletteOptions, } from "./palette";
 export { deltaEHex } from "./deltaE";
+export { resolveAutoColorScale, autoRampMinStep, autoRampCanvas, AUTO_RAMP_CLASSES, AUTO_RAMP_DRAWN_OPACITY, AUTO_RAMP_MIN_STEP_DELTA_E, type AutoColorScale, type AutoColorScaleInput } from "./autoRamp";

package/dist/types/valuePlacement.d.ts

@@ -0,0 +1,34 @@
+/** A straight line must explain at least this share of the positions to call it the value axis. */
+export declare const VALUE_AXIS_MIN_FIT = 0.8;
+export interface ValuePlacementCensus {
+    /** Dots measured: circles carrying exactly one row index. 0 = the census declined. */
+    marks: number;
+    /** The screen axis the values run along, and the column they encode. */
+    axis: "x" | "y" | "";
+    column: string;
+    /** How well the fitted line explains the positions (1 = every dot on its value). */
+    fit: number;
+    /** Share (0-100) of the dots more than one radius from their value. */
+    offShare: number;
+    /** Median distance, in radii, between a dot and its value. */
+    medianOffRadii: number;
+}
+/**
+ * Where do the dots sit against their values? Never throws; declines with `marks: 0`.
+ * `rows` are the rows the chart was handed, indexed exactly as data-row-idx indexes them.
+ */
+export declare function censusValuePlacement(container: any, data: {
+    columns?: {
+        name: string;
+    }[];
+    rows?: any[][];
+} | null | undefined): ValuePlacementCensus;
+/**
+ * The always-on behaviour tag, or "" when the census declined.
+ *
+ * `place:d3:off0` no dot more than a radius from its value; `off1` some, under 5%; `off5` 5-20%;
+ * `off20` 20-50%; `off50` half or more. Finer at the bottom than the colour census's twenty-point
+ * buckets on purpose: a correct layout reports exactly zero, so the first few percent are the
+ * interesting ones.
+ */
+export declare function valuePlacementFlag(c: ValuePlacementCensus): string;

package/package.json

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