api_binding_ui 3.2.0 → 3.3.0

package/README.md

@@ -41,6 +41,7 @@ export default defineConfig({ plugins: [/* …, */ bindingStudio()] });   // rea
 - Adds a floating **Bind API** button to every HTML page (SPA and server-rendered). It opens the studio over the app on the screen being shown, found from the `data-component-id` attributes the user can see; anything covered by a layer above it does not count.
 - **Alt+click** any component to open the studio on it; holding Alt outlines components.
 - The studio is served by the dev server under `/__binding/`, which reads and writes `bindings.json` and fetches the docs server-side. Writes are same-origin only.
+- On start it generates the API client (runs the app's `orval.config.ts`, when present) and the screen hooks, before the server takes requests, so a project can run without committed generated code.
 - Every save, and every edit of `registry.json`, regenerates the screen hooks (errors are printed in the dev server's terminal; nothing is written then). Vite does not watch `bindings.json`, so a save never reloads the page under the studio.
 
 ## registry.json

package/dist/vite/plugin.d.ts

@@ -7,7 +7,9 @@
  *
  * Serves the studio under /__binding/ and injects a floating button into the app's HTML pages
  * (SPA and server-rendered alike). Every save regenerates the screen hooks, so Vite reloads the
- * screen with the new binding. `vite build` never runs it (apply: "serve").
+ * screen with the new binding. On start it generates the API client (Orval, when the app has
+ * orval.config.ts) and the screen hooks, so a project needs no committed generated code.
+ * `vite build` never runs it (apply: "serve").
  */
 import type { IncomingMessage, ServerResponse } from "node:http";
 export interface BindingStudioOptions {
@@ -39,11 +41,13 @@ export interface VitePluginLike {
         watcher?: {
             on: (event: "change", fn: (p: string) => void) => void;
         };
-    }) => void;
+    }) => Promise<void>;
 }
 /** Adds the overlay script before the last </body> of HTML chunks; leaves everything else as it is. */
 export declare function injectOverlay(res: ServerResponse, tag: string): void;
 /** Regenerates the hooks after a save; logs the outcome, since the file is already saved either way. */
 export declare function regenerate(file: string, log?: (line: string) => void): Promise<void>;
+/** Runs the app's Orval config, so the client the hooks import exists. Orval is the app's dependency, not this package's. */
+export declare function generateClient(root: string, log?: (line: string) => void): Promise<void>;
 export declare function bindingStudio(options?: BindingStudioOptions): VitePluginLike;
 export {};

package/dist/vite.js

@@ -1,5 +1,5 @@
 // src/vite/plugin.ts
-import { readFileSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import path4 from "node:path";
 
 // src/server/handler.ts
@@ -1055,10 +1055,23 @@ async function regenerate(file, log = console.log) {
     log(`[api-binding] Screen hooks not regenerated: ${e.message}`);
   }
 }
+async function generateClient(root, log = console.log) {
+  const config = path4.join(root, "orval.config.ts");
+  if (!existsSync(config))
+    return;
+  try {
+    const orval = "orval";
+    const { generate } = await import(orval);
+    await generate(config, root);
+    log("[api-binding] API client generated.");
+  } catch (e) {
+    log(`[api-binding] API client not generated: ${e.message}`);
+  }
+}
 function bindingStudio(options = {}) {
   const base = (options.base ?? "/__binding").replace(/\/+$/, "");
   const tag = `<script type="module" src="${base}/overlay.js"></script>`;
-  let file = "";
+  let file = "", root = "";
   const norm = (s) => process.platform === "win32" ? path4.resolve(s).toLowerCase() : path4.resolve(s);
   const isBindingsFile = (p) => {
     const abs = norm(p), f = norm(file);
@@ -1076,11 +1089,16 @@ function bindingStudio(options = {}) {
     name: "api-binding-studio",
     apply: "serve",
     configResolved(config) {
-      file = path4.resolve(config.root, options.file ?? "bindings.json");
+      root = config.root;
+      file = path4.resolve(root, options.file ?? "bindings.json");
     },
     transformIndexHtml: (html) => html.includes(tag) ? html : html.replace(/<\/body>/i, `${tag}</body>`),
     config: () => ({ server: { watch: { ignored: [(p) => isBindingsFile(p)] } } }),
-    configureServer(server) {
+    async configureServer(server) {
+      if (existsSync(file)) {
+        await generateClient(root);
+        await regenerate(file);
+      }
       const allowed = (req) => {
         const origin = req.headers.origin;
         return req.method === "GET" || !origin || new URL(origin).host === req.headers.host;
@@ -1108,6 +1126,7 @@ function bindingStudio(options = {}) {
 }
 export {
   bindingStudio,
+  generateClient,
   injectOverlay,
   regenerate
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "api_binding_ui",
-  "version": "3.2.0",
+  "version": "3.3.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",

package/spec/FRAMEWORK.md

@@ -1,178 +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**. 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.
+# 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`. On start it also generates the API client (the app's `orval.config.ts`) and the hooks, so a project needs no committed generated code.
+- 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.