@databricks/appkit-ui 0.1.2 → 0.1.4

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.
Files changed (63) hide show
  1. package/AGENTS.md +1154 -0
  2. package/CLAUDE.md +1153 -2
  3. package/bin/setup-claude.js +1 -1
  4. package/dist/react/ui/accordion.d.ts +5 -5
  5. package/dist/react/ui/alert-dialog.d.ts +12 -12
  6. package/dist/react/ui/alert.d.ts +4 -4
  7. package/dist/react/ui/alert.d.ts.map +1 -1
  8. package/dist/react/ui/aspect-ratio.d.ts +2 -2
  9. package/dist/react/ui/avatar.d.ts +4 -4
  10. package/dist/react/ui/badge.d.ts +2 -2
  11. package/dist/react/ui/breadcrumb.d.ts +8 -8
  12. package/dist/react/ui/button-group.d.ts +4 -4
  13. package/dist/react/ui/button.d.ts +2 -2
  14. package/dist/react/ui/calendar.d.ts +3 -3
  15. package/dist/react/ui/card.d.ts +8 -8
  16. package/dist/react/ui/carousel.d.ts +6 -6
  17. package/dist/react/ui/chart.d.ts +5 -5
  18. package/dist/react/ui/chart.d.ts.map +1 -1
  19. package/dist/react/ui/checkbox.d.ts +2 -2
  20. package/dist/react/ui/collapsible.d.ts +4 -4
  21. package/dist/react/ui/command.d.ts +10 -10
  22. package/dist/react/ui/command.d.ts.map +1 -1
  23. package/dist/react/ui/context-menu.d.ts +16 -16
  24. package/dist/react/ui/dialog.d.ts +11 -11
  25. package/dist/react/ui/drawer.d.ts +11 -11
  26. package/dist/react/ui/dropdown-menu.d.ts +16 -16
  27. package/dist/react/ui/empty.d.ts +7 -7
  28. package/dist/react/ui/field.d.ts +11 -11
  29. package/dist/react/ui/form.d.ts +7 -7
  30. package/dist/react/ui/hover-card.d.ts +4 -4
  31. package/dist/react/ui/input-group.d.ts +7 -7
  32. package/dist/react/ui/input-otp.d.ts +5 -5
  33. package/dist/react/ui/input.d.ts +2 -2
  34. package/dist/react/ui/input.d.ts.map +1 -1
  35. package/dist/react/ui/item.d.ts +11 -11
  36. package/dist/react/ui/kbd.d.ts +3 -3
  37. package/dist/react/ui/label.d.ts +2 -2
  38. package/dist/react/ui/menubar.d.ts +17 -17
  39. package/dist/react/ui/navigation-menu.d.ts +9 -9
  40. package/dist/react/ui/pagination.d.ts +8 -8
  41. package/dist/react/ui/popover.d.ts +5 -5
  42. package/dist/react/ui/progress.d.ts +2 -2
  43. package/dist/react/ui/radio-group.d.ts +3 -3
  44. package/dist/react/ui/resizable.d.ts +4 -4
  45. package/dist/react/ui/scroll-area.d.ts +3 -3
  46. package/dist/react/ui/select.d.ts +11 -11
  47. package/dist/react/ui/separator.d.ts +2 -2
  48. package/dist/react/ui/sheet.d.ts +9 -9
  49. package/dist/react/ui/sidebar.d.ts +24 -24
  50. package/dist/react/ui/skeleton.d.ts +2 -2
  51. package/dist/react/ui/slider.d.ts +2 -2
  52. package/dist/react/ui/sonner.d.ts +2 -2
  53. package/dist/react/ui/spinner.d.ts +2 -2
  54. package/dist/react/ui/switch.d.ts +2 -2
  55. package/dist/react/ui/table.d.ts +9 -9
  56. package/dist/react/ui/tabs.d.ts +5 -5
  57. package/dist/react/ui/textarea.d.ts +2 -2
  58. package/dist/react/ui/toggle-group.d.ts +3 -3
  59. package/dist/react/ui/toggle.d.ts +2 -2
  60. package/dist/react/ui/tooltip.d.ts +5 -5
  61. package/dist/react/ui/tooltip.d.ts.map +1 -1
  62. package/llms.txt +123 -46
  63. package/package.json +3 -2
package/AGENTS.md ADDED
@@ -0,0 +1,1154 @@
1
+ # llms.txt — LLM Guide for Building Great Databricks Apps with AppKit
2
+ Project: Databricks AppKit
3
+
4
+ This document is written *for LLMs* generating code in a brand-new project folder that installs AppKit from npm. It is intentionally prescriptive.
5
+
6
+ ## High-level mission
7
+
8
+ Build **full-stack TypeScript apps** on Databricks using:
9
+
10
+ - **Backend**: `@databricks/appkit`
11
+ - **Frontend**: `@databricks/appkit-ui`
12
+ - **Analytics**: SQL files in `config/queries/*.sql` executed via the AppKit analytics plugin
13
+
14
+ This file is designed to work even when you *do not* have access to the AppKit source repo. Prefer only public package APIs and portable project structures.
15
+
16
+ ## Hard rules (LLM guardrails)
17
+
18
+ - **Do not invent APIs**. If unsure, stick to the patterns shown in this file and only documented exports from `@databricks/appkit` and `@databricks/appkit-ui`.
19
+ - **`createApp()` is async**. Prefer **top-level `await createApp(...)`**. If you can’t, use `void createApp(...)` and do not ignore promise rejection.
20
+ - **Always memoize query parameters** passed to `useAnalyticsQuery` / charts to avoid refetch loops.
21
+ - **Always handle loading/error/empty states** in UI (use `Skeleton`, error text, empty state).
22
+ - **Always use `sql.*` helpers** for query parameters (do not pass raw strings/numbers unless the query expects none).
23
+ - **Never construct SQL strings dynamically**. Use parameterized queries with `:paramName`.
24
+ - **Never use `require()`**. Use ESM `import/export`.
25
+
26
+ ## TypeScript import rules (when using `verbatimModuleSyntax`)
27
+
28
+ If your `tsconfig.json` uses `"verbatimModuleSyntax": true`, **always use `import type` for type-only imports** (otherwise builds can fail in strict setups):
29
+
30
+ ```ts
31
+ import type { ReactNode } from "react";
32
+ import { useMemo } from "react";
33
+ ```
34
+
35
+ ## Canonical project layout
36
+
37
+ Recommended structure (client/server split):
38
+
39
+ ```
40
+ my-app/
41
+ ├── server/
42
+ │ ├── index.ts # backend entry point (AppKit)
43
+ │ └── .env # optional local dev env vars (do not commit)
44
+ ├── client/
45
+ │ ├── index.html
46
+ │ ├── vite.config.ts
47
+ │ └── src/
48
+ │ ├── main.tsx
49
+ │ └── App.tsx
50
+ ├── config/
51
+ │ └── queries/
52
+ │ └── my_query.sql
53
+ ├── app.yaml
54
+ ├── package.json
55
+ └── tsconfig.json
56
+ ```
57
+
58
+ Why this layout:
59
+
60
+ - The AppKit `server()` plugin automatically serves:
61
+ - **Dev**: Vite dev server (HMR) from `client/`
62
+ - **Prod**: static files from `client/dist` (built by Vite)
63
+
64
+ ## Project scaffolding (start here)
65
+
66
+ ### `package.json`
67
+
68
+ ```json
69
+ {
70
+ "name": "my-app",
71
+ "private": true,
72
+ "version": "0.0.0",
73
+ "type": "module",
74
+ "scripts": {
75
+ "dev": "NODE_ENV=development tsx watch server/index.ts",
76
+ "build": "npm run build:server && npm run build:client",
77
+ "build:server": "tsdown --out-dir build server/index.ts",
78
+ "build:client": "tsc -b && vite build --config client/vite.config.ts",
79
+ "start": "node build/index.mjs"
80
+ },
81
+ "dependencies": {
82
+ "@databricks/appkit": "^0.1.2"
83
+ "@databricks/appkit-ui": "^0.1.2",
84
+ "react": "^19.2.3",
85
+ "react-dom": "^19.2.3"
86
+ },
87
+ "devDependencies": {
88
+ "@types/node": "^20.0.0",
89
+ "@types/react": "^19.0.0",
90
+ "@types/react-dom": "^19.0.0",
91
+ "@vitejs/plugin-react": "^5.1.1",
92
+ "tsdown": "^0.15.7",
93
+ "tsx": "^4.19.0",
94
+ "typescript": "~5.6.0",
95
+ "vite": "^7.2.4"
96
+ }
97
+ }
98
+ ```
99
+
100
+ ### `client/index.html`
101
+
102
+ ```html
103
+ <!doctype html>
104
+ <html lang="en">
105
+ <head>
106
+ <meta charset="UTF-8" />
107
+ <meta name="viewport" content="width=device-width, initial-scale=1.0" />
108
+ <title>My App</title>
109
+ </head>
110
+ <body>
111
+ <div id="root"></div>
112
+ <script type="module" src="/src/main.tsx"></script>
113
+ </body>
114
+ </html>
115
+ ```
116
+
117
+ ### `client/src/main.tsx`
118
+
119
+ ```tsx
120
+ import { StrictMode } from "react";
121
+ import { createRoot } from "react-dom/client";
122
+ import App from "./App";
123
+
124
+ createRoot(document.getElementById("root")!).render(
125
+ <StrictMode>
126
+ <App />
127
+ </StrictMode>,
128
+ );
129
+ ```
130
+
131
+ ### `client/src/App.tsx` (minimal)
132
+
133
+ ```tsx
134
+ export default function App() {
135
+ return (
136
+ <div className="p-8">
137
+ <h1 className="text-2xl font-bold">My App</h1>
138
+ </div>
139
+ );
140
+ }
141
+ ```
142
+
143
+ ### `client/vite.config.ts`
144
+
145
+ ```ts
146
+ import { defineConfig } from "vite";
147
+ import react from "@vitejs/plugin-react";
148
+
149
+ export default defineConfig({
150
+ plugins: [react()],
151
+ });
152
+ ```
153
+
154
+ ### `tsconfig.json`
155
+
156
+ ```json
157
+ {
158
+ "compilerOptions": {
159
+ "target": "ES2022",
160
+ "lib": ["ES2022", "DOM", "DOM.Iterable"],
161
+ "module": "ESNext",
162
+ "moduleResolution": "bundler",
163
+ "jsx": "react-jsx",
164
+ "strict": true,
165
+ "skipLibCheck": true,
166
+ "noEmit": true,
167
+ "allowImportingTsExtensions": true,
168
+ "verbatimModuleSyntax": true
169
+ },
170
+ "include": ["server", "client/src"]
171
+ }
172
+ ```
173
+
174
+ ### `server/index.ts`
175
+
176
+ ```ts
177
+ import { createApp, server } from "@databricks/appkit";
178
+
179
+ await createApp({
180
+ plugins: [server()],
181
+ });
182
+ ```
183
+
184
+ ### Running the app
185
+
186
+ ```bash
187
+ # Install dependencies
188
+ npm install
189
+
190
+ # Development (starts backend + Vite dev server)
191
+ npm run dev
192
+
193
+ # Production build
194
+ npm run build
195
+ npm start
196
+ ```
197
+
198
+ ## Integrating into an existing app
199
+
200
+ If you already have a React/Vite app and want to add AppKit:
201
+
202
+ ### 1. Install dependencies
203
+
204
+ ```bash
205
+ npm install @databricks/appkit @databricks/appkit-ui react react-dom
206
+ npm install -D tsx tsdown vite @vitejs/plugin-react typescript
207
+
208
+ # If you don't already have a client/ folder, create one and move your Vite app into it:
209
+ # - move index.html -> client/index.html
210
+ # - move vite.config.ts -> client/vite.config.ts
211
+ # - move src/ -> client/src/
212
+ #
213
+ ```
214
+
215
+ ### 2. Create `server/index.ts` (new file)
216
+
217
+ ```ts
218
+ import { createApp, server } from "@databricks/appkit";
219
+
220
+ await createApp({
221
+ plugins: [server()],
222
+ });
223
+ ```
224
+
225
+ ### 3. Update `package.json` scripts
226
+
227
+ ```json
228
+ {
229
+ "scripts": {
230
+ "dev": "NODE_ENV=development tsx watch server/index.ts",
231
+ "build": "npm run build:server && npm run build:client",
232
+ "build:server": "tsdown --out-dir build server/index.ts",
233
+ "build:client": "tsc -b && vite build --config client/vite.config.ts",
234
+ "start": "node build/index.mjs"
235
+ }
236
+ }
237
+ ```
238
+
239
+ ### 4. That's it
240
+
241
+ - AppKit's server plugin will automatically serve your Vite app in dev mode and `client/dist` in production.
242
+ - If your Vite app must stay at the repo root (no `client/` folder), AppKit can still work, but the recommended layout is `client/` + `server/`.
243
+
244
+ ### Adding analytics to an existing app
245
+
246
+ ```ts
247
+ // server/index.ts
248
+ import { createApp, server, analytics } from "@databricks/appkit";
249
+
250
+ await createApp({
251
+ plugins: [server(), analytics()],
252
+ });
253
+ ```
254
+
255
+ Then create `config/queries/` and add your `.sql` files.
256
+
257
+ ## Environment variables
258
+
259
+ ### Required for Databricks Apps deployment
260
+
261
+ These are typically **provided by Databricks Apps runtime** (exact set can vary by platform/version):
262
+
263
+ | Variable | Description |
264
+ |----------|-------------|
265
+ | `DATABRICKS_HOST` | Workspace URL (e.g. `https://xxx.cloud.databricks.com`) |
266
+ | `DATABRICKS_APP_PORT` | Port to bind (default: `8000`) |
267
+ | `DATABRICKS_APP_NAME` | App name in Databricks |
268
+
269
+ ### Required for SQL queries (analytics plugin)
270
+
271
+ | Variable | Description | How to set |
272
+ |----------|-------------|------------|
273
+ | `DATABRICKS_WAREHOUSE_ID` | SQL warehouse ID | In `app.yaml`: `valueFrom: sql-warehouse` |
274
+
275
+ ### Optional
276
+
277
+ | Variable | Description | Default |
278
+ |----------|-------------|---------|
279
+ | `DATABRICKS_WORKSPACE_ID` | Workspace ID | Auto-fetched from API |
280
+ | `NODE_ENV` | `"development"` or `"production"` | — |
281
+ | `FLASK_RUN_HOST` | Host to bind | `0.0.0.0` |
282
+
283
+ ### Local development
284
+
285
+ For local development, you need to authenticate with Databricks. Options:
286
+
287
+ **Option 1: Databricks CLI Auth (recommended)**
288
+
289
+ ```bash
290
+ # Configure once
291
+ databricks auth login --host [host] --profile [profile-name]
292
+
293
+ # If you used `DEFAULT` as the profile name then you can just run
294
+
295
+ `npm run dev`
296
+
297
+ # To run with a specific profile
298
+ DATABRICKS_CONFIG_PROFILE=my-profile npm run dev
299
+ # If your Databricks SDK expects a different variable name, try:
300
+ # DATABRICKS_PROFILE=my-profile npm run dev
301
+ ```
302
+
303
+ **Option 2: Environment variables**
304
+
305
+ ```bash
306
+ export DATABRICKS_HOST="https://xxx.cloud.databricks.com"
307
+ export DATABRICKS_TOKEN="dapi..."
308
+ export DATABRICKS_WAREHOUSE_ID="abc123..."
309
+ npm run dev
310
+ ```
311
+
312
+ **Option 3: `.env` file (auto-loaded by AppKit)**
313
+
314
+ ```bash
315
+ # .env (add to .gitignore!)
316
+ DATABRICKS_HOST=https://xxx.cloud.databricks.com
317
+ DATABRICKS_TOKEN=dapi...
318
+ DATABRICKS_WAREHOUSE_ID=abc123...
319
+ ```
320
+
321
+ ### Telemetry (optional)
322
+
323
+ | Variable | Description |
324
+ |----------|-------------|
325
+ | `OTEL_EXPORTER_OTLP_ENDPOINT` | OpenTelemetry collector endpoint |
326
+ | `OTEL_SERVICE_NAME` | Service name for traces |
327
+
328
+ ## Backend: `@databricks/appkit`
329
+
330
+ ### Minimal server (golden template)
331
+
332
+ The smallest valid AppKit server:
333
+
334
+ ```ts
335
+ // server/index.ts
336
+ import { createApp, server } from "@databricks/appkit";
337
+
338
+ await createApp({
339
+ plugins: [server()],
340
+ });
341
+ ```
342
+
343
+ ### Server plugin (`server()`)
344
+
345
+ What it does:
346
+
347
+ - Starts an Express server (default `host=0.0.0.0`, `port=8000`)
348
+ - Mounts plugin routes under `/api/<pluginName>/...`
349
+ - Adds `/health` (returns `{ status: "ok" }`)
350
+ - Serves frontend:
351
+ - **Development** (`NODE_ENV=development`): runs a Vite dev server in middleware mode
352
+ - **Production**: auto-detects static frontend directory (checks `dist`, `client/dist`, `build`, `public`, `out`)
353
+
354
+ Config (real options):
355
+
356
+ ```ts
357
+ import { createApp, server } from "@databricks/appkit";
358
+
359
+ await createApp({
360
+ plugins: [
361
+ server({
362
+ port: 8000, // default: Number(process.env.DATABRICKS_APP_PORT) || 8000
363
+ host: "0.0.0.0", // default: process.env.FLASK_RUN_HOST || "0.0.0.0"
364
+ autoStart: true, // default: true
365
+ staticPath: "dist", // optional: force a specific static directory
366
+ }),
367
+ ],
368
+ });
369
+ ```
370
+
371
+ Manual server start (when you need to `.extend()` Express):
372
+
373
+ ```ts
374
+ import { createApp, server } from "@databricks/appkit";
375
+
376
+ const appkit = await createApp({
377
+ plugins: [server({ autoStart: false })],
378
+ });
379
+
380
+ appkit.server.extend((app) => {
381
+ app.get("/custom", (_req, res) => res.json({ ok: true }));
382
+ });
383
+
384
+ await appkit.server.start();
385
+ ```
386
+
387
+ ### Analytics plugin (`analytics()`)
388
+
389
+ Add SQL query execution backed by Databricks SQL Warehouses.
390
+
391
+ ```ts
392
+ import { analytics, createApp, server } from "@databricks/appkit";
393
+
394
+ await createApp({
395
+ plugins: [server(), analytics({})],
396
+ });
397
+ ```
398
+
399
+ Where queries live:
400
+
401
+ - Put `.sql` files in `config/queries/`.
402
+ - Query key is the filename without `.sql` (e.g. `spend_summary.sql` → `"spend_summary"`).
403
+
404
+ SQL parameters:
405
+
406
+ - Use `:paramName` placeholders.
407
+ - Optionally annotate parameter types using SQL comments:
408
+
409
+ ```sql
410
+ -- @param startDate DATE
411
+ -- @param endDate DATE
412
+ -- @param limit NUMERIC
413
+ SELECT ...
414
+ WHERE usage_date BETWEEN :startDate AND :endDate
415
+ LIMIT :limit
416
+ ```
417
+
418
+ Supported `-- @param` types (case-insensitive):
419
+
420
+ - `STRING`, `NUMERIC`, `BOOLEAN`, `DATE`, `TIMESTAMP`, `BINARY`
421
+
422
+ Server-injected params (important):
423
+
424
+ - `:workspaceId` is **injected by the server** and **must not** be annotated.
425
+ - Example:
426
+
427
+ ```sql
428
+ WHERE workspace_id = :workspaceId
429
+ ```
430
+
431
+ HTTP endpoints exposed (mounted under `/api/analytics`):
432
+
433
+ - `POST /api/analytics/query/:query_key`
434
+ - `POST /api/analytics/users/me/query/:query_key`
435
+ - `GET /api/analytics/arrow-result/:jobId`
436
+ - `GET /api/analytics/users/me/arrow-result/:jobId`
437
+
438
+ Formats:
439
+
440
+ - `format: "JSON"` (default) returns JSON rows
441
+ - `format: "ARROW"` returns an Arrow “statement_id” payload over SSE, then the client fetches binary Arrow from `/api/analytics/arrow-result/:jobId`
442
+
443
+ ### Request context (`getRequestContext()`)
444
+
445
+ If a plugin sets `requiresDatabricksClient = true`, AppKit adds middleware that provides request context.
446
+
447
+ Headers used:
448
+
449
+ - `x-forwarded-user`: required in production; identifies the user
450
+ - `x-forwarded-access-token`: optional; enables **user token passthrough** if `DATABRICKS_HOST` is set
451
+
452
+ Context fields (real behavior):
453
+
454
+ - `userId`: derived from `x-forwarded-user` (in development it falls back to `serviceUserId`)
455
+ - `serviceUserId`: service principal/user ID
456
+ - `warehouseId`: `Promise<string>` (from `DATABRICKS_WAREHOUSE_ID`, or auto-selected in development)
457
+ - `workspaceId`: `Promise<string>` (from `DATABRICKS_WORKSPACE_ID` or fetched)
458
+ - `userDatabricksClient`: present only when passthrough is available (or in dev it equals service client)
459
+ - `serviceDatabricksClient`: always present
460
+
461
+ ### Custom plugins (backend)
462
+
463
+ If you need custom API routes or background logic, implement an AppKit plugin.
464
+
465
+ ```ts
466
+ import { Plugin, toPlugin } from "@databricks/appkit";
467
+ import type express from "express";
468
+
469
+ class MyPlugin extends Plugin {
470
+ name = "my-plugin";
471
+ envVars = []; // list required env vars here
472
+ requiresDatabricksClient = false; // set true if you need getRequestContext()
473
+
474
+ injectRoutes(router: express.Router) {
475
+ this.route(router, {
476
+ name: "hello",
477
+ method: "get",
478
+ path: "/hello",
479
+ handler: async (_req, res) => {
480
+ res.json({ ok: true });
481
+ },
482
+ });
483
+ }
484
+ }
485
+
486
+ export const myPlugin = toPlugin<typeof MyPlugin, Record<string, never>, "my-plugin">(
487
+ MyPlugin,
488
+ "my-plugin",
489
+ );
490
+ ```
491
+
492
+ ### Caching (global + plugin-level)
493
+
494
+ Global:
495
+
496
+ ```ts
497
+ await createApp({
498
+ plugins: [server(), analytics({})],
499
+ cache: {
500
+ enabled: true,
501
+ ttl: 3600, // seconds
502
+ strictPersistence: false,
503
+ },
504
+ });
505
+ ```
506
+
507
+ - Storage auto-selects **Lakebase persistent cache when healthy**, otherwise falls back to in-memory.
508
+
509
+ Plugin-level:
510
+
511
+ ```ts
512
+ // inside a Plugin subclass:
513
+ const value = await this.cache.getOrExecute(
514
+ ["my-plugin", "data", userId],
515
+ async () => expensiveWork(),
516
+ userKey,
517
+ { ttl: 300 },
518
+ );
519
+ ```
520
+
521
+ ## Frontend: `@databricks/appkit-ui`
522
+
523
+ ### Imports
524
+
525
+ - React-facing APIs: `@databricks/appkit-ui/react`
526
+ - Non-React utilities (sql markers, arrow, SSE): `@databricks/appkit-ui/js`
527
+
528
+ ```tsx
529
+ import { useAnalyticsQuery, Card, Skeleton } from "@databricks/appkit-ui/react";
530
+ import { sql } from "@databricks/appkit-ui/js";
531
+ ```
532
+
533
+ ### `useAnalyticsQuery(queryKey, parameters, options?)`
534
+
535
+ Facts:
536
+
537
+ - Uses **SSE** under the hood (not `fetch()` polling).
538
+ - By default it hits `POST /api/analytics/query/:queryKey`.
539
+ - Returns `{ data, loading, error }` where `data` is `null` until loaded.
540
+ - `format` is `"JSON"` or `"ARROW"` (uppercase).
541
+
542
+ When to use it:
543
+
544
+ - Use `useAnalyticsQuery` **only** when you need a custom UI (cards/KPIs/forms/conditional rendering).
545
+ - If you just need a standard chart or table, prefer the built-in components (`BarChart`, `LineChart`, `DataTable`, etc.) so you don’t re-implement loading/error/empty states.
546
+
547
+ Limitations (common LLM pitfall):
548
+
549
+ - There is **no `enabled` option**. Use conditional rendering to mount/unmount the component.
550
+ - There is **no `refetch()`**. Change `parameters` (memoized) or re-mount to re-run the query.
551
+
552
+ Recommended usage pattern (memoized params + explicit states):
553
+
554
+ ```tsx
555
+ import { useMemo } from "react";
556
+ import { useAnalyticsQuery, Skeleton } from "@databricks/appkit-ui/react";
557
+ import { sql } from "@databricks/appkit-ui/js";
558
+
559
+ export function Users() {
560
+ const params = useMemo(
561
+ () => ({
562
+ status: sql.string("active"),
563
+ limit: sql.number(50),
564
+ }),
565
+ [],
566
+ );
567
+
568
+ const { data, loading, error } = useAnalyticsQuery("users_list", params);
569
+
570
+ if (loading) return <Skeleton className="h-24 w-full" />;
571
+ if (error) return <div className="text-destructive">Error: {error}</div>;
572
+ if (!data || data.length === 0) return <div>No results</div>;
573
+
574
+ return <pre>{JSON.stringify(data[0], null, 2)}</pre>;
575
+ }
576
+ ```
577
+
578
+ Options:
579
+
580
+ - `format?: "JSON" | "ARROW"` (default `"JSON"`)
581
+ - `autoStart?: boolean` (default `true`)
582
+ - `maxParametersSize?: number` (default `100 * 1024` bytes)
583
+
584
+ ### `useChartData({ queryKey, parameters, format, transformer })`
585
+
586
+ - `format` here is **lowercase**: `"json" | "arrow" | "auto"` (default `"auto"`)
587
+ - Auto-selection heuristics:
588
+ - If `parameters._preferArrow === true` → Arrow
589
+ - If `parameters._preferJson === true` → JSON
590
+ - If `parameters.limit` is a number > 500 → Arrow
591
+ - If `parameters.startDate` and `parameters.endDate` exist → Arrow
592
+
593
+ ### Charts (unified query/data API)
594
+
595
+ All charts support:
596
+
597
+ - **Query mode**: `queryKey` + `parameters`
598
+ - **Data mode**: `data` (inline JSON, no server)
599
+
600
+ Available chart components:
601
+
602
+ - `BarChart`, `LineChart`, `AreaChart`, `PieChart`, `DonutChart`, `HeatmapChart`, `ScatterChart`, `RadarChart`
603
+
604
+ Avoid double-fetching:
605
+
606
+ ```tsx
607
+ // ❌ Wrong: fetches the same query twice
608
+ // const { data } = useAnalyticsQuery("spend_data", params);
609
+ // return <LineChart queryKey="spend_data" parameters={params} />;
610
+
611
+ // ✅ Correct: let the chart fetch
612
+ return <LineChart queryKey="spend_data" parameters={params} />;
613
+ ```
614
+
615
+ Query mode (recommended for Databricks-backed analytics):
616
+
617
+ ```tsx
618
+ import { LineChart } from "@databricks/appkit-ui/react";
619
+ import { sql } from "@databricks/appkit-ui/js";
620
+ import { useMemo } from "react";
621
+
622
+ export function SpendChart() {
623
+ const params = useMemo(
624
+ () => ({
625
+ startDate: sql.date("2024-01-01"),
626
+ endDate: sql.date("2024-12-31"),
627
+ aggregationLevel: sql.string("day"),
628
+ }),
629
+ [],
630
+ );
631
+
632
+ return (
633
+ <LineChart
634
+ queryKey="spend_data"
635
+ parameters={params}
636
+ format="auto" // "auto" | "json" | "arrow"
637
+ xKey="period"
638
+ yKey="cost_usd"
639
+ smooth
640
+ showSymbol={false}
641
+ />
642
+ );
643
+ }
644
+ ```
645
+
646
+ ### SQL helpers (`sql.*`)
647
+
648
+ Use these to build typed parameters (they return marker objects: `{ __sql_type, value }`):
649
+
650
+ - `sql.string(value)` → STRING (accepts string|number|boolean)
651
+ - `sql.number(value)` → NUMERIC (accepts number|string)
652
+ - `sql.boolean(value)` → BOOLEAN (accepts boolean|string("true"/"false")|number(1/0))
653
+ - `sql.date(value)` → DATE (accepts Date or `"YYYY-MM-DD"`)
654
+ - `sql.timestamp(value)` → TIMESTAMP (accepts Date, ISO string, or unix time)
655
+
656
+ Binary parameters (important):
657
+
658
+ - Databricks SQL Warehouse doesn't support `BINARY` as a parameter type.
659
+ - `sql.binary(value)` returns a **STRING marker containing hex**, so use `UNHEX(:param)` in SQL.
660
+ - `sql.binary` accepts `Uint8Array`, `ArrayBuffer`, or a hex string.
661
+
662
+ ### SQL result types (important)
663
+
664
+ Databricks SQL JSON results can return some numeric-like fields (especially `DECIMAL`) as strings. If a field behaves like a string at runtime, convert explicitly:
665
+
666
+ ```ts
667
+ const value = Number(row.amount);
668
+ ```
669
+
670
+ If you need more reliable numeric fidelity for large datasets, prefer `format: "ARROW"` and process Arrow on the client.
671
+
672
+ ### `connectSSE` (custom SSE connections)
673
+
674
+ For custom streaming endpoints (not analytics), use the `connectSSE` utility:
675
+
676
+ ```tsx
677
+ import { connectSSE } from "@databricks/appkit-ui/js";
678
+ import { useEffect, useState } from "react";
679
+
680
+ function useCustomStream(endpoint: string) {
681
+ const [messages, setMessages] = useState<string[]>([]);
682
+ const [connected, setConnected] = useState(false);
683
+
684
+ useEffect(() => {
685
+ const controller = new AbortController();
686
+
687
+ connectSSE({
688
+ url: endpoint,
689
+ payload: { key: "value" }, // optional: makes it a POST
690
+ onMessage: async ({ data }) => {
691
+ setConnected(true);
692
+ setMessages((prev) => [...prev, data]);
693
+ },
694
+ onError: (error) => {
695
+ console.error("SSE error:", error);
696
+ setConnected(false);
697
+ },
698
+ signal: controller.signal,
699
+ maxRetries: 3, // default: 3
700
+ retryDelay: 2000, // default: 2000ms (exponential backoff)
701
+ timeout: 300000, // default: 5 minutes
702
+ maxBufferSize: 1048576, // default: 1MB
703
+ });
704
+
705
+ return () => controller.abort();
706
+ }, [endpoint]);
707
+
708
+ return { messages, connected };
709
+ }
710
+ ```
711
+
712
+ Options:
713
+
714
+ - `url`: SSE endpoint URL (required)
715
+ - `payload`: Optional request body (if provided, uses POST; otherwise GET)
716
+ - `onMessage({ id, data })`: Called for each SSE message
717
+ - `onError(error)`: Called on connection errors
718
+ - `signal`: AbortSignal to cancel the connection
719
+ - `lastEventId`: Resume from a specific event ID
720
+ - `maxRetries`: Max retry attempts (default: 3)
721
+ - `retryDelay`: Base delay between retries in ms (default: 2000)
722
+ - `timeout`: Connection timeout in ms (default: 300000)
723
+ - `maxBufferSize`: Max buffer size in bytes (default: 1MB)
724
+
725
+ ### `ArrowClient` (advanced Arrow processing)
726
+
727
+ For low-level Arrow data handling:
728
+
729
+ ```tsx
730
+ import { ArrowClient } from "@databricks/appkit-ui/js";
731
+
732
+ // Process Arrow buffer
733
+ const table = await ArrowClient.processArrowBuffer(buffer);
734
+
735
+ // Fetch and process Arrow data in one call
736
+ const table = await ArrowClient.fetchAndProcessArrow(url, headers);
737
+
738
+ // Extract fields from table
739
+ const fields = ArrowClient.extractArrowFields(table);
740
+ // → [{ name: "date", type: ... }, { name: "value", type: ... }]
741
+
742
+ // Extract columns as arrays
743
+ const columns = ArrowClient.extractArrowColumns(table);
744
+ // → { date: [...], value: [...] }
745
+
746
+ // Extract chart data
747
+ const { xData, yDataMap } = ArrowClient.extractChartData(table, "date", ["value", "count"]);
748
+ // → { xData: [...], yDataMap: { value: [...], count: [...] } }
749
+
750
+ // Auto-detect chart fields from Arrow table
751
+ const detected = ArrowClient.detectFieldsFromArrow(table);
752
+ // → { xField: "date", yFields: ["value"], chartType: "timeseries" }
753
+ ```
754
+
755
+ ### DataTable
756
+
757
+ `DataTable` is a production-ready table integrated with `useAnalyticsQuery`.
758
+
759
+ Key behaviors:
760
+
761
+ - `parameters` is required (use `{}` if none)
762
+ - Supports opinionated mode (auto columns) and full-control mode (`children(table)`)
763
+
764
+ ```tsx
765
+ import { DataTable } from "@databricks/appkit-ui/react";
766
+
767
+ export function UsersTable() {
768
+ return (
769
+ <DataTable
770
+ queryKey="users_list"
771
+ parameters={{}}
772
+ filterColumn="email"
773
+ filterPlaceholder="Filter by email..."
774
+ pageSize={25}
775
+ pageSizeOptions={[10, 25, 50, 100]}
776
+ />
777
+ );
778
+ }
779
+ ```
780
+
781
+ ### UI components (primitives)
782
+
783
+ AppKit-UI ships shadcn-style primitives. Import from `@databricks/appkit-ui/react`.
784
+
785
+ Note: Exact exports can vary by AppKit-UI version. Prefer using IDE auto-import/autocomplete to confirm what your installed version exports.
786
+
787
+ Radix constraint (common bug):
788
+
789
+ - `SelectItem` cannot have `value=""`. Use a sentinel value like `"all"` or `"none"`.
790
+
791
+ **Available components:**
792
+
793
+ `Accordion`, `Alert`, `AlertDialog`, `AspectRatio`, `Avatar`, `Badge`, `Breadcrumb`, `Button`, `ButtonGroup`, `Calendar`, `Card`, `CardHeader`, `CardTitle`, `CardDescription`, `CardContent`, `CardFooter`, `Carousel`, `Checkbox`, `Collapsible`, `Command`, `ContextMenu`, `Dialog`, `DialogTrigger`, `DialogContent`, `DialogHeader`, `DialogTitle`, `DialogDescription`, `DialogFooter`, `Drawer`, `DropdownMenu`, `Empty`, `Field`, `Form`, `HoverCard`, `Input`, `InputGroup`, `InputOtp`, `Item`, `Kbd`, `Label`, `Menubar`, `NavigationMenu`, `Pagination`, `Popover`, `Progress`, `RadioGroup`, `Resizable`, `ScrollArea`, `Select`, `SelectTrigger`, `SelectValue`, `SelectContent`, `SelectItem`, `Separator`, `Sheet`, `Sidebar`, `Skeleton`, `Slider`, `Sonner`, `Spinner`, `Switch`, `Table`, `Tabs`, `TabsList`, `TabsTrigger`, `TabsContent`, `Textarea`, `Toggle`, `ToggleGroup`, `Tooltip`, `TooltipTrigger`, `TooltipContent`, `TooltipProvider`
794
+
795
+ ### Card pattern
796
+
797
+ ```tsx
798
+ import {
799
+ Card,
800
+ CardHeader,
801
+ CardTitle,
802
+ CardDescription,
803
+ CardContent,
804
+ CardFooter,
805
+ } from "@databricks/appkit-ui/react";
806
+
807
+ function MetricCard({ title, value, description }: Props) {
808
+ return (
809
+ <Card>
810
+ <CardHeader>
811
+ <CardDescription>{description}</CardDescription>
812
+ <CardTitle className="text-3xl">{value}</CardTitle>
813
+ </CardHeader>
814
+ <CardContent>
815
+ {/* Optional content */}
816
+ </CardContent>
817
+ <CardFooter>
818
+ {/* Optional footer */}
819
+ </CardFooter>
820
+ </Card>
821
+ );
822
+ }
823
+ ```
824
+
825
+ ### Select pattern
826
+
827
+ ```tsx
828
+ import {
829
+ Select,
830
+ SelectTrigger,
831
+ SelectValue,
832
+ SelectContent,
833
+ SelectItem,
834
+ } from "@databricks/appkit-ui/react";
835
+
836
+ function DateRangeSelect({ value, onChange }: Props) {
837
+ return (
838
+ <Select value={value} onValueChange={onChange}>
839
+ <SelectTrigger className="w-40">
840
+ <SelectValue placeholder="Select range" />
841
+ </SelectTrigger>
842
+ <SelectContent>
843
+ <SelectItem value="7d">Last 7 days</SelectItem>
844
+ <SelectItem value="30d">Last 30 days</SelectItem>
845
+ <SelectItem value="90d">Last 90 days</SelectItem>
846
+ </SelectContent>
847
+ </Select>
848
+ );
849
+ }
850
+ ```
851
+
852
+ ### Tabs pattern
853
+
854
+ ```tsx
855
+ import { Tabs, TabsList, TabsTrigger, TabsContent } from "@databricks/appkit-ui/react";
856
+
857
+ function Dashboard() {
858
+ return (
859
+ <Tabs defaultValue="overview">
860
+ <TabsList>
861
+ <TabsTrigger value="overview">Overview</TabsTrigger>
862
+ <TabsTrigger value="analytics">Analytics</TabsTrigger>
863
+ </TabsList>
864
+ <TabsContent value="overview">
865
+ <p>Overview content</p>
866
+ </TabsContent>
867
+ <TabsContent value="analytics">
868
+ <p>Analytics content</p>
869
+ </TabsContent>
870
+ </Tabs>
871
+ );
872
+ }
873
+ ```
874
+
875
+ ### Dialog pattern
876
+
877
+ ```tsx
878
+ import {
879
+ Dialog,
880
+ DialogTrigger,
881
+ DialogContent,
882
+ DialogHeader,
883
+ DialogTitle,
884
+ DialogDescription,
885
+ DialogFooter,
886
+ Button,
887
+ } from "@databricks/appkit-ui/react";
888
+
889
+ function ConfirmDialog() {
890
+ return (
891
+ <Dialog>
892
+ <DialogTrigger asChild>
893
+ <Button variant="destructive">Delete</Button>
894
+ </DialogTrigger>
895
+ <DialogContent>
896
+ <DialogHeader>
897
+ <DialogTitle>Confirm deletion</DialogTitle>
898
+ <DialogDescription>
899
+ This action cannot be undone.
900
+ </DialogDescription>
901
+ </DialogHeader>
902
+ <DialogFooter>
903
+ <Button variant="outline">Cancel</Button>
904
+ <Button variant="destructive">Delete</Button>
905
+ </DialogFooter>
906
+ </DialogContent>
907
+ </Dialog>
908
+ );
909
+ }
910
+ ```
911
+
912
+ ### TooltipProvider requirement
913
+
914
+ If using tooltips anywhere in your app, wrap your root component with `TooltipProvider`:
915
+
916
+ ```tsx
917
+ import { TooltipProvider } from "@databricks/appkit-ui/react";
918
+
919
+ function App() {
920
+ return (
921
+ <TooltipProvider>
922
+ {/* Your app content */}
923
+ </TooltipProvider>
924
+ );
925
+ }
926
+ ```
927
+
928
+ ### Button variants
929
+
930
+ ```tsx
931
+ import { Button } from "@databricks/appkit-ui/react";
932
+
933
+ <Button variant="default">Primary</Button>
934
+ <Button variant="secondary">Secondary</Button>
935
+ <Button variant="outline">Outline</Button>
936
+ <Button variant="ghost">Ghost</Button>
937
+ <Button variant="destructive">Destructive</Button>
938
+ <Button variant="link">Link</Button>
939
+ ```
940
+
941
+ ### Loading skeleton pattern
942
+
943
+ ```tsx
944
+ import { Card, CardHeader, Skeleton } from "@databricks/appkit-ui/react";
945
+
946
+ function LoadingCard() {
947
+ return (
948
+ <Card>
949
+ <CardHeader>
950
+ <Skeleton className="h-4 w-24 mb-2" />
951
+ <Skeleton className="h-8 w-20 mb-2" />
952
+ <Skeleton className="h-4 w-28" />
953
+ </CardHeader>
954
+ </Card>
955
+ );
956
+ }
957
+ ```
958
+
959
+ ## Stylesheet
960
+
961
+ In the main css file import the following
962
+
963
+ ```css
964
+ @import "@databricks/appkit-ui/styles.css";
965
+ ```
966
+
967
+ That will provide a default theme for the app using css variables.
968
+
969
+ ### Customizing theme (light/dark mode)
970
+
971
+ - Full list of variables to customize the theme.
972
+
973
+ ```css
974
+ @import "@databricks/appkit-ui/styles.css";
975
+
976
+ :root {
977
+ --radius: 0.625rem;
978
+ --background: oklch(1 0 0);
979
+ --foreground: oklch(0.141 0.005 285.823);
980
+ --card: oklch(1 0 0);
981
+ --card-foreground: oklch(0.141 0.005 285.823);
982
+ --popover: oklch(1 0 0);
983
+ --popover-foreground: oklch(0.141 0.005 285.823);
984
+ --primary: oklch(0.21 0.006 285.885);
985
+ --primary-foreground: oklch(0.985 0 0);
986
+ --secondary: oklch(0.967 0.001 286.375);
987
+ --secondary-foreground: oklch(0.21 0.006 285.885);
988
+ --muted: oklch(0.967 0.001 286.375);
989
+ --muted-foreground: oklch(0.552 0.016 285.938);
990
+ --accent: oklch(0.967 0.001 286.375);
991
+ --accent-foreground: oklch(0.21 0.006 285.885);
992
+ --destructive: oklch(0.577 0.245 27.325);
993
+ --destructive-foreground: oklch(0.985 0 0);
994
+ --success: oklch(0.603 0.135 166.892);
995
+ --success-foreground: oklch(1 0 0);
996
+ --warning: oklch(0.795 0.157 78.748);
997
+ --warning-foreground: oklch(0.199 0.027 238.732);
998
+ --border: oklch(0.92 0.004 286.32);
999
+ --input: oklch(0.92 0.004 286.32);
1000
+ --ring: oklch(0.705 0.015 286.067);
1001
+ --chart-1: oklch(0.646 0.222 41.116);
1002
+ --chart-2: oklch(0.6 0.118 184.704);
1003
+ --chart-3: oklch(0.398 0.07 227.392);
1004
+ --chart-4: oklch(0.828 0.189 84.429);
1005
+ --chart-5: oklch(0.769 0.188 70.08);
1006
+ --sidebar: oklch(0.985 0 0);
1007
+ --sidebar-foreground: oklch(0.141 0.005 285.823);
1008
+ --sidebar-primary: oklch(0.21 0.006 285.885);
1009
+ --sidebar-primary-foreground: oklch(0.985 0 0);
1010
+ --sidebar-accent: oklch(0.967 0.001 286.375);
1011
+ --sidebar-accent-foreground: oklch(0.21 0.006 285.885);
1012
+ --sidebar-border: oklch(0.92 0.004 286.32);
1013
+ --sidebar-ring: oklch(0.705 0.015 286.067);
1014
+ }
1015
+
1016
+ @media (prefers-color-scheme: dark) {
1017
+ :root {
1018
+ --background: oklch(0.141 0.005 285.823);
1019
+ --foreground: oklch(0.985 0 0);
1020
+ --card: oklch(0.21 0.006 285.885);
1021
+ --card-foreground: oklch(0.985 0 0);
1022
+ --popover: oklch(0.21 0.006 285.885);
1023
+ --popover-foreground: oklch(0.985 0 0);
1024
+ --primary: oklch(0.92 0.004 286.32);
1025
+ --primary-foreground: oklch(0.21 0.006 285.885);
1026
+ --secondary: oklch(0.274 0.006 286.033);
1027
+ --secondary-foreground: oklch(0.985 0 0);
1028
+ --muted: oklch(0.274 0.006 286.033);
1029
+ --muted-foreground: oklch(0.705 0.015 286.067);
1030
+ --accent: oklch(0.274 0.006 286.033);
1031
+ --accent-foreground: oklch(0.985 0 0);
1032
+ --destructive: oklch(0.704 0.191 22.216);
1033
+ --destructive-foreground: oklch(0.985 0 0);
1034
+ --success: oklch(0.67 0.12 167);
1035
+ --success-foreground: oklch(1 0 0);
1036
+ --warning: oklch(0.83 0.165 85);
1037
+ --warning-foreground: oklch(0.199 0.027 238.732);
1038
+ --border: oklch(1 0 0 / 10%);
1039
+ --input: oklch(1 0 0 / 15%);
1040
+ --ring: oklch(0.552 0.016 285.938);
1041
+ --chart-1: oklch(0.488 0.243 264.376);
1042
+ --chart-2: oklch(0.696 0.17 162.48);
1043
+ --chart-3: oklch(0.769 0.188 70.08);
1044
+ --chart-4: oklch(0.627 0.265 303.9);
1045
+ --chart-5: oklch(0.645 0.246 16.439);
1046
+ --sidebar: oklch(0.21 0.006 285.885);
1047
+ --sidebar-foreground: oklch(0.985 0 0);
1048
+ --sidebar-primary: oklch(0.488 0.243 264.376);
1049
+ --sidebar-primary-foreground: oklch(0.985 0 0);
1050
+ --sidebar-accent: oklch(0.274 0.006 286.033);
1051
+ --sidebar-accent-foreground: oklch(0.985 0 0);
1052
+ --sidebar-border: oklch(1 0 0 / 10%);
1053
+ --sidebar-ring: oklch(0.552 0.016 285.938);
1054
+ }
1055
+ }
1056
+
1057
+ ```
1058
+
1059
+ - If any variable is changed, it must be changed for both light and dark mode.
1060
+
1061
+ ## Type generation (QueryRegistry + IntelliSense)
1062
+
1063
+ Goal: generate `client/src/appKitTypes.d.ts` so query keys, params, and result rows are type-safe.
1064
+
1065
+ ### Vite plugin: `appKitTypesPlugin`
1066
+
1067
+ Correct option names:
1068
+
1069
+ - `outFile?: string` (default `src/appKitTypes.d.ts`)
1070
+ - `watchFolders?: string[]` (default `["../config/queries"]`)
1071
+
1072
+ ```ts
1073
+ // client/vite.config.ts
1074
+ import { defineConfig } from "vite";
1075
+ import react from "@vitejs/plugin-react";
1076
+ import { appKitTypesPlugin } from "@databricks/appkit";
1077
+
1078
+ export default defineConfig({
1079
+ plugins: [
1080
+ react(),
1081
+ appKitTypesPlugin({
1082
+ outFile: "src/appKitTypes.d.ts",
1083
+ watchFolders: ["../config/queries"],
1084
+ }),
1085
+ ],
1086
+ });
1087
+ ```
1088
+
1089
+ Important nuance:
1090
+
1091
+ - When the frontend is served through AppKit in dev mode, AppKit’s dev server already includes `appKitTypesPlugin()` internally.
1092
+ - You still want it in your client build pipeline if you run `vite build` separately.
1093
+
1094
+ ### CLI: `appkit-generate-types`
1095
+
1096
+ ```bash
1097
+ # Requires DATABRICKS_WAREHOUSE_ID (or pass as 3rd arg)
1098
+ npx appkit-generate-types [rootDir] [outFile] [warehouseId]
1099
+
1100
+ # Example:
1101
+ npx appkit-generate-types . client/src/appKitTypes.d.ts
1102
+
1103
+ # Force regeneration (skip cache):
1104
+ npx appkit-generate-types --no-cache
1105
+ ```
1106
+
1107
+ ## Databricks Apps config: `app.yaml`
1108
+
1109
+ Bind a SQL warehouse for Apps runtime:
1110
+
1111
+ ```yaml
1112
+ env:
1113
+ - name: DATABRICKS_WAREHOUSE_ID
1114
+ valueFrom: sql-warehouse
1115
+ ```
1116
+
1117
+ Full example with command:
1118
+
1119
+ ```yaml
1120
+ command:
1121
+ - node
1122
+ - build/index.mjs
1123
+ env:
1124
+ - name: DATABRICKS_WAREHOUSE_ID
1125
+ valueFrom: sql-warehouse
1126
+ ```
1127
+
1128
+ ## LLM checklist (before you "finalize" code)
1129
+
1130
+ - **Project setup**
1131
+ - `package.json` has `"type": "module"`
1132
+ - `tsx` is in devDependencies for dev server
1133
+ - `dev` script uses `NODE_ENV=development tsx watch server/index.ts`
1134
+ - `client/index.html` exists with `<div id="root"></div>` and script pointing to `client/src/main.tsx`
1135
+
1136
+ - **Backend**
1137
+ - `await createApp({ plugins: [...] })` is used (or `void createApp` with intent)
1138
+ - `server()` is included (always)
1139
+ - If using SQL: `analytics({})` included + `config/queries/*.sql` present
1140
+ - Queries use `:param` placeholders, and params are passed from UI using `sql.*`
1141
+ - If query needs workspace scoping: uses `:workspaceId`
1142
+
1143
+ - **Frontend**
1144
+ - `useMemo` wraps parameters objects
1145
+ - Loading/error/empty states are explicit
1146
+ - Charts use `format="auto"` unless you have a reason to force `"json"`/`"arrow"`
1147
+ - If using tooltips: root is wrapped with `<TooltipProvider>`
1148
+
1149
+ - **Never**
1150
+ - Don't build SQL strings manually
1151
+ - Don't pass untyped raw params for annotated queries
1152
+ - Don't ignore `createApp()`'s promise
1153
+ - Don't invent UI components not listed in this file
1154
+