@multiplatform.one/components 6.1.0 → 6.4.0

package/src/views/Dashboard.tsx

@@ -1,7 +1,32 @@
-import { componentColors } from "../componentColors";
+import { BarChart } from "../charts/BarChart";
+import { LineChart } from "../charts/LineChart";
+import { PieChart } from "../charts/PieChart";
+import { componentColors, sectionHeading } from "../componentColors";
+import { AsyncBoundary } from "../layouts/AsyncBoundary";
 import { useResolvedKnobs } from "@multiplatform.one/theme";
-import React, { useMemo, useCallback } from "react";
-import { Card, ScrollView, Text, XStack, YStack, type YStackProps, H3, H4 } from "tamagui";
+import React, { useMemo, type ReactNode } from "react";
+import { useTranslation } from "react-i18next";
+import {
+  Card,
+  ScrollView,
+  Text,
+  XStack,
+  YStack,
+  type YStackProps,
+  H2,
+  H3,
+  H4,
+  H5,
+  H6,
+} from "tamagui";
+
+/**
+ * LC-17 SECTION-HEADING-SCALE + DG-A11Y-02: card sub-titles read at the ONE
+ * shared 20px section scale and step through sequential heading levels. A
+ * chart/KPI card is a section under the page H1, so it defaults to level 2.
+ */
+const SECTION_HEADING_TAGS = { 2: H2, 3: H3, 4: H4, 5: H5, 6: H6 } as const;
+export type CardHeadingLevel = 2 | 3 | 4 | 5 | 6;
 
 // ============================================================================
 // Types
@@ -36,6 +61,17 @@ export interface KPICardConfig {
   previousValue?: number;
   trend?: TrendDirection;
   trendValue?: string | number;
+  /**
+   * Which trend direction is *good* (LC-36 TREND-SENTIMENT, Axiom 9 — the
+   * schema chooses the register). Trend COLOR is derived from `trend ×
+   * goodDirection`: an improving metric is `success`, a worsening one is
+   * `error`. `"none"` — and *omitted* — paint the trend neutral (direction
+   * without sentiment): a metric whose polarity the system doesn't know
+   * must not wear a verdict color, so a falling "Overdue Balance" is only
+   * painted red when the screen explicitly declares `goodDirection: "up"`,
+   * never by guess.
+   */
+  goodDirection?: "up" | "down" | "none";
   format?: "number" | "currency" | "percent";
   currencySymbol?: string;
   icon?: React.ReactNode;
@@ -87,23 +123,19 @@ export interface DashboardProps extends Omit<YStackProps, "children"> {
   gap?: number;
   /** Padding around the dashboard in pixels (default: 16) */
   padding?: number;
+  /** Whether dashboard data is loading (W9 / DG-ST-02). */
+  isLoading?: boolean;
+  /**
+   * Failed load (DG-ST-01 / W9). Wins over empty widgets; KPI/count chrome
+   * in `chrome` is suppressed on failure (DG-ST-04).
+   */
+  error?: boolean | string | Error | ReactNode | null;
+  /** Retry handler for the default error UI. */
+  onRetry?: () => void;
+  /** Message when widgets array is empty. */
+  emptyMessage?: string;
 }
 
-// ============================================================================
-// Default Colors
-// ============================================================================
-
-const defaultChartColors = [
-  "var(--accentBackground)",
-  "var(--color7)",
-  "var(--color8)",
-  "var(--color9)",
-  "var(--color10)",
-  "var(--color11)",
-  "var(--color6)",
-  "var(--color5)",
-];
-
 // ============================================================================
 // KPI Card Component
 // ============================================================================
@@ -112,6 +144,24 @@ export interface KPICardProps extends Omit<YStackProps, "children"> {
   config: KPICardConfig;
 }
 
+/**
+ * The one sentinel resolver for trend sentiment color (LC-36
+ * TREND-SENTIMENT): color encodes sentiment — `trend × goodDirection` —
+ * never direction alone. Undeclared or `"none"` sentiment renders the
+ * neutral muted tier; a metric whose polarity the system doesn't know
+ * must not wear a verdict color.
+ */
+export function resolveTrendColor(
+  trend: TrendDirection | undefined,
+  goodDirection: KPICardConfig["goodDirection"],
+): string {
+  if (!trend || trend === "neutral") return componentColors.text.muted;
+  if (!goodDirection || goodDirection === "none") return componentColors.text.muted;
+  return trend === goodDirection
+    ? componentColors.semantic.success
+    : componentColors.semantic.error;
+}
+
 /**
  * KPI card component for displaying a single metric.
  * Uses native Tamagui `Card` with `elevate`, `bordered`, and `size`.
@@ -131,11 +181,10 @@ export function KPICard({ config, ...stackProps }: KPICardProps) {
     return num.toLocaleString();
   }, [config.value, config.format, config.currencySymbol]);
 
-  const trendColor = useMemo(() => {
-    if (config.trend === "up") return componentColors.semantic.success;
-    if (config.trend === "down") return componentColors.semantic.error;
-    return componentColors.text.muted;
-  }, [config.trend]);
+  const trendColor = useMemo(
+    () => resolveTrendColor(config.trend, config.goodDirection),
+    [config.trend, config.goodDirection],
+  );
 
   const trendSymbol = useMemo(() => {
     if (config.trend === "up") return "↑";
@@ -146,6 +195,7 @@ export function KPICard({ config, ...stackProps }: KPICardProps) {
   return (
     <Card
       size={knobProps.sizeToken}
+      {...knobProps.borderRadius}
       elevation={knobProps.elevation}
       borderWidth={1}
       borderColor="$borderColor"
@@ -201,272 +251,6 @@ export function KPICard({ config, ...stackProps }: KPICardProps) {
   );
 }
 
-// ============================================================================
-// SVG Chart Components
-// ============================================================================
-
-interface ChartSVGProps {
-  config: ChartConfig;
-  colors: string[];
-}
-
-function BarChart({ config, colors }: ChartSVGProps) {
-  const { data, height = 200, showLabels = true } = config;
-  const maxValue = useMemo(() => Math.max(...data.map((d) => d.value), 1), [data]);
-
-  const labelHeight = showLabels ? 28 : 0;
-  const chartHeight = height - labelHeight;
-  const barWidth = 100 / Math.max(data.length, 1);
-  const padding = barWidth * 0.15;
-
-  return (
-    <YStack height={height} width="100%">
-      <YStack flex={1} width="100%">
-        <svg
-          width="100%"
-          height="100%"
-          viewBox={`0 0 100 ${chartHeight}`}
-          preserveAspectRatio="none"
-        >
-          {data.map((point, index) => {
-            const barHeight = (point.value / maxValue) * chartHeight;
-            const x = index * barWidth + padding;
-            const y = chartHeight - barHeight;
-            const color = point.color || colors[index % colors.length];
-            return (
-              <rect
-                key={point.label}
-                x={`${x}%`}
-                y={y}
-                width={`${barWidth - padding * 2}%`}
-                height={barHeight}
-                fill={color}
-                rx="2"
-              />
-            );
-          })}
-        </svg>
-      </YStack>
-      {showLabels && (
-        <XStack height={labelHeight} width="100%" alignItems="center">
-          {data.map((point) => (
-            <Text
-              key={point.label}
-              flex={1}
-              textAlign="center"
-              fontSize="$2"
-              color={componentColors.text.muted}
-              numberOfLines={1}
-            >
-              {point.label}
-            </Text>
-          ))}
-        </XStack>
-      )}
-    </YStack>
-  );
-}
-
-function LineChart({ config, colors }: ChartSVGProps) {
-  const { data, height = 200, showLabels = true } = config;
-  const maxValue = useMemo(() => Math.max(...data.map((d) => d.value), 1), [data]);
-
-  const labelHeight = showLabels ? 28 : 0;
-  const chartHeight = height - labelHeight;
-
-  const points = useMemo(() => {
-    if (data.length < 2) return "";
-    const xStep = 100 / (data.length - 1);
-    return data
-      .map((point, index) => {
-        const x = index * xStep;
-        const y = chartHeight - (point.value / maxValue) * chartHeight;
-        return `${x},${y}`;
-      })
-      .join(" ");
-  }, [data, maxValue, chartHeight]);
-
-  const areaPath = useMemo(() => {
-    if (data.length < 2) return "";
-    const xStep = 100 / (data.length - 1);
-    let path = `M 0,${chartHeight}`;
-    data.forEach((point, index) => {
-      const x = index * xStep;
-      const y = chartHeight - (point.value / maxValue) * chartHeight;
-      path += ` L ${x},${y}`;
-    });
-    path += ` L 100,${chartHeight} Z`;
-    return path;
-  }, [data, maxValue, chartHeight]);
-
-  const color = colors[0];
-
-  return (
-    <YStack height={height} width="100%">
-      <YStack flex={1} width="100%">
-        <svg
-          width="100%"
-          height="100%"
-          viewBox={`0 0 100 ${chartHeight}`}
-          preserveAspectRatio="none"
-        >
-          <path d={areaPath} fill={color} opacity="0.2" />
-          <polyline
-            points={points}
-            fill="none"
-            stroke={color}
-            strokeWidth="2"
-            vectorEffect="non-scaling-stroke"
-          />
-          {data.map((point, index) => {
-            const xStep = 100 / (data.length - 1);
-            const x = index * xStep;
-            const y = chartHeight - (point.value / maxValue) * chartHeight;
-            return (
-              <circle
-                key={point.label}
-                cx={x}
-                cy={y}
-                r="3"
-                fill={color}
-                vectorEffect="non-scaling-stroke"
-              />
-            );
-          })}
-        </svg>
-      </YStack>
-      {showLabels && (
-        <XStack height={labelHeight} width="100%" alignItems="center">
-          {data.map((point) => (
-            <Text
-              key={point.label}
-              flex={1}
-              textAlign="center"
-              fontSize="$2"
-              color={componentColors.text.muted}
-              numberOfLines={1}
-            >
-              {point.label}
-            </Text>
-          ))}
-        </XStack>
-      )}
-    </YStack>
-  );
-}
-
-function PieChart({ config, colors }: ChartSVGProps) {
-  const { knobProps } = useResolvedKnobs();
-  const { data, height = 200, showLegend = true } = config;
-
-  const total = useMemo(() => data.reduce((sum, d) => sum + d.value, 0) || 1, [data]);
-
-  const segments = useMemo(() => {
-    const result: Array<{
-      label: string;
-      value: number;
-      color: string;
-      startAngle: number;
-      endAngle: number;
-    }> = [];
-
-    let currentAngle = -90;
-    data.forEach((point, index) => {
-      const percentage = point.value / total;
-      const angle = percentage * 360;
-      result.push({
-        label: point.label,
-        value: point.value,
-        color: point.color || colors[index % colors.length],
-        startAngle: currentAngle,
-        endAngle: currentAngle + angle,
-      });
-      currentAngle += angle;
-    });
-
-    return result;
-  }, [data, total, colors]);
-
-  const describeArc = useCallback(
-    (cx: number, cy: number, radius: number, startAngle: number, endAngle: number) => {
-      const start = polarToCartesian(cx, cy, radius, endAngle);
-      const end = polarToCartesian(cx, cy, radius, startAngle);
-      const largeArcFlag = endAngle - startAngle <= 180 ? "0" : "1";
-      return [
-        "M",
-        cx,
-        cy,
-        "L",
-        start.x,
-        start.y,
-        "A",
-        radius,
-        radius,
-        0,
-        largeArcFlag,
-        0,
-        end.x,
-        end.y,
-        "Z",
-      ].join(" ");
-    },
-    [],
-  );
-
-  const size = Math.min(height, 200);
-  const radius = size * 0.35;
-  const cx = size / 2;
-  const cy = size / 2;
-
-  return (
-    <XStack height={height} width="100%" {...knobProps.gap}>
-      <YStack width={size} height={size} alignItems="center" justifyContent="center">
-        <svg width={size} height={size} viewBox={`0 0 ${size} ${size}`}>
-          {segments.map((segment) => (
-            <path
-              key={segment.label}
-              d={describeArc(cx, cy, radius, segment.startAngle, segment.endAngle)}
-              fill={segment.color}
-            />
-          ))}
-          <circle cx={cx} cy={cy} r={radius * 0.5} fill="var(--background)" />
-        </svg>
-      </YStack>
-
-      {showLegend && (
-        <ScrollView flex={1} maxHeight={height}>
-          <YStack gap="$2">
-            {segments.map((segment) => (
-              <XStack key={segment.label} gap="$2" alignItems="center">
-                <YStack
-                  width={12}
-                  height={12}
-                  borderRadius="$2"
-                  backgroundColor={segment.color as any}
-                />
-                <Text fontSize="$2" color={componentColors.text.muted} flex={1} numberOfLines={1}>
-                  {segment.label}
-                </Text>
-                <Text fontSize="$2" fontWeight="500">
-                  {segment.value.toLocaleString()}
-                </Text>
-              </XStack>
-            ))}
-          </YStack>
-        </ScrollView>
-      )}
-    </XStack>
-  );
-}
-
-function polarToCartesian(cx: number, cy: number, radius: number, angleInDegrees: number) {
-  const angleInRadians = ((angleInDegrees - 90) * Math.PI) / 180.0;
-  return {
-    x: cx + radius * Math.cos(angleInRadians),
-    y: cy + radius * Math.sin(angleInRadians),
-  };
-}
-
 // ============================================================================
 // Chart Card Component
 // ============================================================================
@@ -474,44 +258,85 @@ function polarToCartesian(cx: number, cy: number, radius: number, angleInDegrees
 export interface ChartCardProps extends Omit<YStackProps, "children"> {
   config: ChartConfig;
   colors?: string[];
+  /**
+   * Semantic heading level for the card title (DG-A11Y-02). Defaults to 2 —
+   * a card is a section under the page H1. Pass 3+ when nested so DOM heading
+   * levels step without skips. Visual scale is pinned by `sectionHeading`.
+   */
+  headingLevel?: CardHeadingLevel;
 }
 
 /**
  * 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
+ * share one x with flush siblings (PageSection got the same fix shape).
+ * Only the chart body earns the card's panelPadding inset (LC-39).
+ *
+ * All chart modes render the universal charts family (`../charts`) —
+ * chromeless plot surfaces (SF-CARD stays with this card wrapper) that
+ * resolve the canonical `useChartPalette()` themselves (LC-27):
+ * single-series bar/line marks paint the theme identity (accent, or the
+ * tint solid under a tinted theme); pie slices take the identity-led
+ * categorical palette. Explicit `config.colors` / per-point `color`
+ * values are data and pass through untouched (Axiom 11).
  */
-export function ChartCard({ config, colors = defaultChartColors, ...stackProps }: ChartCardProps) {
+export function ChartCard({ config, colors, headingLevel = 2, ...stackProps }: ChartCardProps) {
   const { knobProps } = useResolvedKnobs();
-  const chartColors = config.colors || colors;
-
-  const ChartComponent = useMemo(() => {
-    switch (config.type) {
-      case "bar":
-        return BarChart;
-      case "line":
-        return LineChart;
-      case "pie":
-        return PieChart;
-      default:
-        return BarChart;
-    }
-  }, [config.type]);
+  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 (
-    <Card
-      size={knobProps.sizeToken}
-      elevation={knobProps.elevation}
-      borderWidth={1}
-      borderColor="$borderColor"
-      {...stackProps}
-    >
-      <Card.Header {...knobProps.panelPadding}>
-        <H4>{config.title}</H4>
-      </Card.Header>
-      <Card.Footer {...knobProps.panelPadding}>
-        <ChartComponent config={config} colors={chartColors} />
-      </Card.Footer>
-    </Card>
+    <YStack {...knobProps.gap} {...stackProps}>
+      <HeadingTag margin={0} {...sectionHeading}>
+        {config.title}
+      </HeadingTag>
+      <Card
+        size={knobProps.sizeToken}
+        {...knobProps.borderRadius}
+        elevation={knobProps.elevation}
+        borderWidth={1}
+        borderColor="$borderColor"
+      >
+        <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>
+      </Card>
+    </YStack>
   );
 }
 
@@ -544,58 +369,74 @@ export function Dashboard({
   columns = 4,
   gap: gapProp,
   padding: paddingProp,
+  isLoading = false,
+  error = null,
+  onRetry,
+  emptyMessage: emptyMessageProp,
   ...stackProps
 }: DashboardProps) {
+  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 header =
+    title || description ? (
+      <YStack {...knobProps.gap} marginBottom="$2">
+        {title && <H3>{title}</H3>}
+        {description && (
+          <Text fontSize={sz} color={componentColors.text.muted}>
+            {description}
+          </Text>
+        )}
+      </YStack>
+    ) : null;
+
   return (
     <ScrollView>
       <YStack padding={padding} gap={gap} {...stackProps}>
-        {/* Header */}
-        {(title || description) && (
-          <YStack {...knobProps.gap} marginBottom="$2">
-            {title && <H3>{title}</H3>}
-            {description && (
-              <Text fontSize={sz} color={componentColors.text.muted}>
-                {description}
-              </Text>
-            )}
-          </YStack>
-        )}
+        {/* Title stays mounted across async states (EUI: avoid header jump). */}
+        {header}
+        <AsyncBoundary
+          loading={!error && isLoading && widgets.length === 0}
+          empty={!error && widgets.length === 0}
+          error={error}
+          onRetry={onRetry}
+          layout="dashboard"
+          emptyTitle={emptyMessage}
+        >
+          <XStack flexWrap="wrap" gap={gap} marginHorizontal={-gap / 2}>
+            {widgets.map((widget) => {
+              const span = widget.colSpan || 1;
+              const widthPercent = (span / columns) * 100;
+              const adjustedWidth = `calc(${widthPercent}% - ${gap}px)`;
 
-        {/* Widget Grid */}
-        <XStack flexWrap="wrap" gap={gap} marginHorizontal={-gap / 2}>
-          {widgets.map((widget) => {
-            const span = widget.colSpan || 1;
-            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}
-              >
-                {renderWidget ? (
-                  renderWidget(widget)
-                ) : (
-                  <>
-                    {widget.type === "kpi" && widget.kpiConfig && (
-                      <KPICard config={widget.kpiConfig} />
-                    )}
-                    {widget.type === "chart" && widget.chartConfig && (
-                      <ChartCard config={widget.chartConfig} />
-                    )}
-                  </>
-                )}
-              </YStack>
-            );
-          })}
-        </XStack>
+              return (
+                <YStack
+                  key={widget.id}
+                  width={adjustedWidth as any}
+                  minWidth={200}
+                  marginHorizontal={gap / 2}
+                >
+                  {renderWidget ? (
+                    renderWidget(widget)
+                  ) : (
+                    <>
+                      {widget.type === "kpi" && widget.kpiConfig && (
+                        <KPICard config={widget.kpiConfig} />
+                      )}
+                      {widget.type === "chart" && widget.chartConfig && (
+                        <ChartCard config={widget.chartConfig} />
+                      )}
+                    </>
+                  )}
+                </YStack>
+              );
+            })}
+          </XStack>
+        </AsyncBoundary>
       </YStack>
     </ScrollView>
   );