@ai-matrx/associations 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,100 @@
 # Changelog — @ai-matrx/associations
 
+## 0.3.0 — 2026-08-29 (unreleased; W3 + W4 of the extraction)
+
+Waves 3 and 4: the `/react` subpath — the seven hooks riding the /core store
+via `useSyncExternalStore`, and the faces/pickers/capture toolbar. Behavior
+ported VERBATIM from the matrx-frontend originals (re-read in full
+2026-08-29); only the measured seams inverted onto the W1 ports. `/react` is
+the package's ONE banner group: its dist chunks carry `"use client"` (tsup
+banner + `scripts/stamp-client-boundary.mjs` belt); the root and `/core`
+stay pure, and `verify-tarball` now proves both directions.
+
+- **`AssociationsProvider` (`src/react/context.tsx`)** — the one React
+  binding point: the host constructs the /core store in its binding module
+  and mounts the provider with the five UI ports (notifier / windowShell /
+  capture / pickerOverrides / entityDoors). Every hook/face reaches the
+  store via `useAssociationsStore()`, which THROWS with a precise message
+  when no provider is mounted. `useNotifier()` implements the notifier
+  degradation: absent → warn ONCE via errorSink, every user-facing failure
+  still screams to the sink.
+- **W3 hooks, signatures byte-compatible with the originals** (the W5 swap
+  is a re-export flip + Redux-fragment deletion, call sites unchanged):
+  `useAssociations` (+ `useEntityRelationships` alias + re-exported
+  `AssociationWriteResult`), `useContainerLinks` (incl. the viewer-aware
+  `conversation_files` branch, generation/stale guards verbatim),
+  `useEntityTitles` (labels never exempt the liveness read; one settled
+  round proves absence), `useCategories`, `useUniversalEntitySearch`
+  (debounce + recents via `ues_list`), `useAssociationCandidates`,
+  `useAssociationEntitySelectAdapter` (+ the
+  `AssociationEntitySelectAdapter` contract, which now lives with the
+  hook). Redux selectors/thunks → `useSyncExternalStore` over the store;
+  `@/lib/toast` → notifier; `console.error` → errorSink; the host `Json`
+  type → `unknown` (`ContainerLink.metadata`, `attach` metadata).
+  `useAssociationCandidates`' Redux `selectUserId` read became a LENIENT
+  identity-port read (null when unauthenticated): `ownerId` is a
+  candidate-read filter, not an auth gate — write paths keep the loud
+  `requireUserId` contract.
+- **W4 faces**: `AssociationCard`, `AssociationCardGrid`, `AssociationList`
+  (+ `ContainerResourcesAdapter` + `useContainerLinksAdapter`),
+  `AssociationPicker` (+ `AssociationCandidateBody` + the
+  create-then-associate footer), `UniversalAssociationPicker`,
+  `AttachedItemsSheet`, `AssociationCaptureToolbar`, `AssociationWindow`,
+  `PrimaryEntityProvider`/`usePrimaryEntity`, plus the content-role chrome
+  (`CONTENT_ROLES`/`getContentRoleMeta` — display metadata is /react's;
+  the classification stays /core's) and the door-seam helpers
+  (`DoorRef`/`UnresolvedRef`).
+- **Seam inversions (deliberate, per the design's Decision 2 table)**:
+  - the hardcoded `token === "file"` → FilePickerWindow branch became the
+    `pickerOverrides` port: `AssociationPicker` routes a registered token to
+    its override component (same `AssociationPickerProps` contract);
+    `UniversalAssociationPicker`'s browse mode opens the override too, so
+    "file enumeration only happens through the canonical picker" survives
+    the inversion; with no override the generic candidate list serves every
+    token (the documented degradation);
+  - `WindowPanel` → the `windowShell` port; absent → a package-internal
+    fixed centered overlay (non-draggable, same anatomy, page behind stays
+    interactive);
+  - `EntityRef`/`EntityDoorControls`/access-gate `UnresolvedEntityRef` →
+    the `entityDoors` port; absent → title text with the overlay `hrefFor`
+    anchor when present, plain text otherwise, and the package's plain
+    "Unavailable" chip for unreadable targets;
+  - the capture toolbar's `features/files` + `features/data-tables` imports
+    → the `capture` port, PER-HANDLER optional: chips render only when
+    their handler exists, zero handlers → no toolbar and no drop zone
+    (never dead buttons, never a drop that swallows files). The original's
+    "Add document" picker (a host command palette over
+    `listAccessibleDocuments`) has no capture handler by design — hosts
+    append it via `extraActions`. "New document" collects its name with an
+    inline input row (the original's `TextInputDialog` is host chrome) and
+    opens the created document through the registry's `hrefFor` overlay
+    instead of a hardcoded `/documents/…` route;
+  - lucide icons → the package's own inlined SVGs (C19); host shadcn
+    `Input`/`Skeleton`/`Button`/`cn` → `@ai-matrx/design-system` (new
+    OPTIONAL peer at the `>=0.2.0` floor, per C18 — never vendored twins).
+- **Store additions (additive, /core)**: `AssociationsStore` now exposes
+  the bound `errorSink` and `identity` so /react surfaces scream and read
+  identity without a second binding.
+- **W4 gaps (deliberately NOT built — design-system 0.2.0 lacks the
+  primitives; vendoring twins is banned)**: `AssociationEntitySelect`,
+  `CategorySelect`, `CategoryTagPicker`. They need a Command/combobox
+  family (cmdk-style CommandInput/List/Item/Group/Empty + CommandDialog),
+  a Select, and the CreatablePicker composite. The
+  `AssociationEntitySelectAdapter` contract + default adapter hook (the
+  Redux-free seam) shipped anyway, so those faces are a pure-chrome build
+  once design-system grows.
+- Tests: 131 (from 97) — jsdom behavioral suites per hook (subscription
+  updates, in-flight dedup across two consumers, error surfaces,
+  create-then-attach retry + loud outcome) and per face (render +
+  interaction against fake ports, every degradation branch: no windowShell,
+  no entityDoors, picker override routing, zero capture handlers,
+  created-but-unlinked screams).
+- Gate: `pnpm typecheck && pnpm test && pnpm check:package` green; the
+  tarball canary installs react + react-dom + `@ai-matrx/design-system`
+  (npm, 0.2.0) into the empty project and imports AND requires `/react`,
+  proves the `"use client"` banner on both /react chunks and its absence
+  on all four pure chunks.
+
 ## 0.2.0 — 2026-08-29 (unreleased; W2 of the extraction)
 
 Wave 2: the headless owns-persistence `/core` subpath — the service

package/README.md

@@ -4,11 +4,12 @@ THE one way to relate two entities on the AI Matrx platform: association edges,
 categories, favorites/recents, and the generated entity-type vocabulary — shipped
 as one package a Matrx client or enterprise app installs.
 
-**v0.2 ships the types root and the headless `/core`** — the service
-chokepoint, guards, the never-throw result funnel, the registry merge engine,
-and the subscribable cache store. The React faces (`/react`: hooks, cards,
-list, pickers, capture toolbar) arrive in the next waves. Everything below
-about the schema is binding — it is the package's product.
+**v0.3 ships the types root, the headless `/core`, and the React binding
+`/react`** — the service chokepoint, guards, the never-throw result funnel,
+the registry merge engine, the subscribable cache store, the seven hooks, and
+the association faces (cards, list, pickers, attached-items sheet, capture
+toolbar). Everything below about the schema is binding — it is the package's
+product.
 
 ```ts
 import {
@@ -46,6 +47,35 @@ await store.favorites.setFavorite("note", noteId, true);
 await assertDemandedSchema(supabase, { selfTest: true });
 ```
 
+```tsx
+// /react — the banner'd React binding (peer: react >=18 and
+// @ai-matrx/design-system >=0.2.0 for the faces' chrome). Bind ONCE:
+import {
+  AssociationsProvider,
+  useAssociations,              // the seven hooks keep the app originals' exact signatures
+  AssociationCardGrid,          // + AssociationCard / AssociationList / pickers / capture toolbar
+  PrimaryEntityProvider,
+} from "@ai-matrx/associations/react";
+
+<AssociationsProvider
+  store={store}                 // the /core store from createAssociationsStore
+  notifier={toastAdapter}       // optional — absent warns once, failures still hit errorSink
+  windowShell={windowAdapter}   // optional — absent falls back to a fixed overlay
+  capture={captureHandlers}     // optional, per-handler — chips render only when bound
+  pickerOverrides={{ file: FilePickerWindowAdapter }} // optional per-token pickers
+  entityDoors={{ EntityRef, DoorControls, UnresolvedRef }} // optional doors
+>
+  <PrimaryEntityProvider value={{ type: "organization", id, orgId, label }}>
+    <AssociationCardGrid />
+  </PrimaryEntityProvider>
+</AssociationsProvider>;
+```
+
+The faces style with Tailwind semantic tokens (`bg-card`,
+`text-muted-foreground`, …): register this package as a Tailwind v4 source in
+the consuming app (`@source "../node_modules/@ai-matrx/associations/dist"`)
+the same way `@ai-matrx/design-system` documents.
+
 ## The demanded schema — read this first
 
 This package is **opinionated like the Python `matrx-*` packages**: it does not

package/dist/core/index.cjs

@@ -3019,7 +3019,9 @@ function createAssociationsStore(config) {
     helpers,
     registry,
     services: { associations, categories },
-    registerEntityOverlay: registry.registerEntityOverlay
+    registerEntityOverlay: registry.registerEntityOverlay,
+    errorSink,
+    identity: config.identity
   };
 }