@almadar/cli 0.3.2 → 0.3.3

package/shells/typescript-shell/packages/client/src/components/organisms/Split.tsx

@@ -0,0 +1,121 @@
+/**
+ * Split Component
+ * 
+ * A two-column layout with configurable ratios.
+ * Perfect for sidebar/content layouts or side-by-side comparisons.
+ */
+import React from 'react';
+import { cn } from '../../lib/cn';
+
+export type SplitRatio = '1:1' | '1:2' | '2:1' | '1:3' | '3:1' | '1:4' | '4:1' | '2:3' | '3:2';
+export type SplitGap = 'none' | 'sm' | 'md' | 'lg' | 'xl';
+
+export interface SplitProps {
+  /** Size ratio between left and right panels */
+  ratio?: SplitRatio;
+  /** Gap between panels */
+  gap?: SplitGap;
+  /** Reverse the order (right first) */
+  reverse?: boolean;
+  /** Stack vertically on mobile */
+  stackOnMobile?: boolean;
+  /** Breakpoint to switch from stacked to side-by-side */
+  stackBreakpoint?: 'sm' | 'md' | 'lg' | 'xl';
+  /** Align items vertically */
+  align?: 'start' | 'center' | 'end' | 'stretch';
+  /** Custom class name */
+  className?: string;
+  /** Left/first panel class name */
+  leftClassName?: string;
+  /** Right/second panel class name */
+  rightClassName?: string;
+  /** Exactly two children: [left, right] */
+  children: [React.ReactNode, React.ReactNode];
+}
+
+const gapStyles: Record<SplitGap, string> = {
+  none: 'gap-0',
+  sm: 'gap-2',
+  md: 'gap-4',
+  lg: 'gap-6',
+  xl: 'gap-8',
+};
+
+const alignStyles = {
+  start: 'items-start',
+  center: 'items-center',
+  end: 'items-end',
+  stretch: 'items-stretch',
+};
+
+// Tailwind classes for each ratio
+const ratioStyles: Record<SplitRatio, [string, string]> = {
+  '1:1': ['w-1/2', 'w-1/2'],
+  '1:2': ['w-1/3', 'w-2/3'],
+  '2:1': ['w-2/3', 'w-1/3'],
+  '1:3': ['w-1/4', 'w-3/4'],
+  '3:1': ['w-3/4', 'w-1/4'],
+  '1:4': ['w-1/5', 'w-4/5'],
+  '4:1': ['w-4/5', 'w-1/5'],
+  '2:3': ['w-2/5', 'w-3/5'],
+  '3:2': ['w-3/5', 'w-2/5'],
+};
+
+// Responsive variants for stacking
+const breakpointPrefixes = {
+  sm: 'sm:',
+  md: 'md:',
+  lg: 'lg:',
+  xl: 'xl:',
+};
+
+/**
+ * Split - Two-column layout with flexible ratios
+ */
+export const Split: React.FC<SplitProps> = ({
+  ratio = '1:1',
+  gap = 'md',
+  reverse = false,
+  stackOnMobile = true,
+  stackBreakpoint = 'md',
+  align = 'stretch',
+  className,
+  leftClassName,
+  rightClassName,
+  children,
+}) => {
+  const [left, right] = children;
+  const [leftRatio, rightRatio] = ratioStyles[ratio];
+  const bp = breakpointPrefixes[stackBreakpoint];
+
+  // Build responsive width classes
+  const leftWidth = stackOnMobile 
+    ? `w-full ${bp}${leftRatio}` 
+    : leftRatio;
+  const rightWidth = stackOnMobile 
+    ? `w-full ${bp}${rightRatio}` 
+    : rightRatio;
+
+  return (
+    <div
+      className={cn(
+        'flex',
+        stackOnMobile ? `flex-col ${bp}flex-row` : 'flex-row',
+        reverse && `${bp}flex-row-reverse`,
+        gapStyles[gap],
+        alignStyles[align],
+        className
+      )}
+    >
+      <div className={cn(leftWidth, leftClassName)}>
+        {left}
+      </div>
+      <div className={cn(rightWidth, rightClassName)}>
+        {right}
+      </div>
+    </div>
+  );
+};
+
+export default Split;
+

package/shells/typescript-shell/packages/client/src/components/organisms/StatCard.tsx

@@ -0,0 +1,360 @@
+import React from "react";
+import { cn } from "../../lib/cn";
+import { Card, Typography } from "../atoms";
+import { TrendingUp, TrendingDown, Minus, LucideIcon } from "lucide-react";
+import { useEntityList } from "../../hooks/useEntityData";
+import { useEventBus } from "../../hooks/useEventBus";
+
+/**
+ * Schema metric definition
+ * Supports both computed metrics (with field) and static metrics (with value)
+ */
+export interface MetricDefinition {
+  /** Field name for computed metrics (optional if value is provided) */
+  field?: string;
+  /** Display label */
+  label: string;
+  /** Static value for display (alternative to field-based computation) */
+  value?: string | number;
+  /** Icon name for display */
+  icon?: string;
+  /** Value format (e.g., 'currency', 'percent', 'number') */
+  format?: "currency" | "percent" | "number" | string;
+}
+
+export interface StatCardProps {
+  /** Main label */
+  label?: string;
+  /** Title (alias for label) */
+  title?: string;
+  /** Primary value - accepts array/unknown from generated code (will use first element or length) */
+  value?: string | number | (string | number | undefined)[] | unknown;
+  /** Previous value for comparison */
+  previousValue?: number;
+  /** Current value as number for trend calculation */
+  currentValue?: number;
+  /** Manual trend percentage (overrides calculation) */
+  trend?: number;
+  /** Trend direction (overrides calculation) */
+  trendDirection?: "up" | "down" | "neutral";
+  /** Whether up is good (green) or bad (red) */
+  invertTrend?: boolean;
+  /** Icon to display */
+  icon?: LucideIcon;
+  /** Icon background color */
+  iconBg?: string;
+  /** Icon color */
+  iconColor?: string;
+  /** Subtitle or description */
+  subtitle?: string;
+  /** Action button */
+  action?: {
+    label: string;
+    /** Event to dispatch via event bus (for trait state machine integration) */
+    event?: string;
+    /** Navigation URL - supports template interpolation */
+    navigatesTo?: string;
+    /** Legacy onClick callback */
+    onClick?: () => void;
+  };
+  className?: string;
+
+  // Schema-based props
+  /** Entity name for schema-driven stats */
+  entity?: string;
+  /** Metrics to display (schema format) - accepts readonly for compatibility with generated const arrays */
+  metrics?: readonly MetricDefinition[];
+  /** Data to calculate stats from - accepts readonly for compatibility with generated const arrays */
+  data?: readonly Record<string, unknown>[];
+  /** Loading state indicator */
+  isLoading?: boolean;
+  /** Error state */
+  error?: Error | null;
+}
+
+export const StatCard: React.FC<StatCardProps> = ({
+  label: propLabel,
+  title: propTitle,
+  value: propValue,
+  previousValue,
+  currentValue,
+  trend: manualTrend,
+  trendDirection: manualDirection,
+  invertTrend = false,
+  icon: Icon,
+  iconBg = "bg-[var(--color-muted)]",
+  iconColor = "text-[var(--color-foreground)]",
+  subtitle,
+  action,
+  className,
+  // Schema-based props
+  entity,
+  metrics,
+  data: externalData,
+  isLoading: externalLoading,
+  error: externalError,
+}) => {
+  // Use title as fallback for label
+  const labelToUse = propLabel ?? propTitle;
+  const eventBus = useEventBus();
+
+  // Handle action click with event bus integration
+  const handleActionClick = React.useCallback(() => {
+    if (action?.event) {
+      eventBus.emit(`UI:${action.event}`, { entity });
+    }
+    if (action?.onClick) {
+      action.onClick();
+    }
+  }, [action, eventBus, entity]);
+  // Auto-fetch data when entity is provided but no external data
+  const shouldAutoFetch = !!entity && !externalData && !!metrics;
+  const { data: fetchedData, isLoading: fetchLoading } = useEntityList(
+    shouldAutoFetch ? entity : undefined,
+    { skip: !shouldAutoFetch },
+  );
+
+  // Use external data if provided, otherwise use fetched data
+  const data = (externalData ?? fetchedData ?? []) as readonly Record<
+    string,
+    unknown
+  >[];
+
+  // Determine loading and error state
+  const isLoading = externalLoading ?? (shouldAutoFetch ? fetchLoading : false);
+  const error = externalError;
+
+  // Helper to compute a single metric value
+  const computeMetricValue = React.useCallback(
+    (metric: MetricDefinition, items: readonly Record<string, unknown>[]) => {
+      // If static value is provided, use it directly
+      if (metric.value !== undefined) {
+        return metric.value;
+      }
+
+      const field = metric.field;
+
+      // If no field specified, return 0
+      if (!field) {
+        return 0;
+      }
+
+      if (field === "count") {
+        return items.length;
+      }
+
+      // Handle explicit field:value format (e.g., "status:active")
+      if (field.includes(":")) {
+        const [fieldName, fieldValue] = field.split(":");
+        return items.filter((item) => item[fieldName] === fieldValue).length;
+      }
+
+      // Check if field exists on any item
+      const fieldExistsOnItems = items.some((item) => field in item);
+
+      if (fieldExistsOnItems) {
+        // Sum numeric field
+        return items.reduce((acc, item) => {
+          const val = item[field];
+          return acc + (typeof val === "number" ? val : 0);
+        }, 0);
+      }
+
+      // Auto-detect: field name might be a status value
+      // Check common status field names: status, state, phase
+      const statusFields = ["status", "state", "phase"];
+      for (const statusField of statusFields) {
+        const hasStatusField = items.some((item) => statusField in item);
+        if (hasStatusField) {
+          // Count items where statusField === field (the metric field is actually a value)
+          const count = items.filter(
+            (item) => item[statusField] === field,
+          ).length;
+          if (count > 0 || items.length === 0) {
+            return count;
+          }
+        }
+      }
+
+      // Fallback: return 0
+      return 0;
+    },
+    [],
+  );
+
+  // Schema-driven: calculate stats from data and metrics (supports multiple metrics)
+  const schemaStats = React.useMemo(() => {
+    if (!metrics || metrics.length === 0) return null;
+
+    // Compute all metrics
+    return metrics.map((metric) => ({
+      label: metric.label,
+      value: computeMetricValue(metric, data),
+      format: metric.format,
+    }));
+  }, [metrics, data, computeMetricValue]);
+
+  // If multiple metrics, render them as a row of stats
+  if (schemaStats && schemaStats.length > 1) {
+    if (isLoading) {
+      return (
+        <div
+          className={cn("grid gap-4", className)}
+          style={{ gridTemplateColumns: `repeat(${schemaStats.length}, 1fr)` }}
+        >
+          {schemaStats.map((_, idx) => (
+            <Card key={idx} className="p-4">
+              <div className="animate-pulse space-y-2">
+                <div className="h-3 bg-[var(--color-muted)] rounded w-16" />
+                <div className="h-6 bg-[var(--color-muted)] rounded w-12" />
+              </div>
+            </Card>
+          ))}
+        </div>
+      );
+    }
+
+    return (
+      <div
+        className={cn("grid gap-4", className)}
+        style={{ gridTemplateColumns: `repeat(${schemaStats.length}, 1fr)` }}
+      >
+        {schemaStats.map((stat, idx) => (
+          <Card key={idx} className="p-4">
+            <Typography variant="overline" color="secondary">
+              {stat.label}
+            </Typography>
+            <Typography variant="h4" className="text-xl">
+              {stat.value}
+            </Typography>
+          </Card>
+        ))}
+      </div>
+    );
+  }
+
+  // Use schema stats if available (single metric), otherwise use props
+  const label = schemaStats?.[0]?.label || labelToUse || entity || "Stat";
+  // Handle array values (use first element or array length)
+  const normalizedPropValue = Array.isArray(propValue)
+    ? (propValue[0] ?? propValue.length)
+    : propValue;
+  const value = schemaStats?.[0]?.value ?? normalizedPropValue ?? 0;
+  // Calculate trend if not provided manually
+  const calculatedTrend = useMemo(() => {
+    if (manualTrend !== undefined) return manualTrend;
+    if (previousValue === undefined || currentValue === undefined)
+      return undefined;
+    if (previousValue === 0) return currentValue > 0 ? 100 : 0;
+    return ((currentValue - previousValue) / previousValue) * 100;
+  }, [manualTrend, previousValue, currentValue]);
+
+  const trendDirection =
+    manualDirection ||
+    (calculatedTrend === undefined || calculatedTrend === 0
+      ? "neutral"
+      : calculatedTrend > 0
+        ? "up"
+        : "down");
+
+  const isPositive = invertTrend
+    ? trendDirection === "down"
+    : trendDirection === "up";
+
+  const TrendIcon =
+    trendDirection === "up"
+      ? TrendingUp
+      : trendDirection === "down"
+        ? TrendingDown
+        : Minus;
+
+  // Show error state
+  if (error) {
+    return (
+      <Card className={cn("p-6", className)}>
+        <div className="space-y-1">
+          <Typography variant="overline" color="secondary">
+            {label}
+          </Typography>
+          <Typography variant="small" color="error">
+            Error: {error.message}
+          </Typography>
+        </div>
+      </Card>
+    );
+  }
+
+  if (isLoading) {
+    return (
+      <Card className={cn("p-6", className)}>
+        <div className="animate-pulse space-y-3">
+          <div className="h-4 bg-[var(--color-muted)] rounded w-24" />
+          <div className="h-8 bg-[var(--color-muted)] rounded w-32" />
+          <div className="h-4 bg-[var(--color-muted)] rounded w-20" />
+        </div>
+      </Card>
+    );
+  }
+
+  return (
+    <Card className={cn("p-6", className)}>
+      <div className="flex items-start justify-between">
+        <div className="space-y-1">
+          <Typography variant="overline" color="secondary">
+            {label}
+          </Typography>
+          <Typography variant="h4" className="text-2xl">
+            {value}
+          </Typography>
+
+          {/* Trend indicator */}
+          {calculatedTrend !== undefined && (
+            <div className="flex items-center gap-1">
+              <div
+                className={cn(
+                  "flex items-center gap-0.5 text-sm font-bold",
+                  isPositive
+                    ? "text-[var(--color-success)]"
+                    : trendDirection === "neutral"
+                      ? "text-[var(--color-muted-foreground)]"
+                      : "text-[var(--color-error)]",
+                )}
+              >
+                <TrendIcon className="h-4 w-4" />
+                <span>{Math.abs(calculatedTrend).toFixed(1)}%</span>
+              </div>
+              <Typography variant="small" color="secondary" as="span">
+                vs last period
+              </Typography>
+            </div>
+          )}
+
+          {subtitle && !calculatedTrend && (
+            <Typography variant="small" color="secondary">
+              {subtitle}
+            </Typography>
+          )}
+        </div>
+
+        {Icon && (
+          <div className={cn("p-3", iconBg)}>
+            <Icon className={cn("h-6 w-6", iconColor)} />
+          </div>
+        )}
+      </div>
+
+      {action && (
+        <button
+          onClick={handleActionClick}
+          className="mt-4 text-sm font-bold text-[var(--color-foreground)] hover:underline"
+        >
+          {action.label} →
+        </button>
+      )}
+    </Card>
+  );
+};
+
+function useMemo<T>(factory: () => T, deps: unknown[]): T {
+  return React.useMemo(factory, deps);
+}