@burojs/react 0.2.0 → 0.5.0

package/README.md

@@ -13,10 +13,17 @@ pnpm add @burojs/react @burojs/core
 ## Usage
 
 ```tsx
-import { BuroProvider, useResourceList } from '@burojs/react';
+import { BuroProvider, RouterAdapterProvider, useResourceList } from '@burojs/react';
 
-function Root({ app, children }) {
-  return <BuroProvider app={app}>{children}</BuroProvider>;
+// `adapter` binds your router — `RouterAdapterProvider`'s docblock has the
+// react-router and Next App Router ones. It is required, and goes above
+// <BuroProvider>: without it no route matches.
+function Root({ app, adapter, children }) {
+  return (
+    <RouterAdapterProvider adapter={adapter}>
+      <BuroProvider app={app}>{children}</BuroProvider>
+    </RouterAdapterProvider>
+  );
 }
 
 function MyList() {
@@ -33,11 +40,13 @@ function MyList() {
 
 ## Main exports
 
+- **`BuroProvider`** — mounts the app runtime, i18n, the data runtime, and the interaction layer: an action dispatcher with a default for every effect (`refetch` invalidates the framework's queries, `notify` reaches the notification sink a toaster registers, `redirect` pushes through your `RouterAdapter` and skips the page already on screen, `setClipboard`, `download`, `modal`), overridable per key with `effects`; the unsaved-changes navigation guard; and the notification sink. Nested scopes and tests use **`DispatcherProvider`** / **`useDispatcher`**.
+- **`resolveRoute` / `useRouteNavigate`** — the one navigation seam: a `RouteDescriptor` resolved against the registry and pushed through the mounted `RouterAdapter` (a document navigation without one). Mount `RouterAdapterProvider` **above** `<BuroProvider>`: the default `redirect` and the navigation guard's "Leave" read the adapter from where `BuroProvider` sits, so one mounted inside it is invisible to them and they fall back to full page loads. **`useNavigationBlocker`**, **`useRegisterNavigationGuardDialog`**, **`useRegisterNotificationSink`** are the hooks a UI kit's form, dialog and toaster use. A hook whose job is to register is named `useRegister<Thing>`, and the most recently registered, still-mounted registrant wins: one toaster receives notifications, one dialog answers a held navigation.
 - **`useResourceList`** — the data-connected list controller: rows, pagination (including the unknown-total contract), filters, search, sorting, columns, selection, saved views, routing hrefs, and the on-demand row count. **`ResourceListProvider` / `useResourceListContext`** expose it to override slots, so a custom list body is testable against a stub controller with no runtime or Next mocking.
 - **`useApp` / `useCurrentResource` / `useCtx`** — registry and context access.
-- **`useAction`** — invoke a declared action and apply its `ActionResult`.
-- **`useCapability` / `useCapabilityResolver`** — the deny-wins capability engine gating fields, actions and tabs.
-- **`useComponent` / `mergeComponents` / `ComponentsContext`** — the component registry behind override slots (`list.body.<resource>`, `list.filters.<resource>`, `show.banner.<resource>`, …).
+- **`useAction`** (from `@burojs/react/flows`) — run a declared flow from code: its state, and `run()`.
+- **`useCapability` / `useCapabilityResolver`** — the deny-wins capability engine gating fields, actions and columns.
+- **`useComponent` / `mergeComponents` / `ComponentsContext`** — the component registry behind override slots (`list.filters.<resource>`, `list.cell.<resource>`, `record.<action>.<resource>`, `layout.<key>`), keys dotted with the canonical resource last.
 - **`useT` / `useLocale` / `I18nContext`**, plus the built-in **`en` / `ru`** locale bundles — render-time i18n with a live language switch (no reload).
 - **`TestIdBuilder` / `TestIdContext`** — the stable test-id surface shared with `@burojs/test-helpers`.