@bicharts/chart-host 0.5.86 → 0.5.88

package/dist/react.mjs

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

package/dist/types/index.d.ts

@@ -15,6 +15,7 @@ export { qualifyGroupHeadingFor, newQualifyGroupState, type QualifyGroupRow, typ
 export { qualifyPick, qualifyAuto, qualifyCancel, launchGenerates, launchFavorStyle, chooserFitsViewport, shouldOpenChooserOnGenerate, shouldOpenInlineChooserOnGenerate, canConfirmLaunch, confirmLaunch, qualifyFailureFallsOpen, CHOOSER_MIN_WIDTH_PX, CHOOSER_MIN_HEIGHT_PX, type QualifyLaunchOutcome, type ChooserGateInput, } from "./qualifyLaunch";
 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 { formatSourceDate, formatSourceDateFor, type SourceFormats, type SourceFormatDialect, type SourceDateOptions, } from "./sourceDateFormat";
 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";
@@ -24,3 +25,4 @@ 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, buildPaletteFromSeed, type PaletteResult } from "./palette";

package/dist/types/palette.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Minimum perceptual distance (CIE2000 deltaE) that any returned color must
+ * achieve from every previously-issued color. Picked for chart-readable
+ * swatches; JND (just-noticeable-difference) at this scale is ≈5.
+ */
+export declare const MIN_DELTA_E = 10;
+/**
+ * Pick a hex color for a palette slot.
+ *
+ * Strategy (ordered from "closest to theme" to "furthest from theme"):
+ *   1. The seed itself if it's already distant enough.
+ *   2. Saturation walk around the seed (same hue family, in-theme).
+ *   3. Lightness walk around the seed (same hue family, in-theme).
+ *   4. Hue rotation around the seed (drifts off-theme but still tied).
+ *   5. Give up — return the seed. Never random: a slightly-colliding theme
+ *      color reads better than a stranger color.
+ *
+ * The set of `existing` colors is treated as readonly — the caller is
+ * responsible for adding the returned color (and possibly the best-effort
+ * fallback) to their own set when this function returns. We return BOTH the
+ * chosen color AND the colorSet-entry to register, because the give-up case
+ * registers a DIFFERENT value (the best-so-far candidate) than what it
+ * returns (the seed): registering the seed would make a later call think
+ * its slot is empty, but returning the best-so-far would lose theme
+ * fidelity.
+ */
+export interface PaletteResult {
+    /** Hex color to use for this slot. */
+    readonly hex: string;
+    /** 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;
+/**
+ * A whole categorical palette from ONE seed colour.
+ *
+ * THE DIFFERENCE BETWEEN THE TWO HOSTS, and the reason this wrapper exists rather than each
+ * host looping for itself. Power BI hands the visual a DIFFERENT theme colour per slot
+ * (`getColor("1")`, `getColor("2")`, ...), so its loop varies the seed and the walk mostly
+ * settles at step 1. Excel has no such API: a workbook offers ONE resolvable accent - the fill
+ * a themed table style actually painted - so every slot is seeded from the SAME colour and the
+ * walk does the spreading, saturation first, then lightness, then hue.
+ *
+ * That ordering is why one accent is enough to be worth doing. The early slots stay in the
+ * seed's own hue family, so a two- or three-series chart reads as the workbook's colour rather
+ * than as a stranger's; only once those are exhausted does it rotate away. A host with one
+ * brand colour gets a palette that still looks like the brand.
+ *
+ * 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[];

package/dist/types/selectionCard.d.ts

@@ -1,4 +1,5 @@
 import type { RenderPayload } from "./payload";
+import { type SourceFormats } from "./sourceDateFormat";
 export interface SelectionCardOptions {
     /** The chart's own aggregation, so the card AGREES with the picture it sits on. A card
      *  reading "Sum" beside a chart drawn from averages is two answers to one question.
@@ -24,6 +25,16 @@ export interface SelectionCardOptions {
      *  cap already had (on the sample table the two coordinate columns took two of the four
      *  measure slots and pushed the real measures under "+2 more"). Default 2. */
     maxDimensions?: number;
+    /** THE SOURCE'S OWN DATE FORMATS, keyed by column name, plus the dialect they are written in
+     *  — Excel's `range.numberFormat` for the add-in, a `.NET` format string for the visual.
+     *
+     *  Optional, and the fallback is deliberately good rather than minimal: a host that supplies
+     *  nothing still gets a locale date instead of the ISO instant this replaced, so the MCP and
+     *  React hosts (a CSV has no cell formatting to read) and every chart cached before today
+     *  improve without anyone plumbing anything. What the map buys is AGREEMENT with the cells
+     *  the card is floating over — a sheet that shows `31-Aug-25` gets a card that says
+     *  `31-Aug-25`. */
+    sourceFormats?: SourceFormats | null;
 }
 export interface SelectionCardLine {
     column: string;

package/dist/types/sourceDateFormat.d.ts

@@ -0,0 +1,30 @@
+/** Which vocabulary a source format string is written in. See the header note - this is stated
+ *  by the host that owns the format, never inferred from the string. */
+export type SourceFormatDialect = "excel" | "dotnet";
+/** A host's per-column source formats. The dialect is carried WITH the map rather than passed
+ *  beside it, so a caller cannot supply one without the other. */
+export interface SourceFormats {
+    dialect: SourceFormatDialect;
+    /** Keyed by column name, which is the key the payload's columns already carry. Absent or
+     *  blank for a column with no source format - a computed column, a CSV, a text date whose
+     *  own text IS its formatting. */
+    byColumn: Record<string, string>;
+}
+export interface SourceDateOptions {
+    /** The source's own format string for this column, if it has one. */
+    format?: string | null;
+    /** Which vocabulary `format` is written in. Ignored when `format` is absent. */
+    dialect?: SourceFormatDialect;
+    /** BCP-47 tag, for month and weekday names and for the locale fallback. */
+    culture?: string;
+}
+/**
+ * Render a temporal payload value for a reader, or NULL when the value is not a date at all.
+ *
+ * Null rather than a best-effort string, so a caller can fall through to whatever it did before
+ * without this file having an opinion about non-dates. Accepts a `Date` (what a host holds before
+ * the payload is built) and an ISO string (what the payload carries after it).
+ */
+export declare function formatSourceDate(raw: any, opts?: SourceDateOptions): string | null;
+/** Convenience for a caller holding a `SourceFormats` map and a column name. */
+export declare function formatSourceDateFor(raw: any, columnName: string, formats: SourceFormats | null | undefined, culture?: string): string | null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bicharts/chart-host",
-  "version": "0.5.86",
+  "version": "0.5.88",
   "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",
@@ -68,6 +68,7 @@
   "// devDependencies": "@bicharts/shape-core is deliberately NOT declared. It is a workspace sibling that npm links regardless, and its code is BUNDLED into dist, so a consumer never installs it. Declaring it made this package a registry DEPENDENT of shape-core, which blocks lifecycle operations on that package in exchange for nothing. Do not add it back; if the build stops resolving it, fix the workspace, not the manifest.",
   "devDependencies": {
     "@types/react": "^19.2.17",
+    "colorsea": "^1.2.2",
     "esbuild": "^0.28.1",
     "react": "^19.2.8",
     "react-dom": "^19.2.8",