@lightdash/cli 2.167.3 → 2.168.0

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

@@ -0,0 +1,50 @@
+{
+    "fieldMapping": {
+        "category": "orders_status",
+        "value": "orders_total_revenue"
+    },
+    "rows": [
+        {
+            "orders_status": {
+                "value": { "raw": "completed", "formatted": "Completed" }
+            },
+            "orders_total_revenue": {
+                "value": { "raw": 42800, "formatted": "$42,800" }
+            }
+        },
+        {
+            "orders_status": {
+                "value": { "raw": "shipped", "formatted": "Shipped" }
+            },
+            "orders_total_revenue": {
+                "value": { "raw": 31500, "formatted": "$31,500" }
+            }
+        },
+        {
+            "orders_status": {
+                "value": { "raw": "placed", "formatted": "Placed" }
+            },
+            "orders_total_revenue": {
+                "value": { "raw": 18200, "formatted": "$18,200" }
+            }
+        },
+        {
+            "orders_status": {
+                "value": { "raw": "returned", "formatted": "Returned" }
+            },
+            "orders_total_revenue": {
+                "value": { "raw": 6400, "formatted": "$6,400" }
+            }
+        }
+    ],
+    "options": {
+        "showLabels": true,
+        "maxBars": 10
+    },
+    "colorPalette": ["#7162FF", "#1A9AAA", "#E5A800", "#DA5D2B", "#3B82F6"],
+    "seriesColors": {},
+    "valueColors": {},
+    "pivotDetails": null,
+    "underlyingData": { "enabled": false },
+    "drillDown": { "enabled": false }
+}

package/dist/handlers/apps/scaffolding.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"scaffolding.d.ts","sourceRoot":"","sources":["../../../src/handlers/apps/scaffolding.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAMzD;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,MAAM,GAAG,IAAI,CAKpE;AA6DD;;;GAGG;AACH,eAAO,MAAM,oBAAoB,gBAChB,MAAM,WACV,MAAM,KAChB,MAAmE,CAAC;AAEvE;;;;GAIG;AACH,eAAO,MAAM,wBAAwB,eACrB,MAAM,KACnB,MAAM,CAAC,MAAM,EAAE,MAAM,CAevB,CAAC;AAWF,eAAO,MAAM,yBAAyB,eACtB,MAAM,KACnB,eAAe,EAeb,CAAC;AAEN,eAAO,MAAM,yBAAyB,QAAO,eAAe,EAG3D,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,QAAO,eAQ1C,CAAC;AAEF,4EAA4E;AAC5E,MAAM,MAAM,eAAe,GAAG,KAAK,GAAG,YAAY,CAAC;AAEnD;;GAEG;AACH,eAAO,MAAM,yBAAyB,SAAU;IAC5C,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,eAAe,CAAC;CAC5B,KAAG,eAAe,EAkFlB,CAAC"}
+{"version":3,"file":"scaffolding.d.ts","sourceRoot":"","sources":["../../../src/handlers/apps/scaffolding.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAMzD;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,MAAM,GAAG,IAAI,CAKpE;AA6DD;;;GAGG;AACH,eAAO,MAAM,oBAAoB,gBAChB,MAAM,WACV,MAAM,KAChB,MAAmE,CAAC;AAEvE;;;;GAIG;AACH,eAAO,MAAM,wBAAwB,eACrB,MAAM,KACnB,MAAM,CAAC,MAAM,EAAE,MAAM,CAevB,CAAC;AAWF,eAAO,MAAM,yBAAyB,eACtB,MAAM,KACnB,eAAe,EAeb,CAAC;AAEN,eAAO,MAAM,yBAAyB,QAAO,eAAe,EAG3D,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,QAAO,eAQ1C,CAAC;AAEF,4EAA4E;AAC5E,MAAM,MAAM,eAAe,GAAG,KAAK,GAAG,YAAY,CAAC;AAEnD;;GAEG;AACH,eAAO,MAAM,yBAAyB,SAAU;IAC5C,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,eAAe,CAAC;CAC5B,KAAG,eAAe,EA2FlB,CAAC"}

package/dist/handlers/apps/scaffolding.js

@@ -135,6 +135,13 @@ const buildStaticAuthoringFiles = (args) => {
             path: '.claude/skills/developing-chart-types-locally/SKILL.md',
             contentBase64: (0, fs_1.readFileSync)(path.join(authoringDir, 'developing-chart-types-locally', 'SKILL.md')).toString('base64'),
         });
+        // Starter fixture for the SDK's dev-only preview fallback: open the dev
+        // server with `?vizFixture=/viz-fixture.json` to render the chart
+        // without the Lightdash host (see developing-chart-types-locally).
+        files.push({
+            path: 'viz-fixture.json',
+            contentBase64: (0, fs_1.readFileSync)(path.join(authoringDir, 'chart-type', 'viz-fixture.json')).toString('base64'),
+        });
     }
     if (!isChartType) {
         // skill.md → .claude/skills/lightdash-data-app/SKILL.md

package/dist/handlers/apps/scaffolding.test.js

@@ -101,6 +101,28 @@ describe('buildStaticAuthoringFiles', () => {
         expect(files.every((f) => !f.path.startsWith('src/'))).toBe(true);
     });
 });
+describe('buildStaticAuthoringFiles — chart-type flavor', () => {
+    const files = (0, scaffolding_1.buildStaticAuthoringFiles)({
+        appName: 'Radial gauge',
+        sdkVersion: '0.3275.0',
+        flavor: 'chart-type',
+    });
+    const byPath = (p) => files.find((f) => f.path === p);
+    const text = (p) => Buffer.from(byPath(p).contentBase64, 'base64').toString('utf-8');
+    it('ships the chart-type workflow skill, not the app skills', () => {
+        expect(byPath('.claude/skills/developing-chart-types-locally/SKILL.md')).toBeDefined();
+        expect(byPath('.claude/skills/lightdash-data-app/SKILL.md')).toBeUndefined();
+    });
+    it('ships a starter viz fixture for local preview', () => {
+        const fixture = JSON.parse(text('viz-fixture.json'));
+        expect(fixture.fieldMapping.category).toBeDefined();
+        expect(fixture.fieldMapping.value).toBeDefined();
+        expect(Array.isArray(fixture.rows)).toBe(true);
+    });
+    it('documents the fixture preview flow in AGENTS.md', () => {
+        expect(text('AGENTS.md')).toContain('vizFixture');
+    });
+});
 describe('loadVendoredBuildScaffold', () => {
     const files = (0, scaffolding_1.loadVendoredBuildScaffold)('0.3275.0');
     const byPath = (p) => files.find((file) => file.path === p);

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

@@ -19,7 +19,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.
 
-There is no local preview for a chart type: `useVizContext()` waits for the Lightdash host, so the component renders nothing standalone (`lightdash apps preview` and `npm run dev` show a blank page). Upload and verify in the explorer instead.
+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.
 
 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/README.md.tmpl

@@ -10,7 +10,7 @@ Run these commands from this folder under `chart-types/<slug>/`. The upload path
 3. `lightdash upload --chart-types <slug> --path ../..` (the `slug` from `lightdash-app.yml`) — Lightdash rebuilds and serves it.
 4. Open any explore in Lightdash, run a query, and pick this chart type in the chart type picker to see it against real data.
 
-There is no standalone preview: the component waits for the Lightdash host's data, so `npm run dev` shows a blank page. Upload and verify in the explorer.
+Preview locally with the included `viz-fixture.json`: run `lightdash apps preview` (or `npm run dev`) and open the dev URL with `?vizFixture=/viz-fixture.json`. The SDK's dev-only fallback seeds `useVizContext()` from that file so the chart renders without the Lightdash host. Edit the fixture to match your `vizSchema`. It's fake data for layout iteration and never runs in production — the explorer with real data is the source of truth, so upload and verify there too.
 
 ## What's read-only
 Root config (`vite.config.js`, `tsconfig.json`, etc.) is read-only reference — the server rebuilds against a trusted template. Build within the template's fixed dependency set (see `package.json`); chart types published to the official registry must stay template-deps-only.

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

@@ -0,0 +1,50 @@
+{
+    "fieldMapping": {
+        "category": "orders_status",
+        "value": "orders_total_revenue"
+    },
+    "rows": [
+        {
+            "orders_status": {
+                "value": { "raw": "completed", "formatted": "Completed" }
+            },
+            "orders_total_revenue": {
+                "value": { "raw": 42800, "formatted": "$42,800" }
+            }
+        },
+        {
+            "orders_status": {
+                "value": { "raw": "shipped", "formatted": "Shipped" }
+            },
+            "orders_total_revenue": {
+                "value": { "raw": 31500, "formatted": "$31,500" }
+            }
+        },
+        {
+            "orders_status": {
+                "value": { "raw": "placed", "formatted": "Placed" }
+            },
+            "orders_total_revenue": {
+                "value": { "raw": 18200, "formatted": "$18,200" }
+            }
+        },
+        {
+            "orders_status": {
+                "value": { "raw": "returned", "formatted": "Returned" }
+            },
+            "orders_total_revenue": {
+                "value": { "raw": 6400, "formatted": "$6,400" }
+            }
+        }
+    ],
+    "options": {
+        "showLabels": true,
+        "maxBars": 10
+    },
+    "colorPalette": ["#7162FF", "#1A9AAA", "#E5A800", "#DA5D2B", "#3B82F6"],
+    "seriesColors": {},
+    "valueColors": {},
+    "pivotDetails": null,
+    "underlyingData": { "enabled": false },
+    "drillDown": { "enabled": false }
+}

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

@@ -1,6 +1,6 @@
 ---
 name: developing-chart-types-locally
-description: Use when editing a locally created or downloaded Lightdash custom chart type (data_app_viz) — the vizSchema/component lockstep contract, the upload-and-verify loop, why there is no standalone preview, and how a chart type reaches the official registry.
+description: Use when editing a locally created or downloaded Lightdash custom chart type (data_app_viz) — the vizSchema/component lockstep contract, the upload-and-verify loop, the local fixture preview, and how a chart type reaches the official registry.
 ---
 
 # Developing Lightdash Custom Chart Types Locally
@@ -26,10 +26,20 @@ Run these commands from this folder under `chart-types/<slug>/`. The upload path
 3. `lightdash upload --chart-types <slug> --path ../..` (the `slug` from `lightdash-app.yml`) — the server rebuilds and serves it.
 4. Verify in Lightdash: open any explore, run a query with at least the required fields' shapes (e.g. a dimension and a metric), pick this chart type in the chart type picker, and map its fields. Check every config option you declared actually changes the chart.
 
-**There is no standalone preview.** `useVizContext()` waits for the Lightdash host to push context, so outside Lightdash the component renders nothing: `npm run dev` and `lightdash apps preview` show a blank page. Do not build a mock harness or feed the hook fake data to work around this — upload and verify in the explorer instead.
-
 Saved charts already using this chart type may pin a version; unpinned charts move to the newly uploaded version right away. While iterating in a shared project, prefer verifying on a throwaway chart.
 
+## Preview locally with a fixture (fast layout iteration)
+
+`useVizContext()` normally waits for the Lightdash host to push a context, so with no host the component renders nothing. For local iteration the SDK has a **dev-only fixture fallback**: when the app runs top-level (not embedded) and the page URL carries `?vizFixture=<path>`, it fetches that same-origin JSON file and feeds it to `useVizContext()` as the context.
+
+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.
+
+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.
+
 ## Dependencies: template-deps-only, strictly
 
 Build with the template's preinstalled set (see `package.json` — React, Recharts, d3 and friends). Do not add npm packages and do not vendor library source into `src/`. This is stricter than for data apps: the official chart registry rejects any dependency drift from its template, so a chart type that grows custom dependencies becomes unpublishable.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lightdash/cli",
-  "version": "2.167.3",
+  "version": "2.168.0",
   "description": "Lightdash CLI tool",
   "license": "MIT",
   "repository": {
@@ -45,8 +45,8 @@
     "unique-names-generator": "4.7.1",
     "uuid": "11.1.1",
     "yaml": "2.8.3",
-    "@lightdash/common": "2.167.3",
-    "@lightdash/warehouses": "2.167.3"
+    "@lightdash/common": "2.168.0",
+    "@lightdash/warehouses": "2.168.0"
   },
   "devDependencies": {
     "@types/inquirer": "8.2.4",