@collective-intelligence/external-apps-client-sdk-react 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,141 @@
-# Temporary Holding Version
+# `@collective-intelligence/external-apps-client-sdk-react`
 
-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.
+UI-minimal React bindings over the Promise Client SDK. The package has no private application UI dependencies.
+
+`CollectiveIntelligenceProvider` owns a stable, request-isolated QueryClient. TanStack Query is a normal
+SDK dependency; applications do not install it as a peer or configure a QueryClient for SDK CRUD.
+React and React DOM remain peers.
+
+Configure the provider's `entitySource` once, alongside its existing Promise `client`. `EntitySource`
+exposes a stable `getSnapshot`, a `subscribe` function, and a typed `bind(contract)` function returning
+the common Promise `EntityClient`. Authenticated snapshots identify the configured logical source,
+application, user, and organization. Obtain those identities from the authenticated application
+session; they are cache boundaries, not access grants. Return a new stable snapshot for every session
+transition, notify subscribers immediately on logout, and bind clients to that snapshot's authority.
+Backend authorization remains authoritative. `CollectiveIntelligenceLoginProvider` forwards the same
+configuration; the entity source must subscribe to the application's CI-derived session lifecycle.
+
+```tsx
+;<CollectiveIntelligenceProvider client={appSdk} entitySource={entitySource}>
+  <Orders />
+</CollectiveIntelligenceProvider>
+
+// Import these hooks from /resources. Use the portable entity contract.
+const rows = useEntityList(orderContract, query)
+const record = useEntityRecord(orderContract, { id: selectedId })
+const create = useEntityCreate(orderContract)
+const update = useEntityUpdate(orderContract, { id: selectedId })
+const remove = useEntityDelete(orderContract, { id: selectedId })
+
+await update.submit({ value: draft, expectedRevision: editedRecord.revision })
+// Only on an explicit user request to deliver the same action again:
+await update.resubmit()
+```
+
+Reads expose `data`, `loading`, `refreshing`, `error`, `authState`, effective binding `capabilities`,
+and explicit `refresh`; list reads also expose `empty`. Equivalent requests share data across views.
+Cache identity includes source/application/user/organization and resource/version/query, never view
+namespaces or layout settings.
+
+Writes expose `available`, record-scoped `pending`, `status`, `data`, `error`, `submitted`, `submit`,
+and `resubmit`. Status distinguishes `conflict`, `rejected`, and `uncertain` from ordinary
+`idle`/`pending`/`success`. Submission clones and freezes the draft and reviewed revision and generates
+one operation key. A new submit creates a new action; resubmit preserves the previous action exactly.
+Keep editable drafts in the form and use `submitted` for the retained action; a successful replay
+does not overwrite a newer draft. Same-record update/delete calls serialize across hook instances;
+different records and separate creates remain independent. Queued writes retain their original
+revisions. Form unmount does not cancel a dispatched write. Source transitions clear protected reads
+and reject stale queued actions before dispatch. Queries and mutations never automatically retry;
+there is no persistence, reload recovery, or automatic revision rebasing.
+
+The old public TanStack option factories and native-result resource hooks are no longer exported.
+Use the deliberate entity hooks above. Existing generic slotted `Resource*` presentation remains
+separate from common entity CRUD.
+
+## Declared entity views
+
+Import `defineEntity`, `EntityTable`, `EntityList`, and `EntityForm` from
+`@collective-intelligence/external-apps-client-sdk-react/resources`. Declare
+presentation once alongside the portable contract:
+
+```tsx
+const orders = defineEntity({
+  contract: orderContract,
+  config: {
+    fields: { number: { label: "Order number" } },
+    table: {
+      columns: ["number"],
+      variants: { compact: { columns: ["number"] } }
+    },
+    list: { title: "number" },
+    forms: {
+      create: { fields: ["number"] },
+      update: { fields: ["number"] }
+    }
+  }
+})
+
+// Inside the SDK provider and the host framework's NuqsAdapter:
+<EntityTable entity={orders} namespace="orders-main" />
+<EntityList entity={orders} namespace="orders-sidebar" />
+<EntityTable entity={orders} viewState="memory" variant="compact" />
+<EntityForm entity={orders} mode="update" record={selectedOrder} />
+```
+
+The declaration contains labels, field/control/renderer keys and layouts, with
+no JSX, credentials or storage configuration. Field names are inferred from
+the contract; configured fields must also exist in its portable schema.
+Views render public `ui-react` presentation and share authorized query data
+when their normalized queries match.
+
+URL-backed tables/lists require a stable, distinct namespace. Install the host
+adapter once; the proven TanStack Start integration uses
+`NuqsAdapter` from `nuqs/adapters/tanstack-router` inside the router root.
+Nuqs 2.10.1 owns URL serialization and replace-history updates. Defaults are
+omitted; unrelated keys, other namespaces and the hash are preserved. Invalid
+owned values fall back to defaults. Search/filter/sort changes reset the page.
+For custom controls, use `useEntityViewState(namespace, { contract, pageSize })`;
+it exposes `state`, the normalized `query`, and setters for page, page size,
+search, filters and sorting. `useMemoryEntityViewState` and
+`viewState="memory"` need no URL adapter. View namespaces never enter data keys.
+
+Forms infer scalar, enum, date, nullable and required settings from portable
+schemas. Readonly schema fields cannot become writable through configuration
+and are omitted from submissions. Richer values need a named control in the
+form's `controls` registry; missing controls produce explicit feedback.
+Custom controls receive the field metadata and return JSON wire values.
+Named display renderers are supplied separately through `renderers`.
+
+Pending writes disable overlapping saves. Conflict and unknown-outcome states
+keep the local draft; **Resubmit** sends the captured original action, including
+its key, values and revision. Successful resubmission also keeps newer edits.
+An update form retains the revision its draft began editing when refreshed
+record props arrive. Remount it intentionally (for example with a React `key`)
+after the user chooses to discard the draft and edit a newer server revision.
+Drafts and operation keys never enter the URL.
+
+## Workspace development
+
+See the repository's [Effect demo](../../../demo/external-app-effect/README.md)
+for the same declared Lead views configured against local Gateway, proxied CI,
+and direct CI bindings.
+
+Each package export declares an opt-in `ci-source` condition for workspace development. The local
+TypeScript configuration enables it for the framework-neutral Client SDK, so either package's changes
+are consumed without an intermediate rebuild. Release builds disable custom conditions; installed npm
+consumers resolve generated `dist` JavaScript and declarations. Shared runtime chunks keep provider
+contexts identical across the root and `/resources` entrypoints.
+
+Run `bunx vitest run src`, `bun run type-check`, `bun run lint`, and `bun run test:pack`. The pack check
+executes a real root-provider/resources-hook consumer without caller TanStack setup and removes its
+temporary installation on success or failure.
+
+## Enum value compatibility
+
+Repository-owned enum values use lower `snake_case`. Update gateway manifests,
+request payloads and saved resource filters together with their consumers. For
+example, resource filters use `starts_with` and `is_null`, lifecycle operation
+values use `soft_delete` and `hard_delete`, and gateway principal kinds use
+`detached_user` and `service_principal`. Public method and capability property
+names such as `softDelete` remain unchanged. External HTTP, OAuth, JSON Schema
+and provider values retain their required spelling at their adapter boundaries.