@bicharts/chart-host 0.6.30 → 0.6.31

package/dist/index.mjs

@@ -144,6 +144,60 @@ import {
 import "./chunk-A2GMXZP7.mjs";
 import "./chunk-GHODWOAL.mjs";
 
+// src/optionsVocabulary.ts
+var MAX_MAP_POINTS_MIN = 10;
+var MAX_MAP_POINTS_MAX = 1e5;
+var LIMIT_COUNT_MAX = 1e4;
+var entry = (e2) => Object.freeze({ ...e2, ...e2.values ? { values: Object.freeze([...e2.values]) } : {} });
+var OPTIONS_VOCABULARY = Object.freeze({
+  // ---- drawn from on every render, and stated on the request so the model reasons about them ----
+  aggregation: entry({ timing: "live-and-next-generate", default: "", values: ["", "sum", "average", "median", "min", "max", "count", "distinct"], wire: "request" }),
+  colorScaleLow: entry({ timing: "live-and-next-generate", default: "", wire: "request" }),
+  colorScaleHigh: entry({ timing: "live-and-next-generate", default: "", wire: "request" }),
+  /** Blank: the host's own colours when it offers them, else the engine's. */
+  palette: entry({ timing: "live-and-next-generate", default: "", wire: "request" }),
+  /** A HARD offer gate on the server as well as a live cap on what a point map plots. */
+  maxMapPoints: entry({ timing: "live-and-next-generate", default: MAX_MAP_POINTS_DEFAULT, min: MAX_MAP_POINTS_MIN, max: MAX_MAP_POINTS_MAX, wire: "clientHints" }),
+  // ---- live only ----
+  /** 0 means no paging. */
+  pageSize: entry({ timing: "live", default: 0, min: 0 }),
+  valueAxisBaseline: entry({ timing: "live", default: VALUE_AXIS_BASELINE_DEFAULT, values: ["fit", "zero", "auto"] }),
+  seasonalMarkers: entry({ timing: "live", default: SEASONAL_MARKERS_DEFAULT, values: ["auto", "always", "never"] }),
+  animAutoPlay: entry({ timing: "live", default: false }),
+  animPlaySpeedMs: entry({ timing: "live", default: ANIM_PLAY_SPEED_DEFAULT, min: ANIM_PLAY_SPEED_MIN, max: ANIM_PLAY_SPEED_MAX }),
+  /** 0 restarts at once; no upper bound, so a very large value plays once per viewing. */
+  animLoopDelaySec: entry({ timing: "live", default: ANIM_LOOP_DELAY_DEFAULT, min: ANIM_LOOP_DELAY_MIN }),
+  animStopAtEnd: entry({ timing: "live", default: false }),
+  animMaxIdealFrames: entry({ timing: "live", default: ANIM_MAX_IDEAL_FRAMES_DEFAULT, min: ANIM_MAX_IDEAL_FRAMES_MIN, max: ANIM_MAX_IDEAL_FRAMES_MAX }),
+  /** "" chooses by the number of periods. */
+  animTimelineStyle: entry({ timing: "live", default: "", values: ["", "line", "boxes"] }),
+  filtersDuringPlay: entry({ timing: "live", default: false }),
+  // ---- the next generated chart ----
+  levelOfDetail: entry({ timing: "next-generate", default: "", values: ["", "High", "Medium", "Low"], wire: "clientHints" }),
+  favorLimitTo: entry({ timing: "next-generate", default: "", values: ["", "latest", "top / greatest", "bottom / smallest", "most common", "outliers"], wire: "clientHints" }),
+  /** 0 asks for no limit, and travels as absent (`wireLimitCount`): any value the server receives is a limit. */
+  favorLimitCount: entry({ timing: "next-generate", default: 0, min: 0, max: LIMIT_COUNT_MAX, wire: "clientHints" }),
+  /** "1" asks for a title, "0" for none, "" leaves it to the engine. */
+  favorTitle: entry({ timing: "next-generate", default: "", values: ["", "1", "0"], wire: "clientHints" }),
+  /** Data labels on the marks: "1", "0", or "" for the engine's choice. */
+  favorDPValues: entry({ timing: "next-generate", default: "", values: ["", "1", "0"], wire: "clientHints" }),
+  legendPlacement: entry({ timing: "next-generate", default: "", values: ["", "outside", "inside", "none"], wire: "clientHints" }),
+  /** Free text: the industry the data belongs to. */
+  industryContext: entry({ timing: "next-generate", default: "", wire: "clientHints" }),
+  /** Free text: a font family for the chart's own text. */
+  suggestFontFamily: entry({ timing: "next-generate", default: "", wire: "clientHints" }),
+  // ---- after a chart is drawn ----
+  visionReview: entry({ timing: "after-render", default: false }),
+  saveThumbnails: entry({ timing: "after-render", default: false })
+});
+var LIVE_OPTION_KEYS = Object.freeze(
+  Object.keys(OPTIONS_VOCABULARY).filter((k2) => OPTIONS_VOCABULARY[k2].timing === "live" || OPTIONS_VOCABULARY[k2].timing === "live-and-next-generate")
+);
+function wireLimitCount(count) {
+  const n2 = typeof count === "number" ? count : count == null || count === "" ? NaN : Number(count);
+  return Number.isFinite(n2) && n2 > 0 ? n2 : null;
+}
+
 // src/dateCells.ts
 var LOCAL_DATE_METHOD = /\.(?:getFullYear|getMonth|getDate|getDay|getHours|getMinutes|setFullYear|setMonth|setDate|setHours|setMinutes|setSeconds|setMilliseconds)\s*\(/;
 var D3_LOCAL_TIME = /\bd3\s*\.\s*(?:scaleTime|time[A-Z]\w*)\b/;
@@ -2542,14 +2596,19 @@ export {
   LEGIBLE_LIGHTNESS,
   LIFT_SELECTED_CLASS,
   LIGHT_TEXT,
+  LIMIT_COUNT_MAX,
+  LIVE_OPTION_KEYS,
   MARK_CLASS,
   MARK_SELECTED_CLASS,
   MAX_FRAME_GROW_FACTOR,
   MAX_MAP_POINTS_DEFAULT,
+  MAX_MAP_POINTS_MAX,
+  MAX_MAP_POINTS_MIN,
   MIN_CONTRAST,
   MIN_DELTA_E,
   MIN_HIT_BAND_PX,
   MIN_RAMP_FILLS,
+  OPTIONS_VOCABULARY,
   PAGE_MATCH_TOLERANCE,
   PENDING_RECOVERY_FAST_PHASE_MS,
   PENDING_RECOVERY_FIRST_POLL_MS,
@@ -2732,5 +2791,6 @@ export {
   updateRowHighWater,
   valuePlacementFlag,
   vegaSpecReadsDatesInLocalTime,
+  wireLimitCount,
   withoutViewOnlyKeys
 };

package/dist/types/index.d.ts

@@ -1,5 +1,6 @@
 export { HOST_CONTRACT_VERSION, GEO_POINT_PRECISIONS, MARK_CLASS, LEGEND_MARK_CLASS, AXIS_FILTER_CLASS, ROW_IDX_ATTR, LIFT_SELECTED_CLASS, CONTROL_CLASS, XFILTER_REFRESH_EVENT, CONTAINER_SLOT_ANIM_STOP, CONTAINER_SLOT_XF_CLEAR, CONTAINER_SLOT_INITIAL_XF_MARK, CONTAINER_SLOT_UI_STATE, VIEW_ONLY_UI_STATE_KEYS, withoutViewOnlyKeys, HOST_CONTAINER_CLASS, SELECTION_ACTIVE_CLASS, MARK_SELECTED_CLASS, ACTIVE_TICK_CLASS, DIM_OPACITY_VAR, DIM_OPACITY_DEFAULT, chartOwnsTimeline, periodTickSuppressesFeedback, ANIM_PLAY_SPEED_DEFAULT, ANIM_PLAY_SPEED_MIN, ANIM_PLAY_SPEED_MAX, ANIM_LOOP_DELAY_DEFAULT, ANIM_LOOP_DELAY_MIN, ANIM_MAX_IDEAL_FRAMES_DEFAULT, ANIM_MAX_IDEAL_FRAMES_MIN, ANIM_MAX_IDEAL_FRAMES_MAX, ANIMATION_OPTION_KEYS, COLOR_SCALE_SELF_CLAMP_PCT_DEFAULT, COLOR_SCALE_SELF_CLAMP_PCT_MIN, COLOR_SCALE_SELF_CLAMP_PCT_MAX, FLIP_MODE_DEFAULT, APPROXIMATE_POSITIONS_DEFAULT, VALUE_AXIS_BASELINE_DEFAULT, SEASONAL_MARKERS_DEFAULT, MAX_MAP_POINTS_DEFAULT, type GeoPointPrecision, type GeoMapKind, type TimelineStyle, type FlipMode, type ApproximatePositions, type ValueAxisBaseline, type SeasonalMarkers, type ColorScaleScope, type RenderOptions, type ViewStateProvider, type ChartControlChange, } from "./contract";
 export { resolveOptions, type ResolveOptionsInput } from "./defaults";
+export { OPTIONS_VOCABULARY, LIVE_OPTION_KEYS, MAX_MAP_POINTS_MIN, MAX_MAP_POINTS_MAX, LIMIT_COUNT_MAX, wireLimitCount, type OptionVocabularyEntry, type OptionTiming, type OptionWire, type OptionKey, } from "./optionsVocabulary";
 export { loadGeo, geoFromCache, registerGeo, registerGeoAsset, geoAssetFor, clearGeoCache, type GeoAssetName, } from "./geoLazy";
 /** REPLACE the bundled city gazetteer with another packed table. Rarely needed — see the
  *  note above registerCityTable in shape-core's geoPoint.ts before using it. */

package/dist/types/optionsVocabulary.d.ts

@@ -0,0 +1,77 @@
+/**
+ * When a change to an option takes effect.
+ * - `live`: the chart on screen repaints with it; no request, no new chart.
+ * - `next-generate`: it steers what the engine makes, so it applies to the next generated chart.
+ * - `live-and-next-generate`: both - the chart on screen repaints, and the request carries it too.
+ * - `after-render`: it governs what happens after a chart is drawn (a review, a thumbnail).
+ */
+export type OptionTiming = "live" | "next-generate" | "live-and-next-generate" | "after-render";
+/** Where an option travels on a generate request: the request itself, or its client hints. */
+export type OptionWire = "request" | "clientHints";
+/** The shared facts about one option. */
+export interface OptionVocabularyEntry {
+    readonly timing: OptionTiming;
+    /** What "not set" means. A host that stores blank or 0 for "the default" resolves to this. */
+    readonly default: string | number | boolean;
+    /** The least value a reader may set, for a number. */
+    readonly min?: number;
+    /** The greatest value a reader may set, for a number. Absent: no upper bound. */
+    readonly max?: number;
+    /** The values a choice accepts, "" being "leave it to the engine" where offered. */
+    readonly values?: readonly string[];
+    /** Where it travels on a generate request; absent when it never travels. */
+    readonly wire?: OptionWire;
+}
+/** Max Map Points: the fewest and the most points a reader may allow a point map. */
+export declare const MAX_MAP_POINTS_MIN = 10;
+export declare const MAX_MAP_POINTS_MAX = 100000;
+/** Favor Limit Count: the most groups a reader may ask a chart to keep. 0 asks for no limit. */
+export declare const LIMIT_COUNT_MAX = 10000;
+/** The options the hosts share, keyed by wire / render-option name. */
+export declare const OPTIONS_VOCABULARY: Readonly<{
+    aggregation: OptionVocabularyEntry;
+    colorScaleLow: OptionVocabularyEntry;
+    colorScaleHigh: OptionVocabularyEntry;
+    /** Blank: the host's own colours when it offers them, else the engine's. */
+    palette: OptionVocabularyEntry;
+    /** A HARD offer gate on the server as well as a live cap on what a point map plots. */
+    maxMapPoints: OptionVocabularyEntry;
+    /** 0 means no paging. */
+    pageSize: OptionVocabularyEntry;
+    valueAxisBaseline: OptionVocabularyEntry;
+    seasonalMarkers: OptionVocabularyEntry;
+    animAutoPlay: OptionVocabularyEntry;
+    animPlaySpeedMs: OptionVocabularyEntry;
+    /** 0 restarts at once; no upper bound, so a very large value plays once per viewing. */
+    animLoopDelaySec: OptionVocabularyEntry;
+    animStopAtEnd: OptionVocabularyEntry;
+    animMaxIdealFrames: OptionVocabularyEntry;
+    /** "" chooses by the number of periods. */
+    animTimelineStyle: OptionVocabularyEntry;
+    filtersDuringPlay: OptionVocabularyEntry;
+    levelOfDetail: OptionVocabularyEntry;
+    favorLimitTo: OptionVocabularyEntry;
+    /** 0 asks for no limit, and travels as absent (`wireLimitCount`): any value the server receives is a limit. */
+    favorLimitCount: OptionVocabularyEntry;
+    /** "1" asks for a title, "0" for none, "" leaves it to the engine. */
+    favorTitle: OptionVocabularyEntry;
+    /** Data labels on the marks: "1", "0", or "" for the engine's choice. */
+    favorDPValues: OptionVocabularyEntry;
+    legendPlacement: OptionVocabularyEntry;
+    /** Free text: the industry the data belongs to. */
+    industryContext: OptionVocabularyEntry;
+    /** Free text: a font family for the chart's own text. */
+    suggestFontFamily: OptionVocabularyEntry;
+    visionReview: OptionVocabularyEntry;
+    saveThumbnails: OptionVocabularyEntry;
+}>;
+/** A shared option's key. */
+export type OptionKey = keyof typeof OPTIONS_VOCABULARY;
+/** The keys whose change repaints the chart on screen, in table order. */
+export declare const LIVE_OPTION_KEYS: readonly OptionKey[];
+/**
+ * THE LIMIT COUNT A REQUEST CARRIES: a positive count, or null - never 0. The server reads any value it
+ * receives as the reader's own limit (and 0 as a limit of zero), so "no limit" must arrive as no value.
+ * A host places null where it always has; one that omits blank fields maps it to absent.
+ */
+export declare function wireLimitCount(count: unknown): number | null;

package/package.json

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