@fragments-sdk/viewer 0.2.1

package/src/components/LeftSidebar.tsx

@@ -0,0 +1,472 @@
+import { useState, useMemo, useRef, useEffect, useCallback } from 'react';
+import type { FragmentDefinition } from '@fragments-sdk/core';
+import { Sidebar, useSidebar, Text, Menu, Button, Box, Stack } from '@fragments-sdk/ui';
+
+// Fuzzy matching utility
+interface FuzzyMatch {
+  score: number;
+  indices: number[];
+}
+
+function fuzzyMatch(text: string, pattern: string): FuzzyMatch | null {
+  if (!pattern) return { score: 0, indices: [] };
+
+  const textLower = text.toLowerCase();
+  const patternLower = pattern.toLowerCase();
+
+  // Require substring match for short queries (<=3 chars) to avoid scattered single-char noise
+  if (patternLower.length <= 3 && !textLower.includes(patternLower)) {
+    return null;
+  }
+
+  const indices: number[] = [];
+  let patternIdx = 0;
+  let score = 0;
+  let consecutiveBonus = 0;
+  let maxGap = 0;
+
+  for (let i = 0; i < textLower.length && patternIdx < patternLower.length; i++) {
+    if (textLower[i] === patternLower[patternIdx]) {
+      indices.push(i);
+      if (indices.length > 1) {
+        const gap = i - indices[indices.length - 2];
+        if (gap === 1) {
+          consecutiveBonus += 5;
+        }
+        if (gap > maxGap) maxGap = gap;
+      }
+      if (i === 0 || text[i - 1] === ' ' || text[i - 1] === '-' || text[i - 1] === '_') {
+        score += 10;
+      }
+      patternIdx++;
+    }
+  }
+
+  if (patternIdx !== patternLower.length) {
+    return null;
+  }
+
+  // Penalize large gaps between matched characters
+  if (maxGap > 5) {
+    score -= maxGap * 2;
+  }
+
+  score += consecutiveBonus;
+  score += (patternLower.length / textLower.length) * 20;
+
+  // Reject very low scores (scattered single-char matches)
+  if (score <= 0 && patternLower.length > 1) {
+    return null;
+  }
+
+  return { score, indices };
+}
+
+interface SearchResult {
+  item: { path: string; fragment: FragmentDefinition };
+  score: number;
+  nameIndices: number[];
+}
+
+function searchFragment(
+  item: { path: string; fragment: FragmentDefinition },
+  query: string
+): SearchResult | null {
+  const { fragment } = item;
+  // Skip invalid fragments
+  if (!fragment?.meta) return null;
+  const { name, category, tags } = fragment.meta;
+
+  const nameMatch = fuzzyMatch(name, query);
+  if (nameMatch) {
+    return { item, score: nameMatch.score + 100, nameIndices: nameMatch.indices };
+  }
+
+  const categoryMatch = fuzzyMatch(category, query);
+  if (categoryMatch) {
+    return { item, score: categoryMatch.score + 50, nameIndices: [] };
+  }
+
+  if (tags) {
+    for (const tag of tags) {
+      const tagMatch = fuzzyMatch(tag, query);
+      if (tagMatch) {
+        return { item, score: tagMatch.score + 25, nameIndices: [] };
+      }
+    }
+  }
+
+  return null;
+}
+
+function useDebounce<T>(value: T, delay: number): T {
+  const [debouncedValue, setDebouncedValue] = useState(value);
+
+  useEffect(() => {
+    const timer = setTimeout(() => setDebouncedValue(value), delay);
+    return () => clearTimeout(timer);
+  }, [value, delay]);
+
+  return debouncedValue;
+}
+
+function HighlightedText({ text, indices }: { text: string; indices: number[] }) {
+  if (indices.length === 0) return <>{text}</>;
+
+  const result: React.ReactNode[] = [];
+  let lastIndex = 0;
+
+  for (let i = 0; i < indices.length; i++) {
+    const matchIndex = indices[i];
+    if (matchIndex > lastIndex) {
+      result.push(text.slice(lastIndex, matchIndex));
+    }
+    result.push(
+      <span key={matchIndex} style={{ color: 'var(--text-primary)', fontWeight: 500 }}>
+        {text[matchIndex]}
+      </span>
+    );
+    lastIndex = matchIndex + 1;
+  }
+
+  if (lastIndex < text.length) {
+    result.push(text.slice(lastIndex));
+  }
+
+  return <>{result}</>;
+}
+
+interface LeftSidebarProps {
+  fragments: Array<{ path: string; fragment: FragmentDefinition }>;
+  activeFragment: string | null;
+  searchQuery: string;
+  onSelect: (path: string) => void;
+  showHealth?: boolean;
+  onHealthClick?: () => void;
+}
+
+const FilterIcon = ({ active }: { active?: boolean }) => (
+  <svg width="14" height="14" viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">
+    <path
+      d="M2 3h12l-4.5 5.5V13l-3-1.5V8.5L2 3z"
+      stroke={active ? 'var(--color-brand, #3b82f6)' : 'currentColor'}
+      strokeWidth="1.5"
+      strokeLinejoin="round"
+      fill={active ? 'var(--color-brand, #3b82f6)' : 'none'}
+      fillOpacity={active ? 0.15 : 0}
+    />
+  </svg>
+);
+
+const isInstalled = (path: string) => path.startsWith('@');
+
+/** Normalize category names to Title Case: "form" → "Form", "Data Display" stays */
+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.
+ *  Returns the singular form as grouping key. */
+function categoryKey(raw: string): string {
+  const tc = titleCase(raw.trim());
+  // Strip trailing "s" plurals (Forms→Form, Buttons→Button) but not short words like "Tabs"
+  if (tc.length > 4 && tc.endsWith('s') && !tc.endsWith('ss')) {
+    return tc.slice(0, -1);
+  }
+  return tc;
+}
+
+/** Pluralize a category name for display: "Form" → "Forms", "General" stays */
+function pluralizeCategory(key: string): string {
+  // Already plural or naturally non-plural categories
+  const nonPlural = new Set(['General', 'Feedback', 'Layout', 'Navigation', 'Typography', 'Deprecated', 'Data Display']);
+  if (nonPlural.has(key)) return key;
+  // Already ends in s (edge case)
+  if (key.endsWith('s')) return key;
+  return key + 's';
+}
+
+export function LeftSidebar({ fragments, activeFragment, searchQuery, onSelect, showHealth, onHealthClick }: LeftSidebarProps) {
+  const [focusedIndex, setFocusedIndex] = useState(-1);
+  const [showCustom, setShowCustom] = useState(true);
+  const [showLibrary, setShowLibrary] = useState(true);
+  const { isMobile, setOpen } = useSidebar();
+  const navRef = useRef<HTMLDivElement>(null);
+
+  // Determine if both sources exist (only show filter when useful)
+  const hasBothSources = useMemo(() => {
+    let hasCustom = false;
+    let hasLibrary = false;
+    for (const item of fragments) {
+      if (isInstalled(item.path)) hasLibrary = true;
+      else hasCustom = true;
+      if (hasCustom && hasLibrary) return true;
+    }
+    return false;
+  }, [fragments]);
+
+  const debouncedSearch = useDebounce(searchQuery, 150);
+
+  const searchResults = useMemo(() => {
+    if (!debouncedSearch) return null;
+
+    const results: SearchResult[] = [];
+    for (const item of fragments) {
+      const result = searchFragment(item, debouncedSearch);
+      if (result) results.push(result);
+    }
+
+    results.sort((a, b) => b.score - a.score);
+    return results;
+  }, [fragments, debouncedSearch]);
+
+  const highlightMap = useMemo(() => {
+    const map = new Map<string, number[]>();
+    if (searchResults) {
+      for (const result of searchResults) {
+        map.set(result.item.path, result.nameIndices);
+      }
+    }
+    return map;
+  }, [searchResults]);
+
+  const isFilterActive = showCustom !== showLibrary;
+
+  // Apply source filter
+  const sourceFiltered = useMemo(() => {
+    if (!isFilterActive) return fragments;
+    return fragments.filter(item =>
+      showLibrary ? isInstalled(item.path) : !isInstalled(item.path)
+    );
+  }, [fragments, isFilterActive, showLibrary]);
+
+  // Flat alphabetical list (search results sorted by relevance, otherwise alphabetical)
+  const flatItems = useMemo(() => {
+    if (searchResults) {
+      return searchResults
+        .map(r => r.item)
+        .filter(item => item.fragment?.meta?.name)
+        .filter(item => !isFilterActive || (showLibrary ? isInstalled(item.path) : !isInstalled(item.path)));
+    }
+    return [...sourceFiltered]
+      .filter(item => item.fragment?.meta?.name)
+      .sort((a, b) =>
+        a.fragment.meta.name.toLowerCase().localeCompare(b.fragment.meta.name.toLowerCase())
+      );
+  }, [sourceFiltered, searchResults, isFilterActive, showLibrary]);
+
+  // Group items by category when not searching (for large lists)
+  const categoryGroups = useMemo(() => {
+    if (searchResults || flatItems.length < 30) return null; // Flat list for small sets or search
+    const groups = new Map<string, typeof flatItems>();
+    for (const item of flatItems) {
+      const raw = item.fragment.meta.category || 'Uncategorized';
+      const key = categoryKey(raw);
+      if (!groups.has(key)) groups.set(key, []);
+      groups.get(key)!.push(item);
+    }
+    // Sort categories alphabetically, map key → display label
+    return [...groups.entries()]
+      .sort((a, b) => a[0].toLowerCase().localeCompare(b[0].toLowerCase()))
+      .map(([key, items]) => [pluralizeCategory(key), items] as const);
+  }, [flatItems, searchResults]);
+
+  const keyboardItems = useMemo(() => {
+    const componentItems = flatItems.map((item) => ({ type: 'component' as const, path: item.path }));
+    if (!onHealthClick) return componentItems;
+    return [{ type: 'dashboard' as const }, ...componentItems];
+  }, [flatItems, onHealthClick]);
+
+  useEffect(() => {
+    if (focusedIndex >= 0 && focusedIndex < keyboardItems.length && navRef.current) {
+      // Query all nav item buttons rendered by Sidebar.Item inside the nav
+      const buttons = navRef.current.querySelectorAll<HTMLButtonElement>('li > button[type="button"]');
+      if (buttons[focusedIndex]) {
+        buttons[focusedIndex].focus();
+      }
+    }
+  }, [focusedIndex, keyboardItems.length]);
+
+  // Scroll the active sidebar item into view on mount and when activeFragment changes
+  useEffect(() => {
+    if (!activeFragment || !navRef.current) return;
+    // Small delay to let the DOM render after category grouping
+    const timer = setTimeout(() => {
+      const activeButton = navRef.current?.querySelector<HTMLButtonElement>('[aria-current="page"]');
+      if (activeButton) {
+        activeButton.scrollIntoView({ block: 'nearest', behavior: 'smooth' });
+      }
+    }, 100);
+    return () => clearTimeout(timer);
+  }, [activeFragment]);
+
+  useEffect(() => {
+    setFocusedIndex(-1);
+  }, [searchQuery]);
+
+  const handleSelect = (path: string) => {
+    onSelect(path);
+    if (isMobile) {
+      setOpen(false);
+    }
+  };
+
+  const handleHealthClick = () => {
+    onHealthClick?.();
+    if (isMobile) {
+      setOpen(false);
+    }
+  };
+
+  const handleKeyDown = useCallback((e: KeyboardEvent) => {
+    const target = e.target as HTMLElement;
+    if (target.tagName === 'INPUT' || target.tagName === 'TEXTAREA' || target.isContentEditable) {
+      return;
+    }
+
+    if (e.key === 'Escape') {
+      setFocusedIndex(-1);
+      return;
+    }
+
+    if (e.key === 'ArrowDown') {
+      e.preventDefault();
+      setFocusedIndex(prev => (prev + 1) >= keyboardItems.length ? 0 : prev + 1);
+    } else if (e.key === 'ArrowUp') {
+      e.preventDefault();
+      setFocusedIndex(prev => (prev - 1) < 0 ? keyboardItems.length - 1 : prev - 1);
+    } else if (e.key === 'Enter' && focusedIndex >= 0 && focusedIndex < keyboardItems.length) {
+      e.preventDefault();
+      const currentItem = keyboardItems[focusedIndex];
+      if (currentItem.type === 'dashboard') {
+        handleHealthClick();
+      } else {
+        handleSelect(currentItem.path);
+      }
+    }
+  }, [keyboardItems, focusedIndex, handleHealthClick, handleSelect]);
+
+  useEffect(() => {
+    document.addEventListener('keydown', handleKeyDown);
+    return () => document.removeEventListener('keydown', handleKeyDown);
+  }, [handleKeyDown]);
+
+  return (
+    <>
+      {/* Component list */}
+      <Sidebar.Nav aria-label="Components">
+        <div ref={navRef}>
+          {onHealthClick && (
+            <Sidebar.Section label="Overview">
+              <Sidebar.Item
+                active={!!showHealth}
+                onClick={handleHealthClick}
+              >
+                Dashboard
+              </Sidebar.Item>
+            </Sidebar.Section>
+          )}
+
+          {categoryGroups ? (
+            // Grouped by category for large component lists
+            <>
+              {categoryGroups.map(([category, items]) => (
+                <Sidebar.Section key={category} label={`${category} (${items.length})`}>
+                  {items.map((item) => {
+                    const hasError = !!(item.fragment as any)?._loadError;
+                    return (
+                      <Sidebar.Item
+                        key={item.path}
+                        active={activeFragment === item.path}
+                        onClick={() => handleSelect(item.path)}
+                      >
+                        <span style={{ display: 'flex', alignItems: 'center', gap: '6px', width: '100%' }}>
+                          <HighlightedText
+                            text={item.fragment.meta.name}
+                            indices={highlightMap.get(item.path) || []}
+                          />
+                          {hasError && (
+                            <span
+                              title="Missing dependencies"
+                              style={{ color: 'var(--color-warning, #f59e0b)', fontSize: '14px', lineHeight: 1, flexShrink: 0 }}
+                            >
+                              &#9888;
+                            </span>
+                          )}
+                        </span>
+                      </Sidebar.Item>
+                    );
+                  })}
+                </Sidebar.Section>
+              ))}
+            </>
+          ) : (
+            // Flat list for search results or small component sets
+            <Sidebar.Section
+              label="Components"
+              action={hasBothSources ? (
+                <Menu modal={false}>
+                  <Menu.Trigger asChild>
+                    <Button variant="ghost" size="sm" icon aria-label="Filter components by source">
+                      <FilterIcon active={isFilterActive} />
+                    </Button>
+                  </Menu.Trigger>
+                  <Menu.Content>
+                    <Menu.CheckboxItem checked={showCustom} onCheckedChange={setShowCustom}>
+                      Custom
+                    </Menu.CheckboxItem>
+                    <Menu.CheckboxItem checked={showLibrary} onCheckedChange={setShowLibrary}>
+                      Fragments UI
+                    </Menu.CheckboxItem>
+                  </Menu.Content>
+                </Menu>
+              ) : undefined}
+            >
+              {flatItems.map((item) => {
+                const hasError = !!(item.fragment as any)?._loadError;
+                return (
+                  <Sidebar.Item
+                    key={item.path}
+                    active={activeFragment === item.path}
+                    onClick={() => handleSelect(item.path)}
+                  >
+                    <span style={{ display: 'flex', alignItems: 'center', gap: '6px', width: '100%' }}>
+                      <HighlightedText
+                        text={item.fragment.meta.name}
+                        indices={highlightMap.get(item.path) || []}
+                      />
+                      {hasError && (
+                        <span
+                          title="Missing dependencies"
+                          style={{ color: 'var(--color-warning, #f59e0b)', fontSize: '14px', lineHeight: 1, flexShrink: 0 }}
+                        >
+                          &#9888;
+                        </span>
+                      )}
+                    </span>
+                  </Sidebar.Item>
+                );
+              })}
+            </Sidebar.Section>
+          )}
+
+          {flatItems.length === 0 && (
+            <Box paddingX="lg" paddingY="sm" style={{ textAlign: 'center' }}>
+              <Text size="sm" color="tertiary">No results</Text>
+            </Box>
+          )}
+        </div>
+      </Sidebar.Nav>
+
+      {/* Footer */}
+      <Sidebar.Footer>
+        <Stack direction="row" align="center" justify="between" style={{ width: '100%' }}>
+          <Text size="xs" color="tertiary">
+            {isFilterActive || searchResults ? `${flatItems.length} of ${fragments.length}` : fragments.length} components
+          </Text>
+          <Sidebar.CollapseToggle />
+        </Stack>
+      </Sidebar.Footer>
+    </>
+  );
+}

package/src/components/LoadErrorMessage.tsx

@@ -0,0 +1,102 @@
+import { Stack, Text, Alert, Box } from "@fragments-sdk/ui";
+
+interface LoadErrorMessageProps {
+  error: { message: string; dependencies: string[] };
+  componentName?: string;
+}
+
+export function LoadErrorMessage({ error, componentName }: LoadErrorMessageProps) {
+  const deps = error.dependencies || [];
+  const errorMessage = error.message || "Unknown error";
+
+  // Determine if the error is a missing module/dependency issue
+  const isModuleError =
+    /Failed to resolve import|Cannot find module|Module not found|does not provide an export/.test(
+      errorMessage
+    );
+
+  // Only suggest packages if the error is actually about missing modules
+  let suggestedPackages: string[] = [];
+  if (isModuleError) {
+    if (deps.length > 0) {
+      suggestedPackages = [...deps];
+    } else {
+      const match = errorMessage.match(/Failed to resolve import ["']([^"']+)["']/);
+      if (match) {
+        suggestedPackages = [match[1]];
+      }
+    }
+  }
+
+  const hasMissingDeps = suggestedPackages.length > 0;
+  const installCmd = `pnpm add ${suggestedPackages.join(" ")}`;
+
+  return (
+    <Stack align="center" justify="center" style={{ height: "100%", padding: "24px" }}>
+      <Alert variant="warning">
+        <Alert.Body>
+          <Alert.Title>{hasMissingDeps ? "Missing Dependencies" : "Failed to Load"}</Alert.Title>
+          <Alert.Content>
+            <Stack direction="column" gap="sm">
+              {hasMissingDeps ? (
+                <>
+                  <Text size="xs" color="secondary">
+                    {componentName ? `${componentName} requires` : "This component requires"}{" "}
+                    packages that are not installed in your project.
+                  </Text>
+                  <Text size="xs" weight="semibold" color="secondary">
+                    Install with:
+                  </Text>
+                  <Box
+                    as="code"
+                    padding="sm"
+                    background="tertiary"
+                    rounded="sm"
+                    style={{
+                      display: "block",
+                      fontFamily: "monospace",
+                      fontSize: "12px",
+                      userSelect: "all",
+                    }}
+                  >
+                    {installCmd}
+                  </Box>
+                  <Text size="xs" color="tertiary">
+                    After installing, restart the dev server.
+                  </Text>
+                </>
+              ) : (
+                <>
+                  <Text size="xs" color="secondary">
+                    {componentName ? `${componentName} couldn't` : "This component couldn't"} be
+                    loaded. This may be due to a schema validation error or missing imports.
+                  </Text>
+                  <Text size="xs" weight="semibold" color="secondary">
+                    Error:
+                  </Text>
+                  <Box
+                    as="pre"
+                    padding="sm"
+                    background="tertiary"
+                    rounded="sm"
+                    style={{
+                      fontFamily: "monospace",
+                      fontSize: "11px",
+                      whiteSpace: "pre-wrap",
+                      wordBreak: "break-word",
+                      margin: 0,
+                      maxHeight: "200px",
+                      overflow: "auto",
+                    }}
+                  >
+                    {errorMessage}
+                  </Box>
+                </>
+              )}
+            </Stack>
+          </Alert.Content>
+        </Alert.Body>
+      </Alert>
+    </Stack>
+  );
+}