@bicharts/chart-host 0.6.69 → 0.6.70

package/README.md

@@ -145,6 +145,39 @@ group.onChange(sel => console.log(sel.sourceId, sel.rows));  // SOURCE row indic
 group.clear();
 ```
 
+## Reader options
+
+Everything a reader can tune lives in `options` - the `options` prop on `<BicChart>`, the
+`options` you hand `createChartHost`, or a later `setOptions`. The full set, with each option's
+default, bounds and whether it repaints the chart on screen, is exported as `OPTIONS_VOCABULARY`;
+`LIVE_OPTION_KEYS` lists the ones that apply without a new chart.
+
+**Card decks and carousels.** A chart that pages through several faces (a flippable multi-card
+deck, a rotating carousel) reads these on every draw, so they all restyle live:
+
+| Option | Values | Unset means |
+| --- | --- | --- |
+| `cardBackgroundColor` | any CSS color | the chart's own fill: a deck uses the page, a carousel a light tint |
+| `flipIntervalMs` | `0` (manual only), or 500-120000 ms | the chart's own: manual for a deck, 5 s for a carousel |
+| `flipDirection` | `"horizontal"`, `"vertical"` | `"horizontal"` (side to side) |
+| `flipMode` | `"both"`, `"all"`, `"single"` (the deck only; a carousel has its own arrows) | `"both"` |
+
+```tsx
+<BicChart id="kpis" code={code} d3={d3}
+          options={{ width, height, cardBackgroundColor: "#f4c7b8", flipIntervalMs: 4000 }} />
+```
+
+The fill is the only thing you set: the chart still chooses its text colors, and they are its
+job to keep readable on a dark card.
+
+**Clearing an option.** `setOptions` merges into what the chart already has, and so does a
+changed `options` prop - a key you simply drop keeps its last value. To hand an option back to
+the chart's own default, pass it explicitly as `undefined`:
+
+```js
+host.setOptions({ cardBackgroundColor: undefined, flipIntervalMs: undefined });
+```
+
 ## Sizing is yours
 
 `width`/`height` have **no defaults**. A chart draws once at whatever it is handed and does not

package/dist/index.mjs

@@ -212,6 +212,12 @@ var OPTIONS_VOCABULARY = Object.freeze({
   flipIntervalMs: entry({ timing: "live", default: "", min: 0, max: FLIP_INTERVAL_MAX_MS }),
   /** Which way a face turns, for any chart that turns between faces: side to side, or top to bottom. */
   flipDirection: entry({ timing: "live", default: FLIP_DIRECTION_DEFAULT, values: ["horizontal", "vertical"] }),
+  /**
+   * The fill behind each card of a card deck and each face of a carousel. BLANK - "the chart's own" -
+   * is the default, and it differs by chart: a deck uses the page so its cards read as part of it, a
+   * carousel tints its faces so each reads as a surface. A color is a reader's choice.
+   */
+  cardBackgroundColor: entry({ timing: "live", default: "" }),
   /**
    * Hover drop lines on a 3D chart. BLANK - "the chart's own" - is the default: off, unless the request
    * that made the chart asked for them. "on" / "off" is a reader's choice and wins either way.

package/dist/types/optionsVocabulary.d.ts

@@ -60,6 +60,12 @@ export declare const OPTIONS_VOCABULARY: Readonly<{
     flipIntervalMs: OptionVocabularyEntry;
     /** Which way a face turns, for any chart that turns between faces: side to side, or top to bottom. */
     flipDirection: OptionVocabularyEntry;
+    /**
+     * The fill behind each card of a card deck and each face of a carousel. BLANK - "the chart's own" -
+     * is the default, and it differs by chart: a deck uses the page so its cards read as part of it, a
+     * carousel tints its faces so each reads as a surface. A color is a reader's choice.
+     */
+    cardBackgroundColor: OptionVocabularyEntry;
     /**
      * Hover drop lines on a 3D chart. BLANK - "the chart's own" - is the default: off, unless the request
      * that made the chart asked for them. "on" / "off" is a reader's choice and wins either way.

package/package.json

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