@sparkerp/plugin-sdk 0.1.0

package/bundle/docs/guides/add-a-custom-block.md

@@ -0,0 +1,225 @@
+---
+title: Add a custom block (a "widget" you build yourself)
+audience: tenant
+---
+
+# Add a custom block (a "widget" you build yourself)
+
+## What you're doing
+
+The one UI unit on this platform is a **Block** — every page is a tree of
+blocks (`core.grid`, `core.text-input`, `core.button`, ...), rendered by a
+generic engine that knows nothing about any specific block's internals. This
+guide adds a NEW block type of your own — real React, real `useState`/hooks,
+real data — that plugs into that same tree.
+
+This is narrower than a full [Code Plugin with custom Java](./build-a-code-plugin.md):
+you don't need a `Plugin` subclass, a Java extension, or any backend code at
+all. A custom block can be pure frontend, reading data through the platform's
+existing generic query engine — reach for this guide alone whenever the need
+is "a bespoke piece of UI with real component state," and only add the Java
+half if the data or logic it needs genuinely can't come from an existing
+endpoint (see that guide's "When to reach for this" table).
+
+## How it's different from a page or a full Code Plugin
+
+| | An ordinary page | **A custom block (this guide)** | A full [Code Plugin](./build-a-code-plugin.md) |
+| --- | --- | --- | --- |
+| Built from | Existing block types, composed in JSON | Your OWN new block type | Your own block type + your own Java |
+| Where it can be used | That one page | **Any page, in any app**, once registered | Any page, in any app |
+| Needs React/hooks? | No | Yes | Yes |
+| Needs Java? | No | No | Only if the data/logic needs it |
+
+## The two-part registration seam
+
+A custom block is two things, registered together:
+
+1. **The block's data/logic contract** — a `BlockDefinition` (its property
+   surface: names, types, designer config) plus `BlockLogic` (a `render()`
+   function), admitted via `@erp/block-engine`'s
+   `registry.registerExternal({ definition, logic })` — the IDENTICAL
+   validation path every core block (`core.grid`, `core.button`, ...) goes
+   through. Nothing about this seam is second-class.
+2. **The actual React component** — registered via
+   `@erp/block-adapter-mui`'s `registerCustomRenderer(pluginKind, Component)`.
+   Your `render()` function emits the reserved `"custom"` render-node kind
+   carrying a `pluginKind` string; the adapter looks that string up in this
+   registry and mounts your real component. No match → a neutral placeholder,
+   never a crash.
+
+Both calls are usually wrapped in one `install*(registry)` function, run once
+when your plugin's frontend bundle loads.
+
+## The complete example
+
+This platform's own real, already-shipped example —
+`frontend/packages/erp-code-plugin-demo/src/riskScoreBlock.ts` +
+`RiskScoreCard.tsx` + `register.ts` — is genuinely runnable, not a snippet.
+Read alongside this guide:
+
+**`riskScoreBlock.ts`** — the `BlockDefinition`:
+
+```ts
+import type { BlockDefinition, BlockIO, BlockLogic, RenderNode } from "@erp/block-engine";
+import { node } from "@erp/block-engine";
+
+export const PLUGIN_KIND = "erp-code-plugin-demo.risk-score-card";
+
+export const riskScoreCardDefinition: BlockDefinition = {
+  contractVersion: 1,
+  publisher: "erp-code-plugin-demo",
+  permissions: { visible: true, enabled: true, masked: true },
+  type: "erp-code-plugin-demo.risk-score-card",
+  version: "1.0.0",
+  properties: [
+    {
+      name: "entityName",
+      type: "string",
+      required: true,
+      sources: ["static"],
+      designer: { group: "data", editor: "text", labelKey: "erpCodePluginDemo.riskScoreCard.property.entityName" },
+    },
+    {
+      name: "titleKey",
+      type: "string",
+      sources: ["static"],
+      default: "erpCodePluginDemo.riskScoreCard.title",
+      designer: { group: "content", editor: "text", labelKey: "erpCodePluginDemo.riskScoreCard.property.titleKey" },
+    },
+  ],
+  a11y: { role: "region", labelFrom: "i18n:erpCodePluginDemo.riskScoreCard.title" },
+  designer: {
+    displayNameKey: "erpCodePluginDemo.riskScoreCard.displayName",
+    descriptionKey: "erpCodePluginDemo.riskScoreCard.description",
+    icon: "insights",
+    category: "display",
+    allowedTargets: ["page", "dashboard"],
+    propertyGroups: [
+      { id: "content", titleKey: "core.designer.group.content" },
+      { id: "data", titleKey: "core.designer.group.data" },
+    ],
+    preview: { kind: "text" },
+  },
+  events: [],
+};
+
+export const riskScoreCardLogic: BlockLogic = {
+  render(io: BlockIO): RenderNode {
+    return node("custom", io.instanceId, {
+      props: { pluginKind: PLUGIN_KIND, entityName: io.props["entityName"], titleKey: io.props["titleKey"] },
+    });
+  },
+};
+```
+
+**`RiskScoreCard.tsx`** — the real component (trimmed; see the file for the
+full version):
+
+```tsx
+import { useMemo, useState } from "react";
+import { Card, CardContent, Chip, Stack, Typography } from "@mui/material";
+import type { RenderNode } from "@erp/block-engine";
+import { useERPQuery } from "@erp/data";
+
+function scoreFor(rows: Array<Record<string, unknown>>) {
+  const activeCount = rows.filter((r) => r["active"] === true).length;
+  const score = rows.length === 0 ? 0 : Math.round((activeCount / rows.length) * 100);
+  return { score, band: score >= 70 ? "low" : score >= 40 ? "medium" : "high" } as const;
+}
+
+export function RiskScoreCard({ n }: { n: RenderNode }) {
+  const entityName = n.props["entityName"] as string;
+  const [expanded, setExpanded] = useState(false);           // real component state
+  const { rows, loading, error } = useERPQuery({ entity: entityName, pageSize: 25 }); // real data
+  const { score, band } = useMemo(() => scoreFor(rows), [rows]);
+
+  return (
+    <Card variant="outlined">
+      <CardContent>
+        <Typography variant="subtitle1">{String(n.props["titleKey"])}</Typography>
+        {!loading && !error && (
+          <Stack direction="row" spacing={1}>
+            <Typography variant="h4">{score}</Typography>
+            <Chip label={band} onClick={() => setExpanded((v) => !v)} />
+          </Stack>
+        )}
+      </CardContent>
+    </Card>
+  );
+}
+```
+
+**`register.ts`** — both halves, together:
+
+```ts
+import type { BlockRegistry } from "@erp/block-engine";
+import { registerCustomRenderer } from "@erp/block-adapter-mui";
+import { riskScoreCardDefinition, riskScoreCardLogic, PLUGIN_KIND } from "./riskScoreBlock";
+import { RiskScoreCard } from "./RiskScoreCard";
+
+export function installRiskScoreCardPlugin(registry: BlockRegistry) {
+  const result = registry.registerExternal({ definition: riskScoreCardDefinition, logic: riskScoreCardLogic });
+  registerCustomRenderer(PLUGIN_KIND, RiskScoreCard);
+  return result;
+}
+```
+
+### Build and verify it yourself
+
+This is a real, already-shipped workspace package — run its own checks
+directly, no scaffolding needed:
+
+```bash
+cd frontend/packages/erp-code-plugin-demo
+pnpm typecheck
+pnpm test          # real jsdom mount of this exact block, see riskScoreCard.e2e.test.tsx
+pnpm build          # tsup — produces dist/index.js
+```
+
+## Property surface → the designer's config panel
+
+Each entry in `BlockDefinition.properties` becomes one field in the page
+designer's property panel for an instance of your block, once it's dropped
+onto a canvas:
+
+- `name`/`type`/`required` — the property's identity and validation.
+- `designer.group` — which tab/section of the panel it appears under
+  (`riskScoreCardDefinition` declares two: `content`, `data`).
+- `designer.editor` — which input control renders it (`text` here; other
+  block types use `select`, `checkbox`, `binding-picker`, etc.).
+- `designer.labelKey` — the i18n key for the field's label.
+- `sources: ["static"]` — v0 property values are static only, same static-vs-
+  binding distinction the [Code Plugin compile-to-JSON path](./build-a-code-plugin.md)
+  documents.
+
+## Why this matters: cross-app reusability
+
+Once `installRiskScoreCardPlugin` runs against a host's `BlockRegistry`, the
+block type `erp-code-plugin-demo.risk-score-card` is registered platform-wide
+for that session — it shows up in the page designer's block palette and can
+be dragged onto **any page, in any app**, not only pages belonging to the
+plugin that registered it. That's the actual point of building a custom
+block instead of a full custom page: you write the component once, and every
+other page author on the tenant gets to use it declaratively, the same way
+they use `core.grid` or `core.button`.
+
+## Getting it onto a live tenant
+
+A registered block only exists in whatever process called `registerExternal`
+— shipping it to a real tenant is the same `frontendBundle` +
+`erp plugin publish-frontend` mechanism [the Code Plugin guide](./build-a-code-plugin.md#the-parts-that-differ-from-a-pure-json-plugin)
+describes. If your block needs no Java at all (as `RiskScoreCard` doesn't —
+it reads through the generic query engine), you skip that guide's Java
+sections entirely and package a pure-JSON `.spk` (`mainClass: null`) whose
+`frontendBundle` points at your component's compiled browser bundle.
+
+## What this guide does NOT cover
+
+- A block whose data comes from your OWN Java code (a plugin-owned REST
+  route, not the generic query engine) — see
+  [Build a plugin with custom React + Java code](./build-a-code-plugin.md).
+- Data binding (`{source: "binding"}`) — v0 property values are static only;
+  see that guide's own "not supported" boundary in `ai/patterns/code-plugin-sdk.md`.
+- Wiring your block into Studio's design-time preview surfaces yourself —
+  already real and automatic once `frontendBundle` is set (the dynamic
+  loader wires designer previews and the live page host the same way).

package/bundle/docs/guides/add-a-data-provider.md

@@ -0,0 +1,216 @@
+---
+title: Add a data provider, data view, or data service
+audience: tenant
+---
+
+# Add a data provider, data view, or data service
+
+## What you're doing
+
+Three related artifacts feed data to your pages. They sound alike; here's the
+difference in one line each:
+
+| Artifact | Folder | What it is | Use it for |
+| --- | --- | --- | --- |
+| **Data Provider** | `metadata/provider/` | a name → REST base path mapping | the thing a grid's `metadata.dataSource` points at |
+| **Data View** | `metadata/data_view/` | a declared SQL join over physical tables, read-only | id/label option lists, multi-table reads |
+| **Data Service** | `metadata/data_service/` | a parameterized query: `count`, `search`, `get`, or `composite` | KPI counts, typeahead lookups, dashboard fan-outs |
+
+Rule of thumb: **prefer a Data View or Data Service over hand-writing a REST
+endpoint.** You never write a controller.
+
+## Data Provider — the complete example
+
+Covered in [Wire a page's data](./wire-a-pages-data.md). For an entity you own it
+is always this, with the name and entity swapped:
+
+```json
+{
+  "name": "oeq-checkout-provider",
+  "description": "Data Provider for oeq_checkout (grid + CRUD).",
+  "definition": {
+    "kind": "rest",
+    "connectionRef": "self",
+    "basePath": "/api/v1/entities/oeq_checkout/records",
+    "supports": ["search", "get", "create", "update"]
+  },
+  "metadata": {}, "modules": []
+}
+```
+
+## Data View — the complete example
+
+`spk-assembly/metadata/data_view/oeq-category-select-options-view.json` —
+[real file](../tutorial/example-plugin/spk-assembly/metadata/data_view/oeq-category-select-options-view.json).
+It produces `{ value, label }` pairs for a category picker:
+
+```json
+{
+  "name": "oeq-category-select-options-view",
+  "description": "oeq_category id/label pairs for pickers.",
+  "definition": {
+    "source": { "table": "oeq_category", "alias": "t", "excludeDeleted": false, "schema": "erp_core" },
+    "joins": [],
+    "fields": [ { "ref": "t.id", "outputName": "value" } ],
+    "calculatedFields": [
+      { "outputName": "label", "expression": { "op": "concat", "args": [
+        { "op": "field", "fieldRef": "t.category_code" },
+        { "op": "literal", "literalValue": " - " },
+        { "op": "coalesce", "args": [ { "op": "field", "fieldRef": "t.category_name" }, { "op": "literal", "literalValue": "" } ] }
+      ] } }
+    ],
+    "filter": null, "groupBy": [], "aggregations": [],
+    "sort": [ { "ref": "t.id", "descending": true } ],
+    "pagination": { "defaultPageSize": 200, "maxPageSize": 500 },
+    "permissionKey": null
+  },
+  "metadata": {}, "modules": []
+}
+```
+
+### Line by line
+
+- **`source`** — the driving table, its alias, and its **`schema`** (must match
+  your plugin's `schemaName`).
+- **`fields`** — plain column selections, `{ ref, outputName }`.
+- **`calculatedFields`** — expression columns. The expression tree ops you'll use:
+  `field` (a column), `literal` (a constant), `concat`, `coalesce`.
+- **`sort` / `pagination`** — read defaults.
+- A picker view **must** output columns literally named `value` and `label`.
+
+## Data Service — the complete examples
+
+### A `count` (one number)
+
+`oeq-equipment-count-available.json` —
+[real file](../tutorial/example-plugin/spk-assembly/metadata/data_service/oeq-equipment-count-available.json):
+
+```json
+{
+  "name": "oeq-equipment-count-available",
+  "description": "Available equipment.",
+  "definition": {
+    "operation": "count",
+    "source": { "kind": "entity", "entityName": "oeq_equipment" },
+    "filters": [ { "field": "status", "operator": "eq", "value": "AVAILABLE" } ],
+    "parameters": []
+  },
+  "metadata": {}, "modules": []
+}
+```
+
+`POST /api/v1/data-services/oeq-equipment-count-available/execute` returns
+`{ "value": 3 }`. Bind it as `${out.value}`.
+
+### A `search` (typeahead over a Data View)
+
+`oeq-category-search.json` —
+[real file](../tutorial/example-plugin/spk-assembly/metadata/data_service/oeq-category-search.json):
+
+```json
+{
+  "name": "oeq-category-search",
+  "description": "Typeahead category search for the category lookup field.",
+  "definition": {
+    "operation": "search",
+    "source": { "kind": "dataView", "dataViewName": "oeq-category-select-options-view" },
+    "filters": [ { "field": "t.category_name", "operator": "contains", "value": "${param.search}" } ],
+    "parameters": [ { "name": "search", "type": "string" } ]
+  },
+  "metadata": {}, "modules": []
+}
+```
+
+A `core.lookup` block points its `optionsSourceKey` at
+`"oeq-category-search"`. See
+[the lookup recipe](../recipes/related-record-lookup-field.md).
+
+### A `composite` (KPI fan-out)
+
+`oeq-equipment-kpis.json` —
+[real file](../tutorial/example-plugin/spk-assembly/metadata/data_service/oeq-equipment-kpis.json):
+
+```json
+{
+  "name": "oeq-equipment-kpis",
+  "description": "Composite KPI fan-out for the Equipment Register page.",
+  "definition": {
+    "operation": "composite",
+    "source": { "kind": "entity", "entityName": "oeq_equipment" },
+    "steps": [
+      { "as": "total",     "service": "oeq-equipment-count-total",     "parameters": {} },
+      { "as": "available", "service": "oeq-equipment-count-available", "parameters": {} },
+      { "as": "assigned",  "service": "oeq-equipment-count-assigned",  "parameters": {} }
+    ]
+  },
+  "metadata": {}, "modules": []
+}
+```
+
+`POST .../oeq-equipment-kpis/execute` returns
+`{ "results": { "total": { "value": 12 }, "available": { "value": 8 }, "assigned": { "value": 4 } } }`.
+Bind each as `${out.results.total.value}`. **Verified live** against the tutorial
+module.
+
+## The `/execute` wire-shape trap
+
+A Data Service that declares `parameters` must be called with the arguments
+**nested one level deeper** than a normal entity call:
+
+```json
+{ "params": { "parameters": { "search": "lap" } } }
+```
+
+not `{ "params": { "search": "lap" } }`. A `core.lookup` block does this for you;
+a hand-written `callApi` action must nest it.
+
+## Response envelope by operation
+
+| `operation` | `/execute` returns | bind as |
+| --- | --- | --- |
+| `count` | `{ "value": <n> }` | `${out.value}` |
+| `search` / `get` | `{ "items": [...] }` or `{ "records": [...] }` | check a shipped example |
+| `composite` | `{ "results": { "<step.as>": <that step's envelope> } }` | `${out.results.<as>.value}` |
+
+## Ground yourself first
+
+```bash
+erp schema pull data-service-definition
+erp schema pull data-view-definition
+erp examples search employee-search --kind data-service
+```
+
+## How to verify it worked
+
+```bash
+erp schema validate spk-assembly/metadata/data_service/oeq-equipment-kpis.json --schema data-service-definition
+```
+
+```
+OK — ... matches schema "data-service-definition"
+```
+
+After publishing:
+
+```bash
+erp api post "/api/v1/data-services/oeq-equipment-kpis/execute" --body "{}"
+```
+
+```json
+{ "results": { "total": { "value": 0 }, "available": { "value": 0 }, "assigned": { "value": 0 } } }
+```
+
+## Common mistakes
+
+| Symptom | Cause | Fix |
+| --- | --- | --- |
+| lookup returns nothing | Data View doesn't output columns named `value`/`label` | rename the outputs |
+| `/execute` 400s on a parameterized service | argument not nested under `parameters` | `{ "params": { "parameters": { ... } } }` |
+| KPI card shows `undefined` | bound `${out.value}` on a composite | composite is `${out.results.<step>.value}` |
+| Data View returns 0 rows | `source.schema` doesn't match where the table lives | set it to your plugin's `schemaName` |
+
+## What to read next
+
+- [Add a KPI or aggregation](./add-a-kpi.md)
+- [Add a create / edit form](./add-a-create-edit-form.md) (lookups)
+- Recipe: [searchable related-record lookup field](../recipes/related-record-lookup-field.md)

package/bundle/docs/guides/add-a-kpi.md

@@ -0,0 +1,154 @@
+---
+title: Add a KPI or aggregation
+audience: tenant
+---
+
+# Add a KPI or aggregation
+
+## What you're doing
+
+Putting a number on a page — "12 total", "8 available" — computed server-side.
+The building block is a **Data Service** with `operation: "count"`. A page's
+mount loader calls it and drops the result into page state; a `core.kpi-card`
+displays it.
+
+For a row of several KPIs you wrap the counts in one `composite` Data Service so
+the page makes **one** call, not five.
+
+## The complete example
+
+### One count per metric
+
+`spk-assembly/metadata/data_service/oeq-equipment-count-total.json`:
+
+```json
+{
+  "name": "oeq-equipment-count-total",
+  "description": "Total equipment.",
+  "definition": {
+    "operation": "count",
+    "source": { "kind": "entity", "entityName": "oeq_equipment" },
+    "filters": [],
+    "parameters": []
+  },
+  "metadata": {}, "modules": []
+}
+```
+
+`oeq-equipment-count-available.json` is the same with a filter:
+
+```json
+"filters": [ { "field": "status", "operator": "eq", "value": "AVAILABLE" } ]
+```
+
+> `filters` on a `count` is a list of `{ field, operator, value }`. Operators:
+> `eq`, `neq`, `gt`, `gte`, `lt`, `lte`, `contains`. For "no groupBy, just a
+> filtered number" this is the whole recipe.
+
+### The composite wrapper
+
+`oeq-equipment-kpis.json`:
+
+```json
+{
+  "name": "oeq-equipment-kpis",
+  "description": "Composite KPI fan-out for the Equipment Register page.",
+  "definition": {
+    "operation": "composite",
+    "source": { "kind": "entity", "entityName": "oeq_equipment" },
+    "steps": [
+      { "as": "total",     "service": "oeq-equipment-count-total",     "parameters": {} },
+      { "as": "available", "service": "oeq-equipment-count-available", "parameters": {} },
+      { "as": "assigned",  "service": "oeq-equipment-count-assigned",  "parameters": {} }
+    ]
+  },
+  "metadata": {}, "modules": []
+}
+```
+
+### The page mount loader
+
+```json
+"events": { "mounted": { "source": "action-chain", "actions": [
+  { "id": "a0", "order": 0, "type": "callApi",
+    "config": { "connectionRef": "self", "path": "/api/v1/data-services/oeq-equipment-kpis/execute", "httpMethod": "POST", "params": {} },
+    "output": "kpi" },
+  { "id": "a1", "order": 1, "type": "setValue", "config": { "field": "page.kpiTotal",     "value": "${kpi.results.total.value}" } },
+  { "id": "a2", "order": 2, "type": "setValue", "config": { "field": "page.kpiAvailable", "value": "${kpi.results.available.value}" } },
+  { "id": "a3", "order": 3, "type": "setValue", "config": { "field": "page.kpiAssigned",  "value": "${kpi.results.assigned.value}" } }
+] } }
+```
+
+### The KPI card
+
+```json
+{
+  "blockType": "core.kpi-card",
+  "properties": {
+    "value":    { "source": "binding", "binding": { "scope": "page", "key": "kpiTotal" } },
+    "labelKey": { "source": "static", "value": "office-equipment.equipment-register.kpi.total" },
+    "format":   { "source": "static", "value": "number" },
+    "colorToken": { "source": "static", "value": "primary" },
+    "icon":     { "source": "static", "value": "devices" }
+  }
+}
+```
+
+## Line by line — the two traps
+
+1. **The `outputName: "value"` / no-groupBy pattern.** A `count` returns exactly
+   `{ "value": <number> }`. You do **not** get `.total` (that's the pagination
+   envelope of the entity list endpoint, unrelated). A `composite` nests each
+   step's envelope under `results.<step.as>`, so a composite count step is
+   `${out.results.<as>.value}`.
+
+   | you called | you bind |
+   | --- | --- |
+   | a bare `count` service | `${out.value}` |
+   | a `composite` of counts | `${out.results.<step>.value}` |
+
+2. **Call once on mount, store in page state.** The KPI card binds a page-state
+   key, not the API directly. The mount loader is a hidden `core.container`; see
+   [Build a page](./build-a-page.md).
+
+## Recomputing after a write
+
+Add the same `callApi` + `setValue` steps to the end of your Save action chain,
+so creating a row updates the counts without a page reload.
+
+## How to verify it worked
+
+```bash
+erp api post "/api/v1/data-services/oeq-equipment-kpis/execute" --body "{}"
+```
+
+Actual response from the tutorial module right after install (no rows yet):
+
+```json
+{
+  "value": null, "rows": null, "total": null, "record": null,
+  "results": {
+    "total":     { "value": 0 },
+    "available": { "value": 0 },
+    "assigned":  { "value": 0 }
+  }
+}
+```
+
+The top-level `value`/`rows`/`total` are always-present nulls for a composite —
+ignore them, read `results`.
+
+## Common mistakes
+
+| Symptom | Cause | Fix |
+| --- | --- | --- |
+| card shows `undefined` | bound `${out.value}` on a composite | use `${out.results.<step>.value}` |
+| card shows `0` when there is data | count filter value doesn't match the enum casing | check `typeParams.enumValues` |
+| every KPI is one HTTP call | separate `callApi` per count on mount | wrap them in one `composite` |
+| card never updates after a save | KPI steps not appended to the Save chain | append `callApi` + `setValue` there too |
+
+## What to read next
+
+- [Add a data provider, data view, or data service](./add-a-data-provider.md)
+- [Add a cross-row aggregation job](./add-an-aggregation-job.md) — for rollups stored back into a table
+- Recipe: [KPI dashboard page](../recipes/kpi-dashboard-page.md)