@asteby/metacore-runtime-react 18.16.1 → 18.17.0

package/src/widgets/widget-format.ts

@@ -0,0 +1,181 @@
+// Shared widget formatting + accent theming. Reuses the same Intl-based
+// approach as the table cells (dynamic-columns) so dashboard numbers read
+// identically to the grids: org currency + locale, compact notation, percent.
+
+import type { WidgetAccent, WidgetFormat } from '../dashboard-types'
+
+export interface WidgetFormatCtx {
+    format?: WidgetFormat
+    locale?: string
+    currency?: string
+}
+
+/**
+ * Formats a scalar/series value with the widget's declared format. `currency`
+ * uses the org currency + locale (same fallback chain as table cells); `percent`
+ * treats the value as a fraction (0.142 → "14.2%"); `compact` uses Intl compact
+ * notation (1_200 → "1.2K").
+ */
+export function formatWidgetValue(
+    value: number,
+    { format = 'number', locale, currency }: WidgetFormatCtx,
+): string {
+    if (value === null || value === undefined || Number.isNaN(value)) return '—'
+    const loc = locale || undefined
+    switch (format) {
+        case 'currency':
+            return new Intl.NumberFormat(loc, {
+                style: 'currency',
+                currency: currency || 'USD',
+                maximumFractionDigits: 2,
+            }).format(value)
+        case 'percent':
+            return new Intl.NumberFormat(loc, {
+                style: 'percent',
+                minimumFractionDigits: 0,
+                maximumFractionDigits: 1,
+            }).format(value)
+        case 'compact':
+            return new Intl.NumberFormat(loc, {
+                notation: 'compact',
+                maximumFractionDigits: 1,
+            }).format(value)
+        case 'number':
+        default:
+            return new Intl.NumberFormat(loc, {
+                maximumFractionDigits: 2,
+            }).format(value)
+    }
+}
+
+/** Axis-tick formatter — always compact so charts stay legible. */
+export function formatAxisTick(
+    value: number,
+    { format, locale, currency }: WidgetFormatCtx,
+): string {
+    const loc = locale || undefined
+    if (format === 'currency') {
+        return new Intl.NumberFormat(loc, {
+            style: 'currency',
+            currency: currency || 'USD',
+            notation: 'compact',
+            maximumFractionDigits: 1,
+        }).format(value)
+    }
+    if (format === 'percent') {
+        return new Intl.NumberFormat(loc, {
+            style: 'percent',
+            maximumFractionDigits: 0,
+        }).format(value)
+    }
+    return new Intl.NumberFormat(loc, {
+        notation: 'compact',
+        maximumFractionDigits: 1,
+    }).format(value)
+}
+
+/** Formats the compare delta fraction (0.142 → "+14.2%"). */
+export function formatDelta(delta: number, locale?: string): string {
+    const sign = delta > 0 ? '+' : ''
+    return (
+        sign +
+        new Intl.NumberFormat(locale || undefined, {
+            style: 'percent',
+            minimumFractionDigits: 0,
+            maximumFractionDigits: 1,
+        }).format(delta)
+    )
+}
+
+// --- Accent theming -------------------------------------------------------
+// Tailwind tokens scanned in THIS package's build (the renderers live in the
+// SDK, not the federated host), so static utility classes are safe. We avoid
+// host-dependent arbitrary values. Each accent maps to a small bundle of
+// classes for the icon chip, the chart stroke/fill and the progress/list bar.
+
+export interface AccentClasses {
+    /** Icon chip background + foreground. */
+    chip: string
+    /** Text color for accented labels. */
+    text: string
+    /** Solid bar/fill background (progress, list proportion). */
+    bar: string
+    /** Soft track background behind a bar. */
+    track: string
+    /** Hex-ish CSS color used for recharts stroke/fill (var-based). */
+    chartVar: string
+}
+
+const ACCENTS: Record<WidgetAccent, AccentClasses> = {
+    emerald: {
+        chip: 'bg-emerald-500/10 text-emerald-600 dark:text-emerald-400',
+        text: 'text-emerald-600 dark:text-emerald-400',
+        bar: 'bg-emerald-500',
+        track: 'bg-emerald-500/15',
+        chartVar: 'var(--color-widget-emerald, #10b981)',
+    },
+    sky: {
+        chip: 'bg-sky-500/10 text-sky-600 dark:text-sky-400',
+        text: 'text-sky-600 dark:text-sky-400',
+        bar: 'bg-sky-500',
+        track: 'bg-sky-500/15',
+        chartVar: 'var(--color-widget-sky, #0ea5e9)',
+    },
+    violet: {
+        chip: 'bg-violet-500/10 text-violet-600 dark:text-violet-400',
+        text: 'text-violet-600 dark:text-violet-400',
+        bar: 'bg-violet-500',
+        track: 'bg-violet-500/15',
+        chartVar: 'var(--color-widget-violet, #8b5cf6)',
+    },
+    amber: {
+        chip: 'bg-amber-500/10 text-amber-600 dark:text-amber-400',
+        text: 'text-amber-600 dark:text-amber-400',
+        bar: 'bg-amber-500',
+        track: 'bg-amber-500/15',
+        chartVar: 'var(--color-widget-amber, #f59e0b)',
+    },
+    rose: {
+        chip: 'bg-rose-500/10 text-rose-600 dark:text-rose-400',
+        text: 'text-rose-600 dark:text-rose-400',
+        bar: 'bg-rose-500',
+        track: 'bg-rose-500/15',
+        chartVar: 'var(--color-widget-rose, #f43f5e)',
+    },
+    slate: {
+        chip: 'bg-slate-500/10 text-slate-600 dark:text-slate-300',
+        text: 'text-slate-600 dark:text-slate-300',
+        bar: 'bg-slate-500',
+        track: 'bg-slate-500/15',
+        chartVar: 'var(--color-widget-slate, #64748b)',
+    },
+}
+
+const DEFAULT_ACCENT: WidgetAccent = 'sky'
+
+/** Resolves the accent class bundle, defaulting to `sky`. */
+export function accentClasses(accent?: WidgetAccent): AccentClasses {
+    return ACCENTS[accent ?? DEFAULT_ACCENT] ?? ACCENTS[DEFAULT_ACCENT]
+}
+
+/**
+ * A categorical palette for multi-series charts (pie/donut/bar by bucket).
+ * Cycles the accent chart vars so slices stay theme-aware + dark-mode safe.
+ */
+export const CHART_PALETTE: string[] = [
+    ACCENTS.sky.chartVar,
+    ACCENTS.emerald.chartVar,
+    ACCENTS.violet.chartVar,
+    ACCENTS.amber.chartVar,
+    ACCENTS.rose.chartVar,
+    ACCENTS.slate.chartVar,
+]
+
+/** Picks a palette color by index, wrapping around. */
+export function paletteColor(index: number): string {
+    return CHART_PALETTE[index % CHART_PALETTE.length]
+}
+
+/** Grid/axis muted color from the theme (works in light + dark). */
+export const CHART_MUTED = 'var(--muted-foreground, #94a3b8)'
+export const CHART_GRID = 'var(--border, #e2e8f0)'

package/src/widgets/widget-renderer.tsx

@@ -0,0 +1,181 @@
+// Per-widget dispatcher: maps a spec.kind to its built-in renderer (or a
+// federated <Slot> for kind:"custom"), wrapped in an error boundary so a single
+// broken widget renders its own error card instead of tumbling the grid.
+
+import * as React from 'react'
+import { Slot } from '../slot'
+import type { DashboardWidgetSpec, WidgetData, WidgetSize } from '../dashboard-types'
+import { WidgetCard, WidgetError } from './widget-card'
+import {
+    StatWidget,
+    BarWidget,
+    LineWidget,
+    AreaWidget,
+    PieWidget,
+    DonutWidget,
+    ListWidget,
+    ProgressWidget,
+    type WidgetRenderProps,
+} from './renderers'
+
+/** Maps a widget size to its column span in the 4-col grid. */
+export const SIZE_SPAN: Record<WidgetSize, number> = {
+    sm: 1,
+    md: 2,
+    lg: 3,
+    full: 4,
+}
+
+/** Tailwind col-span class per size (static → scanned in this package build). */
+export const SIZE_CLASS: Record<WidgetSize, string> = {
+    sm: 'sm:col-span-2 lg:col-span-1',
+    md: 'sm:col-span-2 lg:col-span-2',
+    lg: 'sm:col-span-2 lg:col-span-3',
+    full: 'sm:col-span-2 lg:col-span-4',
+}
+
+const RENDERERS: Record<
+    string,
+    (p: WidgetRenderProps) => React.ReactElement
+> = {
+    stat: StatWidget,
+    bar: BarWidget,
+    line: LineWidget,
+    area: AreaWidget,
+    pie: PieWidget,
+    donut: DonutWidget,
+    list: ListWidget,
+    progress: ProgressWidget,
+}
+
+interface BoundaryProps {
+    spec: DashboardWidgetSpec
+    message: string
+    children: React.ReactNode
+}
+interface BoundaryState {
+    error: boolean
+}
+
+/** Isolated boundary: a throwing widget renders its own error card. */
+class WidgetErrorBoundary extends React.Component<BoundaryProps, BoundaryState> {
+    state: BoundaryState = { error: false }
+    static getDerivedStateFromError(): BoundaryState {
+        return { error: true }
+    }
+    render() {
+        if (this.state.error) {
+            return (
+                <WidgetCard
+                    data-testid={`widget-${this.props.spec.key}`}
+                    title={this.props.spec.title}
+                    subtitle={this.props.spec.subtitle}
+                    icon={this.props.spec.icon}
+                    accent={this.props.spec.accent}
+                >
+                    <WidgetError message={this.props.message} />
+                </WidgetCard>
+            )
+        }
+        return this.props.children
+    }
+}
+
+export interface WidgetRendererProps {
+    spec: DashboardWidgetSpec
+    data?: WidgetData
+    locale?: string
+    currency?: string
+    /** Translated empty fallback for this widget. */
+    emptyText: string
+    /** Translated error message for this widget. */
+    errorText: string
+}
+
+/**
+ * Renders one widget. `kind:"custom"` defers to the federated slot
+ * (`spec.slot ?? 'dashboard.widgets'`) inside the same card chrome so it
+ * combines with the declarative widgets.
+ */
+export function WidgetRenderer({
+    spec,
+    data,
+    locale,
+    currency,
+    emptyText,
+    errorText,
+}: WidgetRendererProps) {
+    let body: React.ReactNode
+    if (spec.kind === 'custom') {
+        body = (
+            <WidgetCard
+                data-testid={`widget-${spec.key}`}
+                title={spec.title}
+                subtitle={spec.subtitle}
+                icon={spec.icon}
+                accent={spec.accent}
+            >
+                <Slot
+                    name={spec.slot ?? 'dashboard.widgets'}
+                    props={{ spec, data, locale, currency }}
+                    fallback={
+                        <div className="flex flex-1 items-center justify-center py-6 text-xs text-muted-foreground">
+                            {emptyText}
+                        </div>
+                    }
+                />
+            </WidgetCard>
+        )
+    } else {
+        const Renderer = RENDERERS[spec.kind]
+        body = Renderer ? (
+            <Renderer
+                spec={spec}
+                data={data}
+                locale={locale}
+                currency={currency}
+                emptyText={emptyText}
+            />
+        ) : (
+            <WidgetCard
+                data-testid={`widget-${spec.key}`}
+                title={spec.title}
+                subtitle={spec.subtitle}
+                icon={spec.icon}
+                accent={spec.accent}
+            >
+                <WidgetError message={errorText} />
+            </WidgetCard>
+        )
+    }
+
+    return (
+        <WidgetErrorBoundary spec={spec} message={errorText}>
+            {body}
+        </WidgetErrorBoundary>
+    )
+}
+
+/** Skeleton placeholder shown per widget while data loads. */
+export function WidgetSkeleton({ spec }: { spec: DashboardWidgetSpec }) {
+    const isChart =
+        spec.kind !== 'stat' && spec.kind !== 'progress' && spec.kind !== 'custom'
+    return (
+        <WidgetCard
+            data-testid={`widget-skeleton-${spec.key}`}
+            title={spec.title}
+            subtitle={spec.subtitle}
+            icon={spec.icon}
+            accent={spec.accent}
+        >
+            {isChart ? (
+                <div className="h-[132px] w-full animate-pulse rounded-md bg-muted" />
+            ) : (
+                <div className="flex flex-col gap-2">
+                    <div className="h-8 w-2/3 animate-pulse rounded bg-muted" />
+                    <div className="h-2 w-full animate-pulse rounded bg-muted/60" />
+                </div>
+            )}
+        </WidgetCard>
+    )
+}