@reopt-ai/opt-ui 1.4.1

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

@@ -0,0 +1,397 @@
+---
+title: "Dashboard Recipes"
+description: "opt-ui 대시보드 조합 패턴 3종 — KPI, Analytics, Activity"
+related:
+  links:
+    - ../02-components/02-visuals.md
+    - ../02-components/03-shells.md
+---
+
+<!-- AI agent hint: 차트 컴포넌트는 반드시 ChartContainer로 감쌀 것. ChartDataPoint[]의 name 필드는 필수. -->
+
+# Dashboard Recipes
+
+Copy-paste-ready dashboard composition patterns.
+All imports from `@reopt-ai/opt-ui`.
+
+## 1. KPI Dashboard
+
+SummaryRow for top-level stats, TrendChart for time series, DataTable for details.
+
+```tsx
+"use client";
+
+import { useState } from "react";
+import {
+  SurfaceLayout,
+  PageHeader,
+  SummaryRow,
+  TrendChart,
+  DataTable,
+  Button,
+  type StatCard as StatCardType,
+  type ChartDataPoint,
+  type ChartSeriesDef,
+  type ColumnDef,
+} from "@reopt-ai/opt-ui";
+
+interface SalesRow {
+  id: string;
+  product: string;
+  revenue: number;
+  units: number;
+  growth: string;
+}
+
+const stats: StatCardType[] = [
+  {
+    id: "revenue",
+    title: "매출",
+    value: "₩45.2M",
+    change: "+12.5%",
+    trend: "up",
+  },
+  { id: "orders", title: "주문", value: "1,234", change: "+8.2%", trend: "up" },
+  {
+    id: "aov",
+    title: "객단가",
+    value: "₩36,600",
+    change: "-2.1%",
+    trend: "down",
+  },
+  {
+    id: "refund",
+    title: "환불률",
+    value: "3.2%",
+    change: "-0.5%",
+    trend: "up",
+  },
+];
+
+const trendData: ChartDataPoint[] = [
+  { name: "1월", revenue: 32000, orders: 890 },
+  { name: "2월", revenue: 35000, orders: 920 },
+  { name: "3월", revenue: 38000, orders: 1010 },
+  { name: "4월", revenue: 41000, orders: 1100 },
+  { name: "5월", revenue: 45200, orders: 1234 },
+];
+
+const trendSeries: ChartSeriesDef[] = [
+  { dataKey: "revenue", name: "매출" },
+  { dataKey: "orders", name: "주문" },
+];
+
+const rows: SalesRow[] = [
+  {
+    id: "1",
+    product: "Pro Plan",
+    revenue: 18200000,
+    units: 340,
+    growth: "+15%",
+  },
+  { id: "2", product: "Starter", revenue: 12500000, units: 520, growth: "+8%" },
+  {
+    id: "3",
+    product: "Enterprise",
+    revenue: 14500000,
+    units: 90,
+    growth: "+22%",
+  },
+];
+
+const columns: ColumnDef<SalesRow>[] = [
+  { id: "product", header: "상품", accessor: "product" },
+  {
+    id: "revenue",
+    header: "매출",
+    accessor: (r) => `₩${(r.revenue / 1e6).toFixed(1)}M`,
+  },
+  { id: "units", header: "판매", accessor: "units", align: "right" },
+  { id: "growth", header: "성장률", accessor: "growth", align: "right" },
+];
+
+export function KpiDashboard() {
+  return (
+    <SurfaceLayout>
+      <PageHeader
+        title="매출 대시보드"
+        actions={<Button variant="secondary">리포트 다운로드</Button>}
+      />
+
+      <SummaryRow stats={stats} columns={4} />
+
+      <TrendChart
+        title="월별 추세"
+        description="매출 및 주문 수 추이"
+        data={trendData}
+        series={trendSeries}
+        height={280}
+      />
+
+      <DataTable
+        data={rows}
+        columns={columns}
+        keyExtractor={(r) => r.id}
+        title="상품별 실적"
+        sortable
+      />
+    </SurfaceLayout>
+  );
+}
+```
+
+## 2. Analytics Overview
+
+TimeRangeSelector for date filtering, LineChart and BarChart side by side, FilterBar for segmentation.
+
+```tsx
+"use client";
+
+import { useState } from "react";
+import {
+  SurfaceLayout,
+  PageHeader,
+  TimeRangeSelector,
+  ChartContainer,
+  LineChart,
+  BarChart,
+  FilterBar,
+  type ChartDataPoint,
+  type ChartSeriesDef,
+  type FilterGroupDef,
+  type DateRange,
+} from "@reopt-ai/opt-ui";
+
+const pageViewData: ChartDataPoint[] = [
+  { name: "Mon", views: 1200, visitors: 800 },
+  { name: "Tue", views: 1400, visitors: 950 },
+  { name: "Wed", views: 1100, visitors: 750 },
+  { name: "Thu", views: 1600, visitors: 1100 },
+  { name: "Fri", views: 1800, visitors: 1250 },
+  { name: "Sat", views: 900, visitors: 600 },
+  { name: "Sun", views: 700, visitors: 450 },
+];
+
+const lineSeries: ChartSeriesDef[] = [
+  { dataKey: "views", name: "페이지뷰" },
+  { dataKey: "visitors", name: "방문자" },
+];
+
+const channelData: ChartDataPoint[] = [
+  { name: "Organic", sessions: 4500 },
+  { name: "Direct", sessions: 3200 },
+  { name: "Social", sessions: 2100 },
+  { name: "Referral", sessions: 1800 },
+  { name: "Paid", sessions: 1200 },
+];
+
+const barSeries: ChartSeriesDef[] = [{ dataKey: "sessions", name: "세션" }];
+
+const filters: FilterGroupDef[] = [
+  {
+    id: "channel",
+    label: "채널",
+    type: "select",
+    options: [
+      { id: "all", label: "전체", value: "all" },
+      { id: "organic", label: "Organic", value: "organic" },
+      { id: "paid", label: "Paid", value: "paid" },
+    ],
+    value: "all",
+  },
+  {
+    id: "device",
+    label: "디바이스",
+    type: "multi-select",
+    options: [
+      { id: "desktop", label: "Desktop", value: "desktop" },
+      { id: "mobile", label: "Mobile", value: "mobile" },
+      { id: "tablet", label: "Tablet", value: "tablet" },
+    ],
+    value: [],
+  },
+];
+
+export function AnalyticsOverview() {
+  const [timeRange, setTimeRange] = useState<DateRange>({
+    start: null,
+    end: null,
+  });
+
+  return (
+    <SurfaceLayout>
+      <PageHeader
+        title="분석 개요"
+        description="트래픽 및 채널 분석"
+        actions={
+          <TimeRangeSelector value={timeRange} onChange={setTimeRange} />
+        }
+      />
+
+      <FilterBar
+        filters={filters}
+        onFilterChange={(id, value) => console.log(id, value)}
+      />
+
+      <div className="gap-group grid grid-cols-1 lg:grid-cols-2">
+        <div className="gap-element flex flex-col">
+          <h3 className="text-text-primary text-sm font-medium">일별 트래픽</h3>
+          <ChartContainer height={280}>
+            <LineChart data={pageViewData} series={lineSeries} />
+          </ChartContainer>
+        </div>
+
+        <div className="gap-element flex flex-col">
+          <h3 className="text-text-primary text-sm font-medium">채널별 세션</h3>
+          <ChartContainer height={280}>
+            <BarChart data={channelData} series={barSeries} />
+          </ChartContainer>
+        </div>
+      </div>
+    </SurfaceLayout>
+  );
+}
+```
+
+## 3. Activity Dashboard
+
+ActivityFeed for recent events, TaskList for action items, MetricsCard grid for quick stats.
+
+```tsx
+"use client";
+
+import {
+  SurfaceLayout,
+  PageHeader,
+  ActivityFeed,
+  TaskList,
+  MetricsCard,
+  Button,
+  type ActivityDef,
+  type TaskDef,
+  type TeamMemberDef,
+} from "@reopt-ai/opt-ui";
+
+const actor: TeamMemberDef = {
+  id: "u1",
+  name: "김개발",
+  email: "dev@example.com",
+  role: "Engineer",
+  status: "online",
+};
+
+const activities: ActivityDef[] = [
+  {
+    id: "a1",
+    type: "deployed",
+    title: "v2.4.0 프로덕션 배포",
+    actor,
+    timestamp: new Date(Date.now() - 1000 * 60 * 30).toISOString(),
+  },
+  {
+    id: "a2",
+    type: "merged",
+    title: "feat: 대시보드 리팩토링 PR 병합",
+    actor,
+    timestamp: new Date(Date.now() - 1000 * 60 * 120).toISOString(),
+  },
+  {
+    id: "a3",
+    type: "completed",
+    title: "API 마이그레이션 완료",
+    description: "REST → GraphQL 전환 작업",
+    actor,
+    timestamp: new Date(Date.now() - 1000 * 60 * 300).toISOString(),
+  },
+];
+
+const tasks: TaskDef[] = [
+  {
+    id: "t1",
+    title: "인증 토큰 만료 처리",
+    status: "in-progress",
+    priority: "high",
+    assignee: actor,
+    dueDate: "2026-04-05",
+  },
+  {
+    id: "t2",
+    title: "대시보드 성능 최적화",
+    status: "todo",
+    priority: "medium",
+    tags: ["performance"],
+  },
+  {
+    id: "t3",
+    title: "E2E 테스트 추가",
+    description: "핵심 플로우 커버리지 확보",
+    status: "todo",
+    priority: "low",
+  },
+];
+
+export function ActivityDashboard() {
+  return (
+    <SurfaceLayout>
+      <PageHeader
+        title="활동 대시보드"
+        actions={<Button variant="secondary">전체 보기</Button>}
+      />
+
+      <div className="gap-group grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-4">
+        <MetricsCard
+          title="오늘 배포"
+          value={3}
+          change="+2"
+          trend="up"
+          sparklineData={[1, 0, 2, 1, 3]}
+        />
+        <MetricsCard
+          title="열린 PR"
+          value={7}
+          change="-1"
+          trend="down"
+          sparklineData={[9, 8, 10, 8, 7]}
+        />
+        <MetricsCard
+          title="완료 태스크"
+          value={12}
+          change="+4"
+          trend="up"
+          sparklineData={[5, 6, 8, 10, 12]}
+        />
+        <MetricsCard
+          title="미해결 이슈"
+          value={23}
+          trend="neutral"
+          sparklineData={[25, 24, 23, 24, 23]}
+        />
+      </div>
+
+      <div className="gap-section grid grid-cols-1 lg:grid-cols-2">
+        <ActivityFeed activities={activities} maxItems={5} />
+        <TaskList
+          tasks={tasks}
+          onTaskToggle={(id) => console.log("toggle", id)}
+        />
+      </div>
+    </SurfaceLayout>
+  );
+}
+```
+
+## 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[]`                              |
+
+All page-level layouts use `SurfaceLayout` for consistent `gap-section` spacing.
+Use `gap-group` for grid gaps and `gap-element` for tightly spaced items.