@streamoid/ui 0.6.46 → 0.6.48

package/dist/docs/AGENTS.md

@@ -1,6 +1,6 @@
 # @streamoid/ui — component router (for AI agents)
 
-126 components. Full docs for each live beside this file as `<ScName>.md`;
+127 components. Full docs for each live beside this file as `<ScName>.md`;
 the same metadata is machine-readable in `components.json`.
 
 **How to use this file:** scan for the job you need below, then open only that
@@ -136,6 +136,7 @@ theme-aware (dark on `:root`, light override) — never hardcode a colour.
 - **`ScBadges`** — use when you need to state a status, a count or a tag next to something — "Revoked", "Active", "1,240 credits", "Needs attention".
 - **`ScBeacon`** — use when a row or card needs a colour-coded state marker that sits beside a text label ("● Live", "● Needs attention").
 - **`ScDrawer`** — use when you need a create/edit panel or a detail pane that slides in from the screen edge and stays full height.
+- **`ScErrorBoundary`** — use when you are wrapping an app, a route, or any subtree whose crash would otherwise blank the page.
 - **`ScGuide`** — use when you are building a product walkthrough / coachmark sequence and need the step card.
 - **`ScInfoPopup`** — use when a label or a table header needs a short explanation, and you want the standard ⓘ affordance next to it.
 - **`ScMenuOptions`** — use when you need a row in a profile flyout, an account/settings menu, or a kebab/overflow menu.
@@ -227,6 +228,7 @@ theme-aware (dark on `:root`, light override) — never hardcode a colour.
 | `ScDefaultCard` | `ScAppListingCard`, `ScStoreCard`, `ScMappingCard`, `ScBriefCard`, `ScRadio` |
 | `ScDp` | `ScIntialProfileCover`, `ScProfileImageUpdate`, `ScProfile` |
 | `ScDrawer` | `ScModal`, `ScSidebar`, `StreamoidSidebar`, `ScProfilePopup` |
+| `ScErrorBoundary` | `ScBadges`, `ScToast` |
 | `ScGoogleSignIn` | `ScButton`, `ScAppSwitchPanel`, `ScAppCard` |
 | `ScGuide` | `ScInfoPopup`, `ScModal`, `ScDrawer`, `ScBeacon`, `ScPopUpMenu` |
 | `ScHDivider` | `ScVDivider` |

package/dist/docs/ScErrorBoundary.md

@@ -0,0 +1,160 @@
+---
+component: ScErrorBoundary
+package: "@streamoid/ui"
+category: overlays
+status: stable
+renders: div[role="alert"]
+tags: [error, boundary, crash, white-screen, report, exception, telemetry, posthog]
+related: [ScBadges, ScToast]
+do_not_confuse_with: [ScBadges, ScToast]
+---
+
+# ScErrorBoundary
+
+**The only place a white screen can be observed.** A render crash produces no
+request — no span, no access-log line, no status code — so every server-side
+signal we have is blind to it. This catches it, shows the user the reference the
+server already minted, and gives them a way to say what happened.
+
+## TL;DR for agents
+
+- **Reach for it when:** you are wrapping an app, a route, or any subtree whose
+  crash would otherwise blank the page.
+- **Don't reach for it when:** you want to show a handled API failure inline
+  (→ a toast or inline message; a boundary only catches *render* errors), or you
+  need to catch errors in an event handler or a promise — React boundaries do
+  not see those.
+- **Three things that will bite you:**
+  1. It does **not** depend on `posthog-js`, and never will. You pass the client
+     in. Nothing is reported until you supply a `reporter`.
+  2. Where a failure never reached a server there is **no reference**, and none
+     is invented — the reference line is simply absent.
+  3. Error boundaries must be class components. There is no hook equivalent, so
+     this cannot be wrapped in one.
+
+---
+
+## 1. How to use it
+
+### Import
+
+```tsx
+import { ScErrorBoundary, scCreatePostHogReporter } from "@streamoid/ui";
+```
+
+### Minimal usage
+
+```tsx
+<ScErrorBoundary>
+  <App />
+</ScErrorBoundary>
+```
+
+That catches the crash and shows the fallback. It reports nothing — supply a
+`reporter` for that.
+
+```tsx
+<ScErrorBoundary
+  service="unified-admin-dashboard"
+  reporter={scCreatePostHogReporter(posthog)}
+>
+  <App />
+</ScErrorBoundary>
+```
+
+### Props
+
+| Prop | Type | Required | Notes |
+|---|---|---|---|
+| `children` | `ReactNode` | yes | The subtree to guard |
+| `reporter` | `(report: IScErrorReport) => void` | no | Called once on catch, and again if the user submits a note |
+| `service` | `string` | no | The id from `deployment/service.yaml`, recorded on the report so it routes itself |
+| `route` | `string` | no | Defaults to `window.location.pathname` |
+| `fallback` | `({ error, errorRef, report }) => ReactNode` | no | Replaces the default surface entirely |
+
+### Recipes
+
+**Report somewhere other than PostHog.** The signature is the whole contract:
+
+```tsx
+<ScErrorBoundary reporter={(report) => myLogger.error(report)}>
+```
+
+**Keep the page usable around a broken panel** by scoping the boundary rather
+than wrapping the whole app:
+
+```tsx
+<ScErrorBoundary route="/billing/invoices" fallback={({ errorRef }) => (
+  <InlineNotice>Invoices are unavailable. Reference {errorRef ?? "none"}.</InlineNotice>
+)}>
+  <InvoiceTable />
+</ScErrorBoundary>
+```
+
+## 2. Where to use it
+
+At the root of an application, and around any subtree that is worth keeping
+independently alive — a dashboard panel, a table that renders third-party data,
+an editor. Scoping it narrowly is what turns a blank page into a single broken
+card.
+
+## 3. When to use it
+
+### Use it when
+
+- A crash in this subtree would otherwise show the user nothing at all.
+- You want the user's own account of what they were doing attached to the error.
+
+### Don't use it — reach for this instead
+
+- A handled API error you want to show inline → a toast or an inline message.
+- An error thrown in an event handler or an unawaited promise → React boundaries
+  never see these; catch them where they are thrown.
+
+### Don't confuse with
+
+- **ScBadges** — a status label, not an error surface.
+- **ScToast** — transient feedback for something that was handled.
+
+## 4. Why to use it
+
+Because the failure it catches is the one nothing else can see. A 5xx leaves a
+span, a log line and a status code. A render crash leaves a blank rectangle and a
+user who closes the tab.
+
+It also carries the reference forward. The fallback shows `ERR-` plus the first
+twelve characters of the server's trace id, which the request wrapper attached to
+the failing response — so the string the user reads out is the same string that
+finds the trace in SigNoz, with no lookup table in between.
+
+## Gotchas
+
+- **No `posthog-js` dependency, deliberately.** This package has five consuming
+  applications, and a dependency added here arrives in all of them on the next
+  version bump whether they want it or not. A shared component library is the
+  wrong place to decide that a product ships an analytics SDK. The host passes
+  in the client it already created;`scCreatePostHogReporter` accepts anything
+  with a `capture` method and emits PostHog's own `$exception` event, so reports
+  land in its error tracking rather than a bespoke event with no view.
+- **A missing reference is a real answer.** A 502 from the edge never reached the
+  application, so there is no trace to point at. Showing an invented id sends
+  whoever reads it hunting for something that does not exist.
+- **Reporting cannot cause a second failure.** The `reporter` call is wrapped in
+  its own try/catch and its errors are swallowed.
+- **The reference is `user-select: all`.** The one thing a person is expected to
+  do with this surface is copy that string.
+- **`prompt()` is used for the note.** It is synchronous and unstyled, and the
+  trade is deliberate: a custom modal inside an error boundary is more code
+  running in a subtree that has already proven it can crash.
+
+## In the wild
+
+**No host render site found** — this component is new in `@streamoid/ui@0.6.48`
+and nothing consumes it yet. The first will be `unified-admin-dashboard`, whose
+`utils/request.js` already annotates failures with the `errorRef` this reads.
+
+## Related
+
+- `scGetErrorRef(error)` — the reference off an annotated error, exported
+  alongside for code that needs it outside a boundary.
+- `scCreatePostHogReporter(client, { service })` — the PostHog adapter.

package/dist/docs/components.json

@@ -1,6 +1,6 @@
 {
   "package": "@streamoid/ui",
-  "count": 126,
+  "count": 127,
   "components": {
     "ScAccess": {
       "doc": "ScAccess.md",
@@ -1073,6 +1073,37 @@
       "alsoExports": [],
       "exported": true
     },
+    "ScErrorBoundary": {
+      "doc": "ScErrorBoundary.md",
+      "source": "src/SC-ErrorBoundary",
+      "category": "overlays",
+      "status": "stable",
+      "renders": "div[role=\"alert\"]",
+      "summary": "The only place a white screen can be observed.",
+      "reachForWhen": "you are wrapping an app, a route, or any subtree whose crash would otherwise blank the page.",
+      "tags": [
+        "error",
+        "boundary",
+        "crash",
+        "white-screen",
+        "report",
+        "exception",
+        "telemetry",
+        "posthog"
+      ],
+      "related": [
+        "ScBadges",
+        "ScToast"
+      ],
+      "doNotConfuseWith": [
+        "ScBadges",
+        "ScToast"
+      ],
+      "requiredProps": [],
+      "usedBy": [],
+      "alsoExports": [],
+      "exported": true
+    },
     "ScGoogleSignIn": {
       "doc": "ScGoogleSignIn.md",
       "source": "src/SC-Google sign in",