@bicharts/chart-host 0.5.89 → 0.5.90

package/dist/react.mjs

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

package/dist/types/colourSpread.d.ts

@@ -0,0 +1,75 @@
+/**
+ * CIE2000 distance at which two fills stop being separable at a glance, side by side on a chart.
+ *
+ * Not a tuned parameter — a perceptual constant. 1.0 is the textbook just-noticeable difference
+ * under laboratory conditions with the two patches touching; 5 is the conventional "clearly
+ * different to an ordinary observer in ordinary conditions", which is what a reader scanning a
+ * choropleth is. Erring high is the safe direction: it makes the census UNDERstate crowding.
+ */
+export declare const SAME_SHADE_DELTA_E = 5;
+/**
+ * Fewer distinct fills than this and there is nothing to characterise.
+ *
+ * Four is the floor for the collinearity test below, not a judgement: the two extremes anchor the
+ * line, so a fourth fill is the second interior point and the first one that can disagree.
+ */
+export declare const MIN_RAMP_FILLS = 4;
+/**
+ * How far off a straight line a set of fills may sit and still be a RAMP.
+ *
+ * THIS IS WHAT SEPARATES A VALUE-ENCODED COLOUR CHANNEL FROM A CATEGORICAL ONE, and counting
+ * fills cannot do it. The obvious "at least six distinct colours" rule fails at exactly the
+ * wrong moment: a five-bin quantile scale — the recommended REMEDY for the washout this census
+ * exists to find — has five fills, so a count floor would have excluded the charts that did the
+ * right thing and biased the prevalence it was built to measure.
+ *
+ * A sequential ramp is, by construction, a path between two colours: every fill lies close to the
+ * segment joining its extremes, so `d(lo,x) + d(x,hi)` barely exceeds `d(lo,hi)`. A categorical
+ * scheme is chosen for mutual separation and its members sit well off that line. Measured in
+ * CIE2000 over the standard schemes, the two populations do not overlap:
+ *
+ * ```text
+ *   interpolateBlues (5, 8 and 40 stops)  mean slack  -0.05        SEQUENTIAL
+ *   interpolateReds (8)                   mean slack  +0.06        SEQUENTIAL
+ *   viridis (8)                           mean slack  +0.02        SEQUENTIAL
+ *   schemeTableau10 (5 and 8)             mean slack  +0.24        categorical
+ *   RdBu diverging (7)                    mean slack  +0.35        two arms, not one line
+ * ```
+ *
+ * 0.15 sits in the four-fold gap. A DIVERGING ramp landing outside is correct rather than a miss:
+ * it is genuinely two paths from a neutral middle, and measuring it as one would report the arm
+ * that happened to be longer. It is excluded and said so, not mismeasured.
+ */
+export declare const RAMP_SLACK_MAX = 0.15;
+export interface ColourSpreadCensus {
+    /** Marks carrying a resolvable, non-transparent fill. */
+    marks: number;
+    /** Distinct fills among them, before quantisation. */
+    distinctFills: number;
+    /** Share (0-100) of marks whose fill is within SAME_SHADE_DELTA_E of the most crowded fill. */
+    crowdShare: number;
+    /** Largest CIE2000 distance between any two sampled fills — the ramp's perceptual reach. */
+    spanDeltaE: number;
+}
+/**
+ * How much of this chart is one shade?
+ *
+ * Never throws. Telemetry must not be the reason a delivered render fails, and an environment
+ * that cannot report a fill reports nothing rather than a number that describes the environment.
+ *
+ * KNOWN LIMIT, stated rather than hidden: a DIVERGING ramp is measured the same way as any
+ * other, so a chart whose two arms are each well spread but which crowds around its neutral
+ * midpoint reports honestly, while one that crowds at BOTH ends reports the larger arm only. That
+ * understates rather than overstates, which is the direction an audit should err.
+ */
+export declare function censusColourSpread(container: any, doc?: any): ColourSpreadCensus;
+/**
+ * The always-on behaviour tag, or "" when the census had nothing to say.
+ *
+ * A BUCKETED MEASUREMENT, NOT A VERDICT. `ramp:d3:crowd60` says three in five marks are one
+ * shade; it does not say that is wrong. Twenty-point buckets are coarse enough to read as a
+ * distribution off a few hundred renders and fine enough to separate "a bit clustered" from the
+ * failure this exists for, and the whole family is one `LIKE 'ramp:d3:crowd%'` away — which is
+ * the denominator any rate needs. When the distribution is in, a cut can be argued from it.
+ */
+export declare function colourSpreadFlag(c: ColourSpreadCensus): string;

package/dist/types/host.d.ts

@@ -2,6 +2,7 @@ import { type RenderOptions, type ViewStateProvider } from "./contract";
 import { type ResolveOptionsInput } from "./defaults";
 import { type MarkCensus } from "./blankRender";
 import { type HitBandCensus } from "./hitBands";
+import { type ColourSpreadCensus } from "./colourSpread";
 import { type FitRenderedChartOptions, type FitRenderedChartResult } from "./fitDom";
 import { type LabelContrastOptions, type LabelContrastReport } from "./labelContrastDom";
 export type RenderFn = (container: HTMLElement, data: any, options: RenderOptions) => void;
@@ -92,6 +93,21 @@ export interface ChartHostConfig {
      * number only the browser knows, and this reads the COMPUTED width off the rendered element.
      */
     onHitBandCensus?: (census: HitBandCensus) => void;
+    /**
+     * HOW MUCH OF THIS CHART IS ONE SHADE (2026-09-09)? Runs after every render, counts only.
+     *
+     * The sibling question to the hit-band census, on the colour channel: a right-skewed measure
+     * on a linear ramp is accurate and unreadable, because the outliers eat the ramp and the
+     * dense bulk lands in one indistinguishable tint. It measures the OUTCOME, never the scale,
+     * so a well-spread scale of any kind reports well and a curved or hand-rolled ramp needs no
+     * special case; it declines outright on a categorical palette or a diverging ramp, which are
+     * a different question wearing the same numbers.
+     *
+     * The other half a server-side check cannot do. A code rule reads `scaleLinear()` and a
+     * domain built from `d3.max`; whether THAT washes out depends on the data, and the shape's
+     * own skew is measured on the raw column while the ramp encodes an aggregate.
+     */
+    onColourSpreadCensus?: (census: ColourSpreadCensus) => 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

@@ -21,6 +21,7 @@ export { applyLabelContrast, LABEL_CONTRAST_DONE_ATTR, LABEL_CONTRAST_CAP, type
 export { decideLabelColor, toRGBA, compositeOver, relativeLuminance, contrastRatio, isPillBackdropAlpha, pillBacksGlyph, backingHoldsGlyph, cellSuppressesNormalize, glyphSampleGrid, DARK_TEXT, LIGHT_TEXT, MIN_CONTRAST, WHITE_TEXT_BG_LUM, PILL_MIN_ALPHA, PILL_OPAQUE_ALPHA, PILL_MIN_COVERAGE, PAGE_MATCH_TOLERANCE, BACKING_MAJORITY, GLYPH_SAMPLE_N, type LabelDecision, } from "./labelContrast";
 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 { 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";

package/package.json

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