@fragments-sdk/viewer 0.2.1

package/src/components/HealthDashboard.tsx

@@ -0,0 +1,441 @@
+/**
+ * Dashboard Component
+ * Minimalist overview of design system coverage and components
+ * with enhanced accessibility insights and top issues aggregation
+ */
+
+import { useMemo, useState, useCallback, useEffect } from 'react';
+import type { FragmentDefinition } from '@fragments-sdk/core';
+import type { ImpactValue } from 'axe-core';
+import { Badge, Progress, Stack, Text, Card, EmptyState } from '@fragments-sdk/ui';
+import {
+  getAllA11yData,
+  getA11ySummary,
+  getAllA11yResults,
+  type ComponentA11yData,
+} from '../hooks/useA11yCache.js';
+import type { A11ySummary, CachedA11yResult } from '../types/a11y.js';
+
+/** Normalize category to Title Case for display */
+function titleCase(str: string): string {
+  return str.replace(/\b\w/g, (c) => c.toUpperCase());
+}
+
+/** Normalize category to a canonical key so "Form" and "Forms" merge into one group */
+function categoryKey(raw: string): string {
+  const tc = titleCase(raw.trim());
+  if (tc.length > 4 && tc.endsWith('s') && !tc.endsWith('ss')) {
+    return tc.slice(0, -1);
+  }
+  return tc;
+}
+
+interface HealthDashboardProps {
+  fragments: Array<{ path: string; fragment: FragmentDefinition }>;
+  onNavigate?: (componentName: string) => void;
+}
+
+interface CoverageMetric {
+  label: string;
+  count: number;
+  total: number;
+}
+
+interface A11yResults {
+  accessibleComponents: number;
+  totalComponents: number;
+  totalViolations: number;
+  totalCritical: number;
+  totalSerious: number;
+}
+
+interface ComponentA11yResult {
+  violations: number;
+  critical: number;
+  serious: number;
+  status: 'pending' | 'scanning' | 'pass' | 'warn' | 'fail';
+}
+
+interface ComponentRow {
+  name: string;
+  category: string;
+  variantCount: number;
+  status: string;
+}
+
+function calculateCoverage(
+  fragments: Array<{ path: string; fragment: FragmentDefinition }>
+): { metrics: CoverageMetric[]; components: ComponentRow[]; categoryCount: number } {
+  const total = fragments.length;
+
+  if (total === 0) {
+    return { metrics: [], components: [], categoryCount: 0 };
+  }
+
+  const categories = new Set<string>();
+  const components: ComponentRow[] = [];
+
+  let documented = 0;
+  let withVariants = 0;
+  let withUsage = 0;
+  let figmaLinked = 0;
+
+  for (const { fragment } of fragments) {
+    const cat = fragment.meta.category || 'uncategorized';
+    categories.add(categoryKey(cat));
+
+    if (fragment.meta.description && fragment.meta.description.trim().length > 10) {
+      documented++;
+    }
+
+    const variantCount = fragment.variants?.length || 0;
+    if (variantCount > 0) {
+      withVariants++;
+    }
+
+    if (fragment.usage && (fragment.usage.when.length > 0 || fragment.usage.whenNot.length > 0)) {
+      withUsage++;
+    }
+
+    if (fragment.meta.figma || fragment.variants?.some((v) => v.figma)) {
+      figmaLinked++;
+    }
+
+    components.push({
+      name: fragment.meta.name,
+      category: titleCase(cat),
+      variantCount,
+      status: fragment.meta.status || 'stable',
+    });
+  }
+
+  components.sort((a, b) => {
+    if (a.category !== b.category) return a.category.localeCompare(b.category);
+    return a.name.localeCompare(b.name);
+  });
+
+  const metrics: CoverageMetric[] = [
+    { label: 'Documented', count: documented, total },
+    { label: 'Variants', count: withVariants, total },
+    { label: 'Usage', count: withUsage, total },
+    { label: 'Figma', count: figmaLinked, total },
+  ];
+
+  return { metrics, components, categoryCount: categories.size };
+}
+
+function impactToBadgeVariant(impact: ImpactValue | undefined): 'error' | 'warning' | 'info' | 'default' {
+  switch (impact) {
+    case 'critical': return 'error';
+    case 'serious': return 'error';
+    case 'moderate': return 'warning';
+    case 'minor': return 'info';
+    default: return 'default';
+  }
+}
+
+export function HealthDashboard({ fragments, onNavigate }: HealthDashboardProps) {
+  const { metrics, components, categoryCount } = useMemo(
+    () => calculateCoverage(fragments),
+    [fragments]
+  );
+
+  const [componentA11y, setComponentA11y] = useState<Record<string, ComponentA11yResult>>({});
+  const [scanningComponents, setScanningComponents] = useState<Set<string>>(new Set());
+  const [a11ySummary, setA11ySummary] = useState<A11ySummary | null>(null);
+
+  const convertCacheToA11y = useCallback((cached: Record<string, ComponentA11yData>): Record<string, ComponentA11yResult> => {
+    const result: Record<string, ComponentA11yResult> = {};
+    for (const [name, data] of Object.entries(cached)) {
+      let status: ComponentA11yResult['status'] = 'pass';
+      if (data.critical > 0 || data.serious > 0) {
+        status = 'fail';
+      } else if (data.violations > 0) {
+        status = 'warn';
+      }
+      result[name] = {
+        violations: data.violations,
+        critical: data.critical,
+        serious: data.serious,
+        status,
+      };
+    }
+    return result;
+  }, []);
+
+  useEffect(() => {
+    const cached = getAllA11yData();
+    if (Object.keys(cached).length > 0) {
+      setComponentA11y(convertCacheToA11y(cached));
+      setA11ySummary(getA11ySummary());
+    }
+
+    const handleCacheUpdate = () => {
+      const updatedCache = getAllA11yData();
+      setComponentA11y(convertCacheToA11y(updatedCache));
+      setA11ySummary(getA11ySummary());
+    };
+
+    const handleCacheCleared = () => {
+      setComponentA11y({});
+      setA11ySummary(null);
+    };
+
+    const handleScanStarted = (event: CustomEvent<{ componentName: string }>) => {
+      setScanningComponents(prev => new Set(prev).add(event.detail.componentName));
+    };
+
+    const handleScanCompleted = (event: CustomEvent<{ componentName: string }>) => {
+      setScanningComponents(prev => {
+        const next = new Set(prev);
+        next.delete(event.detail.componentName);
+        return next;
+      });
+    };
+
+    window.addEventListener('a11y-cache-updated', handleCacheUpdate);
+    window.addEventListener('a11y-cache-cleared', handleCacheCleared);
+    window.addEventListener('a11y-scan-started', handleScanStarted as EventListener);
+    window.addEventListener('a11y-scan-completed', handleScanCompleted as EventListener);
+
+    return () => {
+      window.removeEventListener('a11y-cache-updated', handleCacheUpdate);
+      window.removeEventListener('a11y-cache-cleared', handleCacheCleared);
+      window.removeEventListener('a11y-scan-started', handleScanStarted as EventListener);
+      window.removeEventListener('a11y-scan-completed', handleScanCompleted as EventListener);
+    };
+  }, [convertCacheToA11y]);
+
+  const a11yResults = useMemo((): A11yResults | null => {
+    const scannedComponents = Object.keys(componentA11y).length;
+    if (scannedComponents === 0) {
+      return null;
+    }
+
+    const summary = a11ySummary || getA11ySummary();
+    return {
+      accessibleComponents: summary.accessibleComponents,
+      totalComponents: summary.totalComponents,
+      totalViolations:
+        summary.violationsByImpact.critical +
+        summary.violationsByImpact.serious +
+        summary.violationsByImpact.moderate +
+        summary.violationsByImpact.minor,
+      totalCritical: summary.violationsByImpact.critical,
+      totalSerious: summary.violationsByImpact.serious,
+    };
+  }, [componentA11y, a11ySummary]);
+
+  if (fragments.length === 0) {
+    return (
+      <EmptyState>
+        <EmptyState.Description>No components loaded</EmptyState.Description>
+      </EmptyState>
+    );
+  }
+
+  const a11yMetric: CoverageMetric | null = a11yResults
+    ? {
+        label: 'Accessible',
+        count: a11yResults.accessibleComponents,
+        total: a11yResults.totalComponents,
+      }
+    : null;
+
+  return (
+    <Stack direction="column" gap="lg" style={{ maxWidth: '672px' }}>
+      {/* Header */}
+      <div>
+        <Text as="h1" size="lg" weight="semibold">Fragments</Text>
+        <Text size="sm" color="tertiary" style={{ marginTop: '2px' }}>
+          {fragments.length} component{fragments.length !== 1 ? 's' : ''} · {categoryCount} categor{categoryCount !== 1 ? 'ies' : 'y'}
+        </Text>
+      </div>
+
+      {/* Coverage */}
+      <Card>
+        <Card.Body>
+          <Stack direction="column" gap="sm">
+            <Text as="h2" size="sm" weight="medium">Coverage</Text>
+            <Stack direction="column" gap="sm">
+              {metrics.map((metric) => (
+                <CoverageRow key={metric.label} metric={metric} />
+              ))}
+              {a11yMetric ? (
+                <CoverageRow metric={a11yMetric} />
+              ) : (
+                <Stack direction="row" align="center" gap="sm">
+                  <Text size="sm" color="secondary" style={{ width: '96px', flexShrink: 0 }}>Accessible</Text>
+                  <div style={{ flex: 1 }}>
+                    <Progress value={0} />
+                  </div>
+                  <Text size="xs" color="tertiary" style={{ width: '40px', textAlign: 'right', flexShrink: 0 }}>-</Text>
+                </Stack>
+              )}
+            </Stack>
+            <div style={{ paddingTop: '8px', borderTop: '1px solid var(--border-subtle)' }}>
+              {a11yResults ? (
+                a11yResults.totalViolations > 0 ? (
+                  <Text size="xs" color="tertiary">
+                    {a11yResults.totalViolations} violation{a11yResults.totalViolations !== 1 ? 's' : ''} found
+                    ({a11yResults.totalCritical} critical, {a11yResults.totalSerious} serious)
+                  </Text>
+                ) : (
+                  <Text size="xs" style={{ color: 'var(--color-success)' }}>
+                    All scanned components pass accessibility checks
+                  </Text>
+                )
+              ) : (
+                <Text size="xs" color="tertiary">
+                  Visit components to scan for accessibility issues
+                </Text>
+              )}
+            </div>
+          </Stack>
+        </Card.Body>
+      </Card>
+
+      {/* Top Issues Section */}
+      {a11ySummary && a11ySummary.topViolations.length > 0 && (
+        <Card>
+          <Card.Body>
+            <Stack direction="column" gap="sm">
+              <Text as="h2" size="sm" weight="medium">Top Issues</Text>
+              <Text size="xs" color="tertiary">
+                Common accessibility violations across your components
+              </Text>
+              <Stack direction="column" gap="sm">
+                {a11ySummary.topViolations.map((violation) => (
+                  <Stack
+                    key={violation.ruleId}
+                    direction="row"
+                    align="start"
+                    gap="sm"
+                    style={{
+                      padding: '8px',
+                      borderRadius: '4px',
+                      backgroundColor: 'var(--bg-secondary)',
+                      border: '1px solid var(--border-subtle)',
+                    }}
+                  >
+                    {violation.impact && (
+                      <Badge variant={impactToBadgeVariant(violation.impact)} size="sm">
+                        {violation.impact}
+                      </Badge>
+                    )}
+                    <div style={{ flex: 1, minWidth: 0 }}>
+                      <Text size="xs" style={{ overflow: 'hidden', textOverflow: 'ellipsis', whiteSpace: 'nowrap' }}>
+                        {violation.description}
+                      </Text>
+                      <Text size="xs" color="tertiary" style={{ marginTop: '2px' }}>
+                        <Text as="span" size="xs" font="mono">{violation.ruleId}</Text>
+                        {' · '}
+                        {violation.affectedComponents.length} component{violation.affectedComponents.length !== 1 ? 's' : ''}
+                      </Text>
+                    </div>
+                    <Text size="xs" color="tertiary" style={{ flexShrink: 0 }}>
+                      {violation.affectedComponents.length}
+                    </Text>
+                  </Stack>
+                ))}
+              </Stack>
+              {a11ySummary.topViolations.length >= 5 && (
+                <Text size="xs" color="tertiary" style={{ textAlign: 'center' }}>
+                  Showing top 5 issues
+                </Text>
+              )}
+            </Stack>
+          </Card.Body>
+        </Card>
+      )}
+
+      {/* Components Table */}
+      <div>
+        <Text as="h2" size="sm" weight="medium" style={{ marginBottom: '8px' }}>Components</Text>
+        <div style={{ borderRadius: '8px', border: '1px solid var(--border-subtle)', overflow: 'hidden' }}>
+          <table style={{ width: '100%', fontSize: '14px', borderCollapse: 'collapse' }}>
+            <thead>
+              <tr style={{ borderBottom: '1px solid var(--border-subtle)', backgroundColor: 'var(--bg-secondary)' }}>
+                <th style={{ textAlign: 'left', padding: '8px 12px', fontSize: '12px', fontWeight: 500, color: 'var(--text-tertiary)' }}>Name</th>
+                <th style={{ textAlign: 'left', padding: '8px 12px', fontSize: '12px', fontWeight: 500, color: 'var(--text-tertiary)' }}>Category</th>
+                <th style={{ textAlign: 'left', padding: '8px 12px', fontSize: '12px', fontWeight: 500, color: 'var(--text-tertiary)' }}>Variants</th>
+                <th style={{ textAlign: 'left', padding: '8px 12px', fontSize: '12px', fontWeight: 500, color: 'var(--text-tertiary)' }}>A11y</th>
+                <th style={{ textAlign: 'left', padding: '8px 12px', fontSize: '12px', fontWeight: 500, color: 'var(--text-tertiary)' }}>Status</th>
+              </tr>
+            </thead>
+            <tbody>
+              {components.map((component, index) => {
+                const a11yStatus = componentA11y[component.name];
+                const isScanning = scanningComponents.has(component.name);
+                return (
+                  <tr
+                    key={component.name}
+                    onClick={() => onNavigate?.(component.name)}
+                    style={{
+                      borderBottom: index < components.length - 1 ? '1px solid var(--border-subtle)' : 'none',
+                      cursor: 'pointer',
+                      transition: 'background-color 150ms',
+                    }}
+                    onMouseEnter={(e) => { (e.currentTarget as HTMLElement).style.backgroundColor = 'var(--bg-hover)'; }}
+                    onMouseLeave={(e) => { (e.currentTarget as HTMLElement).style.backgroundColor = ''; }}
+                  >
+                    <td style={{ padding: '8px 12px' }}><Text weight="medium" size="sm">{component.name}</Text></td>
+                    <td style={{ padding: '8px 12px' }}><Text size="sm" color="tertiary">{component.category}</Text></td>
+                    <td style={{ padding: '8px 12px' }}><Text size="sm" color="tertiary">{component.variantCount}</Text></td>
+                    <td style={{ padding: '8px 12px' }}>
+                      <A11yBadge result={a11yStatus} isScanning={isScanning} />
+                    </td>
+                    <td style={{ padding: '8px 12px' }}><Text size="sm" color="tertiary">{component.status}</Text></td>
+                  </tr>
+                );
+              })}
+            </tbody>
+          </table>
+        </div>
+      </div>
+    </Stack>
+  );
+}
+
+function CoverageRow({ metric }: { metric: CoverageMetric }) {
+  const percentage = metric.total > 0 ? Math.round((metric.count / metric.total) * 100) : 0;
+
+  return (
+    <Stack direction="row" align="center" gap="sm">
+      <Text size="sm" color="secondary" style={{ width: '96px', flexShrink: 0 }}>{metric.label}</Text>
+      <div style={{ flex: 1 }}>
+        <Progress value={percentage} />
+      </div>
+      <Text size="xs" color="tertiary" style={{ width: '40px', textAlign: 'right', flexShrink: 0 }}>
+        {metric.count}/{metric.total}
+      </Text>
+    </Stack>
+  );
+}
+
+function A11yBadge({ result, isScanning }: { result?: ComponentA11yResult; isScanning?: boolean }) {
+  if (isScanning) {
+    return <Badge variant="warning" size="sm">Scanning</Badge>;
+  }
+
+  if (!result || result.status === 'pending') {
+    return <Text size="xs" color="tertiary">-</Text>;
+  }
+
+  if (result.status === 'scanning') {
+    return <Badge variant="default" size="sm">...</Badge>;
+  }
+
+  if (result.status === 'pass') {
+    return <Badge variant="success" size="sm">Pass</Badge>;
+  }
+
+  if (result.status === 'fail') {
+    return <Badge variant="error" size="sm">{result.violations}</Badge>;
+  }
+
+  // warn status
+  return <Badge variant="warning" size="sm">{result.violations}</Badge>;
+}
+
+export default HealthDashboard;

package/src/components/HmrStatusIndicator.tsx

@@ -0,0 +1,61 @@
+import { Badge, Stack, Text } from '@fragments-sdk/ui';
+import { HMR_STATUS } from '../constants/ui.js';
+import { useHmrStatus } from '../hooks/useHmrStatus.js';
+import { WifiIcon, WifiOffIcon } from './Icons.js';
+
+interface HmrStatusIndicatorProps {
+  className?: string;
+}
+
+export function HmrStatusIndicator({ className }: HmrStatusIndicatorProps) {
+  const { status, lastUpdate } = useHmrStatus();
+  const config = HMR_STATUS[status];
+
+  const variant = status === 'connected' ? 'success' as const
+    : status === 'disconnected' ? 'error' as const
+    : 'warning' as const;
+
+  return (
+    <Stack direction="row" gap="xs" align="center" className={className}>
+      <Badge variant={variant} size="sm" dot>
+        <span style={{ display: 'flex', alignItems: 'center', gap: '4px' }}>
+          {status === 'disconnected' ? (
+            <WifiOffIcon style={{ width: '12px', height: '12px' }} />
+          ) : (
+            <WifiIcon style={{ width: '12px', height: '12px' }} />
+          )}
+        </span>
+      </Badge>
+
+      {lastUpdate && (
+        <Text
+          size="2xs"
+          color="tertiary"
+          truncate
+          style={{ maxWidth: '100px' }}
+          title={lastUpdate}
+        >
+          Updated: {lastUpdate.split('/').pop()}
+        </Text>
+      )}
+    </Stack>
+  );
+}
+
+/**
+ * Compact version that just shows the status dot.
+ */
+export function HmrStatusDot() {
+  const { status } = useHmrStatus();
+  const config = HMR_STATUS[status];
+
+  const variant = status === 'connected' ? 'success' as const
+    : status === 'disconnected' ? 'error' as const
+    : 'warning' as const;
+
+  return (
+    <Badge variant={variant} size="sm" dot title={config.label}>
+      <span />
+    </Badge>
+  );
+}