@databricks/appkit-ui 0.1.5 → 0.3.0

package/llms.txt

@@ -431,9 +431,12 @@ WHERE workspace_id = :workspaceId
 HTTP endpoints exposed (mounted under `/api/analytics`):
 
 - `POST /api/analytics/query/:query_key`
-- `POST /api/analytics/users/me/query/:query_key`
 - `GET /api/analytics/arrow-result/:jobId`
-- `GET /api/analytics/users/me/arrow-result/:jobId`
+
+**Query file naming convention determines execution context:**
+
+- `config/queries/<query_key>.sql` - Executes as service principal (shared cache)
+- `config/queries/<query_key>.obo.sql` - Executes as user (OBO = On-Behalf-Of, per-user cache)
 
 Formats:
 
@@ -668,6 +671,56 @@ export function SpendChart() {
 }
 ```
 
+**Chart props reference (important):**
+
+Charts are **self-contained ECharts components**. Configure via props, NOT children:
+
+```tsx
+// ✅ Correct: use props for customization
+<BarChart
+  queryKey="sales_by_region"
+  parameters={{}}
+  xKey="region"                    // X-axis field
+  yKey={["revenue", "expenses"]}   // Y-axis field(s) - string or string[]
+  colors={['#40d1f5', '#4462c9']}  // Custom colors
+  stacked                          // Stack bars (BarChart, AreaChart)
+  orientation="horizontal"         // "vertical" (default) | "horizontal"
+  showLegend                       // Show legend
+  height={400}                     // Height in pixels (default: 300)
+/>
+
+<LineChart
+  queryKey="trend_data"
+  parameters={{}}
+  xKey="date"
+  yKey="value"
+  smooth                           // Smooth curves (default: true)
+  showSymbol={false}               // Hide data point markers
+/>
+```
+
+**❌ CRITICAL: Charts do NOT accept Recharts children**
+
+```tsx
+// ❌ WRONG - AppKit charts are NOT Recharts wrappers
+import { BarChart } from "@databricks/appkit-ui/react";
+import { Bar, XAxis, YAxis, CartesianGrid } from "recharts";
+
+<BarChart queryKey="data" parameters={{}}>
+  <CartesianGrid />  // ❌ This will cause TypeScript errors
+  <XAxis dataKey="x" />  // ❌ Not supported
+  <Bar dataKey="y" />  // ❌ Not supported
+</BarChart>
+
+// ✅ CORRECT - use props instead
+<BarChart
+  queryKey="data"
+  parameters={{}}
+  xKey="x"
+  yKey="y"
+/>
+```
+
 ### SQL helpers (`sql.*`)
 
 Use these to build typed parameters (they return marker objects: `{ __sql_type, value }`):
@@ -1169,6 +1222,7 @@ env:
   - `useMemo` wraps parameters objects
   - Loading/error/empty states are explicit
   - Charts use `format="auto"` unless you have a reason to force `"json"`/`"arrow"`
+  - Charts use props (`xKey`, `yKey`, `colors`) NOT children (they're ECharts-based, not Recharts)
   - If using tooltips: root is wrapped with `<TooltipProvider>`
 
 - **Never**
@@ -1176,4 +1230,5 @@ env:
   - Don't pass untyped raw params for annotated queries
   - Don't ignore `createApp()`'s promise
   - Don't invent UI components not listed in this file
+  - Don't pass Recharts children (`<Bar>`, `<XAxis>`, etc.) to AppKit chart components
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@databricks/appkit-ui",
   "type": "module",
-  "version": "0.1.5",
+  "version": "0.3.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/databricks/appkit.git"