@lightdash/cli 2.290.0 → 2.291.0

package/dist/vendor/authoring/chart-type/lightdash-library-theme.md

@@ -96,9 +96,13 @@ turn missing values into zeros, or sample away facts without disclosure.
 Honor saved options and pivoted results. Empty, invalid, and zero-only states
 explain the relevant condition in `var(--ll-text-muted)`.
 
-Preserve native **View underlying data** and **Drill into** on eligible
-marks, retaining original result-row references through transforms. Marks are
-inspectable by pointer and keyboard. Decorative overlays use
+Never hand-build a data-point action menu when
+`useVizContext().pointMenu.enabled` — call `pointMenu.open({ x, y, row, metric })`
+and let Lightdash render it; an in-viz menu is only the fallback for hosts that
+predate the capability. Preserve native **View underlying data** and **Drill
+into** on eligible marks (via `pointMenu`, or the `underlyingData`/`drillDown`
+fallback), retaining original result-row references through transforms. Marks
+are inspectable by pointer and keyboard. Decorative overlays use
 `pointer-events: none`. Scope SVG gradient/mask/pattern IDs uniquely.
 Reduced motion disables reveal effects; animation is never the mechanism
 that makes data visible.

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

@@ -11,6 +11,8 @@ You are editing a Lightdash **custom chart type** (a reusable visualization, the
 
 Read `.claude/skills/reusable-visualization` before editing. It defines everything the component may do: `useVizContext()` is the only channel to the host (data, options, resolved colours), the component runs no query, owns no explore, and never fetches anything itself. App-level SDK APIs (query builder, `useLightdash`, filters, `externalFetch`) do not apply here and must not be introduced.
 
+Never hand-build a data-point action menu when `useVizContext().pointMenu.enabled` — call `pointMenu.open({ x, y, row, metric })` and let Lightdash render it; an in-viz menu is only the fallback for hosts that predate the capability.
+
 ## The declaration lives in lightdash-app.yml — keep it in lockstep
 
 In the in-product builder the declaration is emitted by the generation run; **locally it is the `vizSchema` block in this folder's `lightdash-app.yml`**, and upload round-trips it to the server (without it the chart type never appears in the explorer's chart type picker).

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

@@ -35,6 +35,7 @@ const {
   colorPalette,
   pivotDetails,
   ready,
+  pointMenu,
   underlyingData,
   drillDown,
 } = context;
@@ -57,9 +58,13 @@ const {
 - `pivotDetails` — the complete backend-pivot layout, or `null` for ordinary rows. See
   "Backend-pivoted results" below.
 - `ready` — false until the first context arrives.
-- `underlyingData` — host-mediated access to the raw rows behind a clicked data point.
-  See "Data-point actions" below.
-- `drillDown` — host-mediated drill on a clicked data point. See "Data-point
+- `pointMenu` — host-rendered data-point action menu for a clicked mark; this is
+  the current data-point action contract. See "Data-point actions" below.
+- `underlyingData` — host-mediated access to the raw rows behind a clicked data point;
+  the fallback per-action dialog for hosts that predate `pointMenu`. See
+  "Data-point actions" below.
+- `drillDown` — host-mediated drill on a clicked data point; the fallback
+  per-action dialog for hosts that predate `pointMenu`. See "Data-point
   actions" below.
 
 Read all of them. Pass the complete `context` to the colour helpers; they preserve model
@@ -169,18 +174,46 @@ declared series fields builds its label from each matching `pivotValues` entry i
 field order. Backend-pivoted rows do not have safe one-source-row provenance, so the host
 sets `underlyingData.enabled` to false for them.
 
-## Data-point actions: underlying data and drill-down
+## Data-point actions: pointMenu, underlying data, and drill-down
 
-Every chart whose marks satisfy the provenance rule below MUST wire the data-point
-action menu. This is part of the component contract, not an optional nicety — a
-"keep it minimal" prompt does not waive it. The flags decide at RUNTIME whether each
-item shows; you always write the wiring, and it costs nothing visually when disabled.
+Every chart whose marks satisfy the provenance rule below MUST wire the standard
+data-point action. This is part of the component contract, not an optional nicety —
+a "keep it minimal" prompt does not waive it. `pointMenu.enabled` (or, on the
+fallback path, `underlyingData.enabled` and `drillDown.enabled`) decides at RUNTIME
+whether anything shows; you always write the wiring, and it costs nothing visually
+when disabled.
 
-When `underlyingData.enabled` is true, viewers get the standard Lightdash action on
-chart marks: click a data point → small action menu → "View underlying data" → the
-standard Lightdash dialog listing the raw rows behind that point, with its Download
-button. When it is false (host too old, viewer lacks permission, embed), render no menu
-item — never a disabled one.
+### `pointMenu`: the current contract
+
+The current contract is a single call on click: `pointMenu.open({ x, y, row, metric,
+fieldId? })`, with `x`/`y` taken from the click event's `clientX`/`clientY`. Lightdash
+renders the entire menu — copy value, view underlying data, drill, dashboard
+cross-filtering — over the viz and owns all subsequent UI; the component renders no
+menu of its own. `pointMenu.open` resolves `{ shown: boolean }`; `shown: false` means
+the host had no applicable action for that point, and the component still renders
+nothing extra.
+
+```tsx
+onClick={(event, datum) => {
+  if (pointMenu.enabled) {
+    pointMenu
+      .open({
+        x: event.clientX,
+        y: event.clientY,
+        row: datum.sourceRow,
+        metric: 'value',
+      })
+      .catch(() => {});
+    return;
+  }
+  // Fallback for hosts that predate the point menu:
+  openLocalActionMenu(event, datum);
+}}
+```
+
+Only when `pointMenu.enabled` is false (a host that predates the capability) does the
+component fall back to building its own in-viz action menu from `underlyingData.open`
+and `drillDown.open`, as described in the rest of this section.
 
 Provenance is the contract: **every interactive datum keeps a reference to its
 untransformed source row.** When mapping `rows` into chart data, carry the row:
@@ -189,13 +222,25 @@ untransformed source row.** When mapping `rows` into chart data, carry the row:
 const data = rows.map((row) => ({
   label: getFormatted(row, catField),
   value: Number(getRaw(row, valField) ?? 0),
-  sourceRow: row,               // ← required for underlying data
+  sourceRow: row,               // ← required for the data-point action
 }));
 ```
 
 Only attach the action where one mark maps to exactly ONE source row and ONE metric-slot
 field. A mark that aggregates several rows (a binned bucket, a "top N + other" slice)
-gets no underlying-data item.
+gets no data-point action.
+
+### Fallback: the in-viz action menu
+
+Everything through "Open the menu at the data point" below applies only when
+`pointMenu.enabled` is false. It calls the two per-action APIs directly and builds
+its own accessible in-viz menu instead of delegating to a Lightdash-rendered one.
+
+When `underlyingData.enabled` is true, viewers get the fallback action on chart
+marks: click a data point → small action menu → "View underlying data" → the
+standard Lightdash dialog listing the raw rows behind that point, with its Download
+button. When it is false (host too old, viewer lacks permission, embed), render no menu
+item — never a disabled one.
 
 On click, send the intent and render nothing else. Lightdash opens the dialog outside
 the viz and owns its table, loading, error, sorting, and download controls:
@@ -280,7 +325,7 @@ const registerMark = (key, node) => {
   if (node) markElements.current.set(key, node);
   else markElements.current.delete(key);
 };
-const openPointMenu = (datum, anchor) => {
+const openFallbackMenu = (datum, anchor) => {
   if (!underlyingData.enabled && !drillDown.enabled) return;
   const rect = anchor.activator.getBoundingClientRect();
   setTooltipVisible(false);
@@ -318,8 +363,9 @@ const openPointMenu = (datum, anchor) => {
 
 ### Interaction hygiene
 
-One floating surface at a time, and no leftover emphasis — native Lightdash
-charts show a menu OR a tooltip, never both, and clicking leaves no mark
+These rules apply on both paths — the host-rendered `pointMenu` and the fallback
+in-viz menu. One floating surface at a time, and no leftover emphasis — native
+Lightdash charts show a menu OR a tooltip, never both, and clicking leaves no mark
 highlighted:
 
 - **Opening the action menu closes the tooltip.** Drive tooltip visibility
@@ -545,9 +591,10 @@ matters. Keep that help reusable across queries: describe the chart contract rat
 specific dataset.
 
 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
-action is gated on `underlyingData.enabled`, and the drill action is gated on
-`drillDown.enabled`. Omitting the menu on a chart whose marks satisfy
+is wired: each interactive datum carries `sourceRow`, and the click handler calls
+`pointMenu.open({ x, y, row, metric })` when `pointMenu.enabled`, falling back to
+an in-viz menu — gated on `underlyingData.enabled` and `drillDown.enabled` — only
+when it is not. Omitting the action on a chart whose marks satisfy
 provenance is a defect, not a simplification. Then click a mark mentally:
 the tooltip closes, nothing stays highlighted, and only the menu remains —
 one floating surface at a time.

package/dist/vendor/template/.claude/skills/sdk-features/SKILL.md

@@ -28,6 +28,7 @@ Users describe features by what they see in the Lightdash editor. Translate:
 | external API data | `external-fetch` | app code opt-in |
 | runs inside a dashboard tile | `viz-context` | required — see below |
 | reusable chart/table with pivoted results | `viz-pivoted-results` | required — see below |
+| "Data point actions" — native context menu on a data-point click (copy, view underlying data, drill, cross-filter; viz only) | `point-action-menu` | app code opt-in |
 | "view underlying data", raw rows behind a point (viz only) | `viz-underlying-data` | app code opt-in |
 | Lightdash-owned "View underlying data" dialog (viz only) | `viz-host-underlying-data` | app code opt-in |
 | light/dark mode, "matches my Lightdash theme" | `follow-host-theme` | CSS tokens — see below |
@@ -106,10 +107,23 @@ order, `sortBy` describes result ordering, `totalColumnCount` exposes truncation
 
 - `drill-down`: `drillDown(...)` derives a more detailed query from a clicked
   result row — wire it to click handlers on charts/rows.
-- `viz-drill-down`: in a reusable visualization, the data-point action menu
-  offers "Drill into …" when `useVizContext().drillDown.enabled`; selection
-  calls `drillDown.open({ row, metric })` and Lightdash opens its drill
-  dialog. Distinct from `drill-down`, which is the full-app query helper.
+- `point-action-menu` (vizs only): the primary data-point-action contract. On a
+  data-point click, when `useVizContext().pointMenu.enabled`, call
+  `pointMenu.open({ x: event.clientX, y: event.clientY, row: datum.sourceRow, metric: '<field name>' })`
+  and render no menu of your own — Lightdash renders the entire native menu
+  (copy value, view underlying data, drill, dashboard cross-filtering) and
+  owns all subsequent UI. `viz-drill-down` and
+  `viz-underlying-data`/`viz-host-underlying-data` below are the
+  `pointMenu.enabled === false` fallback for older hosts, not a separate
+  feature to wire in addition.
+- `viz-drill-down`: in a reusable visualization, when
+  `useVizContext().pointMenu.enabled`, call `pointMenu.open({ x, y, row, metric })`
+  and render no menu of your own — Lightdash's menu offers "Drill into …".
+  Only when `pointMenu.enabled` is false, fall back to a local data-point
+  action menu gated on `drillDown.enabled` and call
+  `drillDown.open({ row, metric })` on selection. Either way Lightdash opens
+  its drill dialog. Distinct from `drill-down`, which is the full-app query
+  helper.
 - `url-state`: `useUrlState(...)` syncs a piece of app state into the page URL
   so views can be shared and restored.
 - `gsheet-export`: `exportToSheets(...)` sends tabular results to a new
@@ -137,11 +151,13 @@ order, `sortBy` describes result ordering, `totalColumnCount` exposes truncation
   visible — never mount all tabs unconditionally (interactive loads must stay
   lazy).
 - `viz-underlying-data` and `viz-host-underlying-data` (vizs only): keep the
-  untransformed `sourceRow` on each interactive datum, gate a data-point action menu on
-  `useVizContext().underlyingData.enabled`, and call
-  `underlyingData.open({ row, metric })`. Lightdash renders the dialog and
-  owns its table, loading, error, and download controls. Full contract in the
-  `reusable-visualization` skill.
+  untransformed `sourceRow` on each interactive datum. When
+  `useVizContext().pointMenu.enabled`, call `pointMenu.open({ x, y, row, metric })`
+  and render no menu of your own. Only when `pointMenu.enabled` is false, fall
+  back to a local data-point action menu gated on `underlyingData.enabled` and
+  call `underlyingData.open({ row, metric })` on selection. Either way,
+  Lightdash renders the dialog and owns its table, loading, error, and
+  download controls. Full contract in the `reusable-visualization` skill.
 
 ## After a template upgrade
 

package/package.json

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