@umituz/web-dashboard 8.11.0 → 9.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (46) hide show
  1. package/README.md +54 -7
  2. package/package.json +6 -2
  3. package/src/config/DashboardConfig.ts +4 -8
  4. package/src/domains/analytics/components/AnalyticsLayout.test.tsx +85 -0
  5. package/src/domains/analytics/components/AnalyticsLayout.tsx +103 -105
  6. package/src/domains/analytics/components/index.ts +0 -3
  7. package/src/domains/analytics/hooks/index.ts +1 -1
  8. package/src/domains/analytics/hooks/useAnalytics.test.tsx +125 -0
  9. package/src/domains/analytics/hooks/useAnalytics.ts +37 -56
  10. package/src/domains/analytics/index.ts +9 -26
  11. package/src/domains/analytics/services/index.ts +0 -1
  12. package/src/domains/analytics/types/analytics.ts +32 -149
  13. package/src/domains/analytics/types/index.ts +3 -15
  14. package/src/domains/analytics/utils/analytics.test.ts +82 -13
  15. package/src/domains/analytics/utils/analytics.ts +52 -75
  16. package/src/domains/analytics/utils/index.ts +5 -8
  17. package/src/domains/charts/charts.css +455 -0
  18. package/src/domains/charts/components/ActivityHeatmap.test.tsx +48 -0
  19. package/src/domains/charts/components/ActivityHeatmap.tsx +58 -0
  20. package/src/domains/charts/components/BarChart.test.tsx +91 -0
  21. package/src/domains/charts/components/BarChart.tsx +143 -0
  22. package/src/domains/charts/components/ChartCard.tsx +39 -0
  23. package/src/domains/charts/components/ChartPrimitives.test.tsx +90 -0
  24. package/src/domains/charts/components/ChartTip.tsx +18 -0
  25. package/src/domains/charts/components/Donut.test.tsx +51 -0
  26. package/src/domains/charts/components/Donut.tsx +97 -0
  27. package/src/domains/charts/components/HBars.tsx +31 -0
  28. package/src/domains/charts/components/Legend.tsx +21 -0
  29. package/src/domains/charts/components/LineChart.test.tsx +81 -0
  30. package/src/domains/charts/components/LineChart.tsx +244 -0
  31. package/src/domains/charts/components/Sparkline.tsx +35 -0
  32. package/src/domains/charts/components/index.ts +16 -0
  33. package/src/domains/charts/index.ts +16 -2
  34. package/src/domains/charts/ssr.test.tsx +35 -0
  35. package/src/domains/charts/types/index.ts +8 -0
  36. package/src/domains/charts/utils.ts +15 -0
  37. package/src/index.ts +6 -23
  38. package/src/styles/chrome.css +10 -490
  39. package/src/styles/dashboard.contract.test.ts +20 -5
  40. package/src/styles/dashboard.css +1 -0
  41. package/src/domains/analytics/components/AnalyticsCard.tsx +0 -87
  42. package/src/domains/analytics/components/AnalyticsChart.tsx +0 -387
  43. package/src/domains/analytics/components/MetricCard.tsx +0 -42
  44. package/src/domains/analytics/services/AnalyticsEngineService.ts +0 -300
  45. package/src/domains/charts/components.test.tsx +0 -141
  46. package/src/domains/charts/components.tsx +0 -683
package/README.md CHANGED
@@ -19,7 +19,7 @@ import "@umituz/web-dashboard/styles.css";
19
19
 
20
20
  Peers: `react` + `react-dom` (^18 or ^19), `react-router-dom` (^6 or ^7),
21
21
  and `framer-motion` (^12, onboarding animations only).
22
- Runtime deps: `@umituz/web-design-system` (^4.9),
22
+ Runtime deps: `@umituz/web-design-system` (^5.0),
23
23
  `@umituz/web-localization`, `lucide-react`.
24
24
 
25
25
  ### Tailwind hosts
@@ -51,10 +51,11 @@ hosts set dark values on the DS variables under `[data-theme="dark"]` /
51
51
  @umituz/web-dashboard/layouts # DashboardLayout, DashboardSidebar, DashboardHeader
52
52
  @umituz/web-dashboard/settings # SettingsLayout, admin skeletons (users, matrix, audit)
53
53
  @umituz/web-dashboard/onboarding # OnboardingFlow + 15 screens, persistence, analytics
54
- @umituz/web-dashboard/analytics # AnalyticsLayout, SVG AnalyticsChart, services
54
+ @umituz/web-dashboard/analytics # AnalyticsLayout v2, useAnalytics, CSV export
55
55
  @umituz/web-dashboard/calendar # useCalendar, CalendarService (injected DB)
56
56
  @umituz/web-dashboard/config # dashboard config helpers
57
57
  @umituz/web-dashboard/charts # dependency-free SVG chart components
58
+ @umituz/web-dashboard/charts/charts.css # chart stylesheet (also chained by styles.css)
58
59
  ```
59
60
 
60
61
  Each domain also exposes `components`, `hooks`, `utils`, `types`
@@ -173,12 +174,59 @@ import { NotificationCenter, NotificationsPage } from "@umituz/web-dashboard/not
173
174
  <NotificationsPage typeMeta={TYPE_META} attentionLabel="Needs attention" />
174
175
  ```
175
176
 
177
+ ### Charts
178
+
179
+ Dependency-free SVG charts under `@umituz/web-dashboard/charts`:
180
+ `ChartCard`/`ChartTip`, `Legend`, `Sparkline`, `HBars`, `BarChart`
181
+ (grouped or `stacking="stacked"` with a tooltip total row), `Donut`,
182
+ `LineChart` (dual axes, band, crosshair, `areaFill: "gradient"`), and
183
+ `ActivityHeatmap` (CSS-var level classes, `levelClassNames` escape hatch).
184
+
185
+ Series colors resolve through the `--udb-chart-1..8` tokens (each with an
186
+ inline fallback hex), so a theme overrides its whole chart palette from one
187
+ place:
188
+
189
+ ```css
190
+ :root {
191
+ --udb-chart-1: #0e7490;
192
+ --udb-chart-2: #f59e0b;
193
+ }
194
+ ```
195
+
196
+ `styles.css` chains `charts/charts.css` transitively. Tailwind hosts that
197
+ import `chrome.css` directly add one line beside it:
198
+
199
+ ```css
200
+ @import "@umituz/web-dashboard/charts/charts.css";
201
+ ```
202
+
176
203
  ### Analytics
177
204
 
178
- `AnalyticsChart` consumes `ChartConfig` for line/area/bar/pie/donut. Tooltips
179
- are native SVG `<title>` elements; legends are color chips; unsupported types
180
- render an empty state. `useAnalytics` stays dependency-injected
181
- (`createStubAnalyticsApiClient`).
205
+ `AnalyticsLayout` composes design-system primitives — `DateRangePicker`
206
+ (presets default to 7d/30d/90d/month), a `KpiCard` grid, skeleton loading and
207
+ an `EmptyState` error panel with retry. Charts are a `ReactNode` slot (drop
208
+ `ChartCard`s in), filters too:
209
+
210
+ ```tsx
211
+ import { AnalyticsLayout, useAnalytics } from "@umituz/web-dashboard/analytics";
212
+ import { ChartCard, LineChart } from "@umituz/web-dashboard/charts";
213
+
214
+ const { kpis, series, range, updateRange, isLoading } = useAnalytics({ apiClient });
215
+
216
+ <AnalyticsLayout
217
+ title="analytics.title"
218
+ range={range}
219
+ onRangeChange={updateRange}
220
+ kpis={kpis}
221
+ loading={isLoading}
222
+ charts={<ChartCard title="Trend" tip={null}><LineChart labels={labels} series={[...]} /></ChartCard>}
223
+ />;
224
+ ```
225
+
226
+ `useAnalytics` stays dependency-injected (`createStubAnalyticsApiClient`);
227
+ `loadAnalytics(range)` is required, `exportAnalytics` optional. CSV exports
228
+ are one call — `exportCsv({ filename, headers, rows })` (BOM + CRLF +
229
+ Excel-safe quoting) — no dead adapters.
182
230
 
183
231
  ## i18n contract
184
232
 
@@ -197,7 +245,6 @@ provider, `useT()` falls back to `defaultT`, which humanizes keys
197
245
  readably. The per-domain key catalogs are the string contract:
198
246
 
199
247
  ```ts
200
- import { ANALYTICS_KEYS } from "@umituz/web-dashboard/analytics";
201
248
  import { SETTINGS_ADMIN_KEYS } from "@umituz/web-dashboard/settings/utils";
202
249
  import { PERMISSIONS_KEYS } from "@umituz/web-dashboard/permissions";
203
250
  ```
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@umituz/web-dashboard",
3
- "version": "8.11.0",
3
+ "version": "9.0.0",
4
4
  "description": "Installable app skeleton for the fleet — layouts, analytics (dependency-free SVG charts), calendar, onboarding flow permissions/module registry; udb-* stylesheet on design-system tokens",
5
5
  "type": "module",
6
6
  "main": "./src/index.ts",
@@ -24,6 +24,10 @@
24
24
  "./calendar/types": "./src/domains/calendar/types/index.ts",
25
25
  "./calendar/utils": "./src/domains/calendar/utils/index.ts",
26
26
  "./charts": "./src/domains/charts/index.ts",
27
+ "./charts/charts.css": "./src/domains/charts/charts.css",
28
+ "./charts/components": "./src/domains/charts/components/index.ts",
29
+ "./charts/types": "./src/domains/charts/types/index.ts",
30
+ "./charts/utils": "./src/domains/charts/utils.ts",
27
31
  "./chrome.css": "./src/styles/chrome.css",
28
32
  "./config": "./src/config/index.ts",
29
33
  "./layouts": "./src/domains/layouts/index.ts",
@@ -89,7 +93,7 @@
89
93
  "@types/react-dom": "^19.2.3",
90
94
  "@typescript-eslint/eslint-plugin": "^8.57.2",
91
95
  "@typescript-eslint/parser": "^8.57.2",
92
- "@umituz/web-design-system": "^4.31.0",
96
+ "@umituz/web-design-system": "^5.0.0",
93
97
  "eslint": "^10.0.2",
94
98
  "framer-motion": "^12.23.12",
95
99
  "jsdom": "^29.1.1",
@@ -1,8 +1,8 @@
1
- import type { ChartType } from '../domains/analytics/types/analytics';
1
+ import type { ExportFormat } from '../domains/analytics/types/analytics';
2
2
 
3
- export type AnalyticsServiceType = 'traffic' | 'cohort' | 'funnel' | 'growth' | 'performance';
3
+ export type { ExportFormat };
4
4
 
5
- export type ExportFormat = 'pdf' | 'excel' | 'csv' | 'json';
5
+ export type AnalyticsServiceType = 'traffic' | 'cohort' | 'funnel' | 'growth' | 'performance';
6
6
 
7
7
  export interface AnalyticsConfig {
8
8
  enabled?: boolean;
@@ -21,10 +21,8 @@ export interface DataConfig {
21
21
  }
22
22
 
23
23
  export interface ChartsConfig {
24
- defaultType?: ChartType;
25
24
  theme?: 'light' | 'dark' | 'auto';
26
25
  animations?: boolean;
27
- colors?: string[];
28
26
  }
29
27
 
30
28
  export interface PerformanceConfig {
@@ -47,17 +45,15 @@ export const DEFAULT_DASHBOARD_CONFIG: DashboardConfig = {
47
45
  realtime: true,
48
46
  export: {
49
47
  enabled: true,
50
- formats: ['pdf', 'excel', 'csv'],
48
+ formats: ['pdf', 'xlsx', 'csv'],
51
49
  },
52
50
  },
53
51
  data: {
54
52
  refreshInterval: 30000, cacheDuration: 300000, retryAttempts: 3,
55
53
  },
56
54
  charts: {
57
- defaultType: 'line',
58
55
  theme: 'auto',
59
56
  animations: true,
60
- colors: ['#6366f1', '#a855f7', '#f59e0b', '#10b981'],
61
57
  },
62
58
  performance: {
63
59
  lazyLoad: true,
@@ -0,0 +1,85 @@
1
+ import { describe, expect, it, vi } from "vitest";
2
+ import { fireEvent, render, screen } from "@testing-library/react";
3
+ import { AnalyticsLayout } from "./AnalyticsLayout";
4
+ import { presetRange } from "@umituz/web-design-system/organisms";
5
+
6
+ const kpis = [
7
+ { id: "rev", label: "Revenue", value: 120, previousValue: 100 },
8
+ { id: "users", label: "Users", value: 42 },
9
+ ];
10
+
11
+ describe("AnalyticsLayout", () => {
12
+ it("renders kpis through the design-system KpiCard with deltas", () => {
13
+ render(<AnalyticsLayout title="Analytics" kpis={kpis} />);
14
+ expect(screen.getByText("Revenue")).toBeTruthy();
15
+ expect(screen.getByText("120")).toBeTruthy();
16
+ expect(screen.getByText("+20.0%")).toBeTruthy();
17
+ expect(screen.getByText("Users")).toBeTruthy();
18
+ expect(screen.getByText("42")).toBeTruthy();
19
+ });
20
+
21
+ it("formats numeric kpi values through the format hook", () => {
22
+ render(
23
+ <AnalyticsLayout
24
+ title="A"
25
+ kpis={[{ id: "rev", label: "Revenue", value: 1200, format: (v) => `${v}₺` }]}
26
+ />,
27
+ );
28
+ expect(screen.getByText("1200₺")).toBeTruthy();
29
+ });
30
+
31
+ it("renders skeletons while loading and hides content", () => {
32
+ const { container } = render(
33
+ <AnalyticsLayout title="Analytics" loading kpis={kpis} charts={<div>chartbody</div>} />,
34
+ );
35
+ expect(container.querySelectorAll(".udb-analytics__kpi-skeleton")).toHaveLength(4);
36
+ expect(container.querySelector(".udb-analytics__chart-skeleton")).not.toBeNull();
37
+ expect(screen.queryByText("Revenue")).toBeNull();
38
+ expect(screen.queryByText("chartbody")).toBeNull();
39
+ });
40
+
41
+ it("shows the error state with a retry action", () => {
42
+ const onRetry = vi.fn();
43
+ render(<AnalyticsLayout title="Analytics" error="Load failed" onRetry={onRetry} />);
44
+ expect(screen.getByText("Load failed")).toBeTruthy();
45
+ fireEvent.click(screen.getByRole("button", { name: "Retry" }));
46
+ expect(onRetry).toHaveBeenCalledTimes(1);
47
+ });
48
+
49
+ it("wires refresh and export through custom labels", () => {
50
+ const onRefresh = vi.fn();
51
+ const onExport = vi.fn();
52
+ render(
53
+ <AnalyticsLayout
54
+ title="Analytics"
55
+ range={presetRange("30d")}
56
+ onRangeChange={() => undefined}
57
+ onRefresh={onRefresh}
58
+ onExport={onExport}
59
+ labels={{ refresh: "Yenile", export: "Dışa aktar" }}
60
+ />,
61
+ );
62
+ fireEvent.click(screen.getByRole("button", { name: "Yenile" }));
63
+ fireEvent.click(screen.getByRole("button", { name: "Dışa aktar" }));
64
+ expect(onRefresh).toHaveBeenCalledTimes(1);
65
+ expect(onExport).toHaveBeenCalledTimes(1);
66
+ });
67
+
68
+ it("renders the range picker, charts slot, filters slot and children", () => {
69
+ render(
70
+ <AnalyticsLayout
71
+ title="A"
72
+ range={presetRange("30d")}
73
+ onRangeChange={() => undefined}
74
+ filters={<div data-testid="filters">f</div>}
75
+ charts={<div data-testid="charts">c</div>}
76
+ >
77
+ <div data-testid="child">x</div>
78
+ </AnalyticsLayout>,
79
+ );
80
+ expect(screen.getByLabelText("Date range")).toBeTruthy();
81
+ expect(screen.getByTestId("filters")).toBeTruthy();
82
+ expect(screen.getByTestId("charts")).toBeTruthy();
83
+ expect(screen.getByTestId("child")).toBeTruthy();
84
+ });
85
+ });
@@ -1,89 +1,100 @@
1
- import { useMemo } from "react";
2
- import { RefreshCw, Download, Calendar, Loader2 } from "lucide-react";
1
+ import { Download, RefreshCw } from "lucide-react";
3
2
  import { cn } from "@umituz/web-design-system/utils/cn";
4
- import { Button } from "@umituz/web-design-system/atoms";
5
- import type { AnalyticsLayoutProps, AnalyticsPeriod } from "../types/analytics";
6
- import { AnalyticsCard } from "./AnalyticsCard";
7
- import { MetricCard } from "./MetricCard";
8
-
9
- const DEFAULT_PERIODS: AnalyticsPeriod[] = ["7d", "30d", "90d", "1y"];
3
+ import { Button, Skeleton } from "@umituz/web-design-system/atoms";
4
+ import {
5
+ DateRangePicker,
6
+ DEFAULT_RANGE_PRESETS,
7
+ EmptyState,
8
+ KpiCard,
9
+ } from "@umituz/web-design-system/organisms";
10
+ import type { KpiCardProps, RangePreset } from "@umituz/web-design-system/organisms";
11
+ import { toKpiDelta } from "../utils/analytics";
12
+ import type { AnalyticsLayoutLabels, AnalyticsLayoutProps, KpiDatum } from "../types/analytics";
13
+
14
+ const DEFAULT_PRESETS: readonly RangePreset[] = ["7d", "30d", "90d", "month"];
15
+
16
+ const DEFAULT_LABELS: Required<AnalyticsLayoutLabels> = {
17
+ refresh: "Refresh",
18
+ export: "Export",
19
+ retry: "Retry",
20
+ range: "Date range",
21
+ };
10
22
 
11
- export const AnalyticsLayout = ({
12
- config,
13
- labels,
23
+ function toKpiCardProps(kpi: KpiDatum): KpiCardProps {
24
+ return {
25
+ label: kpi.label,
26
+ value:
27
+ typeof kpi.value === "number"
28
+ ? kpi.format
29
+ ? kpi.format(kpi.value)
30
+ : String(kpi.value)
31
+ : kpi.value,
32
+ delta: toKpiDelta(kpi.value, kpi.previousValue, kpi.goodWhen),
33
+ hint: kpi.hint,
34
+ icon: kpi.icon,
35
+ iconTone: kpi.iconTone,
36
+ spark: kpi.spark,
37
+ onClick: kpi.onClick,
38
+ };
39
+ }
40
+
41
+ export function AnalyticsLayout({
14
42
  title,
15
43
  description,
16
- metrics,
17
- loading = false,
18
- period,
19
- onPeriodChange,
20
- showDateRange = true,
21
- showRefresh = true,
22
- showExport = true,
23
- charts,
24
- headerContent,
44
+ range,
45
+ onRangeChange,
46
+ presets = DEFAULT_PRESETS,
25
47
  onRefresh,
48
+ refreshing = false,
26
49
  onExport,
50
+ kpis,
51
+ charts,
52
+ filters,
53
+ loading = false,
54
+ error,
55
+ onRetry,
27
56
  children,
28
- }: AnalyticsLayoutProps) => {
29
- const visibleMetrics = useMemo(() => metrics ?? [], [metrics]);
30
-
31
- const showRefreshAction = showRefresh && Boolean(onRefresh);
32
- const showExportAction = showExport && Boolean(onExport);
57
+ className,
58
+ labels: labelOverrides,
59
+ }: AnalyticsLayoutProps) {
60
+ const labels = { ...DEFAULT_LABELS, ...labelOverrides };
61
+ const presetOptions = DEFAULT_RANGE_PRESETS.filter((option) => presets.includes(option.id));
62
+ const busy = loading || refreshing;
33
63
 
34
64
  return (
35
- <div className="udb-analytics">
65
+ <div className={cn("udb-analytics", className)}>
36
66
  <div className="udb-analytics__header">
37
67
  <div className="udb-analytics__heading">
38
- <h1 className="udb-analytics__title">{title ?? labels.title}</h1>
39
-
40
- {description && (
41
- <p className="udb-analytics__description">{description}</p>
42
-
43
- )}
68
+ <h1 className="udb-analytics__title">{title}</h1>
69
+ {description && <p className="udb-analytics__description">{description}</p>}
44
70
  </div>
45
71
 
46
72
  <div className="udb-analytics__actions">
47
- {showDateRange && onPeriodChange && period && (
48
- <label className="udb-period-select">
49
- <Calendar className="udb-period-select__icon" aria-hidden="true" />
50
- <span className="udb-sr-only">{labels.periodSelector}</span>
51
-
52
- <select
53
- className="udb-period-select__select"
54
- value={period}
55
- onChange={(e) => onPeriodChange(e.target.value as AnalyticsPeriod)}
56
- aria-label={labels.periodSelector}
57
- >
58
- {(config?.availablePeriods ?? DEFAULT_PERIODS).map((p) => (
59
- <option key={p} value={p}>
60
- {labels.periods[p] ?? p}
61
- </option>
62
-
63
- ))}
64
- </select>
65
-
66
- </label>
67
-
73
+ {range !== undefined && onRangeChange !== undefined && (
74
+ <DateRangePicker
75
+ value={range}
76
+ onChange={onRangeChange}
77
+ presets={presetOptions}
78
+ aria-label={labels.range}
79
+ />
68
80
  )}
69
81
 
70
- {showRefreshAction && (
82
+ {onRefresh !== undefined && (
71
83
  <Button
72
84
  variant="ghost"
73
85
  size="sm"
74
86
  onClick={onRefresh}
75
- disabled={loading}
87
+ disabled={busy}
76
88
  aria-label={labels.refresh}
77
89
  >
78
90
  <RefreshCw
79
- className={cn("udb-analytics__action-icon", loading && "udb-spin")}
91
+ className={cn("udb-analytics__action-icon", busy && "udb-spin")}
80
92
  aria-hidden="true"
81
93
  />
82
94
  </Button>
83
-
84
95
  )}
85
96
 
86
- {showExportAction && (
97
+ {onExport !== undefined && (
87
98
  <Button
88
99
  variant="ghost"
89
100
  size="sm"
@@ -93,61 +104,48 @@ export const AnalyticsLayout = ({
93
104
  >
94
105
  <Download className="udb-analytics__action-icon" aria-hidden="true" />
95
106
  <span>{labels.export}</span>
96
-
97
107
  </Button>
98
-
99
108
  )}
100
-
101
- {headerContent}
102
109
  </div>
103
-
104
110
  </div>
105
111
 
106
- {loading && (
107
- <div
108
- className="udb-analytics__loading"
109
- role="status"
110
- aria-live="polite"
111
- >
112
- <Loader2 className="udb-spin udb-analytics__loading-spinner" aria-hidden="true" />
113
- <span className="udb-sr-only">{labels.loading}</span>
114
-
115
- </div>
116
-
117
- )}
118
-
119
- {!loading && visibleMetrics.length > 0 && (
120
- <div
121
- className={cn(
122
- "udb-analytics__metrics",
123
- visibleMetrics.length >= 4 && "udb-analytics__metrics--wide",
112
+ {filters}
113
+
114
+ {error != null ? (
115
+ <EmptyState
116
+ className="udb-analytics__error"
117
+ title={error}
118
+ action={onRetry !== undefined ? { label: labels.retry, onClick: onRetry } : undefined}
119
+ />
120
+ ) : loading ? (
121
+ <>
122
+ <div className="udb-analytics__metrics" role="status" aria-live="polite">
123
+ {Array.from({ length: 4 }, (_, i) => (
124
+ <Skeleton key={i} className="udb-analytics__kpi-skeleton" />
125
+ ))}
126
+ </div>
127
+ <Skeleton className="udb-analytics__chart-skeleton" />
128
+ </>
129
+ ) : (
130
+ <>
131
+ {kpis !== undefined && kpis.length > 0 && (
132
+ <div
133
+ className={cn(
134
+ "udb-analytics__metrics",
135
+ kpis.length >= 4 && "udb-analytics__metrics--wide",
136
+ )}
137
+ >
138
+ {kpis.map((kpi) => (
139
+ <KpiCard key={kpi.id} {...toKpiCardProps(kpi)} />
140
+ ))}
141
+ </div>
124
142
  )}
125
- >
126
- {visibleMetrics.map((metric) => (
127
- <MetricCard key={metric.id} metric={metric} />
128
- ))}
129
- </div>
130
-
131
- )}
132
143
 
133
- {!loading && charts && charts.length > 0 && (
134
- <div className="udb-analytics__charts">
135
- {charts.map((chartConfig) => (
136
- <AnalyticsCard
137
- key={chartConfig.id}
138
- title={chartConfig.title}
139
- description={chartConfig.description}
140
- chart={chartConfig}
141
- />
142
- ))}
143
- </div>
144
+ {charts !== undefined && charts !== null && <div className="udb-analytics__charts">{charts}</div>}
144
145
 
146
+ {children}
147
+ </>
145
148
  )}
146
-
147
- {!loading && children}
148
149
  </div>
149
-
150
150
  );
151
- };
152
-
153
- export default AnalyticsLayout;
151
+ }
@@ -1,4 +1 @@
1
- export { MetricCard } from "./MetricCard";
2
- export { AnalyticsChart } from "./AnalyticsChart";
3
- export { AnalyticsCard } from "./AnalyticsCard";
4
1
  export { AnalyticsLayout } from "./AnalyticsLayout";
@@ -1,7 +1,7 @@
1
1
  export { useAnalytics, createStubAnalyticsApiClient } from "./useAnalytics";
2
2
  export type {
3
3
  AnalyticsApiClient,
4
- AnalyticsDataPayload,
4
+ AnalyticsPayload,
5
5
  UseAnalyticsOptions,
6
6
  UseAnalyticsReturn,
7
7
  } from "./useAnalytics";
@@ -0,0 +1,125 @@
1
+ import { afterEach, describe, expect, it, vi } from "vitest";
2
+ import { act, renderHook, waitFor } from "@testing-library/react";
3
+ import { presetRange } from "@umituz/web-design-system/organisms";
4
+ import type { DateRange } from "@umituz/web-design-system/organisms";
5
+ import { useAnalytics, createStubAnalyticsApiClient } from "./useAnalytics";
6
+ import type { AnalyticsPayload } from "./useAnalytics";
7
+
8
+ const payload: AnalyticsPayload = {
9
+ kpis: [{ id: "rev", label: "Revenue", value: 5 }],
10
+ series: [{ date: "2026-01-01", value: 5 }],
11
+ };
12
+
13
+ describe("useAnalytics", () => {
14
+ afterEach(() => {
15
+ vi.clearAllMocks();
16
+ vi.restoreAllMocks();
17
+ });
18
+
19
+ it("loads analytics for the default 30d range on mount", async () => {
20
+ const loadAnalytics = vi.fn(async (_range: DateRange) => payload);
21
+ const apiClient = { loadAnalytics };
22
+ const { result } = renderHook(() => useAnalytics({ apiClient }));
23
+
24
+ await waitFor(() => expect(result.current.isLoading).toBe(false));
25
+ expect(loadAnalytics).toHaveBeenCalledTimes(1);
26
+ const range = loadAnalytics.mock.calls[0]![0];
27
+ expect(range.preset).toBe("30d");
28
+ expect(range.to).toBe(new Date().toISOString().slice(0, 10));
29
+ expect(result.current.kpis).toEqual(payload.kpis);
30
+ expect(result.current.series).toEqual(payload.series);
31
+ expect(result.current.error).toBeNull();
32
+ });
33
+
34
+ it("honors an explicit initial range", async () => {
35
+ const loadAnalytics = vi.fn(async (_range: DateRange) => payload);
36
+ const initial = presetRange("7d");
37
+ const apiClient = { loadAnalytics };
38
+ const { result } = renderHook(() =>
39
+ useAnalytics({ apiClient, initialRange: initial }),
40
+ );
41
+ await waitFor(() => expect(result.current.isLoading).toBe(false));
42
+ expect(loadAnalytics.mock.calls[0]![0]).toEqual(initial);
43
+ });
44
+
45
+ it("refetches when the range changes", async () => {
46
+ const loadAnalytics = vi.fn(async (_range: DateRange) => payload);
47
+ const apiClient = { loadAnalytics };
48
+ const { result } = renderHook(() => useAnalytics({ apiClient }));
49
+ await waitFor(() => expect(result.current.isLoading).toBe(false));
50
+
51
+ act(() => result.current.updateRange(presetRange("7d")));
52
+ await waitFor(() => expect(loadAnalytics).toHaveBeenCalledTimes(2));
53
+ expect(loadAnalytics.mock.calls[1]![0].preset).toBe("7d");
54
+ });
55
+
56
+ it("surfaces load errors", async () => {
57
+ const apiClient = {
58
+ loadAnalytics: async () => {
59
+ throw new Error("boom");
60
+ },
61
+ };
62
+ const { result } = renderHook(() => useAnalytics({ apiClient }));
63
+ await waitFor(() => expect(result.current.error).toBe("boom"));
64
+ expect(result.current.isLoading).toBe(false);
65
+ });
66
+
67
+ it("discards a stale response that resolves after a newer one", async () => {
68
+ let resolveSlow!: (p: AnalyticsPayload) => void;
69
+ const slow = new Promise<AnalyticsPayload>((resolve) => {
70
+ resolveSlow = resolve;
71
+ });
72
+ let call = 0;
73
+ const loadAnalytics = vi.fn((_range: DateRange) => {
74
+ call += 1;
75
+ return call === 1 ? slow : Promise.resolve({ kpis: [], series: [{ date: "d", value: 2 }] });
76
+ });
77
+ const apiClient = { loadAnalytics };
78
+ const { result } = renderHook(() => useAnalytics({ apiClient }));
79
+
80
+ act(() => result.current.updateRange(presetRange("7d")));
81
+ await waitFor(() => expect(result.current.series).toEqual([{ date: "d", value: 2 }]));
82
+
83
+ await act(async () => {
84
+ resolveSlow({ kpis: [], series: [{ date: "stale", value: 9 }] });
85
+ });
86
+ expect(result.current.series).toEqual([{ date: "d", value: 2 }]);
87
+ });
88
+
89
+ it("refuses to export when the client has no exporter", async () => {
90
+ const apiClient = { loadAnalytics: async () => payload };
91
+ const { result } = renderHook(() => useAnalytics({ apiClient }));
92
+ await waitFor(() => expect(result.current.isLoading).toBe(false));
93
+
94
+ await expect(result.current.exportData({ format: "csv" })).rejects.toThrow(
95
+ "AnalyticsApiClient.exportAnalytics not configured",
96
+ );
97
+ });
98
+
99
+ it("downloads the blob produced by the client exporter", async () => {
100
+ const createObjectURL = vi.fn(() => "blob:csv");
101
+ const revokeObjectURL = vi.fn();
102
+ Object.defineProperty(URL, "createObjectURL", { value: createObjectURL, configurable: true });
103
+ Object.defineProperty(URL, "revokeObjectURL", { value: revokeObjectURL, configurable: true });
104
+ const click = vi.spyOn(HTMLAnchorElement.prototype, "click").mockImplementation(() => {});
105
+ const exportAnalytics = vi.fn(async () => new Blob(["a,b"], { type: "text/csv" }));
106
+
107
+ const apiClient = { loadAnalytics: async () => payload, exportAnalytics };
108
+ const { result } = renderHook(() => useAnalytics({ apiClient }));
109
+ await waitFor(() => expect(result.current.isLoading).toBe(false));
110
+
111
+ await act(async () => {
112
+ await result.current.exportData({ format: "csv", filename: "report.csv" });
113
+ });
114
+ expect(exportAnalytics).toHaveBeenCalledWith(payload, { format: "csv", filename: "report.csv" });
115
+ expect(click).toHaveBeenCalledTimes(1);
116
+ expect(revokeObjectURL).toHaveBeenCalledWith("blob:csv");
117
+ });
118
+
119
+ it("stubs reject until configured", async () => {
120
+ const stub = createStubAnalyticsApiClient();
121
+ await expect(stub.loadAnalytics(presetRange("30d"))).rejects.toThrow(
122
+ "AnalyticsApiClient not configured",
123
+ );
124
+ });
125
+ });