@richardmcquiston01/dashboard-widgets-toolkit 0.1.0

package/dist/react.d.ts

@@ -0,0 +1,203 @@
+import { ReactNode } from 'react';
+import { D as DashboardWidget, W as WidgetSize, G as GraphWidgetData, N as NiceDomain, L as Locale, a as DashboardLayout, A as AlertListWidgetData, B as BarListWidgetData, b as GaugeWidgetData, K as KpiWidgetData, T as TableWidgetData, c as TextWidgetData, d as WidgetData } from './scale-WlRozDCf.js';
+
+interface WidgetCardProps {
+    readonly title: string;
+    readonly description?: string;
+    /** Extra controls in the header (move, hide...), before the minimise toggle. */
+    readonly actions?: ReactNode;
+    readonly minimized?: boolean;
+    /** Shows the minimise/expand toggle when given. */
+    readonly onToggleMinimized?: () => void;
+    /** Default 'ok', which renders `children`. */
+    readonly status?: 'ok' | 'loading' | 'empty' | 'error';
+    readonly emptyText?: string;
+    readonly error?: string;
+    /** Shows a Retry button on the error state when given. */
+    readonly onRetry?: () => void;
+    readonly footer?: ReactNode;
+    readonly size?: WidgetSize;
+    /** 2 to 6; default 2. */
+    readonly headingLevel?: 2 | 3 | 4 | 5 | 6;
+    readonly className?: string;
+    readonly children?: ReactNode;
+}
+/**
+ * The frame every widget sits in: title, optional description and actions,
+ * a minimise toggle, and loading, empty and error states.
+ */
+declare function WidgetCard({ title, description, actions, minimized, onToggleMinimized, status, emptyText, error, onRetry, footer, size, headingLevel, className, children, }: WidgetCardProps): ReactNode;
+/** The title to show: alert lists add their total, e.g. "Low stock (3)". */
+declare function widgetTitle(widget: DashboardWidget): string;
+interface ResolvedWidgetCardProps {
+    readonly widget: DashboardWidget;
+    readonly actions?: ReactNode;
+    readonly minimized?: boolean;
+    readonly onToggleMinimized?: () => void;
+    readonly onRetry?: () => void;
+    readonly headingLevel?: 2 | 3 | 4 | 5 | 6;
+    readonly className?: string;
+}
+/** A WidgetCard for a resolved (or loading) widget, with its renderer. */
+declare function ResolvedWidgetCard({ widget, ...props }: ResolvedWidgetCardProps): ReactNode;
+
+/** A bar with a rounded data end and a square end on the baseline. */
+declare function barPath(x: number, y: number, width: number, height: number, roundedEnd: 'top' | 'bottom'): string;
+interface ChartModel {
+    readonly labels: readonly string[];
+    /** values[series][index]; null where a series has no point. */
+    readonly values: readonly (readonly (number | null)[])[];
+    readonly domain: NiceDomain;
+}
+/** Labels by position (first series that has one) and a value matrix. */
+declare function buildChartModel(data: GraphWidgetData): ChartModel;
+/** A plain-language summary of the chart, for its SVG <desc>. */
+declare function describeChart(data: GraphWidgetData, model: ChartModel, format: (value: number) => string): string;
+declare function GraphWidget({ data, title, }: {
+    readonly data: GraphWidgetData;
+    /** The accessible name; defaults to the series names. */
+    readonly title?: string;
+}): ReactNode;
+
+/** Every element that carries a stable `dwt-*` class, for `classNames`. */
+type DashboardClassSlot = 'dashboard' | 'hiddenBar' | 'grid' | 'card' | 'cardHeader' | 'cardTitle' | 'cardDescription' | 'cardActions' | 'cardBody' | 'cardFooter' | 'button' | 'status' | 'empty' | 'error' | 'text' | 'kpi' | 'gauge' | 'table' | 'barList' | 'alertList' | 'chart' | 'legend' | 'tooltip' | 'tableTwin';
+/**
+ * Extra classes per slot, appended to the `dwt-*` class (never replacing
+ * it), e.g. `{ card: 'rounded-lg shadow-sm' }` for Tailwind.
+ */
+type DashboardClassNames = Partial<Record<DashboardClassSlot, string>>;
+/** Interface text, overridable for other languages or house style. */
+interface DashboardLabels {
+    readonly loading: string;
+    readonly retry: string;
+    readonly viewAsTable: string;
+    readonly hide: (title: string) => string;
+    readonly show: (title: string) => string;
+    readonly minimize: (title: string) => string;
+    readonly expand: (title: string) => string;
+    readonly moveEarlier: (title: string) => string;
+    readonly moveLater: (title: string) => string;
+    readonly hiddenWidgets: string;
+    readonly allHidden: string;
+    readonly noWidgets: string;
+    readonly andMore: (count: number) => string;
+    /** The comparison in KPI deltas, e.g. "previous period". */
+    readonly comparison: string;
+}
+declare const DEFAULT_LABELS: DashboardLabels;
+interface WidgetSettings {
+    /** BCP 47 locale for numbers; undefined uses the runtime default. */
+    readonly locale?: Locale;
+    /** e.g. "_blank". Links always get rel="noreferrer". */
+    readonly linkTarget?: string;
+    readonly classNames?: DashboardClassNames;
+    readonly labels?: Partial<DashboardLabels>;
+}
+interface ResolvedSettings {
+    readonly locale: Locale;
+    readonly linkTarget: string | undefined;
+    readonly classNames: DashboardClassNames;
+    readonly labels: DashboardLabels;
+}
+/** Sets locale, link target, extra classes and labels for widgets inside it. */
+declare function WidgetSettingsProvider({ children, ...settings }: WidgetSettings & {
+    readonly children?: ReactNode;
+}): ReactNode;
+declare function useWidgetSettings(): ResolvedSettings;
+/** Joins class names, skipping empty ones. */
+declare function joinClassNames(...names: readonly (string | false | null | undefined)[]): string;
+
+interface WidgetGridProps {
+    /** Rendered in the order given. */
+    readonly widgets: readonly DashboardWidget[];
+    readonly onRetry?: (key: string) => void;
+    readonly headingLevel?: 2 | 3 | 4 | 5 | 6;
+    readonly className?: string;
+}
+/** A plain grid of widget cards, no layout controls. */
+declare function WidgetGrid({ widgets, onRetry, headingLevel, className, }: WidgetGridProps): ReactNode;
+interface DashboardProps extends WidgetSettings {
+    /** Resolved (or loading) widgets, any order: the layout orders them. */
+    readonly widgets: readonly DashboardWidget[];
+    /** The viewer's saved layout. Default: none saved. */
+    readonly layout?: DashboardLayout;
+    /**
+     * Called with the next layout after a move, hide, show, minimise or
+     * restore; persist it. Without it the layout is read-only (no controls).
+     */
+    readonly onLayoutChange?: (layout: DashboardLayout) => void;
+    readonly onRetry?: (key: string) => void;
+    readonly headingLevel?: 2 | 3 | 4 | 5 | 6;
+    readonly className?: string;
+}
+/**
+ * A full dashboard: widgets ordered by the viewer's layout, with move,
+ * hide/show and minimise controls when `onLayoutChange` is given. Settings
+ * (locale, link target, classNames, labels) apply to every widget inside.
+ */
+declare function Dashboard({ locale, linkTarget, classNames, labels, ...props }: DashboardProps): ReactNode;
+
+/**
+ * Default colours, used as `var(--dwt-*, fallback)` so charts read correctly
+ * without the stylesheet. `styles.css` redefines them for dark mode, and an
+ * app can override any of them with its own CSS custom properties.
+ *
+ * The categorical order is the dataviz reference palette, validated for
+ * colour-vision deficiency on adjacent pairs in light and dark modes. Slots
+ * are assigned in this fixed order, never cycled, and follow the series
+ * (its position in the payload), never its rank.
+ */
+declare const DEFAULT_SERIES_COLORS: readonly string[];
+/** `var(--dwt-series-N, #hex)` for the series at `index` (0-based). */
+declare function seriesColor(index: number): string;
+
+/**
+ * An anchor with rel="noreferrer", or plain text when there is no href or
+ * it isn't a safe scheme (http, https, mailto, relative). Never fetches.
+ */
+declare function WidgetLink({ href, className, children, }: {
+    readonly href: string | undefined;
+    readonly className?: string;
+    readonly children: ReactNode;
+}): ReactNode;
+/** A decorative square thumbnail; nothing for an unsafe or missing URL. */
+declare function Thumbnail({ url, }: {
+    readonly url: string | undefined;
+}): ReactNode;
+
+/** TEXT: a headline value and its label. */
+declare function TextWidget({ data, }: {
+    readonly data: TextWidgetData;
+}): ReactNode;
+/**
+ * KPI: a stat tile. The change against the previous period carries an arrow
+ * and signed text as well as colour, so it never relies on colour alone.
+ */
+declare function KpiWidget({ data, }: {
+    readonly data: KpiWidgetData;
+}): ReactNode;
+/** GAUGE: a meter whose track is a lighter step of the fill's own hue. */
+declare function GaugeWidget({ data, }: {
+    readonly data: GaugeWidgetData;
+}): ReactNode;
+/** TABLE: a data table; cells with a safe `href` become links. */
+declare function TableWidget({ data, }: {
+    readonly data: TableWidgetData;
+}): ReactNode;
+/**
+ * BAR_LIST: labelled horizontal bars. One series, so one colour (slot 1)
+ * for every bar; the value text sits beside the bar, never inside it.
+ */
+declare function BarListWidget({ data, }: {
+    readonly data: BarListWidgetData;
+}): ReactNode;
+/** ALERT_LIST: rows needing attention, with thumbnail, link and value. */
+declare function AlertListWidget({ data, }: {
+    readonly data: AlertListWidgetData;
+}): ReactNode;
+/** Renders any payload with the renderer for its kind. */
+declare function WidgetContent({ data, }: {
+    readonly data: WidgetData;
+}): ReactNode;
+
+export { AlertListWidget, BarListWidget, DEFAULT_LABELS, DEFAULT_SERIES_COLORS, Dashboard, type DashboardClassNames, type DashboardClassSlot, type DashboardLabels, type DashboardProps, GaugeWidget, GraphWidget, KpiWidget, ResolvedWidgetCard, type ResolvedWidgetCardProps, TableWidget, TextWidget, Thumbnail, WidgetCard, type WidgetCardProps, WidgetContent, WidgetGrid, type WidgetGridProps, WidgetLink, type WidgetSettings, WidgetSettingsProvider, barPath, buildChartModel, describeChart, joinClassNames, seriesColor, useWidgetSettings, widgetTitle };