@asteby/metacore-runtime-react 18.16.1 → 18.17.1

package/src/widgets/renderers.tsx

@@ -0,0 +1,351 @@
+// 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
+
+// Chart body that fills the card's flexible height. The dashboard grid gives
+// each chart cell a definite height (fixed auto-rows × row-span), so height:100%
+// resolves cleanly and charts scale with the card instead of a fixed stub.
+function ChartArea({ children }: { children: React.ReactElement }) {
+    return (
+        <div className="min-h-0 flex-1">
+            <ResponsiveContainer width="100%" height="100%">
+                {children}
+            </ResponsiveContainer>
+        </div>
+    )
+}
+
+// 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="flex min-h-0 flex-1 flex-col justify-center">
+                    <div className="text-[2rem] font-semibold leading-none tabular-nums tracking-tight text-foreground">
+                        {formatWidgetValue(value!, ctx)}
+                    </div>
+                </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) ? (
+                <ChartArea>
+                    <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={48} />
+                    </BarChart>
+                </ChartArea>
+            ) : (
+                <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) ? (
+                <ChartArea>
+                    {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>
+                    )}
+                </ChartArea>
+            ) : (
+                <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 min-h-0 flex-1 items-center gap-3">
+                    <div className="h-full min-h-0 w-[46%] shrink-0">
+                        <ResponsiveContainer width="100%" height="100%">
+                            <PieChart>
+                                <ChartTooltip ctx={ctx} />
+                                <Pie
+                                    data={p.data.series}
+                                    dataKey="value"
+                                    nameKey="label"
+                                    innerRadius={p.variant === 'donut' ? '55%' : 0}
+                                    outerRadius="92%"
+                                    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>
+                    </div>
+                    <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 min-h-0 flex-1 flex-col 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>
+    )
+}

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)'