@asteby/metacore-runtime-react 18.16.1 → 18.17.1

package/src/dashboard-grid.tsx

@@ -0,0 +1,205 @@
+// DashboardGrid — the modular dashboard surface. Renders the union of
+// declarative + federated widgets in a responsive 4-column grid, grouped with
+// headings, honouring per-widget size, permission gating (useCan), batch data
+// loading with per-widget skeletons, isolated per-widget errors, and a pro
+// global empty state. See CONTRACT-dashboard-widgets.md §4.
+
+import * as React from 'react'
+import { useTranslation } from 'react-i18next'
+import { cn } from '@asteby/metacore-ui/lib'
+import { useCan, usePermissionsActive } from './permissions-context'
+import { DynamicIcon } from './dynamic-icon'
+import type {
+    DashboardGridProps,
+    DashboardGridStrings,
+    DashboardWidgetGroup,
+    DashboardWidgetSpec,
+} from './dashboard-types'
+import { WidgetRenderer, WidgetSkeleton, spanClass } from './widgets/widget-renderer'
+
+const DEFAULT_STRINGS: DashboardGridStrings = {
+    emptyTitle: 'Your dashboard is empty',
+    emptyDescription:
+        'Install an addon with dashboard widgets to start seeing metrics here.',
+    widgetError: 'Could not load this widget.',
+    widgetEmpty: 'No data yet.',
+}
+
+/** Normalizes flat `widgets` + `groups` into an ordered group list. */
+export function normalizeGroups(
+    groups?: DashboardWidgetGroup[],
+    widgets?: DashboardWidgetSpec[],
+): DashboardWidgetGroup[] {
+    if (groups && groups.length > 0) return groups
+    if (!widgets || widgets.length === 0) return []
+    // Group flat widgets by `group` (preserve first-seen order), sort each
+    // group by `order` (default 100), keep insertion order across groups.
+    const map = new Map<string, DashboardWidgetSpec[]>()
+    for (const w of widgets) {
+        const key = w.group ?? ''
+        const arr = map.get(key) ?? []
+        arr.push(w)
+        map.set(key, arr)
+    }
+    return Array.from(map.entries()).map(([title, ws]) => ({
+        title,
+        widgets: [...ws].sort((a, b) => (a.order ?? 100) - (b.order ?? 100)),
+    }))
+}
+
+/** Collects every widget key across groups (for the batch loader). */
+function allKeys(groups: DashboardWidgetGroup[]): string[] {
+    const keys: string[] = []
+    for (const g of groups) for (const w of g.widgets) keys.push(w.key)
+    return keys
+}
+
+export function DashboardGrid({
+    groups,
+    widgets,
+    loadData,
+    isAdmin,
+    locale,
+    currency,
+    className,
+    strings,
+}: DashboardGridProps) {
+    const { t } = useTranslation()
+    const can = useCan()
+    const permissionsActive = usePermissionsActive()
+    const s = { ...DEFAULT_STRINGS, ...strings }
+
+    // i18n helper: translate a key, falling back to the raw key when missing
+    // (specs ship raw i18n keys; the host bundle may or may not have them).
+    const tr = React.useCallback(
+        (key?: string, fallback?: string): string => {
+            if (!key) return fallback ?? ''
+            const out = t(key)
+            return out === key ? fallback ?? key : out
+        },
+        [t],
+    )
+
+    // Permission gating: admin bypass; without a PermissionsProvider everything
+    // is visible (retrocompat). With one, honour each widget's `permission`.
+    const visibleGroups = React.useMemo(() => {
+        const norm = normalizeGroups(groups, widgets)
+        const gate = (w: DashboardWidgetSpec): boolean => {
+            if (isAdmin) return true
+            if (!permissionsActive) return true
+            if (!w.permission) return true
+            return can(w.permission)
+        }
+        return norm
+            .map((g) => ({ ...g, widgets: g.widgets.filter(gate) }))
+            .filter((g) => g.widgets.length > 0)
+    }, [groups, widgets, isAdmin, permissionsActive, can])
+
+    const keys = React.useMemo(() => allKeys(visibleGroups), [visibleGroups])
+    const keySig = keys.join(',')
+
+    const [data, setData] = React.useState<
+        Record<string, import('./dashboard-types').WidgetData> | null
+    >(null)
+    const [loading, setLoading] = React.useState(true)
+
+    React.useEffect(() => {
+        let cancelled = false
+        if (keys.length === 0) {
+            setLoading(false)
+            setData({})
+            return
+        }
+        setLoading(true)
+        loadData(keys)
+            .then((res) => {
+                if (!cancelled) {
+                    setData(res ?? {})
+                    setLoading(false)
+                }
+            })
+            .catch(() => {
+                // Batch failure: still render the grid; every widget falls to
+                // its empty/error state rather than blanking the page.
+                if (!cancelled) {
+                    setData({})
+                    setLoading(false)
+                }
+            })
+        return () => {
+            cancelled = true
+        }
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [keySig, loadData])
+
+    // Global empty state (no widgets at all / none visible after gating).
+    if (visibleGroups.length === 0) {
+        return (
+            <div
+                data-testid="dashboard-empty"
+                className={cn(
+                    'flex min-h-[40vh] flex-col items-center justify-center rounded-xl border border-dashed border-border/60 p-10 text-center',
+                    className,
+                )}
+            >
+                <div className="mb-4 flex size-14 items-center justify-center rounded-2xl bg-muted text-muted-foreground">
+                    <DynamicIcon name="LayoutDashboard" className="size-7" />
+                </div>
+                <h3 className="text-base font-semibold text-foreground">
+                    {tr(undefined, s.emptyTitle) || s.emptyTitle}
+                </h3>
+                <p className="mt-1 max-w-sm text-sm text-muted-foreground">
+                    {s.emptyDescription}
+                </p>
+            </div>
+        )
+    }
+
+    return (
+        <div data-testid="dashboard-grid" className={cn('flex flex-col gap-8', className)}>
+            {visibleGroups.map((group) => (
+                <section key={group.title || '__default'} className="flex flex-col gap-3">
+                    {group.title && (
+                        <h2 className="text-sm font-semibold uppercase tracking-wide text-muted-foreground">
+                            {tr(group.title, group.title)}
+                        </h2>
+                    )}
+                    <div className="grid grid-flow-row-dense auto-rows-[116px] grid-cols-2 gap-4 lg:grid-cols-4">
+                        {group.widgets.map((spec) => {
+                            return (
+                                <div key={spec.key} className={cn(spanClass(spec), 'min-h-0')}>
+                                    {loading ? (
+                                        <WidgetSkeleton
+                                            spec={{
+                                                ...spec,
+                                                title: tr(spec.title, spec.title),
+                                                subtitle: tr(spec.subtitle, spec.subtitle),
+                                            }}
+                                        />
+                                    ) : (
+                                        <WidgetRenderer
+                                            spec={{
+                                                ...spec,
+                                                title: tr(spec.title, spec.title),
+                                                subtitle: tr(spec.subtitle, spec.subtitle),
+                                            }}
+                                            data={data?.[spec.key]}
+                                            locale={locale}
+                                            currency={currency}
+                                            emptyText={
+                                                spec.empty
+                                                    ? tr(spec.empty, spec.empty)
+                                                    : s.widgetEmpty
+                                            }
+                                            errorText={s.widgetError}
+                                        />
+                                    )}
+                                </div>
+                            )
+                        })}
+                    </div>
+                </section>
+            ))}
+        </div>
+    )
+}

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'