@nubitio/dashboard 0.7.4 → 0.8.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.
- package/dist/index.cjs +523 -335
- package/dist/index.d.cts +237 -20
- package/dist/index.d.mts +237 -20
- package/dist/index.mjs +510 -339
- package/dist/style.css +183 -2
- package/package.json +9 -3
package/dist/index.d.cts
CHANGED
|
@@ -1,4 +1,5 @@
|
|
|
1
1
|
import { BadgeVariant } from "@nubitio/ui";
|
|
2
|
+
import { ComponentType } from "react";
|
|
2
3
|
|
|
3
4
|
//#region packages/dashboard/dashboard/types.d.ts
|
|
4
5
|
type ValueFormat = 'text' | 'number' | 'currency' | 'percent' | 'date' | 'datetime';
|
|
@@ -13,34 +14,42 @@ interface TrendConfig {
|
|
|
13
14
|
invertColors?: boolean;
|
|
14
15
|
}
|
|
15
16
|
type StatIconTone = 'accent' | 'success' | 'warning' | 'danger' | 'info';
|
|
16
|
-
|
|
17
|
-
|
|
17
|
+
/** Independent data source for a single widget — bypasses the dashboard's shared payload. */
|
|
18
|
+
interface WidgetQueryConfig {
|
|
19
|
+
/** GET endpoint, relative or absolute — resolved the same way as `DashboardConfig.dataUrl`. */
|
|
20
|
+
url: string;
|
|
21
|
+
params?: Record<string, string>;
|
|
22
|
+
/** Include the dashboard's resolved period as query params and refetch when it changes. Defaults to true. */
|
|
23
|
+
usePeriod?: boolean;
|
|
24
|
+
refreshInterval?: number;
|
|
25
|
+
}
|
|
26
|
+
interface BaseWidgetConfig {
|
|
18
27
|
id: string;
|
|
19
28
|
title: string;
|
|
29
|
+
menuVisible?: boolean;
|
|
30
|
+
/** Fetches this widget's data independently via react-query instead of reading the dashboard's shared payload. */
|
|
31
|
+
query?: WidgetQueryConfig;
|
|
32
|
+
}
|
|
33
|
+
interface StatWidgetConfig extends BaseWidgetConfig {
|
|
34
|
+
type: 'stat';
|
|
20
35
|
valuePath?: string;
|
|
21
36
|
value?: string | number;
|
|
22
37
|
format?: ValueFormat;
|
|
23
38
|
icon?: string;
|
|
24
39
|
iconTone?: StatIconTone;
|
|
25
40
|
trend?: TrendConfig;
|
|
26
|
-
menuVisible?: boolean;
|
|
27
41
|
}
|
|
28
|
-
interface BarChartWidgetConfig {
|
|
42
|
+
interface BarChartWidgetConfig extends BaseWidgetConfig {
|
|
29
43
|
type: 'bar-chart';
|
|
30
|
-
id: string;
|
|
31
|
-
title: string;
|
|
32
44
|
subtitle?: string;
|
|
33
45
|
dataPath: string;
|
|
34
46
|
xKey: string;
|
|
35
47
|
yKey: string;
|
|
36
48
|
valueFormat?: ValueFormat;
|
|
37
49
|
height?: number;
|
|
38
|
-
menuVisible?: boolean;
|
|
39
50
|
}
|
|
40
|
-
interface DonutChartWidgetConfig {
|
|
51
|
+
interface DonutChartWidgetConfig extends BaseWidgetConfig {
|
|
41
52
|
type: 'donut-chart';
|
|
42
|
-
id: string;
|
|
43
|
-
title: string;
|
|
44
53
|
subtitle?: string;
|
|
45
54
|
dataPath: string;
|
|
46
55
|
labelKey: string;
|
|
@@ -50,7 +59,6 @@ interface DonutChartWidgetConfig {
|
|
|
50
59
|
centerLabel?: string;
|
|
51
60
|
centerValuePath?: string;
|
|
52
61
|
valueFormat?: ValueFormat;
|
|
53
|
-
menuVisible?: boolean;
|
|
54
62
|
}
|
|
55
63
|
interface TableColumnConfig {
|
|
56
64
|
key: string;
|
|
@@ -64,19 +72,68 @@ interface TableViewAllConfig {
|
|
|
64
72
|
to: string;
|
|
65
73
|
label?: string;
|
|
66
74
|
}
|
|
67
|
-
interface TableWidgetConfig {
|
|
75
|
+
interface TableWidgetConfig extends BaseWidgetConfig {
|
|
68
76
|
type: 'table';
|
|
69
|
-
id: string;
|
|
70
|
-
title: string;
|
|
71
77
|
subtitle?: string;
|
|
72
78
|
dataPath: string;
|
|
73
79
|
columns: TableColumnConfig[];
|
|
74
80
|
viewAll?: TableViewAllConfig;
|
|
75
81
|
emptyTitle?: string;
|
|
76
82
|
emptyDescription?: string;
|
|
77
|
-
menuVisible?: boolean;
|
|
78
83
|
}
|
|
79
|
-
|
|
84
|
+
interface ChartSeriesConfig {
|
|
85
|
+
/** Numeric field within each row of `dataPath`. */
|
|
86
|
+
key: string;
|
|
87
|
+
label?: string;
|
|
88
|
+
color?: string;
|
|
89
|
+
valueFormat?: ValueFormat;
|
|
90
|
+
}
|
|
91
|
+
interface LineChartWidgetConfig extends BaseWidgetConfig {
|
|
92
|
+
type: 'line-chart';
|
|
93
|
+
subtitle?: string;
|
|
94
|
+
dataPath: string;
|
|
95
|
+
xKey: string;
|
|
96
|
+
/** One entry renders a single line; multiple entries render a multi-series chart. */
|
|
97
|
+
series: ChartSeriesConfig[];
|
|
98
|
+
valueFormat?: ValueFormat;
|
|
99
|
+
height?: number;
|
|
100
|
+
showLegend?: boolean;
|
|
101
|
+
showGrid?: boolean;
|
|
102
|
+
curved?: boolean;
|
|
103
|
+
}
|
|
104
|
+
interface AreaChartWidgetConfig extends BaseWidgetConfig {
|
|
105
|
+
type: 'area-chart';
|
|
106
|
+
subtitle?: string;
|
|
107
|
+
dataPath: string;
|
|
108
|
+
xKey: string;
|
|
109
|
+
series: ChartSeriesConfig[];
|
|
110
|
+
stacked?: boolean;
|
|
111
|
+
valueFormat?: ValueFormat;
|
|
112
|
+
height?: number;
|
|
113
|
+
showLegend?: boolean;
|
|
114
|
+
showGrid?: boolean;
|
|
115
|
+
}
|
|
116
|
+
interface ProgressWidgetConfig extends BaseWidgetConfig {
|
|
117
|
+
type: 'progress';
|
|
118
|
+
subtitle?: string;
|
|
119
|
+
valuePath?: string;
|
|
120
|
+
value?: number;
|
|
121
|
+
maxPath?: string;
|
|
122
|
+
/** Defaults to 100. */
|
|
123
|
+
max?: number;
|
|
124
|
+
format?: ValueFormat;
|
|
125
|
+
tone?: StatIconTone;
|
|
126
|
+
}
|
|
127
|
+
/**
|
|
128
|
+
* Escape hatch for widget types registered via `registerWidgetType` that aren't
|
|
129
|
+
* one of the built-ins. `type` is intentionally a plain `string` so third-party
|
|
130
|
+
* widget types type-check without editing this union.
|
|
131
|
+
*/
|
|
132
|
+
interface CustomWidgetConfig extends BaseWidgetConfig {
|
|
133
|
+
type: string;
|
|
134
|
+
[key: string]: unknown;
|
|
135
|
+
}
|
|
136
|
+
type DashboardWidget = StatWidgetConfig | BarChartWidgetConfig | DonutChartWidgetConfig | LineChartWidgetConfig | AreaChartWidgetConfig | ProgressWidgetConfig | TableWidgetConfig | CustomWidgetConfig;
|
|
80
137
|
type DashboardSectionLayout = 'stats' | 'charts' | 'full' | 'grid';
|
|
81
138
|
interface DashboardSection {
|
|
82
139
|
id?: string;
|
|
@@ -91,15 +148,49 @@ interface DashboardDataResult {
|
|
|
91
148
|
error?: string | null;
|
|
92
149
|
refetch?: () => void;
|
|
93
150
|
}
|
|
151
|
+
/** Resolved period selection, passed to `useData` and appended to `dataUrl`. */
|
|
152
|
+
interface DashboardPeriodValue {
|
|
153
|
+
presetKey: string;
|
|
154
|
+
/** ISO date, e.g. `2026-06-01`. */
|
|
155
|
+
start: string;
|
|
156
|
+
/** ISO date, e.g. `2026-06-30`. */
|
|
157
|
+
end: string;
|
|
158
|
+
}
|
|
159
|
+
interface DashboardPeriodPreset {
|
|
160
|
+
key: string;
|
|
161
|
+
label: string;
|
|
162
|
+
/** Computes the ISO date range for this preset, relative to `today`. */
|
|
163
|
+
getRange: (today: Date) => {
|
|
164
|
+
start: string;
|
|
165
|
+
end: string;
|
|
166
|
+
};
|
|
167
|
+
}
|
|
168
|
+
interface DashboardPeriodConfig {
|
|
169
|
+
presets?: DashboardPeriodPreset[];
|
|
170
|
+
defaultPreset?: string;
|
|
171
|
+
/** Shows a "Custom" segment that opens a date-range picker. Defaults to true. */
|
|
172
|
+
allowCustomRange?: boolean;
|
|
173
|
+
/** Query param names appended to `dataUrl`. Defaults to `{ start: 'from', end: 'to' }`. */
|
|
174
|
+
paramNames?: {
|
|
175
|
+
start: string;
|
|
176
|
+
end: string;
|
|
177
|
+
};
|
|
178
|
+
/** URL search param used to persist the selection. Defaults to `period`. */
|
|
179
|
+
urlParam?: string;
|
|
180
|
+
}
|
|
94
181
|
interface DashboardConfig {
|
|
95
182
|
id?: string;
|
|
96
183
|
title: string;
|
|
97
184
|
/** GET endpoint returning the dashboard JSON payload. */
|
|
98
185
|
dataUrl?: string;
|
|
99
|
-
/** Custom data hook — takes precedence over `dataUrl`. */
|
|
100
|
-
useData?: () => DashboardDataResult;
|
|
186
|
+
/** Custom data hook — takes precedence over `dataUrl`. Receives the resolved period when `period` is configured. */
|
|
187
|
+
useData?: (period?: DashboardPeriodValue) => DashboardDataResult;
|
|
101
188
|
sections: DashboardSection[];
|
|
102
189
|
refreshInterval?: number;
|
|
190
|
+
/** Enables a period filter in the toolbar; omit to disable. */
|
|
191
|
+
period?: DashboardPeriodConfig;
|
|
192
|
+
/** Lets end users hide/reorder widgets within a section; persisted to localStorage per `id`. */
|
|
193
|
+
customizable?: boolean;
|
|
103
194
|
}
|
|
104
195
|
//#endregion
|
|
105
196
|
//#region packages/dashboard/dashboard/defineDashboard.d.ts
|
|
@@ -128,14 +219,137 @@ declare function DashboardPage({
|
|
|
128
219
|
config
|
|
129
220
|
}: DashboardPageProps): import("react").JSX.Element;
|
|
130
221
|
//#endregion
|
|
222
|
+
//#region packages/dashboard/dashboard/useDashboardPeriod.d.ts
|
|
223
|
+
declare const CUSTOM_PERIOD_KEY = "custom";
|
|
224
|
+
interface DashboardPeriodState {
|
|
225
|
+
value: DashboardPeriodValue;
|
|
226
|
+
presets: DashboardPeriodConfig['presets'];
|
|
227
|
+
allowCustomRange: boolean;
|
|
228
|
+
setPreset: (key: string) => void;
|
|
229
|
+
setCustomRange: (start: string, end: string) => void;
|
|
230
|
+
}
|
|
231
|
+
declare function useDashboardPeriod(config?: DashboardPeriodConfig): DashboardPeriodState | undefined;
|
|
232
|
+
//#endregion
|
|
233
|
+
//#region packages/dashboard/dashboard/DashboardPeriodFilter.d.ts
|
|
234
|
+
declare function DashboardPeriodFilter({
|
|
235
|
+
period
|
|
236
|
+
}: {
|
|
237
|
+
period: DashboardPeriodState;
|
|
238
|
+
}): import("react").JSX.Element;
|
|
239
|
+
//#endregion
|
|
240
|
+
//#region packages/dashboard/dashboard/useDashboardLayout.d.ts
|
|
241
|
+
interface HiddenWidgetEntry {
|
|
242
|
+
sectionId: string;
|
|
243
|
+
widget: DashboardWidget;
|
|
244
|
+
}
|
|
245
|
+
interface DashboardLayoutState {
|
|
246
|
+
editMode: boolean;
|
|
247
|
+
setEditMode: (value: boolean) => void;
|
|
248
|
+
getSectionWidgets: (section: DashboardSection, sectionId: string) => DashboardWidget[];
|
|
249
|
+
hiddenWidgets: HiddenWidgetEntry[];
|
|
250
|
+
hideWidget: (sectionId: string, widgetId: string) => void;
|
|
251
|
+
showWidget: (sectionId: string, widgetId: string) => void;
|
|
252
|
+
moveWidget: (sectionId: string, widgetId: string, direction: -1 | 1) => void;
|
|
253
|
+
resetLayout: () => void;
|
|
254
|
+
}
|
|
255
|
+
declare function useDashboardLayout(dashboardId: string | undefined, sections: DashboardSection[], enabled: boolean): DashboardLayoutState | undefined;
|
|
256
|
+
//#endregion
|
|
257
|
+
//#region packages/dashboard/dashboard/DashboardLayoutControls.d.ts
|
|
258
|
+
declare function DashboardLayoutControls({
|
|
259
|
+
layout
|
|
260
|
+
}: {
|
|
261
|
+
layout: DashboardLayoutState;
|
|
262
|
+
}): import("react").JSX.Element;
|
|
263
|
+
//#endregion
|
|
264
|
+
//#region packages/dashboard/dashboard/DashboardWidgetSlot.d.ts
|
|
265
|
+
type Props = {
|
|
266
|
+
widget: DashboardWidget;
|
|
267
|
+
data: Record<string, unknown>;
|
|
268
|
+
loading?: boolean;
|
|
269
|
+
editMode: boolean;
|
|
270
|
+
onHide: () => void;
|
|
271
|
+
onMoveUp: () => void;
|
|
272
|
+
onMoveDown: () => void;
|
|
273
|
+
period?: DashboardPeriodValue;
|
|
274
|
+
periodParamNames?: {
|
|
275
|
+
start: string;
|
|
276
|
+
end: string;
|
|
277
|
+
};
|
|
278
|
+
};
|
|
279
|
+
declare function DashboardWidgetSlot({
|
|
280
|
+
widget,
|
|
281
|
+
data,
|
|
282
|
+
loading,
|
|
283
|
+
editMode,
|
|
284
|
+
onHide,
|
|
285
|
+
onMoveUp,
|
|
286
|
+
onMoveDown,
|
|
287
|
+
period,
|
|
288
|
+
periodParamNames
|
|
289
|
+
}: Props): import("react").JSX.Element;
|
|
290
|
+
//#endregion
|
|
131
291
|
//#region packages/dashboard/dashboard/useDashboardData.d.ts
|
|
132
|
-
declare function useDashboardData(dataUrl?: string, refreshInterval?: number
|
|
292
|
+
declare function useDashboardData(dataUrl?: string, refreshInterval?: number, period?: DashboardPeriodValue, periodParamNames?: {
|
|
293
|
+
start: string;
|
|
294
|
+
end: string;
|
|
295
|
+
}): DashboardDataResult;
|
|
296
|
+
//#endregion
|
|
297
|
+
//#region packages/dashboard/dashboard/useWidgetQuery.d.ts
|
|
298
|
+
interface WidgetQueryResult {
|
|
299
|
+
data: Record<string, unknown>;
|
|
300
|
+
loading: boolean;
|
|
301
|
+
error: string | null;
|
|
302
|
+
}
|
|
303
|
+
/**
|
|
304
|
+
* Fetches a single widget's data independently of the dashboard's shared
|
|
305
|
+
* payload — its own cache entry, its own loading/error state, no head-of-line
|
|
306
|
+
* blocking behind slower widgets. Returns `undefined` when the widget has no
|
|
307
|
+
* `query` configured, so callers fall back to the dashboard's shared data.
|
|
308
|
+
*/
|
|
309
|
+
declare function useWidgetQuery(query: WidgetQueryConfig | undefined, period: DashboardPeriodValue | undefined, periodParamNames?: {
|
|
310
|
+
start: string;
|
|
311
|
+
end: string;
|
|
312
|
+
}): WidgetQueryResult | undefined;
|
|
313
|
+
//#endregion
|
|
314
|
+
//#region packages/dashboard/dashboard/periodPresets.d.ts
|
|
315
|
+
declare const DEFAULT_PERIOD_PRESETS: DashboardPeriodPreset[];
|
|
316
|
+
declare function getPeriodPreset(key: string, presets?: DashboardPeriodPreset[]): DashboardPeriodPreset | undefined;
|
|
317
|
+
//#endregion
|
|
318
|
+
//#region packages/dashboard/dashboard/defaults.d.ts
|
|
319
|
+
declare const DEFAULT_PERIOD_PARAM_NAMES: {
|
|
320
|
+
readonly start: "from";
|
|
321
|
+
readonly end: "to";
|
|
322
|
+
};
|
|
323
|
+
//#endregion
|
|
324
|
+
//#region packages/dashboard/dashboard/widgetRegistry.d.ts
|
|
325
|
+
interface WidgetViewProps<W extends DashboardWidget = DashboardWidget> {
|
|
326
|
+
widget: W;
|
|
327
|
+
data: Record<string, unknown>;
|
|
328
|
+
loading?: boolean;
|
|
329
|
+
}
|
|
330
|
+
type WidgetComponent = ComponentType<WidgetViewProps<any>>;
|
|
331
|
+
/**
|
|
332
|
+
* Registers a component to render for `widget.type`. Built-in types (`stat`,
|
|
333
|
+
* `bar-chart`, `donut-chart`, `line-chart`, `area-chart`, `progress`, `table`)
|
|
334
|
+
* are registered automatically. Call this to add a new widget type — or to
|
|
335
|
+
* replace a built-in one — without forking `@nubitio/dashboard`.
|
|
336
|
+
*
|
|
337
|
+
* ```ts
|
|
338
|
+
* registerWidgetType('funnel', FunnelWidgetView);
|
|
339
|
+
* ```
|
|
340
|
+
*/
|
|
341
|
+
declare function registerWidgetType(type: string, component: WidgetComponent): void;
|
|
342
|
+
declare function getWidgetComponent(type: string): WidgetComponent | undefined;
|
|
343
|
+
declare function isWidgetTypeRegistered(type: string): boolean;
|
|
133
344
|
//#endregion
|
|
134
345
|
//#region packages/dashboard/dashboard/widgetBuilders.d.ts
|
|
135
346
|
declare function statWidget(config: Omit<StatWidgetConfig, 'type'>): StatWidgetConfig;
|
|
136
347
|
declare function barChartWidget(config: Omit<BarChartWidgetConfig, 'type'>): BarChartWidgetConfig;
|
|
137
348
|
declare function donutChartWidget(config: Omit<DonutChartWidgetConfig, 'type'>): DonutChartWidgetConfig;
|
|
138
349
|
declare function tableWidget(config: Omit<TableWidgetConfig, 'type'>): TableWidgetConfig;
|
|
350
|
+
declare function lineChartWidget(config: Omit<LineChartWidgetConfig, 'type'>): LineChartWidgetConfig;
|
|
351
|
+
declare function areaChartWidget(config: Omit<AreaChartWidgetConfig, 'type'>): AreaChartWidgetConfig;
|
|
352
|
+
declare function progressWidget(config: Omit<ProgressWidgetConfig, 'type'>): ProgressWidgetConfig;
|
|
139
353
|
//#endregion
|
|
140
354
|
//#region packages/dashboard/dashboard/resolvePath.d.ts
|
|
141
355
|
declare function resolvePath(source: unknown, path?: string): unknown;
|
|
@@ -144,4 +358,7 @@ declare function resolveArray(source: unknown, path: string): Record<string, unk
|
|
|
144
358
|
//#region packages/dashboard/dashboard/formatValue.d.ts
|
|
145
359
|
declare function formatDashboardValue(value: unknown, format?: ValueFormat): string;
|
|
146
360
|
//#endregion
|
|
147
|
-
|
|
361
|
+
//#region packages/dashboard/dashboard/chartPalette.d.ts
|
|
362
|
+
declare const DEFAULT_CHART_COLORS: string[];
|
|
363
|
+
//#endregion
|
|
364
|
+
export { type AreaChartWidgetConfig, type BarChartWidgetConfig, type BaseWidgetConfig, CUSTOM_PERIOD_KEY, type ChartSeriesConfig, type CustomWidgetConfig, DEFAULT_CHART_COLORS, DEFAULT_PERIOD_PARAM_NAMES, DEFAULT_PERIOD_PRESETS, type DashboardConfig, type DashboardDataResult, DashboardLayoutControls, type DashboardLayoutState, DashboardPage, type DashboardPageProps, type DashboardPeriodConfig, DashboardPeriodFilter, type DashboardPeriodPreset, type DashboardPeriodState, type DashboardPeriodValue, type DashboardSection, type DashboardSectionLayout, type DashboardWidget, DashboardWidgetSlot, type DonutChartWidgetConfig, type HiddenWidgetEntry, type LineChartWidgetConfig, type ProgressWidgetConfig, type StatIconTone, type StatWidgetConfig, type TableColumnConfig, type TableViewAllConfig, type TableWidgetConfig, type TrendConfig, type ValueFormat, type WidgetComponent, type WidgetQueryConfig, type WidgetQueryResult, type WidgetViewProps, areaChartWidget, barChartWidget, defineDashboard, donutChartWidget, formatDashboardValue, getPeriodPreset, getWidgetComponent, isWidgetTypeRegistered, lineChartWidget, progressWidget, registerWidgetType, resolveArray, resolvePath, statWidget, tableWidget, useDashboardData, useDashboardLayout, useDashboardPeriod, useWidgetQuery };
|
package/dist/index.d.mts
CHANGED
|
@@ -1,4 +1,5 @@
|
|
|
1
1
|
import { BadgeVariant } from "@nubitio/ui";
|
|
2
|
+
import { ComponentType } from "react";
|
|
2
3
|
|
|
3
4
|
//#region packages/dashboard/dashboard/types.d.ts
|
|
4
5
|
type ValueFormat = 'text' | 'number' | 'currency' | 'percent' | 'date' | 'datetime';
|
|
@@ -13,34 +14,42 @@ interface TrendConfig {
|
|
|
13
14
|
invertColors?: boolean;
|
|
14
15
|
}
|
|
15
16
|
type StatIconTone = 'accent' | 'success' | 'warning' | 'danger' | 'info';
|
|
16
|
-
|
|
17
|
-
|
|
17
|
+
/** Independent data source for a single widget — bypasses the dashboard's shared payload. */
|
|
18
|
+
interface WidgetQueryConfig {
|
|
19
|
+
/** GET endpoint, relative or absolute — resolved the same way as `DashboardConfig.dataUrl`. */
|
|
20
|
+
url: string;
|
|
21
|
+
params?: Record<string, string>;
|
|
22
|
+
/** Include the dashboard's resolved period as query params and refetch when it changes. Defaults to true. */
|
|
23
|
+
usePeriod?: boolean;
|
|
24
|
+
refreshInterval?: number;
|
|
25
|
+
}
|
|
26
|
+
interface BaseWidgetConfig {
|
|
18
27
|
id: string;
|
|
19
28
|
title: string;
|
|
29
|
+
menuVisible?: boolean;
|
|
30
|
+
/** Fetches this widget's data independently via react-query instead of reading the dashboard's shared payload. */
|
|
31
|
+
query?: WidgetQueryConfig;
|
|
32
|
+
}
|
|
33
|
+
interface StatWidgetConfig extends BaseWidgetConfig {
|
|
34
|
+
type: 'stat';
|
|
20
35
|
valuePath?: string;
|
|
21
36
|
value?: string | number;
|
|
22
37
|
format?: ValueFormat;
|
|
23
38
|
icon?: string;
|
|
24
39
|
iconTone?: StatIconTone;
|
|
25
40
|
trend?: TrendConfig;
|
|
26
|
-
menuVisible?: boolean;
|
|
27
41
|
}
|
|
28
|
-
interface BarChartWidgetConfig {
|
|
42
|
+
interface BarChartWidgetConfig extends BaseWidgetConfig {
|
|
29
43
|
type: 'bar-chart';
|
|
30
|
-
id: string;
|
|
31
|
-
title: string;
|
|
32
44
|
subtitle?: string;
|
|
33
45
|
dataPath: string;
|
|
34
46
|
xKey: string;
|
|
35
47
|
yKey: string;
|
|
36
48
|
valueFormat?: ValueFormat;
|
|
37
49
|
height?: number;
|
|
38
|
-
menuVisible?: boolean;
|
|
39
50
|
}
|
|
40
|
-
interface DonutChartWidgetConfig {
|
|
51
|
+
interface DonutChartWidgetConfig extends BaseWidgetConfig {
|
|
41
52
|
type: 'donut-chart';
|
|
42
|
-
id: string;
|
|
43
|
-
title: string;
|
|
44
53
|
subtitle?: string;
|
|
45
54
|
dataPath: string;
|
|
46
55
|
labelKey: string;
|
|
@@ -50,7 +59,6 @@ interface DonutChartWidgetConfig {
|
|
|
50
59
|
centerLabel?: string;
|
|
51
60
|
centerValuePath?: string;
|
|
52
61
|
valueFormat?: ValueFormat;
|
|
53
|
-
menuVisible?: boolean;
|
|
54
62
|
}
|
|
55
63
|
interface TableColumnConfig {
|
|
56
64
|
key: string;
|
|
@@ -64,19 +72,68 @@ interface TableViewAllConfig {
|
|
|
64
72
|
to: string;
|
|
65
73
|
label?: string;
|
|
66
74
|
}
|
|
67
|
-
interface TableWidgetConfig {
|
|
75
|
+
interface TableWidgetConfig extends BaseWidgetConfig {
|
|
68
76
|
type: 'table';
|
|
69
|
-
id: string;
|
|
70
|
-
title: string;
|
|
71
77
|
subtitle?: string;
|
|
72
78
|
dataPath: string;
|
|
73
79
|
columns: TableColumnConfig[];
|
|
74
80
|
viewAll?: TableViewAllConfig;
|
|
75
81
|
emptyTitle?: string;
|
|
76
82
|
emptyDescription?: string;
|
|
77
|
-
menuVisible?: boolean;
|
|
78
83
|
}
|
|
79
|
-
|
|
84
|
+
interface ChartSeriesConfig {
|
|
85
|
+
/** Numeric field within each row of `dataPath`. */
|
|
86
|
+
key: string;
|
|
87
|
+
label?: string;
|
|
88
|
+
color?: string;
|
|
89
|
+
valueFormat?: ValueFormat;
|
|
90
|
+
}
|
|
91
|
+
interface LineChartWidgetConfig extends BaseWidgetConfig {
|
|
92
|
+
type: 'line-chart';
|
|
93
|
+
subtitle?: string;
|
|
94
|
+
dataPath: string;
|
|
95
|
+
xKey: string;
|
|
96
|
+
/** One entry renders a single line; multiple entries render a multi-series chart. */
|
|
97
|
+
series: ChartSeriesConfig[];
|
|
98
|
+
valueFormat?: ValueFormat;
|
|
99
|
+
height?: number;
|
|
100
|
+
showLegend?: boolean;
|
|
101
|
+
showGrid?: boolean;
|
|
102
|
+
curved?: boolean;
|
|
103
|
+
}
|
|
104
|
+
interface AreaChartWidgetConfig extends BaseWidgetConfig {
|
|
105
|
+
type: 'area-chart';
|
|
106
|
+
subtitle?: string;
|
|
107
|
+
dataPath: string;
|
|
108
|
+
xKey: string;
|
|
109
|
+
series: ChartSeriesConfig[];
|
|
110
|
+
stacked?: boolean;
|
|
111
|
+
valueFormat?: ValueFormat;
|
|
112
|
+
height?: number;
|
|
113
|
+
showLegend?: boolean;
|
|
114
|
+
showGrid?: boolean;
|
|
115
|
+
}
|
|
116
|
+
interface ProgressWidgetConfig extends BaseWidgetConfig {
|
|
117
|
+
type: 'progress';
|
|
118
|
+
subtitle?: string;
|
|
119
|
+
valuePath?: string;
|
|
120
|
+
value?: number;
|
|
121
|
+
maxPath?: string;
|
|
122
|
+
/** Defaults to 100. */
|
|
123
|
+
max?: number;
|
|
124
|
+
format?: ValueFormat;
|
|
125
|
+
tone?: StatIconTone;
|
|
126
|
+
}
|
|
127
|
+
/**
|
|
128
|
+
* Escape hatch for widget types registered via `registerWidgetType` that aren't
|
|
129
|
+
* one of the built-ins. `type` is intentionally a plain `string` so third-party
|
|
130
|
+
* widget types type-check without editing this union.
|
|
131
|
+
*/
|
|
132
|
+
interface CustomWidgetConfig extends BaseWidgetConfig {
|
|
133
|
+
type: string;
|
|
134
|
+
[key: string]: unknown;
|
|
135
|
+
}
|
|
136
|
+
type DashboardWidget = StatWidgetConfig | BarChartWidgetConfig | DonutChartWidgetConfig | LineChartWidgetConfig | AreaChartWidgetConfig | ProgressWidgetConfig | TableWidgetConfig | CustomWidgetConfig;
|
|
80
137
|
type DashboardSectionLayout = 'stats' | 'charts' | 'full' | 'grid';
|
|
81
138
|
interface DashboardSection {
|
|
82
139
|
id?: string;
|
|
@@ -91,15 +148,49 @@ interface DashboardDataResult {
|
|
|
91
148
|
error?: string | null;
|
|
92
149
|
refetch?: () => void;
|
|
93
150
|
}
|
|
151
|
+
/** Resolved period selection, passed to `useData` and appended to `dataUrl`. */
|
|
152
|
+
interface DashboardPeriodValue {
|
|
153
|
+
presetKey: string;
|
|
154
|
+
/** ISO date, e.g. `2026-06-01`. */
|
|
155
|
+
start: string;
|
|
156
|
+
/** ISO date, e.g. `2026-06-30`. */
|
|
157
|
+
end: string;
|
|
158
|
+
}
|
|
159
|
+
interface DashboardPeriodPreset {
|
|
160
|
+
key: string;
|
|
161
|
+
label: string;
|
|
162
|
+
/** Computes the ISO date range for this preset, relative to `today`. */
|
|
163
|
+
getRange: (today: Date) => {
|
|
164
|
+
start: string;
|
|
165
|
+
end: string;
|
|
166
|
+
};
|
|
167
|
+
}
|
|
168
|
+
interface DashboardPeriodConfig {
|
|
169
|
+
presets?: DashboardPeriodPreset[];
|
|
170
|
+
defaultPreset?: string;
|
|
171
|
+
/** Shows a "Custom" segment that opens a date-range picker. Defaults to true. */
|
|
172
|
+
allowCustomRange?: boolean;
|
|
173
|
+
/** Query param names appended to `dataUrl`. Defaults to `{ start: 'from', end: 'to' }`. */
|
|
174
|
+
paramNames?: {
|
|
175
|
+
start: string;
|
|
176
|
+
end: string;
|
|
177
|
+
};
|
|
178
|
+
/** URL search param used to persist the selection. Defaults to `period`. */
|
|
179
|
+
urlParam?: string;
|
|
180
|
+
}
|
|
94
181
|
interface DashboardConfig {
|
|
95
182
|
id?: string;
|
|
96
183
|
title: string;
|
|
97
184
|
/** GET endpoint returning the dashboard JSON payload. */
|
|
98
185
|
dataUrl?: string;
|
|
99
|
-
/** Custom data hook — takes precedence over `dataUrl`. */
|
|
100
|
-
useData?: () => DashboardDataResult;
|
|
186
|
+
/** Custom data hook — takes precedence over `dataUrl`. Receives the resolved period when `period` is configured. */
|
|
187
|
+
useData?: (period?: DashboardPeriodValue) => DashboardDataResult;
|
|
101
188
|
sections: DashboardSection[];
|
|
102
189
|
refreshInterval?: number;
|
|
190
|
+
/** Enables a period filter in the toolbar; omit to disable. */
|
|
191
|
+
period?: DashboardPeriodConfig;
|
|
192
|
+
/** Lets end users hide/reorder widgets within a section; persisted to localStorage per `id`. */
|
|
193
|
+
customizable?: boolean;
|
|
103
194
|
}
|
|
104
195
|
//#endregion
|
|
105
196
|
//#region packages/dashboard/dashboard/defineDashboard.d.ts
|
|
@@ -128,14 +219,137 @@ declare function DashboardPage({
|
|
|
128
219
|
config
|
|
129
220
|
}: DashboardPageProps): import("react").JSX.Element;
|
|
130
221
|
//#endregion
|
|
222
|
+
//#region packages/dashboard/dashboard/useDashboardPeriod.d.ts
|
|
223
|
+
declare const CUSTOM_PERIOD_KEY = "custom";
|
|
224
|
+
interface DashboardPeriodState {
|
|
225
|
+
value: DashboardPeriodValue;
|
|
226
|
+
presets: DashboardPeriodConfig['presets'];
|
|
227
|
+
allowCustomRange: boolean;
|
|
228
|
+
setPreset: (key: string) => void;
|
|
229
|
+
setCustomRange: (start: string, end: string) => void;
|
|
230
|
+
}
|
|
231
|
+
declare function useDashboardPeriod(config?: DashboardPeriodConfig): DashboardPeriodState | undefined;
|
|
232
|
+
//#endregion
|
|
233
|
+
//#region packages/dashboard/dashboard/DashboardPeriodFilter.d.ts
|
|
234
|
+
declare function DashboardPeriodFilter({
|
|
235
|
+
period
|
|
236
|
+
}: {
|
|
237
|
+
period: DashboardPeriodState;
|
|
238
|
+
}): import("react").JSX.Element;
|
|
239
|
+
//#endregion
|
|
240
|
+
//#region packages/dashboard/dashboard/useDashboardLayout.d.ts
|
|
241
|
+
interface HiddenWidgetEntry {
|
|
242
|
+
sectionId: string;
|
|
243
|
+
widget: DashboardWidget;
|
|
244
|
+
}
|
|
245
|
+
interface DashboardLayoutState {
|
|
246
|
+
editMode: boolean;
|
|
247
|
+
setEditMode: (value: boolean) => void;
|
|
248
|
+
getSectionWidgets: (section: DashboardSection, sectionId: string) => DashboardWidget[];
|
|
249
|
+
hiddenWidgets: HiddenWidgetEntry[];
|
|
250
|
+
hideWidget: (sectionId: string, widgetId: string) => void;
|
|
251
|
+
showWidget: (sectionId: string, widgetId: string) => void;
|
|
252
|
+
moveWidget: (sectionId: string, widgetId: string, direction: -1 | 1) => void;
|
|
253
|
+
resetLayout: () => void;
|
|
254
|
+
}
|
|
255
|
+
declare function useDashboardLayout(dashboardId: string | undefined, sections: DashboardSection[], enabled: boolean): DashboardLayoutState | undefined;
|
|
256
|
+
//#endregion
|
|
257
|
+
//#region packages/dashboard/dashboard/DashboardLayoutControls.d.ts
|
|
258
|
+
declare function DashboardLayoutControls({
|
|
259
|
+
layout
|
|
260
|
+
}: {
|
|
261
|
+
layout: DashboardLayoutState;
|
|
262
|
+
}): import("react").JSX.Element;
|
|
263
|
+
//#endregion
|
|
264
|
+
//#region packages/dashboard/dashboard/DashboardWidgetSlot.d.ts
|
|
265
|
+
type Props = {
|
|
266
|
+
widget: DashboardWidget;
|
|
267
|
+
data: Record<string, unknown>;
|
|
268
|
+
loading?: boolean;
|
|
269
|
+
editMode: boolean;
|
|
270
|
+
onHide: () => void;
|
|
271
|
+
onMoveUp: () => void;
|
|
272
|
+
onMoveDown: () => void;
|
|
273
|
+
period?: DashboardPeriodValue;
|
|
274
|
+
periodParamNames?: {
|
|
275
|
+
start: string;
|
|
276
|
+
end: string;
|
|
277
|
+
};
|
|
278
|
+
};
|
|
279
|
+
declare function DashboardWidgetSlot({
|
|
280
|
+
widget,
|
|
281
|
+
data,
|
|
282
|
+
loading,
|
|
283
|
+
editMode,
|
|
284
|
+
onHide,
|
|
285
|
+
onMoveUp,
|
|
286
|
+
onMoveDown,
|
|
287
|
+
period,
|
|
288
|
+
periodParamNames
|
|
289
|
+
}: Props): import("react").JSX.Element;
|
|
290
|
+
//#endregion
|
|
131
291
|
//#region packages/dashboard/dashboard/useDashboardData.d.ts
|
|
132
|
-
declare function useDashboardData(dataUrl?: string, refreshInterval?: number
|
|
292
|
+
declare function useDashboardData(dataUrl?: string, refreshInterval?: number, period?: DashboardPeriodValue, periodParamNames?: {
|
|
293
|
+
start: string;
|
|
294
|
+
end: string;
|
|
295
|
+
}): DashboardDataResult;
|
|
296
|
+
//#endregion
|
|
297
|
+
//#region packages/dashboard/dashboard/useWidgetQuery.d.ts
|
|
298
|
+
interface WidgetQueryResult {
|
|
299
|
+
data: Record<string, unknown>;
|
|
300
|
+
loading: boolean;
|
|
301
|
+
error: string | null;
|
|
302
|
+
}
|
|
303
|
+
/**
|
|
304
|
+
* Fetches a single widget's data independently of the dashboard's shared
|
|
305
|
+
* payload — its own cache entry, its own loading/error state, no head-of-line
|
|
306
|
+
* blocking behind slower widgets. Returns `undefined` when the widget has no
|
|
307
|
+
* `query` configured, so callers fall back to the dashboard's shared data.
|
|
308
|
+
*/
|
|
309
|
+
declare function useWidgetQuery(query: WidgetQueryConfig | undefined, period: DashboardPeriodValue | undefined, periodParamNames?: {
|
|
310
|
+
start: string;
|
|
311
|
+
end: string;
|
|
312
|
+
}): WidgetQueryResult | undefined;
|
|
313
|
+
//#endregion
|
|
314
|
+
//#region packages/dashboard/dashboard/periodPresets.d.ts
|
|
315
|
+
declare const DEFAULT_PERIOD_PRESETS: DashboardPeriodPreset[];
|
|
316
|
+
declare function getPeriodPreset(key: string, presets?: DashboardPeriodPreset[]): DashboardPeriodPreset | undefined;
|
|
317
|
+
//#endregion
|
|
318
|
+
//#region packages/dashboard/dashboard/defaults.d.ts
|
|
319
|
+
declare const DEFAULT_PERIOD_PARAM_NAMES: {
|
|
320
|
+
readonly start: "from";
|
|
321
|
+
readonly end: "to";
|
|
322
|
+
};
|
|
323
|
+
//#endregion
|
|
324
|
+
//#region packages/dashboard/dashboard/widgetRegistry.d.ts
|
|
325
|
+
interface WidgetViewProps<W extends DashboardWidget = DashboardWidget> {
|
|
326
|
+
widget: W;
|
|
327
|
+
data: Record<string, unknown>;
|
|
328
|
+
loading?: boolean;
|
|
329
|
+
}
|
|
330
|
+
type WidgetComponent = ComponentType<WidgetViewProps<any>>;
|
|
331
|
+
/**
|
|
332
|
+
* Registers a component to render for `widget.type`. Built-in types (`stat`,
|
|
333
|
+
* `bar-chart`, `donut-chart`, `line-chart`, `area-chart`, `progress`, `table`)
|
|
334
|
+
* are registered automatically. Call this to add a new widget type — or to
|
|
335
|
+
* replace a built-in one — without forking `@nubitio/dashboard`.
|
|
336
|
+
*
|
|
337
|
+
* ```ts
|
|
338
|
+
* registerWidgetType('funnel', FunnelWidgetView);
|
|
339
|
+
* ```
|
|
340
|
+
*/
|
|
341
|
+
declare function registerWidgetType(type: string, component: WidgetComponent): void;
|
|
342
|
+
declare function getWidgetComponent(type: string): WidgetComponent | undefined;
|
|
343
|
+
declare function isWidgetTypeRegistered(type: string): boolean;
|
|
133
344
|
//#endregion
|
|
134
345
|
//#region packages/dashboard/dashboard/widgetBuilders.d.ts
|
|
135
346
|
declare function statWidget(config: Omit<StatWidgetConfig, 'type'>): StatWidgetConfig;
|
|
136
347
|
declare function barChartWidget(config: Omit<BarChartWidgetConfig, 'type'>): BarChartWidgetConfig;
|
|
137
348
|
declare function donutChartWidget(config: Omit<DonutChartWidgetConfig, 'type'>): DonutChartWidgetConfig;
|
|
138
349
|
declare function tableWidget(config: Omit<TableWidgetConfig, 'type'>): TableWidgetConfig;
|
|
350
|
+
declare function lineChartWidget(config: Omit<LineChartWidgetConfig, 'type'>): LineChartWidgetConfig;
|
|
351
|
+
declare function areaChartWidget(config: Omit<AreaChartWidgetConfig, 'type'>): AreaChartWidgetConfig;
|
|
352
|
+
declare function progressWidget(config: Omit<ProgressWidgetConfig, 'type'>): ProgressWidgetConfig;
|
|
139
353
|
//#endregion
|
|
140
354
|
//#region packages/dashboard/dashboard/resolvePath.d.ts
|
|
141
355
|
declare function resolvePath(source: unknown, path?: string): unknown;
|
|
@@ -144,4 +358,7 @@ declare function resolveArray(source: unknown, path: string): Record<string, unk
|
|
|
144
358
|
//#region packages/dashboard/dashboard/formatValue.d.ts
|
|
145
359
|
declare function formatDashboardValue(value: unknown, format?: ValueFormat): string;
|
|
146
360
|
//#endregion
|
|
147
|
-
|
|
361
|
+
//#region packages/dashboard/dashboard/chartPalette.d.ts
|
|
362
|
+
declare const DEFAULT_CHART_COLORS: string[];
|
|
363
|
+
//#endregion
|
|
364
|
+
export { type AreaChartWidgetConfig, type BarChartWidgetConfig, type BaseWidgetConfig, CUSTOM_PERIOD_KEY, type ChartSeriesConfig, type CustomWidgetConfig, DEFAULT_CHART_COLORS, DEFAULT_PERIOD_PARAM_NAMES, DEFAULT_PERIOD_PRESETS, type DashboardConfig, type DashboardDataResult, DashboardLayoutControls, type DashboardLayoutState, DashboardPage, type DashboardPageProps, type DashboardPeriodConfig, DashboardPeriodFilter, type DashboardPeriodPreset, type DashboardPeriodState, type DashboardPeriodValue, type DashboardSection, type DashboardSectionLayout, type DashboardWidget, DashboardWidgetSlot, type DonutChartWidgetConfig, type HiddenWidgetEntry, type LineChartWidgetConfig, type ProgressWidgetConfig, type StatIconTone, type StatWidgetConfig, type TableColumnConfig, type TableViewAllConfig, type TableWidgetConfig, type TrendConfig, type ValueFormat, type WidgetComponent, type WidgetQueryConfig, type WidgetQueryResult, type WidgetViewProps, areaChartWidget, barChartWidget, defineDashboard, donutChartWidget, formatDashboardValue, getPeriodPreset, getWidgetComponent, isWidgetTypeRegistered, lineChartWidget, progressWidget, registerWidgetType, resolveArray, resolvePath, statWidget, tableWidget, useDashboardData, useDashboardLayout, useDashboardPeriod, useWidgetQuery };
|