@databricks/appkit-ui 0.92.0 → 0.94.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.
- package/CLAUDE.md +3 -0
- package/dist/cli/commands/docs.js +231 -10
- package/dist/cli/commands/docs.js.map +1 -1
- package/dist/cli/commands/plugin/add/add.js +398 -0
- package/dist/cli/commands/plugin/add/add.js.map +1 -0
- package/dist/cli/commands/plugin/add/plan.js +216 -0
- package/dist/cli/commands/plugin/add/plan.js.map +1 -0
- package/dist/cli/commands/plugin/add/resolve.js +45 -0
- package/dist/cli/commands/plugin/add/resolve.js.map +1 -0
- package/dist/cli/commands/plugin/index.js +4 -1
- package/dist/cli/commands/plugin/index.js.map +1 -1
- package/dist/cli/commands/registry/add.js +3 -2
- package/dist/cli/commands/registry/add.js.map +1 -1
- package/dist/cli/commands/registry/config-plan.js +1 -1
- package/dist/cli/commands/registry/config-plan.js.map +1 -1
- package/dist/cli/commands/registry/config-writer.js +77 -9
- package/dist/cli/commands/registry/config-writer.js.map +1 -1
- package/dist/cli/commands/registry/env-writer.js +1 -1
- package/dist/cli/commands/registry/env-writer.js.map +1 -1
- package/dist/cli/commands/registry/server-register.js +62 -26
- package/dist/cli/commands/registry/server-register.js.map +1 -1
- package/dist/cli/commands/registry/workspace-picker.js +1 -1
- package/dist/cli/deploy-config.js.map +1 -1
- package/dist/cli/index.js +1 -1
- package/dist/react/beta.d.ts +3 -1
- package/dist/react/beta.js +3 -1
- package/dist/react/charts/base.d.ts +1 -1
- package/dist/react/charts/base.d.ts.map +1 -1
- package/dist/react/charts/base.js +5 -3
- package/dist/react/charts/base.js.map +1 -1
- package/dist/react/charts/constants.js +13 -1
- package/dist/react/charts/constants.js.map +1 -1
- package/dist/react/charts/create-chart.js +1 -1
- package/dist/react/charts/create-chart.js.map +1 -1
- package/dist/react/charts/index.d.ts +1 -1
- package/dist/react/charts/types.d.ts +17 -8
- package/dist/react/charts/types.d.ts.map +1 -1
- package/dist/react/charts/types.js.map +1 -1
- package/dist/react/charts/wrapper.d.ts +1 -1
- package/dist/react/charts/wrapper.d.ts.map +1 -1
- package/dist/react/charts/wrapper.js +12 -5
- package/dist/react/charts/wrapper.js.map +1 -1
- package/dist/react/design-page.d.ts +33 -0
- package/dist/react/design-page.d.ts.map +1 -0
- package/dist/react/design-page.js +173 -0
- package/dist/react/design-page.js.map +1 -0
- package/dist/react/hooks/use-design-ready.d.ts +19 -0
- package/dist/react/hooks/use-design-ready.d.ts.map +1 -0
- package/dist/react/hooks/use-design-ready.js +33 -0
- package/dist/react/hooks/use-design-ready.js.map +1 -0
- package/dist/react/index.d.ts +2 -2
- package/dist/react/table/data-table.d.ts +6 -0
- package/dist/react/table/data-table.d.ts.map +1 -1
- package/dist/react/table/data-table.js +6 -0
- package/dist/react/table/data-table.js.map +1 -1
- package/dist/shared/src/plugin.d.ts.map +1 -1
- package/docs/api/appkit/Variable.design.md +6 -0
- package/docs/api/appkit-ui/data/AreaChart.md +25 -25
- package/docs/api/appkit-ui/data/BarChart.md +23 -23
- package/docs/api/appkit-ui/data/DataTable.md +2 -0
- package/docs/api/appkit-ui/data/DonutChart.md +24 -24
- package/docs/api/appkit-ui/data/HeatmapChart.md +25 -25
- package/docs/api/appkit-ui/data/LineChart.md +24 -24
- package/docs/api/appkit-ui/data/PieChart.md +24 -24
- package/docs/api/appkit-ui/data/RadarChart.md +22 -22
- package/docs/api/appkit-ui/data/ScatterChart.md +22 -22
- package/docs/api/appkit.md +1 -0
- package/docs/plugins/analytics.md +9 -1
- package/docs/plugins/design.md +233 -0
- package/llms.txt +3 -0
- package/package.json +1 -1
- package/sbom.cdx.json +1 -1
|
@@ -46,28 +46,28 @@ Supports both query mode (queryKey + parameters) and data mode (static data).
|
|
|
46
46
|
|
|
47
47
|
### Props[](#props "Direct link to Props")
|
|
48
48
|
|
|
49
|
-
| Prop | Type | Required | Default | Description
|
|
50
|
-
| ---------------- | --------------------------------------------------------------- | -------- | -------- |
|
|
51
|
-
| `queryKey` | `string` | | - | Analytics query key registered with analytics plugin
|
|
52
|
-
| `parameters` | `Record<string, unknown>` | | - | Query parameters passed to the analytics endpoint
|
|
53
|
-
| `format` | `"auto" \| "json_array" \| "arrow_stream" \| "json" \| "arrow"` | | `"auto"` | Data format to use - "json\_array": Use JSON format (smaller payloads, simpler) - "arrow\_stream": Use Arrow format (faster for large datasets) - "auto": Automatically select based on expected data size
|
|
54
|
-
| `transformer` | `(<T>(data: T) => T)` | | - | Transform raw data before rendering
|
|
55
|
-
| `data` | `
|
|
56
|
-
| `title` | `string` | | - | Chart title
|
|
57
|
-
| `showLegend` | `boolean` | | - | Show legend
|
|
58
|
-
| `colorPalette` | `"categorical" \| "sequential" \| "diverging"` | | - | Color palette to use. Auto-selected based on chart type if not specified. - "categorical": Distinct colors for different categories (bar, pie, line) - "sequential": Gradient for magnitude/intensity (heatmap) - "diverging": Two-tone for positive/negative values
|
|
59
|
-
| `colors` | `string[]` | | - | Custom colors for series (overrides colorPalette)
|
|
60
|
-
| `height` | `number` | |
|
|
61
|
-
| `className` | `string` | | - | Additional CSS classes
|
|
62
|
-
| `xKey` | `string` | | - | X-axis field key. Auto-detected from schema if not provided.
|
|
63
|
-
| `yKey` | `string \| string[]` | | - | Y-axis field key(s). Auto-detected from schema if not provided.
|
|
64
|
-
| `ariaLabel` | `string` | | - | Accessibility label for screen readers
|
|
65
|
-
| `testId` | `string` | | - | Test ID for automated testing
|
|
66
|
-
| `options` | `Record<string, unknown>` | | - | Additional ECharts options to merge
|
|
67
|
-
| `valueFormatter` | `ChartValueFormatter` | | - | Formats measure values in the chart's built-in value axes, tooltips, and value labels. `field` is the corresponding `yKey`, so one formatter can select a different format for each series.
|
|
68
|
-
| `onDataClick` | `((datum: ChartClickDatum) => void)` | | - | Pointer-only: charts render to \<canvas>, so this does not fire for keyboard users. Provide a keyboard-accessible equivalent (e.g. a table row action) for the same action.
|
|
69
|
-
| `selected` | `string \| string[]` | | - | Controlled selection by category name. Matching data element(s) render at full prominence while the rest are dimmed. Drive it from your own state to reflect a cross-filter or selection. Categorical charts (bar, pie/donut) show emphasis; other chart types ignore it.
|
|
70
|
-
| `symbolSize` | `number` | | `8` | Symbol size
|
|
49
|
+
| Prop | Type | Required | Default | Description |
|
|
50
|
+
| ---------------- | --------------------------------------------------------------- | -------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
51
|
+
| `queryKey` | `string` | | - | Analytics query key registered with analytics plugin |
|
|
52
|
+
| `parameters` | `Record<string, unknown>` | | - | Query parameters passed to the analytics endpoint |
|
|
53
|
+
| `format` | `"auto" \| "json_array" \| "arrow_stream" \| "json" \| "arrow"` | | `"auto"` | Data format to use - "json\_array": Use JSON format (smaller payloads, simpler) - "arrow\_stream": Use Arrow format (faster for large datasets) - "auto": Automatically select based on expected data size |
|
|
54
|
+
| `transformer` | `(<T>(data: T) => T)` | | - | Transform raw data before rendering |
|
|
55
|
+
| `data` | `ChartDataInput` | | - | Arrow Table or an array of row objects (interfaces and `as const` arrays too). |
|
|
56
|
+
| `title` | `string` | | - | Chart title |
|
|
57
|
+
| `showLegend` | `boolean` | | - | Show legend |
|
|
58
|
+
| `colorPalette` | `"categorical" \| "sequential" \| "diverging"` | | - | Color palette to use. Auto-selected based on chart type if not specified. - "categorical": Distinct colors for different categories (bar, pie, line) - "sequential": Gradient for magnitude/intensity (heatmap) - "diverging": Two-tone for positive/negative values |
|
|
59
|
+
| `colors` | `string[]` | | - | Custom colors for series (overrides colorPalette) as hex, `rgb()` or `hsl()` strings, since ECharts draws on a canvas and cannot resolve `var()` or parse `oklch()` (those draw gray); without it, series colors are the CSS variables `--chart-cat-1` to `--chart-cat-8` on `:root` (`--chart-seq-*` and `--chart-div-*` for the sequential and diverging palettes), held to the same formats. |
|
|
60
|
+
| `height` | `number` | | - | Chart height in pixels. Defaults to filling its parent (see `chartSizeStyle`). |
|
|
61
|
+
| `className` | `string` | | - | Additional CSS classes |
|
|
62
|
+
| `xKey` | `string` | | - | X-axis field key. Auto-detected from schema if not provided. |
|
|
63
|
+
| `yKey` | `string \| string[]` | | - | Y-axis field key(s). Auto-detected from schema if not provided. |
|
|
64
|
+
| `ariaLabel` | `string` | | - | Accessibility label for screen readers |
|
|
65
|
+
| `testId` | `string` | | - | Test ID for automated testing |
|
|
66
|
+
| `options` | `Record<string, unknown>` | | - | Additional ECharts options to merge |
|
|
67
|
+
| `valueFormatter` | `ChartValueFormatter` | | - | `(value: string \| number, field: string) => string`. Formats measure values in the chart's built-in value axes, tooltips, and value labels. `field` is the corresponding `yKey`, so one formatter can select a different format for each series. |
|
|
68
|
+
| `onDataClick` | `((datum: ChartClickDatum) => void)` | | - | Pointer-only: charts render to \<canvas>, so this does not fire for keyboard users. Provide a keyboard-accessible equivalent (e.g. a table row action) for the same action. |
|
|
69
|
+
| `selected` | `string \| string[]` | | - | Controlled selection by category name. Matching data element(s) render at full prominence while the rest are dimmed. Drive it from your own state to reflect a cross-filter or selection. Categorical charts (bar, pie/donut) show emphasis; other chart types ignore it. |
|
|
70
|
+
| `symbolSize` | `number` | | `8` | Symbol size |
|
|
71
71
|
|
|
72
72
|
### Usage[](#usage "Direct link to Usage")
|
|
73
73
|
|
package/docs/api/appkit.md
CHANGED
|
@@ -189,6 +189,7 @@ Documentation merge entry for Typedoc — combines the stable `@databricks/appki
|
|
|
189
189
|
| ------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
190
190
|
| [agents](./docs/api/appkit/Variable.agents.md) | Plugin factory for the agents plugin. Discovers agents from `server/agents/<id>/agent.{ts,md}` by default (markdown still in `config/agents/` is read as a deprecated fallback), resolves toolkits/tools from registered plugins, exposes the `appkit.agents.*` runtime API and mounts `POST /invocations` and `POST /responses` (aliased non-streaming invoke endpoints) plus `POST /chat` (streaming, HITL-capable). |
|
|
191
191
|
| [aiSearch](./docs/api/appkit/Variable.aiSearch.md) | - |
|
|
192
|
+
| [design](./docs/api/appkit/Variable.design.md) | - |
|
|
192
193
|
| [READ\_ACTIONS](./docs/api/appkit/Variable.READ_ACTIONS.md) | Actions that only read data. |
|
|
193
194
|
| [sql](./docs/api/appkit/Variable.sql.md) | SQL helper namespace |
|
|
194
195
|
| [SUPERVISOR\_EXTENSION\_KEY](./docs/api/appkit/Variable.SUPERVISOR_EXTENSION_KEY.md) | Namespace key under which the adapter reads its hosted-tool payload from [AgentInput.extensions](./docs/api/appkit/Interface.AgentInput.md#extensions). Exported so the agents plugin and standalone `runAgent` (the producers) can write under the same key the adapter reads. |
|
|
@@ -266,7 +266,7 @@ Editing `definitions.json` is picked up on the next request — no server restar
|
|
|
266
266
|
|
|
267
267
|
### useAnalyticsQuery[](#useanalyticsquery "Direct link to useAnalyticsQuery")
|
|
268
268
|
|
|
269
|
-
React hook that subscribes to an analytics query over SSE and returns its latest result.
|
|
269
|
+
React hook that subscribes to an analytics query over SSE and returns its latest result. Wrap `parameters` in `useMemo` (see [Memoization](#memoization)): the query re-runs whenever the parameters object is a new reference.
|
|
270
270
|
|
|
271
271
|
```ts
|
|
272
272
|
import { useAnalyticsQuery } from "@databricks/appkit-ui/react";
|
|
@@ -691,6 +691,14 @@ When multiple series share one value axis, its ticks use the first `yKey`; each
|
|
|
691
691
|
|
|
692
692
|
The `selected` prop adds declarative emphasis only to bar, pie, and donut charts. Line, area, scatter, heatmap, and radar charts ignore it because category-selection semantics are not defined for those chart types.
|
|
693
693
|
|
|
694
|
+
**Chart size.** By default a chart fills its container's height, so it fits the card or grid cell it's placed in, and is at least 160px tall when the container's height comes from its content. In a fixed-height card, give the chart's parent the remaining space (e.g. `className="flex-1 min-h-0"` on `CardContent` in a `flex flex-col` card). Pass `height` (pixels) for an exact size instead:
|
|
695
|
+
|
|
696
|
+
```tsx
|
|
697
|
+
<BarChart data={rows} xKey="city" yKey="trips" /> {/* fills its container */}
|
|
698
|
+
<BarChart data={rows} xKey="city" yKey="trips" height={208} /> {/* exactly 208px */}
|
|
699
|
+
|
|
700
|
+
```
|
|
701
|
+
|
|
694
702
|
**[Plotly](https://plotly.com/javascript/)** — pass the numeric specifier as `tickformat` and the literal currency symbol as `tickprefix`. Keeping them separate is necessary because d3's `$` marker is locale-driven and cannot represent arbitrary symbols:
|
|
695
703
|
|
|
696
704
|
```tsx
|
|
@@ -0,0 +1,233 @@
|
|
|
1
|
+
# Design plugin
|
|
2
|
+
|
|
3
|
+
Beta plugin
|
|
4
|
+
|
|
5
|
+
This plugin is currently **beta**. APIs may change between minor releases. Import from `@databricks/appkit/beta`. See [Plugin Stability Tiers](./docs/plugins/stability.md).
|
|
6
|
+
|
|
7
|
+
Dev-only design pages, for building a layout before it becomes part of the real app. The plugin only runs with `NODE_ENV=development`. In any other environment it does nothing, and `/design` returns 404.
|
|
8
|
+
|
|
9
|
+
## Basic usage[](#basic-usage "Direct link to Basic usage")
|
|
10
|
+
|
|
11
|
+
```ts
|
|
12
|
+
import { createApp, server } from "@databricks/appkit";
|
|
13
|
+
import { design } from "@databricks/appkit/beta";
|
|
14
|
+
|
|
15
|
+
await createApp({
|
|
16
|
+
plugins: [server(), design({ builderOrigin: "https://builder.example.com" })],
|
|
17
|
+
});
|
|
18
|
+
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
## Configuration[](#configuration "Direct link to Configuration")
|
|
22
|
+
|
|
23
|
+
| Option | Type | Description |
|
|
24
|
+
| --------------- | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
25
|
+
| `builderOrigin` | `string \| string[]` | Origin(s) of the app builder that embeds the app. The [design](#readiness) and [app](#app-readiness) ready messages are posted only to these origins, and `/design/__status` answers CORS for them. Must be a bare origin like `"https://builder.example.com"`; `"*"` is rejected. Defaults to the `APPKIT_DESIGN_BUILDER_ORIGIN` environment variable (one origin, or several separated by commas), so a builder's runtime can set it for a scaffolded `design()` with no options; an explicit `builderOrigin` wins. Optional: without either, no message is posted, and `/design/__status` still works. |
|
|
26
|
+
|
|
27
|
+
## Pages[](#pages "Direct link to Pages")
|
|
28
|
+
|
|
29
|
+
| URL | File |
|
|
30
|
+
| ---------------- | ------------------------------------ |
|
|
31
|
+
| `/design` | `client/src/design/index.tsx` |
|
|
32
|
+
| `/design/<name>` | `client/src/design/pages/<name>.tsx` |
|
|
33
|
+
|
|
34
|
+
Each file's default export is the page, rendered on its own at full size with the app's styles (`client/src/index.css`). Anything else under `/design` returns 404. The page names `index` and anything starting with `__` are reserved (`pages/index.tsx` would collide with `/design`, and `__status` is the plugin's own endpoint), so such files aren't served or listed. Pages hot-reload like the rest of the app. The requested page is loaded directly and other pages only when navigated to, so an unfinished draft only breaks its own URL.
|
|
35
|
+
|
|
36
|
+
When the app has `react-router` (the app template does), design pages share a router whose basename is `/design`. Links between them stay inside `/design`, and keep working when the pages are later promoted into the app's own routes:
|
|
37
|
+
|
|
38
|
+
```tsx
|
|
39
|
+
import { Link } from "react-router";
|
|
40
|
+
|
|
41
|
+
<Link to="/orders">Orders</Link>; // goes to /design/orders
|
|
42
|
+
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
Without `react-router`, each page renders on its own; link with `<a href="/design/orders">`.
|
|
46
|
+
|
|
47
|
+
```tsx
|
|
48
|
+
// client/src/design/index.tsx
|
|
49
|
+
import { Button, Card, CardContent, CardHeader, CardTitle } from "@databricks/appkit-ui/react";
|
|
50
|
+
|
|
51
|
+
export default function DesignPage() {
|
|
52
|
+
return (
|
|
53
|
+
<Card className="m-10 max-w-sm">
|
|
54
|
+
<CardHeader>
|
|
55
|
+
<CardTitle>Orders</CardTitle>
|
|
56
|
+
</CardHeader>
|
|
57
|
+
<CardContent>
|
|
58
|
+
<Button>New order</Button>
|
|
59
|
+
</CardContent>
|
|
60
|
+
</Card>
|
|
61
|
+
);
|
|
62
|
+
}
|
|
63
|
+
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
## Mapping elements to source[](#mapping-elements-to-source "Direct link to Mapping elements to source")
|
|
67
|
+
|
|
68
|
+
In development, the dev server adds `data-source="file:line:col"` to every native JSX element, on design pages and app pages alike. A builder's element inspector can use it to map what was clicked back to the code that renders it.
|
|
69
|
+
|
|
70
|
+
## Readiness[](#readiness "Direct link to Readiness")
|
|
71
|
+
|
|
72
|
+
A builder that embeds `/design` can wait until there is a real design to show, instead of revealing an empty page. `/design` is **ready** once `client/src/design/index.tsx` exists, isn't the template placeholder, and has rendered in a browser since it last changed. **`ready` needs a browser, but not a visible one**: a client has to load `/design`, and a hidden iframe is enough (nothing waits for a painted frame, and nothing looks at pixels). To wait without a browser at all, use `compiled` and `waitingFor` (below). A page that throws while rendering (in the page file or any component it uses) shows the error in place, reports it, and turns `ready` back to `false` until a render succeeds again.
|
|
73
|
+
|
|
74
|
+
### What "ready" waits for[](#what-ready-waits-for "Direct link to What \"ready\" waits for")
|
|
75
|
+
|
|
76
|
+
After a successful render the page waits until it shows its real content before reporting:
|
|
77
|
+
|
|
78
|
+
* web fonts have loaded (`document.fonts.ready`);
|
|
79
|
+
* no `Suspense` fallback is on screen (lazy components and data that suspend);
|
|
80
|
+
* no `fetch` started by the page is still in flight (its data, whatever kind);
|
|
81
|
+
* the page's DOM hasn't changed for 300 ms (lists filling in, content appearing);
|
|
82
|
+
* then two animation frames, or 100 ms without any: a hidden page (a builder's preview kept out of sight) gets no animation frames, and still reports.
|
|
83
|
+
|
|
84
|
+
It never reports while the page is the template placeholder or is showing a render error. The automatic waits give up after 10 seconds, so a stream that never ends can't hold the page back forever.
|
|
85
|
+
|
|
86
|
+
### Holding readiness back: `useDesignReady`[](#holding-readiness-back-usedesignready "Direct link to holding-readiness-back-usedesignready")
|
|
87
|
+
|
|
88
|
+
For content the page can't detect on its own (a chart that draws on a timer, an animation, data from a source that isn't `fetch`), hold readiness back explicitly. While any mounted component passes `false`, the page isn't ready, with no time limit:
|
|
89
|
+
|
|
90
|
+
```tsx
|
|
91
|
+
import { useDesignReady } from "@databricks/appkit-ui/react/beta";
|
|
92
|
+
|
|
93
|
+
function TripsPerDay() {
|
|
94
|
+
const { data, loading } = useAnalyticsQuery("trips_per_day", {});
|
|
95
|
+
useDesignReady(!loading && data != null);
|
|
96
|
+
return <LineChart data={data ?? []} />;
|
|
97
|
+
}
|
|
98
|
+
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
It also holds back [app readiness](#app-readiness) on the app's own pages in development. Elsewhere (production, tests) it does nothing, so it can stay in components that are later promoted into the app.
|
|
102
|
+
|
|
103
|
+
### Placeholder[](#placeholder "Direct link to Placeholder")
|
|
104
|
+
|
|
105
|
+
The app template's starter page is marked as a placeholder by this export. Delete it when you write the real page:
|
|
106
|
+
|
|
107
|
+
```tsx
|
|
108
|
+
export const designPlaceholder = true;
|
|
109
|
+
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
### `GET /design/__status`[](#get-design__status "Direct link to get-design__status")
|
|
113
|
+
|
|
114
|
+
```json
|
|
115
|
+
{
|
|
116
|
+
"ready": true,
|
|
117
|
+
"compiled": true,
|
|
118
|
+
"pages": [
|
|
119
|
+
{ "name": "index", "path": "/design", "compiled": true, "rendered": true, "errors": [], "state": "ready" },
|
|
120
|
+
{ "name": "orders", "path": "/design/orders", "compiled": true, "rendered": true, "errors": [{ "error": "Unhandled rejection: save failed" }], "state": "failed" }
|
|
121
|
+
],
|
|
122
|
+
"app": { "entry": "/src/main.tsx", "compiled": true, "path": "/", "rendered": true, "template": false, "errors": [] }
|
|
123
|
+
}
|
|
124
|
+
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
`pages` lists every design page, index first, so a builder can show a page switcher. For each, as a browser (hidden is fine) last reported it for the file's current version:
|
|
128
|
+
|
|
129
|
+
* `rendered`: React mounted the page without a render error and it settled (see above).
|
|
130
|
+
* `errors`: what the page hit: its render error (caught by the page's error boundary), uncaught errors (event handlers, timers), unhandled promise rejections and Vite compile errors, each `{ "error": message }`. `null` until a browser has loaded this version of the page (unknown, not "no errors"). Errors are cleared when the page loads again or takes a hot update (also one to a component it imports): what's still wrong is reported again, so a fixed error disappears without a reload.
|
|
131
|
+
|
|
132
|
+
`app` is the same for the app's own pages (not `/design`):
|
|
133
|
+
|
|
134
|
+
* `entry`: the app's entry module, from `client/index.html`.
|
|
135
|
+
* `compiled`: that module and everything it imports build, checked server-side like `compiled` below (`compileError` when they don't).
|
|
136
|
+
* `path`: the page last reported. Each path is tracked on its own, so two tabs on different pages don't reset each other; `rendered`, `template` and `errors` are this path's.
|
|
137
|
+
* `rendered`: something is mounted in `#root` and the page settled (a crash outside an error boundary leaves `#root` empty: `false`, and its error is listed).
|
|
138
|
+
* `template`: it's the template's default home page.
|
|
139
|
+
* `errors`: as for `pages` (`null` until a page has loaded since the dev server started).
|
|
140
|
+
|
|
141
|
+
The status also carries:
|
|
142
|
+
|
|
143
|
+
| Field | Meaning |
|
|
144
|
+
| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
145
|
+
| `compiled` | The index page and every module of the app it imports, transitively, build (compiled server-side as a browser would load them, so no browser is needed; dependencies in `node_modules` aren't recompiled). |
|
|
146
|
+
| `compileError` | Why it doesn't, prefixed with the failing module (`src/design/Card.tsx: ...`). |
|
|
147
|
+
| `waitingFor` | What `ready` is waiting on: `"index"` (no `index.tsx`), `"placeholder"` (still the template page), `"compile"` (build error), `"paint"` (no browser has rendered it yet, visible or not; the name is kept for compatibility), or `null` when ready. |
|
|
148
|
+
| `placeholder` | `index.tsx` is still the template placeholder. |
|
|
149
|
+
|
|
150
|
+
An agent writing the page waits for `compiled: true`; a builder that wants to reveal it loads `/design` (hidden is fine) and waits for `ready` or the `appkit:design-ready` message. To check that a page works, an agent reads `rendered` and `errors` here, for any kind of app (a game, a form, a chat, a dashboard); it never needs the preview to be visible, a resize, or a look at its pixels:
|
|
151
|
+
|
|
152
|
+
```ts
|
|
153
|
+
const s = await (await fetch(`${appUrl}/design/__status`)).json();
|
|
154
|
+
const appWorks = s.app.compiled && s.app.rendered && s.app.errors?.length === 0;
|
|
155
|
+
const pagesWork = s.pages.every((p) => p.rendered && p.errors?.length === 0);
|
|
156
|
+
|
|
157
|
+
```
|
|
158
|
+
|
|
159
|
+
### `appkit:design-ready` message[](#appkitdesign-ready-message "Direct link to appkitdesign-ready-message")
|
|
160
|
+
|
|
161
|
+
Once a design page is ready (see above) and again after each hot update that leaves it ready, the page posts this to `window.parent` (or `window.opener`), only to the configured `builderOrigin`s:
|
|
162
|
+
|
|
163
|
+
```ts
|
|
164
|
+
interface DesignReadyMessage {
|
|
165
|
+
type: "appkit:design-ready";
|
|
166
|
+
version: 1;
|
|
167
|
+
page: string; // name of the page that painted ("index" or <name>)
|
|
168
|
+
pages: { name: string; path: string }[];
|
|
169
|
+
}
|
|
170
|
+
|
|
171
|
+
```
|
|
172
|
+
|
|
173
|
+
```ts
|
|
174
|
+
// In the app builder:
|
|
175
|
+
window.addEventListener("message", (event) => {
|
|
176
|
+
if (event.origin !== appOrigin) return;
|
|
177
|
+
if (event.data?.type === "appkit:design-ready" && event.data.version === 1) {
|
|
178
|
+
showDesign(event.data.pages);
|
|
179
|
+
}
|
|
180
|
+
});
|
|
181
|
+
|
|
182
|
+
```
|
|
183
|
+
|
|
184
|
+
## App readiness[](#app-readiness "Direct link to App readiness")
|
|
185
|
+
|
|
186
|
+
The same idea for the real app, so a builder never reveals the template's default home page. In development the plugin adds a small script to the app's own pages (not `/design`). It always reports to `/design/__status` (`app`, above); with `builderOrigin` set it also posts to the builder. Once a page has settled (the same waits as [design readiness](#what-ready-waits-for), including `useDesignReady`), and again after client-side navigation and hot updates, it posts:
|
|
187
|
+
|
|
188
|
+
```ts
|
|
189
|
+
interface AppReadyMessage {
|
|
190
|
+
type: "appkit:app-ready";
|
|
191
|
+
version: 1;
|
|
192
|
+
path: string; // location.pathname of the page that is ready
|
|
193
|
+
}
|
|
194
|
+
|
|
195
|
+
```
|
|
196
|
+
|
|
197
|
+
This is the signal for an app that skips `/design` (e.g. one that needs no data): the builder can load the app's `/` in a hidden frame and reveal it when `appkit:app-ready` arrives. It isn't posted while nothing is mounted in `#root` (a crash), and it's sent from a hidden frame too (the final wait for a paint gives up after 100 ms, as on `/design`).
|
|
198
|
+
|
|
199
|
+
It isn't posted while an element with the `data-appkit-template-home` attribute is on screen. The app template's default home page (`HomePage` in `client/src/App.tsx`) carries it; a builder can also look for it directly. Remove the attribute, or the page, when the app gets its real home page, and the next settle (a hot update counts) posts `appkit:app-ready`.
|
|
200
|
+
|
|
201
|
+
```ts
|
|
202
|
+
// In the app builder:
|
|
203
|
+
window.addEventListener("message", (event) => {
|
|
204
|
+
if (event.origin !== appOrigin) return;
|
|
205
|
+
if (event.data?.type === "appkit:app-ready" && event.data.version === 1) {
|
|
206
|
+
showApp(event.data.path);
|
|
207
|
+
}
|
|
208
|
+
});
|
|
209
|
+
|
|
210
|
+
```
|
|
211
|
+
|
|
212
|
+
## TSX drafts[](#tsx-drafts "Direct link to TSX drafts")
|
|
213
|
+
|
|
214
|
+
TSX drafts are design pages written with real appkit-ui components. The plugin only renders them; whatever writes them (an app builder) owns the prompt, the model calls, the mock data and the type-check. A builder writes:
|
|
215
|
+
|
|
216
|
+
* `client/src/design/mock.ts`: the sample data the drafts share (any module works; the pages import it as `../mock`).
|
|
217
|
+
* `client/src/design/pages/<name>.tsx` per draft, default-exporting the page, served at `/design/<name>`. Write a page there only once it type-checks (e.g. write elsewhere, then move it in), so a half-written file never shows. Use theme tokens (`bg-background`, `text-foreground`, ...), so drafts work in dark mode.
|
|
218
|
+
* After moving a page in, touch `client/src/index.css` (update its modification time). Tailwind's Vite plugin only rescans sources for classes when the stylesheet changes, so until then a new page renders without its Tailwind styles.
|
|
219
|
+
|
|
220
|
+
Each page renders in its own error boundary and posts `appkit:design-ready` once rendered. Its state is in `GET /design/__status` under `pages` (see above): `compiled` / `compileError` (built server-side, no browser needed), `rendered`, `errors`, and `state`: `compile-error`, `rendering` (builds, not rendered yet), `ready` or `failed` (a browser reported errors).
|
|
221
|
+
|
|
222
|
+
### Streaming a draft while it's written[](#streaming-a-draft-while-its-written "Direct link to Streaming a draft while it's written")
|
|
223
|
+
|
|
224
|
+
A builder can show a draft while it's still being written, instead of only once it's finished:
|
|
225
|
+
|
|
226
|
+
* Append the page's source, as it arrives, to `client/src/design/.staging/<name>.tsx` (and the shared mock's to `.staging/mock.ts`).
|
|
227
|
+
* Show `/design/__stream/<name>`. The dev server keeps the latest renderable version of the staging file under the page's real module (`pages/<name>.tsx`): it closes whatever is still open at the cut (JSX tags, brackets, template literals) and stubs what the page uses that hasn't arrived yet. Components not written yet show a `DraftPlaceholder` skeleton of the right shape. Each version reaches the page as a hot update, so it fills in in place, with no reload and with its state kept.
|
|
228
|
+
* Until `mock.ts` exists, the page's `../mock` import is what `.staging/mock.ts` has so far, plus stubs for whatever the page imports from it that isn't there yet.
|
|
229
|
+
* When the page type-checks, write it to `pages/<name>.tsx` (and `mock.ts`): the same module then loads from disk. Deleting the staging file starts that draft over.
|
|
230
|
+
|
|
231
|
+
Every design page, streamed or not, renders through `DesignPage` (from `@databricks/appkit-ui/react/beta`; the plugin adds it, pages don't). It applies the app's theme before the first paint (`?theme=dark` or `?theme=light` on the URL, else the system setting), so a dark page never flashes light. If a render fails mid-stream, it keeps the last good frame on screen instead of a broken page, and holds readiness back until a render succeeds.
|
|
232
|
+
|
|
233
|
+
Lock-in is a file operation for the builder: keep the chosen page as `client/src/design/index.tsx` (`/design`, repointing `../mock` to `./mock`), or as the app's home page for apps with no data, and delete the other drafts.
|
package/llms.txt
CHANGED
|
@@ -7,6 +7,7 @@ npx @databricks/appkit docs <query>
|
|
|
7
7
|
```
|
|
8
8
|
|
|
9
9
|
- View documentation index: `npx @databricks/appkit docs`
|
|
10
|
+
- Look up components, hooks and functions by name: `npx @databricks/appkit docs BarChart DataTable Select useAnalyticsQuery sql`
|
|
10
11
|
- View a section: `npx @databricks/appkit docs "appkit-ui API reference"`
|
|
11
12
|
- Full index (all API entries): `npx @databricks/appkit docs --full`
|
|
12
13
|
- View specific doc: `npx @databricks/appkit docs ./docs/plugins/analytics.md`
|
|
@@ -49,6 +50,7 @@ npx @databricks/appkit docs <query>
|
|
|
49
50
|
- [Caching](./docs/plugins/caching.md): AppKit provides both global and plugin-level caching capabilities.
|
|
50
51
|
- [Creating custom plugins](./docs/plugins/custom-plugins.md): If you need custom API routes or background logic, implement an AppKit plugin. The fastest way is to use the CLI:
|
|
51
52
|
- [Database plugin](./docs/plugins/database.md): This plugin is currently beta. APIs may change between minor releases. Import from @databricks/appkit/beta. See Plugin Stability Tiers.
|
|
53
|
+
- [Design plugin](./docs/plugins/design.md): This plugin is currently beta. APIs may change between minor releases. Import from @databricks/appkit/beta. See Plugin Stability Tiers.
|
|
52
54
|
- [Execution context](./docs/plugins/execution-context.md): AppKit uses the service principal by default. Open a caller scope when an
|
|
53
55
|
- [Files plugin](./docs/plugins/files.md): File operations against Databricks Unity Catalog Volumes. Supports listing, reading, downloading, uploading, deleting, and previewing files with built-in caching, retry, and timeout handling via the execution interceptor pipeline.
|
|
54
56
|
- [Genie plugin](./docs/plugins/genie.md): Integrates Databricks AI/BI Genie spaces into your AppKit application, enabling natural language data queries via a conversational interface.
|
|
@@ -317,6 +319,7 @@ npx @databricks/appkit docs <query>
|
|
|
317
319
|
- [Type Alias: WorkspaceClientLike](./docs/api/appkit/TypeAlias.WorkspaceClientLike.md): Structural shape of a Databricks SDK client used by fromSupervisorApi.
|
|
318
320
|
- [Variable: agents](./docs/api/appkit/Variable.agents.md): Plugin factory for the agents plugin. Discovers agents from
|
|
319
321
|
- [Variable: aiSearch](./docs/api/appkit/Variable.aiSearch.md)
|
|
322
|
+
- [Variable: design](./docs/api/appkit/Variable.design.md)
|
|
320
323
|
- [Variable: READ_ACTIONS](./docs/api/appkit/Variable.READ_ACTIONS.md): Actions that only read data.
|
|
321
324
|
- [Variable: sql](./docs/api/appkit/Variable.sql.md): SQL helper namespace
|
|
322
325
|
- [Variable: SUPERVISOR_EXTENSION_KEY](./docs/api/appkit/Variable.SUPERVISOR_EXTENSION_KEY.md): Namespace key under which the adapter reads its hosted-tool payload
|