api_binding_ui 0.0.0-stage → 1.0.0

package/README.md

@@ -1,3 +1,384 @@
-# 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 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.

package/SKILL.md

@@ -0,0 +1,294 @@
+---
+name: api-binding-ui
+description: Instructions for AI agents to integrate API Binding Studio (api_binding_ui) into React application screens, modals, drawers, and forms.
+---
+
+# API Binding Studio Integration Skill
+
+This skill defines the operational standards and technical requirements for AI agents integrating `api_binding_ui` into frontend codebases. Follow these instructions whenever adding, updating, or maintaining action dialogs, flyout drawers, forms, or data grid action bars.
+
+---
+
+## 1. When to Apply This Skill
+
+Apply this skill whenever any of the following conditions are met:
+1. The user asks to bind, map, or connect a screen, dialog, modal, drawer, or action form to backend APIs.
+2. The user requests an API binding trigger button on an action modal (such as "Add Notes", "Create P2P", "Dispute Invoice", "Edit Customer", "Assign Task").
+3. The application requires visual mapping, request payload previewing, or zero-network simulated validation across selected table/grid records.
+4. Setting up the `/api-binding/$key` studio route in an application router.
+
+---
+
+## 2. Dependency Verification
+
+Verify that `package.json` contains `api_binding_ui`:
+
+```json
+{
+  "dependencies": {
+    "api_binding_ui": "file:../api_binding_ui"
+  }
+}
+```
+
+If missing, add it to dependencies or prompt the user to link the local package.
+
+---
+
+## 3. Router Setup Requirements
+
+Every application using `api_binding_ui` must declare a route matching `/api-binding/$key`.
+
+### 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" }],
+  }),
+  component: ApiBindingRouteView,
+});
+
+function ApiBindingRouteView() {
+  const { key } = Route.useParams();
+  return <ApiBindingWorkspace key={key} pageKey={key} />;
+}
+```
+
+### React Router (`src/routes/ApiBindingRoute.tsx`)
+```tsx
+import { useParams } from "react-router-dom";
+import { ApiBindingWorkspace } from "api_binding_ui";
+import "api_binding_ui/style.css";
+
+export function ApiBindingRoute() {
+  const { key = "default" } = useParams<{ key: string }>();
+  return <ApiBindingWorkspace key={key} pageKey={key} />;
+}
+```
+
+---
+
+## 4. Host Form Integration Rules
+
+When rendering forms, modals, or drawers that will be bound to APIs, AI agents MUST follow these structural rules:
+
+### Rule 1: Form Inputs Must Have Identifiers
+Every form control (`<input>`, `<select>`, `<textarea>`, or custom combobox) MUST have a `name` attribute matching the semantic field name (or an `id`, `data-testid`, or `aria-label`).
+- Correct: `<input name="subject" required />`
+- Incorrect: `<input placeholder="Subject" />` (lacks identifier, will be ignored by DOM discovery).
+
+### Rule 2: Explicit Labels
+Controls should be paired with standard `<label htmlFor="...">` tags or include `aria-label`. The studio extracts human-readable field labels from these associations.
+
+### Rule 3: Pass Dropdown Options via `options` Prop
+Dropdown choices captured in state or constants must be passed to `<BindApiButton />` using the `options` prop:
+```tsx
+const noteTypeOptions = [
+  { value: "1", label: "General Follow-up" },
+  { value: "2", label: "Promise to Pay" },
+];
+
+const templateOptions = [
+  {
+    value: "tmpl-1",
+    label: "Payment Reminder",
+    subject: "Payment Reminder",
+    description: "Followed up with customer regarding pending invoices.",
+  },
+];
+
+<BindApiButton
+  // ...
+  options={{
+    notesType: noteTypeOptions,
+    template: templateOptions,
+  }}
+/>
+```
+
+### Rule 4: Pass Grid Selection when Targeting Grid Rows
+If the action is triggered from or operates on selected table/grid rows:
+```tsx
+<BindApiButton
+  // ...
+  grid={{
+    gridId: "worklistUIGrid",
+    rows: selectedRecords,
+  }}
+/>
+```
+If the screen does not operate on a grid (such as a standalone dispute creation screen or customer profile editor), omit the `grid` prop. The studio automatically adapts its target context view and simulation engine to direct screen input.
+
+---
+
+## 5. Complete Implementation Patterns
+
+### Pattern A: Modal Dialog Triggered from a Data Grid
+```tsx
+import * as React from "react";
+import { BindApiButton } from "api_binding_ui";
+
+interface CustomerRecord {
+  customerId: number;
+  customerName: 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: "Reminder: Invoice due",
+      description: "Contacted customer regarding pending balance.",
+    },
+  ];
+
+  return (
+    <div role="dialog" aria-labelledby="dialog-title" className="ds-dialog">
+      <h2 id="dialog-title">Add Notes</h2>
+
+      <div className="form-group">
+        <label htmlFor="notesType">Notes 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="button-bar">
+        <button type="button" onClick={onClose}>Cancel</button>
+        <button type="submit">Submit</button>
+
+        <BindApiButton
+          appId="collections"
+          windowId="worklist-add-notes"
+          source="Add Notes"
+          parent="Worklist Grid"
+          grid={{
+            gridId: "worklistUIGrid",
+            rows: selectedCustomers,
+          }}
+          options={{
+            notesType: noteTypeOptions,
+            template: templateOptions,
+          }}
+        />
+      </div>
+    </div>
+  );
+}
+```
+
+### Pattern B: Standalone Drawer or Form without Grid
+```tsx
+import * as React from "react";
+import { BindApiButton } from "api_binding_ui";
+
+export function DisputeDrawer({ open, onClose }: { open: boolean; onClose: () => void }) {
+  if (!open) return null;
+
+  const disputeReasons = [
+    { value: "DAMAGED", label: "Damaged Goods" },
+    { value: "PRICING", label: "Incorrect Pricing" },
+  ];
+
+  return (
+    <aside className="drawer-container" aria-label="Create Dispute">
+      <h2>Create Dispute</h2>
+
+      <form id="dispute-form">
+        <label htmlFor="reasonCode">Dispute Reason</label>
+        <select id="reasonCode" name="reasonCode" required>
+          {disputeReasons.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-actions">
+          <button type="button" onClick={onClose}>Cancel</button>
+          <button type="submit">Submit Dispute</button>
+
+          <BindApiButton
+            appId="receivables"
+            windowId="disputes-create"
+            source="Create Dispute"
+            parent="Disputes Management"
+            options={{
+              reasonCode: disputeReasons,
+            }}
+          />
+        </div>
+      </form>
+    </aside>
+  );
+}
+```
+
+---
+
+## 6. Listening to Applied Configurations
+
+When the user verifies and applies an API binding inside the Studio, the configuration is stored in browser storage. The parent screen can react to this using `useAppliedBinding`:
+
+```tsx
+import { useAppliedBinding } from "api_binding_ui";
+
+export function ScreenComponent() {
+  const { isApplied, appliedConfig } = useAppliedBinding(
+    "collections.worklistUIGrid.worklist-add-notes"
+  );
+
+  React.useEffect(() => {
+    if (isApplied && appliedConfig) {
+      // Configuration applied: access appliedConfig.calls or appliedConfig.fields
+    }
+  }, [isApplied, appliedConfig]);
+}
+```
+
+---
+
+## 7. Agent Verification Checklist
+
+Before completing an integration task, the AI agent must verify:
+1. `name` attributes are assigned to all form controls on the host screen.
+2. The `<BindApiButton />` has accurate `appId`, `windowId`, `source`, and `parent` strings.
+3. Dropdown choices are forwarded in the `options` record.
+4. The application router has an active route at `/api-binding/$key` mounting `<ApiBindingWorkspace />`.
+5. No emojis or informal characters are introduced into the code or documentation.