api_binding_ui 1.0.0 → 2.0.0

package/README.md

@@ -1,384 +1,74 @@
-# API Binding Studio (api_binding_ui)
-
-API Binding Studio (`api_binding_ui`) is an isolated, browser-side visual API mapping, simulation, and verification engine designed for enterprise web applications. It enables engineers, business analysts, and QA specialists to visually bind user interface components and action buttons to backend REST/OpenAPI endpoints, inspect live request payloads, and execute interactive end-to-end simulations without modifying production code or sending destructive mutations to live servers.
-
----
-
-## Architecture Overview
-
-The system is engineered as an independent package that mounts into any React application while operating its management workspace in a dedicated browser window.
-
-### 1. Canonical Single-Configuration Model (`src/core/model.ts`)
-The studio is driven by a single canonical configuration (`ApiBindingConfig`) containing:
-- Ordered API calls (`calls: BindingCall[]`) covering both data retrieval (`read`) and action execution (`write`).
-- Component declarations (`fields: BindingField[]`) reflecting all interactive form controls on the screen.
-- Execution parameters, customer iteration rules (`customerRule: "each" | "single"`), post-execution behaviors (`success: "close" | "keep"`), and template population policies.
-
-All workspace views, data grids, request payload previews, and simulation runners derive from this single state structure. When API contracts change or are reselected, the reconciliation engine automatically preserves matching parameter assignments while reporting removed or newly required parameters.
-
-### 2. Universal Screen Context and DOM Discovery (`src/core/bindingContext.ts`)
-The `<BindApiButton />` component is screen-agnostic and can be mounted within:
-- Modal dialogs (`[role="dialog"]`, `<dialog>`, `.ds-dialog`)
-- Slide-out drawers and flyout panels (`[role="region"]`, `[data-drawer]`, `<aside>`)
-- Dedicated forms (`<form>`)
-- Full-page views and standalone screens
-
-The context extractor progressively inspects the DOM hierarchy using explicit references (`containerRef`, `containerSelector`, `rootElement`, `formId`) or heuristic boundary detection. It automatically discovers form inputs, selects, textareas, custom ARIA widgets (`role="combobox"`, `role="textbox"`, `role="checkbox"`, `role="switch"`), and action buttons.
-
-### 3. Multi-Channel Cross-Window Transport (`src/core/transport.ts`)
-The studio operates in a dedicated browser window identified by a stable key (`api-binding:<key>`). Re-clicking the trigger button re-focuses the existing tab, preserving in-progress unsaved configurations. Communication between the host application and the studio window utilizes three redundant layers:
-1. Bidirectional `window.postMessage` handshake (`api-binding-ready` and `api-binding-context`).
-2. `BroadcastChannel("api-binding-studio")` for real-time grid selection updates and cross-tab synchronization.
-3. Structured `localStorage` persistence keys for context, draft configurations, and applied bindings across page refreshes.
-
-### 4. Design System CSS Custom Property Inheritance (`src/styles/highradius-bridge.css`)
-The studio UI relies entirely on design token custom properties:
-- Background and surfaces: `--ds-color-background`, `--ds-color-surface`, `--ds-color-surface-subtle`
-- Text and typography: `--ds-color-foreground`, `--ds-color-foreground-muted`, `--ds-font-family-sans`, `--ds-font-family-mono`
-- Borders and focus: `--ds-color-border`, `--ds-color-focus`
-- Accents and feedback: `--ds-color-primary`, `--ds-color-destructive`, `--ds-color-warning`, `--ds-color-success`
-- Layout geometry: `--ds-space-*`, `--ds-radius-*`
-
-When rendered within an application that declares these variables, the studio immediately inherits the host styling. Standalone fallback values are bundled to ensure rendering fidelity when loaded outside the parent shell.
-
-### 5. Zero-Network Simulation and Verification Engine (`src/components/SimulationDialog.tsx`)
-Before any configuration can be marked as verified or applied:
-- The engine constructs actual HTTP request payloads (headers, query parameters, path variables, request bodies).
-- Dynamic value coercion handles arrays (`number[]`, `string[]`), booleans, nested object dot-paths (`customer.billing.id`), and static text overrides.
-- An interactive simulation environment executes the mapped submission against sample datasets without initiating actual network fetch operations.
-- Verifications validate all required fields, parameter constraints, and record iterators before recording a cryptographic-style fingerprint of the verified configuration.
-
----
-
-## Installation
-
-Add `api_binding_ui` to your application dependencies:
-
-```json
-{
-  "dependencies": {
-    "api_binding_ui": "file:../api_binding_ui"
-  }
-}
-```
-
-Or via your package manager when using an internal package registry:
-
-```bash
-npm install api_binding_ui
-# or
-yarn add api_binding_ui
-# or
-bun add api_binding_ui
-```
-
----
-
-## Host Application Setup
-
-### Step 1: Register the Studio Route
-
-The studio window opens at the path `/api-binding/$key`. Configure your application router to mount the `ApiBindingWorkspace` component at this path.
-
-#### TanStack Router (`src/routes/api-binding.$key.tsx`)
-```tsx
-import { createFileRoute } from "@tanstack/react-router";
-import { ApiBindingWorkspace } from "api_binding_ui";
-import "api_binding_ui/style.css";
-
-export const Route = createFileRoute("/api-binding/$key")({
-  head: () => ({
-    meta: [
-      { title: "API Binding Studio" },
-      { name: "description", content: "Visual API mapping and simulation studio." },
-    ],
-  }),
-  component: ApiBindingRouteView,
-});
-
-function ApiBindingRouteView() {
-  const { key } = Route.useParams();
-  return <ApiBindingWorkspace key={key} pageKey={key} />;
-}
-```
-
-#### React Router (`src/App.tsx`)
-```tsx
-import { BrowserRouter, Routes, Route, useParams } from "react-router-dom";
-import { ApiBindingWorkspace } from "api_binding_ui";
-import "api_binding_ui/style.css";
-
-function ApiBindingPage() {
-  const { key = "default" } = useParams();
-  return <ApiBindingWorkspace key={key} pageKey={key} />;
-}
-
-export function App() {
-  return (
-    <BrowserRouter>
-      <Routes>
-        <Route path="/api-binding/:key" element={<ApiBindingPage />} />
-        {/* Application routes */}
-      </Routes>
-    </BrowserRouter>
-  );
-}
-```
-
----
-
-### Step 2: Mount `<BindApiButton />` on Host Screens
-
-Place `<BindApiButton />` inside your modal dialogs, slide-out drawers, form panels, or screen toolbars.
-
-#### Example A: Dialog with Data Grid Context
-```tsx
-import * as React from "react";
-import { BindApiButton } from "api_binding_ui";
-
-interface CustomerRecord {
-  customerId: number;
-  customerName: string;
-  accountNumber: string;
-}
-
-export function AddNotesModal({
-  open,
-  onClose,
-  selectedCustomers,
-}: {
-  open: boolean;
-  onClose: () => void;
-  selectedCustomers: CustomerRecord[];
-}) {
-  if (!open) return null;
-
-  const noteTypeOptions = [
-    { value: "1", label: "General Follow-up" },
-    { value: "2", label: "Promise to Pay" },
-  ];
-
-  const templateOptions = [
-    {
-      value: "tmpl-payment",
-      label: "Payment Reminder",
-      subject: "Pending statement follow-up",
-      description: "Contacted accounts payable regarding past-due invoices.",
-    },
-  ];
-
-  return (
-    <div role="dialog" aria-labelledby="modal-heading" className="modal-container">
-      <h2 id="modal-heading">Add Customer Note</h2>
-
-      <div className="form-group">
-        <label htmlFor="notesType">Note Type</label>
-        <select id="notesType" name="notesType" required>
-          {noteTypeOptions.map((opt) => (
-            <option key={opt.value} value={opt.value}>
-              {opt.label}
-            </option>
-          ))}
-        </select>
-      </div>
-
-      <div className="form-group">
-        <label htmlFor="subject">Subject</label>
-        <input id="subject" name="subject" required />
-      </div>
-
-      <div className="form-group">
-        <label htmlFor="notes">Description</label>
-        <textarea id="notes" name="notes" required />
-      </div>
-
-      <div className="modal-actions">
-        <button type="button" onClick={onClose}>
-          Cancel
-        </button>
-        <button type="submit">
-          Save Note
-        </button>
-
-        <BindApiButton
-          appId="collections"
-          windowId="worklist-add-notes"
-          source="Add Notes Dialog"
-          parent="Worklist Grid"
-          grid={{
-            gridId: "worklistUIGrid",
-            rows: selectedCustomers,
-          }}
-          options={{
-            notesType: noteTypeOptions,
-            template: templateOptions,
-          }}
-        />
-      </div>
-    </div>
-  );
-}
-```
-
-#### Example B: Standalone Screen or Drawer without a Grid
-```tsx
-import * as React from "react";
-import { BindApiButton } from "api_binding_ui";
-
-export function CreateDisputeDrawer({ isOpen, onClose }: { isOpen: boolean; onClose: () => void }) {
-  if (!isOpen) return null;
-
-  const reasonCodes = [
-    { value: "PRICING_ERROR", label: "Pricing Discrepancy" },
-    { value: "DAMAGED_GOODS", label: "Damaged Goods" },
-  ];
-
-  return (
-    <aside className="drawer-panel" aria-label="Create Dispute">
-      <h2>Create Dispute</h2>
-
-      <form id="dispute-form">
-        <label htmlFor="reasonCode">Reason Code</label>
-        <select id="reasonCode" name="reasonCode" required>
-          {reasonCodes.map((r) => (
-            <option key={r.value} value={r.value}>{r.label}</option>
-          ))}
-        </select>
-
-        <label htmlFor="amount">Disputed Amount</label>
-        <input id="amount" name="amount" type="number" required />
-
-        <label htmlFor="comments">Comments</label>
-        <textarea id="comments" name="comments" />
-
-        <div className="drawer-footer">
-          <button type="button" onClick={onClose}>Cancel</button>
-          <button type="submit">Submit Dispute</button>
-
-          <BindApiButton
-            appId="receivables"
-            windowId="dispute-create"
-            source="Create Dispute"
-            parent="Disputes Management"
-            options={{
-              reasonCode: reasonCodes,
-            }}
-          />
-        </div>
-      </form>
-    </aside>
-  );
-}
-```
-
----
-
-## Component API Specification
-
-### `<BindApiButton />` Props
-
-| Prop | Type | Default | Description |
-| :--- | :--- | :--- | :--- |
-| `appId` | `string` | `"default"` | Identifier of the parent application module. |
-| `windowId` | `string` | *(Required)* | Stable identifier of the screen, dialog, or form. |
-| `source` | `string` | *(Required)* | Human-readable title of the current screen or action. |
-| `parent` | `string` | *(Required)* | Human-readable title of the parent view or grid. |
-| `grid` | `BindingGrid` | `undefined` | Grid context including `gridId`, `columns`, and `rows` when actions target selected records. |
-| `parents` | `SnapshotContext[]` | `undefined` | Array of parent context hierarchies for multi-level navigation. |
-| `kind` | `WindowKind` | Automatic | `"dialog" \| "drawer" \| "screen" \| "action-form"`. Detected automatically if omitted. |
-| `trigger` | `WindowTrigger` | `undefined` | Metadata regarding the invocation trigger (button text, hotkey, icon). |
-| `options` | `Record<string, BindingOption[]>` | `{}` | Lookup options for select and combobox fields. Supports `{ value, label, subject, description }`. |
-| `definitions` | `ApiDefinition[]` | `[]` | Registered API endpoints catalog available for mapping. |
-| `mappingFile` | `MappingFile \| null` | `null` | Pre-existing mapping file to preload. |
-| `routeBase` | `string` | `"/api-binding"` | Studio route base path configured in the application router. |
-| `containerRef` | `React.RefObject<HTMLElement>` | `undefined` | Explicit DOM reference to the container element. |
-| `containerSelector` | `string` | `undefined` | CSS selector used to locate the enclosing container element. |
-| `rootElement` | `HTMLElement \| null` | `undefined` | Direct DOM element override. |
-| `formId` | `string` | `undefined` | Target HTML `<form id="...">` identifier. |
-| `components` | `SnapshotComponent[]` | `undefined` | Explicit components list overriding automatic DOM discovery. |
-| `buttons` | `string[]` | `undefined` | Explicit action buttons list overriding automatic DOM discovery. |
-| `className` | `string` | `""` | Additional CSS class for the button. |
-| `children` | `React.ReactNode` | `"Bind API"` | Button label or children nodes. |
-
----
-
-## DOM Discovery Protocol
-
-When `<BindApiButton />` is clicked, the context extraction pipeline executes the following sequence:
-
-1. **Container Resolution**:
-   - Checks `rootElement`, `containerRef`, `containerSelector`, and `formId`.
-   - Searches upward for `role="dialog"`, `<dialog>`, or `.ds-dialog`.
-   - Searches upward for `<form>`.
-   - Searches upward for `role="region"`, `[data-drawer]`, `<aside>`, `<main>`, `<section>`, `.drawer`, or `.panel`.
-   - Traverses parent elements to locate any ancestor containing at least two input elements.
-   - Falls back to `document.body`.
-
-2. **Form Control Discovery**:
-   - Evaluates all standard controls (`input`, `select`, `textarea`) and custom ARIA controls (`role="combobox"`, `role="textbox"`, `role="checkbox"`, `role="switch"`).
-   - Resolves control names from `name`, `id`, `data-testid`, `data-field`, or `aria-label`.
-   - Extracts labels from `<label for="...">`, parent `<label>`, `aria-labelledby`, `aria-label`, or field placeholders.
-   - Captures current input values and state (`checked`, `value`, `data-value`).
-
-3. **Action Button Discovery**:
-   - Evaluates buttons and submit inputs within the container.
-   - Excludes modal close controls, minimize/maximize adornments, dismiss triggers, and API binding triggers.
-   - Captures active primary and secondary action labels (e.g., `"Save"`, `"Submit"`, `"Cancel"`, `"Reset"`).
-
----
-
-## Consuming Applied Bindings
-
-When an engineer or analyst clicks **Apply Binding** inside the Studio, the verified configuration is stored in `localStorage` under `api-binding:applied:<key>` and broadcast across active windows.
-
-Host components can listen to applied bindings using the `useAppliedBinding` hook:
-
-```tsx
-import { useAppliedBinding } from "api_binding_ui";
-
-export function AddNotesModal() {
-  const { isApplied, appliedConfig, appliedAt } = useAppliedBinding(
-    "collections.worklistUIGrid.worklist-add-notes"
-  );
-
-  React.useEffect(() => {
-    if (isApplied && appliedConfig) {
-      console.log("Applied API Binding Configuration:", appliedConfig);
-      // Access appliedConfig.calls, appliedConfig.fields, appliedConfig.customerRule
-    }
-  }, [isApplied, appliedConfig]);
-
-  // Render modal
-}
-```
-
----
-
-## Testing and Verification
-
-Run test suites using the bundled test runner:
-
-```bash
-bun test
-# or
-yarn test
-```
-
-Build the distribution package:
-
-```bash
-bun run build
-# or
-yarn build
-```
-
-The build produces:
-- `dist/index.js`: Browser ES module bundle.
-- `dist/api-binding-ui.css`: Compiled style bundle with `--ds-*` design token bridges.
-- `dist/**/*.d.ts`: TypeScript declaration definitions.
-
----
-
-## License
-
-Internal enterprise package. All rights reserved.
+# api_binding_ui
+
+Bind any UI component to documented APIs while a product is being designed, then run those bindings in production.
+
+- **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.
+
+The full contract is in [`spec/FRAMEWORK.md`](spec/FRAMEWORK.md); the types are in [`src/framework/contract.ts`](src/framework/contract.ts).
+
+## Entries
+
+| 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 |
+
+## Runtime
+
+```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
+}
+```
+
+`fetcher` receives `{ method, path, query, headers, body }` and the catalog operation; base URL, auth and errors stay in the app.
+
+## Studio
+
+```tsx
+import { BindingWidget } from "api_binding_ui/studio";
+import "api_binding_ui/studio.css";
+
+// once, inside <BindingProvider persistence={…}>, design mode only
+<BindingWidget framework={{ descriptors, registry }} />
+```
+
+A floating button opens the studio over the app on the screen being shown. Edits apply when it closes.
+
+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.
+
+## Layout
+
+```
+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)
+```
+
+## Develop
+
+```
+bun install
+bun run dev        # studio with sample data on http://localhost:5174
+bun test
+bun run typecheck
+bun run build
+```