api_binding_ui 3.0.0 → 3.2.0

package/README.md

@@ -1,80 +1,118 @@
-# api_binding_ui
-
-Design-time API binding. Register an app's components by id, bind them to documented APIs in a local studio, and generate plain React Query hooks over an [Orval](https://orval.dev) client. Nothing from this package ships in the app.
-
-Spec: [`spec/FRAMEWORK.md`](spec/FRAMEWORK.md). Agent rules: [`SKILL.md`](SKILL.md).
-
-## Flow
-
-1. **Ids.** Every bindable component gets `componentId="<product>.<screen>[.<sub-screen>].<component>"`, e.g. `collections.worklist.add-notes.submit`.
-2. **Register.** List kinds, screens and components in `bindings.json`.
-3. **Client.** Run Orval on the same OpenAPI file (see below).
-4. **Bind.** `npx api-binding studio bindings.json` opens the studio on http://localhost:5180. Edits save to the file.
-5. **Generate.** `npx api-binding generate bindings.json` writes one hook per screen into `output.dir`.
-6. **Wire once.** Each screen calls its hook:
-
-```tsx
-import { useCollectionsWorklistAddNotesApi } from "@/api/screens";
-
-const api = useCollectionsWorklistAddNotesApi({
-  notesType: { selected }, subject: { value: subject }, notes: { value: notes },
-  context: { selection: selectedRows },
-});
-const options = api.notesType.options.bound ? api.notesType.options.data ?? [] : sampleOptions;
-
-<Button componentId="collections.worklist.add-notes.submit" disabled={api.submit.click.running}
-  onClick={async () => { try { await api.submit.click.run(); close(); } catch (e) { toast(String(e)); } }} />
-```
-
-Rebinding changes only the hook bodies; the hook's types come from the registry, so call sites stay put.
-
-## bindings.json
-
-```jsonc
-{
-  "version": 3,
-  "openapi": "https://apidocs.highradius.com/documentation-ui/index.yaml",
-  "output": { "dir": "src/api/screens", "client": "@/api/generated" },
-  "kinds": [],        // slot descriptors per component kind
-  "screens": [],      // { id, label, context? }
-  "components": [],   // { id, kind, label, parent? }
-  "bindings": []      // written by the studio
-}
-```
-
-`openapi` is a URL or a path relative to the file; `output.dir` is relative to the file; `output.client` is the import specifier of the Orval output as the app sees it.
-
-## Orval
-
-```ts
-// orval.config.ts
-export default {
-  api: {
-    input: "<same OpenAPI URL or file>",
-    output: { target: "src/api/generated/index.ts", client: "fetch", mode: "single", baseUrl: "<API base URL>" },
-  },
-};
-```
-
-The generated hooks call Orval's functions (named after each `operationId`) and unwrap `{ data, status }`; a non-2xx status throws. A `client: "react-query"` setup with `httpClient: "fetch"` works the same, since it exports the same functions.
-
-## CLI
-
-| Command | Does |
-|---|---|
-| `api-binding studio [file] [--port 5180]` | Local studio. Reads and writes the file; fetches the docs server-side (no CORS). Accepts requests from localhost only. |
-| `api-binding generate [file]` | Validates, then writes the hooks. Any error: nothing is written. Removes only files it generated. |
-| `api-binding generate [file] --check` | Writes nothing; exits 1 when the hooks are out of date. For CI. |
-| `api-binding generate [file] --src src` | Also lists registered ids missing from the source, and `componentId` literals not registered. |
-
-## Develop
-
-```sh
-bun install
-bun run dev        # builds the studio and serves it on src/dev/sample/bindings.json
-bun test
-bun run typecheck
-bun run build      # library, CLI (dist/cli.js) and studio app (dist/app)
-```
-
-Vite's esbuild binary is blocked on some managed machines, so the build uses Bun.
+# api_binding_ui
+
+Design-time API binding. Register an app's components by id, bind them to documented APIs in a local studio, and generate plain React Query hooks over an [Orval](https://orval.dev) client. Nothing from this package ships in the app.
+
+Spec: [`spec/FRAMEWORK.md`](spec/FRAMEWORK.md). Agent rules: [`SKILL.md`](SKILL.md).
+
+## Flow
+
+1. **Ids.** Every bindable component gets `componentId="<product>.<screen>[.<sub-screen>].<component>"`, e.g. `collections.worklist.add-notes.submit`.
+2. **Register.** List kinds and the screen → component → part tree in `registry.json` (below). The studio's navigation comes from it.
+3. **Docs, once.** Download the OpenAPI file into the repo (e.g. `openapi/collections.yaml`). Orval, the studio and the generator all read that one file.
+4. **Generate, then wire once.** Run Orval (below) and `npx api-binding generate bindings.json`. Every screen gets its hook with nothing bound yet; each screen calls it and falls back to its own values:
+
+```tsx
+import { useCollectionsWorklistAddNotesApi } from "@/api/screens";
+
+const api = useCollectionsWorklistAddNotesApi({
+  notesType: { selected }, subject: { value: subject }, notes: { value: notes },
+  context: { selection: selectedRows },
+});
+const options = api.notesType.options.bound ? api.notesType.options.data ?? [] : sampleOptions;
+
+<Button componentId="collections.worklist.add-notes.submit" disabled={api.submit.click.running}
+  onClick={async () => { try { await api.submit.click.run(); close(); } catch (e) { toast(String(e)); } }} />
+```
+
+5. **Bind.** In a Vite app, add the dev plugin (below), run `vite dev` and click **Bind API**. Each save regenerates the hooks and Vite hot-updates the screen, so a confirmed binding makes real calls right away. Elsewhere, `npx api-binding studio bindings.json` opens it on http://localhost:5180, then run `generate`.
+
+Rebinding changes only the hook bodies; the hook's types come from the registry, so call sites stay put.
+
+## Dev plugin (Vite)
+
+```ts
+// vite.config.ts
+import { bindingStudio } from "api_binding_ui/vite";
+
+export default defineConfig({ plugins: [/* …, */ bindingStudio()] });   // reads ./bindings.json
+```
+
+- `vite dev` only (`apply: "serve"`); `vite build` output contains nothing from it. Keep `api_binding_ui` a devDependency.
+- 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.
+- 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
+
+What exists in the app, as a tree. Every id extends the id it is nested under. People edit it; the studio only reads it.
+
+```jsonc
+{
+  "version": 1,
+  "kinds": [],   // slot descriptors per component kind
+  "screens": [
+    { "id": "collections.worklist", "label": "Worklist",
+      "components": [
+        { "id": "collections.worklist.grid", "kind": "hr-ds/grid", "label": "Grid",
+          "children": [ { "id": "collections.worklist.grid.column.customer-name", "kind": "hr-ds/column", "label": "Customer Name" } ] } ],
+      "screens": [   // sub-screens that open over it
+        { "id": "collections.worklist.add-notes", "label": "Add Notes", "context": [],
+          "components": [ { "id": "collections.worklist.add-notes.submit", "kind": "hr-ds/button", "label": "Submit" } ] } ] }
+  ]
+}
+```
+
+## bindings.json
+
+```jsonc
+{
+  "version": 3,
+  "registry": "registry.json",
+  "openapi": "openapi/collections.yaml",
+  "output": { "dir": "src/api/screens", "client": "@/api/generated" },
+  "bindings": []      // written by the studio
+}
+```
+
+Paths are relative to the file; `output.client` is the import specifier of the Orval output as the app sees it. Without `registry`, `kinds`, `screens` and `components` (flat, with `parent`) can sit in this file instead.
+
+## Orval
+
+```ts
+// orval.config.ts
+export default {
+  api: {
+    input: "./openapi/collections.yaml",
+    output: {
+      target: "src/api/generated/index.ts",   // so output.client "@/api/generated" resolves
+      client: "fetch",
+      mode: "single",
+      override: { mutator: { path: "./src/api/fetcher.ts", name: "apiFetch" } },   // auth + base URL; returns { data, status, headers }
+    },
+  },
+};
+```
+
+The generated hooks call Orval's functions (named after each `operationId`) and unwrap `{ data, status }`; a non-2xx status throws. A `client: "react-query"` setup with `httpClient: "fetch"` works the same, since it exports the same functions.
+
+## CLI
+
+| Command | Does |
+|---|---|
+| `api-binding studio [file] [--port 5180]` | Local studio. Reads and writes the file; fetches the docs server-side (no CORS). Accepts requests from localhost only. |
+| `api-binding generate [file]` | Validates, then writes the hooks. Any error: nothing is written. Removes only files it generated. |
+| `api-binding generate [file] --check` | Writes nothing; exits 1 when the hooks are out of date. For CI. |
+| `api-binding generate [file] --src src` | Also lists registered ids missing from the source, and `componentId` literals not registered. |
+
+## Develop
+
+```sh
+bun install
+bun run dev        # builds the studio and serves it on src/dev/sample/bindings.json
+bun test
+bun run typecheck
+bun run build      # library, CLI (dist/cli.js) and studio app (dist/app)
+```
+
+Vite's esbuild binary is blocked on some managed machines, so the build uses Bun.

package/SKILL.md

@@ -1,45 +1,45 @@
----
-name: api-binding-ui
-description: "Use when adding, changing or wiring screens in an app whose API calls are designed with api_binding_ui: componentId props, bindings.json, generated screen hooks (src/api/screens), the Orval client."
----
-
-# api_binding_ui: rules for agents
-
-Spec: `node_modules/api_binding_ui/spec/FRAMEWORK.md`. The app never imports `api_binding_ui`; it imports the generated hooks.
-
-## Never
-
-- Import `api_binding_ui` from app code, or add a binding runtime, provider or manifest to the app.
-- Edit files under the Orval output or `src/api/screens`. They start with `// @generated`; regenerate instead.
-- Call APIs from screens other than through the generated screen hook.
-- Add hardcoded option lists, rows or values an API should provide.
-- Put opening, closing, navigation, toasts or reloads into bindings. They are app code.
-- Rename or reuse a `componentId`. Renaming orphans its bindings.
-- Invent APIs. Only operations in the OpenAPI docs exist.
-
-## Always
-
-1. **componentId on every bindable component**: data, input and action components.
-   - Format: `<product>.<screen>[.<sub-screen>…].<component>[.<part>…]`, lowercase kebab-case segments joined by dots. Examples: `collections.worklist.grid`, `collections.worklist.grid.column.customer-name`, `collections.worklist.grid.row.add-notes`, `collections.worklist.add-notes.notes-type`.
-   - A dialog or drawer is a sub-screen: its id extends the id of the screen it opens over.
-   - A component id never equals a screen id.
-   - Components built from config (grid columns, row actions) build the id from the grid's id and the config item's id: `` `${gridId}.column.${kebab(col.id)}` ``.
-2. **Register** every new screen and component in `bindings.json` (`screens`, `components`), with its kind and the label users see.
-3. **One hook call per screen:**
-   ```tsx
-   const api = use<Screen>Api({ <component>: { <produceSlot>: value }, context: { <id>: value } });
-   ```
-   - Pass every value the screen's components produce: input values, the selected option object (whole object, as `selected`), grid page, sort and selection.
-   - Pass what the screen was opened with as `context`.
-4. **Render by `bound`:**
-   - `Data`: `api.x.slot.bound ? api.x.slot.data : <the screen's own value>`, with `loading` and `error`.
-   - `Cell`: `api.col.value.bound ? api.col.value.read(row) : row.field`.
-   - `Action`: `await api.btn.click.run(payload?)`. It rejects on failure. After success, the app decides what happens next (close, toast, reload).
-5. After changing `bindings.json` or the docs: `npx api-binding generate bindings.json --src src`, then typecheck. `tsc` errors show the call sites to update.
-
-## New screen checklist
-
-- [ ] `componentId` on every component, in the format above
-- [ ] Screen and components registered in `bindings.json`
-- [ ] Hooks regenerated; screen calls `use<Screen>Api(state)` once and passes every produced value
-- [ ] Unbound slots keep the screen's existing content
+---
+name: api-binding-ui
+description: "Use when adding, changing or wiring screens in an app whose API calls are designed with api_binding_ui: componentId props, bindings.json, generated screen hooks (src/api/screens), the Orval client."
+---
+
+# api_binding_ui: rules for agents
+
+Spec: `node_modules/api_binding_ui/spec/FRAMEWORK.md`. The app never imports `api_binding_ui`; it imports the generated hooks.
+
+## Never
+
+- Import `api_binding_ui` from app code, or add a binding runtime, provider or manifest to the app. The only allowed use is `bindingStudio()` from `api_binding_ui/vite` in `vite.config.ts`, with the package as a devDependency.
+- Edit files under the Orval output or `src/api/screens`. They start with `// @generated`; regenerate instead.
+- Call APIs from screens other than through the generated screen hook.
+- Add hardcoded option lists, rows or values an API should provide.
+- Put opening, closing, navigation, toasts or reloads into bindings. They are app code.
+- Rename or reuse a `componentId`. Renaming orphans its bindings.
+- Invent APIs. Only operations in the OpenAPI docs exist.
+
+## Always
+
+1. **componentId on every bindable component**: data, input and action components.
+   - Format: `<product>.<screen>[.<sub-screen>…].<component>[.<part>…]`, lowercase kebab-case segments joined by dots. Examples: `collections.worklist.grid`, `collections.worklist.grid.column.customer-name`, `collections.worklist.grid.row.add-notes`, `collections.worklist.add-notes.notes-type`.
+   - A dialog or drawer is a sub-screen: its id extends the id of the screen it opens over.
+   - A component id never equals a screen id.
+   - Components built from config (grid columns, row actions) build the id from the grid's id and the config item's id: `` `${gridId}.column.${kebab(col.id)}` ``.
+2. **Register** every new screen and component in `registry.json`, nested under the screen or component it belongs to, with its kind and the label users see.
+3. **One hook call per screen:**
+   ```tsx
+   const api = use<Screen>Api({ <component>: { <produceSlot>: value }, context: { <id>: value } });
+   ```
+   - Pass every value the screen's components produce: input values, the selected option object (whole object, as `selected`), grid page, sort and selection.
+   - Pass what the screen was opened with as `context`.
+4. **Render by `bound`:**
+   - `Data`: `api.x.slot.bound ? api.x.slot.data : <the screen's own value>`, with `loading` and `error`.
+   - `Cell`: `api.col.value.bound ? api.col.value.read(row) : row.field`.
+   - `Action`: `await api.btn.click.run(payload?)`. It rejects on failure. After success, the app decides what happens next (close, toast, reload).
+5. After changing `bindings.json` or the docs: `npx api-binding generate bindings.json --src src`, then typecheck. `tsc` errors show the call sites to update.
+
+## New screen checklist
+
+- [ ] `componentId` on every component, in the format above
+- [ ] Screen and components registered in `registry.json`
+- [ ] Hooks regenerated; screen calls `use<Screen>Api(state)` once and passes every produced value
+- [ ] Unbound slots keep the screen's existing content