@lightdash/cli 2.255.3 → 2.256.0

package/dist/vendor/authoring/developing-chart-types-locally/SKILL.md

@@ -36,7 +36,15 @@ The scaffold ships a `viz-fixture.json` at the folder root. To use it:
 
 1. `lightdash apps preview` (or `npm run dev`) to start the dev server.
 2. Open the dev URL with the param, e.g. `http://localhost:5173/?vizFixture=/viz-fixture.json`. The chart renders from the fixture.
-3. Edit `viz-fixture.json` to match your declared `vizSchema` — `fieldMapping` (declared field name → any string id), `rows` (each cell is `{ "value": { "raw": ..., "formatted": "..." } }`, keyed by those ids), `options` (declared option name → value), `colorPalette`, and `pivotDetails` (`null` unless you map a `series` field). Reload to see changes.
+3. Edit `viz-fixture.json` to match your declared `vizSchema` — `fieldMapping` (input name → string id, or an ordered array of ids for multiple-field inputs), `rows` (each cell is `{ "value": { "raw": ..., "formatted": "..." } }`, keyed by those ids), `options` (declared option name → value), `colorPalette`, and `pivotDetails` (`null` unless you map a `series` field). Reload to see changes.
+
+For multiple-field inputs, set `multiple: true` on the `vizSchema.fields` entry and iterate
+the array at `useVizContext().fieldMapping[name]` in its existing order, narrowing with
+`Array.isArray` first. Single-field
+inputs continue to read a string from `fieldMapping[name]`. Test three
+metrics and multiple dimensions, remove and re-add one, then save and reopen the chart
+in the explorer. Verify fields follow the order they were added, with re-added fields at the end. Keep the input names stable across upgrades. Single-field inputs
+retain string bindings; details and examples live in the reusable-visualization skill.
 
 This is for **layout and option iteration only**, and never fires in production (an embedded viz has a real host whose context always wins, and the param must be explicitly present). The fixture is fake data you hand-maintain: colors fall back to the palette (no model or shared-dashboard colors), `pivotDetails` must be shaped by hand, and formatting is whatever you type. **The explorer with real data remains the source of truth for correctness** — still run the upload → verify loop above before finishing, and verify every declared option actually changes the chart there.
 

package/dist/vendor/template/.claude/skills/reusable-visualization/SKILL.md

@@ -40,9 +40,10 @@ const {
 } = context;
 ```
 
-- `fieldMapping` — `Record<string, string>`: the field name you declared → the query field
-  id it is bound to. Read cells with `getFormatted(row, fieldId)` (display text) and
-  `getRaw(row, fieldId)` (raw value).
+- `fieldMapping` — `Record<string, string | string[]>`: each single-field input maps
+  to one query field id; inputs declared with `multiple: true` map to ordered arrays.
+  Narrow with `Array.isArray(binding)` before iterating. Read each id with
+  `getFormatted(row, fieldId)` (display text) and `getRaw(row, fieldId)` (raw value).
 - `rows` — the host-fetched result rows, keyed by query field id.
 - `options` — `Record<string, boolean | number | string>`: the current value of each config
   option you declared (the viewer's choice, else your declared `default`).
@@ -208,6 +209,11 @@ underlyingData.open({ row: datum.sourceRow, metric: 'value' }).catch(() => {});
 action menu. It never renders an underlying-data dialog, table, loading state, error
 state, or download control inside the iframe.
 
+For a multiple-metric input, also pass `fieldId`, the member of that input's binding
+whose mark was clicked: `underlyingData.open({ row: datum.sourceRow, metric: 'values',
+fieldId })`. Use the same `fieldId` with `drillDown.open`. A mark combining several
+metrics cannot identify one underlying metric and gets no data-point action.
+
 ### Drill into a data point
 
 When `drillDown.enabled` is true, the same data-point action menu also offers
@@ -256,13 +262,12 @@ file**. It has four parts: `fields`, `configOptions`, `colorPalette` and optiona
 the field-mapping UI and the chart config panel from it, so the component is unusable
 without it.
 
-The correspondence is exact in both directions: **every key read from `fieldMapping` or
-`options` is declared, and everything declared is read.** A declared option nothing reads is
-a dead control the viewer can move with no effect.
+The correspondence is exact in both directions: **every key read from `fieldMapping` or `options` is declared, and everything declared is read.** A declared
+option nothing reads is a dead control the viewer can move with no effect.
 
 ### `fields`
 
-One entry per data column the component reads:
+One entry per input the component reads:
 
 - `name` — the key read from `fieldMapping`. Unique, no spaces.
 - `label` — human label shown in the mapping UI.
@@ -270,6 +275,11 @@ One entry per data column the component reads:
   `series` (a dimension used to split or colour the chart), or `column` (any result
   column, whether metric or dimension).
 - `required` — `false` only when the chart still renders with this field unmapped.
+- `multiple` — optional boolean, default `false`. Set `true` when this input accepts an
+  ordered selection of fields of its declared type. Its `fieldMapping` value is a
+  `string[]`, including when only one field is selected. A required input needs at least
+  one selection; an empty array means the viewer cleared it. Render a placeholder until
+  required selections exist.
 - `description` — optional reusable mapping help, maximum 160 characters. Use one
   or two short, plain sentences explaining the field's role in the chart. Keep it agnostic
   to any business, explore, or query; do not imply fixed categories or values.
@@ -277,6 +287,39 @@ One entry per data column the component reads:
 Do not generate field examples. Viewers supply their own values; describe the field's
 role and data shape without prescribing categories from a particular business.
 
+### Ordered multiple-field inputs
+
+Use one multiple input for a variable number of measures or grouping columns instead of
+declaring a fixed number of numbered slots:
+
+```json
+{
+  "fields": [
+    { "name": "groups", "label": "Grouping fields", "type": "dimension", "required": true, "multiple": true },
+    { "name": "values", "label": "Measures", "type": "metric", "required": true, "multiple": true }
+  ],
+  "configOptions": [],
+  "colorPalette": null
+}
+```
+
+```tsx
+const { fieldMapping, rows } = useVizContext();
+const groups = Array.isArray(fieldMapping.groups) ? fieldMapping.groups : [];
+const values = Array.isArray(fieldMapping.values) ? fieldMapping.values : [];
+const data = rows.map((row) => ({
+  label: groups.map((id) => getFormatted(row, id)).join(' / '),
+  values: values.map((id) => ({ id, value: getRaw(row, id) })),
+}));
+```
+
+Array order is the viewer's display order: preserve it when building axes, columns,
+legends and series. For pivoted metrics, iterate the selected ids first and then match
+`pivotDetails.valuesColumns` by `referenceField`. The flag also works for `series` and
+`column` inputs. Existing single inputs continue receiving strings in `fieldMapping`;
+leave their declarations unchanged when adding a separate multiple input. Keep field
+names stable across compatible upgrades so saved selections can be reconciled.
+
 ### `inputGuidance`
 
 Optional reusable help shown above the mappings, maximum 200 characters. Use at most two

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lightdash/cli",
-  "version": "2.255.3",
+  "version": "2.256.0",
   "description": "Lightdash CLI tool",
   "license": "MIT",
   "repository": {
@@ -22,8 +22,8 @@
     "@actions/core": "1.11.1",
     "@aws-sdk/credential-providers": "3.995.0",
     "@casl/ability": "6.8.0",
-    "@lightdash/common": "2.255.3",
-    "@lightdash/warehouses": "2.255.3",
+    "@lightdash/common": "2.256.0",
+    "@lightdash/warehouses": "2.256.0",
     "@sidvind/better-ajv-errors": "7.0.0",
     "@types/columnify": "1.5.1",
     "ajv": "8.18.0",