api_binding_ui 2.0.2 → 3.1.0

package/README.md

@@ -1,74 +1,94 @@
 # api_binding_ui
 
-Bind any UI component to documented APIs while a product is being designed, then run those bindings in production.
+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.
 
-- **Generic.** The code knows three slot roles (`consume`, `produce`, `trigger`) and nothing else. Component kinds, screens, products and APIs are data.
-- **Docs only.** APIs come from the OpenAPI documents. If the docs do not have it, it cannot be bound.
-- **API only.** Bindings say which API is called with what data and where results go. Opening, closing and navigation stay in the app.
+Spec: [`spec/FRAMEWORK.md`](spec/FRAMEWORK.md). Agent rules: [`SKILL.md`](SKILL.md).
 
-The full contract is in [`spec/FRAMEWORK.md`](spec/FRAMEWORK.md); the types are in [`src/framework/contract.ts`](src/framework/contract.ts).
+## Flow
 
-## Entries
+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.** In a Vite app, add the dev plugin (below) and click **Bind API** on any screen. Elsewhere, `npx api-binding studio bindings.json` opens it 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:
 
-| Import | Use | In production |
-|---|---|---|
-| `api_binding_ui` | Contract types, `catalogFromOpenApi`, the runtime (`BindingProvider`, `BindingScreen`, `useSlot`, `useCell`, `useProduce`, `useTrigger`), validation | Yes |
-| `api_binding_ui/studio` + `api_binding_ui/studio.css` | `BindingWidget`, `BindingStudio` | No; import only from design-time code |
+```tsx
+import { useCollectionsWorklistAddNotesApi } from "@/api/screens";
 
-## Runtime
+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;
 
-```tsx
-import { BindingProvider, BindingScreen, useSlot, useProduce, useTrigger } from "api_binding_ui";
-
-<BindingProvider catalog={catalog} manifests={manifests} fetcher={fetcher}>
-  <BindingScreen id="collections.worklist.add-notes" context={{ selection }}>
-    <AddNotesForm />
-  </BindingScreen>
-</BindingProvider>;
-
-function AddNotesForm() {
-  const notesType = useSlot<{ value: string; label: string }[]>("notesType", "options");
-  const [subject, setSubject] = useState("");
-  useProduce("subject", "value", subject);
-  const submit = useTrigger("submit", "click");
-  // render notesType.data, call submit.run(), then close the dialog in your own code
-}
+<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)); } }} />
 ```
 
-`fetcher` receives `{ method, path, query, headers, body }` and the catalog operation; base URL, auth and errors stay in the app.
+Rebinding changes only the hook bodies; the hook's types come from the registry, so call sites stay put.
 
-## Studio
+## Dev plugin (Vite)
 
-```tsx
-import { BindingWidget } from "api_binding_ui/studio";
-import "api_binding_ui/studio.css";
+```ts
+// vite.config.ts
+import { bindingStudio } from "api_binding_ui/vite";
 
-// once, inside <BindingProvider persistence={…}>, design mode only
-<BindingWidget framework={{ descriptors, registry }} />
+export default defineConfig({ plugins: [/* …, */ bindingStudio()] });   // reads ./bindings.json
 ```
 
-A floating button opens the studio over the app on the screen being shown. Edits apply when it closes.
+- `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 on the page; an open dialog wins over its page.
+- **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.
+
+## 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
+}
+```
 
-The studio reads every product's APIs from the published docs (default `https://apidocs.highradius.com/documentation-ui/index.yaml`, JSON or YAML). Each user can change the URL in **Settings** (top right), which also downloads and imports bindings as JSON for committing with the app. Pass `docsUrl` to change the default, or `framework.catalog` to skip loading.
+`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.
 
-## Layout
+## 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>" },
+  },
+};
 ```
-src/
-  framework/   pure TypeScript: contract, OpenAPI → catalog, schema, names, engine, validation,
-               expressions, request runner, persistence
-  runtime/     React runtime: provider, screen scope, hooks
-  studio/      design-time UI: shell, navigator, search, component list, inspector, slot editors
-  dev/         sample data and the local harness (not published)
-spec/          FRAMEWORK.md (the contract) and contract.ts (re-export)
-```
+
+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        # studio with sample data on http://localhost:5174
+bun run dev        # builds the studio and serves it on src/dev/sample/bindings.json
 bun test
 bun run typecheck
-bun run build
+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,50 +1,45 @@
 ---
 name: api-binding-ui
-description: "Use when adding, changing or wiring screens in an app that depends on api_binding_ui: registry entries, BindingScreen, slot hooks, the design-mode BindingWidget."
+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
 
-Contract: `node_modules/api_binding_ui/spec/FRAMEWORK.md`. Types: `import type { … } from "api_binding_ui"`.
+Spec: `node_modules/api_binding_ui/spec/FRAMEWORK.md`. The app never imports `api_binding_ui`; it imports the generated hooks.
 
 ## Never
 
-- Call APIs from screens (`fetch`, axios, generated clients, mock hooks).
-- Add new hardcoded option lists, rows or values that an API should provide.
-- Put opening, closing, navigation, toasts or reloads in bindings. They are app code.
-- Invent APIs. Only operations in the catalog (generated from the OpenAPI docs) exist.
-- Edit the catalog or `openapi/*.json` by hand.
-- Import `api_binding_ui/studio` from production code paths. Load it with `React.lazy` behind the design-mode flag.
-- Add component kinds, product names or field names to framework code.
+- 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. **Registry entry per screen** (`src/bindings/registry.ts`):
-   ```ts
-   { id: "<product>.<area>.<screen>", label, path: ["<Product>", ...groups], parent?: "<screen id>",
-     context: [{ id, label, many?, shape: { schema } | { from: { screen, component, slot } } }],
-     components: [{ bindId, kind, kindVersion: 1, label, parent?: "<bindId>" }] }
+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 } });
    ```
-   - `path[0]` is the product. A dialog or drawer is its own screen with `parent`.
-   - `bindId` is stable, unique per screen and independent of the label: `notesType`, not `select1`. Letters, digits, `-` and `_` only; never a dot (`grid-search-status`, not `grid.search.status`).
-   - `label` is the text the user sees ("Call list"), never the id.
-   - `kind` must exist in `src/bindings/descriptors.ts`. Grid columns and row actions set `parent` to the grid's bindId.
-2. **Wrap the screen:** `<BindingScreen id="<screen id>" context={{ <context id>: value }}>`. Views kept mounted while hidden (inactive tabs) are wrapped in `<BindingActive value={isVisible}>`.
-3. **Wire every component through its slots:**
-
-   | Slot role | Hook | Use |
-   |---|---|---|
-   | consume | `const s = useSlot<T>(bindId, slot)` | render by `s.status`: `unbound` / `waiting` / `loading` / `ready` / `error`; data in `s.data`; `s.reload()` |
-   | consume, per row | `const cell = useCell<T>(bindId, slot)` | `cell(row)` |
-   | produce | `useProduce(bindId, slot, value)` | publish every value the component exposes; dropdowns publish the whole selected option object as `selected` |
-   | trigger | `const t = useTrigger(bindId, slot)` | `if (t.bound) { const out = await t.run(item?); if (out.every(o => o.ok)) { /* app: close, toast, reload */ } else { /* show out.find(o => !o.ok).error */ } }` |
-
-4. **Unbound keeps what the screen has today:** `status === "unbound"` renders the screen's existing content (its sample data during design); `ready` replaces it with API data. `t.bound === false` keeps the existing behaviour.
-5. **No per-screen Bind API buttons.** One `<BindingWidget>` near the app root opens the studio on whichever `BindingScreen` is showing.
+   - 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
 
-- [ ] Registry entry with every component; `parent` for dialogs; `context` for inputs
-- [ ] `<BindingScreen>` around the screen
-- [ ] Every component wired with the hooks; no API calls or static data left
-- [ ] Screen opens in the studio from the floating button, in design mode
+- [ ] `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