api_binding_ui 1.0.0 → 2.0.0

package/SKILL.md

@@ -1,294 +1,49 @@
----
-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.
+---
+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."
+---
+
+# api_binding_ui: rules for agents
+
+Contract: `node_modules/api_binding_ui/spec/FRAMEWORK.md`. Types: `import type { … } from "api_binding_ui"`.
+
+## 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.
+
+## 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>" }] }
+   ```
+   - `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`.
+   - `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.
+
+## 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

package/dist/framework/contract.d.ts

@@ -0,0 +1,268 @@
+/** Binding framework contract v1. Semantics: spec/FRAMEWORK.md. */
+/** JSON Schema (2020-12). */
+export type JsonSchema = boolean | {
+    [keyword: string]: unknown;
+};
+/** Namespaced component kind, e.g. "acme-ds/grid". */
+export type KindId = string;
+/** Component instance id, unique within its screen. */
+export type BindId = string;
+/** Screen id, e.g. "<product>.<area>.<screen>". */
+export type ScreenId = string;
+/** Expression string; grammar in FRAMEWORK.md §7. */
+export type Expr = string;
+/** RFC 6901 JSON Pointer into a request: "/path/<name>", "/query/<name>", "/header/<name>", "/body/<pointer>". */
+export type RequestPointer = string;
+/** Selector into a response, e.g. "$", "$.items[*]". */
+export type ResponseSelector = string;
+export interface Labelled {
+    label: string;
+    description?: string;
+}
+/** consume: needs data. produce: exposes data. trigger: emits an event that runs API calls. */
+export type SlotRole = "consume" | "produce" | "trigger";
+export interface SlotDescriptor extends Labelled {
+    id: string;
+    role: SlotRole;
+    /**
+     * consume: shape the component needs (per item when `many`).
+     * produce: shape the component provides (per item when `many`).
+     * trigger: payload the event carries.
+     */
+    schema: JsonSchema;
+    many?: boolean;
+    /** The screen is incomplete until this slot is bound. */
+    required?: boolean;
+    /** Evaluated per item of a parent slot (e.g. a cell in a row); `$item` is that item. */
+    scope?: {
+        parentSlot: string;
+    };
+    /** Produce slots of the same component that may feed the request (paging, sort). */
+    feeds?: string[];
+    /** Matching hints from the component author. */
+    hints?: MatchHints;
+}
+export interface MatchHints {
+    /** Words describing the slot, for name matching. */
+    keywords?: string[];
+    /** Operation intents this slot usually binds to. */
+    intents?: string[];
+}
+export interface ChildPolicy {
+    /** Kinds allowed as children; omit for any. */
+    kinds?: KindId[];
+    /** Parent slot children are scoped to (e.g. columns to rows). */
+    scopedTo?: string;
+}
+export interface ComponentDescriptor extends Labelled {
+    kind: KindId;
+    /** Bump on incompatible slot changes; manifests record it. */
+    version: number;
+    slots: SlotDescriptor[];
+    children?: ChildPolicy;
+    /** SVG markup. */
+    icon?: string;
+}
+export interface ComponentInstance {
+    bindId: BindId;
+    kind: KindId;
+    kindVersion: number;
+    label: string;
+    /** Parent component's bindId. */
+    parent?: BindId;
+    /** Display-only configuration; never used for matching. */
+    info?: Record<string, string>;
+}
+export interface ContextDeclaration extends Labelled {
+    /** Name used in expressions: `$context.<id>`. */
+    id: string;
+    /** A schema, or another screen's produce slot whose bound shape it follows. */
+    shape: {
+        schema: JsonSchema;
+    } | {
+        from: {
+            screen: ScreenId;
+            component: BindId;
+            slot: string;
+        };
+    };
+    many?: boolean;
+}
+export interface ScreenEntry extends Labelled {
+    id: ScreenId;
+    /** Navigation path; the first segment is the product. */
+    path: string[];
+    /** Screen this one opens over (dialog, drawer). Grouping only. */
+    parent?: ScreenId;
+    context: ContextDeclaration[];
+    components: ComponentInstance[];
+}
+export interface ScreenRegistry {
+    registryVersion: 1;
+    screens: ScreenEntry[];
+}
+export interface CatalogParameter {
+    pointer: RequestPointer;
+    name: string;
+    required: boolean;
+    schema: JsonSchema;
+    description?: string;
+}
+export interface CatalogOperation {
+    /** operationId. */
+    id: string;
+    method: string;
+    path: string;
+    summary?: string;
+    description?: string;
+    tags: string[];
+    /** Product from the docs' `x-tagGroups`. */
+    product?: string;
+    /** "read" or "write": `x-binding-intent` if declared, else from the HTTP method. */
+    intent?: string;
+    parameters: CatalogParameter[];
+    body?: {
+        required: boolean;
+        schema: JsonSchema;
+    };
+    responses: Array<{
+        status: string;
+        schema?: JsonSchema;
+    }>;
+    /** `x-*` extensions as published. */
+    extensions: Record<string, unknown>;
+}
+export interface Catalog {
+    catalogVersion: 1;
+    source: {
+        title: string;
+        version: string;
+        url?: string;
+    };
+    /** Content hash; manifests pin it. */
+    hash: string;
+    operations: CatalogOperation[];
+    /** Shared schemas referenced by `$ref` inside operations. */
+    schemas: Record<string, JsonSchema>;
+}
+export type BindingOrigin = "manual" | "suggested";
+export type BindingState = "draft" | "confirmed";
+interface BindingBase {
+    component: BindId;
+    slot: string;
+    origin: BindingOrigin;
+    state: BindingState;
+}
+/** consume slot fed by an operation. */
+export interface OperationConsumeBinding extends BindingBase {
+    type: "operation";
+    operation: string;
+    request: Record<RequestPointer, Expr>;
+    /** Where the slot's data is in the response. */
+    select: ResponseSelector;
+    /** Slot-schema property → expression over `$item` (when the slot declares properties). */
+    map?: Record<string, Expr>;
+    /** When to load: on open, on first use, or on an interval. */
+    load?: "open" | "demand" | {
+        everySeconds: number;
+    };
+}
+/** consume slot fed by an expression (row field, another component, context). */
+export interface ExpressionConsumeBinding extends BindingBase {
+    type: "expression";
+    value: Expr;
+}
+/** One API call of a trigger. UI behaviour (open, close, navigate) stays in the app. */
+export interface Step {
+    type: "call";
+    id: string;
+    operation: string;
+    request: Record<RequestPointer, Expr>;
+    forEach?: Expr;
+    onError: "stop" | "continue";
+}
+/** trigger slot that calls APIs in order. */
+export interface TriggerBinding extends BindingBase {
+    type: "steps";
+    steps: Step[];
+}
+/** trigger slot reviewed as calling no API. */
+export interface NoApiBinding extends BindingBase {
+    type: "none";
+}
+export type SlotBinding = OperationConsumeBinding | ExpressionConsumeBinding | TriggerBinding | NoApiBinding;
+export interface BindingManifest {
+    $schema?: string;
+    manifestVersion: 1;
+    screen: ScreenId;
+    catalog: {
+        hash: string;
+    };
+    /** Descriptor versions the bindings were made against. */
+    kinds: Record<KindId, number>;
+    bindings: SlotBinding[];
+}
+/** A named, typed value transform usable as `expr | name(args)`. */
+export interface TransformDefinition extends Labelled {
+    name: string;
+    input: JsonSchema;
+    output: JsonSchema;
+    apply: (value: unknown, ...args: unknown[]) => unknown;
+}
+/** Supplies `$<id>` values (e.g. the signed-in user). Registered by the host app. */
+export interface ContextProvider extends Labelled {
+    id: string;
+    schema: JsonSchema;
+    read: () => unknown;
+}
+export interface MatchInput {
+    screen: ScreenEntry;
+    component: ComponentInstance;
+    descriptor: ComponentDescriptor;
+    slot: SlotDescriptor;
+    operation: CatalogOperation;
+    catalog: Catalog;
+}
+export interface MatchResult {
+    /** 0..1 */
+    score: number;
+    /** Reasons shown in the studio. */
+    reasons: string[];
+    /** Proposed request/map entries, if the matcher can propose them. */
+    proposal?: Partial<Pick<OperationConsumeBinding, "request" | "select" | "map">> | Partial<Pick<TriggerBinding, "steps">>;
+}
+/** Scores one operation for one slot; matchers combine by weight. */
+export interface Matcher {
+    id: string;
+    weight: number;
+    score: (input: MatchInput) => MatchResult | null;
+}
+/** Per-product synonyms, loaded as data. */
+export interface Glossary {
+    product: string;
+    /** Groups of words that mean the same thing in this product. */
+    synonyms: string[][];
+}
+export interface PersistenceAdapter {
+    load: (screen: ScreenId) => Promise<BindingManifest | null>;
+    save: (manifest: BindingManifest) => Promise<void>;
+}
+export interface FrameworkRegistry {
+    registerDescriptor: (descriptor: ComponentDescriptor) => void;
+    registerTransform: (transform: TransformDefinition) => void;
+    registerContext: (provider: ContextProvider) => void;
+    registerMatcher: (matcher: Matcher) => void;
+    registerGlossary: (glossary: Glossary) => void;
+    setPersistence: (adapter: PersistenceAdapter) => void;
+}
+export type IssueSeverity = "error" | "warning";
+export interface ValidationIssue {
+    severity: IssueSeverity;
+    screen: ScreenId;
+    component?: BindId;
+    slot?: string;
+    /** Stable machine code, e.g. "slot.required-unbound", "schema.incompatible", "catalog.operation-missing". */
+    code: string;
+    message: string;
+}
+export {};