@multiplatform.one/components 5.0.27 → 6.0.0

package/src/views/Dashboard.tsx

@@ -0,0 +1,667 @@
+import { componentColors } from "../componentColors";
+import { useResolvedKnobs } from "@multiplatform.one/theme";
+import React, { useMemo, useCallback } from "react";
+import { Card, ScrollView, Text, XStack, YStack, type YStackProps, H3, H4 } from "tamagui";
+
+// ============================================================================
+// Types
+// ============================================================================
+
+/**
+ * Trend direction for KPI cards.
+ */
+export type TrendDirection = "up" | "down" | "neutral";
+
+/**
+ * Chart types supported by the dashboard.
+ */
+export type ChartType = "bar" | "line" | "pie";
+
+/**
+ * Data point for charts.
+ */
+export interface ChartDataPoint {
+  label: string;
+  value: number;
+  color?: string;
+}
+
+/**
+ * Configuration for a KPI card.
+ */
+export interface KPICardConfig {
+  id: string;
+  title: string;
+  value: number | string;
+  previousValue?: number;
+  trend?: TrendDirection;
+  trendValue?: string | number;
+  format?: "number" | "currency" | "percent";
+  currencySymbol?: string;
+  icon?: React.ReactNode;
+  color?: string;
+  onClick?: () => void;
+}
+
+/**
+ * Configuration for a chart.
+ */
+export interface ChartConfig {
+  id: string;
+  title: string;
+  type: ChartType;
+  data: ChartDataPoint[];
+  height?: number;
+  showLegend?: boolean;
+  showLabels?: boolean;
+  colors?: string[];
+}
+
+/**
+ * Dashboard widget configuration.
+ */
+export interface DashboardWidget {
+  id: string;
+  type: "kpi" | "chart" | "custom";
+  colSpan?: number;
+  rowSpan?: number;
+  kpiConfig?: KPICardConfig;
+  chartConfig?: ChartConfig;
+}
+
+/**
+ * Props for the generic Dashboard component.
+ */
+export interface DashboardProps extends Omit<YStackProps, "children"> {
+  /** Widget configurations */
+  widgets: DashboardWidget[];
+  /** Custom render function for widgets */
+  renderWidget?: (widget: DashboardWidget) => React.ReactNode;
+  /** Dashboard title */
+  title?: string;
+  /** Dashboard description */
+  description?: string;
+  /** Number of columns in the grid (default: 4) */
+  columns?: number;
+  /** Gap between widgets in pixels (default: 16) */
+  gap?: number;
+  /** Padding around the dashboard in pixels (default: 16) */
+  padding?: number;
+}
+
+// ============================================================================
+// Default Colors
+// ============================================================================
+
+const defaultChartColors = [
+  "var(--accentBackground)",
+  "var(--color7)",
+  "var(--color8)",
+  "var(--color9)",
+  "var(--color10)",
+  "var(--color11)",
+  "var(--color6)",
+  "var(--color5)",
+];
+
+// ============================================================================
+// KPI Card Component
+// ============================================================================
+
+export interface KPICardProps extends Omit<YStackProps, "children"> {
+  config: KPICardConfig;
+}
+
+/**
+ * KPI card component for displaying a single metric.
+ * Uses native Tamagui `Card` with `elevate`, `bordered`, and `size`.
+ */
+export function KPICard({ config, ...stackProps }: KPICardProps) {
+  const { knobProps } = useResolvedKnobs();
+  const formattedValue = useMemo(() => {
+    if (typeof config.value === "string") return config.value;
+
+    const num = config.value;
+    if (config.format === "currency") {
+      return `${config.currencySymbol || "$"}${num.toLocaleString()}`;
+    }
+    if (config.format === "percent") {
+      return `${num.toLocaleString()}%`;
+    }
+    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 trendSymbol = useMemo(() => {
+    if (config.trend === "up") return "↑";
+    if (config.trend === "down") return "↓";
+    return "—";
+  }, [config.trend]);
+
+  return (
+    <Card
+      size={knobProps.sizeToken}
+      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}
+      {...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>
+      </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 {config.previousValue.toLocaleString()}
+                </Text>
+              )}
+            </XStack>
+          )}
+        </YStack>
+      </Card.Footer>
+    </Card>
+  );
+}
+
+// ============================================================================
+// 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
+// ============================================================================
+
+export interface ChartCardProps extends Omit<YStackProps, "children"> {
+  config: ChartConfig;
+  colors?: string[];
+}
+
+/**
+ * Chart card component for displaying a chart with a title.
+ * Uses native Tamagui `Card` with `elevate`, `bordered`, and `size`.
+ */
+export function ChartCard({ config, colors = defaultChartColors, ...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]);
+
+  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>
+  );
+}
+
+// ============================================================================
+// Main Dashboard Component
+// ============================================================================
+
+/**
+ * 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.
+ *
+ * @example
+ * ```tsx
+ * <Dashboard
+ *   title="Sales Overview"
+ *   widgets={[
+ *     { id: 'revenue', type: 'kpi', kpiConfig: { ... } },
+ *     { id: 'chart', type: 'chart', chartConfig: { ... }, colSpan: 2 },
+ *   ]}
+ * />
+ * ```
+ */
+export function Dashboard({
+  widgets,
+  renderWidget,
+  title,
+  description,
+  columns = 4,
+  gap: gapProp,
+  padding: paddingProp,
+  ...stackProps
+}: DashboardProps) {
+  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);
+
+  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>
+        )}
+
+        {/* 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>
+      </YStack>
+    </ScrollView>
+  );
+}
+
+// ============================================================================
+// Utility Functions
+// ============================================================================
+
+/**
+ * Calculate trend direction based on current and previous values.
+ */
+export function calculateTrend(current: number, previous: number): TrendDirection {
+  if (current > previous) return "up";
+  if (current < previous) return "down";
+  return "neutral";
+}
+
+/**
+ * Calculate percentage change between two values.
+ */
+export function calculatePercentageChange(current: number, previous: number): string {
+  if (previous === 0) return current > 0 ? "+100%" : "0%";
+  const change = ((current - previous) / previous) * 100;
+  const sign = change >= 0 ? "+" : "";
+  return `${sign}${change.toFixed(1)}%`;
+}
+
+/**
+ * Aggregate data for charts.
+ */
+export function aggregateData<T>(
+  data: T[],
+  groupByField: keyof T,
+  valueField: keyof T,
+  operation: "count" | "sum" | "avg" = "count",
+): ChartDataPoint[] {
+  const groups: Record<string, number[]> = {};
+
+  for (const item of data) {
+    const key = String(item[groupByField]);
+    if (!groups[key]) groups[key] = [];
+
+    if (operation === "count") {
+      groups[key].push(1);
+    } else {
+      const value = Number(item[valueField]) || 0;
+      groups[key].push(value);
+    }
+  }
+
+  return Object.entries(groups).map(([label, values]) => {
+    let value: number;
+    switch (operation) {
+      case "count":
+        value = values.length;
+        break;
+      case "sum":
+        value = values.reduce((a, b) => a + b, 0);
+        break;
+      case "avg":
+        value = values.reduce((a, b) => a + b, 0) / values.length;
+        break;
+      default:
+        value = values.length;
+    }
+    return { label, value };
+  });
+}

package/src/views/ImageGrid.stories.tsx

@@ -0,0 +1,48 @@
+import type { Meta } from "@storybook/react-native-web-vite";
+import { Text, View } from "tamagui";
+import { ImageGrid } from "./ImageGrid";
+
+interface ImageItem {
+  id: string;
+  src: string;
+  alt: string;
+}
+
+const items: ImageItem[] = Array.from({ length: 12 }, (_, i) => ({
+  id: `img-${i + 1}`,
+  src: `https://picsum.photos/seed/${i + 1}/200/200`,
+  alt: `Sample image ${i + 1}`,
+}));
+
+const meta: Meta = {
+  title: "Components/ImageGrid",
+  parameters: {
+    status: { type: "stable" },
+  },
+};
+
+export default meta;
+
+export const Default = {
+  name: "Main",
+  render: () => (
+    <ImageGrid<ImageItem>
+      items={items}
+      columns={3}
+      getItemKey={(item) => item.id}
+      renderItem={(item) => (
+        <View
+          width="100%"
+          aspectRatio={1}
+          backgroundColor="$color3"
+          borderRadius="$3"
+          alignItems="center"
+          justifyContent="center"
+        >
+          <Text fontSize="$2">{item.alt}</Text>
+        </View>
+      )}
+      height={400}
+    />
+  ),
+};