@reopt-ai/opt-ui 1.11.0 → 1.12.0

package/dist/docs/03-recipes/02-dashboards.md

@@ -380,18 +380,134 @@ export function ActivityDashboard() {
 }
 ```
 
+## 4. Analytics Detail Investigation
+
+Keep the result list visible while the reader investigates one profile. The
+row owns identity fallback, the flyout owns disclosure and focus return, and
+the evidence inside the panel stays semantic: facts are a definition list,
+score axes are named, and events preserve session boundaries.
+
+```tsx
+"use client";
+
+import { useState } from "react";
+import {
+  Button,
+  DescriptionList,
+  EventTimeline,
+  Flyout,
+  Identity,
+  ScoreBreakdown,
+  type EventTimelineGroup,
+} from "@reopt-ai/opt-ui";
+
+const customer = {
+  id: "usr_01J5Q8M2N7W4",
+  name: "Mina Park",
+  email: "mina.park@example.com",
+  company: "Northstar Labs",
+};
+
+const sessions: EventTimelineGroup[] = [
+  {
+    id: "checkout-recovery",
+    title: "Checkout recovery",
+    meta: "12m · 2 events",
+    items: [
+      {
+        id: "order",
+        name: "Order completed",
+        timestamp: "2026-08-27T01:17:44.000Z",
+        tone: "success",
+        properties: { order_id: "R-1842", value: 128000 },
+      },
+      {
+        id: "coupon",
+        name: "Recovery coupon applied",
+        timestamp: "2026-08-27T01:14:09.000Z",
+        properties: { code: "RECOVER20" },
+      },
+    ],
+  },
+];
+
+export function CustomerInvestigation() {
+  const [open, setOpen] = useState(false);
+
+  return (
+    <div className="grid gap-group lg:grid-cols-[1fr_30rem]">
+      <button type="button" onClick={() => setOpen(true)}>
+        <Identity
+          name={customer.name}
+          secondary={customer.email}
+          id={customer.id}
+          state="identified"
+        />
+      </button>
+
+      <Flyout
+        open={open}
+        onClose={() => setOpen(false)}
+        type="inline"
+        title={customer.name}
+        footer={
+          <Button variant="secondary" onClick={() => setOpen(false)}>
+            Close
+          </Button>
+        }
+      >
+        <div className="flex flex-col gap-group">
+          <DescriptionList
+            columns={2}
+            items={[
+              {
+                id: "id",
+                term: "Profile ID",
+                description: customer.id,
+                copyValue: customer.id,
+              },
+              {
+                id: "company",
+                term: "Company",
+                description: customer.company,
+              },
+            ]}
+          />
+          <ScoreBreakdown
+            score={76}
+            axes={[
+              { id: "recency", label: "Recency", value: 92, weight: 0.5 },
+              { id: "depth", label: "Depth", value: 60, weight: 0.5 },
+            ]}
+          />
+          <EventTimeline groups={sessions} showGaps />
+        </div>
+      </Flyout>
+    </div>
+  );
+}
+```
+
+Do not wrap an interactive `StatCard` or `Identity` row in a second control.
+Let the component or one row button own the focus stop. `Flyout` is deliberately
+non-modal, so use it for comparison and investigation; use `Dialog` when the
+reader must finish or cancel a blocking task before returning to the page.
+
 ## Composition Notes
 
-| Pattern             | Key Components                           | Data Types                               |
-| ------------------- | ---------------------------------------- | ---------------------------------------- |
-| KPI stats row       | `SummaryRow`                             | `StatCard[]` (aliased as `StatCardType`) |
-| Trend visualization | `TrendChart` or `ChartContainer` + chart | `ChartDataPoint[]` + `ChartSeriesDef[]`  |
-| Tabular detail      | `DataTable`                              | `ColumnDef<T>[]` + data array            |
-| Date filtering      | `TimeRangeSelector`                      | `DateRange`                              |
-| Segment filtering   | `FilterBar`                              | `FilterGroupDef[]`                       |
-| Quick metrics       | `MetricsCard`                            | inline props + `sparklineData: number[]` |
-| Activity timeline   | `ActivityFeed`                           | `ActivityDef[]`                          |
-| Task tracking       | `TaskList`                               | `TaskDef[]`                              |
+| Pattern              | Key Components                           | Data Types                               |
+| -------------------- | ---------------------------------------- | ---------------------------------------- |
+| KPI stats row        | `SummaryRow`                             | `StatCard[]` (aliased as `StatCardType`) |
+| Trend visualization  | `TrendChart` or `ChartContainer` + chart | `ChartDataPoint[]` + `ChartSeriesDef[]`  |
+| Tabular detail       | `DataTable`                              | `ColumnDef<T>[]` + data array            |
+| Date filtering       | `TimeRangeSelector`                      | `DateRange`                              |
+| Segment filtering    | `FilterBar`                              | `FilterGroupDef[]`                       |
+| Quick metrics        | `MetricsCard`                            | inline props + `sparklineData: number[]` |
+| Activity timeline    | `ActivityFeed`                           | `ActivityDef[]`                          |
+| Detail investigation | `Identity`, `Flyout`, `DescriptionList`  | profile + labelled facts                 |
+| Explainable score    | `ScoreBreakdown`                         | `ScoreAxis[]` + `ScoreBand[]`            |
+| Session evidence     | `EventTimeline`                          | `EventTimelineGroup[]`                   |
+| Task tracking        | `TaskList`                               | `TaskDef[]`                              |
 
 All page-level layouts use `SurfaceLayout` for consistent `gap-section` spacing.
 Use `gap-group` for grid gaps and `gap-element` for tightly spaced items.