@richardmcquiston01/dashboard-widgets-toolkit 0.7.0 → 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/core.cjs +100 -19
- package/dist/core.cjs.map +1 -1
- package/dist/core.d.cts +2 -2
- package/dist/core.d.ts +2 -2
- package/dist/core.js +99 -20
- package/dist/core.js.map +1 -1
- package/dist/index.cjs +100 -19
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +1 -1
- package/dist/index.d.ts +1 -1
- package/dist/index.js +99 -20
- package/dist/index.js.map +1 -1
- package/dist/react.cjs +155 -66
- package/dist/react.cjs.map +1 -1
- package/dist/react.d.cts +8 -1
- package/dist/react.d.ts +8 -1
- package/dist/react.js +155 -66
- package/dist/react.js.map +1 -1
- package/dist/{scale-W60sXwlI.d.cts → scale-CrXxawQn.d.cts} +57 -5
- package/dist/{scale-W60sXwlI.d.ts → scale-CrXxawQn.d.ts} +57 -5
- package/package.json +1 -1
|
@@ -567,7 +567,30 @@ interface WidgetDefinition {
|
|
|
567
567
|
readonly tableControls?: boolean | WidgetTableControls;
|
|
568
568
|
/** Fill free space in the row (height, width or both). Default: none. */
|
|
569
569
|
readonly fill?: WidgetFill;
|
|
570
|
+
/**
|
|
571
|
+
* Keeps viewers from rearranging this widget. `true` locks everything:
|
|
572
|
+
* move, hide and minimize. Use an object to lock only some; fields left out
|
|
573
|
+
* are not locked.
|
|
574
|
+
*/
|
|
575
|
+
readonly locked?: boolean | WidgetLock;
|
|
570
576
|
}
|
|
577
|
+
/** What a viewer may not do to a locked widget. */
|
|
578
|
+
interface WidgetLock {
|
|
579
|
+
/** Can't be reordered, and holds its place (a pinned slot). */
|
|
580
|
+
readonly move?: boolean;
|
|
581
|
+
/** Can't be hidden. */
|
|
582
|
+
readonly hide?: boolean;
|
|
583
|
+
/** Can't be collapsed to its header. */
|
|
584
|
+
readonly minimize?: boolean;
|
|
585
|
+
}
|
|
586
|
+
/** `WidgetLock` with every default filled in. */
|
|
587
|
+
type ResolvedWidgetLock = Required<WidgetLock>;
|
|
588
|
+
/**
|
|
589
|
+
* Reads a widget's `locked` setting with defaults: `true` locks move, hide
|
|
590
|
+
* and minimize, an object locks the fields it sets to `true`, and anything
|
|
591
|
+
* else (absent, `false`) locks nothing.
|
|
592
|
+
*/
|
|
593
|
+
declare function resolveWidgetLock(definition: Pick<WidgetDefinition, 'locked'>): ResolvedWidgetLock;
|
|
571
594
|
/**
|
|
572
595
|
* Identity helper that keeps the literal `kind` (so typed providers can be
|
|
573
596
|
* checked against it) and gives a definition its type without a cast.
|
|
@@ -586,10 +609,13 @@ declare function isWidgetVisibleTo(definition: WidgetDefinition, roles: readonly
|
|
|
586
609
|
*
|
|
587
610
|
* Generalised from Maker Toolkit's desktop `dashboard-layout.ts`.
|
|
588
611
|
*/
|
|
612
|
+
|
|
589
613
|
/** What layout functions need from a widget definition. */
|
|
590
614
|
interface LayoutItem {
|
|
591
615
|
readonly key: string;
|
|
592
616
|
readonly sortOrder?: number;
|
|
617
|
+
/** See `WidgetDefinition.locked`. Pinned widgets hold their slot. */
|
|
618
|
+
readonly locked?: boolean | WidgetLock;
|
|
593
619
|
}
|
|
594
620
|
interface DashboardLayout {
|
|
595
621
|
/** Widget keys in display order. Keys not listed follow, by sortOrder. */
|
|
@@ -611,18 +637,27 @@ declare function serializeLayout(layout: DashboardLayout): string;
|
|
|
611
637
|
/**
|
|
612
638
|
* The widgets to show, in order: saved keys first (when still present),
|
|
613
639
|
* then widgets the layout doesn't know yet, by sortOrder. Hidden widgets
|
|
614
|
-
* are left out.
|
|
640
|
+
* are left out. Widgets locked against moving are pinned: each keeps its
|
|
641
|
+
* place from the definitions (never from `layout.order`) and the others
|
|
642
|
+
* rearrange around it.
|
|
615
643
|
*/
|
|
616
644
|
declare function visibleWidgets<T extends LayoutItem>(definitions: readonly T[], layout: DashboardLayout): T[];
|
|
617
645
|
/** Hidden widgets, by sortOrder, for a "restore" menu. */
|
|
618
646
|
declare function hiddenWidgets<T extends LayoutItem>(definitions: readonly T[], layout: DashboardLayout): T[];
|
|
619
647
|
/**
|
|
620
648
|
* Moves `key` to `toIndex` within the current visible order. Returns the
|
|
621
|
-
* same layout object when the key isn't visible
|
|
622
|
-
*
|
|
649
|
+
* same layout object when the key isn't visible, the index is out of range,
|
|
650
|
+
* or the move isn't allowed: a pinned widget can't move, and nothing can be
|
|
651
|
+
* moved onto a pinned slot. Free widgets keep their relative order around
|
|
652
|
+
* pinned ones, so a move that crosses a pinned slot lands on the nearest
|
|
653
|
+
* free slot you named.
|
|
623
654
|
*/
|
|
624
655
|
declare function moveWidget<T extends LayoutItem>(definitions: readonly T[], layout: DashboardLayout, key: string, toIndex: number): DashboardLayout;
|
|
625
|
-
/**
|
|
656
|
+
/**
|
|
657
|
+
* Moves `key` by `offset` places (negative is earlier). Pinned slots are
|
|
658
|
+
* stepped over, not counted, and the move is clamped at the first and last
|
|
659
|
+
* free slot.
|
|
660
|
+
*/
|
|
626
661
|
declare function moveWidgetBy<T extends LayoutItem>(definitions: readonly T[], layout: DashboardLayout, key: string, offset: number): DashboardLayout;
|
|
627
662
|
/** Moves `key` one place earlier. */
|
|
628
663
|
declare function moveWidgetUp<T extends LayoutItem>(definitions: readonly T[], layout: DashboardLayout, key: string): DashboardLayout;
|
|
@@ -648,6 +683,23 @@ declare function toggleMinimized(layout: DashboardLayout, key: string): Dashboar
|
|
|
648
683
|
* they temporarily can't see are lost.
|
|
649
684
|
*/
|
|
650
685
|
declare function pruneLayout<T extends LayoutItem>(definitions: readonly T[], layout: DashboardLayout): DashboardLayout;
|
|
686
|
+
/** Options for `enforceLocks`. */
|
|
687
|
+
interface EnforceLocksOptions {
|
|
688
|
+
/**
|
|
689
|
+
* Skip enforcement. Set it server-side only for a user who may rearrange
|
|
690
|
+
* locked widgets (an administrator editing the default layout), never from
|
|
691
|
+
* a flag the client sends.
|
|
692
|
+
*/
|
|
693
|
+
readonly overrideLocks?: boolean;
|
|
694
|
+
}
|
|
695
|
+
/**
|
|
696
|
+
* Removes whatever a widget's lock forbids from a layout: a hide-locked key
|
|
697
|
+
* leaves `hidden`, a minimize-locked key leaves `minimized`, and a
|
|
698
|
+
* move-locked key leaves `order` (a pinned widget's place comes from the
|
|
699
|
+
* definitions). Idempotent; returns the same object when nothing changes.
|
|
700
|
+
* Run it on a layout a client sends before saving it.
|
|
701
|
+
*/
|
|
702
|
+
declare function enforceLocks<T extends LayoutItem>(definitions: readonly T[], layout: DashboardLayout, options?: EnforceLocksOptions): DashboardLayout;
|
|
651
703
|
|
|
652
704
|
/** Axis maths for charts: clean domains and tick values. Pure. */
|
|
653
705
|
/** The smallest 1, 2 or 5 × 10^n that is at least `value` (1 for 0 or less). */
|
|
@@ -668,4 +720,4 @@ declare function niceDomain(values: readonly number[], tickCount?: number): Nice
|
|
|
668
720
|
*/
|
|
669
721
|
declare function labelStride(count: number, maxLabels?: number): number;
|
|
670
722
|
|
|
671
|
-
export {
|
|
723
|
+
export { type LoadingWidget as $, type AlertListWidgetData as A, type BarListWidgetData as B, type CachedPayload as C, type DashboardWidget as D, type DetailMode as E, type DetailPage as F, type GraphWidgetData as G, type DetailProvider as H, type DetailProviders as I, type DetailSort as J, type KpiWidgetData as K, type Locale as L, EMPTY_LAYOUT as M, type NiceDomain as N, type EmptyWidget as O, type EnforceLocksOptions as P, type Err as Q, type ResolvedTableControls as R, type ErrorWidget as S, type TableWidgetData as T, type FormatOptions as U, type GraphPoint as V, type WidgetSize as W, type GraphSeries as X, type KpiDelta as Y, type KpiDeltaOptions as Z, type LayoutItem as _, type WidgetFill as a, resolveWidget as a$, MAX_DETAIL_PAGE_SIZE as a0, MAX_GRAPH_SERIES as a1, type Ok as a2, type OkWidget as a3, type ProviderOptions as a4, type ResolvedDetailOptions as a5, type ResolvedWidget as a6, type ResolvedWidgetLock as a7, type SortDirection as a8, type TableCell as a9, formatValue as aA, hiddenWidgets as aB, hideWidget as aC, isHidden as aD, isMinimized as aE, isWidgetEmptyState as aF, isWidgetKind as aG, isWidgetVisibleTo as aH, kpiDelta as aI, labelStride as aJ, loadingWidgets as aK, minimizeWidget as aL, moveWidget as aM, moveWidgetBy as aN, moveWidgetDown as aO, moveWidgetUp as aP, niceDomain as aQ, niceStep as aR, ok as aS, parseDetailQuery as aT, parseLayout as aU, percentChange as aV, pruneLayout as aW, queryRows as aX, resolveDetailOptions as aY, resolvePayload as aZ, resolveTableControls as a_, type TableColumn as aa, VALUE_FORMATS as ab, type ValueFormat as ac, WIDGET_FILLS as ad, WIDGET_KINDS as ae, WIDGET_SIZES as af, type WidgetCache as ag, type WidgetDataOf as ah, type WidgetDetailOptions as ai, type WidgetEmptyState as aj, type WidgetLock as ak, type WidgetProvider as al, type WidgetStatus as am, type WidgetTableControls as an, cacheKeyFor as ao, defaultDetailQuery as ap, defineWidget as aq, deriveDetailData as ar, describeUnknownError as as, emptyTextFor as at, emptyWidget as au, enforceLocks as av, err as aw, failedWidget as ax, formatCount as ay, formatPercentChange as az, type WidgetDefinition as b, resolveWidgetLock as b0, resolveWidgets as b1, restoreWidget as b2, serializeDetailQuery as b3, serializeLayout as b4, shareOf as b5, showWidget as b6, sortDefinitions as b7, tableDetailData as b8, toggleHidden as b9, toggleMinimized as ba, validateDetailData as bb, visibleWidgets as bc, widgetsFor as bd, type DetailProviderOptions as c, type DetailData as d, type DetailQuery as e, type DashboardLayout as f, type GaugeWidgetData as g, type TextWidgetData as h, type WidgetData as i, type ResolveOptions as j, type WidgetContext as k, type WidgetProviders as l, type WidgetKind as m, type Result as n, type WidgetPayload as o, type AlertListItem as p, type BarListItem as q, DEFAULT_COMPARISON_LABEL as r, DEFAULT_CURRENCY as s, DEFAULT_DETAIL_PAGE_SIZE as t, DEFAULT_EMPTY_TEXT as u, DETAIL_MODES as v, type DeltaDirection as w, type DeltaSentiment as x, type DetailCell as y, type DetailColumn as z };
|
|
@@ -567,7 +567,30 @@ interface WidgetDefinition {
|
|
|
567
567
|
readonly tableControls?: boolean | WidgetTableControls;
|
|
568
568
|
/** Fill free space in the row (height, width or both). Default: none. */
|
|
569
569
|
readonly fill?: WidgetFill;
|
|
570
|
+
/**
|
|
571
|
+
* Keeps viewers from rearranging this widget. `true` locks everything:
|
|
572
|
+
* move, hide and minimize. Use an object to lock only some; fields left out
|
|
573
|
+
* are not locked.
|
|
574
|
+
*/
|
|
575
|
+
readonly locked?: boolean | WidgetLock;
|
|
570
576
|
}
|
|
577
|
+
/** What a viewer may not do to a locked widget. */
|
|
578
|
+
interface WidgetLock {
|
|
579
|
+
/** Can't be reordered, and holds its place (a pinned slot). */
|
|
580
|
+
readonly move?: boolean;
|
|
581
|
+
/** Can't be hidden. */
|
|
582
|
+
readonly hide?: boolean;
|
|
583
|
+
/** Can't be collapsed to its header. */
|
|
584
|
+
readonly minimize?: boolean;
|
|
585
|
+
}
|
|
586
|
+
/** `WidgetLock` with every default filled in. */
|
|
587
|
+
type ResolvedWidgetLock = Required<WidgetLock>;
|
|
588
|
+
/**
|
|
589
|
+
* Reads a widget's `locked` setting with defaults: `true` locks move, hide
|
|
590
|
+
* and minimize, an object locks the fields it sets to `true`, and anything
|
|
591
|
+
* else (absent, `false`) locks nothing.
|
|
592
|
+
*/
|
|
593
|
+
declare function resolveWidgetLock(definition: Pick<WidgetDefinition, 'locked'>): ResolvedWidgetLock;
|
|
571
594
|
/**
|
|
572
595
|
* Identity helper that keeps the literal `kind` (so typed providers can be
|
|
573
596
|
* checked against it) and gives a definition its type without a cast.
|
|
@@ -586,10 +609,13 @@ declare function isWidgetVisibleTo(definition: WidgetDefinition, roles: readonly
|
|
|
586
609
|
*
|
|
587
610
|
* Generalised from Maker Toolkit's desktop `dashboard-layout.ts`.
|
|
588
611
|
*/
|
|
612
|
+
|
|
589
613
|
/** What layout functions need from a widget definition. */
|
|
590
614
|
interface LayoutItem {
|
|
591
615
|
readonly key: string;
|
|
592
616
|
readonly sortOrder?: number;
|
|
617
|
+
/** See `WidgetDefinition.locked`. Pinned widgets hold their slot. */
|
|
618
|
+
readonly locked?: boolean | WidgetLock;
|
|
593
619
|
}
|
|
594
620
|
interface DashboardLayout {
|
|
595
621
|
/** Widget keys in display order. Keys not listed follow, by sortOrder. */
|
|
@@ -611,18 +637,27 @@ declare function serializeLayout(layout: DashboardLayout): string;
|
|
|
611
637
|
/**
|
|
612
638
|
* The widgets to show, in order: saved keys first (when still present),
|
|
613
639
|
* then widgets the layout doesn't know yet, by sortOrder. Hidden widgets
|
|
614
|
-
* are left out.
|
|
640
|
+
* are left out. Widgets locked against moving are pinned: each keeps its
|
|
641
|
+
* place from the definitions (never from `layout.order`) and the others
|
|
642
|
+
* rearrange around it.
|
|
615
643
|
*/
|
|
616
644
|
declare function visibleWidgets<T extends LayoutItem>(definitions: readonly T[], layout: DashboardLayout): T[];
|
|
617
645
|
/** Hidden widgets, by sortOrder, for a "restore" menu. */
|
|
618
646
|
declare function hiddenWidgets<T extends LayoutItem>(definitions: readonly T[], layout: DashboardLayout): T[];
|
|
619
647
|
/**
|
|
620
648
|
* Moves `key` to `toIndex` within the current visible order. Returns the
|
|
621
|
-
* same layout object when the key isn't visible
|
|
622
|
-
*
|
|
649
|
+
* same layout object when the key isn't visible, the index is out of range,
|
|
650
|
+
* or the move isn't allowed: a pinned widget can't move, and nothing can be
|
|
651
|
+
* moved onto a pinned slot. Free widgets keep their relative order around
|
|
652
|
+
* pinned ones, so a move that crosses a pinned slot lands on the nearest
|
|
653
|
+
* free slot you named.
|
|
623
654
|
*/
|
|
624
655
|
declare function moveWidget<T extends LayoutItem>(definitions: readonly T[], layout: DashboardLayout, key: string, toIndex: number): DashboardLayout;
|
|
625
|
-
/**
|
|
656
|
+
/**
|
|
657
|
+
* Moves `key` by `offset` places (negative is earlier). Pinned slots are
|
|
658
|
+
* stepped over, not counted, and the move is clamped at the first and last
|
|
659
|
+
* free slot.
|
|
660
|
+
*/
|
|
626
661
|
declare function moveWidgetBy<T extends LayoutItem>(definitions: readonly T[], layout: DashboardLayout, key: string, offset: number): DashboardLayout;
|
|
627
662
|
/** Moves `key` one place earlier. */
|
|
628
663
|
declare function moveWidgetUp<T extends LayoutItem>(definitions: readonly T[], layout: DashboardLayout, key: string): DashboardLayout;
|
|
@@ -648,6 +683,23 @@ declare function toggleMinimized(layout: DashboardLayout, key: string): Dashboar
|
|
|
648
683
|
* they temporarily can't see are lost.
|
|
649
684
|
*/
|
|
650
685
|
declare function pruneLayout<T extends LayoutItem>(definitions: readonly T[], layout: DashboardLayout): DashboardLayout;
|
|
686
|
+
/** Options for `enforceLocks`. */
|
|
687
|
+
interface EnforceLocksOptions {
|
|
688
|
+
/**
|
|
689
|
+
* Skip enforcement. Set it server-side only for a user who may rearrange
|
|
690
|
+
* locked widgets (an administrator editing the default layout), never from
|
|
691
|
+
* a flag the client sends.
|
|
692
|
+
*/
|
|
693
|
+
readonly overrideLocks?: boolean;
|
|
694
|
+
}
|
|
695
|
+
/**
|
|
696
|
+
* Removes whatever a widget's lock forbids from a layout: a hide-locked key
|
|
697
|
+
* leaves `hidden`, a minimize-locked key leaves `minimized`, and a
|
|
698
|
+
* move-locked key leaves `order` (a pinned widget's place comes from the
|
|
699
|
+
* definitions). Idempotent; returns the same object when nothing changes.
|
|
700
|
+
* Run it on a layout a client sends before saving it.
|
|
701
|
+
*/
|
|
702
|
+
declare function enforceLocks<T extends LayoutItem>(definitions: readonly T[], layout: DashboardLayout, options?: EnforceLocksOptions): DashboardLayout;
|
|
651
703
|
|
|
652
704
|
/** Axis maths for charts: clean domains and tick values. Pure. */
|
|
653
705
|
/** The smallest 1, 2 or 5 × 10^n that is at least `value` (1 for 0 or less). */
|
|
@@ -668,4 +720,4 @@ declare function niceDomain(values: readonly number[], tickCount?: number): Nice
|
|
|
668
720
|
*/
|
|
669
721
|
declare function labelStride(count: number, maxLabels?: number): number;
|
|
670
722
|
|
|
671
|
-
export {
|
|
723
|
+
export { type LoadingWidget as $, type AlertListWidgetData as A, type BarListWidgetData as B, type CachedPayload as C, type DashboardWidget as D, type DetailMode as E, type DetailPage as F, type GraphWidgetData as G, type DetailProvider as H, type DetailProviders as I, type DetailSort as J, type KpiWidgetData as K, type Locale as L, EMPTY_LAYOUT as M, type NiceDomain as N, type EmptyWidget as O, type EnforceLocksOptions as P, type Err as Q, type ResolvedTableControls as R, type ErrorWidget as S, type TableWidgetData as T, type FormatOptions as U, type GraphPoint as V, type WidgetSize as W, type GraphSeries as X, type KpiDelta as Y, type KpiDeltaOptions as Z, type LayoutItem as _, type WidgetFill as a, resolveWidget as a$, MAX_DETAIL_PAGE_SIZE as a0, MAX_GRAPH_SERIES as a1, type Ok as a2, type OkWidget as a3, type ProviderOptions as a4, type ResolvedDetailOptions as a5, type ResolvedWidget as a6, type ResolvedWidgetLock as a7, type SortDirection as a8, type TableCell as a9, formatValue as aA, hiddenWidgets as aB, hideWidget as aC, isHidden as aD, isMinimized as aE, isWidgetEmptyState as aF, isWidgetKind as aG, isWidgetVisibleTo as aH, kpiDelta as aI, labelStride as aJ, loadingWidgets as aK, minimizeWidget as aL, moveWidget as aM, moveWidgetBy as aN, moveWidgetDown as aO, moveWidgetUp as aP, niceDomain as aQ, niceStep as aR, ok as aS, parseDetailQuery as aT, parseLayout as aU, percentChange as aV, pruneLayout as aW, queryRows as aX, resolveDetailOptions as aY, resolvePayload as aZ, resolveTableControls as a_, type TableColumn as aa, VALUE_FORMATS as ab, type ValueFormat as ac, WIDGET_FILLS as ad, WIDGET_KINDS as ae, WIDGET_SIZES as af, type WidgetCache as ag, type WidgetDataOf as ah, type WidgetDetailOptions as ai, type WidgetEmptyState as aj, type WidgetLock as ak, type WidgetProvider as al, type WidgetStatus as am, type WidgetTableControls as an, cacheKeyFor as ao, defaultDetailQuery as ap, defineWidget as aq, deriveDetailData as ar, describeUnknownError as as, emptyTextFor as at, emptyWidget as au, enforceLocks as av, err as aw, failedWidget as ax, formatCount as ay, formatPercentChange as az, type WidgetDefinition as b, resolveWidgetLock as b0, resolveWidgets as b1, restoreWidget as b2, serializeDetailQuery as b3, serializeLayout as b4, shareOf as b5, showWidget as b6, sortDefinitions as b7, tableDetailData as b8, toggleHidden as b9, toggleMinimized as ba, validateDetailData as bb, visibleWidgets as bc, widgetsFor as bd, type DetailProviderOptions as c, type DetailData as d, type DetailQuery as e, type DashboardLayout as f, type GaugeWidgetData as g, type TextWidgetData as h, type WidgetData as i, type ResolveOptions as j, type WidgetContext as k, type WidgetProviders as l, type WidgetKind as m, type Result as n, type WidgetPayload as o, type AlertListItem as p, type BarListItem as q, DEFAULT_COMPARISON_LABEL as r, DEFAULT_CURRENCY as s, DEFAULT_DETAIL_PAGE_SIZE as t, DEFAULT_EMPTY_TEXT as u, DETAIL_MODES as v, type DeltaDirection as w, type DeltaSentiment as x, type DetailCell as y, type DetailColumn as z };
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@richardmcquiston01/dashboard-widgets-toolkit",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.8.0",
|
|
4
4
|
"description": "Framework-agnostic dashboard widget toolkit: typed widget definitions and data payloads (KPI, gauge, table, bar list, alert list, chart), user layout (order, hide, minimise), and React renderers. Bring your own data providers.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"dashboard",
|