@b1-road/react 0.1.0-alpha.1 → 0.1.0-alpha.2

package/README.md

@@ -148,6 +148,77 @@ authkit-react). Plan
 [10-react-cookie-mode-spec.md](../../../docs/plans/10-react-cookie-mode-spec.md)
 has the detailed rationale.
 
+## Widgets
+
+Two drop-in UI widgets ship with the SDK. Both must render inside
+`<RoadProvider>` and inherit your [theming](#theming) from the provider's
+`appearance` prop — no extra wiring. They gate themselves on the user's
+permissions, so you don't guard them with `useCan`.
+
+### `<BusinessUnitSwitcher />`
+
+A sidebar control that shows the active business unit, switches between the
+user's memberships, surfaces pending invitations (accept / reject inline), and
+links into management and "create unit". Built to sit at the top or bottom of
+an app sidebar.
+
+```tsx
+import { BusinessUnitSwitcher } from "@b1-road/react";
+
+<aside className="sidebar">
+  <BusinessUnitSwitcher />
+</aside>;
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `collapsed` | `boolean` | _auto_ | Force the compact icon-only trigger (`true`) or the expanded avatar + name + role trigger (`false`). Left unset, it auto-detects via `ResizeObserver` — under 180px wide it collapses. Pass it when your sidebar's collapse state lives in app state. |
+| `className` | `string` | — | Extra classes on the trigger button (for sidebar layout). |
+
+The active BU is read from / written to the provider's business-unit context
+(`useCurrentBusinessUnit` / `useSetCurrentBusinessUnit`), so switching here
+re-scopes every `useCan(buId)` and BU-scoped query across your app.
+
+### `<BusinessUnitsMgmt />`
+
+A dialog for managing business units and their roles: list / create / edit
+BUs, manage members and invitations, and define roles + permissions (the role
+editor with the permission picker lives here). Two tabs: `"business-units"`
+and `"roles"`.
+
+It runs in either **uncontrolled** mode (renders its own trigger) or
+**controlled** mode (you own the open state). The prop types enforce the
+pairing at compile time.
+
+```tsx
+import { useState } from "react";
+import { BusinessUnitsMgmt } from "@b1-road/react";
+
+// Uncontrolled — renders a default trigger (or pass your own):
+<BusinessUnitsMgmt trigger={<button>Manage units</button>} />;
+
+// Controlled — you own the open state:
+function Example() {
+  const [open, setOpen] = useState(false);
+  return <BusinessUnitsMgmt open={open} onOpenChange={setOpen} />;
+}
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `trigger` | `ReactNode` | default button | _(uncontrolled only)_ element that opens the dialog. |
+| `open` | `boolean` | — | _(controlled only)_ open state; must be paired with `onOpenChange`. |
+| `onOpenChange` | `(open: boolean) => void` | — | _(controlled only)_ open-state callback. |
+| `initialTab` | `"business-units" \| "roles"` | `"business-units"` | Tab shown each time the dialog opens. |
+| `initialBusinessUnitId` | `string` | — | Deep-link: open straight into this BU's detail view. |
+
+> `trigger` and the `open`/`onOpenChange` pair are mutually exclusive —
+> passing `open` without `onOpenChange`, or mixing in `trigger`, is a
+> compile-time type error.
+
+`BusinessUnitSwitcher` already embeds this dialog for its manage/settings
+entry, so adding the switcher often covers both.
+
 ## Permission-gated UI
 
 Widgets gate themselves. For your own UI, `useCan(buId)` returns a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@b1-road/react",
-  "version": "0.1.0-alpha.1",
+  "version": "0.1.0-alpha.2",
   "type": "module",
   "description": "Official React toolkit for integrating with Road — components, hooks, and helpers for embedding Road IAM into platform apps.",
   "main": "./dist/index.cjs",