@lightdash/cli 2.323.0 → 2.324.0

package/dist/handlers/apps/authoring/chart-type/viz-fixture.json

@@ -3,6 +3,14 @@
         "category": "orders_status",
         "value": "orders_total_revenue"
     },
+    "fields": {
+        "orders_status": { "label": "Status", "tableLabel": "Orders" },
+        "orders_total_revenue": {
+            "label": "Total revenue",
+            "tableLabel": "Orders",
+            "format": { "type": "currency", "currency": "USD", "round": 0 }
+        }
+    },
     "rows": [
         {
             "orders_status": {

package/dist/vendor/authoring/chart-type/AGENTS.md.tmpl

@@ -11,6 +11,8 @@ contract in `references/lightdash-library-theme.md`): `--ll-*` tokens for axes,
 grids, legends, tooltips, and typography; transparent canvas; series colors from
 the instance palette, never the theme.
 
+Name fields with `getFieldLabel(context, id)` — labels, never raw query ids.
+
 The one difference from that skill here: the declaration is not emitted as structured output. It lives in this folder's `lightdash-app.yml` under `vizSchema`, and **must stay in lockstep with the component** — every key `src/App.jsx` reads from `fieldMapping` or `options` is declared there, and everything declared there is read. When you change what the component reads, update `vizSchema` in the same edit.
 
 Edit only `src/`. Root config files are read-only reference — the server rebuilds against a trusted template.
@@ -24,7 +26,7 @@ Run these commands from this folder under `chart-types/<slug>/`. The upload path
 3. `lightdash upload --chart-types <slug> --path ../..` — the server rebuilds; the chart type then appears in the explorer's chart type picker for that project.
 4. Verify in Lightdash: open any explore, run a query, pick this chart type, and map its fields.
 
-Preview locally with the fixture: `useVizContext()` normally waits for the Lightdash host, but the SDK has a dev-only fallback. Run `lightdash apps preview` (or `npm run dev`) and open the dev URL with `?vizFixture=/viz-fixture.json` — the scaffold's `viz-fixture.json` seeds `useVizContext()` so the chart renders. Edit that file to match your `vizSchema` (fieldMapping, rows as `{ value: { raw, formatted } }` cells, options, colorPalette, pivotDetails). It's fake data for layout/option iteration and never fires in production; the explorer with real data is still the source of truth — upload and verify there before finishing.
+Preview locally with the fixture: `useVizContext()` normally waits for the Lightdash host, but the SDK has a dev-only fallback. Run `lightdash apps preview` (or `npm run dev`) and open the dev URL with `?vizFixture=/viz-fixture.json` — the scaffold's `viz-fixture.json` seeds `useVizContext()` so the chart renders. Edit that file to match your `vizSchema` (fieldMapping, fields labels, rows as `{ value: { raw, formatted } }` cells, options, colorPalette, pivotDetails). It's fake data for layout/option iteration and never fires in production; the explorer with real data is still the source of truth — upload and verify there before finishing.
 
 Build with the template's preinstalled dependency set (see `package.json` — React, Recharts, d3, and more). Do not add npm packages or vendor library source into `src/`; chart types published to the official registry must stay template-deps-only.
 

package/dist/vendor/authoring/chart-type/App.jsx

@@ -1,4 +1,5 @@
 import {
+    getFieldLabel,
     getFormatted,
     getRaw,
     resolveValueColor,
@@ -80,10 +81,15 @@ function App() {
         ink: token('--ll-ink'),
     };
     const axisTick = { fill: ll.text, fontSize: 11.5, fontWeight: 500 };
+    // Name fields with their host labels ("Total revenue"), never the raw
+    // query ids; getFieldLabel falls back to the id only on hosts that send
+    // no field metadata.
+    const valueLabel = getFieldLabel(context, valField);
     const data = rows.slice(0, maxBars).map((row) => ({
         label: getFormatted(row, catField),
         category: getRaw(row, catField),
         value: Number(getRaw(row, valField) ?? 0),
+        formatted: getFormatted(row, valField),
     }));
 
     return (
@@ -112,8 +118,15 @@ function App() {
                         axisLine={false}
                         tickFormatter={(v) => v.toLocaleString()}
                     />
-                    <Tooltip wrapperClassName="ll-tooltip" cursor={false} />
-                    <Bar dataKey="value">
+                    <Tooltip
+                        wrapperClassName="ll-tooltip"
+                        cursor={false}
+                        formatter={(value, name, item) => [
+                            item.payload.formatted,
+                            name,
+                        ]}
+                    />
+                    <Bar dataKey="value" name={valueLabel}>
                         {data.map((d, i) => (
                             <Cell
                                 key={`${d.label}-${i}`}

package/dist/vendor/authoring/chart-type/viz-fixture.json

@@ -3,6 +3,14 @@
         "category": "orders_status",
         "value": "orders_total_revenue"
     },
+    "fields": {
+        "orders_status": { "label": "Status", "tableLabel": "Orders" },
+        "orders_total_revenue": {
+            "label": "Total revenue",
+            "tableLabel": "Orders",
+            "format": { "type": "currency", "currency": "USD", "round": 0 }
+        }
+    },
     "rows": [
         {
             "orders_status": {

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

@@ -38,7 +38,7 @@ 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` (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.
+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), `fields` (id → `{ "label": ..., "format": ... }`, so labels render as they will in Lightdash), `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

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

@@ -30,6 +30,7 @@ returns.
 const context = useVizContext();
 const {
   fieldMapping,
+  fields,
   rows,
   options,
   colorPalette,
@@ -45,6 +46,12 @@ const {
   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).
+- `fields` — `Record<string, { label, tableLabel?, format? }>`: display metadata for
+  each bound query field id. Name fields with `getFieldLabel(context, fieldId)` — the
+  field's label ("Total revenue"), or the raw id only when the host sent no metadata.
+  `format` is the semantic-layer format (`type` such as `currency`/`percent`/`number`,
+  plus `round`, `currency`, `compact`, `prefix`, `suffix`) for formatters that have no
+  cell to hand, such as axis ticks; per-value text still comes from `getFormatted`.
 - `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`).
@@ -91,6 +98,10 @@ shadcn, charting, theming, floating surfaces, screenshots) still applies.
 - **Fundamentals.** Clear axes and labels, readable spacing, a tooltip on hover.
   Give every axis a `tickFormatter` (compact numbers, shortened labels) or `hide`
   it — raw ticks overflow and overlap on a chart the viewer can resize.
+- **Labels, never ids.** Wherever the chart names a field — axis titles, legend and
+  series names, table headers, tooltip rows, default labels — use
+  `getFieldLabel(context, fieldId)`. Never show the query id (`orders_total_revenue`)
+  or a name derived from it (humanized, or with the table prefix stripped).
 
 ## Series colours
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lightdash/cli",
-  "version": "2.323.0",
+  "version": "2.324.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.323.0",
-    "@lightdash/warehouses": "2.323.0",
+    "@lightdash/common": "2.324.0",
+    "@lightdash/warehouses": "2.324.0",
     "@sidvind/better-ajv-errors": "7.0.0",
     "@types/columnify": "1.5.1",
     "ajv": "8.18.0",