@bicharts/chart-host 0.5.72 → 0.5.74

package/dist/index.mjs

@@ -11,7 +11,7 @@ import {
   ANIM_PLAY_SPEED_MIN,
   APPROXIMATE_POSITIONS_DEFAULT,
   AXIS_FILTER_CLASS,
-  At,
+  BACKING_MAJORITY,
   COLOR_SCALE_SELF_CLAMP_PCT_DEFAULT,
   COLOR_SCALE_SELF_CLAMP_PCT_MAX,
   COLOR_SCALE_SELF_CLAMP_PCT_MIN,
@@ -19,65 +19,88 @@ import {
   CONTAINER_SLOT_INITIAL_XF_MARK,
   CONTAINER_SLOT_UI_STATE,
   CONTAINER_SLOT_XF_CLEAR,
+  DARK_TEXT,
   DIM_OPACITY_DEFAULT,
   DIM_OPACITY_VAR,
   FIT_CONTENT_SELECTOR,
   FLIP_MODE_DEFAULT,
   GEO_POINT_PRECISIONS,
+  GLYPH_SAMPLE_N,
   HOST_CONTAINER_CLASS,
   HOST_CONTRACT_VERSION,
   L3,
+  LABEL_CONTRAST_CAP,
+  LABEL_CONTRAST_DONE_ATTR,
   LEGEND_MARK_CLASS,
   LIFT_SELECTED_CLASS,
+  LIGHT_TEXT,
   MARK_CLASS,
   MARK_SELECTED_CLASS,
   MAX_FRAME_GROW_FACTOR,
+  MIN_CONTRAST,
   MIN_HIT_BAND_PX,
+  PAGE_MATCH_TOLERANCE,
   PHANTOM_FRACTION,
+  PILL_MIN_ALPHA,
+  PILL_MIN_COVERAGE,
+  PILL_OPAQUE_ALPHA,
   ROW_IDX_ATTR,
+  Rt,
   SCROLL_SLACK_PX,
   SEASONAL_MARKERS_DEFAULT,
   SELECTION_ACTIVE_CLASS,
+  Se,
   Tt,
   VALUE_AXIS_BASELINE_DEFAULT,
+  WHITE_TEXT_BG_LUM,
   XFILTER_REFRESH_EVENT,
+  applyLabelContrast,
+  backingHoldsGlyph,
   blankRenderFlag,
   buildRenderPayload,
+  cellSuppressesNormalize,
   censusHitBands,
   censusMarks,
   chartOwnsTimeline,
   clearGeoCache,
   compileRenderFn,
+  compositeOver,
   contentExtentOf,
+  contrastRatio,
   createChartHost,
   createMarkResolver,
   ctmScaleOf,
+  decideLabelColor,
   ensureCrossfilterHitTargets,
   explainRenderFailure,
   fitReadingFor,
   fitRenderedChart,
   geoAssetFor,
   geoFromCache,
-  he,
+  glyphSampleGrid,
   hitBandFlag,
   isBlankRender,
   isPhantomBox,
+  isPillBackdropAlpha,
   loadGeo,
   measureContainerBoxes,
   needsScroll,
   noopViewStateProvider,
   periodTickSuppressesFeedback,
+  pillBacksGlyph,
   planFrameGrow,
   registerGeo,
   registerGeoAsset,
+  relativeLuminance,
   requiredD3Plugins,
   resolveOptions,
   scrollFitFor,
   sessionViewStateProvider,
   stripEsmExports,
   svgInkReach,
+  toRGBA,
   ye
-} from "./chunk-QCB6PBO5.mjs";
+} from "./chunk-E6P2ZMGC.mjs";
 import "./chunk-A2GMXZP7.mjs";
 import "./chunk-GHODWOAL.mjs";
 
@@ -823,15 +846,15 @@ function isRealColumn(col) {
   return !!col && !isSynthetic(col.name);
 }
 function isSuppressed(col) {
-  return At(col).suppressed;
+  return Tt(col).suppressed;
 }
 function resolveAgg(col, requested, auto) {
   const fallback = () => {
-    const d = he(col);
+    const d = ye(col);
     return d === "first" ? "count" : d;
   };
   if (auto) return fallback();
-  return Tt(col).indexOf(requested) >= 0 ? requested : fallback();
+  return Rt(col).indexOf(requested) >= 0 ? requested : fallback();
 }
 function toNumber(v) {
   if (v == null || v === "") return null;
@@ -935,7 +958,7 @@ function computeSelectionCard(payload, selectedRowIdxs, opts = {}) {
     }
     const value = reduce(selVals, colAgg, selRaw);
     let sharePct = null;
-    if (ye(col, colAgg) && value != null) {
+    if (Se(col, colAgg) && value != null) {
       const allVals = [];
       const allRaw = [];
       for (let r = 0; r < rows.length; r++) {
@@ -1010,6 +1033,7 @@ export {
   ANIM_PLAY_SPEED_MIN,
   APPROXIMATE_POSITIONS_DEFAULT,
   AXIS_FILTER_CLASS,
+  BACKING_MAJORITY,
   CHOOSER_MIN_HEIGHT_PX,
   CHOOSER_MIN_WIDTH_PX,
   COLOR_SCALE_SELF_CLAMP_PCT_DEFAULT,
@@ -1019,6 +1043,7 @@ export {
   CONTAINER_SLOT_INITIAL_XF_MARK,
   CONTAINER_SLOT_UI_STATE,
   CONTAINER_SLOT_XF_CLEAR,
+  DARK_TEXT,
   DIM_OPACITY_DEFAULT,
   DIM_OPACITY_VAR,
   FILTER_MIN_HEIGHT_PX,
@@ -1028,30 +1053,43 @@ export {
   FIT_CONTENT_SELECTOR,
   FLIP_MODE_DEFAULT,
   GEO_POINT_PRECISIONS,
+  GLYPH_SAMPLE_N,
   HOST_CONTAINER_CLASS,
   HOST_CONTRACT_VERSION,
   INLINE_FILTER_MIN_ROWS,
+  LABEL_CONTRAST_CAP,
+  LABEL_CONTRAST_DONE_ATTR,
   LEGEND_MARK_CLASS,
   LIFT_SELECTED_CLASS,
+  LIGHT_TEXT,
   MARK_CLASS,
   MARK_SELECTED_CLASS,
   MAX_FRAME_GROW_FACTOR,
+  MIN_CONTRAST,
   MIN_HIT_BAND_PX,
+  PAGE_MATCH_TOLERANCE,
   PHANTOM_FRACTION,
+  PILL_MIN_ALPHA,
+  PILL_MIN_COVERAGE,
+  PILL_OPAQUE_ALPHA,
   ROW_IDX_ATTR,
   SCROLL_SLACK_PX,
   SEASONAL_MARKERS_DEFAULT,
   SELECTION_ACTIVE_CLASS,
   VALUE_AXIS_BASELINE_DEFAULT,
+  WHITE_TEXT_BG_LUM,
   XFILTER_REFRESH_EVENT,
   actionFor,
+  applyLabelContrast,
   askApplyImprovements,
+  backingHoldsGlyph,
   bareBase64,
   blankRenderFlag,
   buildRenderPayload,
   buildReviewWire,
   canConfirmLaunch,
   captureSvgSnapshot,
+  cellSuppressesNormalize,
   censusHitBands,
   censusMarks,
   chartOwnsTimeline,
@@ -1059,13 +1097,16 @@ export {
   clearGeoCache,
   compileRenderFn,
   compileTrivialSource,
+  compositeOver,
   computeQualifyFilterView,
   computeSelectionCard,
   confirmLaunch,
   contentExtentOf,
+  contrastRatio,
   createChartHost,
   createMarkResolver,
   ctmScaleOf,
+  decideLabelColor,
   ensureCrossfilterHitTargets,
   explainRenderFailure,
   filterFitsChooser,
@@ -1074,11 +1115,13 @@ export {
   fitRenderedChart,
   geoAssetFor,
   geoFromCache,
+  glyphSampleGrid,
   hasRefusalsToShow,
   hitBandFlag,
   inlineFilterGate,
   isBlankRender,
   isPhantomBox,
+  isPillBackdropAlpha,
   launchFavorStyle,
   launchGenerates,
   listNeedsFilter,
@@ -1092,6 +1135,7 @@ export {
   normalizeFilterTerm,
   orderRefusalsForDisplay,
   periodTickSuppressesFeedback,
+  pillBacksGlyph,
   planFrameGrow,
   planTrivialChart,
   qualifyAuto,
@@ -1109,6 +1153,7 @@ export {
   registerCityTable,
   registerGeo,
   registerGeoAsset,
+  relativeLuminance,
   requiredD3Plugins,
   resolveOptions,
   scrollFitFor,
@@ -1119,5 +1164,6 @@ export {
   stripEsmExports,
   svgInkReach,
   svgNaturalSize,
-  svgToDataUrl
+  svgToDataUrl,
+  toRGBA
 };

package/dist/react.mjs

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

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 FitRenderedChartOptions, type FitRenderedChartResult } from "./fitDom";
+import { type LabelContrastOptions, type LabelContrastReport } from "./labelContrastDom";
 export type RenderFn = (container: HTMLElement, data: any, options: RenderOptions) => void;
 /**
  * THE SESSION PROVIDER — what every host got hard-coded before contract 1.6.0, now named.
@@ -115,6 +116,25 @@ export interface ChartHostConfig {
     fit?: boolean | FitRenderedChartOptions;
     /** The fit result after each render - what was grown, and how the chart measured. */
     onFit?: (result: FitRenderedChartResult) => void;
+    /**
+     * CAN THE LABELS ON THE MARKS BE READ? Runs after every render, BEFORE the hit-target heal
+     * (which injects transparent rects this pass must not mistake for backdrops).
+     *
+     * Generated code picks an in-mark label's colour from the mark's NOMINAL hue; the mark's
+     * ACTUAL rendered fill - a 0.18-opacity band over white, a translucent pill over a tile, an
+     * arc whose hole is canvas - is something else, and only a post-render read of the real DOM
+     * knows it. This resolves which shapes really back each label (geometry, not bounding
+     * boxes), composites the real stack over the page, and recolours to black or white only
+     * where the label would otherwise be unreadable or a tile's labels would read as mixed.
+     *
+     * DEFAULT ON, because the alternative is text nobody can read, and the pass only ever sets a
+     * text's fill. Pass `false` for a host that owns its own label colours, or an options object
+     * to name the page background it composites onto (`pageBg`) - a themed or high-contrast
+     * canvas is not white, and every readability answer is measured against it.
+     */
+    labelContrast?: boolean | LabelContrastOptions;
+    /** What the label-contrast pass did after each render - counts, so a host can log them. */
+    onLabelContrast?: (report: LabelContrastReport) => void;
 }
 export interface ChartHost {
     render(): void;

package/dist/types/index.d.ts

@@ -16,6 +16,8 @@ export { qualifyPick, qualifyAuto, qualifyCancel, launchGenerates, launchFavorSt
 export { normalizeFilterTerm, filterQualifyRows, readQualifyChartRow, readQualifyRefusalRow, filterFitsChooser, listNeedsFilter, qualifyFilterGate, inlineFilterGate, FILTER_MIN_TERM_CHARS, FILTER_ROW_PX, FILTER_MIN_WIDTH_PX, FILTER_MIN_HEIGHT_PX, INLINE_FILTER_MIN_ROWS, computeQualifyFilterView, qualifyFilterCountText, type QualifyFilterTier, type QualifyFilterResult, type QualifyFilterRead, type QualifyFilterGateReason, type QualifyFilterGateInput, type QualifyFilterRow, type QualifyFilterGroup, type QualifyFilterView, type QualifyFilterNoteKind, } from "./qualifyFilter";
 export { computeSelectionCard, normaliseAggregation, type SelectionCardModel, type SelectionCardLine, type SelectionCardOptions, } from "./selectionCard";
 export { ensureCrossfilterHitTargets, type HitTargetReport } from "./hitTargets";
+export { applyLabelContrast, LABEL_CONTRAST_DONE_ATTR, LABEL_CONTRAST_CAP, type LabelContrastOptions, type LabelContrastReport, } from "./labelContrastDom";
+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 { 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";

package/dist/types/labelContrast.d.ts

@@ -0,0 +1,56 @@
+export declare const DARK_TEXT = "#111111";
+export declare const LIGHT_TEXT = "#ffffff";
+export declare const MIN_CONTRAST = 3;
+export declare const WHITE_TEXT_BG_LUM = 0.5;
+export declare const PILL_MIN_ALPHA = 0.05;
+export declare const PILL_OPAQUE_ALPHA = 0.85;
+export declare const PAGE_MATCH_TOLERANCE = 2;
+/** True when a shape's effective alpha lets it act as a label backdrop rather than the cell. */
+export declare function isPillBackdropAlpha(a: number): boolean;
+export declare const PILL_MIN_COVERAGE = 0.6;
+/** True when a candidate backdrop covers enough of the glyph box to be the thing behind it. */
+export declare function pillBacksGlyph(overlapArea: number, glyphArea: number): boolean;
+export declare const BACKING_MAJORITY = 0.5;
+/** True when the painted marks under a glyph hold enough of it to count as its background. */
+export declare function backingHoldsGlyph(backedArea: number, glyphArea: number): boolean;
+export declare function cellSuppressesNormalize(cellClass: string | null | undefined): boolean;
+type RGB = [number, number, number];
+type RGBA = [number, number, number, number];
+/** Parse a colour string to RGBA, covering hex, rgb()/rgba() and a few keywords. */
+export declare function toRGBA(c: string | null | undefined): RGBA | null;
+/** Alpha-composite a foreground RGBA over an opaque RGB background. */
+export declare function compositeOver(fg: RGBA, bg: RGB): RGB;
+/** WCAG relative luminance of an opaque sRGB colour (0..1). */
+export declare function relativeLuminance(rgb: RGB): number;
+/** WCAG contrast ratio (1..21) between two luminances. */
+export declare function contrastRatio(l1: number, l2: number): number;
+export interface LabelDecision {
+    fix: boolean;
+    color: string;
+    reason: string;
+}
+/**
+ * Decide whether an in-mark label needs recolouring for legibility.
+ *
+ * @param textColor    current text colour (any CSS form the SVG carries)
+ * @param fill         the backing mark's fill colour
+ * @param fillOpacity  the backing mark's fill-opacity (0..1)
+ * @param pageBg       the page/visual background the mark sits on (opaque; '' → white)
+ * @param minContrast  trip point; defaults to MIN_CONTRAST
+ */
+export declare function decideLabelColor(textColor: string | null | undefined, fill: string | null | undefined, fillOpacity: number, pageBg: string | null | undefined, minContrast?: number, normalize?: boolean): LabelDecision;
+export declare const GLYPH_SAMPLE_N = 3;
+/**
+ * Evenly-spaced sample points over a glyph box, in the box's own coordinate space.
+ * `n` per side (n² points), each at the centre of its cell so no point lands on an edge.
+ */
+export declare function glyphSampleGrid(box: {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+}, n?: number): {
+    x: number;
+    y: number;
+}[];
+export {};

package/dist/types/labelContrastDom.d.ts

@@ -0,0 +1,33 @@
+/** The attribute a recoloured (or pill-backed) label carries, so a second pass in the same
+ *  render leaves it alone. Generated code that rebuilds its text nodes clears it by construction. */
+export declare const LABEL_CONTRAST_DONE_ATTR = "data-lch-contrast";
+/** How many shapes / texts the pass will consider before declining. Layout reads in a loop, so
+ *  it is a real ceiling: a 5,000-cell heatmap is the size of thing this exists for, a 50,000-node
+ *  scatter is not, and on the latter the pass costs more than the defect it would fix. */
+export declare const LABEL_CONTRAST_CAP = 2000;
+export interface LabelContrastOptions {
+    /** The opaque canvas the marks sit on. Default white; a host with a themed or high-contrast
+     *  background passes it, or every "is this label readable" answer is measured against the
+     *  wrong page. */
+    pageBg?: string;
+    /** Override the DOM ceiling. */
+    cap?: number;
+}
+export interface LabelContrastReport {
+    /** Filled shapes harvested as candidate backings. */
+    rects: number;
+    /** Labels that resolved a backing and were judged. */
+    scanned: number;
+    /** Labels recoloured. `fixed === scanned` is the module's own tell for a pass that is not
+     *  measuring anything - see the incident notes in labelContrast.ts. */
+    fixed: number;
+    /** Translucent backdrops boosted to opaque so they actually back their label. */
+    pillsBoosted: number;
+    /** Labels whose candidates' BOXES contained them but whose FILLS did not - a ring's hole. */
+    offFill: number;
+    /** Labels mostly over the page with one end clipping a mark - handed back to the chart. */
+    pageMajority: number;
+    /** Why the pass did nothing, when it did nothing. */
+    skipped?: "no-container" | "no-shapes" | "too-many-shapes" | "too-many-texts" | "error";
+}
+export declare function applyLabelContrast(container: HTMLElement | null | undefined, opts?: LabelContrastOptions): LabelContrastReport;

package/package.json

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