@multiplatform.one/components 6.7.0 → 7.0.0

package/src/views/Dashboard.tsx

@@ -1,8 +1,10 @@
 import { BarChart } from "../charts/BarChart";
 import { LineChart } from "../charts/LineChart";
 import { PieChart } from "../charts/PieChart";
+import { Sparkline } from "../charts/Sparkline";
 import { componentColors, sectionHeading } from "../componentColors";
 import { AsyncBoundary } from "../layouts/AsyncBoundary";
+import { Card } from "../surfaces";
 import {
   formatCurrency,
   formatNumber,
@@ -10,13 +12,13 @@ import {
   useResolvedKnobs,
 } from "@multiplatform.one/theme";
 import React, { useCallback, useMemo, type ReactNode } from "react";
-import { useTranslation } from "react-i18next";
+import { useTranslation } from "../shared/i18n";
 import {
-  Card,
   ScrollView,
   Text,
   XStack,
   YStack,
+  isWeb,
   type YStackProps,
   H2,
   H3,
@@ -33,6 +35,26 @@ import {
 const SECTION_HEADING_TAGS = { 2: H2, 3: H3, 4: H4, 5: H5, 6: H6 } as const;
 export type CardHeadingLevel = 2 | 3 | 4 | 5 | 6;
 
+function splitNestedControl(nested: {
+  px: number;
+  hitSlop: { top: number; bottom: number; left: number; right: number };
+  width: number;
+  height: number;
+  minWidth: number;
+  maxWidth: number;
+  minHeight: number;
+  maxHeight: number;
+}) {
+  const { px, hitSlop, ...box } = nested;
+  return { px, hitSlop, box };
+}
+
+function trendFill(color: string): string {
+  if (color === componentColors.semantic.success) return "$green4";
+  if (color === componentColors.semantic.error) return "$red4";
+  return "$color4";
+}
+
 // ============================================================================
 // Types
 // ============================================================================
@@ -82,6 +104,11 @@ export interface KPICardConfig {
   icon?: React.ReactNode;
   color?: string;
   onClick?: () => void;
+  /**
+   * Grafana Stat / Polaris metric sparkline. Nested-scale height (LC-73);
+   * series color stays on the chart identity palette (LC-27).
+   */
+  sparkline?: number[];
 }
 
 /**
@@ -98,16 +125,64 @@ export interface ChartConfig {
   colors?: string[];
 }
 
+/**
+ * Grafana bar-gauge / Polaris progress / Frappe percentage number-card.
+ */
+export interface ProgressConfig {
+  id: string;
+  title: string;
+  value: number;
+  max?: number;
+  format?: "number" | "percent";
+  color?: string;
+}
+
+/**
+ * Frappe workspace shortcut: label + nested count pill.
+ */
+export interface ShortcutConfig {
+  id: string;
+  title: string;
+  count?: number | string;
+  icon?: React.ReactNode;
+  color?: string;
+  onClick?: () => void;
+}
+
+/**
+ * Frappe link card / Polaris resource list / Grafana table-lite.
+ */
+export interface DashboardListItem {
+  id: string;
+  label: string;
+  meta?: string;
+  onClick?: () => void;
+}
+
+export interface ListConfig {
+  id: string;
+  title: string;
+  items: DashboardListItem[];
+}
+
 /**
  * Dashboard widget configuration.
+ *
+ * Catalog (Frappe workspace + Grafana-lite + Polaris metrics):
+ * number card (`kpi`), plot (`chart`), bar gauge (`progress`), shortcut,
+ * link list, and an escape hatch (`custom`).
  */
 export interface DashboardWidget {
   id: string;
-  type: "kpi" | "chart" | "custom";
+  type: "kpi" | "chart" | "custom" | "progress" | "shortcut" | "list";
   colSpan?: number;
   rowSpan?: number;
   kpiConfig?: KPICardConfig;
   chartConfig?: ChartConfig;
+  progressConfig?: ProgressConfig;
+  shortcutConfig?: ShortcutConfig;
+  listConfig?: ListConfig;
+  content?: ReactNode;
 }
 
 /**
@@ -141,6 +216,94 @@ export interface DashboardProps extends Omit<YStackProps, "children"> {
   emptyMessage?: string;
 }
 
+// ============================================================================
+// Shared card chrome
+// ============================================================================
+
+function useWidgetChrome(onPress?: () => void) {
+  const resolved = useResolvedKnobs();
+  const { knobProps, control } = resolved;
+  const nested = splitNestedControl(knobProps.nestedControl);
+  const interactive = onPress
+    ? {
+        cursor: "pointer" as const,
+        hoverStyle: control.hoverKnobProps,
+        pressStyle: control.pressKnobProps,
+        focusVisibleStyle: control.focusVisibleKnobProps,
+        onPress,
+        role: "button" as const,
+      }
+    : undefined;
+  return { knobProps, control, nested, interactive };
+}
+
+function NestedIconWell({
+  color,
+  box,
+  px,
+  radius,
+  children,
+}: {
+  color?: string;
+  box: ReturnType<typeof splitNestedControl>["box"];
+  px: number;
+  radius: object;
+  children: ReactNode;
+}) {
+  return (
+    <YStack
+      {...box}
+      {...radius}
+      alignItems="center"
+      justifyContent="center"
+      backgroundColor={(color || "$accentBackground") as any}
+      overflow="hidden"
+      data-nested-px={px}
+    >
+      {children}
+    </YStack>
+  );
+}
+
+function TrendPill({
+  symbol,
+  value,
+  color,
+  px,
+  radius,
+  label,
+}: {
+  symbol: string;
+  value?: string | number;
+  color: string;
+  px: number;
+  radius: object;
+  label: object;
+}) {
+  return (
+    <XStack
+      height={px}
+      minHeight={px}
+      maxHeight={px}
+      paddingHorizontal="$2"
+      alignItems="center"
+      gap="$1"
+      backgroundColor={trendFill(color)}
+      {...radius}
+      data-nested-px={px}
+    >
+      <Text {...label} color={color}>
+        {symbol}
+      </Text>
+      {value != null && value !== "" && (
+        <Text {...label} color={color}>
+          {value}
+        </Text>
+      )}
+    </XStack>
+  );
+}
+
 // ============================================================================
 // KPI Card Component
 // ============================================================================
@@ -168,15 +331,14 @@ export function resolveTrendColor(
 }
 
 /**
- * KPI card component for displaying a single metric.
- * Uses native Tamagui `Card` with `elevate`, `bordered`, and `size`.
+ * KPI card — Frappe number card + Grafana Stat + Polaris metric.
+ * Nested icon well and trend pill use `nestedControl` (LC-73); the value
+ * never takes `sizeToken` as fontSize (that token is a control height).
  */
 export function KPICard({ config, ...stackProps }: KPICardProps) {
-  const { knobProps } = useResolvedKnobs();
-  // One register for the metric, wherever the card shows it (LC-12 render
-  // channel): the headline value and the "vs previous" comparison are the
-  // same data class and may not speak in two voices. Summary tiles take the
-  // money register's `auto` variant — cents only when the value has them.
+  const { t } = useTranslation();
+  const { knobProps, nested, interactive } = useWidgetChrome(config.onClick);
+  const { px, box } = nested;
   const formatMetric = useCallback(
     (num: number) => {
       if (config.format === "currency") {
@@ -208,59 +370,48 @@ export function KPICard({ config, ...stackProps }: KPICardProps) {
 
   return (
     <Card
-      size={knobProps.sizeToken}
-      {...knobProps.borderRadius}
+      width="100%"
       elevation={knobProps.elevation}
-      borderWidth={1}
-      borderColor="$borderColor"
-      cursor={config.onClick ? "pointer" : undefined}
-      hoverStyle={config.onClick ? { scale: 0.98, borderColor: "$accentBackground" } : undefined}
-      pressStyle={config.onClick ? { scale: 0.97 } : undefined}
-      onPress={config.onClick}
+      {...knobProps.surface}
+      {...interactive}
       {...stackProps}
     >
-      <Card.Header {...knobProps.panelPadding}>
-        <XStack justifyContent="space-between" alignItems="flex-start">
-          <Text fontSize={knobProps.sizeToken} color={componentColors.text.muted} fontWeight="500">
-            {config.title}
-          </Text>
-          {config.icon && (
-            <YStack
-              backgroundColor={(config.color || "$accentBackground") as any}
-              padding="$2"
-              {...knobProps.borderRadius}
-            >
-              {config.icon}
-            </YStack>
+      <XStack justifyContent="space-between" alignItems="flex-start">
+        <Text {...knobProps.label} color={componentColors.text.muted} flex={1}>
+          {config.title}
+        </Text>
+        {config.icon ? (
+          <NestedIconWell color={config.color} box={box} px={px} radius={knobProps.borderRadius}>
+            {config.icon}
+          </NestedIconWell>
+        ) : null}
+      </XStack>
+
+      <Text fontSize="$8" color="$color" {...knobProps.heading}>
+        {formattedValue}
+      </Text>
+
+      {config.sparkline && config.sparkline.length > 0 ? (
+        <Sparkline data={config.sparkline} height={px} title={config.title} />
+      ) : null}
+
+      {(config.trend || config.trendValue) && (
+        <XStack gap="$2" alignItems="center" flexWrap="wrap">
+          <TrendPill
+            symbol={trendSymbol}
+            value={config.trendValue}
+            color={trendColor}
+            px={px}
+            radius={knobProps.borderRadius}
+            label={knobProps.label}
+          />
+          {config.previousValue !== undefined && (
+            <Text {...knobProps.label} color={componentColors.text.muted}>
+              {t("vs {{previousValue}}", { previousValue: formatMetric(config.previousValue) })}
+            </Text>
           )}
         </XStack>
-      </Card.Header>
-
-      <Card.Footer {...knobProps.panelPadding}>
-        <YStack {...knobProps.gap}>
-          <Text fontSize="$8" fontWeight="700" color="$color">
-            {formattedValue}
-          </Text>
-
-          {(config.trend || config.trendValue) && (
-            <XStack gap="$2" alignItems="center">
-              <Text fontSize="$2" color={trendColor}>
-                {trendSymbol}
-              </Text>
-              {config.trendValue && (
-                <Text fontSize="$2" color={trendColor}>
-                  {config.trendValue}
-                </Text>
-              )}
-              {config.previousValue !== undefined && (
-                <Text fontSize="$2" color={componentColors.text.muted}>
-                  vs {formatMetric(config.previousValue)}
-                </Text>
-              )}
-            </XStack>
-          )}
-        </YStack>
-      </Card.Footer>
+      )}
     </Card>
   );
 }
@@ -282,7 +433,6 @@ export interface ChartCardProps extends Omit<YStackProps, "children"> {
 
 /**
  * Chart card component for displaying a chart with a title.
- * Uses native Tamagui `Card` with `elevate`, `bordered`, and `size`.
  *
  * LC-38 PAGE-LINE (Axiom 16 ALIGNMENT): the title renders OUTSIDE the
  * painted card — a chart card is a section, and same-rank section headings
@@ -300,60 +450,212 @@ export interface ChartCardProps extends Omit<YStackProps, "children"> {
 export function ChartCard({ config, colors, headingLevel = 2, ...stackProps }: ChartCardProps) {
   const { knobProps } = useResolvedKnobs();
   const HeadingTag = SECTION_HEADING_TAGS[headingLevel];
-  // Explicit colors only where the dashboard intends data-colored series.
   const dataColors = config.colors ?? colors;
-  // ChartConfig.showLabels maps to the category (x) axis of the universal
-  // charts; the value axis stays off, matching the card's compact anatomy.
   const showXAxis = config.showLabels !== false;
 
   return (
-    <YStack {...knobProps.gap} {...stackProps}>
-      <HeadingTag margin={0} {...sectionHeading}>
+    <YStack {...knobProps.gap} width="100%" {...stackProps}>
+      <HeadingTag margin={0} {...knobProps.heading} {...sectionHeading}>
         {config.title}
       </HeadingTag>
-      <Card
-        size={knobProps.sizeToken}
+      <Card elevation={knobProps.elevation} {...knobProps.surface}>
+        {config.type === "pie" ? (
+          <PieChart
+            data={config.data}
+            height={config.height}
+            donut={0.5}
+            colors={dataColors}
+            showLegend={config.showLegend}
+            title={config.title}
+          />
+        ) : config.type === "line" ? (
+          <LineChart
+            data={config.data}
+            height={config.height}
+            color={dataColors?.[0]}
+            showPoints
+            showXAxis={showXAxis}
+            showYAxis={false}
+          />
+        ) : (
+          <BarChart
+            data={config.data}
+            height={config.height}
+            colors={dataColors}
+            showXAxis={showXAxis}
+            showYAxis={false}
+          />
+        )}
+      </Card>
+    </YStack>
+  );
+}
+
+// ============================================================================
+// Progress / Shortcut / List widgets
+// ============================================================================
+
+export interface ProgressCardProps extends Omit<YStackProps, "children"> {
+  config: ProgressConfig;
+}
+
+export function ProgressCard({ config, ...stackProps }: ProgressCardProps) {
+  const { knobProps, nested } = useWidgetChrome();
+  const { px } = nested;
+  const max = config.max && config.max > 0 ? config.max : 100;
+  const pct = Math.max(0, Math.min(100, (config.value / max) * 100));
+  const trackHeight = Math.max(6, Math.round(px / 4));
+  const label =
+    config.format === "number" ? formatNumber(config.value) : formatPercent(Math.round(pct));
+
+  return (
+    <Card width="100%" elevation={knobProps.elevation} {...knobProps.surface} {...stackProps}>
+      <XStack justifyContent="space-between" alignItems="baseline" {...knobProps.gap}>
+        <Text {...knobProps.label} color={componentColors.text.muted} flex={1}>
+          {config.title}
+        </Text>
+        <Text color="$color" {...knobProps.label}>
+          {label}
+        </Text>
+      </XStack>
+      <YStack
+        height={trackHeight}
+        backgroundColor="$color4"
+        overflow="hidden"
         {...knobProps.borderRadius}
-        elevation={knobProps.elevation}
-        borderWidth={1}
-        borderColor="$borderColor"
+        role="progressbar"
+        aria-valuenow={config.value}
+        aria-valuemin={0}
+        aria-valuemax={max}
+        aria-label={config.title}
       >
-        <Card.Footer {...knobProps.panelPadding}>
-          {config.type === "pie" ? (
-            <PieChart
-              data={config.data}
-              height={config.height}
-              // Parity with the old card pie anatomy (0.5-ratio hole) — now a
-              // true transparent arc hole instead of a painted circle.
-              donut={0.5}
-              colors={dataColors}
-              showLegend={config.showLegend}
-              title={config.title}
-            />
-          ) : config.type === "line" ? (
-            <LineChart
-              data={config.data}
-              height={config.height}
-              color={dataColors?.[0]}
-              showPoints
-              showXAxis={showXAxis}
-              showYAxis={false}
-            />
-          ) : (
-            <BarChart
-              data={config.data}
-              height={config.height}
-              colors={dataColors}
-              showXAxis={showXAxis}
-              showYAxis={false}
-            />
-          )}
-        </Card.Footer>
+        <YStack
+          height="100%"
+          width={`${pct}%`}
+          backgroundColor={(config.color || "$accentBackground") as any}
+        />
+      </YStack>
+    </Card>
+  );
+}
+
+export interface ShortcutCardProps extends Omit<YStackProps, "children"> {
+  config: ShortcutConfig;
+}
+
+export function ShortcutCard({ config, ...stackProps }: ShortcutCardProps) {
+  const { knobProps, nested, interactive } = useWidgetChrome(config.onClick);
+  const { px, box, hitSlop } = nested;
+
+  return (
+    <Card
+      width="100%"
+      elevation={knobProps.elevation}
+      {...knobProps.surface}
+      {...interactive}
+      hitSlop={config.onClick ? hitSlop : undefined}
+      {...stackProps}
+    >
+      <XStack alignItems="center" {...knobProps.gap}>
+        {config.icon ? (
+          <NestedIconWell color={config.color} box={box} px={px} radius={knobProps.borderRadius}>
+            {config.icon}
+          </NestedIconWell>
+        ) : null}
+        <Text {...knobProps.body} fontWeight="600" flex={1} numberOfLines={1}>
+          {config.title}
+        </Text>
+        {config.count != null && config.count !== "" ? (
+          <XStack
+            height={px}
+            minHeight={px}
+            maxHeight={px}
+            minWidth={px}
+            paddingHorizontal="$2"
+            alignItems="center"
+            justifyContent="center"
+            backgroundColor="$color4"
+            {...knobProps.borderRadius}
+            data-nested-px={px}
+          >
+            <Text {...knobProps.label} color={componentColors.text.secondary}>
+              {config.count}
+            </Text>
+          </XStack>
+        ) : null}
+      </XStack>
+    </Card>
+  );
+}
+
+export interface ListCardProps extends Omit<YStackProps, "children"> {
+  config: ListConfig;
+  headingLevel?: CardHeadingLevel;
+}
+
+export function ListCard({ config, headingLevel = 2, ...stackProps }: ListCardProps) {
+  const { knobProps, nested, control } = useWidgetChrome();
+  const { px, hitSlop } = nested;
+  const HeadingTag = SECTION_HEADING_TAGS[headingLevel];
+
+  return (
+    <YStack {...knobProps.gap} width="100%" {...stackProps}>
+      <HeadingTag margin={0} {...knobProps.heading} {...sectionHeading}>
+        {config.title}
+      </HeadingTag>
+      <Card elevation={knobProps.elevation} {...knobProps.surface}>
+        {config.items.map((item) => (
+          <XStack
+            key={item.id}
+            height={px}
+            minHeight={px}
+            maxHeight={px}
+            alignItems="center"
+            justifyContent="space-between"
+            {...knobProps.gap}
+            data-nested-px={px}
+            cursor={item.onClick ? "pointer" : undefined}
+            hitSlop={item.onClick ? hitSlop : undefined}
+            hoverStyle={item.onClick ? control.hoverKnobProps : undefined}
+            pressStyle={item.onClick ? control.pressKnobProps : undefined}
+            focusVisibleStyle={item.onClick ? control.focusVisibleKnobProps : undefined}
+            onPress={item.onClick}
+            role={item.onClick ? "button" : undefined}
+          >
+            <Text {...knobProps.label} flex={1} numberOfLines={1}>
+              {item.label}
+            </Text>
+            {item.meta ? (
+              <Text {...knobProps.label} color={componentColors.text.muted}>
+                {item.meta}
+              </Text>
+            ) : null}
+          </XStack>
+        ))}
       </Card>
     </YStack>
   );
 }
 
+function DefaultWidget({ widget }: { widget: DashboardWidget }) {
+  switch (widget.type) {
+    case "kpi":
+      return widget.kpiConfig ? <KPICard config={widget.kpiConfig} /> : null;
+    case "chart":
+      return widget.chartConfig ? <ChartCard config={widget.chartConfig} /> : null;
+    case "progress":
+      return widget.progressConfig ? <ProgressCard config={widget.progressConfig} /> : null;
+    case "shortcut":
+      return widget.shortcutConfig ? <ShortcutCard config={widget.shortcutConfig} /> : null;
+    case "list":
+      return widget.listConfig ? <ListCard config={widget.listConfig} /> : null;
+    case "custom":
+      return widget.content ?? null;
+    default:
+      return null;
+  }
+}
+
 // ============================================================================
 // Main Dashboard Component
 // ============================================================================
@@ -361,8 +663,8 @@ export function ChartCard({ config, colors, headingLevel = 2, ...stackProps }: C
 /**
  * Generic dashboard component.
  *
- * Renders a grid of KPI cards and charts using native Tamagui `Card`.
- * Accepts data purely through props — no data fetching logic included.
+ * Renders a grid of KPI, progress, shortcut, list, and chart widgets using
+ * the house Card surface. Accepts data purely through props — no fetching.
  *
  * @example
  * ```tsx
@@ -392,16 +694,18 @@ export function Dashboard({
   const { t } = useTranslation();
   const emptyMessage = emptyMessageProp ?? t("No widgets to display");
   const { knobProps } = useResolvedKnobs();
-  const sz = knobProps.sizeToken;
-  const gap = gapProp ?? (sz === "$3" ? 12 : sz === "$5" ? 20 : 16);
-  const padding = paddingProp ?? (sz === "$3" ? 12 : sz === "$5" ? 20 : 16);
+  const gap = gapProp ?? 16;
 
   const header =
     title || description ? (
-      <YStack {...knobProps.gap} marginBottom="$2">
-        {title && <H3>{title}</H3>}
+      <YStack {...knobProps.gap}>
+        {title && (
+          <H3 margin={0} {...knobProps.heading}>
+            {title}
+          </H3>
+        )}
         {description && (
-          <Text fontSize={sz} color={componentColors.text.muted}>
+          <Text {...knobProps.body} {...knobProps.label} color={componentColors.text.muted}>
             {description}
           </Text>
         )}
@@ -410,8 +714,11 @@ export function Dashboard({
 
   return (
     <ScrollView>
-      <YStack padding={padding} gap={gap} {...stackProps}>
-        {/* Title stays mounted across async states (EUI: avoid header jump). */}
+      <YStack
+        {...(paddingProp != null ? { padding: paddingProp } : knobProps.panelPadding)}
+        gap={gap}
+        {...stackProps}
+      >
         {header}
         <AsyncBoundary
           loading={!error && isLoading && widgets.length === 0}
@@ -421,31 +728,37 @@ export function Dashboard({
           layout="dashboard"
           emptyTitle={emptyMessage}
         >
-          <XStack flexWrap="wrap" gap={gap} marginHorizontal={-gap / 2}>
+          <XStack
+            flexWrap="wrap"
+            gap={gap}
+            {...(isWeb
+              ? // CSS grid props are web-only and absent from the RN-flavored
+                // View type; Tamagui forwards them to the DOM (house Record cast).
+                ({
+                  display: "grid",
+                  gridTemplateColumns: `repeat(${columns}, minmax(0, 1fr))`,
+                } as Record<string, unknown>)
+              : { marginHorizontal: -gap / 2 })}
+          >
             {widgets.map((widget) => {
-              const span = widget.colSpan || 1;
+              const span = Math.min(widget.colSpan || 1, columns);
               const widthPercent = (span / columns) * 100;
               const adjustedWidth = `calc(${widthPercent}% - ${gap}px)`;
 
               return (
                 <YStack
                   key={widget.id}
-                  width={adjustedWidth as any}
-                  minWidth={200}
-                  marginHorizontal={gap / 2}
+                  data-dashboard-widget={widget.type}
+                  {...(isWeb
+                    ? { gridColumn: `span ${span}`, minWidth: 0, width: "100%" }
+                    : {
+                        width: adjustedWidth as any,
+                        minWidth: 200,
+                        marginHorizontal: gap / 2,
+                        marginBottom: gap,
+                      })}
                 >
-                  {renderWidget ? (
-                    renderWidget(widget)
-                  ) : (
-                    <>
-                      {widget.type === "kpi" && widget.kpiConfig && (
-                        <KPICard config={widget.kpiConfig} />
-                      )}
-                      {widget.type === "chart" && widget.chartConfig && (
-                        <ChartCard config={widget.chartConfig} />
-                      )}
-                    </>
-                  )}
+                  {renderWidget ? renderWidget(widget) : <DefaultWidget widget={widget} />}
                 </YStack>
               );
             })}