@fragments-sdk/cli 0.2.2

package/src/viewer/components/TokenStylePanel.tsx

@@ -0,0 +1,708 @@
+/**
+ * Token-Aware Style Comparison Panel
+ *
+ * Enhanced style comparison that shows:
+ * - Property, Figma value, Rendered value, Match status
+ * - Token names when values match design tokens
+ * - Hardcoded value warnings
+ * - Fix suggestions that can be copied
+ */
+
+import { useState, useEffect, useCallback } from "react";
+import clsx from "clsx";
+import type { DesignToken, EnhancedStyleDiffItem, TokenUsageSummary } from "../../core/index.js";
+import { CheckIcon, XIcon, LoadingIcon, FigmaIcon, WandIcon } from "./Icons.js";
+
+// Alias for semantic clarity
+const SyncingIcon = LoadingIcon;
+
+/**
+ * Maps CSS properties to expected token categories
+ * This prevents false positives like "height: 49px" matching "--top-bar-height"
+ */
+const PROPERTY_CATEGORY_MAP: Record<string, string[]> = {
+  // Color properties
+  color: ["color"],
+  backgroundColor: ["color"],
+  borderColor: ["color", "border"],
+  borderTopColor: ["color", "border"],
+  borderRightColor: ["color", "border"],
+  borderBottomColor: ["color", "border"],
+  borderLeftColor: ["color", "border"],
+  outlineColor: ["color"],
+  fill: ["color"],
+  stroke: ["color"],
+  caretColor: ["color"],
+  textDecorationColor: ["color"],
+  boxShadow: ["shadow", "color"],
+
+  // Spacing properties
+  margin: ["spacing"],
+  marginTop: ["spacing"],
+  marginRight: ["spacing"],
+  marginBottom: ["spacing"],
+  marginLeft: ["spacing"],
+  padding: ["spacing"],
+  paddingTop: ["spacing"],
+  paddingRight: ["spacing"],
+  paddingBottom: ["spacing"],
+  paddingLeft: ["spacing"],
+  gap: ["spacing"],
+  rowGap: ["spacing"],
+  columnGap: ["spacing"],
+
+  // Sizing properties (NOT spacing - heights shouldn't match spacing tokens)
+  width: ["sizing"],
+  height: ["sizing"],
+  minWidth: ["sizing"],
+  minHeight: ["sizing"],
+  maxWidth: ["sizing"],
+  maxHeight: ["sizing"],
+
+  // Border radius
+  borderRadius: ["radius"],
+  borderTopLeftRadius: ["radius"],
+  borderTopRightRadius: ["radius"],
+  borderBottomLeftRadius: ["radius"],
+  borderBottomRightRadius: ["radius"],
+
+  // Typography
+  fontSize: ["typography"],
+  fontWeight: ["typography"],
+  lineHeight: ["typography"],
+  letterSpacing: ["typography"],
+  fontFamily: ["typography"],
+
+  // Border
+  borderWidth: ["border"],
+  borderTopWidth: ["border"],
+  borderRightWidth: ["border"],
+  borderBottomWidth: ["border"],
+  borderLeftWidth: ["border"],
+
+  // Z-index
+  zIndex: ["z-index"],
+
+  // Animation
+  transitionDuration: ["animation"],
+  animationDuration: ["animation"],
+  transitionDelay: ["animation"],
+  animationDelay: ["animation"],
+};
+
+/**
+ * Get expected token categories for a CSS property
+ */
+function getExpectedCategories(property: string): string[] | null {
+  return PROPERTY_CATEGORY_MAP[property] || null;
+}
+
+interface TokenStylePanelProps {
+  figmaUrl: string;
+  figmaStyles: Record<string, string> | null;
+  renderedStyles: Record<string, string> | null;
+  figmaLoading: boolean;
+  figmaError?: string;
+  onFetchFigma: () => void;
+  onRefreshRendered: () => void;
+}
+
+interface TokenData {
+  tokens: DesignToken[];
+  meta?: {
+    totalTokens: number;
+    parseTimeMs: number;
+  };
+}
+
+// Module-level cache for tokens to avoid refetching on tab switches
+let cachedTokenData: TokenData | null = null;
+let cachedTokenError: string | null = null;
+let tokenFetchPromise: Promise<void> | null = null;
+
+export function TokenStylePanel({
+  figmaUrl,
+  figmaStyles,
+  renderedStyles,
+  figmaLoading,
+  figmaError,
+  onFetchFigma,
+  onRefreshRendered,
+}: TokenStylePanelProps) {
+  const [tokenData, setTokenData] = useState<TokenData | null>(null);
+  const [tokenError, setTokenError] = useState<string | null>(null);
+  const [tokenLoading, setTokenLoading] = useState(false);
+  const [copiedFix, setCopiedFix] = useState<string | null>(null);
+
+  // Fetch tokens on mount (with module-level caching)
+  useEffect(() => {
+    // Use cached data if available
+    if (cachedTokenData) {
+      setTokenData(cachedTokenData);
+      setTokenLoading(false);
+      return;
+    }
+    if (cachedTokenError) {
+      setTokenError(cachedTokenError);
+      setTokenLoading(false);
+      return;
+    }
+
+    // If a fetch is already in progress, wait for it
+    if (tokenFetchPromise) {
+      setTokenLoading(true);
+      tokenFetchPromise.then(() => {
+        setTokenData(cachedTokenData);
+        setTokenError(cachedTokenError);
+        setTokenLoading(false);
+      });
+      return;
+    }
+
+    const fetchTokens = async () => {
+      setTokenLoading(true);
+      setTokenError(null);
+
+      try {
+        const response = await fetch("/segments/tokens");
+
+        if (!response.ok) {
+          const data = await response.json();
+          if (data.error) {
+            cachedTokenError = data.suggestion || data.error;
+            setTokenError(cachedTokenError);
+          }
+          return;
+        }
+
+        const data = await response.json();
+        cachedTokenData = data;
+        setTokenData(data);
+      } catch (err) {
+        cachedTokenError = "Failed to fetch tokens";
+        setTokenError(cachedTokenError);
+      } finally {
+        setTokenLoading(false);
+        tokenFetchPromise = null;
+      }
+    };
+
+    tokenFetchPromise = fetchTokens();
+  }, []);
+
+  /**
+   * Find a token by value, filtered by property category to avoid false positives.
+   * Returns null if no appropriate token is found.
+   */
+  const tokenByValue = useCallback(
+    (value: string, property?: string): { token: DesignToken; confidence: "exact" | "value-only" } | null => {
+      if (!tokenData?.tokens) return null;
+
+      const normalized = normalizeValue(value);
+      const expectedCategories = property ? getExpectedCategories(property) : null;
+
+      // First pass: look for exact category match
+      for (const token of tokenData.tokens) {
+        const tokenNormalized = normalizeValue(token.resolvedValue);
+        if (tokenNormalized === normalized) {
+          // Check if this token's category matches what we expect for this property
+          if (expectedCategories && expectedCategories.includes(token.category)) {
+            return { token, confidence: "exact" };
+          }
+        }
+      }
+
+      // Second pass: if we have expectedCategories but found no match, don't return anything
+      // This prevents "height: 49px" from matching "--top-bar-height" (a sizing token when we want sizing)
+      if (expectedCategories) {
+        return null;
+      }
+
+      // Fallback: if we don't know the property type, return any matching token
+      // but mark it as "value-only" confidence
+      for (const token of tokenData.tokens) {
+        const tokenNormalized = normalizeValue(token.resolvedValue);
+        if (tokenNormalized === normalized) {
+          return { token, confidence: "value-only" };
+        }
+      }
+
+      return null;
+    },
+    [tokenData]
+  );
+
+  // Copy fix to clipboard
+  const copyFix = useCallback((property: string, tokenName: string) => {
+    const cssProperty = property.replace(/([A-Z])/g, "-$1").toLowerCase();
+    const code = `${cssProperty}: var(${tokenName});`;
+    navigator.clipboard.writeText(code);
+    setCopiedFix(property);
+    setTimeout(() => setCopiedFix(null), 2000);
+  }, []);
+
+  // Show loading state
+  if (figmaLoading) {
+    return (
+      <div className="flex items-center gap-2 text-tertiary p-4">
+        <SyncingIcon className="w-4 h-4 animate-spin" />
+        <span className="text-xs">Loading Figma styles...</span>
+      </div>
+    );
+  }
+
+  // Show error state
+  if (figmaError) {
+    return (
+      <div className="flex items-center gap-2 text-tertiary p-4">
+        <XIcon className="w-4 h-4 text-red-500" />
+        <span className="text-xs">{figmaError}</span>
+        <button
+          onClick={onFetchFigma}
+          className="text-xs text-[--color-accent] hover:underline ml-2"
+        >
+          Retry
+        </button>
+      </div>
+    );
+  }
+
+  // Show idle state
+  if (!figmaStyles) {
+    return (
+      <div className="flex items-center gap-2 text-tertiary p-4">
+        <FigmaIcon className="w-4 h-4" />
+        <span className="text-xs">Click to load style comparison</span>
+        <button
+          onClick={onFetchFigma}
+          className="text-xs text-[--color-accent] hover:underline ml-2"
+        >
+          Load
+        </button>
+      </div>
+    );
+  }
+
+  // Build comparison data
+  const figma = figmaStyles;
+  const rendered = renderedStyles || {};
+  const allProps = [...new Set([...Object.keys(figma), ...Object.keys(rendered)])];
+
+  const properties = allProps.map((prop) => {
+    const figmaValue = figma[prop] || "(not set)";
+    const renderedValue = rendered[prop] || "(not set)";
+    const match = compareValue(prop, figma[prop] || "", rendered[prop] || "");
+
+    // Find matching tokens (with category-aware filtering)
+    const figmaMatch = figma[prop] ? tokenByValue(figma[prop], prop) : null;
+    const renderedMatch = rendered[prop] ? tokenByValue(rendered[prop], prop) : null;
+
+    const figmaToken = figmaMatch?.token || null;
+    const renderedToken = renderedMatch?.token || null;
+    const figmaConfidence = figmaMatch?.confidence;
+    const renderedConfidence = renderedMatch?.confidence;
+
+    // Determine if hardcoded (Figma uses a token but rendered doesn't)
+    const isHardcoded = !!figmaToken && !renderedToken && figma[prop] !== rendered[prop];
+
+    return {
+      property: prop,
+      figma: figmaValue,
+      rendered: renderedValue,
+      match,
+      figmaToken,
+      renderedToken,
+      figmaConfidence,
+      renderedConfidence,
+      isHardcoded,
+    };
+  });
+
+  const differences = properties.filter((p) => !p.match).length;
+  const hardcodedCount = properties.filter((p) => p.isHardcoded).length;
+  const fixableCount = properties.filter((p) => p.isHardcoded && p.figmaToken).length;
+  const tokenUsageCount = properties.filter((p) => p.renderedToken).length;
+
+  // Calculate compliance
+  const compliancePercent =
+    properties.length > 0
+      ? Math.round(((tokenUsageCount + properties.filter((p) => p.match && !p.figmaToken).length) / properties.length) * 100)
+      : 100;
+
+  return (
+    <div className="overflow-x-auto p-4">
+      {/* Summary Header */}
+      <div className="flex items-center justify-between mb-3">
+        <div className="flex items-center gap-4">
+          <span className="text-xs font-medium text-primary">Style Comparison</span>
+
+          {/* Token info badge */}
+          {tokenData && (
+            <span className="text-xs text-tertiary">
+              {tokenData.meta?.totalTokens || tokenData.tokens.length} tokens loaded
+            </span>
+          )}
+          {tokenLoading && (
+            <span className="text-xs text-tertiary flex items-center gap-1">
+              <SyncingIcon className="w-3 h-3 animate-spin" />
+              Loading tokens...
+            </span>
+          )}
+          {tokenError && !tokenLoading && (
+            <span className="text-xs text-amber-600" title={tokenError}>
+              Tokens not configured
+            </span>
+          )}
+        </div>
+
+        <div className="flex items-center gap-3">
+          {/* Compliance badge */}
+          {tokenData && (
+            <span
+              className={clsx(
+                "text-xs font-medium px-2 py-0.5 rounded",
+                compliancePercent >= 80
+                  ? "bg-green-100 text-green-700 dark:bg-green-900 dark:text-green-300"
+                  : compliancePercent >= 50
+                  ? "bg-amber-100 text-amber-700 dark:bg-amber-900 dark:text-amber-300"
+                  : "bg-red-100 text-red-700 dark:bg-red-900 dark:text-red-300"
+              )}
+            >
+              {compliancePercent}% token compliance
+            </span>
+          )}
+
+          {/* Match summary */}
+          <span
+            className={clsx(
+              "text-xs font-medium",
+              differences === 0 ? "text-green-600" : "text-amber-600"
+            )}
+          >
+            {differences === 0 ? "All styles match" : `${differences} difference${differences !== 1 ? "s" : ""}`}
+          </span>
+
+          {/* Hardcoded warning */}
+          {hardcodedCount > 0 && (
+            <span className="text-xs font-medium text-red-600">
+              {hardcodedCount} hardcoded
+            </span>
+          )}
+        </div>
+      </div>
+
+      {/* Comparison Table */}
+      <table className="w-full text-xs">
+        <thead>
+          <tr className="border-b border-[--border-subtle]">
+            <th className="px-3 py-2 text-left text-tertiary font-medium">Property</th>
+            <th className="px-3 py-2 text-left text-tertiary font-medium">Figma</th>
+            {tokenData && (
+              <th className="px-3 py-2 text-left text-tertiary font-medium">Token</th>
+            )}
+            <th className="px-3 py-2 text-left text-tertiary font-medium">Rendered</th>
+            <th className="px-3 py-2 text-center text-tertiary font-medium w-12">Match</th>
+            {tokenData && fixableCount > 0 && (
+              <th className="px-3 py-2 text-center text-tertiary font-medium w-16">Fix</th>
+            )}
+          </tr>
+        </thead>
+        <tbody>
+          {properties.map((prop) => (
+            <tr
+              key={prop.property}
+              className={clsx(
+                "border-b border-[--border-subtle] last:border-b-0",
+                !prop.match && "bg-amber-50 dark:bg-amber-950/20",
+                prop.isHardcoded && "bg-red-50 dark:bg-red-950/20"
+              )}
+            >
+              <td className="px-3 py-2 font-mono text-primary">{prop.property}</td>
+              <td className="px-3 py-2">
+                <div className="flex items-center gap-2">
+                  {/* Color swatch */}
+                  {isColorProperty(prop.property) && prop.figma !== "(not set)" && (
+                    <ColorSwatch color={prop.figma} />
+                  )}
+                  <span className="font-mono text-secondary truncate max-w-[120px]" title={prop.figma}>
+                    {prop.figma}
+                  </span>
+                </div>
+              </td>
+              {tokenData && (
+                <td className="px-3 py-2">
+                  {prop.figmaToken ? (
+                    <TokenBadge token={prop.figmaToken} confidence={prop.figmaConfidence} />
+                  ) : prop.renderedToken ? (
+                    <TokenBadge token={prop.renderedToken} confidence={prop.renderedConfidence} />
+                  ) : (
+                    <span className="text-tertiary">-</span>
+                  )}
+                </td>
+              )}
+              <td className="px-3 py-2">
+                <div className="flex items-center gap-2">
+                  {/* Color swatch */}
+                  {isColorProperty(prop.property) && prop.rendered !== "(not set)" && (
+                    <ColorSwatch color={prop.rendered} />
+                  )}
+                  <span className="font-mono text-secondary truncate max-w-[120px]" title={prop.rendered}>
+                    {prop.rendered}
+                  </span>
+                  {/* Hardcoded badge */}
+                  {prop.isHardcoded && (
+                    <span className="text-[10px] px-1 py-0.5 bg-red-100 text-red-600 dark:bg-red-900 dark:text-red-300 rounded">
+                      HC
+                    </span>
+                  )}
+                </div>
+              </td>
+              <td className="px-3 py-2 text-center">
+                {prop.match ? (
+                  <CheckIcon className="w-4 h-4 text-green-600 mx-auto" />
+                ) : (
+                  <XIcon className="w-4 h-4 text-amber-600 mx-auto" />
+                )}
+              </td>
+              {tokenData && fixableCount > 0 && (
+                <td className="px-3 py-2 text-center">
+                  {prop.isHardcoded && prop.figmaToken && (
+                    <button
+                      onClick={() => copyFix(prop.property, prop.figmaToken!.name)}
+                      className={clsx(
+                        "p-1 rounded transition-colors",
+                        copiedFix === prop.property
+                          ? "bg-green-100 text-green-600"
+                          : "hover:bg-[--bg-hover] text-tertiary hover:text-primary"
+                      )}
+                      title={`Copy: ${prop.property.replace(/([A-Z])/g, "-$1").toLowerCase()}: var(${prop.figmaToken.name});`}
+                    >
+                      {copiedFix === prop.property ? (
+                        <CheckIcon className="w-3 h-3" />
+                      ) : (
+                        <WandIcon className="w-3 h-3" />
+                      )}
+                    </button>
+                  )}
+                </td>
+              )}
+            </tr>
+          ))}
+        </tbody>
+      </table>
+
+      {/* Hardcoded fixes summary */}
+      {hardcodedCount > 0 && tokenData && (
+        <div className="mt-4 p-3 bg-amber-50 dark:bg-amber-950/30 rounded-lg border border-amber-200 dark:border-amber-800">
+          <div className="flex items-start gap-2">
+            <WandIcon className="w-4 h-4 text-amber-600 mt-0.5" />
+            <div>
+              <p className="text-xs font-medium text-amber-800 dark:text-amber-200">
+                {hardcodedCount} hardcoded value{hardcodedCount !== 1 ? "s" : ""} detected
+              </p>
+              <p className="text-xs text-amber-700 dark:text-amber-300 mt-1">
+                These values should use design tokens for consistency and theming support.
+                Click the fix button to copy the token-based CSS.
+              </p>
+            </div>
+          </div>
+        </div>
+      )}
+    </div>
+  );
+}
+
+// ----- Helper Components -----
+
+/**
+ * Enhanced tooltip showing full token details on hover
+ */
+function TokenBadge({
+  token,
+  confidence,
+}: {
+  token: DesignToken;
+  confidence?: "exact" | "value-only";
+}) {
+  const [showTooltip, setShowTooltip] = useState(false);
+
+  return (
+    <div className="relative inline-block">
+      <span
+        className={clsx(
+          "font-mono text-xs cursor-help px-1.5 py-0.5 rounded",
+          confidence === "value-only"
+            ? "text-amber-600 dark:text-amber-400 bg-amber-50 dark:bg-amber-950/30"
+            : "text-purple-600 dark:text-purple-400 bg-purple-50 dark:bg-purple-950/30"
+        )}
+        onMouseEnter={() => setShowTooltip(true)}
+        onMouseLeave={() => setShowTooltip(false)}
+      >
+        {token.name}
+      </span>
+
+      {/* Enhanced tooltip */}
+      {showTooltip && (
+        <div
+          className="absolute z-50 left-0 top-full mt-1 p-3 bg-[--bg-primary] border border-[--border] rounded-lg shadow-lg min-w-[280px]"
+          style={{ maxWidth: "320px" }}
+        >
+          <div className="space-y-2 text-xs">
+            {/* Token name */}
+            <div>
+              <span className="text-tertiary">Token:</span>
+              <span className="ml-2 font-mono text-primary font-medium">{token.name}</span>
+            </div>
+
+            {/* Resolved value */}
+            <div className="flex items-center">
+              <span className="text-tertiary">Value:</span>
+              <span className="ml-2 font-mono text-secondary">{token.resolvedValue}</span>
+              {token.category === "color" && (
+                <ColorSwatch color={token.resolvedValue} />
+              )}
+            </div>
+
+            {/* Raw value (if different from resolved) */}
+            {token.rawValue !== token.resolvedValue && (
+              <div>
+                <span className="text-tertiary">Raw:</span>
+                <span className="ml-2 font-mono text-secondary">{token.rawValue}</span>
+              </div>
+            )}
+
+            {/* Category & Level */}
+            <div className="flex gap-4">
+              <div>
+                <span className="text-tertiary">Category:</span>
+                <span className="ml-2 text-secondary capitalize">{token.category}</span>
+              </div>
+              <div>
+                <span className="text-tertiary">Level:</span>
+                <span className="ml-2 text-secondary">
+                  {token.level === 1 ? "Base" : token.level === 2 ? "Semantic" : "Component"}
+                </span>
+              </div>
+            </div>
+
+            {/* Theme */}
+            <div>
+              <span className="text-tertiary">Theme:</span>
+              <span className="ml-2 text-secondary">{token.theme}</span>
+            </div>
+
+            {/* Reference chain (if has references) */}
+            {token.referenceChain.length > 1 && (
+              <div>
+                <span className="text-tertiary">References:</span>
+                <div className="mt-1 font-mono text-secondary text-[10px] space-y-0.5">
+                  {token.referenceChain.map((ref, i) => (
+                    <div key={ref} className="flex items-center">
+                      {i > 0 && <span className="mr-1 text-tertiary">→</span>}
+                      <span>{ref}</span>
+                    </div>
+                  ))}
+                </div>
+              </div>
+            )}
+
+            {/* Source file */}
+            <div className="pt-1 border-t border-[--border-subtle]">
+              <span className="text-tertiary">Source:</span>
+              <span className="ml-2 font-mono text-[10px] text-tertiary truncate">
+                {token.sourceFile.split("/").slice(-2).join("/")}
+                {token.lineNumber && `:${token.lineNumber}`}
+              </span>
+            </div>
+
+            {/* Confidence indicator */}
+            {confidence === "value-only" && (
+              <div className="pt-1 text-amber-600 dark:text-amber-400">
+                ⚠️ Value match only - verify this is the correct token
+              </div>
+            )}
+          </div>
+        </div>
+      )}
+    </div>
+  );
+}
+
+function ColorSwatch({ color }: { color: string }) {
+  return (
+    <div
+      className="w-4 h-4 rounded border border-[--border] flex-shrink-0 ml-1"
+      style={{ backgroundColor: color }}
+      title={color}
+    />
+  );
+}
+
+// ----- Helper Functions -----
+
+function isColorProperty(prop: string): boolean {
+  const colorProps = ["backgroundColor", "borderColor", "color", "fill", "stroke"];
+  return colorProps.includes(prop) || prop.toLowerCase().includes("color");
+}
+
+/**
+ * Normalize a CSS value for comparison.
+ * Handles colors (hex, rgb, rgba) and general values.
+ */
+function normalizeValue(value: string): string {
+  if (!value) return "";
+
+  const trimmed = value.toLowerCase().trim();
+
+  // Already normalized hex
+  if (trimmed.match(/^#[0-9a-f]{6}$/i)) {
+    return trimmed;
+  }
+
+  // Short hex -> long hex
+  const shortHex = trimmed.match(/^#([0-9a-f])([0-9a-f])([0-9a-f])$/i);
+  if (shortHex) {
+    return `#${shortHex[1]}${shortHex[1]}${shortHex[2]}${shortHex[2]}${shortHex[3]}${shortHex[3]}`;
+  }
+
+  // Parse hex
+  const hexMatch = trimmed.match(/^#([0-9a-f]{2})([0-9a-f]{2})([0-9a-f]{2})$/i);
+  if (hexMatch) {
+    return trimmed;
+  }
+
+  // Parse rgb/rgba
+  const rgbMatch = value.match(
+    /rgba?\(\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d+)\s*(?:,\s*[\d.]+)?\s*\)/
+  );
+  if (rgbMatch) {
+    const r = parseInt(rgbMatch[1], 10).toString(16).padStart(2, "0");
+    const g = parseInt(rgbMatch[2], 10).toString(16).padStart(2, "0");
+    const b = parseInt(rgbMatch[3], 10).toString(16).padStart(2, "0");
+    return `#${r}${g}${b}`;
+  }
+
+  return trimmed;
+}
+
+function compareValue(prop: string, figma: string, rendered: string): boolean {
+  if (figma === rendered) return true;
+  if (!figma || !rendered) return false;
+
+  // Color comparison
+  if (isColorProperty(prop)) {
+    return normalizeValue(figma) === normalizeValue(rendered);
+  }
+
+  // Numeric comparison with near-zero tolerance for floating point rounding only
+  // Using < 0.1 ensures 1px vs 2px shows as mismatch, while 1.0001px vs 1px matches
+  const figmaNum = parseFloat(figma);
+  const renderedNum = parseFloat(rendered);
+  if (!isNaN(figmaNum) && !isNaN(renderedNum)) {
+    return Math.abs(figmaNum - renderedNum) < 0.1;
+  }
+
+  return false;
+}
+
+export default TokenStylePanel;