@asteby/metacore-runtime-react 18.16.1 → 18.17.0

package/src/dashboard-types.ts

@@ -0,0 +1,178 @@
+// Dashboard widget types — the SDK-facing surface of the modular dashboard
+// contract (CONTRACT-dashboard-widgets.md §1, §3, §4). The host (ops/kernel)
+// computes the data and ships the specs as raw i18n keys; the SDK renders.
+//
+// These mirror the v3 `contributions.dashboard[]` shape so a host can forward
+// the backend response straight into <DashboardGrid> without remapping.
+
+/** Widget renderer kinds. `custom` defers to a federated slot component. */
+export type WidgetKind =
+    | 'stat'
+    | 'bar'
+    | 'line'
+    | 'area'
+    | 'pie'
+    | 'donut'
+    | 'list'
+    | 'progress'
+    | 'custom'
+
+/** Grid footprint in a 4-column grid: sm=1, md=2, lg=3, full=4. */
+export type WidgetSize = 'sm' | 'md' | 'lg' | 'full'
+
+/** Value format applied to the scalar value and to series values. */
+export type WidgetFormat = 'number' | 'currency' | 'percent' | 'compact'
+
+/** Accent color token (theme CSS vars). */
+export type WidgetAccent =
+    | 'emerald'
+    | 'sky'
+    | 'violet'
+    | 'amber'
+    | 'rose'
+    | 'slate'
+
+/** Aggregation kinds for declarative queries. */
+export type WidgetAggregate = 'count' | 'sum' | 'avg' | 'min' | 'max'
+
+/** Where-clause operators (mirror the list builder). */
+export interface WidgetWhereOp {
+    eq?: unknown
+    neq?: unknown
+    gt?: unknown
+    gte?: unknown
+    lt?: unknown
+    lte?: unknown
+    contains?: unknown
+}
+
+/**
+ * Declarative aggregation query (kinds other than `custom`). The host resolves
+ * the logical table from `model` and computes the aggregate org-scoped.
+ */
+export interface DashboardWidgetQuery {
+    model: string
+    aggregate: WidgetAggregate
+    field?: string
+    where?: Record<string, unknown | WidgetWhereOp>
+    group_by?: string
+    label_field?: string
+    date_field?: string
+    interval?: 'day' | 'week' | 'month'
+    range?:
+        | 'this_day'
+        | 'last_7_days'
+        | 'last_30_days'
+        | 'last_12_months'
+        | 'this_month'
+        | 'this_year'
+        | 'all'
+    order?: 'asc' | 'desc'
+    limit?: number
+}
+
+/** Optional delta comparison against the previous window → `+14.2%` chip. */
+export interface DashboardWidgetCompare {
+    to: 'previous_period'
+}
+
+/**
+ * A single dashboard widget spec (v3 contract §1). The host ships these as raw
+ * i18n keys (`title`, `subtitle`, `group`, `empty`); the grid translates them.
+ */
+export interface DashboardWidgetSpec {
+    /** Unique within the addon. Capability = `<addon>.dashboard.<key>`. */
+    key: string
+    /** i18n key for the title. */
+    title: string
+    /** i18n key for the subtitle. */
+    subtitle?: string
+    /** lucide icon slug. */
+    icon?: string
+    kind: WidgetKind
+    size?: WidgetSize
+    /** i18n key for the group heading. */
+    group?: string
+    /** Order within the group. */
+    order?: number
+    accent?: WidgetAccent
+    format?: WidgetFormat
+    /** Capability gating the widget (useCan). */
+    permission?: string
+    /** i18n key for the per-widget empty state. */
+    empty?: string
+
+    // declarative kinds
+    query?: DashboardWidgetQuery
+    compare?: DashboardWidgetCompare
+
+    // custom (federated) kind
+    slot?: string
+    expose?: string
+}
+
+/** A bucket of an aggregated series. */
+export interface WidgetSeriesPoint {
+    key: string
+    label: string
+    value: number
+}
+
+/**
+ * The computed data for one widget (CONTRACT §3). `value` for scalars,
+ * `series` for bucketed/temporal aggregates, `delta` for the compare chip
+ * (fraction, e.g. `0.142` → `+14.2%`).
+ */
+export interface WidgetData {
+    value?: number
+    delta?: number
+    series?: WidgetSeriesPoint[]
+}
+
+/** A titled group of widgets (CONTRACT §3 — backend grouping/order). */
+export interface DashboardWidgetGroup {
+    /** i18n key for the group heading. */
+    title: string
+    widgets: DashboardWidgetSpec[]
+}
+
+/**
+ * Loads the data for a batch of widget keys. The host runs the aggregation and
+ * returns a `{ [key]: WidgetData }` map. Keys missing from the result render
+ * their empty state.
+ */
+export type LoadWidgetData = (
+    keys: string[],
+) => Promise<Record<string, WidgetData>>
+
+/** Props for <DashboardGrid>. */
+export interface DashboardGridProps {
+    /** Pre-grouped widgets (backend grouping/order). */
+    groups?: DashboardWidgetGroup[]
+    /** Flat widget list — grouped client-side by `group`/`order`. */
+    widgets?: DashboardWidgetSpec[]
+    /** Batch loader for widget data (org-scoped, host-side aggregation). */
+    loadData: LoadWidgetData
+    /** When true, bypass permission gating (admin/owner sees everything). */
+    isAdmin?: boolean
+    /** BCP-47 locale for number/currency/date formatting. */
+    locale?: string
+    /** ISO-4217 currency for `format: 'currency'` widgets. */
+    currency?: string
+    /** Extra class on the grid root. */
+    className?: string
+    /** Optional override for empty/loading/error copy. */
+    strings?: Partial<DashboardGridStrings>
+}
+
+/** Translatable copy used by the grid chrome. Defaults are English. */
+export interface DashboardGridStrings {
+    /** Global empty state title (no widgets at all). */
+    emptyTitle: string
+    /** Global empty state description. */
+    emptyDescription: string
+    /** Per-widget error message. */
+    widgetError: string
+    /** Per-widget empty (no data) fallback when the spec has no `empty` key. */
+    widgetEmpty: string
+}

package/src/index.ts

@@ -181,3 +181,59 @@ export {
     ActivityTimeline,
     type ActivityTimelineProps,
 } from './activity-timeline'
+export {
+    DashboardGrid,
+    normalizeGroups,
+} from './dashboard-grid'
+export type {
+    WidgetKind,
+    WidgetSize,
+    WidgetFormat,
+    WidgetAccent,
+    WidgetAggregate,
+    WidgetWhereOp,
+    DashboardWidgetQuery,
+    DashboardWidgetCompare,
+    DashboardWidgetSpec,
+    WidgetSeriesPoint,
+    WidgetData,
+    DashboardWidgetGroup,
+    LoadWidgetData,
+    DashboardGridProps,
+    DashboardGridStrings,
+} from './dashboard-types'
+export {
+    StatWidget,
+    BarWidget,
+    LineWidget,
+    AreaWidget,
+    PieWidget,
+    DonutWidget,
+    ListWidget,
+    ProgressWidget,
+    type WidgetRenderProps,
+} from './widgets/renderers'
+export {
+    WidgetRenderer,
+    WidgetSkeleton,
+    SIZE_SPAN,
+    SIZE_CLASS,
+    type WidgetRendererProps,
+} from './widgets/widget-renderer'
+export {
+    WidgetCard,
+    DeltaChip,
+    WidgetEmpty,
+    WidgetError,
+    type WidgetCardProps,
+} from './widgets/widget-card'
+export {
+    formatWidgetValue,
+    formatAxisTick,
+    formatDelta,
+    accentClasses,
+    paletteColor,
+    CHART_PALETTE,
+    type AccentClasses,
+    type WidgetFormatCtx,
+} from './widgets/widget-format'

package/src/widgets/renderers.tsx

@@ -0,0 +1,336 @@
+// Built-in dashboard widget renderers, one per declarative `kind`. Each takes
+// the resolved spec + computed WidgetData + the format context (locale/currency)
+// and renders the body INSIDE a <WidgetCard>. recharts powers the charts; colors
+// come from theme CSS vars (dark-mode safe), curves are smooth, axes/legends
+// compact, tooltips on.
+
+import * as React from 'react'
+import {
+    Area,
+    AreaChart,
+    Bar,
+    BarChart,
+    CartesianGrid,
+    Cell,
+    Line,
+    LineChart,
+    Pie,
+    PieChart,
+    ResponsiveContainer,
+    Tooltip,
+    XAxis,
+    YAxis,
+} from 'recharts'
+import { cn } from '@asteby/metacore-ui/lib'
+import type { DashboardWidgetSpec, WidgetData } from '../dashboard-types'
+import { WidgetCard, DeltaChip, WidgetEmpty } from './widget-card'
+import {
+    accentClasses,
+    paletteColor,
+    formatWidgetValue,
+    formatAxisTick,
+    formatDelta,
+    CHART_GRID,
+    CHART_MUTED,
+    type WidgetFormatCtx,
+} from './widget-format'
+
+export interface WidgetRenderProps {
+    spec: DashboardWidgetSpec
+    data?: WidgetData
+    locale?: string
+    currency?: string
+    /** i18n: per-widget empty fallback (already translated). */
+    emptyText: string
+}
+
+const fmtCtx = (
+    spec: DashboardWidgetSpec,
+    locale?: string,
+    currency?: string,
+): WidgetFormatCtx => ({ format: spec.format, locale, currency })
+
+const hasSeries = (d?: WidgetData): d is WidgetData & { series: NonNullable<WidgetData['series']> } =>
+    Array.isArray(d?.series) && d!.series!.length > 0
+
+const CHART_HEIGHT = 132
+
+// Compact recharts tooltip styled with theme tokens.
+function ChartTooltip({ ctx }: { ctx: WidgetFormatCtx }) {
+    return (
+        <Tooltip
+            cursor={{ fill: 'var(--muted, rgba(148,163,184,0.12))', opacity: 0.4 }}
+            contentStyle={{
+                background: 'var(--popover, #fff)',
+                border: '1px solid var(--border, #e2e8f0)',
+                borderRadius: 8,
+                fontSize: 12,
+                color: 'var(--popover-foreground, #0f172a)',
+                boxShadow: '0 4px 16px rgba(0,0,0,0.08)',
+            }}
+            labelStyle={{ color: 'var(--muted-foreground, #64748b)', marginBottom: 2 }}
+            formatter={(v: number) => formatWidgetValue(Number(v), ctx)}
+        />
+    )
+}
+
+// --- stat -----------------------------------------------------------------
+export function StatWidget(p: WidgetRenderProps) {
+    const ctx = fmtCtx(p.spec, p.locale, p.currency)
+    const value = p.data?.value
+    const delta = p.data?.delta
+    const hasValue = typeof value === 'number' && !Number.isNaN(value)
+    return (
+        <WidgetCard
+            data-testid={`widget-${p.spec.key}`}
+            title={p.spec.title}
+            subtitle={p.spec.subtitle}
+            icon={p.spec.icon}
+            accent={p.spec.accent}
+            headerExtra={
+                typeof delta === 'number' ? (
+                    <DeltaChip delta={delta} text={formatDelta(delta, p.locale)} />
+                ) : undefined
+            }
+        >
+            {hasValue ? (
+                <div className="text-3xl font-semibold tabular-nums tracking-tight text-foreground">
+                    {formatWidgetValue(value!, ctx)}
+                </div>
+            ) : (
+                <WidgetEmpty message={p.emptyText} />
+            )}
+        </WidgetCard>
+    )
+}
+
+// --- bar ------------------------------------------------------------------
+export function BarWidget(p: WidgetRenderProps) {
+    const ctx = fmtCtx(p.spec, p.locale, p.currency)
+    const a = accentClasses(p.spec.accent)
+    return (
+        <WidgetCard
+            data-testid={`widget-${p.spec.key}`}
+            title={p.spec.title}
+            subtitle={p.spec.subtitle}
+            icon={p.spec.icon}
+            accent={p.spec.accent}
+        >
+            {hasSeries(p.data) ? (
+                <ResponsiveContainer width="100%" height={CHART_HEIGHT}>
+                    <BarChart data={p.data.series} margin={{ top: 4, right: 4, left: -16, bottom: 0 }}>
+                        <CartesianGrid vertical={false} stroke={CHART_GRID} strokeDasharray="3 3" />
+                        <XAxis
+                            dataKey="label"
+                            tick={{ fontSize: 10, fill: CHART_MUTED }}
+                            tickLine={false}
+                            axisLine={false}
+                            interval="preserveStartEnd"
+                        />
+                        <YAxis
+                            tick={{ fontSize: 10, fill: CHART_MUTED }}
+                            tickLine={false}
+                            axisLine={false}
+                            width={44}
+                            tickFormatter={(v: number) => formatAxisTick(v, ctx)}
+                        />
+                        <ChartTooltip ctx={ctx} />
+                        <Bar dataKey="value" fill={a.chartVar} radius={[4, 4, 0, 0]} maxBarSize={40} />
+                    </BarChart>
+                </ResponsiveContainer>
+            ) : (
+                <WidgetEmpty message={p.emptyText} />
+            )}
+        </WidgetCard>
+    )
+}
+
+// --- line / area (shared) -------------------------------------------------
+function TimeSeriesWidget(p: WidgetRenderProps & { variant: 'line' | 'area' }) {
+    const ctx = fmtCtx(p.spec, p.locale, p.currency)
+    const a = accentClasses(p.spec.accent)
+    const gradId = `wg-grad-${p.spec.key}`
+    return (
+        <WidgetCard
+            data-testid={`widget-${p.spec.key}`}
+            title={p.spec.title}
+            subtitle={p.spec.subtitle}
+            icon={p.spec.icon}
+            accent={p.spec.accent}
+        >
+            {hasSeries(p.data) ? (
+                <ResponsiveContainer width="100%" height={CHART_HEIGHT}>
+                    {p.variant === 'area' ? (
+                        <AreaChart data={p.data.series} margin={{ top: 4, right: 6, left: -16, bottom: 0 }}>
+                            <defs>
+                                <linearGradient id={gradId} x1="0" y1="0" x2="0" y2="1">
+                                    <stop offset="0%" stopColor={a.chartVar} stopOpacity={0.35} />
+                                    <stop offset="100%" stopColor={a.chartVar} stopOpacity={0.02} />
+                                </linearGradient>
+                            </defs>
+                            <CartesianGrid vertical={false} stroke={CHART_GRID} strokeDasharray="3 3" />
+                            <XAxis dataKey="label" tick={{ fontSize: 10, fill: CHART_MUTED }} tickLine={false} axisLine={false} interval="preserveStartEnd" />
+                            <YAxis tick={{ fontSize: 10, fill: CHART_MUTED }} tickLine={false} axisLine={false} width={44} tickFormatter={(v: number) => formatAxisTick(v, ctx)} />
+                            <ChartTooltip ctx={ctx} />
+                            <Area type="monotone" dataKey="value" stroke={a.chartVar} strokeWidth={2} fill={`url(#${gradId})`} />
+                        </AreaChart>
+                    ) : (
+                        <LineChart data={p.data.series} margin={{ top: 4, right: 6, left: -16, bottom: 0 }}>
+                            <CartesianGrid vertical={false} stroke={CHART_GRID} strokeDasharray="3 3" />
+                            <XAxis dataKey="label" tick={{ fontSize: 10, fill: CHART_MUTED }} tickLine={false} axisLine={false} interval="preserveStartEnd" />
+                            <YAxis tick={{ fontSize: 10, fill: CHART_MUTED }} tickLine={false} axisLine={false} width={44} tickFormatter={(v: number) => formatAxisTick(v, ctx)} />
+                            <ChartTooltip ctx={ctx} />
+                            <Line type="monotone" dataKey="value" stroke={a.chartVar} strokeWidth={2} dot={false} activeDot={{ r: 4 }} />
+                        </LineChart>
+                    )}
+                </ResponsiveContainer>
+            ) : (
+                <WidgetEmpty message={p.emptyText} />
+            )}
+        </WidgetCard>
+    )
+}
+
+export function LineWidget(p: WidgetRenderProps) {
+    return <TimeSeriesWidget {...p} variant="line" />
+}
+export function AreaWidget(p: WidgetRenderProps) {
+    return <TimeSeriesWidget {...p} variant="area" />
+}
+
+// --- pie / donut (shared) -------------------------------------------------
+function CircularWidget(p: WidgetRenderProps & { variant: 'pie' | 'donut' }) {
+    const ctx = fmtCtx(p.spec, p.locale, p.currency)
+    return (
+        <WidgetCard
+            data-testid={`widget-${p.spec.key}`}
+            title={p.spec.title}
+            subtitle={p.spec.subtitle}
+            icon={p.spec.icon}
+            accent={p.spec.accent}
+        >
+            {hasSeries(p.data) ? (
+                <div className="flex items-center gap-3">
+                    <ResponsiveContainer width="50%" height={CHART_HEIGHT}>
+                        <PieChart>
+                            <ChartTooltip ctx={ctx} />
+                            <Pie
+                                data={p.data.series}
+                                dataKey="value"
+                                nameKey="label"
+                                innerRadius={p.variant === 'donut' ? 32 : 0}
+                                outerRadius={56}
+                                paddingAngle={p.variant === 'donut' ? 2 : 0}
+                                stroke="var(--background, #fff)"
+                                strokeWidth={2}
+                            >
+                                {p.data.series.map((_, i) => (
+                                    <Cell key={i} fill={paletteColor(i)} />
+                                ))}
+                            </Pie>
+                        </PieChart>
+                    </ResponsiveContainer>
+                    <ul className="flex min-w-0 flex-1 flex-col gap-1.5">
+                        {p.data.series.slice(0, 6).map((pt, i) => (
+                            <li key={pt.key} className="flex items-center gap-2 text-xs">
+                                <span className="size-2.5 shrink-0 rounded-sm" style={{ background: paletteColor(i) }} />
+                                <span className="truncate text-muted-foreground">{pt.label}</span>
+                                <span className="ml-auto shrink-0 font-medium tabular-nums text-foreground">
+                                    {formatWidgetValue(pt.value, ctx)}
+                                </span>
+                            </li>
+                        ))}
+                    </ul>
+                </div>
+            ) : (
+                <WidgetEmpty message={p.emptyText} />
+            )}
+        </WidgetCard>
+    )
+}
+
+export function PieWidget(p: WidgetRenderProps) {
+    return <CircularWidget {...p} variant="pie" />
+}
+export function DonutWidget(p: WidgetRenderProps) {
+    return <CircularWidget {...p} variant="donut" />
+}
+
+// --- list (top-N with proportion bars) ------------------------------------
+export function ListWidget(p: WidgetRenderProps) {
+    const ctx = fmtCtx(p.spec, p.locale, p.currency)
+    const a = accentClasses(p.spec.accent)
+    const series = p.data?.series ?? []
+    const max = series.reduce((m, s) => Math.max(m, s.value), 0) || 1
+    return (
+        <WidgetCard
+            data-testid={`widget-${p.spec.key}`}
+            title={p.spec.title}
+            subtitle={p.spec.subtitle}
+            icon={p.spec.icon}
+            accent={p.spec.accent}
+        >
+            {series.length > 0 ? (
+                <ul className="flex flex-col gap-2.5">
+                    {series.map((pt) => (
+                        <li key={pt.key} className="flex flex-col gap-1">
+                            <div className="flex items-baseline justify-between gap-2 text-xs">
+                                <span className="truncate text-foreground">{pt.label}</span>
+                                <span className="shrink-0 font-medium tabular-nums text-muted-foreground">
+                                    {formatWidgetValue(pt.value, ctx)}
+                                </span>
+                            </div>
+                            <div className={cn('h-1.5 w-full overflow-hidden rounded-full', a.track)}>
+                                <div
+                                    className={cn('h-full rounded-full transition-all', a.bar)}
+                                    style={{ width: `${Math.max(2, (pt.value / max) * 100)}%` }}
+                                />
+                            </div>
+                        </li>
+                    ))}
+                </ul>
+            ) : (
+                <WidgetEmpty message={p.emptyText} />
+            )}
+        </WidgetCard>
+    )
+}
+
+// --- progress -------------------------------------------------------------
+// A scalar rendered as a proportion bar. When `format:'percent'` the value is
+// a fraction in [0,1]; otherwise it's shown as the big number with a full bar.
+export function ProgressWidget(p: WidgetRenderProps) {
+    const ctx = fmtCtx(p.spec, p.locale, p.currency)
+    const a = accentClasses(p.spec.accent)
+    const value = p.data?.value
+    const hasValue = typeof value === 'number' && !Number.isNaN(value)
+    const pct =
+        p.spec.format === 'percent'
+            ? Math.min(100, Math.max(0, (value ?? 0) * 100))
+            : 100
+    return (
+        <WidgetCard
+            data-testid={`widget-${p.spec.key}`}
+            title={p.spec.title}
+            subtitle={p.spec.subtitle}
+            icon={p.spec.icon}
+            accent={p.spec.accent}
+        >
+            {hasValue ? (
+                <div className="flex flex-col gap-2">
+                    <div className="text-2xl font-semibold tabular-nums tracking-tight text-foreground">
+                        {formatWidgetValue(value!, ctx)}
+                    </div>
+                    <div className={cn('h-2 w-full overflow-hidden rounded-full', a.track)}>
+                        <div
+                            className={cn('h-full rounded-full transition-all duration-500', a.bar)}
+                            style={{ width: `${pct}%` }}
+                        />
+                    </div>
+                </div>
+            ) : (
+                <WidgetEmpty message={p.emptyText} />
+            )}
+        </WidgetCard>
+    )
+}

package/src/widgets/widget-card.tsx

@@ -0,0 +1,125 @@
+// Shared "pro" card chrome for every dashboard widget. Subtle border, hover
+// ring, an accent icon chip, title + optional subtitle, and a subtle mount
+// motion done in pure CSS (runtime-react does not ship framer-motion). The
+// chrome is identical for declarative renderers AND `kind:"custom"` federated
+// widgets so they visually combine in the same grid.
+
+import * as React from 'react'
+import { Card, CardContent, CardHeader } from '@asteby/metacore-ui'
+import { cn } from '@asteby/metacore-ui/lib'
+import { DynamicIcon, isLucideIconName } from '../dynamic-icon'
+import { accentClasses } from './widget-format'
+import type { WidgetAccent } from '../dashboard-types'
+
+export interface WidgetCardProps {
+    title: string
+    subtitle?: string
+    icon?: string
+    accent?: WidgetAccent
+    /** Right-aligned header slot (e.g. a delta chip). */
+    headerExtra?: React.ReactNode
+    /** Body content. */
+    children?: React.ReactNode
+    className?: string
+    /** Forwarded for testing/automation. */
+    'data-testid'?: string
+}
+
+/**
+ * The card frame shared by all widgets. Keep the chrome here so a single style
+ * change propagates to every kind (and to federated custom widgets).
+ */
+export function WidgetCard({
+    title,
+    subtitle,
+    icon,
+    accent,
+    headerExtra,
+    children,
+    className,
+    ...rest
+}: WidgetCardProps) {
+    const a = accentClasses(accent)
+    const showIcon = icon && isLucideIconName(icon)
+    return (
+        <Card
+            {...rest}
+            className={cn(
+                // base: subtle border, ring on hover, gentle lift, mount fade-in
+                'group/widget relative flex h-full flex-col overflow-hidden',
+                'border-border/60 transition-all duration-200',
+                'hover:border-border hover:ring-1 hover:ring-ring/30 hover:shadow-sm',
+                'motion-safe:animate-in motion-safe:fade-in-0 motion-safe:slide-in-from-bottom-1 motion-safe:duration-500',
+                className,
+            )}
+        >
+            <CardHeader className="flex flex-row items-start justify-between gap-3 space-y-0 pb-2">
+                <div className="flex min-w-0 items-start gap-3">
+                    {showIcon && (
+                        <span
+                            className={cn(
+                                'flex size-9 shrink-0 items-center justify-center rounded-lg',
+                                a.chip,
+                            )}
+                        >
+                            <DynamicIcon name={icon!} className="size-[18px]" />
+                        </span>
+                    )}
+                    <div className="min-w-0">
+                        <div className="truncate text-sm font-medium leading-tight text-foreground">
+                            {title}
+                        </div>
+                        {subtitle && (
+                            <div className="mt-0.5 truncate text-xs text-muted-foreground">
+                                {subtitle}
+                            </div>
+                        )}
+                    </div>
+                </div>
+                {headerExtra && <div className="shrink-0">{headerExtra}</div>}
+            </CardHeader>
+            <CardContent className="flex flex-1 flex-col justify-end pt-1">
+                {children}
+            </CardContent>
+        </Card>
+    )
+}
+
+/** Delta chip: green up / red down, neutral on zero. `text` is preformatted. */
+export function DeltaChip({ delta, text }: { delta: number; text: string }) {
+    const up = delta > 0
+    const down = delta < 0
+    return (
+        <span
+            className={cn(
+                'inline-flex items-center gap-1 rounded-full px-2 py-0.5 text-xs font-medium tabular-nums',
+                up && 'bg-emerald-500/10 text-emerald-600 dark:text-emerald-400',
+                down && 'bg-rose-500/10 text-rose-600 dark:text-rose-400',
+                !up && !down && 'bg-muted text-muted-foreground',
+            )}
+        >
+            {up && '▲'}
+            {down && '▼'}
+            {text}
+        </span>
+    )
+}
+
+/** Centered empty state inside a widget body (no data / missing). */
+export function WidgetEmpty({ message }: { message: string }) {
+    return (
+        <div className="flex flex-1 items-center justify-center py-6 text-center text-xs text-muted-foreground">
+            {message}
+        </div>
+    )
+}
+
+/** Per-widget error state — isolated so a broken widget never tumbles the grid. */
+export function WidgetError({ message }: { message: string }) {
+    return (
+        <div className="flex flex-1 items-center justify-center gap-2 py-6 text-center text-xs text-destructive">
+            <DynamicIcon name="TriangleAlert" className="size-4" />
+            <span>{message}</span>
+        </div>
+    )
+}