@zestl/zvolv-widgets 0.0.0-stage → 0.0.1

package/SKILL.md

@@ -0,0 +1,251 @@
+---
+name: zvolv-widgets
+description: Build Zvolv dashboards with @zestl/zvolv-widgets. Use whenever designing or coding a dashboard, KPI, chart, table, list, timeline, calendar or any Zvolv widget — including adding search, column filters, sorting or widget-level filters. The library owns data fetching, query generation, filtering and sorting; you own all visual design, configuration and the UI of every control.
+---
+
+# @zestl/zvolv-widgets — contract
+
+**The library owns the data. You own the UI.** You write widget configuration,
+design tokens, render props and control slots. You never write data logic.
+
+## Hard rules — read first
+
+1. **Never** write a raw API call, build an Elasticsearch query, recompute a pivot, or filter/search/sort rows yourself. Pass `search` / `columnFilters` / `sort` / `widgetFilters` (or turn on the built-in controls). The library applies them on the server or on loaded rows, whichever is correct.
+2. **Names must match.** `series[].argumentField` = `pivot.rows[].title`. `series[].valueField` = `pivot.summary[].value` (or a `derive()` title). `WidgetFilter.field`, `SortState.key` and `ColumnFilters` keys are each a `header` in `dataSource.fields`. A mismatch shows an empty widget with no error.
+3. **Declare every field** you plot, group, filter, search or sort on in `dataSource.fields`.
+4. **`taskSource()` never has a `formId`.** Never invent a `formId` or field name. Ask for it, or read it from an existing widget's stored `DataSource`.
+5. **`unconfigured` ≠ `empty`.** Never fall back to demo data.
+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.
+
+## Setup
+
+```tsx
+import { ZvolvProvider, ZvolvThemeProvider, TemplateProvider, createZvolvRuntime, createMockRuntime } from "@zestl/zvolv-widgets";
+
+// Real data: an SDK client after workspace.init(domain) + login. Pass a getter.
+const runtime = createZvolvRuntime({ client: () => zvolvClient });   // or createMockRuntime() for previews
+
+<ZvolvProvider runtime={runtime}>
+  <ZvolvThemeProvider tokens={myDesign}>
+    <TemplateProvider templates={myTemplates}>   {/* optional */}
+      <Dashboard />
+    </TemplateProvider>
+  </ZvolvThemeProvider>
+</ZvolvProvider>
+```
+
+## Props every data widget takes
+
+```tsx
+<AnyWidget
+  dataSource={ds}              // WHAT is queried — formSource()/taskSource(), or stored value untouched
+  configurations={cfg}         // HOW it looks — object or JSON string
+  dashFilters={dashState}      // dashboard filter state (optional)
+  cdateFilters={dateFilters}   // dashboard date filters (optional)
+  title="…" description="…"    // optional chrome
+  render={(args) => …}         // optional: own the visuals (args per family below)
+/>
+```
+
+By type string: `<ZvolvWidget type="BAR_CHART" {...props} />`.
+
+## Search, column filters, sort, widget filters
+
+| Control | Widgets | Turn on (any one) | Value shape |
+| --- | --- | --- | --- |
+| Search | all data widgets | `showSearch` · `config.showSearchbar` · pass `renderSearch` | `string` |
+| Widget filter | all data widgets | `showWidgetFilter` · `config.showWidgetFilter` · pass `renderWidgetFilter` | `WidgetFilter[]` |
+| Column filter | tables | `showColumnFilter` · `config.showColumnFilter` · pass `renderColumnFilter` | `Record<columnKey, any[]>`, where `""` means blanks |
+| Sort | tables | on by default. Off: `enableSort={false}` | `{ key, direction: "asc" \| "desc" } \| null` |
+
+```ts
+interface WidgetFilter {
+  field: string;   // a dataSource.fields header
+  operator: "IN" | "NOT_IN" | "EQUALS" | "CONTAINS" | "STARTS_WITH"
+          | "GREATER_THAN" | "LESS_THAN" | "BETWEEN" | "EMPTY" | "NOT_EMPTY" | "DATE_IS";
+  value?: any;     // IN/NOT_IN: array · BETWEEN: [from, to] · DATE_IS: "TODAY" | "YESTERDAY" |
+                   // "LAST_SEVEN_DAYS" | "LAST_THIRTY_DAYS" | "THIS_WEEK" | "THIS_MONTH" | "THIS_YEAR"
+                   // EMPTY/NOT_EMPTY: omit · user fields: user ids, not names
+}
+```
+
+**State.** Choose one approach per control:
+- Uncontrolled: `defaultSearch`, `defaultWidgetFilters`, `defaultColumnFilters`, `defaultSort`.
+- Controlled: pass the value **and** its change handler: `search` + `onSearchChange`, `widgetFilters` + `onWidgetFiltersChange`, `columnFilters` + `onColumnFiltersChange`, `sort` + `onSortChange`. A controlled value without its handler is read-only.
+- `onInteractionsChange(state)` fires with the full state after any change.
+
+**UI is yours: slots.** Each receives the value and setters. Whatever it sets is applied to the data.
+
+| Slot | Args |
+| --- | --- |
+| `renderSearch` | `{ value, setValue, clear, placeholder, mode, loading, tokens }` |
+| `renderWidgetFilter` | `{ filters, setFilters, addFilter, removeFilter, clear, fields: {field,label,kind,operators}[], declared, mode, tokens }` |
+| `renderColumnFilter` (tables) | `{ column, selected, setSelected, clear, options: {value,label,count}[], mode, tokens }` |
+| `renderSortIndicator` (tables) | `{ column, direction, toggle, setDirection, tokens }` |
+| `renderToolbar` | `{ search, widgetFilter, interactions, tokens }`. Place the resolved nodes yourself |
+
+If you omit a slot, a minimal token-styled default is used.
+**Slots must return elements.** Write `renderColumnFilter={(a) => <MyFilter {...a} />}`, never `renderColumnFilter={MyFilter}`. Slots are called as functions, so a hook-using component passed directly breaks hook order.
+
+```tsx
+<DashboardTableWidget
+  dataSource={ds} configurations={cfg} showColumnFilter
+  renderSearch={({ value, setValue, placeholder }) =>
+    <MyInput value={value} onChange={(e) => setValue(e.target.value)} placeholder={placeholder} />}
+  renderColumnFilter={({ column, options, selected, setSelected }) =>
+    <MyMultiSelect label={column.header} options={options} value={selected} onChange={setSelected} />}
+  renderSortIndicator={({ direction, toggle }) => <MySortIcon dir={direction} onClick={toggle} />}
+  renderWidgetFilter={({ fields, filters, addFilter, removeFilter }) =>
+    <MyFilterBuilder fields={fields} value={filters} onAdd={addFilter} onRemove={removeFilter} />}
+/>
+```
+
+**Where it runs.** Automatic; don't fight it:
+
+| Source | Search / column filter / sort | Widget filters |
+| --- | --- | --- |
+| form/task, no `pivot.rows` | server (full dataset) | server |
+| form/task with `pivot.rows` | loaded rows (buckets) | server |
+| legacy widget-id, `automationRows` | loaded rows | loaded rows |
+| `ChildTableWidget` | loaded rows | server |
+
+`meta.tableMode` / `meta.filterMode` (and each slot's `mode`) report which one applies.
+
+`FilterPanelWidget` is a **dashboard-level** control. It is controlled via `value`/`onChange` and issues no queries. Feed its output into other widgets' `dashFilters`. Use widget filters to narrow a single widget.
+
+## Rendering a stored dashboard
+
+For `getDashboard(dashId, zappId).elements[0].widgets`, never parse or lay out by hand:
+`normalizeWidget(w)` (deep-parses `Configuration`/`DataSource`, hoists legacy `isTask`/`formId`) ·
+`gridWidgets(ws)` · `resolveDashboardLayout(ws)` + `gridHeight(h)` (60-col grid, legacy ×5) ·
+`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.
+
+## Authoring a data source
+
+```tsx
+import { formSource, taskSource, field, taskField, groupBy, aggregate, derive, where, pivot } from "@zestl/zvolv-widgets";
+
+const region  = field("Region",  "DROP_DOWN");       // use the REAL element type
+const revenue = field("Revenue", "INPUT_CURRENCY");
+
+formSource(1042, [region, revenue]);                  // raw rows (tables, lists)
+formSource(1042, [region, revenue], {                 // grouped (charts)
+  pivot: pivot({
+    rows: [groupBy(region)],
+    summary: [aggregate(revenue, "sum")],             // sum avg min max count value_count cardinality
+    postOperations: [derive("Share", "PERCENT", ["Revenue", "Total"])],  // ADD SUB MUL DIV PERCENT; order matters
+  }),
+});
+taskSource([taskField("Status"), taskField("Priority")]);   // tasks index, no formId
+
+field("Status", "DROP_DOWN", { filter: where("IN", "Open") });  // baked-in author filter, always applied
+```
+
+Element type → ES type: `INPUT_NUMBER`/`INPUT_CURRENCY`/`INPUT_PERCENT` → FLOAT · `FORM_SEARCH`/`INPUT_TAG` → ARRAY · `CHECK_BOX` → BOOLEAN · else STRING.
+
+## Writing configuration
+
+```tsx
+import { defineConfig, type ChartConfig, type KpiConfig, type TableConfig } from "@zestl/zvolv-widgets";
+
+const chart = defineConfig<ChartConfig>({
+  title: "Revenue by region", template: "horizontal",
+  series: [{ name: "Revenue", valueField: "Revenue", argumentField: "Region" }],
+  axis: { valueAxis: { valueFormat: "currency" } }, legends: { show: false },
+  showWidgetFilter: true,
+});
+const table = defineConfig<TableConfig>({
+  title: "Deals", showSearchbar: true, showColumnFilter: true,
+  columns: [{ key: "Region", header: "Region" }, { key: "Revenue", header: "Revenue", kind: "number" }],
+});
+const kpi = defineConfig<KpiConfig>({
+  contents: [{ title: "Orders", dataPoint: "Orders", template: "trend", targetPoint: "Target", deltaMode: "percent" }],
+});
+```
+
+Schemas: `ChartConfig` `KpiConfig` `TableConfig` `CollectionConfig` `TemporalConfig` `StepperConfig` `GaugeConfig` `HeatMapConfig` `RankingConfig` `TreeConfig` `MapConfig` `HtmlConfig` `IframeConfig` `ActionConfig` `TabConfig` `FormConfig` `FilterPanelConfig`.
+Shared chrome keys: `title` `description` `hideHeader` `customMessage` `enableFullScreen` `enableRefreshButtons` `bgColor` `template` `style` `showSearchbar` `showWidgetFilter` `showColumnFilter` `enableSort` `searchPlaceholder`.
+Temporal configs keep the zvolv-web spellings `projectTitle` `taskTitle` `taskStatus` `startDate` `endDate`.
+KPI templates: `standard` `trend` `comparison` `progress` `financial` `status` `chart` `hero_chart` `icon`.
+
+## Widget catalogue and `render` args
+
+| Family | Components | `render` args |
+| --- | --- | --- |
+| KPI | `KpiWidget` | templates get `{ vm, index }`. `vm` is fully resolved; never read `vm.raw` |
+| Charts | `BarChartWidget` `LineChartWidget` `AreaChartWidget` `PieChartWidget` `DoughnutChartWidget` `ScatterChartWidget` | `{ rows, xKey, series, colorFor, toLabel, template, config, tokens, meta }` |
+| Ranking | `RankingBarWidget` | `{ rows: {rank,label,value,ratio}[], max }` |
+| Gauge | `GaugeMeterWidget` | `{ value, min, max, ratio, color, band }` |
+| Heat map | `HeatMapWidget` | `{ cells: {zone,count,color,band}[], grid }` |
+| Tables | `DashboardTableWidget` `DatabaseTableWidget` `TaskTrackerTableWidget` `ChildTableWidget` `PivotGridWidget` | `{ rows, columns, renderCell, toLabel, interactions, headerControls(col), getColumnOptions(key), enableSort, showColumnFilter, mode }` |
+| Collections | `CardListWidget` `ActivityFeedWidget` `EntityGalleryWidget` `GridCardWidget` `CarouselWidget` `BannerWidget` | `{ items: CollectionItem[] }` |
+| Temporal | `TimelineWidget` `GanttChartWidget` `CalendarWidget` `MeetingSchedulerWidget` | `{ events, range, lanes }` |
+| Stepper | `StepperWidget` | `{ steps, currentIndex }` |
+| Display | `HtmlWidget` `RawHtmlWidget` `IframeWidget` `GoogleMapWidget` `TreeWidget` `ActionCardWidget` | see types |
+| Containers | `TabWidget` `FormWidget` `FilterPanelWidget` `ZaiChatWidget` | see types |
+
+**`render` is REQUIRED** for `ZaiChatWidget`, `GoogleMapWidget` and `HtmlWidget` markup. `FormWidget` renders `<ZvolvForm>` by default (see Forms). The package never calls `dangerouslySetInnerHTML`.
+
+In chart `render`, always use `xKey` and `series[].valueField` from the args, pass axis and user values through `toLabel`, and colour with `colorFor(i, s)`.
+In a custom table `render`, put `headerControls(column)` in each header cell to keep the sort and filter controls. `rows` are already searched, filtered and sorted.
+
+## Styling, cheapest first
+
+1. Tokens: `<ZvolvThemeProvider tokens={{ colors, typography, widget, surfaces, overrides, widgetDefaults }}>`. `widgetDefaults` layers **under** each widget's own config.
+2. `render` prop per widget.
+3. `<TemplateProvider templates={{ "KPI_CARD:standard": MyCard, "BAR_CHART:*": MyBars }}>`.
+4. Interaction slots for the controls.
+
+## Headless
+
+```tsx
+const ix = useWidgetInteractions({ defaultSort: { key: "Revenue", direction: "desc" } });
+const { rows, sourceRows, state, meta, refresh } = useWidgetData({
+  dataSource, configurations, widgetType: "TABLE",
+  search: ix.search, columnFilters: ix.columnFilters, sort: ix.sort, widgetFilters: ix.widgetFilters,
+});
+```
+
+Also: `useInteractiveWidgetData`, `useKpiContents`, `useCollectionItems`, `useTemporalEvents`, `useTableColumns`.
+
+## Previewing without a backend
+
+`createMockRuntime({ rows?, delay?, onQuery? })` applies filters, search and sort to its rows, so controls visibly work. It does not aggregate pivots.
+
+## Forms
+
+Forms work like widgets: Zvolv owns the behaviour and you own the look.
+
+- Render with `<ZvolvForm formId … />`, or let a `FORM` / `FORM_WIDGET` dashboard widget do it.
+- Style every field once with `<FormKitSlot.Provider value={{ field, form, status, grid }}>`. Switch on `field.kind`, and use `useFieldOptions`, `useFileField`, `useSheetField` and `form.runAction` for behaviour. Never re-implement rules, formulas, lookups or the submit body.
+- Sheet row formulas: call `useSheetField().updateRow` — it recalculates formula cells. For a debug/inspector panel use `useFormInspector(form)` (rules, filters, validation, formulas, defaults, payload).
+- Write formulas with `{Label}` references (`MUL({Qty}, {Price})`). The submission API re-evaluates formulas and reads bare labels as 0, so `MUL(Qty, Price)` is rejected with "Evaluated value \"0\" … do not match". Check with `isServerSafeFormula`.
+- Nested layout: for `section`, `tabs` and `steps` kinds, render `<FormFields form={form} fields={form.childrenOf(field)} />`.
+- Kind `"trials"` (ABA widgets) → draw with `useTrialField`; action `variant === "dropdown"` (ACTION_DROPDOWN) → a select of `field.options`, call `form.runAction(field, label)`.
+- Lookup / people controls must call `o.onFocus()` on focus — options load on focus (zvolv-web / ZAI parity). Single vs multi is `maxResults`; respect `o.atLimit`; INPUT_TAG free text via `o.addFreeTag`. ExtraLabels auto-fill is opt-in (`autofillExtraLabels`); prefer FETCH_OPTIONS_FILTERS. Draw kind `"onbehalf"` read-only with `field.displayText`; checkbox `variant === "switch"`; sheets honour `canAdd` / `canDelete` / `limitMessage`. SAVE_SUBMISSION and other open-UI actions need `onAction`.
+- Triage / show-hide-mandatory rules follow ZAI-Dashboard: `properties.triage` overrides `dependencies`; array values must match the selection exactly; a matching rule beats a non-matching one; hiding keeps the value; `field.error` appears only after submit and clears when the field changes. Don't add reset-on-hide or live "touched" errors in the app.
+- Dependent lookups (`FETCH_OPTIONS_FILTERS`) use the platform shape: the rule sits **on the dependent lookup** — `{ type: "FETCH_OPTIONS_FILTERS", elementId: <source field>, masterField: <label on its source form> }`. `useFieldOptions` filters by the source's value, reports `waitingFor` until it is set, clears the selection when it changes, and auto-selects when exactly one row matches. Build it with `cascade(source, target, masterField)`.
+
+When asked to build a dashboard that captures data:
+1. Create the form: build the payload with `el.*` / `when` / `defineForm`, then call `create_form`.
+2. Re-read it with `get_form_by_id` to confirm elementIds and rules.
+3. Add it with `formWidget({ formId, title, layout })` → `create_widget`, sized to its fields. An `ACTION_CARD` with `actionType: NEW_SUBMISSION` also opens the form in the host.
+
+`create_form` quirks:
+- Formulas must use bare, single-word labels: `MUL(Quantity, Rate)`.
+- Never use `AVG`: every write to the form 502s. Use `DIVI(ADD(...), n)`.
+- Required SIGNATURE fields are enforced even with `skipValidations`. Seed data needs a data-URL value.
+- `width` is a percentage, placed at the element root and in `attributes.Width`.
+- Rules go on the driving field; each target starts `hidden: true`.
+
+## 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.
+- [ ] No fetch, query, `.filter()` or `.sort()` over widget rows in your code. Interactions go through props or slots.
+- [ ] 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.