@lightdash/cli 2.53.0 → 2.54.0

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

@@ -27,6 +27,7 @@ fetch anything yourself; the only host interaction is through the helpers the ho
 returns.
 
 ```tsx
+const context = useVizContext();
 const {
   fieldMapping,
   rows,
@@ -36,7 +37,7 @@ const {
   ready,
   underlyingData,
   drillDown,
-} = useVizContext();
+} = context;
 ```
 
 - `fieldMapping` — `Record<string, string>`: the field name you declared → the query field
@@ -47,6 +48,11 @@ const {
   option you declared (the viewer's choice, else your declared `default`).
 - `colorPalette` — `string[]`: the Lightdash palette resolved for this chart. Always pushed,
   whether or not you declared `colorPalette`. Empty only when the host resolved none.
+- `seriesColors` — `Record<string, string>`: final host-resolved colours keyed by backend
+  pivot column name. Read them through `resolveSeriesColor(context, column, index)`.
+- `valueColors` — `Record<string, Record<string, string>>`: final host-resolved colours keyed
+  by query field id then raw value. Read them through
+  `resolveValueColor(context, fieldId, rawValue, index)`.
 - `pivotDetails` — the complete backend-pivot layout, or `null` for ordinary rows. See
   "Backend-pivoted results" below.
 - `ready` — false until the first context arrives.
@@ -55,8 +61,8 @@ const {
 - `drillDown` — host-mediated drill on a clicked data point. See "Data-point
   actions" below.
 
-Read all of them. Ignoring `options` and `colorPalette` is the most common way to build a
-viz nobody can configure.
+Read all of them. Pass the complete `context` to the colour helpers; they preserve model
+colours and shared dashboard assignments before falling back to `colorPalette`.
 
 ### These app-level APIs do not apply to a viz
 
@@ -82,10 +88,15 @@ shadcn, charting, theming, floating surfaces, screenshots) still applies.
 
 ## Series colours
 
-Never hardcode series hex values and never hand-pick a palette of your own. Colour series
-with `colorPalette[i % colorPalette.length]`, and declare `colorPalette` in your output so
-the viewer gets the palette picker. Keep a small fallback array in your own code for the
-case where `colorPalette` is empty.
+Use the query SDK's host-resolved colour helpers for every series or group:
+
+- Backend-pivoted series: `resolveSeriesColor(context, column, index)`.
+- Client-side groups: `resolveValueColor(context, fieldId, rawValue, index)`.
+
+The helpers first honor model-defined fixed colours and Lightdash's shared dashboard colour
+assignment, then fall back to `colorPalette[index % colorPalette.length]`. Keep a small
+fallback array only for the case where the helper returns `undefined`, and declare
+`colorPalette` in your output so the viewer gets the palette picker.
 
 This is the same rule as the sandbox skill's "chart series colors must come from
 `CHART_COLORS`" and `references/d3.md`'s "never hand-pick palettes" — the same Lightdash
@@ -132,11 +143,12 @@ const pivotedMetrics =
     (column) => column.referenceField === metricId,
   ) ?? [];
 
-const series = pivotedMetrics.map((column) => ({
+const series = pivotedMetrics.map((column, index) => ({
   columnId: column.pivotColumnName,
   label:
     column.pivotValues.find((value) => value.referenceField === seriesId)
       ?.formatted ?? 'Unknown',
+  color: resolveSeriesColor(context, column, index) ?? FALLBACK_COLORS[index % FALLBACK_COLORS.length],
 }));
 
 const categoryId = fieldMapping['category'];
@@ -151,7 +163,7 @@ const data = rows.map((row) => ({
 }));
 ```
 
-Use the order of `valuesColumns` for stable colour assignment. A chart with multiple
+Use the order of `valuesColumns` for the helper's fallback index. A chart with multiple
 declared series fields builds its label from each matching `pivotValues` entry in declared
 field order. Backend-pivoted rows do not have safe one-source-row provenance, so the host
 sets `underlyingData.enabled` to false for them.
@@ -275,8 +287,8 @@ One entry per data column the component reads:
 ### `configOptions`
 
 One entry per setting the viewer can change without regenerating the viz. Every option is a
-whole-viz value applying to the entire chart — there is no per-series option. To colour
-series individually, index into `colorPalette` by series position.
+whole-viz value applying to the entire chart — there is no per-series option. Colour series
+and groups with the SDK's resolved-colour helpers.
 
 Every option has:
 
@@ -301,9 +313,10 @@ Series colours are not in this list. They are declared separately, on `colorPale
 ### `colorPalette`
 
 Whether the viewer gets the standard Lightdash palette picker. Declare
-`{ "group": "..." }` when your component colours anything from `colorPalette`, or `null`
-when it colours nothing. `group` is optional and works like an option's: the picker joins
-that tab, and gets a tab of its own when no option shares the name.
+`{ "group": "..." }` when your component colours anything with the resolved-colour helpers
+or `colorPalette`, or `null` when it colours nothing. `group` is optional and works like an
+option's: the picker joins that tab, and gets a tab of its own when no option shares the
+name.
 
 This is not a config option. There is one palette per chart, it has no `name` and no
 `default`, and its colours arrive on `colorPalette` — never on `options`.
@@ -313,19 +326,21 @@ This is not a config option. There is one palette per chart, it has no `name` an
 Component and declaration lining up. Your chart will differ; the correspondence must not.
 
 ```tsx
-import { useVizContext, getFormatted, getRaw } from '@lightdash/query-sdk';
+import { useVizContext, getFormatted, getRaw, resolveValueColor } from '@lightdash/query-sdk';
 import { Bar, BarChart, Cell, LabelList, ResponsiveContainer, Tooltip, XAxis, YAxis } from 'recharts';
 
 function Chart() {
-  const { fieldMapping, rows, options, colorPalette, ready } = useVizContext();
+  const context = useVizContext();
+  const { fieldMapping, rows, options, ready } = context;
   if (!ready) return <div style={{ height: '100vh' }}>Loading…</div>;
   const catField = fieldMapping['category'];            // your field name -> column id
   const valField = fieldMapping['value'];
   const showLabels = options['showLabels'] as boolean;  // your option name -> current value
   const maxBars = options['maxBars'] as number;
-  const colors = colorPalette.length ? colorPalette : ['#7162FF', '#1A1B1E'];
+  const fallbackColors = ['#7162FF', '#1A1B1E'];
   const data = rows.slice(0, maxBars).map((row) => ({
     label: getFormatted(row, catField),                 // display text, e.g. "Completed"
+    category: getRaw(row, catField),                    // raw value for host-resolved colour
     value: Number(getRaw(row, valField) ?? 0),          // raw number
   }));
   return (
@@ -340,7 +355,12 @@ function Chart() {
           <YAxis tickFormatter={(v) => v.toLocaleString()} />
           <Tooltip />
           <Bar dataKey="value">
-            {data.map((d, i) => <Cell key={d.label} fill={colors[i % colors.length]} />)}
+            {data.map((d, i) => (
+              <Cell
+                key={d.label}
+                fill={resolveValueColor(context, catField, d.category, i) ?? fallbackColors[i % fallbackColors.length]}
+              />
+            ))}
             {showLabels && <LabelList dataKey="value" position="top" />}
           </Bar>
         </BarChart>
@@ -372,15 +392,16 @@ minimum, not a menu:
 - every number you chose (bar width, max rows, decimal places, a threshold) → `number`
 - every string you wrote into the chart (title, axis label, empty-state text) → `text`
 - every accent colour that is not a series colour (a target line, a highlight) → `color`
-- the series colours, whenever the chart draws more than one series → `colorPalette`
+- the series colours, whenever the chart draws more than one series → resolved-colour
+  helper plus `colorPalette`
 
 Where the answer is yes, make that literal the option's `default`, declare the option, and
 read the option in its place. Leave it hardcoded only where changing it would break the
 chart.
 
 Then check both directions: every key you read from `options` is declared, and every option
-you declared is read somewhere. `colorPalette` is declared when you colour from
-`colorPalette` — it is never read from `options`.
+you declared is read somewhere. `colorPalette` is declared when you use either resolved-
+colour helper or colour from `colorPalette` — it is never read from `options`.
 
 Finally, if any mark maps to exactly one source row, the data-point action
 menu is wired: each interactive datum carries `sourceRow`, the underlying-data

package/dist/vendor/template/skill.md

@@ -1218,6 +1218,15 @@ function tableToCsv(columns: Column[], data: Row[], format: FormatFn): string {
 </ScrollArea>
 ```
 
+### Table and query performance
+
+Treat Safari/WebKit as the constrained target for layout-heavy apps. Test dense tables and filter interactions in Safari: an app that is smooth there will generally be smooth in Chrome, but the reverse is not guaranteed.
+
+- **Bound data-derived columns.** Pivot-style tables that derive columns from dates, categories, or other result values must cap the rendered window. Paginate the column range or virtualize it horizontally; never render an unbounded `dates.map(...)` or equivalent column set.
+- **Keep sticky positioning to headers.** Never apply `position: sticky` to body cells. If a pinned first column is essential, render it as a separate fixed pane synchronized with the scrollable data pane.
+- **Virtualize individual rows, not multi-row groups.** For large tables, avoid mounting virtualized rows inside one shared `<table>` layout where scroll-driven row changes can relayout the whole table. Prefer block or grid rows with fixed column widths, and make each virtual item one row rather than a group containing many rows and cells.
+- **Batch filter-driven queries.** When a control change would refetch multiple queries, debounce the committed filter value or require an Apply action. Do not fire the full query fan-out on every date, granularity, or filter input change.
+
 ### Resizable panels
 
 Only when the user asks for adjustable panel sizing (or two sibling areas genuinely benefit from rebalancing), read `/app/references/resizable-panels.md` and use the pre-installed shadcn `Resizable`. Otherwise use fixed flex/grid proportions — don't reach for it by default.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lightdash/cli",
-  "version": "2.53.0",
+  "version": "2.54.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.53.0",
-    "@lightdash/warehouses": "2.53.0"
+    "@lightdash/warehouses": "2.54.0",
+    "@lightdash/common": "2.54.0"
   },
   "devDependencies": {
     "@types/inquirer": "8.2.4",