@burojs/react

React bindings for buro: context providers, the list controller, i18n, capabilities and test-id plumbing.

UI-kit agnostic — it deliberately depends on no @burojs/ui-* package, so any renderer can sit on top. Its native data runtime uses @tanstack/react-query internally.

Install

pnpm add @burojs/react @burojs/core

Usage

import { BuroProvider, RouterAdapterProvider, useResourceList } from '@burojs/react';

// `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() {
  const list = useResourceList('company');
  return (
    <ul>
      {list.rows.map((r) => (
        <li key={r.id}>{String(r.name)}</li>
      ))}
    </ul>
  );
}

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 (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.

License

MIT