@concepttocloud/saiku-embed 3.18.2 → 3.20.0

package/README.md

@@ -50,6 +50,91 @@ globally — no further setup.
 ></saiku-embed>
 ```
 
+### A saved query, rendered as a hierarchical matrix (v3.19)
+
+Matrix mode preserves the row / column axis structure — measures on
+columns, dimension members on rows — instead of flattening to a single
+row-key map like `render="table"` does. Useful for pivot-style reports.
+
+```html
+<saiku-embed
+  server="..."
+  token="..."
+  path="homes/admin/Examples/Sales.saiku"
+  render="matrix"
+  height="500px"
+></saiku-embed>
+```
+
+### An AI ask widget over a cube (v3.19, `kind="ai"`)
+
+Point the token at a cube (rather than a saved query) and drop in a
+plain-English ask box. Behind the scenes it POSTs to
+`/rest/saiku/api/embed/ai/{cubeId}/ask`, which runs the question through
+the server's configured LLM provider under the pinned owner's data
+scope. Requires an AI-kind token (see "Minting an AI token" below).
+
+```html
+<saiku-embed
+  server="..."
+  token="..."
+  kind="ai"
+  path="foodmart/FoodMart/FoodMart/Sales"
+  height="200px"
+></saiku-embed>
+```
+
+### A single KPI tile (v3.20, `render="kpi"`)
+
+The most common embed shape — one governed figure rendered large. Derives its
+value from the same records response as `render="table"`, so it needs no server
+change. Point it at a saved query whose last measure is the headline number;
+when the query carries a prior measure column, a delta chip is shown.
+
+```html
+<saiku-embed
+  server="..."
+  token="..."
+  path="homes/admin/Examples/NetRevenue.saiku"
+  render="kpi"
+  height="160px"
+></saiku-embed>
+```
+
+### A saved query, sliced at embed time (v3.20, `filter`)
+
+Pass slicer overrides as a JSON array. They ride the same validated slicer path
+the dashboard filter tiles use — the saved query's cube binding and axes are
+untouched, so a host can parameterise an embed without re-authoring the query.
+
+```html
+<saiku-embed
+  server="..."
+  token="..."
+  path="homes/admin/Examples/Sales.saiku"
+  filter='[{"dimension":"Time","level":"Year","members":["[Time].[2024]"]}]'
+></saiku-embed>
+```
+
+### A persona-scoped AI ask (v3.20, `space`)
+
+Add a `space` to a `kind="ai"` embed to scope the assistant to an admin-authored
+[Agent Space](../../../docs/AGENT-SPACES-SPEC.md) persona. The persona's system
+prompt, skill filter, and cube allowlist apply server-side. The cube stays
+pinned by the token, so a space can only **narrow** what the guest reaches — if
+the space's allowlist excludes the pinned cube, the ask fails closed.
+
+```html
+<saiku-embed
+  server="..."
+  token="..."
+  kind="ai"
+  path="foodmart/FoodMart/FoodMart/Sales"
+  space="foodmart-sales-analyst"
+  height="240px"
+></saiku-embed>
+```
+
 ### A saved dashboard
 
 ```html
@@ -79,18 +164,43 @@ If the resource is marked publicly embeddable on the server
 
 | Attribute | Default     | Notes                                                                  |
 |-----------|-------------|------------------------------------------------------------------------|
-| `server`  | _(required)_| Origin of the Saiku launcher, e.g. `https://demo.saiku.bi`            |
-| `path`    | _(required)_| Repository path of the saved query (`.saiku`) or dashboard (`.saikudash`) |
-| `kind`    | `query`     | `query` or `dashboard`                                                 |
+| `server`  | _(optional)_| Origin of the Saiku launcher, e.g. `https://demo.saiku.bi`. Leave empty for same-origin (v3.19+) |
+| `path`    | _(required)_| `kind=query`: saved query path (`.saiku`) — `kind=dashboard`: dashboard path (`.saikudash`) — `kind=ai`: cube ref `connection/catalog/schema/cubeName` |
+| `kind`    | `query`     | `query`, `dashboard`, or `ai`                                          |
 | `token`   | _(none)_    | Embed token from `POST /saiku/api/embed/tokens`. Omit for public reads |
-| `render`  | `table`     | For `kind=query`: `table` or `chart`                                  |
+| `render`  | `table`     | For `kind=query`: `table`, `matrix`, `chart`, or `kpi` (v3.20)         |
 | `mode`    | `bar`       | For `render=chart`: `bar`, `line`, or `pie`                            |
 | `height`  | `400px`     | CSS height of the rendered surface                                     |
+| `space`   | _(none)_    | For `kind=ai`: Agent Space persona id — scopes the ask server-side (v3.20) |
+| `filter`  | _(none)_    | For `kind=query`: JSON array of slicer overrides applied at embed time (v3.20) |
+| `theme`   | _(light)_   | `light`, `dark`, or `auto` (follow `prefers-color-scheme`) (v3.20)     |
 
 The component re-renders whenever an attribute changes, so frameworks
 binding state to attrs (React's JSX, Vue's `:server="..."`, etc.) just
 work.
 
+## Events (v3.20)
+
+The element emits namespaced `CustomEvent`s so the host page can react to what
+happens inside the embed. All bubble and are `composed`, so a listener on the
+`<saiku-embed>` element receives them:
+
+| Event             | `detail`                          | Fires when                              |
+|-------------------|-----------------------------------|-----------------------------------------|
+| `saiku:load`      | `{ kind, rows }`                  | a query / matrix / kpi surface loads    |
+| `saiku:error`     | `{ message }`                     | a query load fails (friendly message)   |
+| `saiku:select`    | `{ row }`                         | a table row is clicked (`render=table`) |
+| `saiku:ai-query`  | `{ question, degraded }`          | an AI ask resolves (`kind=ai`)          |
+
+```js
+const el = document.querySelector("saiku-embed");
+el.addEventListener("saiku:load", (e) => console.log("loaded", e.detail.rows, "rows"));
+el.addEventListener("saiku:select", (e) => showDetail(e.detail.row));
+```
+
+In React (via `@concepttocloud/saiku-embed-react`) the same events are exposed
+as `onLoad` / `onError` / `onSelect` / `onAiQuery` callback props.
+
 ## Server-side: minting a token
 
 Authenticated as a user who has GRANT on the saved query / dashboard:
@@ -108,6 +218,28 @@ curl -X POST 'https://YOUR-SAIKU/rest/saiku/api/embed/tokens' \
 # → { "status": "OK", "token": "tx-...", "expiresAt": ... }
 ```
 
+### Minting an AI token (v3.19)
+
+For `kind="ai"` embeds. `resourcePath` is a cube ref rather than a
+file path. Mint is admin-only for v1 (cube-level ACLs are a follow-up).
+
+```bash
+curl -X POST 'https://YOUR-SAIKU/rest/saiku/api/embed/tokens' \
+  -u admin:admin \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "resourceKind": "ai",
+    "resourcePath": "foodmart/FoodMart/FoodMart/Sales",
+    "ttlHours": 72,
+    "label": "DimSum widget on marketing site"
+  }'
+```
+
+Server-side, an AI ask requires the launcher to have an LLM provider
+configured (`saiku.ai.ask.provider = anthropic | openai` plus the
+matching API key). Without it, the widget renders a degraded message
+rather than an error.
+
 Paste the `token` into the host page's `<saiku-embed token="...">`.
 Tokens are server-authoritative — revoke any time via:
 
@@ -144,8 +276,14 @@ curl -X DELETE 'https://YOUR-SAIKU/rest/saiku/api/embed/public?kind=query&path=s
 
 The embed lives inside an
 [open shadow root](https://developer.mozilla.org/docs/Web/API/ShadowRoot),
-so host page CSS can't leak in and vice versa. To recolour the embed,
-set CSS variables on the host page:
+so host page CSS can't leak in and vice versa.
+
+For a quick dark surface, set `theme="dark"` (or `theme="auto"` to follow the
+viewer's `prefers-color-scheme`) — it swaps the whole palette without the host
+having to set each variable (v3.20). Leaving `theme` unset keeps the original
+light palette, so existing embeds are unchanged.
+
+To fine-tune individual colours, set CSS variables on the host page:
 
 ```css
 saiku-embed {
@@ -161,6 +299,28 @@ saiku-embed {
 }
 ```
 
+### Theming the chart itself
+
+The variables above style the embed **chrome** (frame, header, table). To brand
+the **chart series + axes**, set these (custom properties inherit through the
+shadow boundary, so the canvas chart picks them up):
+
+```css
+saiku-embed {
+  /* Series colour cycle — set as many as you need, 1..8, contiguously.
+     Any unset → the chart falls back to the built-in palette. */
+  --saiku-embed-chart-1: #2563eb;
+  --saiku-embed-chart-2: #16a34a;
+  --saiku-embed-chart-3: #dc2626;
+  /* …up to --saiku-embed-chart-8 */
+
+  /* Axis labels / legend / titles use --saiku-embed-fg;
+     axis + split lines use --saiku-embed-muted (both shared with the chrome). */
+}
+```
+
+An embed with none of these set renders exactly as before (ECharts defaults).
+
 ## Security model
 
 - **Header-only token transport.** The token travels as

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@concepttocloud/saiku-embed",
-  "version": "3.18.2",
+  "version": "3.20.0",
   "description": "<saiku-embed> Web Component — drop a saved Saiku query or dashboard into any page.",
   "license": "Apache-2.0",
   "type": "module",