@zestl/zvolv-widgets 0.0.3 → 0.0.5

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 0.0.4
+
+### Added
+- **`canViewDashboard(d, { isAdmin, groupId })`** — ZAI-Dashboard's dashboard view rule (admins all; `permissions` VIEW/EDIT_PERMISSION; `HideInMobileApp` needs EDIT_PERMISSION; `ViewPerm` fallback).
+- **`visibleDashboardTree(elements, viewer)`** — `canViewDashboard` + `buildDashboardTree`, for an app's sidebar.
+- README §12 and SKILL.md: apps on stored dashboards (pages, access, per-page loading, per-widget refresh) and writing records with `fetchSubmission` / `updateSubmission` / `createSubmission`.
+
+### Documented
+- A TABLE widget with `configuration.columns` returns only `id` + those columns (`_source`); store every field a host reads or writes back as a column.
+
 ## 0.0.3
 
 These are all client-side enhancements that run after the query; none changes

package/README.md

@@ -36,6 +36,7 @@ visual decision can be overridden.
 9. [Install, link, test](#9-install-link-test)
 10. [Rules and known limitations](#10-rules-and-known-limitations)
 11. [Forms](#11-forms)
+12. [Apps on stored dashboards: pages, access, writes](#12-apps-on-stored-dashboards-pages-access-writes)
 
 ---
 
@@ -839,6 +840,8 @@ same rules ZAI-Dashboard applies:
 | `dateRangeFor(token)`, `dashboardDefaultDateToken(ws)` | date presets, and the DATE_FILTER widget's default |
 | `cdateFiltersFor(w, ws)` | the per-widget `cdateFilters` (the fields a date range lands on) |
 | `buildDashboardTree(elements, isAdmin)` | `getDashboards()` → a sorted tree (`ChildReportIDs` nest), with hidden/mobile-only removed |
+| `canViewDashboard(d, { isAdmin, groupId })` | ZAI-Dashboard's view rule: admins see all; otherwise `d.permissions` must hold `VIEW_PERMISSION` / `EDIT_PERMISSION` (`HideInMobileApp` needs `EDIT_PERMISSION`); without `permissions`, `ViewPerm` (group ids, `-1` = everyone) is checked |
+| `visibleDashboardTree(elements, viewer)` | `canViewDashboard` filter + `buildDashboardTree`: the sidebar of an app |
 
 ```tsx
 const w = normalizeWidget(stored);
@@ -913,6 +916,7 @@ writes widget code. Without it, Claude tends to write its own data fetching.
 - **Live backend:** `zvolv-insights` reaches the live API through `createZvolvRuntime` (workspace init and login verified). Check real dashboards against ZAI-Dashboard before relying on the numbers.
 - **Tables fetch up to `rowLimit` rows (default 1000).** There is no server pagination yet. Server-side search, filters and sort run over the full dataset, but only the first `rowLimit` matches are shown.
 - **Column-filter options** come from the rows loaded so far. They accumulate across fetches, so options do not vanish once one is ticked. They are not a full distinct-values query.
+- **A TABLE widget returns only its columns.** When `configuration.columns` is non-empty, the query asks Elasticsearch for `_source: ["id", ...columns.map(c => c.dataPoint)]` (`["uuid", …]` for tasks). A field that is not a column is not in the rows, even if it is in `dataSource.fields`. Store every field a host reads or writes back as a column (`hidden: true` hides it from the default table), or leave `columns` empty to get every field.
 - **Widget filters are AND-ed.** For OR logic, pass a host ZFilters payload through `localFilters`.
 - **0.0.2 query features need server and host support.** `interval` grouping, `dateDiff` metrics, percentiles and AND-ed per-metric filters produce ES shapes that the server's aggregation flattener and ZAI-Dashboard must also handle. See `MIRROR_NOTES.md`.
 - **Calendar / MeetingScheduler are simplified.** There is no drag-to-resize, month-grid layout or virtual scrolling. For full parity, wrap FullCalendar in `render`.
@@ -1085,3 +1089,64 @@ Platform rules these helpers follow:
 - **Do not use `AVG`**: the platform lists it but does not implement it. Every write to the form then fails with a 502. Write the average out instead, e.g. `DIVI(ADD(A, ADD(B, C)), 3)`. `ADD`, `SUB`, `MUL`, `DIVI` and `IF` are verified working.
 - The `create_form` validator only accepts formulas with **bare, single-word labels**, e.g. `MUL(Quantity, Rate)`. It rejects `{Label}` and labels containing spaces, even though the KB documents `{Label}`. The engine evaluates both styles.
 - Row height is 21px. A tile of `h` rows is `h × 21 − 16` px tall, so size form tiles to their fields; forms scroll inside the tile with the footer pinned.
+
+---
+
+## 12. Apps on stored dashboards: pages, access, writes
+
+A custom app (e.g. a zapp app at `/v6/<app>/zapp/<id>`) can use the zapp's dashboards as its pages.
+The pattern below is what the `zvolv-zapp-app` skill's template does.
+
+### Pages = the dashboards the user may open
+
+```ts
+const res = await client.workflow.getDashboards(String(zappId));
+const elements = res?.data?.elements ?? res?.elements ?? [];
+const tree = visibleDashboardTree(elements, { isAdmin, groupId });   // sidebar, in SequenceID order, titles from Zvolv
+```
+
+- Tag each dashboard's Description (e.g. `app:screen:orders`) to pick the screen that draws it; draw an
+  untagged one generically with `normalizeWidget` + `resolveDashboardLayout` + `<ZvolvWidget>`.
+- Edit rights on the zapp: `client.workflow.checkPermissions(zappId, ["EDIT_WORKFLOW_TYPE"])` returns the
+  granted ops (ZAI-Dashboard's `hasDashboardEditAccess`).
+- `isAdmin`: the signed-in user's `profile.role_details.role === "admin"` (decrypt the session first:
+  `decryptAuthObject(client.auth.userInstance)`). `groupId`: `userGroupId` on the same object.
+
+### Load per page, refresh per widget
+
+On each visit to a page, call `getDashboard(dashId, zappId)` once and run only that page's widgets
+(`useWidgetData({ widgetId, widgetType, dataSource, configurations })` per widget, from
+`normalizeWidget`). Nothing is fetched for pages that are not open. A card's refresh button calls that
+widget's `refresh()`; nothing else refetches.
+
+### Writing records
+
+The submission engine `<ZvolvForm>` uses is exported for in-place edits (a status select, a drag to
+another stage, an owner pick):
+
+```ts
+import { fetchForm, fetchSubmission, updateSubmission, createSubmission, submissionIdOf } from "@zestl/zvolv-widgets";
+
+// update a few fields of one record, keeping every other stored value
+const { form, values } = await fetchSubmission(client, row.id);          // row.id = the submission id
+const def = form ?? (await fetchForm(client, formId));
+const byId = { ...values };
+for (const [label, v] of Object.entries(patch)) byId[def.elements.find((e) => e.label === label)!.elementId] = v;
+await updateSubmission(client, def, row.id, def.elements, byId);
+
+// create one
+const res = await createSubmission(client, def, def.elements, { [elementIdOf("Status")]: "Open" });
+const id = submissionIdOf(res);
+```
+
+| Field type | Value |
+| --- | --- |
+| text, number, date (`YYYY-MM-DD`), SPINNER | as is (the option text for SPINNER) |
+| CHECK_BOX | `true` / `false` |
+| AUTO_COMPLETE people picker | `[userId]` |
+| FORM_SEARCH / INPUT_TAG lookup | `{ view, select, extraLabels: [] }` |
+
+- A row's identity is `row.id` (the submission id). Autonumber fields come back only if they are columns
+  (see §10), so never key records on them.
+- After a write, refetch the widgets that read that form (`refresh()`), rather than patching rows locally.
+- The server re-evaluates formulas and enforces form permissions; show its error when a write is refused.

package/SKILL.md

@@ -18,6 +18,8 @@ design tokens, render props and control slots. You never write data logic.
 6. **No colour/font/shadow literals** in templates or slots. Use `tokens` / `useTokens()`.
 7. Pass stored `dataSource` / `configurations` through **untouched**. Give widgets a sized parent.
 8. Never call `getZvolvClient()` at module scope. The runtime's `client` is a getter.
+9. **A TABLE returns only its columns.** Non-empty `configuration.columns` limits the query to `["id", ...columns]`. Store every field you read or write back as a column (`hidden: true` to hide it), or leave `columns` empty.
+10. **Rows are keyed by `row.id`** (the submission id). Edits go through `fetchSubmission` + `updateSubmission` (or `<ZvolvForm mode="EDIT">`), creates through `createSubmission` / `<ZvolvForm>`. Never keep edited records only in app state.
 
 ## Setup
 
@@ -123,6 +125,7 @@ For `getDashboard(dashId, zappId).elements[0].widgets`, never parse or lay out b
 `dashboardFilterDefs(ws)` + `buildDashFilters(values, range)` → `dashFilters` ·
 `cdateFiltersFor(w, ws)` → `cdateFilters` · `dateRangeFor(token)` · `buildDashboardTree(getDashboards().elements, isAdmin)`.
 Stored table columns are `{ label, dataPoint, type }` and are read as-is.
+Sidebar of an app: `visibleDashboardTree(getDashboards().elements, { isAdmin, groupId })` — the access rule is `canViewDashboard` (admins all; else `permissions` has VIEW/EDIT_PERMISSION; else `ViewPerm` holds the group). Load a dashboard's widgets when its page opens, not before; a card refresh = that widget's `refresh()`. Zapp edit right: `workflow.checkPermissions(zappId, ["EDIT_WORKFLOW_TYPE"])`. Full pattern: README §12.
 
 ## Authoring a data source
 
@@ -269,6 +272,10 @@ When asked to build a dashboard that captures data:
 - `width` is a percentage, placed at the element root and in `attributes.Width`.
 - Rules go on the driving field; each target starts `hidden: true`.
 
+## Writing records
+
+`fetchSubmission(client, row.id)` → `updateSubmission(client, form, row.id, form.elements, valuesByElementId)` keeps every other stored value. `createSubmission(client, form, form.elements, values)` + `submissionIdOf(res)` for a create. Values: people `[userId]`, lookups `{ view, select, extraLabels: [] }`, checkbox `true/false`, dates `YYYY-MM-DD`. Refetch the widgets of that form after a write. See README §12.
+
 ## Checklist before you finish
 
 - [ ] Every plotted, grouped, filtered, searched or sorted name exists as a `dataSource.fields` header, and series names equal the pivot titles/values.
@@ -276,3 +283,4 @@ When asked to build a dashboard that captures data:
 - [ ] Controlled interaction props each have their `on*Change`.
 - [ ] No hard-coded colours. `render` is supplied for ZaiChat, GoogleMap and Html markup, and a FormKit is provided when forms are shown.
 - [ ] Each widget sits in a sized container, and `ChildTableWidget` is width-clamped.
+- [ ] Every change a user makes is written with `ZvolvForm` / `updateSubmission` / `createSubmission`; no records live only in app state or browser storage.

package/dist/index.cjs

@@ -9334,6 +9334,20 @@ function buildDashboardTree(elements, isAdmin = false) {
   });
   return list.filter((d) => !childIds.has(String(d.ReportID)) && visible(d)).sort(seq).map(node);
 }
+function canViewDashboard(d, viewer = {}) {
+  if (!d) return false;
+  if (viewer.isAdmin) return true;
+  const perms = Array.isArray(d.permissions) ? d.permissions : null;
+  if (d.HideInMobileApp === "YES") return !!perms?.includes("EDIT_PERMISSION");
+  if (perms) return perms.includes("VIEW_PERMISSION") || perms.includes("EDIT_PERMISSION");
+  const view = Array.isArray(d.ViewPerm) ? d.ViewPerm.map(Number) : null;
+  if (view && view.length && viewer.groupId != null && !view.includes(-1)) return view.includes(Number(viewer.groupId));
+  return true;
+}
+function visibleDashboardTree(elements, viewer = {}) {
+  const list = (Array.isArray(elements) ? elements : []).filter((d) => canViewDashboard(d, viewer));
+  return buildDashboardTree(list, !!viewer.isAdmin);
+}
 var text = (v) => {
   if (v === null || v === void 0 || v === "") return "";
   if (Array.isArray(v)) return v.map(text).filter(Boolean).join(", ");
@@ -9762,6 +9776,7 @@ exports.buildSubmissionElements = buildSubmissionElements;
 exports.buildTree = buildTree;
 exports.buildTriggerBody = buildTriggerBody;
 exports.buildWidgetFilterClauses = buildWidgetFilterClauses;
+exports.canViewDashboard = canViewDashboard;
 exports.cascade = cascade;
 exports.cdateFiltersFor = cdateFiltersFor;
 exports.childIdsOf = childIdsOf;
@@ -9896,6 +9911,7 @@ exports.useZvolvRuntime = useZvolvRuntime;
 exports.usesFormFramework = usesFormFramework;
 exports.validateField = validateField;
 exports.validateForm = validateForm;
+exports.visibleDashboardTree = visibleDashboardTree;
 exports.when = when;
 exports.where = where;
 //# sourceMappingURL=index.cjs.map