@lightdash/cli 1.0.0 → 1.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
|
@@ -0,0 +1,82 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: sdk-features
|
|
3
|
+
description: Map Lightdash SDK capabilities to their host-UI names and the app-code wiring each needs. Use when the user asks about a feature by name (Inspect data, drill-down, exports, shareable URLs), when offering newly available features after a template upgrade, or when wiring a host-facing capability into the app.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
The `@lightdash/query-sdk` in this workspace declares its capabilities in a
|
|
7
|
+
registry: `node_modules/@lightdash/query-sdk/dist/features.js` (`SDK_FEATURES`,
|
|
8
|
+
each `{ key, label, description, wiring? }`). That registry is the source of
|
|
9
|
+
truth — never invent capabilities from export lists or type definitions. This
|
|
10
|
+
skill adds what the registry can't: how each feature maps to the Lightdash
|
|
11
|
+
host UI and the exact wiring recipe.
|
|
12
|
+
|
|
13
|
+
## Vocabulary: users speak host-UI, the SDK speaks keys
|
|
14
|
+
|
|
15
|
+
Users describe features by what they see in the Lightdash editor. Translate:
|
|
16
|
+
|
|
17
|
+
| User says / host UI | Registry key | Wiring |
|
|
18
|
+
| --- | --- | --- |
|
|
19
|
+
| "Inspect data" (Queries panel button) | `lineage` | required — see below |
|
|
20
|
+
| "select an element", editor element picker | `inspect` | none (automatic) |
|
|
21
|
+
| thumbnails / screenshots / scheduled deliveries | `screenshot` | required — see below |
|
|
22
|
+
| drill down, click into a chart | `drill-down` | app code opt-in |
|
|
23
|
+
| "share this view", URL that restores state | `url-state` | app code opt-in |
|
|
24
|
+
| Google Sheets export | `gsheet-export` | app code opt-in |
|
|
25
|
+
| external API data | `external-fetch` | app code opt-in |
|
|
26
|
+
| runs inside a dashboard tile | `viz-context` | required — see below |
|
|
27
|
+
|
|
28
|
+
## Automatic (zero wiring — active on any current-SDK bundle)
|
|
29
|
+
|
|
30
|
+
`createClient()` mounts these itself: the capability **manifest**, the editor
|
|
31
|
+
**element inspector** (`inspect`), and the **lineage runtime**. Core querying
|
|
32
|
+
(`query`, `saved-chart` via `useLightdash`/`savedChart`) is just normal SDK
|
|
33
|
+
usage. If the app calls `createClient()`, these need nothing from you.
|
|
34
|
+
|
|
35
|
+
## Wiring recipes
|
|
36
|
+
|
|
37
|
+
### `lineage` — the host's "Inspect data" button
|
|
38
|
+
|
|
39
|
+
The lineage runtime only announces itself once the DOM contains
|
|
40
|
+
`data-ld-query` stamps; until then the host's Inspect data button stays
|
|
41
|
+
disabled. Spread the `lineage` props returned by `useLightdash` onto the root
|
|
42
|
+
element of every query-bound block:
|
|
43
|
+
|
|
44
|
+
```jsx
|
|
45
|
+
const { data, lineage } = useLightdash(myQuery);
|
|
46
|
+
return <div {...lineage}>{/* chart rendered from data */}</div>;
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
Stamp every visualization, not just one — each stamp maps that block to its
|
|
50
|
+
query in the host's Queries panel.
|
|
51
|
+
|
|
52
|
+
### `screenshot` — thumbnails and scheduled deliveries
|
|
53
|
+
|
|
54
|
+
Provided by the template file `src/screenshotHandler.js`; `main.jsx` must
|
|
55
|
+
import and call it (`initScreenshotHandler()`). Apps migrated from older
|
|
56
|
+
templates may be missing the file or the call — copy the file from the
|
|
57
|
+
template and add the call rather than reimplementing.
|
|
58
|
+
|
|
59
|
+
### `viz-context` — apps embedded as dashboard tiles
|
|
60
|
+
|
|
61
|
+
Wrap the app in `VizContextProvider` (see the template `main.jsx`) and read
|
|
62
|
+
the host-supplied query context with `useVizContext`. Only relevant for
|
|
63
|
+
visualization-style apps meant to run inside dashboards.
|
|
64
|
+
|
|
65
|
+
### App-code opt-ins (call the API where it fits the app)
|
|
66
|
+
|
|
67
|
+
- `drill-down`: `drillDown(...)` derives a more detailed query from a clicked
|
|
68
|
+
result row — wire it to click handlers on charts/rows.
|
|
69
|
+
- `url-state`: `useUrlState(...)` syncs a piece of app state into the page URL
|
|
70
|
+
so views can be shared and restored.
|
|
71
|
+
- `gsheet-export`: `exportToSheets(...)` sends tabular results to a new
|
|
72
|
+
Google Sheet — offer it wherever the app renders a table.
|
|
73
|
+
- `external-fetch`: `client.externalFetch(alias, opts)` calls an external
|
|
74
|
+
connection linked to this app. The connection must already be linked by the
|
|
75
|
+
host; you cannot add one from app code.
|
|
76
|
+
|
|
77
|
+
## After a template upgrade
|
|
78
|
+
|
|
79
|
+
An upgrade rebuilds the app on the current SDK, which turns on the automatic
|
|
80
|
+
capabilities but does NOT add wiring — that is a deliberate rail. When you
|
|
81
|
+
offer newly available features, offer wiring-required ones too (their registry
|
|
82
|
+
entries carry a `wiring` note); implement only when the user asks.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@lightdash/cli",
|
|
3
|
-
"version": "1.
|
|
3
|
+
"version": "1.1.0",
|
|
4
4
|
"description": "Lightdash CLI tool",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"repository": {
|
|
@@ -41,8 +41,8 @@
|
|
|
41
41
|
"unique-names-generator": "4.7.1",
|
|
42
42
|
"uuid": "11.1.1",
|
|
43
43
|
"yaml": "2.8.3",
|
|
44
|
-
"@lightdash/common": "1.
|
|
45
|
-
"@lightdash/warehouses": "1.
|
|
44
|
+
"@lightdash/common": "1.1.0",
|
|
45
|
+
"@lightdash/warehouses": "1.1.0"
|
|
46
46
|
},
|
|
47
47
|
"devDependencies": {
|
|
48
48
|
"@types/inquirer": "8.2.4",
|