@fragments-sdk/cli 0.2.2

package/src/viewer/components/SkeletonLoader.tsx

@@ -0,0 +1,156 @@
+/**
+ * Skeleton Loading Components
+ *
+ * Shows animated placeholders while the app is loading.
+ */
+
+import clsx from "clsx";
+
+interface SkeletonProps {
+  className?: string;
+}
+
+function Skeleton({ className }: SkeletonProps) {
+  return (
+    <div
+      className={clsx(
+        "animate-pulse bg-[--bg-hover] rounded",
+        className
+      )}
+    />
+  );
+}
+
+/**
+ * Full app skeleton shown during initial load
+ */
+export function AppSkeleton() {
+  return (
+    <div className="flex h-screen bg-[--bg-primary]">
+      {/* Sidebar skeleton */}
+      <div className="w-60 border-r border-[--border] bg-[--bg-secondary] flex flex-col">
+        {/* Header */}
+        <div className="flex items-center justify-between px-4 py-2 border-b border-[--border]">
+          <Skeleton className="w-20 h-5" />
+          <Skeleton className="w-6 h-6 rounded-md" />
+        </div>
+
+        {/* Search */}
+        <div className="px-3 py-3">
+          <Skeleton className="w-full h-8 rounded-md" />
+        </div>
+
+        {/* Component list */}
+        <div className="flex-1 px-2 space-y-4 overflow-hidden">
+          {/* Category 1 */}
+          <div>
+            <Skeleton className="w-16 h-3 mx-2 mb-2" />
+            <div className="space-y-1">
+              <Skeleton className="w-full h-7 rounded-md" />
+              <Skeleton className="w-full h-7 rounded-md" />
+              <Skeleton className="w-3/4 h-7 rounded-md" />
+            </div>
+          </div>
+
+          {/* Category 2 */}
+          <div>
+            <Skeleton className="w-20 h-3 mx-2 mb-2" />
+            <div className="space-y-1">
+              <Skeleton className="w-full h-7 rounded-md" />
+              <Skeleton className="w-5/6 h-7 rounded-md" />
+              <Skeleton className="w-full h-7 rounded-md" />
+              <Skeleton className="w-2/3 h-7 rounded-md" />
+            </div>
+          </div>
+
+          {/* Category 3 */}
+          <div>
+            <Skeleton className="w-24 h-3 mx-2 mb-2" />
+            <div className="space-y-1">
+              <Skeleton className="w-4/5 h-7 rounded-md" />
+              <Skeleton className="w-full h-7 rounded-md" />
+            </div>
+          </div>
+        </div>
+
+        {/* Footer */}
+        <div className="px-4 py-3 border-t border-[--border-subtle]">
+          <Skeleton className="w-24 h-3" />
+        </div>
+      </div>
+
+      {/* Main content skeleton */}
+      <div className="flex-1 flex flex-col">
+        {/* Toolbar */}
+        <div className="flex items-center justify-between px-4 py-2 border-b border-[--border] bg-[--bg-secondary]">
+          <div className="flex items-center gap-3">
+            <Skeleton className="w-24 h-5" />
+            <Skeleton className="w-16 h-4" />
+          </div>
+          <div className="flex items-center gap-2">
+            <Skeleton className="w-16 h-7 rounded" />
+            <Skeleton className="w-24 h-7 rounded" />
+            <Skeleton className="w-20 h-7 rounded" />
+            <Skeleton className="w-6 h-6 rounded" />
+            <Skeleton className="w-6 h-6 rounded" />
+          </div>
+        </div>
+
+        {/* Variant tabs */}
+        <div className="px-4 py-2 border-b border-[--border] bg-[--bg-primary]">
+          <div className="flex items-center gap-2">
+            <Skeleton className="w-16 h-7 rounded-md" />
+            <Skeleton className="w-20 h-7 rounded-md" />
+            <Skeleton className="w-14 h-7 rounded-md" />
+            <Skeleton className="w-18 h-7 rounded-md" />
+            <Skeleton className="w-12 h-7 rounded-md" />
+          </div>
+        </div>
+
+        {/* Preview area */}
+        <div className="flex-1 flex items-center justify-center p-8">
+          <Skeleton className="w-64 h-32 rounded-lg" />
+        </div>
+
+        {/* Bottom panel */}
+        <div className="h-64 border-t border-[--border] bg-[--bg-secondary]">
+          <div className="flex items-center gap-1 px-4 h-10 border-b border-[--border-subtle]">
+            <Skeleton className="w-12 h-6 rounded" />
+            <Skeleton className="w-10 h-6 rounded" />
+            <Skeleton className="w-12 h-6 rounded" />
+          </div>
+          <div className="p-4 space-y-3">
+            <div className="flex items-center gap-4">
+              <Skeleton className="w-20 h-4" />
+              <Skeleton className="w-32 h-8 rounded" />
+            </div>
+            <div className="flex items-center gap-4">
+              <Skeleton className="w-16 h-4" />
+              <Skeleton className="w-24 h-8 rounded" />
+            </div>
+            <div className="flex items-center gap-4">
+              <Skeleton className="w-24 h-4" />
+              <Skeleton className="w-20 h-8 rounded" />
+            </div>
+          </div>
+        </div>
+      </div>
+    </div>
+  );
+}
+
+/**
+ * Component preview skeleton
+ */
+export function PreviewSkeleton() {
+  return (
+    <div className="flex items-center justify-center p-8">
+      <div className="text-center space-y-3">
+        <div className="animate-spin w-8 h-8 border-2 border-[--border] border-t-[--color-accent] rounded-full mx-auto" />
+        <p className="text-sm text-tertiary">Loading component...</p>
+      </div>
+    </div>
+  );
+}
+
+export default AppSkeleton;

package/src/viewer/components/StoryRenderer.tsx

@@ -0,0 +1,128 @@
+import { useState, useEffect, useMemo, type ReactNode } from "react";
+import type { SegmentVariant } from "../../core/index.js";
+
+interface StoryRendererProps {
+  /** The variant to render */
+  variant: SegmentVariant;
+  /** Children render function - receives rendered content */
+  children: (content: ReactNode | null, isLoading: boolean, error: Error | null) => ReactNode;
+}
+
+/**
+ * Component that handles async loader execution before rendering a story variant.
+ *
+ * If the variant has loaders:
+ * 1. Shows loading state while loaders execute
+ * 2. Merges all loaded data
+ * 3. Passes loaded data to render function
+ *
+ * If no loaders, renders immediately.
+ */
+export function StoryRenderer({ variant, children }: StoryRendererProps) {
+  const [loadedData, setLoadedData] = useState<Record<string, unknown> | null>(null);
+  const [isLoading, setIsLoading] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  const hasLoaders = variant.loaders && variant.loaders.length > 0;
+
+  useEffect(() => {
+    // Reset state when variant changes
+    setLoadedData(null);
+    setError(null);
+
+    if (!hasLoaders) {
+      return;
+    }
+
+    let cancelled = false;
+    setIsLoading(true);
+
+    async function executeLoaders() {
+      try {
+        // Execute all loaders in parallel
+        const results = await Promise.all(
+          variant.loaders!.map((loader) => loader())
+        );
+
+        if (cancelled) return;
+
+        // Merge all loaded data (later loaders override earlier ones)
+        const merged = results.reduce(
+          (acc, result) => ({ ...acc, ...result }),
+          {}
+        );
+
+        setLoadedData(merged);
+        setError(null);
+      } catch (err) {
+        if (cancelled) return;
+        setError(err instanceof Error ? err : new Error(String(err)));
+      } finally {
+        if (!cancelled) {
+          setIsLoading(false);
+        }
+      }
+    }
+
+    executeLoaders();
+
+    return () => {
+      cancelled = true;
+    };
+  }, [variant, hasLoaders]);
+
+  // If loading, pass null content with loading flag
+  if (hasLoaders && isLoading) {
+    return <>{children(null, true, null)}</>;
+  }
+
+  // If error during loading, pass error
+  if (error) {
+    return <>{children(null, false, error)}</>;
+  }
+
+  // Build render options with loaded data only
+  const renderOptions = useMemo(() => ({
+    loadedData: hasLoaders ? loadedData ?? undefined : undefined,
+  }), [hasLoaders, loadedData]);
+
+  // Render the variant with options
+  try {
+    const content = variant.render(renderOptions);
+    return <>{children(content, false, null)}</>;
+  } catch (err) {
+    const renderError = err instanceof Error ? err : new Error(String(err));
+    return <>{children(null, false, renderError)}</>;
+  }
+}
+
+/**
+ * Loading indicator for stories with loaders
+ */
+export function LoaderIndicator() {
+  return (
+    <div className="flex items-center gap-2 text-secondary text-sm">
+      <svg
+        className="animate-spin h-4 w-4"
+        xmlns="http://www.w3.org/2000/svg"
+        fill="none"
+        viewBox="0 0 24 24"
+      >
+        <circle
+          className="opacity-25"
+          cx="12"
+          cy="12"
+          r="10"
+          stroke="currentColor"
+          strokeWidth="4"
+        />
+        <path
+          className="opacity-75"
+          fill="currentColor"
+          d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4zm2 5.291A7.962 7.962 0 014 12H0c0 3.042 1.135 5.824 3 7.938l3-2.647z"
+        />
+      </svg>
+      <span>Running loaders...</span>
+    </div>
+  );
+}

package/src/viewer/components/ThemeProvider.tsx

@@ -0,0 +1,96 @@
+import { createContext, useContext, useEffect, useState, useCallback, type ReactNode } from 'react';
+import { BRAND } from '../../core/index.js';
+
+type Theme = 'light' | 'dark' | 'system';
+
+interface ThemeContextValue {
+  theme: Theme;
+  resolvedTheme: 'light' | 'dark';
+  setTheme: (theme: Theme) => void;
+}
+
+const ThemeContext = createContext<ThemeContextValue | null>(null);
+
+const STORAGE_KEY = `${BRAND.storagePrefix}theme`;
+
+function getSystemTheme(): 'light' | 'dark' {
+  if (typeof window === 'undefined') return 'light';
+  return window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
+}
+
+function getStoredTheme(): Theme {
+  if (typeof window === 'undefined') return 'system';
+  const stored = localStorage.getItem(STORAGE_KEY);
+  if (stored === 'light' || stored === 'dark' || stored === 'system') {
+    return stored;
+  }
+  return 'system';
+}
+
+export function ThemeProvider({ children }: { children: ReactNode }) {
+  const [theme, setThemeState] = useState<Theme>(getStoredTheme);
+  const [resolvedTheme, setResolvedTheme] = useState<'light' | 'dark'>(() => {
+    const stored = getStoredTheme();
+    return stored === 'system' ? getSystemTheme() : stored;
+  });
+
+  const setTheme = useCallback((newTheme: Theme) => {
+    setThemeState(newTheme);
+    localStorage.setItem(STORAGE_KEY, newTheme);
+
+    // Immediately update resolved theme to avoid timing issues
+    const resolved = newTheme === 'system' ? getSystemTheme() : newTheme;
+    setResolvedTheme(resolved);
+
+    // Immediately apply to document
+    if (resolved === 'dark') {
+      document.documentElement.classList.add('dark');
+    } else {
+      document.documentElement.classList.remove('dark');
+    }
+  }, []);
+
+  // Update resolved theme and apply to document
+  useEffect(() => {
+    const resolved = theme === 'system' ? getSystemTheme() : theme;
+    setResolvedTheme(resolved);
+
+    if (resolved === 'dark') {
+      document.documentElement.classList.add('dark');
+    } else {
+      document.documentElement.classList.remove('dark');
+    }
+  }, [theme]);
+
+  // Listen for system theme changes
+  useEffect(() => {
+    if (theme !== 'system') return;
+
+    const mediaQuery = window.matchMedia('(prefers-color-scheme: dark)');
+    const handler = (e: MediaQueryListEvent) => {
+      setResolvedTheme(e.matches ? 'dark' : 'light');
+      if (e.matches) {
+        document.documentElement.classList.add('dark');
+      } else {
+        document.documentElement.classList.remove('dark');
+      }
+    };
+
+    mediaQuery.addEventListener('change', handler);
+    return () => mediaQuery.removeEventListener('change', handler);
+  }, [theme]);
+
+  return (
+    <ThemeContext.Provider value={{ theme, resolvedTheme, setTheme }}>
+      {children}
+    </ThemeContext.Provider>
+  );
+}
+
+export function useTheme() {
+  const context = useContext(ThemeContext);
+  if (!context) {
+    throw new Error('useTheme must be used within a ThemeProvider');
+  }
+  return context;
+}

package/src/viewer/components/Toast.tsx

@@ -0,0 +1,67 @@
+import { useEffect, useState } from 'react';
+import { CheckIcon, WarningIcon, RefreshIcon } from './Icons.js';
+
+export interface ToastMessage {
+  id: string;
+  type: 'success' | 'error' | 'info';
+  message: string;
+  duration?: number;
+}
+
+interface ToastProps {
+  messages: ToastMessage[];
+  onDismiss: (id: string) => void;
+}
+
+export function Toast({ messages, onDismiss }: ToastProps) {
+  return (
+    <div className="fixed bottom-4 right-4 z-50 flex flex-col gap-2">
+      {messages.map((toast) => (
+        <ToastItem key={toast.id} toast={toast} onDismiss={onDismiss} />
+      ))}
+    </div>
+  );
+}
+
+function ToastItem({ toast, onDismiss }: { toast: ToastMessage; onDismiss: (id: string) => void }) {
+  const [isVisible, setIsVisible] = useState(false);
+
+  useEffect(() => {
+    // Animate in
+    requestAnimationFrame(() => setIsVisible(true));
+
+    // Auto-dismiss
+    const timer = setTimeout(() => {
+      setIsVisible(false);
+      setTimeout(() => onDismiss(toast.id), 200);
+    }, toast.duration || 3000);
+
+    return () => clearTimeout(timer);
+  }, [toast.id, toast.duration, onDismiss]);
+
+  const iconMap = {
+    success: <CheckIcon className="w-4 h-4 text-emerald-500" />,
+    error: <WarningIcon className="w-4 h-4 text-red-500" />,
+    info: <RefreshIcon className="w-4 h-4 text-blue-500" />,
+  };
+
+  const bgMap = {
+    success: 'bg-emerald-500/10 border-emerald-500/20',
+    error: 'bg-red-500/10 border-red-500/20',
+    info: 'bg-blue-500/10 border-blue-500/20',
+  };
+
+  return (
+    <div
+      className={`
+        flex items-center gap-2 px-3 py-2 rounded-lg border backdrop-blur-sm
+        shadow-lg transition-all duration-200 ease-out
+        ${bgMap[toast.type]}
+        ${isVisible ? 'opacity-100 translate-y-0' : 'opacity-0 translate-y-2'}
+      `}
+    >
+      {iconMap[toast.type]}
+      <span className="text-sm text-primary font-medium">{toast.message}</span>
+    </div>
+  );
+}