@fragments-sdk/viewer 0.2.1

package/src/components/CommandPalette.tsx

@@ -0,0 +1,392 @@
+/**
+ * Command Palette - Cmd+K Quick Switcher
+ *
+ * A keyboard-driven command palette for:
+ * - Quick navigation to components
+ * - Fuzzy search across all components and variants
+ * - Keyboard navigation (arrows, enter, escape)
+ *
+ * Uses Fragments UI Dialog for the overlay shell.
+ */
+
+import { useState, useEffect, useRef, useMemo, useCallback } from "react";
+import { Dialog, Stack, Text, Badge, Separator, Input, Box } from '@fragments-sdk/ui';
+import type { FragmentDefinition } from '@fragments-sdk/core';
+import { SearchIcon, ChevronRightIcon } from "./Icons.js";
+
+interface CommandPaletteProps {
+  /** Whether the palette is open */
+  isOpen: boolean;
+  /** Callback to close the palette */
+  onClose: () => void;
+  /** All available fragments */
+  fragments: Array<{ path: string; fragment: FragmentDefinition }>;
+  /** Callback when a component is selected */
+  onSelectComponent: (path: string) => void;
+  /** Callback when a variant is selected */
+  onSelectVariant: (path: string, variantIndex: number) => void;
+}
+
+interface SearchResult {
+  type: "component" | "variant";
+  path: string;
+  componentName: string;
+  variantName?: string;
+  variantIndex?: number;
+  category: string;
+  score: number;
+}
+
+export function CommandPalette({
+  isOpen,
+  onClose,
+  fragments,
+  onSelectComponent,
+  onSelectVariant,
+}: CommandPaletteProps) {
+  const [query, setQuery] = useState("");
+  const [selectedIndex, setSelectedIndex] = useState(0);
+  const inputRef = useRef<HTMLInputElement>(null);
+  const listRef = useRef<HTMLDivElement>(null);
+
+  // Build search results with fuzzy matching
+  const results = useMemo(() => {
+    const allResults: SearchResult[] = [];
+
+    for (const { path, fragment } of fragments) {
+      const componentName = fragment.meta.name;
+      const category = fragment.meta.category;
+
+      // Add component result
+      allResults.push({
+        type: "component",
+        path,
+        componentName,
+        category,
+        score: 0,
+      });
+
+      // Add variant results
+      if (fragment.variants) {
+        for (let i = 0; i < fragment.variants.length; i++) {
+          const variant = fragment.variants[i];
+          allResults.push({
+            type: "variant",
+            path,
+            componentName,
+            variantName: variant.name,
+            variantIndex: i,
+            category,
+            score: 0,
+          });
+        }
+      }
+    }
+
+    if (!query.trim()) {
+      // No query - show all components sorted alphabetically
+      return allResults
+        .filter((r) => r.type === "component")
+        .sort((a, b) => a.componentName.localeCompare(b.componentName))
+        .slice(0, 20);
+    }
+
+    // Fuzzy match and score results
+    const lowerQuery = query.toLowerCase();
+    const scored = allResults
+      .map((result) => {
+        const searchText = result.variantName
+          ? `${result.componentName} ${result.variantName}`
+          : result.componentName;
+        const score = fuzzyScore(searchText.toLowerCase(), lowerQuery);
+        return { ...result, score };
+      })
+      .filter((r) => r.score > 0)
+      .sort((a, b) => b.score - a.score)
+      .slice(0, 20);
+
+    return scored;
+  }, [fragments, query]);
+
+  // Reset selection when results change
+  useEffect(() => {
+    setSelectedIndex(0);
+  }, [results]);
+
+  // Focus input when opened
+  useEffect(() => {
+    if (isOpen) {
+      setQuery("");
+      setSelectedIndex(0);
+      setTimeout(() => inputRef.current?.focus(), 0);
+    }
+  }, [isOpen]);
+
+  // Scroll selected item into view
+  useEffect(() => {
+    if (listRef.current && results.length > 0) {
+      const selectedEl = listRef.current.children[selectedIndex] as HTMLElement;
+      if (selectedEl) {
+        selectedEl.scrollIntoView({ block: "nearest" });
+      }
+    }
+  }, [selectedIndex, results.length]);
+
+  const handleKeyDown = useCallback(
+    (e: React.KeyboardEvent) => {
+      switch (e.key) {
+        case "ArrowDown":
+          e.preventDefault();
+          setSelectedIndex((i) => Math.min(i + 1, results.length - 1));
+          break;
+        case "ArrowUp":
+          e.preventDefault();
+          setSelectedIndex((i) => Math.max(i - 1, 0));
+          break;
+        case "Enter":
+          e.preventDefault();
+          if (results[selectedIndex]) {
+            handleSelect(results[selectedIndex]);
+          }
+          break;
+        case "Escape":
+          e.preventDefault();
+          onClose();
+          break;
+      }
+    },
+    [results, selectedIndex, onClose]
+  );
+
+  const handleSelect = (result: SearchResult) => {
+    if (result.type === "variant" && result.variantIndex !== undefined) {
+      onSelectVariant(result.path, result.variantIndex);
+    } else {
+      onSelectComponent(result.path);
+    }
+    onClose();
+  };
+
+  if (!isOpen) return null;
+
+  return (
+    <Dialog open={isOpen} onOpenChange={(open: boolean) => { if (!open) onClose(); }}>
+      <Dialog.Content size="lg">
+        {/* Search input */}
+        <Stack direction="row" align="center" style={{
+          padding: '12px 16px',
+          borderBottom: '2px solid #3b82f6',
+        }}>
+          <SearchIcon style={{ width: 20, height: 20, color: '#3b82f6', marginRight: 12 }} />
+          <input
+            ref={inputRef}
+            type="text"
+            value={query}
+            onChange={(e) => setQuery(e.target.value)}
+            onKeyDown={handleKeyDown}
+            placeholder="Search components and variants..."
+            style={{
+              flex: 1,
+              background: 'transparent',
+              color: 'var(--text-primary)',
+              fontSize: '16px',
+              border: 'none',
+              outline: 'none',
+            }}
+          />
+          <Badge size="sm" variant="default">esc</Badge>
+        </Stack>
+
+        {/* Results */}
+        <Box ref={listRef} overflow="auto" style={{ maxHeight: '320px', padding: '8px 0' }}>
+          {results.length === 0 ? (
+            <Box padding="lg" style={{ textAlign: 'center' }}>
+              <Text color="tertiary">
+                {query ? (
+                  <>No results for &ldquo;{query}&rdquo;</>
+                ) : (
+                  <>Start typing to search...</>
+                )}
+              </Text>
+            </Box>
+          ) : (
+            results.map((result, index) => (
+              <button
+                key={`${result.path}-${result.variantName || "component"}`}
+                onClick={() => handleSelect(result)}
+                style={{
+                  width: '100%',
+                  padding: '8px 16px',
+                  display: 'flex',
+                  alignItems: 'center',
+                  gap: '12px',
+                  textAlign: 'left',
+                  transition: 'background-color 150ms',
+                  border: 'none',
+                  cursor: 'pointer',
+                  backgroundColor: index === selectedIndex ? 'rgba(59, 130, 246, 0.1)' : 'transparent',
+                  color: index === selectedIndex ? 'var(--text-primary)' : 'var(--text-secondary)',
+                }}
+                onMouseEnter={(e) => {
+                  setSelectedIndex(index);
+                  if (index !== selectedIndex) {
+                    e.currentTarget.style.backgroundColor = 'var(--bg-hover)';
+                  }
+                }}
+                onMouseLeave={(e) => {
+                  if (index !== selectedIndex) {
+                    e.currentTarget.style.backgroundColor = 'transparent';
+                  }
+                }}
+              >
+                {/* Icon/Badge */}
+                <Badge
+                  size="sm"
+                  style={{
+                    flexShrink: 0,
+                    width: '32px',
+                    height: '32px',
+                    borderRadius: '8px',
+                    display: 'flex',
+                    alignItems: 'center',
+                    justifyContent: 'center',
+                    backgroundColor: result.type === "component"
+                      ? 'rgba(59, 130, 246, 0.15)'
+                      : 'rgba(168, 85, 247, 0.15)',
+                    color: result.type === "component"
+                      ? '#3b82f6'
+                      : '#a855f7',
+                  }}
+                >
+                  {result.type === "component" ? "C" : "V"}
+                </Badge>
+
+                {/* Content */}
+                <div style={{ flex: 1, minWidth: 0 }}>
+                  <Stack direction="row" align="center" gap="sm">
+                    <Text weight="medium" style={{
+                      overflow: 'hidden',
+                      textOverflow: 'ellipsis',
+                      whiteSpace: 'nowrap',
+                    }}>
+                      {result.componentName}
+                    </Text>
+                    {result.variantName && (
+                      <>
+                        <ChevronRightIcon style={{ width: 12, height: 12, color: 'var(--text-tertiary)', flexShrink: 0 }} />
+                        <Text color="secondary" style={{
+                          overflow: 'hidden',
+                          textOverflow: 'ellipsis',
+                          whiteSpace: 'nowrap',
+                        }}>
+                          {result.variantName}
+                        </Text>
+                      </>
+                    )}
+                  </Stack>
+                  <Text size="xs" color="tertiary" style={{
+                    overflow: 'hidden',
+                    textOverflow: 'ellipsis',
+                    whiteSpace: 'nowrap',
+                  }}>
+                    {result.category}
+                  </Text>
+                </div>
+
+                {/* Keyboard hint for selected */}
+                {index === selectedIndex && (
+                  <Badge size="sm" variant="default">enter</Badge>
+                )}
+              </button>
+            ))
+          )}
+        </Box>
+
+        {/* Footer */}
+        <Box paddingX="md" paddingY="sm" borderTop>
+          <Stack direction="row" align="center" justify="between">
+            <Stack direction="row" align="center" gap="md">
+              <Stack direction="row" align="center" gap="xs">
+                <Badge size="sm" variant="default">&#8593;</Badge>
+                <Badge size="sm" variant="default">&#8595;</Badge>
+                <Text size="xs" color="tertiary">to navigate</Text>
+              </Stack>
+              <Stack direction="row" align="center" gap="xs">
+                <Badge size="sm" variant="default">&#8629;</Badge>
+                <Text size="xs" color="tertiary">to select</Text>
+              </Stack>
+            </Stack>
+            <Text size="xs" color="tertiary">
+              {results.length} result{results.length !== 1 ? "s" : ""}
+            </Text>
+          </Stack>
+        </Box>
+      </Dialog.Content>
+    </Dialog>
+  );
+}
+
+/**
+ * Simple fuzzy matching score
+ * Returns 0 for no match, higher values for better matches
+ */
+function fuzzyScore(text: string, query: string): number {
+  if (!query) return 1;
+
+  // Require substring match for short queries to avoid scattered single-char noise
+  if (query.length <= 3 && !text.includes(query)) {
+    return 0;
+  }
+
+  let score = 0;
+  let queryIndex = 0;
+  let consecutiveBonus = 0;
+  let lastMatchIndex = -2;
+  let maxGap = 0;
+
+  for (let i = 0; i < text.length && queryIndex < query.length; i++) {
+    if (text[i] === query[queryIndex]) {
+      score += 1;
+
+      // Bonus for consecutive matches
+      if (i === lastMatchIndex + 1) {
+        consecutiveBonus += 2;
+        score += consecutiveBonus;
+      } else {
+        consecutiveBonus = 0;
+        // Track max gap between matches
+        if (lastMatchIndex >= 0) {
+          const gap = i - lastMatchIndex;
+          if (gap > maxGap) maxGap = gap;
+        }
+      }
+
+      // Bonus for matching at word start
+      if (i === 0 || text[i - 1] === " " || text[i - 1] === "-" || text[i - 1] === "_") {
+        score += 3;
+      }
+
+      lastMatchIndex = i;
+      queryIndex++;
+    }
+  }
+
+  // Only return score if all query characters were found
+  if (queryIndex < query.length) return 0;
+
+  // Penalize large gaps between matched characters
+  if (maxGap > 5) {
+    score -= maxGap;
+  }
+
+  // Bonus for shorter results (more relevant)
+  score += Math.max(0, 20 - text.length);
+
+  // Bonus for exact match
+  if (text === query) score += 50;
+
+  // Bonus for starts with
+  if (text.startsWith(query)) score += 30;
+
+  return Math.max(score, 0) || 0;
+}

package/src/components/ComponentDocView.tsx

@@ -0,0 +1,164 @@
+import type { ReactNode } from "react";
+import type {
+  FragmentDefinition,
+  FragmentVariant,
+  PropDefinition,
+} from '@fragments-sdk/core';
+import type { DocProp } from "../shared/types";
+import { ComponentDocContent } from "../shared/ComponentDocContent";
+import { VariantPreviewCard } from "../shared/VariantPreviewCard";
+import { Badge, Card, CardBody, Stack, Text } from "@fragments-sdk/ui";
+import { PreviewArea } from "./PreviewArea.js";
+import { resolveDisplayedCode } from "./CodePanel.js";
+import { getVariantSectionId } from "./viewer-utils.js";
+import type { ZoomLevel, ViewportPreset, ViewportSize } from "../constants/ui.js";
+import type { PreviewTheme } from "../hooks/useViewSettings.js";
+
+interface ComponentDocViewProps {
+  fragment: { path: string; fragment: FragmentDefinition };
+  fragments: Array<{ path: string; fragment: FragmentDefinition }>;
+  renderVariantContent: (variant: FragmentVariant) => ReactNode;
+  onNavigateToComponent: (name: string) => void;
+  zoom: ZoomLevel;
+  viewport: ViewportPreset;
+  customSize: ViewportSize;
+  previewTheme: PreviewTheme;
+  showComparison: boolean;
+  allFigmaUrls: string[];
+  onRetry: () => void;
+  previewKeyBase: string;
+}
+
+function mapPropsToDocProps(props: Record<string, PropDefinition>): Record<string, DocProp> {
+  const record: Record<string, DocProp> = {};
+  for (const [name, prop] of Object.entries(props)) {
+    record[name] = {
+      type: prop.type,
+      description: prop.description || "",
+      required: prop.required,
+      default: prop.default,
+      values: prop.values ? [...prop.values] : undefined,
+    };
+  }
+  return record;
+}
+
+export function ComponentDocView({
+  fragment,
+  fragments,
+  renderVariantContent,
+  onNavigateToComponent,
+  zoom,
+  viewport,
+  customSize,
+  previewTheme,
+  showComparison,
+  allFigmaUrls,
+  onRetry,
+  previewKeyBase,
+}: ComponentDocViewProps) {
+  const def = fragment.fragment;
+  const componentName = def.meta.name;
+
+  const propsRecord = mapPropsToDocProps(def.props);
+  const packageName = typeof window !== 'undefined' ? window.__FRAGMENTS_PACKAGE_NAME__ : null;
+
+  const usageData = {
+    when: def.usage?.when || [],
+    whenNot: def.usage?.whenNot || [],
+    guidelines: def.usage?.guidelines || [],
+    accessibility: def.usage?.accessibility || [],
+  };
+
+  const relations = def.relations || [];
+
+  return (
+    <ComponentDocContent
+      name={componentName}
+      description={def.meta.description || ""}
+      componentId={componentName}
+      packageName={packageName || undefined}
+      props={propsRecord}
+      variants={def.variants.map((v) => ({
+        name: v.name,
+        description: v.description,
+        code: v.code,
+      }))}
+      usage={usageData}
+      relations={relations}
+      dependencies={def.meta.dependencies}
+      renderVariant={(variant, index) => {
+        const fragVariant = def.variants[index];
+        if (!fragVariant) return null;
+
+        return (
+          <VariantPreviewCard
+            key={variant.name}
+            name={variant.name}
+            description={variant.description}
+            code={resolveDisplayedCode(componentName, fragVariant)}
+            id={getVariantSectionId(componentName, variant.name)}
+          >
+            <PreviewArea
+              componentName={componentName}
+              fragmentPath={fragment.path}
+              variant={fragVariant}
+              variants={def.variants}
+              zoom={zoom}
+              viewport={viewport}
+              customSize={customSize}
+              previewTheme={previewTheme}
+              showMatrixView={false}
+              showMultiViewport={false}
+              showComparison={showComparison}
+              figmaUrl={fragVariant.figma || def.meta.figma}
+              allFigmaUrls={allFigmaUrls}
+              onSelectVariant={() => {}}
+              onRetry={onRetry}
+              renderContent={() => renderVariantContent(fragVariant)}
+              previewKey={`${previewKeyBase}-${index}`}
+            />
+          </VariantPreviewCard>
+        );
+      }}
+      renderRelatedLink={(comp, relationship, note, key) => {
+        const target = fragments.find(
+          (s) => s.fragment.meta.name.toLowerCase() === comp.toLowerCase()
+        );
+
+        return (
+          <a
+            key={key}
+            onClick={(e) => {
+              e.preventDefault();
+              onNavigateToComponent(comp);
+            }}
+            href="#"
+            style={{
+              textDecoration: "none",
+              color: "inherit",
+              cursor: target ? "pointer" : "default",
+              opacity: target ? 1 : 0.6,
+            }}
+          >
+            <Card variant="outlined">
+              <CardBody>
+                <Stack gap="xs">
+                  <Stack direction="row" align="center" justify="between">
+                    <Text weight="semibold">{comp}</Text>
+                    <Badge size="sm">{relationship}</Badge>
+                  </Stack>
+                  {note && (
+                    <Text size="sm" color="secondary">
+                      {note}
+                    </Text>
+                  )}
+                </Stack>
+              </CardBody>
+            </Card>
+          </a>
+        );
+      }}
+    />
+  );
+}