@fragments-sdk/cli 0.2.2

package/src/viewer/components/ResizablePanel.tsx

@@ -0,0 +1,328 @@
+/**
+ * ResizablePanel - A panel that can be resized by dragging and docked to bottom or right
+ *
+ * Features:
+ * - Drag-to-resize from the edge
+ * - Dock to bottom or right side
+ * - Collapsible
+ * - Persists size and dock position to localStorage
+ */
+
+import { useState, useEffect, useCallback, useRef, type ReactNode } from "react";
+import clsx from "clsx";
+import { BRAND } from "../../core/index.js";
+import { ChevronDownIcon } from "./Icons.js";
+
+// Storage key for persisting panel state
+const STORAGE_KEY = `${BRAND.storagePrefix}panel-state`;
+
+interface PanelState {
+  height: number;
+  width: number;
+  dock: "bottom" | "right";
+  isOpen: boolean;
+}
+
+const DEFAULT_STATE: PanelState = {
+  height: 180, // Reduced from 256 to give preview area more space
+  width: 400,
+  dock: "bottom",
+  isOpen: true,
+};
+
+const MIN_HEIGHT = 120;
+const MAX_HEIGHT = 600;
+const MIN_WIDTH = 280;
+const MAX_WIDTH = 800;
+
+function loadPanelState(): PanelState {
+  try {
+    const stored = localStorage.getItem(STORAGE_KEY);
+    if (stored) {
+      const parsed = JSON.parse(stored);
+      return { ...DEFAULT_STATE, ...parsed };
+    }
+  } catch {
+    // Ignore parse errors
+  }
+  return DEFAULT_STATE;
+}
+
+function savePanelState(state: PanelState): void {
+  try {
+    localStorage.setItem(STORAGE_KEY, JSON.stringify(state));
+  } catch {
+    // Ignore storage errors
+  }
+}
+
+interface ResizablePanelProps {
+  /** Panel header content (tabs, title, etc.) */
+  header: ReactNode;
+  /** Panel body content */
+  children: ReactNode;
+  /** Whether to show the panel at all */
+  visible?: boolean;
+  /** Additional class name for the panel container */
+  className?: string;
+}
+
+export function ResizablePanel({
+  header,
+  children,
+  visible = true,
+  className,
+}: ResizablePanelProps) {
+  const [state, setState] = useState<PanelState>(loadPanelState);
+  const [isResizing, setIsResizing] = useState(false);
+  const panelRef = useRef<HTMLDivElement>(null);
+  const startPosRef = useRef({ x: 0, y: 0 });
+  const startSizeRef = useRef({ width: 0, height: 0 });
+
+  // Save state changes to localStorage
+  useEffect(() => {
+    savePanelState(state);
+  }, [state]);
+
+  const handleMouseDown = useCallback(
+    (e: React.MouseEvent) => {
+      e.preventDefault();
+      setIsResizing(true);
+      startPosRef.current = { x: e.clientX, y: e.clientY };
+      startSizeRef.current = { width: state.width, height: state.height };
+    },
+    [state.width, state.height]
+  );
+
+  const handleMouseMove = useCallback(
+    (e: MouseEvent) => {
+      if (!isResizing) return;
+
+      if (state.dock === "bottom") {
+        // Resize height (drag up = increase, drag down = decrease)
+        const deltaY = startPosRef.current.y - e.clientY;
+        const newHeight = Math.max(
+          MIN_HEIGHT,
+          Math.min(MAX_HEIGHT, startSizeRef.current.height + deltaY)
+        );
+        setState((s) => ({ ...s, height: newHeight }));
+      } else {
+        // Resize width (drag left = increase, drag right = decrease)
+        const deltaX = startPosRef.current.x - e.clientX;
+        const newWidth = Math.max(
+          MIN_WIDTH,
+          Math.min(MAX_WIDTH, startSizeRef.current.width + deltaX)
+        );
+        setState((s) => ({ ...s, width: newWidth }));
+      }
+    },
+    [isResizing, state.dock]
+  );
+
+  const handleMouseUp = useCallback(() => {
+    setIsResizing(false);
+  }, []);
+
+  // Add global mouse event listeners during resize
+  useEffect(() => {
+    if (isResizing) {
+      document.addEventListener("mousemove", handleMouseMove);
+      document.addEventListener("mouseup", handleMouseUp);
+      document.body.style.cursor = state.dock === "bottom" ? "ns-resize" : "ew-resize";
+      document.body.style.userSelect = "none";
+
+      return () => {
+        document.removeEventListener("mousemove", handleMouseMove);
+        document.removeEventListener("mouseup", handleMouseUp);
+        document.body.style.cursor = "";
+        document.body.style.userSelect = "";
+      };
+    }
+  }, [isResizing, handleMouseMove, handleMouseUp, state.dock]);
+
+  const toggleOpen = useCallback(() => {
+    setState((s) => ({ ...s, isOpen: !s.isOpen }));
+  }, []);
+
+  const toggleDock = useCallback(() => {
+    setState((s) => ({
+      ...s,
+      dock: s.dock === "bottom" ? "right" : "bottom",
+    }));
+  }, []);
+
+  if (!visible) return null;
+
+  const isBottom = state.dock === "bottom";
+  const isOpen = state.isOpen;
+
+  // Header height for collapsed state
+  const headerHeight = 40; // h-10 = 2.5rem = 40px
+
+  return (
+    <div
+      ref={panelRef}
+      className={clsx(
+        "flex-shrink-0 bg-[--bg-secondary] relative",
+        isBottom
+          ? "border-t border-[--border]"
+          : "border-l border-[--border]",
+        className
+      )}
+      style={{
+        // Only transition when NOT resizing (for smooth open/close animations)
+        // Disable during drag to prevent sluggish feel
+        transition: isResizing ? 'none' : 'height 150ms ease, width 150ms ease',
+        ...(isBottom
+          ? { height: isOpen ? state.height : headerHeight }
+          : { width: isOpen ? state.width : headerHeight }),
+        // Prevent content from being selected during resize
+        ...(isResizing && { pointerEvents: "none" }),
+      }}
+    >
+      {/* Full-viewport overlay during resize - prevents iframes from capturing events */}
+      {isResizing && (
+        <div
+          className="fixed inset-0 z-50"
+          style={{
+            cursor: isBottom ? "ns-resize" : "ew-resize",
+            // Must explicitly enable pointer events since parent has pointerEvents: none
+            pointerEvents: "auto",
+          }}
+        />
+      )}
+
+      {/* Resize Handle - extends above/left of panel for easier grabbing */}
+      {isOpen && (
+        <div
+          className={clsx(
+            "absolute z-20 group",
+            isBottom
+              ? "-top-2 left-0 right-0 h-4 cursor-ns-resize"
+              : "top-0 -left-2 bottom-0 w-4 cursor-ew-resize",
+            isResizing && "bg-[--color-accent]/20"
+          )}
+          onMouseDown={handleMouseDown}
+        >
+          {/* Visual indicator - shows on hover */}
+          <div
+            className={clsx(
+              "absolute bg-[--color-accent] opacity-0 group-hover:opacity-50 transition-opacity",
+              isBottom
+                ? "left-1/2 top-1/2 -translate-x-1/2 -translate-y-1/2 w-12 h-1 rounded-full"
+                : "top-1/2 left-1/2 -translate-x-1/2 -translate-y-1/2 w-1 h-12 rounded-full"
+            )}
+          />
+        </div>
+      )}
+
+      {/* Panel Header */}
+      <div
+        className={clsx(
+          "flex items-center justify-between px-4 border-[--border-subtle]",
+          isBottom ? "h-10 border-b" : "h-10 border-b"
+        )}
+      >
+        <div className="flex items-center gap-1 flex-1 overflow-hidden">
+          {header}
+        </div>
+        <div className="flex items-center gap-1">
+          {/* Dock toggle button */}
+          <button
+            onClick={toggleDock}
+            className="p-1 text-tertiary hover:text-primary hover:bg-[--bg-hover] rounded transition-colors"
+            title={isBottom ? "Dock to right" : "Dock to bottom"}
+          >
+            <DockIcon dock={state.dock} className="w-4 h-4" />
+          </button>
+          {/* Collapse toggle button */}
+          <button
+            onClick={toggleOpen}
+            className="p-1 text-tertiary hover:text-primary hover:bg-[--bg-hover] rounded transition-colors"
+            title={isOpen ? "Collapse panel" : "Expand panel"}
+          >
+            <ChevronDownIcon
+              className={clsx(
+                "w-4 h-4 transition-transform",
+                !isOpen && (isBottom ? "rotate-180" : "-rotate-90"),
+                isOpen && !isBottom && "rotate-90"
+              )}
+            />
+          </button>
+        </div>
+      </div>
+
+      {/* Panel Content */}
+      {isOpen && (
+        <div
+          className="overflow-auto"
+          style={{
+            height: isBottom ? `calc(100% - ${headerHeight}px)` : "100%",
+            width: isBottom ? "100%" : `calc(100% - ${headerHeight}px)`,
+          }}
+        >
+          {children}
+        </div>
+      )}
+    </div>
+  );
+}
+
+/**
+ * Hook to get panel dock position for layout purposes
+ */
+export function usePanelDock(): "bottom" | "right" {
+  const [dock, setDock] = useState<"bottom" | "right">(() => {
+    const state = loadPanelState();
+    return state.dock;
+  });
+
+  useEffect(() => {
+    const handleStorage = () => {
+      const state = loadPanelState();
+      setDock(state.dock);
+    };
+
+    // Listen for storage changes (from other tabs)
+    window.addEventListener("storage", handleStorage);
+
+    // Also poll for changes since localStorage events don't fire in same tab
+    const interval = setInterval(handleStorage, 500);
+
+    return () => {
+      window.removeEventListener("storage", handleStorage);
+      clearInterval(interval);
+    };
+  }, []);
+
+  return dock;
+}
+
+// Icon for dock position toggle
+function DockIcon({ dock, className }: { dock: "bottom" | "right"; className?: string }) {
+  if (dock === "bottom") {
+    // Show icon indicating "dock to right" action
+    return (
+      <svg className={className} viewBox="0 0 16 16" fill="none" stroke="currentColor" strokeWidth="1.5">
+        {/* Outer frame */}
+        <rect x="1" y="2" width="14" height="12" rx="1" />
+        {/* Right panel indicator */}
+        <line x1="10" y1="2" x2="10" y2="14" />
+        <line x1="10" y1="8" x2="15" y2="8" strokeDasharray="2 1" />
+      </svg>
+    );
+  }
+
+  // Show icon indicating "dock to bottom" action
+  return (
+    <svg className={className} viewBox="0 0 16 16" fill="none" stroke="currentColor" strokeWidth="1.5">
+      {/* Outer frame */}
+      <rect x="1" y="2" width="14" height="12" rx="1" />
+      {/* Bottom panel indicator */}
+      <line x1="1" y1="10" x2="15" y2="10" />
+      <line x1="8" y1="10" x2="8" y2="14" strokeDasharray="2 1" />
+    </svg>
+  );
+}
+
+export default ResizablePanel;

package/src/viewer/components/RightSidebar.tsx

@@ -0,0 +1,118 @@
+import type { SegmentDefinition } from '../../core/index.js';
+import { useScrollSpy } from '../hooks/useScrollSpy.js';
+import clsx from 'clsx';
+
+interface RightSidebarProps {
+  segment: SegmentDefinition;
+}
+
+interface TocItem {
+  id: string;
+  label: string;
+  children?: TocItem[];
+}
+
+export function RightSidebar({ segment }: RightSidebarProps) {
+  // Build table of contents from segment
+  const tocItems: TocItem[] = [];
+
+  // Overview section
+  tocItems.push({ id: 'overview', label: 'Overview' });
+
+  // Variants section with nested items
+  if (segment.variants && segment.variants.length > 0) {
+    tocItems.push({
+      id: 'variants',
+      label: 'Variants',
+      children: segment.variants.map((variant, index) => ({
+        id: `variant-${index}`,
+        label: variant.name,
+      })),
+    });
+  }
+
+  // Usage section
+  if (segment.usage) {
+    tocItems.push({ id: 'usage', label: 'Usage' });
+  }
+
+  // Props section
+  if (segment.props && Object.keys(segment.props).length > 0) {
+    tocItems.push({ id: 'props', label: 'Props' });
+  }
+
+  // Relations section
+  if (segment.relations && segment.relations.length > 0) {
+    tocItems.push({ id: 'relations', label: 'Relations' });
+  }
+
+  // Flatten for scroll spy
+  const allIds = tocItems.flatMap((item) => [
+    item.id,
+    ...(item.children?.map((child) => child.id) ?? []),
+  ]);
+
+  const { activeId, scrollToSection } = useScrollSpy({
+    sectionIds: allIds,
+    offset: 100,
+  });
+
+  return (
+    <div className="py-2">
+      <h4 className="px-3 mb-4 text-[11px] font-medium text-tertiary uppercase tracking-wider">
+        On this page
+      </h4>
+      <nav>
+        <ul className="space-y-0.5">
+          {tocItems.map((item) => {
+            const isActive = activeId === item.id;
+            const hasActiveChild = item.children?.some((child) => activeId === child.id);
+
+            return (
+              <li key={item.id}>
+                <button
+                  onClick={() => scrollToSection(item.id)}
+                  className={clsx(
+                    'group flex items-center w-full text-left px-3 py-1.5 text-[13px] rounded-md transition-all duration-150',
+                    'focus:outline-none focus-visible:ring-2 focus-visible:ring-[--color-accent] focus-visible:ring-inset',
+                    isActive || hasActiveChild
+                      ? 'text-primary font-medium'
+                      : 'text-secondary hover:text-primary hover:bg-[--bg-hover]'
+                  )}
+                >
+                  {(isActive || hasActiveChild) && (
+                    <span className="w-0.5 h-3.5 rounded-full bg-[--color-accent] mr-2 -ml-1" />
+                  )}
+                  {item.label}
+                </button>
+                {item.children && item.children.length > 0 && (
+                  <ul className="ml-4 mt-0.5 space-y-0.5 border-l border-[--border-subtle] pl-2">
+                    {item.children.map((child) => {
+                      const isChildActive = activeId === child.id;
+                      return (
+                        <li key={child.id}>
+                          <button
+                            onClick={() => scrollToSection(child.id)}
+                            className={clsx(
+                              'block w-full text-left px-2 py-1 text-[12px] rounded-md transition-all duration-150',
+                              'focus:outline-none focus-visible:ring-2 focus-visible:ring-[--color-accent] focus-visible:ring-inset',
+                              isChildActive
+                                ? 'text-primary font-medium'
+                                : 'text-tertiary hover:text-secondary'
+                            )}
+                          >
+                            {child.label}
+                          </button>
+                        </li>
+                      );
+                    })}
+                  </ul>
+                )}
+              </li>
+            );
+          })}
+        </ul>
+      </nav>
+    </div>
+  );
+}

package/src/viewer/components/ScreenshotButton.tsx

@@ -0,0 +1,90 @@
+/**
+ * ScreenshotButton component - captures screenshots of the preview area.
+ * Saves directly to file.
+ */
+
+import { useState, memo } from 'react';
+import html2canvas from 'html2canvas';
+import { CameraIcon } from './Icons.js';
+
+interface ScreenshotButtonProps {
+  componentName: string;
+  variantName: string;
+}
+
+export const ScreenshotButton = memo(function ScreenshotButton({ componentName, variantName }: ScreenshotButtonProps) {
+  const [status, setStatus] = useState<'idle' | 'loading' | 'success' | 'error'>('idle');
+
+  const handleSaveToFile = async () => {
+    setStatus('loading');
+    try {
+      const previewContainer = document.querySelector('[data-preview-container="true"]');
+      if (!previewContainer) throw new Error('Preview container not found');
+
+      // Wait for fonts to be fully loaded
+      await document.fonts.ready;
+
+      const canvas = await html2canvas(previewContainer as HTMLElement, {
+        backgroundColor: null,
+        scale: 2,
+        logging: false,
+        useCORS: true,
+        allowTaint: true,
+        // Clone callback to ensure styles are properly computed
+        onclone: (clonedDoc) => {
+          // Force the cloned document to use the same computed styles
+          const clonedElement = clonedDoc.querySelector('[data-preview-container="true"]');
+          if (clonedElement) {
+            // Ensure fonts are applied in the cloned document
+            const style = clonedDoc.createElement('style');
+            style.textContent = Array.from(document.styleSheets)
+              .map(sheet => {
+                try {
+                  return Array.from(sheet.cssRules)
+                    .map(rule => rule.cssText)
+                    .join('\n');
+                } catch {
+                  return '';
+                }
+              })
+              .join('\n');
+            clonedDoc.head.appendChild(style);
+          }
+        },
+      });
+
+      const blob = await new Promise<Blob>((resolve, reject) => {
+        canvas.toBlob((b) => {
+          if (b) resolve(b);
+          else reject(new Error('Failed to create blob'));
+        }, 'image/png');
+      });
+
+      const url = URL.createObjectURL(blob);
+      const a = document.createElement('a');
+      a.href = url;
+      a.download = `${componentName}-${variantName}.png`;
+      document.body.appendChild(a);
+      a.click();
+      document.body.removeChild(a);
+      URL.revokeObjectURL(url);
+      setStatus('success');
+      setTimeout(() => setStatus('idle'), 2000);
+    } catch (err) {
+      console.error('Screenshot save failed:', err);
+      setStatus('error');
+      setTimeout(() => setStatus('idle'), 2000);
+    }
+  };
+
+  return (
+    <button
+      onClick={handleSaveToFile}
+      disabled={status === 'loading'}
+      className="p-1.5 text-tertiary hover:text-primary hover:bg-[--bg-hover] rounded transition-colors disabled:opacity-50"
+      title="Save screenshot"
+    >
+      <CameraIcon className="w-4 h-4" />
+    </button>
+  );
+});

package/src/viewer/components/Sidebar.tsx

@@ -0,0 +1,169 @@
+import React, { useState, useMemo } from 'react';
+import type { SegmentDefinition } from '../../core/index.js';
+
+interface SidebarProps {
+  segments: Array<{ path: string; segment: SegmentDefinition }>;
+  activeSegment: string | null;
+  onSelect: (path: string) => void;
+}
+
+export function Sidebar({ segments, activeSegment, onSelect }: SidebarProps): React.ReactElement {
+  const [search, setSearch] = useState('');
+
+  // Group segments by category
+  const grouped = useMemo(() => {
+    const groups: Record<string, typeof segments> = {};
+
+    for (const item of segments) {
+      const category = item.segment.meta.category || 'uncategorized';
+      if (!groups[category]) {
+        groups[category] = [];
+      }
+      groups[category].push(item);
+    }
+
+    // Filter by search
+    if (search) {
+      const filtered: Record<string, typeof segments> = {};
+      for (const [category, items] of Object.entries(groups)) {
+        const matchingItems = items.filter(
+          (item) =>
+            item.segment.meta.name.toLowerCase().includes(search.toLowerCase()) ||
+            item.segment.meta.description.toLowerCase().includes(search.toLowerCase())
+        );
+        if (matchingItems.length > 0) {
+          filtered[category] = matchingItems;
+        }
+      }
+      return filtered;
+    }
+
+    return groups;
+  }, [segments, search]);
+
+  return (
+    <div
+      style={{
+        width: '280px',
+        height: '100vh',
+        background: '#f9fafb',
+        borderRight: '1px solid #e5e7eb',
+        display: 'flex',
+        flexDirection: 'column',
+        overflow: 'hidden',
+      }}
+    >
+      {/* Header */}
+      <div
+        style={{
+          padding: '16px',
+          borderBottom: '1px solid #e5e7eb',
+        }}
+      >
+        <h1
+          style={{
+            margin: 0,
+            fontSize: '18px',
+            fontWeight: 700,
+            color: '#111827',
+          }}
+        >
+          Segments
+        </h1>
+        <p
+          style={{
+            margin: '4px 0 0',
+            fontSize: '12px',
+            color: '#6b7280',
+          }}
+        >
+          {segments.length} component{segments.length !== 1 ? 's' : ''}
+        </p>
+      </div>
+
+      {/* Search */}
+      <div style={{ padding: '12px 16px' }}>
+        <input
+          type="text"
+          placeholder="Search components..."
+          value={search}
+          onChange={(e) => setSearch(e.target.value)}
+          style={{
+            width: '100%',
+            padding: '8px 12px',
+            border: '1px solid #d1d5db',
+            borderRadius: '6px',
+            fontSize: '13px',
+            outline: 'none',
+            boxSizing: 'border-box',
+          }}
+        />
+      </div>
+
+      {/* Component list */}
+      <div
+        style={{
+          flex: 1,
+          overflow: 'auto',
+          padding: '0 8px 16px',
+        }}
+      >
+        {Object.entries(grouped).map(([category, items]) => (
+          <div key={category} style={{ marginBottom: '16px' }}>
+            <div
+              style={{
+                padding: '8px',
+                fontSize: '11px',
+                fontWeight: 600,
+                color: '#6b7280',
+                textTransform: 'uppercase',
+                letterSpacing: '0.05em',
+              }}
+            >
+              {category}
+            </div>
+            {items.map((item) => (
+              <button
+                key={item.path}
+                onClick={() => onSelect(item.path)}
+                style={{
+                  display: 'block',
+                  width: '100%',
+                  padding: '8px 12px',
+                  border: 'none',
+                  borderRadius: '6px',
+                  background: activeSegment === item.path ? '#e5e7eb' : 'transparent',
+                  textAlign: 'left',
+                  cursor: 'pointer',
+                  transition: 'background 0.15s',
+                }}
+              >
+                <div
+                  style={{
+                    fontSize: '13px',
+                    fontWeight: 500,
+                    color: '#111827',
+                  }}
+                >
+                  {item.segment.meta.name}
+                </div>
+                <div
+                  style={{
+                    fontSize: '12px',
+                    color: '#6b7280',
+                    marginTop: '2px',
+                    overflow: 'hidden',
+                    textOverflow: 'ellipsis',
+                    whiteSpace: 'nowrap',
+                  }}
+                >
+                  {item.segment.meta.description}
+                </div>
+              </button>
+            ))}
+          </div>
+        ))}
+      </div>
+    </div>
+  );
+}