@stapel/workspaces-react 0.1.0 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,83 @@
 # @stapel/workspaces-react
 
+## 0.4.0
+
+### Minor Changes
+
+- b1b327e: Track stapel-workspaces 0.4.x (scheme B; contract pin bumped to the `0.4.1`
+  HEAD — G12 anchor pagination for member listing). **Breaking**: `GET
+/{id}/members` is no longer a flat array wrapper — it is now an
+  anchor-paginated page (core `AnchorPagination`, the same shape as
+  notifications-react's feed), matching the backend's move off unbounded member
+  listing:
+
+  - **`MemberListData`** (the `MemberList` export) now aliases
+    `PaginatedMemberResponseList` — `{ items, next_anchor, prev_anchor, has_next,
+has_prev, count }` — instead of `{ members }`. Read `.items` where you used
+    to read `.members`.
+  - **`useMembers(workspaceId, params?)`** takes an optional second
+    `MembersParams` (`{ anchor, direction, limit, search }`, all optional; no
+    params fetches the newest page, default limit 100/max 500) and its query key
+    now carries those params (`workspacesQueryKeys.membersPage`); the bare
+    `workspacesQueryKeys.members(workspaceId)` prefix still invalidates every
+    page (mutations unchanged).
+  - **`WorkspacesApi.listMembers(workspaceId, params?)`** sends
+    `?anchor=&direction=&limit=&search=`.
+  - `<Members>` (headless) is unaffected at the call-site level — it still hands
+    `children` a flat `members` array (now sourced from the page's `.items`,
+    first page only; a follow-up can add pager controls to its bag for consumers
+    with >100 members).
+
+  `backend.contract` is now `>=0.4 <0.5`.
+
+### Patch Changes
+
+- 2fa025a: §17 arch-contract-pipeline Wave 2 + Wave 3 — the five original pairs are now
+  self-contained per-module contracts, aligned to their backend minor.
+
+  **Wave 2 (contract isolation).** Each pair generates its typed surface from its
+  backend module's OWN committed `docs/{schema,flows}.json` (byte-identical to the
+  former monolith slice) instead of the unified monolith aggregate:
+
+  - `gen:api` emits a package-LOCAL `src/api/generated/schema.ts` per pair (via the
+    `API_SCHEMA`/`API_OUT` knobs — the calendar/recordings §17-native shape);
+    `api/types.ts` aliases `components` from `./generated/schema.js`, no longer from
+    `@stapel/core`. `@stapel/core` stays a RUNTIME peer (client / react-query),
+    not the type source.
+  - `gen:flows` reads `../stapel-<mod>/docs/flows.json`; `gen:manifest` reads the
+    per-module `docs/schema.json`. Public types are unchanged — the repoint is a
+    zero-diff source-swap (byte-identity proven), so no consumer breaks.
+
+  **Wave 3 (version scheme B).** Each pair's minor now tracks its backend minor:
+  `auth-react → 0.5.0` (stapel-auth 0.5.x), `notifications-react → 0.3.0`,
+  `profiles-react → 0.3.0`, `billing-react → 0.4.0`, `workspaces-react → 0.3.0`.
+  `manifest.backend.contract` records the one-minor compatibility window
+  (`>=0.5 <0.6` etc.), auto-derived from the backend `pyproject.toml`.
+
+- 4e6f442: Internal plumbing swap (slim wave §21/S2) — the pair's stamped
+  `model/runtime.ts` / `model/context.tsx` / `headless/<Mod>Provider.tsx`
+  boilerplate (byte-identical across the six standard pairs) now binds
+  `@stapel/core`'s `createModuleRuntime` / `createModuleContext` factories
+  instead of carrying its own copy. Public API preserved exactly: same exported
+  names and signatures (`create<Mod>Runtime`, `<Mod>Runtime`,
+  `Create<Mod>RuntimeOptions`, `<Mod>RuntimeContext`, `use<Mod>Runtime`,
+  `use<Mod>Api`, `use<Mod>Analytics`, `<Mod>Provider>`), same guard-hook error
+  messages. No behavior change.
+- c3482e7: README wave (slim wave §21/S4): every pair now documents its setup — a new
+  Install + "Wire the app once" section built on core's `<StapelProvider>`
+  (previously only auth-react's README showed any wiring, as a 5-level provider
+  nest). auth-react's wiring example moves to the one-provider shape with the
+  `queryRuntime`/`i18n` escape hatches spelled out.
+- d3232a9: Zero-flow scaffolding removed (slim wave §21/S3). These six backends annotate
+  no `@flow_step`, so `gen:flows` now skips emission for them and the pair's
+  `src/flows/generated/` files are gone. The public flow surface is preserved
+  exactly by a tiny hand-written shim (`src/flows/registry.ts`): `<MOD>_FLOWS`
+  (still `{}`), `<Mod>FlowId`/`<Mod>FlowSpec` (still `never`), `FlowEndpoint`,
+  and `flowEndpoints` keep their names, types, and behavior. `toFlowError` and
+  the core flow-machine re-exports are untouched. No public-surface delta; the
+  generated registry returns automatically once the backend documents its first
+  flow.
+
 ## 0.1.0
 
 ### Minor Changes

package/README.md

@@ -5,18 +5,60 @@ Headless React flow pair for stapel-workspaces: typed API client, TanStack Query
 Headless React flow pair for **stapel-workspaces** (frontend-standard §2). Business +
 state only, zero visual opinion — any design layers on top. Built on
 `@stapel/core` (typed client + `StapelApiError` envelope, token refresh,
-verification-403 interception, i18n engine, analytics facade, TanStack Query).
+verification-403 interception, i18n engine, analytics seam, TanStack Query).
 
 Scaffolded by `stapel-new-react-lib`. See `MODULE.md` for the layer map, machine
 table, extension seams, and persist policy.
 
+## Install
+
+```
+pnpm add @stapel/workspaces-react @stapel/core @tanstack/react-query react
+```
+
+## Wire the app once
+
+One `<StapelProvider>` for the whole app (core's config + query + i18n in a
+single component — slim wave §21/S4), one `<WorkspacesProvider>` for this pair:
+
+```tsx
+import { createI18n, StapelProvider } from "@stapel/core";
+import {
+  createWorkspacesRuntime,
+  WorkspacesProvider,
+  registerWorkspacesI18n,
+} from "@stapel/workspaces-react";
+
+const runtime = createWorkspacesRuntime({ baseUrl: "/workspaces/api/" });
+const i18n = createI18n({ locale: "en" });
+registerWorkspacesI18n(i18n); // the pair's key bundle → core's engine
+
+export function Root({ children }: { children: React.ReactNode }) {
+  return (
+    <StapelProvider client={runtime.client} i18n={i18n} cacheVersion="0.1.0">
+      <WorkspacesProvider runtime={runtime}>{children}</WorkspacesProvider>
+    </StapelProvider>
+  );
+}
+```
+
+Hooks and headless components work anywhere below `<WorkspacesProvider>`
+(`useWorkspacesApi`, the query/mutation hooks, the render-prop components — see
+`MODULE.md`). Already wired a `<StapelProvider>` for another pair (or
+auth-react)? Keep the ONE provider: pass this runtime's client as a
+per-module override — `clients={{ workspaces: runtime.client }}` — and nest
+`<WorkspacesProvider>` next to your other pair providers. The individual core
+providers (`StapelConfigProvider` + `QueryClientProvider` + `I18nProvider`)
+remain exported for bespoke composition.
+
 ## Layers
 
 ```
 src/
   api/        typed client — thin adapter over @stapel/core `components`
   model/      query keys, runtime wiring, context/hooks
-  flows/      createFlowMachine flow machines (+ generated registry)
+  flows/      toFlowError + zero-flow registry shim (machines + generated
+              registry arrive with the backend's first @flow_step)
   headless/   renderless components (WorkspacesProvider, flow render-props)
   i18n/       translation keys + generated backend error map
   analytics/  generated typed-event registry (events.json)
@@ -27,7 +69,7 @@ demo/         first-class demos (compiled, product-linted, smoke-rendered)
 
 | Surface | Path | Gate |
 |---|---|---|
-| Flow registry | `src/flows/generated/` | `pnpm gen:flows:check` |
+| Flow registry | none — zero-flow module (`src/flows/registry.ts` shim); `gen:flows` emits `src/flows/generated/` once the backend documents flows | `pnpm gen:flows:check` |
 | Backend error map + en bundle | `src/i18n/generated/` | `pnpm gen:errors:check` |
 | Typed-event registry | `src/analytics/generated/events.json` | `pnpm gen:events:check` |
 | Demos → Ladle stories | `demo/generated/` | `pnpm gen:demos:check` |