api_binding_ui 3.0.0 → 3.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "api_binding_ui",
-  "version": "3.0.0",
+  "version": "3.2.0",
   "description": "Design-time API binding: register screen components, bind them to documented APIs in a studio, and generate plain React Query hooks over an Orval client. Nothing ships in the app.",
   "type": "module",
   "main": "./dist/index.js",
@@ -16,7 +16,11 @@
       "import": "./dist/studio/index.js"
     },
     "./studio.css": "./dist/studio/index.css",
-    "./package.json": "./package.json"
+    "./package.json": "./package.json",
+    "./vite": {
+      "types": "./dist/vite/plugin.d.ts",
+      "import": "./dist/vite.js"
+    }
   },
   "files": [
     "dist",
@@ -30,7 +34,7 @@
   "scripts": {
     "dev": "bun run build:app && node dist/cli.js studio src/dev/sample/bindings.json",
     "build:app": "rm -rf dist/app && bun build ./index.html --outdir dist/app --minify",
-    "build": "rm -rf dist && bun build src/index.ts src/studio/index.ts --outdir dist --root src --target browser --splitting --sourcemap=linked --external react --external react-dom --external react/jsx-runtime --external yaml && bun build src/cli/cli.ts --outfile dist/cli.js --target node --external yaml --banner '#!/usr/bin/env node' && bun run build:app && node ./node_modules/typescript/bin/tsc -p tsconfig.build.json",
+    "build": "rm -rf dist && bun build src/index.ts src/studio/index.ts --outdir dist --root src --target browser --splitting --sourcemap=linked --external react --external react-dom --external react/jsx-runtime --external yaml && bun build src/cli/cli.ts --outfile dist/cli.js --target node --external yaml --banner '#!/usr/bin/env node' && bun build src/vite/plugin.ts --outfile dist/vite.js --target node --external yaml && bun build src/overlay/main.ts --outfile dist/overlay.js --target browser --minify && bun run build:app && node ./node_modules/typescript/bin/tsc -p tsconfig.build.json",
     "typecheck": "node ./node_modules/typescript/bin/tsc --noEmit -p tsconfig.json",
     "test": "bun test",
     "prepublishOnly": "bun run typecheck && bun test && bun run build"

package/spec/FRAMEWORK.md

@@ -1,176 +1,178 @@
-# API Binding Framework — v3
-
-Normative types: [`contract.ts`](../src/framework/contract.ts).
-
-The framework connects **UI components** to **documented API operations** at design time and turns the result into **plain code**. Everything about binding lives in one file, `bindings.json`. After design time the app holds only ordinary React Query hooks over an Orval client; no framework code, runtime or manifest ships.
-
----
-
-## 1. Principles
-
-1. **Nothing concrete in the framework.** Component kinds, products, operations and fields arrive as data: kinds and the registry in the bindings file, operations from the OpenAPI docs.
-2. **The API docs are the only source of operations.** No local hooks, hardcoded option lists or free-text overrides.
-3. **UI first.** The unit of work is a screen and its components; APIs attach to component slots.
-4. **One file.** Kinds, screens, components, bindings and output settings are all in `bindings.json`.
-5. **No trace at run time.** The generator writes plain hooks; the app never imports this package.
-6. **Deterministic.** The same file and docs always produce the same code. Generated files carry an `@generated` mark and are never edited by hand.
-
----
-
-## 2. The pieces
-
-```
-OpenAPI docs ──► Orval ──────────────► src/api/generated   (typed client)
-     │
-     └──► api-binding studio ◄──► bindings.json ──► api-binding generate ──► src/api/screens (one hook per screen)
-                                                                               │
-                                          app components ── use<Screen>Api(state) ┘
-```
-
-| Piece | What it is | Owned by |
-|---|---|---|
-| Kinds | A component kind's slots, with JSON Schema shapes | Design system, in `bindings.json` → `kinds` |
-| Screens and components | Every screen and component instance, by id | The app, in `bindings.json` |
-| Bindings | Which operation or value feeds each slot | Designers in the studio, reviewed by engineers |
-| Orval client | Typed functions per operation | Generated by Orval from the same docs |
-| Screen hooks | `use<Screen>Api(state)` per screen | Generated by `api-binding generate` |
-
----
-
-## 3. Ids
-
-One namespace for screens and components, used everywhere: in `componentId` props, in the file and in expressions.
-
-```
-<product>.<screen>[.<sub-screen>…].<component>[.<part>…]
-collections.worklist                         screen
-collections.worklist.add-notes               sub-screen (a dialog over the worklist)
-collections.worklist.grid                    component on collections.worklist
-collections.worklist.grid.column.customer-name
-collections.worklist.grid.row.add-notes
-collections.worklist.add-notes.notes-type    component on collections.worklist.add-notes
-```
-
-- Segments are lowercase kebab-case (`[a-z0-9-]`), joined by dots: `^[a-z][a-z0-9-]*(\.[a-z0-9-]+)+$`.
-- A component belongs to the **longest** registered screen id that prefixes it. A screen's parent is the longest other screen id that prefixes it. Navigation is built from this; there is no `path` or `parent` to maintain.
-- A component id may not equal a screen id (it would capture that screen's components).
-- Ids are stable: renaming one orphans its bindings. They never depend on labels.
-- In the app, each component gets `componentId="<id>"`; design-system components render it as `data-component-id`.
-
----
-
-## 4. Kinds and slots
-
-A kind declares slots with one of three **roles**:
-
-| Role | Meaning | Bound to |
-|---|---|---|
-| `consume` | The component needs data | An operation (request + response selection) or an expression |
-| `produce` | The component exposes data | Nothing; a source others read |
-| `trigger` | The component emits an event | Ordered API call steps, or "no API" |
-
-- `scope.parentSlot`: the slot is evaluated per item of the parent's slot (a cell in a row, an action on a row); `$item` is that item.
-- `feeds`: produce slots of the same component offered as request sources (paging, sorting).
-- `"$ref": "#slot/<id>"`: the same shape as that slot after binding (a grid's selection has the shape of its rows).
-
----
-
-## 5. The bindings file
-
-```jsonc
-{
-  "version": 3,
-  "openapi": "https://apidocs.example.com/index.yaml",   // or a path next to this file
-  "output": { "dir": "src/api/screens", "client": "@/api/generated" },
-  "kinds": [ /* ComponentDescriptor */ ],
-  "screens": [ { "id": "collections.worklist.add-notes", "label": "Add Notes",
-                 "context": [ { "id": "selection", "label": "Selected rows", "many": true,
-                                "shape": { "from": { "screen": "collections.worklist", "component": "collections.worklist.grid", "slot": "selection" } } } ] } ],
-  "components": [ { "id": "collections.worklist.add-notes.notes-type", "kind": "hr-ds/select", "label": "Notes Type" } ],
-  "bindings": [ /* SlotBinding */ ]
-}
-```
-
-| Slot role | Binding type | Contents |
-|---|---|---|
-| consume | `operation` | operation, request mapping (pointer → expression), response `select`, optional `map`, `load` |
-| consume | `expression` | one expression |
-| trigger | `steps` | ordered `call` steps; a step may run `forEach` over a list; `onError: stop \| continue` |
-| trigger | `none` | reviewed: this event calls no API |
-
-Only `confirmed` bindings are generated; drafts are reported as warnings. Bindings describe API calls only: opening, closing, navigation, toasts and reloads are app code.
-
----
-
-## 6. Expressions
-
-| Form | Resolves to |
-|---|---|
-| `<componentId>:<slot>[.path]` | A produce slot on the same screen, e.g. `collections.worklist.add-notes.subject:value` |
-| `<expr>[*].<path>` | A property of every item, as a list |
-| `$item[.path]` | The current item: a scoped slot's item, a `forEach` item, or the trigger's payload |
-| `$context.<id>[.path]` | A value declared in the screen's `context` |
-| `$steps.<stepId>.response[.path]` | The response of an earlier step |
-
-`:` ends a component id, so ids can contain dots. Nothing outside this grammar is valid.
-
----
-
-## 7. Generated code
-
-`api-binding generate` writes into `output.dir`:
-
-- `screen-helpers.ts`: the few helpers the hooks share (React Query only).
-- `<screen id>.ts` per screen: `<Screen>State`, `<Screen>Api` and `use<Screen>Api(state)`.
-- `index.ts`: re-exports.
-
-**The signature comes from the registry, the body from the bindings.** `<Screen>State` has one optional entry per component that produces values; `<Screen>Api` has one entry per consume and trigger slot. Changing bindings never changes either type, so call sites stay put. Adding or removing components does, and `tsc` points at every call site to update.
-
-| Slot | Returns | When unbound |
-|---|---|---|
-| consume | `Data<T>`: `{ bound, data, loading, error }` | `bound: false`; keep the UI's own value |
-| consume, scoped | `Cell<T>`: `{ bound, read(item) }` | `read` returns `undefined` |
-| trigger | `Action`: `{ bound, run(payload?), running, error }` | `run` resolves at once |
-
-- Queries call the Orval function for the operation: path params in path order, then the body, then the query params object, then fetch options (headers). A query is enabled only when every required input has a value; `load: { everySeconds }` polls.
-- Actions run steps in order. A failed call rejects `run` (`stop`) or is collected and rejected after the rest run (`continue`).
-- Responses are unwrapped from Orval's `{ data, status, headers }`; a non-2xx status throws `ApiError`.
-
----
-
-## 8. Suggestions
-
-The studio ranks **all** operations for each slot and shows the best first; any operation can be chosen. Ranking uses metadata only: shape compatibility, intent, name similarity, glossary synonyms. Request fields are proposed from the values the screen has (produce slots, context, earlier steps, the current item), ranked by name and type. Proposals stay `origin: "suggested"` until a person confirms them.
-
----
-
-## 9. Validation
-
-`api-binding generate` fails, and writes nothing, on any error:
-
-- an id that breaks the format, is duplicated, or clashes with a screen id; a component under no screen
-- an unknown kind, or a parent that is not registered
-- an expression reading a slot that is not produced on the screen, an undeclared context, a later step, or `$item` where there is none
-- an operation not in the docs, a request input the operation does not have, an unconnected path parameter
-- two components whose names become the same TypeScript key
-
-Warnings: drafts, unconnected required body fields, and with `--src` every registered id missing from the source (and every `componentId` literal not registered). `--check` exits 1 when generated files are out of date.
-
----
-
-## 10. Studio rules
-
-- Runs locally from the CLI (`api-binding studio`); it reads and writes `bindings.json` and fetches the docs server-side, so the browser needs no CORS access.
-- Navigation and component lists come from the ids. Icons come from kinds.
-- Three slot editors, one per role, generated from slot schemas. A new kind never needs studio code.
-- Shows only what validates.
-
----
-
-## 11. Conformance rules for an app
-
-1. Every bindable component has a `componentId` in the format above, registered in `bindings.json`.
-2. Each screen calls its generated `use<Screen>Api(state)` once, passes what its components produce and what it was opened with, and renders `bound ? data : <its own value>`.
-3. No direct API calls in screens other than through generated hooks; no hardcoded data an API should provide.
-4. Opening, closing, navigation, toasts and reloads stay in the app's UI code.
-5. Orval output and screen hooks are regenerated, never edited by hand.
+# API Binding Framework — v3
+
+Normative types: [`contract.ts`](../src/framework/contract.ts).
+
+The framework connects **UI components** to **documented API operations** at design time and turns the result into **plain code**. Binding lives in two files: `registry.json` (what exists: kinds and the screen → component → part tree) and `bindings.json` (how it is wired to the API). After design time the app holds only ordinary React Query hooks over an Orval client; no framework code, runtime or manifest ships.
+
+---
+
+## 1. Principles
+
+1. **Nothing concrete in the framework.** Component kinds, products, operations and fields arrive as data: kinds and the registry in the bindings file, operations from the OpenAPI docs.
+2. **The API docs are the only source of operations.** No local hooks, hardcoded option lists or free-text overrides.
+3. **UI first.** The unit of work is a screen and its components; APIs attach to component slots.
+4. **Two files.** `registry.json` says what exists (kinds, screens, components); `bindings.json` says how it is wired (output settings, bindings). The studio writes only `bindings.json`.
+5. **No trace at run time.** The generator writes plain hooks; the app never imports this package.
+6. **Deterministic.** The same file and docs always produce the same code. Generated files carry an `@generated` mark and are never edited by hand.
+
+---
+
+## 2. The pieces
+
+```
+OpenAPI docs ──► Orval ──────────────► src/api/generated   (typed client)
+     │
+     └──► api-binding studio ◄──► bindings.json (+ registry.json) ──► api-binding generate ──► src/api/screens (one hook per screen)
+                                                                               │
+                                          app components ── use<Screen>Api(state) ┘
+```
+
+| Piece | What it is | Owned by |
+|---|---|---|
+| Kinds | A component kind's slots, with JSON Schema shapes | Design system, in `registry.json` → `kinds` |
+| Screens and components | Every screen and component instance, by id | The app, in `registry.json` (a tree; nesting gives each part its parent) |
+| Bindings | Which operation or value feeds each slot | Designers in the studio, reviewed by engineers |
+| Orval client | Typed functions per operation | Generated by Orval from the same docs |
+| Screen hooks | `use<Screen>Api(state)` per screen | Generated by `api-binding generate` |
+
+---
+
+## 3. Ids
+
+One namespace for screens and components, used everywhere: in `componentId` props, in the file and in expressions.
+
+```
+<product>.<screen>[.<sub-screen>…].<component>[.<part>…]
+collections.worklist                         screen
+collections.worklist.add-notes               sub-screen (a dialog over the worklist)
+collections.worklist.grid                    component on collections.worklist
+collections.worklist.grid.column.customer-name
+collections.worklist.grid.row.add-notes
+collections.worklist.add-notes.notes-type    component on collections.worklist.add-notes
+```
+
+- Segments are lowercase kebab-case (`[a-z0-9-]`), joined by dots: `^[a-z][a-z0-9-]*(\.[a-z0-9-]+)+$`.
+- A component belongs to the **longest** registered screen id that prefixes it. A screen's parent is the longest other screen id that prefixes it. Navigation is built from this; there is no `path` or `parent` to maintain.
+- A component id may not equal a screen id (it would capture that screen's components).
+- Ids are stable: renaming one orphans its bindings. They never depend on labels.
+- In the app, each component gets `componentId="<id>"`; design-system components render it as `data-component-id`.
+
+---
+
+## 4. Kinds and slots
+
+A kind declares slots with one of three **roles**:
+
+| Role | Meaning | Bound to |
+|---|---|---|
+| `consume` | The component needs data | An operation (request + response selection) or an expression |
+| `produce` | The component exposes data | Nothing; a source others read |
+| `trigger` | The component emits an event | Ordered API call steps, or "no API" |
+
+- `scope.parentSlot`: the slot is evaluated per item of the parent's slot (a cell in a row, an action on a row); `$item` is that item.
+- `feeds`: produce slots of the same component offered as request sources (paging, sorting).
+- `"$ref": "#slot/<id>"`: the same shape as that slot after binding (a grid's selection has the shape of its rows).
+
+---
+
+## 5. The bindings file
+
+```jsonc
+{
+  "version": 3,
+  "openapi": "https://apidocs.example.com/index.yaml",   // or a path next to this file
+  "output": { "dir": "src/api/screens", "client": "@/api/generated" },
+  "kinds": [ /* ComponentDescriptor */ ],
+  "screens": [ { "id": "collections.worklist.add-notes", "label": "Add Notes",
+                 "context": [ { "id": "selection", "label": "Selected rows", "many": true,
+                                "shape": { "from": { "screen": "collections.worklist", "component": "collections.worklist.grid", "slot": "selection" } } } ] } ],
+  "components": [ { "id": "collections.worklist.add-notes.notes-type", "kind": "hr-ds/select", "label": "Notes Type" } ],
+  "bindings": [ /* SlotBinding */ ]
+}
+```
+
+| Slot role | Binding type | Contents |
+|---|---|---|
+| consume | `operation` | operation, request mapping (pointer → expression), response `select`, optional `map`, `load` |
+| consume | `expression` | one expression |
+| trigger | `steps` | ordered `call` steps; a step may run `forEach` over a list; `onError: stop \| continue` |
+| trigger | `none` | reviewed: this event calls no API |
+
+Only `confirmed` bindings are generated; drafts are reported as warnings. Bindings describe API calls only: opening, closing, navigation, toasts and reloads are app code.
+
+---
+
+## 6. Expressions
+
+| Form | Resolves to |
+|---|---|
+| `<componentId>:<slot>[.path]` | A produce slot on the same screen, e.g. `collections.worklist.add-notes.subject:value` |
+| `<expr>[*].<path>` | A property of every item, as a list |
+| `$item[.path]` | The current item: a scoped slot's item, a `forEach` item, or the trigger's payload |
+| `$context.<id>[.path]` | A value declared in the screen's `context` |
+| `$steps.<stepId>.response[.path]` | The response of an earlier step |
+
+`:` ends a component id, so ids can contain dots. Nothing outside this grammar is valid.
+
+---
+
+## 7. Generated code
+
+`api-binding generate` writes into `output.dir`:
+
+- `screen-helpers.ts`: the few helpers the hooks share (React Query only).
+- `<screen id>.ts` per screen: `<Screen>State`, `<Screen>Api` and `use<Screen>Api(state)`.
+- `index.ts`: re-exports.
+
+**The signature comes from the registry, the body from the bindings.** `<Screen>State` has one optional entry per component that produces values; `<Screen>Api` has one entry per consume and trigger slot. Changing bindings never changes either type, so call sites stay put. Adding or removing components does, and `tsc` points at every call site to update.
+
+| Slot | Returns | When unbound |
+|---|---|---|
+| consume | `Data<T>`: `{ bound, data, loading, error }` | `bound: false`; keep the UI's own value |
+| consume, scoped | `Cell<T>`: `{ bound, read(item) }` | `read` returns `undefined` |
+| trigger | `Action`: `{ bound, run(payload?), running, error }` | `run` resolves at once |
+
+- Queries call the Orval function for the operation: path params in path order, then the body, then the query params object, then fetch options (headers). A query is enabled only when every required input has a value; `load: { everySeconds }` polls.
+- Actions run steps in order. A failed call rejects `run` (`stop`) or is collected and rejected after the rest run (`continue`).
+- Responses are unwrapped from Orval's `{ data, status, headers }`; a non-2xx status throws `ApiError`.
+
+---
+
+## 8. Suggestions
+
+The studio ranks **all** operations for each slot and shows the best first; any operation can be chosen. Ranking uses metadata only: shape compatibility, intent, name similarity, glossary synonyms. Request fields are proposed from the values the screen has (produce slots, context, earlier steps, the current item), ranked by name and type. Proposals stay `origin: "suggested"` until a person confirms them.
+
+---
+
+## 9. Validation
+
+`api-binding generate` fails, and writes nothing, on any error:
+
+- an id that breaks the format, is duplicated, or clashes with a screen id; a component under no screen
+- an unknown kind, or a parent that is not registered
+- an expression reading a slot that is not produced on the screen, an undeclared context, a later step, or `$item` where there is none
+- an operation not in the docs, a request input the operation does not have, an unconnected path parameter
+- two components whose names become the same TypeScript key
+
+Warnings: drafts, unconnected required body fields, and with `--src` every registered id missing from the source (and every `componentId` literal not registered). `--check` exits 1 when generated files are out of date.
+
+---
+
+## 10. Studio rules
+
+- Runs from the Vite dev plugin (`api_binding_ui/vite`, serve only) or the CLI (`api-binding studio`). Either server reads `registry.json`, reads and writes `bindings.json`, and fetches the docs server-side, so the browser needs no CORS access.
+- Under the Vite plugin every save regenerates the screen hooks, so a confirmed binding is live in the running app after the save. Vite does not watch `bindings.json`.
+- The dev plugin's floating button opens the studio over the app on the screen shown: the screen most `data-component-id` values the user can see belong to; a component covered by any layer above it does not count. Alt+click opens it on one component. Nothing reaches a build.
+- Navigation and component lists come from the ids. Icons come from kinds.
+- Three slot editors, one per role, generated from slot schemas. A new kind never needs studio code.
+- Shows only what validates.
+
+---
+
+## 11. Conformance rules for an app
+
+1. Every bindable component has a `componentId` in the format above, registered in `registry.json`.
+2. Each screen calls its generated `use<Screen>Api(state)` once, passes what its components produce and what it was opened with, and renders `bound ? data : <its own value>`.
+3. No direct API calls in screens other than through generated hooks; no hardcoded data an API should provide.
+4. Opening, closing, navigation, toasts and reloads stay in the app's UI code.
+5. Orval output and screen hooks are regenerated, never edited by hand.