@capxul/sdk-react 0.0.0-rc-2cdddbb91

package/README.md

@@ -0,0 +1,131 @@
+# `@capxul/sdk-react`
+
+The React projection over `@capxul/sdk`. It owns provider lifecycle, the one
+canonical identity projection, renderer-neutral identity controllers, TanStack
+Query bindings for rich data, and authenticated-cache cleanup.
+
+```tsx
+"use client";
+
+import { CapxulProvider } from "@capxul/sdk-react";
+
+export function Providers({ children }: { children: React.ReactNode }) {
+  return (
+    <CapxulProvider publishableKey={process.env.NEXT_PUBLIC_CAPXUL_PUBLISHABLE_KEY!}>
+      {children}
+    </CapxulProvider>
+  );
+}
+```
+
+## Public shape
+
+- `useCapxulIdentity`, `useCapxulDestination`, and `useCapxulTransitions`
+  expose the Core SDK identity actor without a parallel React state model.
+- `useCapxulSend` carries caller-owned invocation controls to that actor.
+- `useCapxulAuth` is the stable six-verb application facade.
+- The provider restores Account readiness after a complete authenticated
+  session. Account and Organization readiness transitions refresh active
+  authenticated queries.
+- CapxulAuthenticationController and CapxulOnboardingController select
+  app-owned slots and render no SDK-owned DOM. Organization create begins a
+  backend setup and returns its exact ID. The Core SDK actor subscribes to
+  that setup. Awaiting authorization, attention, and failure reach actionable
+  slots; processing and rechecking reach a finite progress slot.
+- CapxulDashboardAccess combines current setup with current org.me authority.
+  Initial and changed scopes wait for verified authority. Unchanged setup
+  snapshots reuse cached data. Background authority checks keep an already
+  verified ready dashboard mounted. Non-ready setup, sign-out, scope changes,
+  and authority errors close access. A revoked membership cannot keep a grant.
+- Rich-data hooks such as `useCapxulProfile`, `useCapxulOrgs`, members, roles,
+  treasury, and money hooks remain TanStack Query projections. Personal
+  holdings and activity reads start only after the Account is claimed.
+- `CapxulActivity` is the compound activity component. One root owns fetching,
+  paging, filtering, searching, the summary numbers, row meaning, memo saving
+  and CSV building, and draws nothing. The `.Summary`, `.Filters`, `.Search`,
+  `.Rows`, `.LoadMore`, `.Detail` and `.Export` region parts each hand the
+  screen one finished slice, so the same component serves a ten-row dashboard
+  card and a full transactions page. Paging is infinite scroll through a
+  sentinel ref; `.Export` pages at the backend maximum and stops at 5,000 rows
+  rather than draining a ledger. Detail state and reads stay scoped to the root
+  actor.
+- `capxulKeys` is the public query-key catalog. An application invalidates SDK
+  lanes with it instead of keeping a parallel key namespace.
+- `useCapxulHoldings` takes an optional `actor`, and its cache entry is keyed by
+  that actor.
+- `CapxulSendMoney` is the compound send component. One root owns the send
+  behaviour and draws nothing. The `.Source`, `.Asset`, `.Amount`, `.Recipient`,
+  and `.Actions` region parts each hand the screen one finished slice. The
+  engine hook stays module-scoped. Both actor paths ship: a personal actor omits
+  `.Source` and spends the personal Account; an organization actor holds the
+  Budget the payment is drawn from and spends the treasury Account.
+  The submitted amount uses the selected registry AssetId and precision. This
+  includes 18-decimal WETH.
+- `CapxulContacts` is the compound address-book component. One root owns the
+  book behaviour and draws nothing. The `.Summary`, `.List`, and `.Add` region
+  parts each hand the screen one finished slice, and a `.List` row carries its
+  own `rename`, `hide`, and `unhide` verbs. A screen places any subset. Both
+  actor paths ship: a personal actor reads the account book, and an
+  organization actor reads the organization book. The `managePeople` capability
+  gate stays in the app, on `CapxulOrgMember.Can`.
+- `CapxulPayroll` and `CapxulPayrollRun` are the two payroll compound
+  components. `CapxulPayroll` owns the payroll page's reads through its
+  `.Summary` and `.Groups` region parts; `CapxulPayrollRun` owns the run
+  composer through `.Recipients`, `.Amounts`, `.Asset`, `.Summary`, and
+  `.Actions`. A screen places any subset — the pay-now sheet places all five
+  run parts, the group sheet places two. `.Actions.blockedReason` names the
+  first false fact as a `CapxulPayrollRunBlockedReason` code, never a
+  sentence. `.Amounts` prefills a row from the organization's active engagement
+  terms when the run's period can state that rate — the value stays editable,
+  and an amount the caller passed in `prefill` wins over it. Both engine hooks
+  stay module-scoped.
+
+Activity groups use AssetId. The SDK resolves symbols and precision only for
+display and CSV output. Assets with the same peg remain separate.
+
+Payroll confirmation restores a saved run before enabling submission. An
+uncertain run keeps its period, amounts, recipients, and SDK request key across
+close/reopen and reload. Its fields remain fixed until Core confirms success or terminal closure.
+Use `.Actions.recovery` and `.Actions.recoveryError` to present recovery and
+storage errors. Group editors without `.Actions` keep their editable drafts.
+The application still owns the surrounding sheet and error copy.
+
+The packed npm package exposes `@capxul/sdk-react` and
+`@capxul/sdk-react/testing`. The workspace-only `@capxul/sdk-react/headless`
+subpath is not published.
+
+```tsx
+import { createCapxulReactTestHarness } from "@capxul/sdk-react/testing";
+
+const harness = createCapxulReactTestHarness();
+const tree = harness.provider(harness.authentication(slots));
+await harness.testing.close();
+```
+
+The testing harness uses the real public provider and controllers and imports
+its client factory only through `@capxul/sdk/testing`; it owns no renderer or
+parallel identity state.
+
+## Activity documents
+
+`CapxulActivity.Detail` exposes `documents`, `selectedDocument`, and
+`selectDocument({ documentHash, contentHash })`. Selection defaults to the
+instruction, then the Movement Memo. `renderDocument()` returns safe semantic
+HTML. `downloadDocument()` returns exact bytes for a deliberate download.
+The host owns the panel and download action. Do not log these results.
+Account or Organization changes clear selection and cancel pending reads.
+These methods replace the receipt-only selector and action.
+
+## Documentation
+
+- [Maintainer context](./CONTEXT.md)
+- [Architecture](./docs/architecture.md)
+- [Proof map](./docs/proof.md)
+
+## Development
+
+```bash
+vp run --filter @capxul/sdk-react check-types
+vp run --filter @capxul/sdk-react test
+(cd packages/sdk-react && vp pack)
+```