@fragments-sdk/cli 0.2.2

package/src/viewer/components/UsageSection.tsx

@@ -0,0 +1,95 @@
+import type { SegmentUsage } from '../../core/index.js';
+import { CheckIcon, XIcon, AccessibilityIcon } from './Icons.js';
+
+interface UsageSectionProps {
+  usage: SegmentUsage;
+}
+
+export function UsageSection({ usage }: UsageSectionProps) {
+  const hasWhen = usage.when && usage.when.length > 0;
+  const hasWhenNot = usage.whenNot && usage.whenNot.length > 0;
+  const hasGuidelines = usage.guidelines && usage.guidelines.length > 0;
+  const hasAccessibility = usage.accessibility && usage.accessibility.length > 0;
+
+  if (!hasWhen && !hasWhenNot && !hasGuidelines && !hasAccessibility) {
+    return null;
+  }
+
+  return (
+    <section id="usage" className="scroll-mt-24">
+      <h2 className="text-base font-semibold text-primary mb-5">Usage</h2>
+
+      {/* When to use / When not to use */}
+      {(hasWhen || hasWhenNot) && (
+        <div className="grid md:grid-cols-2 gap-8 mb-8">
+          {hasWhen && (
+            <div className="p-4 rounded-xl bg-[--color-success-bg] border border-[--color-success]/20">
+              <h3 className="text-[13px] font-medium text-[--color-success] mb-3 flex items-center gap-2">
+                <CheckIcon className="w-4 h-4" />
+                When to use
+              </h3>
+              <ul className="space-y-2">
+                {usage.when!.map((item, index) => (
+                  <li key={index} className="text-[13px] text-primary leading-relaxed flex items-start gap-2">
+                    <span className="text-[--color-success] mt-1.5 text-xs">•</span>
+                    <span>{item}</span>
+                  </li>
+                ))}
+              </ul>
+            </div>
+          )}
+
+          {hasWhenNot && (
+            <div className="p-4 rounded-xl bg-[--color-danger-bg] border border-[--color-danger]/20">
+              <h3 className="text-[13px] font-medium text-[--color-danger] mb-3 flex items-center gap-2">
+                <XIcon className="w-4 h-4" />
+                When not to use
+              </h3>
+              <ul className="space-y-2">
+                {usage.whenNot!.map((item, index) => (
+                  <li key={index} className="text-[13px] text-primary leading-relaxed flex items-start gap-2">
+                    <span className="text-[--color-danger] mt-1.5 text-xs">•</span>
+                    <span>{item}</span>
+                  </li>
+                ))}
+              </ul>
+            </div>
+          )}
+        </div>
+      )}
+
+      {/* Guidelines */}
+      {hasGuidelines && (
+        <div className="mb-6">
+          <h3 className="text-[13px] font-medium text-primary mb-3">Guidelines</h3>
+          <ul className="space-y-2">
+            {usage.guidelines!.map((item, index) => (
+              <li key={index} className="text-[13px] text-secondary leading-relaxed flex items-start gap-2">
+                <span className="text-[--color-accent] mt-1.5 text-xs">•</span>
+                <span>{item}</span>
+              </li>
+            ))}
+          </ul>
+        </div>
+      )}
+
+      {/* Accessibility */}
+      {hasAccessibility && (
+        <div className="p-4 rounded-xl border border-[--border] bg-[--bg-secondary]">
+          <h3 className="text-[13px] font-medium text-primary mb-3 flex items-center gap-2">
+            <AccessibilityIcon className="w-4 h-4 text-secondary" />
+            Accessibility
+          </h3>
+          <ul className="space-y-2">
+            {usage.accessibility!.map((item, index) => (
+              <li key={index} className="text-[13px] text-secondary leading-relaxed flex items-start gap-2">
+                <span className="text-tertiary mt-1.5 text-xs">•</span>
+                <span>{item}</span>
+              </li>
+            ))}
+          </ul>
+        </div>
+      )}
+    </section>
+  );
+}

package/src/viewer/components/VariantMatrix.tsx

@@ -0,0 +1,350 @@
+// @ts-nocheck
+/**
+ * Variant Matrix View - Display all variants in a grid
+ *
+ * Shows all variants of a component simultaneously, making it easy to:
+ * - Compare states/variants at a glance
+ * - Spot visual inconsistencies
+ * - Review all component states quickly
+ *
+ * Uses virtualization to only render visible variants for better performance.
+ */
+
+import { useState, useMemo, useRef, useCallback } from "react";
+import { useVirtualizer } from "@tanstack/react-virtual";
+import clsx from "clsx";
+import type { SegmentVariant } from "../../core/index.js";
+import { ErrorBoundary } from "./ErrorBoundary.js";
+import { StoryRenderer, LoaderIndicator } from "./StoryRenderer.js";
+import { IsolatedPreviewFrame } from "./IsolatedPreviewFrame.js";
+import { ChevronDownIcon } from "./Icons.js";
+import { getBackgroundStyle, type BackgroundOption } from "./PreviewToolbar.js";
+
+interface VariantMatrixProps {
+  /** All variants to display */
+  variants: SegmentVariant[];
+  /** Component name for error display */
+  componentName: string;
+  /** Segment path for iframe rendering */
+  segmentPath: string;
+  /** Current zoom level */
+  zoom: number;
+  /** Preview theme */
+  previewTheme: "light" | "dark";
+  /** Background option */
+  background: BackgroundOption;
+  /** Whether to use iframe isolation */
+  useIframeIsolation?: boolean;
+  /** Callback when a variant is clicked to focus on it */
+  onSelectVariant?: (index: number) => void;
+}
+
+type GridSize = "small" | "medium" | "large";
+
+interface GridConfig {
+  cols: string;
+  minHeight: string;
+  heightPx: number; // For virtualization
+  scale: number;
+  colCount: number; // Default column count for virtualization
+}
+
+const GRID_SIZES: Record<GridSize, GridConfig> = {
+  small: { cols: "grid-cols-4 lg:grid-cols-5 xl:grid-cols-6", minHeight: "150px", heightPx: 150, scale: 0.5, colCount: 4 },
+  medium: { cols: "grid-cols-2 lg:grid-cols-3 xl:grid-cols-4", minHeight: "200px", heightPx: 200, scale: 0.75, colCount: 3 },
+  large: { cols: "grid-cols-1 lg:grid-cols-2 xl:grid-cols-3", minHeight: "300px", heightPx: 300, scale: 1, colCount: 2 },
+};
+
+/** Threshold for enabling virtualization */
+const VIRTUALIZATION_THRESHOLD = 12;
+
+export function VariantMatrix({
+  variants,
+  componentName,
+  segmentPath,
+  zoom,
+  previewTheme,
+  background,
+  useIframeIsolation = true,
+  onSelectVariant,
+}: VariantMatrixProps) {
+  const [gridSize, setGridSize] = useState<GridSize>("medium");
+  const [hoveredIndex, setHoveredIndex] = useState<number | null>(null);
+  const scrollRef = useRef<HTMLDivElement>(null);
+
+  const gridConfig = GRID_SIZES[gridSize];
+  const effectiveScale = (zoom / 100) * gridConfig.scale;
+
+  // Determine if we should use virtualization
+  const useVirtualization = variants.length > VIRTUALIZATION_THRESHOLD;
+
+  // Calculate number of rows for virtualization
+  const columns = gridConfig.colCount;
+  const rowCount = Math.ceil(variants.length / columns);
+
+  // Row height includes card height + gap
+  const rowHeight = gridConfig.heightPx + 16; // 16px gap
+
+  const rowVirtualizer = useVirtualizer({
+    count: rowCount,
+    getScrollElement: () => scrollRef.current,
+    estimateSize: () => rowHeight,
+    overscan: 2, // Render 2 extra rows above/below for smooth scrolling
+  });
+
+  if (variants.length === 0) {
+    return (
+      <div className="flex items-center justify-center h-full text-gray-500 dark:text-gray-400">
+        No variants to display
+      </div>
+    );
+  }
+
+  return (
+    <div className="h-full flex flex-col">
+      {/* Toolbar */}
+      <div className="flex-shrink-0 px-4 py-2 border-b border-[--border] bg-[--bg-secondary] flex items-center justify-between">
+        <div className="text-sm text-secondary">
+          {variants.length} variant{variants.length !== 1 ? "s" : ""}
+          {useVirtualization && (
+            <span className="ml-2 text-xs text-tertiary">(virtualized)</span>
+          )}
+        </div>
+        <div className="flex items-center gap-2">
+          <span className="text-xs text-tertiary">Grid size:</span>
+          <div className="flex rounded-md border border-[--border] overflow-hidden">
+            {(["small", "medium", "large"] as GridSize[]).map((size) => (
+              <button
+                key={size}
+                onClick={() => setGridSize(size)}
+                className={clsx(
+                  "px-2 py-1 text-xs capitalize transition-colors",
+                  gridSize === size
+                    ? "bg-[--bg-hover] text-primary"
+                    : "text-tertiary hover:text-secondary hover:bg-[--bg-hover]"
+                )}
+              >
+                {size}
+              </button>
+            ))}
+          </div>
+        </div>
+      </div>
+
+      {/* Grid - Virtualized or Regular */}
+      {useVirtualization ? (
+        <div ref={scrollRef} className="flex-1 overflow-auto p-4">
+          <div
+            style={{
+              height: `${rowVirtualizer.getTotalSize()}px`,
+              width: "100%",
+              position: "relative",
+            }}
+          >
+            {rowVirtualizer.getVirtualItems().map((virtualRow) => {
+              const startIndex = virtualRow.index * columns;
+              const rowVariants = variants.slice(startIndex, startIndex + columns);
+
+              return (
+                <div
+                  key={virtualRow.key}
+                  style={{
+                    position: "absolute",
+                    top: 0,
+                    left: 0,
+                    width: "100%",
+                    height: `${virtualRow.size}px`,
+                    transform: `translateY(${virtualRow.start}px)`,
+                  }}
+                >
+                  <div className={clsx("grid gap-4", gridConfig.cols)} style={{ height: gridConfig.minHeight }}>
+                    {rowVariants.map((variant, colIndex) => {
+                      const index = startIndex + colIndex;
+                      return (
+                        <VariantCard
+                          key={variant.name}
+                          variant={variant}
+                          index={index}
+                          componentName={componentName}
+                          segmentPath={segmentPath}
+                          scale={effectiveScale}
+                          minHeight={gridConfig.minHeight}
+                          previewTheme={previewTheme}
+                          background={background}
+                          useIframeIsolation={useIframeIsolation}
+                          isHovered={hoveredIndex === index}
+                          onHover={() => setHoveredIndex(index)}
+                          onLeave={() => setHoveredIndex(null)}
+                          onClick={() => onSelectVariant?.(index)}
+                        />
+                      );
+                    })}
+                  </div>
+                </div>
+              );
+            })}
+          </div>
+        </div>
+      ) : (
+        <div className="flex-1 overflow-auto p-4">
+          <div className={clsx("grid gap-4", gridConfig.cols)}>
+            {variants.map((variant, index) => (
+              <VariantCard
+                key={variant.name}
+                variant={variant}
+                index={index}
+                componentName={componentName}
+                segmentPath={segmentPath}
+                scale={effectiveScale}
+                minHeight={gridConfig.minHeight}
+                previewTheme={previewTheme}
+                background={background}
+                useIframeIsolation={useIframeIsolation}
+                isHovered={hoveredIndex === index}
+                onHover={() => setHoveredIndex(index)}
+                onLeave={() => setHoveredIndex(null)}
+                onClick={() => onSelectVariant?.(index)}
+              />
+            ))}
+          </div>
+        </div>
+      )}
+    </div>
+  );
+}
+
+interface VariantCardProps {
+  variant: SegmentVariant;
+  index: number;
+  componentName: string;
+  segmentPath: string;
+  scale: number;
+  minHeight: string;
+  previewTheme: "light" | "dark";
+  background: BackgroundOption;
+  useIframeIsolation: boolean;
+  isHovered: boolean;
+  onHover: () => void;
+  onLeave: () => void;
+  onClick: () => void;
+}
+
+function VariantCard({
+  variant,
+  index,
+  componentName,
+  segmentPath,
+  scale,
+  minHeight,
+  previewTheme,
+  background,
+  useIframeIsolation,
+  isHovered,
+  onHover,
+  onLeave,
+  onClick,
+}: VariantCardProps) {
+  const backgroundStyle = getBackgroundStyle(background);
+
+  return (
+    <div
+      className={clsx(
+        "group relative rounded-lg border overflow-hidden transition-all cursor-pointer",
+        isHovered
+          ? "border-blue-500 shadow-lg ring-2 ring-blue-500/20"
+          : "border-[--border] hover:border-blue-300 dark:hover:border-blue-700"
+      )}
+      style={{ minHeight }}
+      onMouseEnter={onHover}
+      onMouseLeave={onLeave}
+      onClick={onClick}
+    >
+      {/* Header */}
+      <div className="absolute top-0 left-0 right-0 z-10 px-2 py-1 bg-gradient-to-b from-black/60 to-transparent">
+        <div className="flex items-center justify-between">
+          <span className="text-xs font-medium text-white truncate">
+            {variant.name}
+          </span>
+          <span className="text-[10px] text-white/70">
+            #{index + 1}
+          </span>
+        </div>
+      </div>
+
+      {/* Click to view overlay */}
+      <div
+        className={clsx(
+          "absolute inset-0 z-10 flex items-center justify-center bg-black/40 transition-opacity",
+          isHovered ? "opacity-100" : "opacity-0"
+        )}
+      >
+        <span className="px-3 py-1.5 bg-blue-600 text-white text-xs font-medium rounded-full shadow-lg">
+          Click to focus
+        </span>
+      </div>
+
+      {/* Preview content */}
+      <div
+        className="h-full w-full overflow-hidden flex items-center justify-center"
+        data-theme={previewTheme}
+        style={backgroundStyle}
+      >
+        {useIframeIsolation ? (
+          <IsolatedPreviewFrame
+            segmentPath={segmentPath}
+            variantName={variant.name}
+            theme={previewTheme}
+            width="100%"
+            height="100%"
+            minHeight={minHeight}
+          />
+        ) : (
+          <div
+            className="p-4"
+            style={{
+              transform: `scale(${scale})`,
+            }}
+          >
+            <ErrorBoundary
+              componentName={componentName}
+              fallback={
+                <div className="text-xs text-red-500 p-2">
+                  Error rendering variant
+                </div>
+              }
+            >
+              <StoryRenderer variant={variant}>
+                {(content, isLoading, error) => {
+                  if (isLoading) {
+                    return (
+                      <div className="flex items-center justify-center p-4">
+                        <LoaderIndicator />
+                      </div>
+                    );
+                  }
+                  if (error) {
+                    return (
+                      <div className="text-xs text-red-500 p-2">
+                        {error.message}
+                      </div>
+                    );
+                  }
+                  return content;
+                }}
+              </StoryRenderer>
+            </ErrorBoundary>
+          </div>
+        )}
+      </div>
+
+      {/* Tags/badges */}
+      {variant.hasPlayFunction && (
+        <div className="absolute bottom-2 right-2 z-10">
+          <span className="px-1.5 py-0.5 text-[10px] bg-purple-600 text-white rounded">
+            play
+          </span>
+        </div>
+      )}
+    </div>
+  );
+}

package/src/viewer/components/VariantRenderer.tsx

@@ -0,0 +1,131 @@
+// @ts-nocheck
+import React, { type ReactNode, Suspense } from 'react';
+import type { SegmentVariant } from '../../core/index.js';
+import { ErrorBoundary } from './ErrorBoundary.js';
+
+interface VariantRendererProps {
+  /** The variant to render */
+  variant: SegmentVariant;
+
+  /** Optional loading fallback for async components */
+  loadingFallback?: ReactNode;
+
+  /** Optional error fallback */
+  errorFallback?: ReactNode;
+
+  /** Callback when variant render throws */
+  onError?: (error: Error) => void;
+}
+
+/**
+ * Renders a single variant with error boundary and suspense support.
+ */
+export function VariantRenderer({
+  variant,
+  loadingFallback,
+  errorFallback,
+  onError,
+}: VariantRendererProps): React.ReactElement {
+  return (
+    <ErrorBoundary
+      fallback={errorFallback}
+      onError={(error) => onError?.(error)}
+    >
+      <Suspense
+        fallback={
+          loadingFallback ?? (
+            <div
+              style={{
+                padding: '16px',
+                color: '#6b7280',
+                fontFamily: 'system-ui, sans-serif',
+              }}
+            >
+              Loading...
+            </div>
+          )
+        }
+      >
+        {variant.render()}
+      </Suspense>
+    </ErrorBoundary>
+  );
+}
+
+interface VariantGridProps {
+  /** Variants to render */
+  variants: SegmentVariant[];
+
+  /** Number of columns in the grid */
+  columns?: number;
+
+  /** Gap between variants in pixels */
+  gap?: number;
+
+  /** Optional loading fallback */
+  loadingFallback?: ReactNode;
+
+  /** Optional error fallback */
+  errorFallback?: ReactNode;
+}
+
+/**
+ * Renders multiple variants in a grid layout.
+ */
+export function VariantGrid({
+  variants,
+  columns = 2,
+  gap = 24,
+  loadingFallback,
+  errorFallback,
+}: VariantGridProps): React.ReactElement {
+  return (
+    <div
+      style={{
+        display: 'grid',
+        gridTemplateColumns: `repeat(${columns}, 1fr)`,
+        gap: `${gap}px`,
+      }}
+    >
+      {variants.map((variant) => (
+        <div key={variant.name}>
+          <div
+            style={{
+              marginBottom: '8px',
+              fontWeight: 600,
+              fontSize: '14px',
+              color: '#374151',
+              fontFamily: 'system-ui, sans-serif',
+            }}
+          >
+            {variant.name}
+          </div>
+          <div
+            style={{
+              marginBottom: '8px',
+              fontSize: '13px',
+              color: '#6b7280',
+              fontFamily: 'system-ui, sans-serif',
+            }}
+          >
+            {variant.description}
+          </div>
+          <div
+            style={{
+              padding: '16px',
+              border: '1px solid #e5e7eb',
+              borderRadius: '8px',
+              background: '#ffffff',
+            }}
+          >
+            <VariantRenderer
+              variant={variant}
+              loadingFallback={loadingFallback}
+              errorFallback={errorFallback}
+            />
+          </div>
+        </div>
+      ))}
+    </div>
+  );
+}

package/src/viewer/components/VariantTabs.tsx

@@ -0,0 +1,84 @@
+import { useRef, useEffect, useCallback } from 'react';
+import type { SegmentVariant } from '../../core/index.js';
+import clsx from 'clsx';
+import { PlayIcon } from './Icons.js';
+
+interface VariantTabsProps {
+  variants: SegmentVariant[];
+  activeIndex: number;
+  onSelect: (index: number) => void;
+}
+
+export function VariantTabs({ variants, activeIndex, onSelect }: VariantTabsProps) {
+  const containerRef = useRef<HTMLDivElement>(null);
+  const buttonRefs = useRef<Map<number, HTMLButtonElement>>(new Map());
+
+  // Scroll active tab into view when it changes
+  useEffect(() => {
+    const button = buttonRefs.current.get(activeIndex);
+    if (button && containerRef.current) {
+      button.scrollIntoView({
+        behavior: 'smooth',
+        block: 'nearest',
+        inline: 'center',
+      });
+    }
+  }, [activeIndex]);
+
+  // Keyboard navigation for variant tabs
+  const handleKeyDown = useCallback((e: React.KeyboardEvent) => {
+    if (e.key === 'ArrowLeft') {
+      e.preventDefault();
+      const newIndex = activeIndex > 0 ? activeIndex - 1 : variants.length - 1;
+      onSelect(newIndex);
+    } else if (e.key === 'ArrowRight') {
+      e.preventDefault();
+      const newIndex = activeIndex < variants.length - 1 ? activeIndex + 1 : 0;
+      onSelect(newIndex);
+    }
+  }, [activeIndex, variants.length, onSelect]);
+
+  if (variants.length === 0) return null;
+
+  return (
+    <div
+      ref={containerRef}
+      className="flex items-center gap-1 overflow-x-auto max-w-full scrollbar-thin"
+      onKeyDown={handleKeyDown}
+      role="tablist"
+      aria-label="Component variants"
+    >
+      {variants.map((variant, index) => {
+        const isActive = activeIndex === index;
+        return (
+          <button
+            key={index}
+            ref={(el) => {
+              if (el) buttonRefs.current.set(index, el);
+              else buttonRefs.current.delete(index);
+            }}
+            onClick={() => onSelect(index)}
+            onKeyDown={handleKeyDown}
+            role="tab"
+            aria-selected={isActive}
+            tabIndex={isActive ? 0 : -1}
+            className={clsx(
+              'px-3 py-1 text-xs font-medium rounded whitespace-nowrap flex-shrink-0',
+              'focus:outline-none focus-visible:ring-2 focus-visible:ring-[--color-accent]',
+              'flex items-center gap-1.5',
+              isActive
+                ? 'text-primary bg-[--bg-hover]'
+                : 'text-tertiary hover:text-secondary'
+            )}
+            title={variant.hasPlayFunction ? `${variant.name} (has interaction test)` : variant.name}
+          >
+            {variant.name}
+            {variant.hasPlayFunction && (
+              <PlayIcon className="w-3 h-3 text-[--color-accent]" />
+            )}
+          </button>
+        );
+      })}
+    </div>
+  );
+}