fix: resolve I18nLabel objects in MetricWidget and MetricCard to prevent React error #31

MetricWidget and MetricCard now use resolveLabel() to convert I18nLabel objects
({key, defaultValue}) to plain strings before rendering. This fixes the crash
when CRM dashboard metadata uses I18nLabel for trend.label.

Added 3 new tests verifying I18nLabel handling.

Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>

Author: Copilot

ROADMAP.md

@@ -1043,6 +1043,14 @@ The `FlowDesigner` is a canvas-based flow editor that bridges the gap between th
 
 **Tests:** Added 2 tests in `data-table-airtable-ux.test.tsx` verifying filler rows are skipped when pagination is off and still rendered when pagination is on. All 59 related tests pass.
 
+### Metric Widget I18nLabel Render Crash (February 2026)
+
+**Root Cause:** `MetricWidget` and `MetricCard` rendered I18nLabel objects (`{key, defaultValue}`) directly as React children. When CRM dashboard metadata used I18nLabel objects for `trend.label` (e.g. `{ key: 'crm.dashboard.trendLabel', defaultValue: 'vs last month' }`), React threw error #31 ("Objects are not valid as a React child").
+
+**Fix:** Added `resolveLabel()` helper to `MetricWidget.tsx` and `MetricCard.tsx` that converts I18nLabel objects to plain strings before rendering. Updated prop types to accept both string and I18nLabel objects for `label`, `description`, and `trend.label`.
+
+**Tests:** Added 3 new tests: 1 in `DashboardRenderer.widgetData.test.tsx` verifying metric widgets with I18nLabel trend labels render correctly, and 2 in `MetricCard.test.tsx` verifying I18nLabel resolution for title and description. All 159 dashboard tests pass.
+
 ---
 
 ## ⚠️ Risk Management

packages/plugin-dashboard/src/MetricCard.tsx

@@ -12,13 +12,20 @@ import { cn } from '@object-ui/components';
 import { ArrowDownIcon, ArrowUpIcon, MinusIcon } from 'lucide-react';
 import * as LucideIcons from 'lucide-react';
 
+/** Resolve an I18nLabel (string or {key, defaultValue}) to a plain string. */
+function resolveLabel(label: string | { key?: string; defaultValue?: string } | undefined): string | undefined {
+  if (label === undefined || label === null) return undefined;
+  if (typeof label === 'string') return label;
+  return label.defaultValue || label.key;
+}
+
 export interface MetricCardProps {
-  title?: string;
+  title?: string | { key?: string; defaultValue?: string };
   value: string | number;
   icon?: string;
   trend?: 'up' | 'down' | 'neutral';
   trendValue?: string;
-  description?: string;
+  description?: string | { key?: string; defaultValue?: string };
   className?: string;
 }
 
@@ -43,7 +50,7 @@ export const MetricCard: React.FC<MetricCardProps> = ({
     <Card className={cn("h-full", className)} {...props}>
       <CardHeader className="flex flex-row items-center justify-between space-y-0 pb-2">
         <CardTitle className="text-sm font-medium">
-          {title}
+          {resolveLabel(title)}
         </CardTitle>
         {IconComponent && (
           <IconComponent className="h-4 w-4 text-muted-foreground" />
@@ -66,7 +73,7 @@ export const MetricCard: React.FC<MetricCardProps> = ({
                 {trendValue}
               </span>
             )}
-            {description}
+            {resolveLabel(description)}
           </p>
         )}
       </CardContent>

packages/plugin-dashboard/src/MetricWidget.tsx

@@ -4,17 +4,24 @@ import { cn } from '@object-ui/components';
 import { ArrowDownIcon, ArrowUpIcon, MinusIcon } from 'lucide-react';
 import * as LucideIcons from 'lucide-react';
 
+/** Resolve an I18nLabel (string or {key, defaultValue}) to a plain string. */
+function resolveLabel(label: string | { key?: string; defaultValue?: string } | undefined): string | undefined {
+  if (label === undefined || label === null) return undefined;
+  if (typeof label === 'string') return label;
+  return label.defaultValue || label.key;
+}
+
 export interface MetricWidgetProps {
-  label: string;
+  label: string | { key?: string; defaultValue?: string };
   value: string | number;
   trend?: {
     value: number;
-    label?: string;
+    label?: string | { key?: string; defaultValue?: string };
     direction?: 'up' | 'down' | 'neutral';
   };
   icon?: React.ReactNode | string;
   className?: string;
-  description?: string;
+  description?: string | { key?: string; defaultValue?: string };
 }
 
 export const MetricWidget = ({
@@ -39,7 +46,7 @@ export const MetricWidget = ({
     <Card className={cn("h-full", className)} {...props}>
       <CardHeader className="flex flex-row items-center justify-between space-y-0 pb-2">
         <CardTitle className="text-sm font-medium">
-          {label}
+          {resolveLabel(label)}
         </CardTitle>
         {resolvedIcon && <div className="h-4 w-4 text-muted-foreground">{resolvedIcon}</div>}
       </CardHeader>
@@ -60,7 +67,7 @@ export const MetricWidget = ({
                 {trend.value}%
               </span>
             )}
-            {description || trend?.label}
+            {resolveLabel(description) || resolveLabel(trend?.label)}
           </p>
         )}
       </CardContent>

packages/plugin-dashboard/src/__tests__/DashboardRenderer.widgetData.test.tsx

@@ -224,6 +224,45 @@ describe('DashboardRenderer widget data extraction', () => {
     expect(container.textContent).toContain('5');
   });
 
+  it('should render metric widgets with I18nLabel objects without crashing', () => {
+    const schema = {
+      type: 'dashboard' as const,
+      name: 'test',
+      title: 'Test',
+      widgets: [
+        {
+          type: 'metric',
+          layout: { x: 0, y: 0, w: 1, h: 1 },
+          options: {
+            label: 'Total Revenue',
+            value: '$652,000',
+            trend: { value: 12.5, direction: 'up', label: { key: 'crm.dashboard.trendLabel', defaultValue: 'vs last month' } },
+            icon: 'DollarSign',
+          },
+        },
+        {
+          type: 'metric',
+          layout: { x: 1, y: 0, w: 1, h: 1 },
+          options: {
+            label: 'Active Deals',
+            value: '5',
+            trend: { value: 2.1, direction: 'down', label: { key: 'crm.dashboard.trendLabel', defaultValue: 'vs last month' } },
+            icon: 'Briefcase',
+          },
+        },
+      ],
+    } as any;
+
+    const { container } = render(<DashboardRenderer schema={schema} />);
+
+    // Should resolve I18nLabel objects to their defaultValue strings
+    expect(container.textContent).toContain('Total Revenue');
+    expect(container.textContent).toContain('$652,000');
+    expect(container.textContent).toContain('vs last month');
+    expect(container.textContent).toContain('Active Deals');
+    expect(container.textContent).toContain('5');
+  });
+
   it('should assign unique keys to widgets without id or title', () => {
     const schema = {
       type: 'dashboard' as const,

packages/plugin-dashboard/src/__tests__/MetricCard.test.tsx

@@ -56,4 +56,27 @@ describe('MetricCard', () => {
     expect(screen.getByText('Count')).toBeInTheDocument();
     expect(screen.getByText('1234')).toBeInTheDocument();
   });
+
+  it('should resolve I18nLabel objects for title', () => {
+    render(
+      <MetricCard
+        title={{ key: 'crm.dashboard.widgets.totalRevenue', defaultValue: 'Total Revenue' } as any}
+        value="$45,231"
+      />
+    );
+    
+    expect(screen.getByText('Total Revenue')).toBeInTheDocument();
+  });
+
+  it('should resolve I18nLabel objects for description', () => {
+    render(
+      <MetricCard
+        title="Revenue"
+        value="$45,231"
+        description={{ key: 'crm.dashboard.trendLabel', defaultValue: 'vs last month' } as any}
+      />
+    );
+    
+    expect(screen.getByText('vs last month')).toBeInTheDocument();
+  });
 });