api_binding_ui 0.0.0-stage → 1.1.0

package/README.md

@@ -1,3 +1,394 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# API Binding Studio (api_binding_ui)
+
+API Binding Studio (`api_binding_ui`) is a browser-side visual API mapper with generic offline request validation. Import OpenAPI contracts, propose editable component mappings, inspect request parts and validate their schemas without calling a server. Validation is not an end-to-end API test or proof of authorization/server behavior.
+
+Version 1.1.0 adds `buildCatalogFromOpenApi(parsedDocument)`, operation descriptions/tags, location-aware parameters, JSON object conversion, headers, `validateRequest`, `validateBindings` and context-sensitive `verificationSignature`. The workspace uses the generic `ValidationDialog`; legacy note simulation exports remain available separately. See [SKILL.md](./SKILL.md) for the complete host integration and seed examples.
+
+---
+
+## 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 Request Validation (`src/components/ValidationDialog.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.
+- Ajv validates supported JSON Schema request constraints for all configured read/write calls using captured or user-supplied sample inputs.
+- Validation signatures cover configuration, contracts and captured context. They are consistency checks, not cryptographic security or server verification. No fake saved-record retrieval is required.
+- Multiple selected rows can supply array values; scalar row parameters require one row. There is no live request executor or automatic per-row dispatch.
+
+---
+
+## Installation
+
+After the 1.1.0 release has been published, install it from npm:
+
+```bash
+npm install api_binding_ui@1.1.0
+# 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.
+
+Supply a complete `ApiDefinition[]` catalog and a per-window `MappingFile` seed. For an OpenAPI file attached to an AI coding task, generate the static catalog from the attachment; the app does not need to store or parse YAML at runtime. If the host already has a parsed OpenAPI 3.0/3.1 object, it may use `buildCatalogFromOpenApi(parsedOpenApi)`. Neither catalog discovery nor semantic mapping inference happens automatically at runtime. Have the host AI generate high-confidence seeds using OpenAPI names, descriptions, tags and actual components; leave ambiguities editable. A `hook` string identifies a catalog operation; it does not create an executable hook.
+
+#### Example A: Dialog with Data Grid Context
+```tsx
+import * as React from "react";
+import { BindApiButton, type ApiDefinition, type MappingFile } from "api_binding_ui";
+
+interface CustomerRecord {
+  customerId: number;
+  customerName: string;
+  accountNumber: string;
+}
+
+export function AddNotesModal({
+  open,
+  onClose,
+  selectedCustomers,
+  definitions,
+  mappingFile,
+}: {
+  open: boolean;
+  onClose: () => void;
+  selectedCustomers: CustomerRecord[];
+  definitions: ApiDefinition[];
+  mappingFile: MappingFile;
+}) {
+  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
+          definitions={definitions}
+          mappingFile={mappingFile}
+          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, type ApiDefinition, type MappingFile } from "api_binding_ui";
+
+export function CreateDisputeDrawer({ isOpen, onClose, definitions, mappingFile }: { isOpen: boolean; onClose: () => void; definitions: ApiDefinition[]; mappingFile: MappingFile }) {
+  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
+            definitions={definitions}
+            mappingFile={mappingFile}
+            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` | `"app"` | 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` | Invocation metadata: `button`, `needsSelection`, `gridId`. |
+| `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 * as React from "react";
+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
+
+`useAppliedBinding` observes stored configuration only; the host retains responsibility for any live execution, response-to-field population and durable persistence. Draft edits take precedence over new seeds. Captured context lives in same-origin browser storage; exclude sensitive fields and keep credentials out of snapshots and fixed values. External schema references must be bundled before import. Cookie parameters, non-JSON bodies, non-object root bodies and unsupported wire serialization produce contract limitations rather than network fallbacks.
+
+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.
+
+## Manual Release
+
+The original Bun/PowerShell build scripts are unchanged. Run `bun test`, `bun run build`, then `npm pack --dry-run` and inspect the archive/exports. Publish version 1.1.0 yourself using `npm publish` after reviewing the diff. This project has not been published automatically. The Lovable handoff prompt is a separate local document, not part of the npm package's files list.
+
+---
+
+## License
+
+Internal enterprise package. All rights reserved.