@nubitio/dashboard 0.7.3 → 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.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
- interface StatWidgetConfig {
17
- type: 'stat';
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
- type DashboardWidget = StatWidgetConfig | BarChartWidgetConfig | DonutChartWidgetConfig | TableWidgetConfig;
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): DashboardDataResult;
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
- export { type BarChartWidgetConfig, type DashboardConfig, type DashboardDataResult, DashboardPage, type DashboardPageProps, type DashboardSection, type DashboardSectionLayout, type DashboardWidget, type DonutChartWidgetConfig, type StatIconTone, type StatWidgetConfig, type TableColumnConfig, type TableViewAllConfig, type TableWidgetConfig, type TrendConfig, type ValueFormat, barChartWidget, defineDashboard, donutChartWidget, formatDashboardValue, resolveArray, resolvePath, statWidget, tableWidget, useDashboardData };
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
- interface StatWidgetConfig {
17
- type: 'stat';
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
- type DashboardWidget = StatWidgetConfig | BarChartWidgetConfig | DonutChartWidgetConfig | TableWidgetConfig;
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): DashboardDataResult;
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
- export { type BarChartWidgetConfig, type DashboardConfig, type DashboardDataResult, DashboardPage, type DashboardPageProps, type DashboardSection, type DashboardSectionLayout, type DashboardWidget, type DonutChartWidgetConfig, type StatIconTone, type StatWidgetConfig, type TableColumnConfig, type TableViewAllConfig, type TableWidgetConfig, type TrendConfig, type ValueFormat, barChartWidget, defineDashboard, donutChartWidget, formatDashboardValue, resolveArray, resolvePath, statWidget, tableWidget, useDashboardData };
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 };