design-folio 0.1.0

package/src/viewer/GalleryView.jsx

@@ -0,0 +1,103 @@
+import React, { useState, useEffect } from 'react';
+import SimulatedWindow from './SimulatedWindow.jsx';
+import DesignNotes from './DesignNotes.jsx';
+import ScreensToolbar from './ScreensToolbar.jsx';
+
+export default function GalleryView({
+  states,
+  activeKey,
+  viewport,
+  syncTheme,
+  isDark,
+  onNavigateToScreen,
+  viewMode,
+  onToggleView,
+  uiHidden,
+  onToggleUI,
+  children,
+}) {
+  const currentIndex = states.findIndex((s) => s.key === activeKey);
+  const activeState = states[currentIndex];
+  const isFirst = currentIndex <= 0;
+  const isLast = currentIndex >= states.length - 1;
+
+  const [copied, setCopied] = useState(false);
+
+  function handleCopyLink() {
+    navigator.clipboard.writeText(window.location.href);
+    setCopied(true);
+    setTimeout(() => setCopied(false), 2000);
+  }
+
+  function handlePrev() {
+    if (!isFirst) {
+      onNavigateToScreen(states[currentIndex - 1].key);
+    }
+  }
+
+  function handleNext() {
+    if (!isLast) {
+      onNavigateToScreen(states[currentIndex + 1].key);
+    }
+  }
+
+  // Arrow key navigation
+  useEffect(() => {
+    function onKeyDown(e) {
+      if (e.key === 'ArrowLeft' && currentIndex > 0) {
+        onNavigateToScreen(states[currentIndex - 1].key);
+      }
+      if (e.key === 'ArrowRight' && currentIndex < states.length - 1) {
+        onNavigateToScreen(states[currentIndex + 1].key);
+      }
+    }
+    window.addEventListener('keydown', onKeyDown);
+    return () => window.removeEventListener('keydown', onKeyDown);
+  }, [currentIndex, states, onNavigateToScreen]);
+
+  if (!activeState) return null;
+
+  return (
+    <section
+      className="flex flex-col h-full bg-neutral-50 dark:bg-neutral-950"
+      role="tabpanel"
+      aria-label="Gallery view"
+    >
+      {/* Toolbar — fixed at top, not scrollable */}
+      <div className="shrink-0 px-5 pt-5">
+        <ScreensToolbar
+          viewMode={viewMode}
+          onToggleView={onToggleView}
+          uiHidden={uiHidden}
+          onToggleUI={onToggleUI}
+          onPrev={handlePrev}
+          onNext={handleNext}
+          isFirst={isFirst}
+          isLast={isLast}
+          currentIndex={currentIndex}
+          totalScreens={states.length}
+          onCopyLink={handleCopyLink}
+          copied={copied}
+        />
+      </div>
+
+      {/* Scrollable content */}
+      <div className="flex-1 overflow-y-auto px-5 pb-5">
+        {/* Screen title */}
+        <h2 className="text-2xl font-semibold text-neutral-800 dark:text-neutral-200 mb-4 mt-4 shrink-0">
+          {activeState.name}
+        </h2>
+
+        {/* Screen + notes share one container so notes match screen width */}
+        <div className="max-w-full" style={{ width: 'fit-content' }}>
+          <div className="pointer-events-none">
+            <SimulatedWindow viewport={viewport} syncTheme={syncTheme} isDark={isDark} fixed>
+              {typeof children === 'function' ? children(activeState) : React.isValidElement(children) ? React.cloneElement(children, { appState: activeState.state }) : children}
+            </SimulatedWindow>
+          </div>
+          <DesignNotes notes={activeState.notes} />
+        </div>
+      </div>
+    </section>
+  );
+}

package/src/viewer/Header.jsx

@@ -0,0 +1,30 @@
+import ThemeToggle from './ThemeToggle.jsx';
+
+function formatDate(dateStr) {
+  if (!dateStr) return null;
+  const date = new Date(dateStr);
+  if (isNaN(date.getTime())) return null;
+  return date.toLocaleDateString('en-US', { month: 'short', day: 'numeric', year: 'numeric' });
+}
+
+export default function Header({ name, designer, updatedAt, isDark, onToggleTheme }) {
+  const formattedDate = formatDate(updatedAt);
+  const subtitleParts = [];
+  if (designer) subtitleParts.push(designer);
+  if (formattedDate) subtitleParts.push(`Updated ${formattedDate}`);
+  const subtitle = subtitleParts.join(' · ');
+
+  return (
+    <header className="flex items-center justify-between px-5 py-3 bg-white dark:bg-neutral-900 border-b border-neutral-300 dark:border-neutral-700">
+      <hgroup>
+        <h1 className="text-sm font-semibold text-neutral-900 dark:text-white">
+          {name || 'Untitled'}
+        </h1>
+        {subtitle && (
+          <p className="text-xs text-neutral-500 dark:text-neutral-400">{subtitle}</p>
+        )}
+      </hgroup>
+      <ThemeToggle isDark={isDark} onToggle={onToggleTheme} />
+    </header>
+  );
+}

package/src/viewer/PrototypeTab.jsx

@@ -0,0 +1,20 @@
+import SimulatedWindow from './SimulatedWindow.jsx';
+
+export default function PrototypeTab({
+  viewport,
+  syncTheme,
+  isDark,
+  children,
+}) {
+  return (
+    <div className="flex h-full" role="tabpanel" aria-label="Prototype view">
+      <main className="flex-1 p-5 flex flex-col bg-neutral-50 dark:bg-neutral-950 overflow-hidden">
+        <div className="flex-1 w-full min-h-0">
+          <SimulatedWindow viewport={viewport} syncTheme={syncTheme} isDark={isDark} fillHeight>
+            {children}
+          </SimulatedWindow>
+        </div>
+      </main>
+    </div>
+  );
+}

package/src/viewer/ScreenFrame.jsx

@@ -0,0 +1,36 @@
+import SimulatedWindow from './SimulatedWindow.jsx';
+
+/**
+ * ScreenFrame – renders a single prototype state as a labelled, non-interactive
+ * preview with a clickable title that navigates to the Prototype tab.
+ *
+ * Props:
+ *   state       – { key, name, notes, ... }
+ *   viewport    – viewport preset string or { width, height } object
+ *   syncTheme   – boolean
+ *   isDark      – boolean
+ *   onNavigate  – callback(key) – called when title button is clicked
+ *   children    – rendered prototype content
+ */
+export default function ScreenFrame({ state, viewport, syncTheme, isDark, onNavigate, children }) {
+  return (
+    <div className="flex flex-col items-start" data-screen-key={state.key}>
+      {/* Clickable state name */}
+      <button
+        type="button"
+        onClick={() => onNavigate(state.key)}
+        className="mb-4 text-4xl font-semibold text-neutral-600 dark:text-neutral-400 hover:text-black dark:hover:text-white hover:underline transition-colors cursor-pointer"
+      >
+        {state.name}
+      </button>
+
+      {/* Non-interactive preview */}
+      <div className="pointer-events-none">
+        <SimulatedWindow viewport={viewport} syncTheme={syncTheme} isDark={isDark} fixed>
+          {children}
+        </SimulatedWindow>
+      </div>
+
+    </div>
+  );
+}

package/src/viewer/ScreensTab.jsx

@@ -0,0 +1,158 @@
+import React, { useRef, useEffect } from 'react';
+import { groupStates } from './StatePicker.jsx';
+
+function chunk(arr, size) {
+  const rows = [];
+  for (let i = 0; i < arr.length; i += size) {
+    rows.push(arr.slice(i, i + size));
+  }
+  return rows;
+}
+import ScreensToolbar from './ScreensToolbar.jsx';
+import ScreenFrame from './ScreenFrame.jsx';
+import { usePanZoom } from '../hooks/usePanZoom.js';
+
+export default function ScreensTab({
+  states,
+  viewport,
+  syncTheme,
+  isDark,
+  onNavigateToState,
+  uiHidden,
+  onToggleUI,
+  viewMode,
+  onToggleView,
+  children,
+}) {
+  const containerRef = useRef(null);
+  const contentRef = useRef(null);
+
+  const { zoom, offset, setOffset, setZoom, fitToView, handlers } = usePanZoom(containerRef);
+
+  // Listen for scroll-to-screen events from sidebar navigation
+  useEffect(() => {
+    function handleScrollToScreen(e) {
+      const { key } = e.detail;
+      const el = document.querySelector(`[data-screen-key="${key}"]`);
+      const container = containerRef.current;
+      const content = contentRef.current;
+      if (!el || !container || !content) return;
+
+      // Get the element's position relative to the content container (at natural scale)
+      const elRect = el.getBoundingClientRect();
+      const contentRect = content.getBoundingClientRect();
+
+      // Convert screen coordinates back to content coordinates
+      const elX = (elRect.left - contentRect.left) / zoom;
+      const elY = (elRect.top - contentRect.top) / zoom;
+      const elW = elRect.width / zoom;
+      const elH = elRect.height / zoom;
+
+      const containerRect = container.getBoundingClientRect();
+
+      // Center the element in the container
+      const newOffsetX = containerRect.width / 2 - (elX + elW / 2) * zoom;
+      const newOffsetY = containerRect.height / 2 - (elY + elH / 2) * zoom;
+
+      setOffset({ x: newOffsetX, y: newOffsetY });
+    }
+
+    window.addEventListener('folio:scroll-to-screen', handleScrollToScreen);
+    return () => window.removeEventListener('folio:scroll-to-screen', handleScrollToScreen);
+  }, [zoom, setOffset]);
+
+  const handleFit = () => fitToView(contentRef);
+
+  const stepZoom = (direction) => {
+    const container = containerRef.current;
+    if (!container) return;
+    const rect = container.getBoundingClientRect();
+    const centerX = rect.left + rect.width / 2;
+    const centerY = rect.top + rect.height / 2;
+
+    const event = new WheelEvent('wheel', {
+      bubbles: true,
+      cancelable: true,
+      ctrlKey: true,
+      clientX: centerX,
+      clientY: centerY,
+      deltaY: direction * -100,
+    });
+    container.dispatchEvent(event);
+  };
+
+  const groups = groupStates(states);
+
+  return (
+    <section
+      className="flex flex-col h-full"
+      role="tabpanel"
+      aria-label="Screens view"
+    >
+      <div className="shrink-0 px-5 pt-5">
+        <ScreensToolbar
+          viewMode={viewMode}
+          onToggleView={onToggleView}
+          zoom={zoom}
+          uiHidden={uiHidden}
+          onToggleUI={onToggleUI}
+          onZoomIn={() => stepZoom(1)}
+          onZoomOut={() => stepZoom(-1)}
+          onFit={handleFit}
+          inline
+        />
+      </div>
+
+      <div
+        ref={containerRef}
+        className="flex-1 overflow-hidden relative bg-neutral-50 dark:bg-neutral-950 cursor-grab active:cursor-grabbing"
+        {...handlers}
+        style={{ touchAction: 'none' }}
+      >
+        <div
+          ref={contentRef}
+          style={{
+            transform: `translate(${offset.x}px, ${offset.y}px) scale(${zoom})`,
+            transformOrigin: '0 0',
+            position: 'absolute',
+            top: 0,
+            left: 0,
+          }}
+        >
+          <div className="grid p-12" style={{ width: 'max-content', gridTemplateColumns: 'auto 1fr', gap: '0 2.5rem' }}>
+            {groups.map(({ group, states: groupStates }, i) => (
+              <React.Fragment key={group}>
+                {i > 0 && (
+                  <hr className="border-t border-neutral-200 dark:border-neutral-800 my-16 col-span-2" />
+                )}
+                <div className="pt-10 whitespace-nowrap self-start">
+                  <h2 className="text-5xl font-bold text-neutral-800 dark:text-neutral-200">
+                    {group}
+                  </h2>
+                </div>
+                <div className="flex flex-col gap-10">
+                  {chunk(groupStates, 4).map((row, rowIdx) => (
+                    <div key={rowIdx} className="flex gap-10">
+                      {row.map((state) => (
+                        <ScreenFrame
+                          key={state.key}
+                          state={state}
+                          viewport={viewport}
+                          syncTheme={syncTheme}
+                          isDark={isDark}
+                          onNavigate={onNavigateToState}
+                        >
+                          {typeof children === 'function' ? children(state) : React.isValidElement(children) ? React.cloneElement(children, { appState: state.state }) : children}
+                        </ScreenFrame>
+                      ))}
+                    </div>
+                  ))}
+                </div>
+              </React.Fragment>
+            ))}
+          </div>
+        </div>
+      </div>
+    </section>
+  );
+}

package/src/viewer/ScreensToolbar.jsx

@@ -0,0 +1,134 @@
+import { GridIcon, SquareIcon, ChevronLeftIcon, ChevronRightIcon, LinkIcon } from '../icons.jsx';
+
+/**
+ * ScreensToolbar – view toggle, zoom controls, and gallery navigation for the Screens tab.
+ *
+ * Height math (all elements = 30px):
+ *   Secondary buttons: border(2) + py-1.5(12) + text(16) = 30
+ *   Containers:        border(2) + py-1.5(12) + content(16) = 30
+ *     Inner buttons have py-0 so they don't add height.
+ *     Icons are w-4 h-4 (16px) to match text line-height.
+ */
+export default function ScreensToolbar({
+  viewMode,
+  onToggleView,
+  zoom,
+  onZoomIn,
+  onZoomOut,
+  onFit,
+  uiHidden,
+  onToggleUI,
+  // Gallery-only props
+  onPrev,
+  onNext,
+  isFirst,
+  isLast,
+  currentIndex,
+  totalScreens,
+  onCopyLink,
+  copied,
+}) {
+  // Inner buttons: equal padding on all sides for square icon buttons
+  const btnClass = "text-xs text-neutral-500 dark:text-neutral-400 hover:text-black dark:hover:text-white hover:bg-neutral-100 dark:hover:bg-neutral-800 transition-colors cursor-pointer p-1 rounded-md";
+  // Standalone buttons: own border + padding
+  const secondaryBtnClass = "text-xs text-neutral-600 dark:text-neutral-300 border border-neutral-200 dark:border-neutral-700 hover:border-neutral-400 dark:hover:border-neutral-500 hover:text-black dark:hover:text-white transition-colors cursor-pointer px-3 py-1.5 rounded-lg";
+  // Container: border + small padding, buttons provide the rest
+  const groupClass = "flex items-center border border-neutral-200 dark:border-neutral-700 rounded-lg p-0.5 gap-0.5";
+
+  return (
+    <nav aria-label="Screen controls" className="flex items-center justify-between w-full px-3 py-2 bg-white dark:bg-neutral-900 border border-neutral-200 dark:border-neutral-700 rounded-xl shrink-0">
+      <div className="flex items-center gap-3">
+        {/* Hide/Show UI — left-most */}
+        {onToggleUI && (
+          <button
+            onClick={onToggleUI}
+            className={secondaryBtnClass}
+            aria-label={uiHidden ? 'Show UI' : 'Hide UI'}
+            aria-pressed={uiHidden}
+          >
+            {uiHidden ? 'Show UI' : 'Hide UI'}
+          </button>
+        )}
+
+        {/* Grid / Gallery toggle */}
+        <div className={groupClass} role="toolbar" aria-label="View mode">
+          <button
+            onClick={() => onToggleView('grid')}
+            className={`${btnClass} ${viewMode === 'grid' ? 'bg-neutral-100 dark:bg-neutral-800' : ''}`}
+            aria-label="Grid view"
+            aria-pressed={viewMode === 'grid'}
+          >
+            <GridIcon className="w-4 h-4" />
+          </button>
+          <button
+            onClick={() => onToggleView('gallery')}
+            className={`${btnClass} ${viewMode === 'gallery' ? 'bg-neutral-100 dark:bg-neutral-800' : ''}`}
+            aria-label="Gallery view"
+            aria-pressed={viewMode === 'gallery'}
+          >
+            <SquareIcon className="w-4 h-4" />
+          </button>
+        </div>
+
+        {/* Zoom controls — only in grid mode */}
+        {viewMode === 'grid' && (
+          <div className={groupClass} role="toolbar" aria-label="Zoom">
+            <button onClick={onZoomOut} className={`${btnClass} w-6 h-6 flex items-center justify-center text-sm leading-none !p-0`} aria-label="Zoom out">
+              −
+            </button>
+            <span className="text-xs tabular-nums text-neutral-400 dark:text-neutral-500 w-10 text-center select-none leading-none">
+              {Math.round(zoom * 100)}%
+            </span>
+            <button onClick={onZoomIn} className={`${btnClass} w-6 h-6 flex items-center justify-center text-sm leading-none !p-0`} aria-label="Zoom in">
+              +
+            </button>
+            <button onClick={onFit} className={`${btnClass} px-2`}>
+              Fit
+            </button>
+          </div>
+        )}
+
+        {/* Gallery nav — prev/next and position */}
+        {viewMode === 'gallery' && (
+          <div className={groupClass} role="toolbar" aria-label="Screen navigation">
+            <button
+              onClick={onPrev}
+              disabled={isFirst}
+              aria-label="Previous screen"
+              className={`${btnClass} disabled:opacity-30 disabled:cursor-default`}
+            >
+              <ChevronLeftIcon className="w-4 h-4" />
+            </button>
+            <span className="text-xs tabular-nums text-neutral-400 dark:text-neutral-500 w-10 text-center select-none leading-none">
+              {currentIndex + 1} / {totalScreens}
+            </span>
+            <button
+              onClick={onNext}
+              disabled={isLast}
+              aria-label="Next screen"
+              className={`${btnClass} disabled:opacity-30 disabled:cursor-default`}
+            >
+              <ChevronRightIcon className="w-4 h-4" />
+            </button>
+          </div>
+        )}
+      </div>
+
+      {/* Right side */}
+      {viewMode === 'grid' && (
+        <span className="text-xs text-neutral-400 dark:text-neutral-500 select-none">
+          Drag to pan · ⌘+scroll to zoom
+        </span>
+      )}
+      {viewMode === 'gallery' && onCopyLink && (
+        <button
+          onClick={onCopyLink}
+          className={`${secondaryBtnClass} flex items-center gap-1`}
+        >
+          <LinkIcon className="w-3 h-3" />
+          {copied ? 'Copied!' : 'Copy link'}
+        </button>
+      )}
+    </nav>
+  );
+}

package/src/viewer/Sidebar.jsx

@@ -0,0 +1,106 @@
+import { ClockIcon, ExternalLinkIcon } from '../icons.jsx';
+import { groupStates } from './StatePicker.jsx';
+
+function formatDate(dateStr) {
+  const date = new Date(dateStr + 'T00:00:00');
+  return date.toLocaleDateString('en-US', { month: 'short', day: 'numeric', year: 'numeric' });
+}
+
+export default function Sidebar({ tab, name, states, activeKey, onSelectState, changelog, onSelectDate, description, prototypeUrl }) {
+  return (
+    <aside className="w-52 shrink-0 ml-5 my-5 mr-3 p-4 bg-white dark:bg-neutral-900 border border-neutral-200 dark:border-neutral-700 rounded-xl overflow-y-auto self-start">
+      {tab === 'prototype' ? (
+        <ProjectInfo name={name} description={description} prototypeUrl={prototypeUrl} />
+      ) : tab === 'screens' ? (
+        <StatesList states={states} activeKey={activeKey} onSelect={onSelectState} />
+      ) : tab === 'changelog' ? (
+        <DatesList changelog={changelog} onSelect={onSelectDate} />
+      ) : null}
+    </aside>
+  );
+}
+
+function StatesList({ states, activeKey, onSelect }) {
+  const groups = groupStates(states);
+  return (
+    <>
+      <nav aria-label="Screen states">
+        {groups.map(({ group, states: groupStates }) => (
+          <section key={group} className="mb-3">
+            {group !== 'Ungrouped' && (
+              <h3 className="text-xs font-semibold text-neutral-500 dark:text-neutral-400 mb-1">{group}</h3>
+            )}
+            <ul className="list-none m-0 p-0">
+              {groupStates.map((state) => {
+                const isActive = state.key === activeKey;
+                return (
+                  <li
+                    key={state.key}
+                    aria-current={isActive ? 'true' : undefined}
+                    className={`text-xs px-2 py-1.5 rounded mb-0.5 cursor-pointer transition-colors ${
+                      isActive
+                        ? 'bg-black dark:bg-white text-white dark:text-black font-medium'
+                        : 'text-neutral-800 dark:text-neutral-300 hover:bg-neutral-100 dark:hover:bg-neutral-800'
+                    }`}
+                    onClick={() => onSelect(state.key)}
+                  >
+                    {state.name}
+                  </li>
+                );
+              })}
+            </ul>
+          </section>
+        ))}
+      </nav>
+    </>
+  );
+}
+
+function DatesList({ changelog, onSelect }) {
+  return (
+    <>
+      <h2 className="flex items-center gap-1 text-xs font-semibold text-neutral-500 dark:text-neutral-400 uppercase tracking-wide mb-3">
+        <ClockIcon className="w-3.5 h-3.5" /> Dates
+      </h2>
+      <nav aria-label="Changelog dates">
+        <ul className="list-none m-0 p-0">
+          {changelog.map(({ date }) => (
+            <li
+              key={date}
+              className="text-xs px-2 py-1.5 rounded mb-0.5 cursor-pointer text-neutral-800 dark:text-neutral-300 hover:bg-neutral-100 dark:hover:bg-neutral-800 transition-colors"
+              onClick={() => onSelect?.(date)}
+            >
+              {formatDate(date)}
+            </li>
+          ))}
+        </ul>
+      </nav>
+    </>
+  );
+}
+
+function ProjectInfo({ name, description, prototypeUrl }) {
+  return (
+    <div>
+      {name && (
+        <h2 className="text-xs font-semibold text-neutral-500 dark:text-neutral-400 uppercase tracking-wide mb-3">
+          About
+        </h2>
+      )}
+      {description && (
+        <p className="text-xs text-neutral-600 dark:text-neutral-400 leading-relaxed mb-4">
+          {description}
+        </p>
+      )}
+      <a
+        href={prototypeUrl || '/'}
+        target="_blank"
+        rel="noopener noreferrer"
+        className="flex items-center gap-1.5 text-xs font-medium text-neutral-500 dark:text-neutral-400 hover:text-black dark:hover:text-white transition-colors"
+      >
+        <ExternalLinkIcon className="w-3.5 h-3.5" />
+        Open prototype
+      </a>
+    </div>
+  );
+}

package/src/viewer/SimulatedWindow.jsx

@@ -0,0 +1,47 @@
+import { VIEWPORT_PRESETS } from '../config/defaults.js';
+
+export default function SimulatedWindow({ viewport, children, syncTheme, isDark, fixed, fillHeight }) {
+  let dimensions;
+  if (typeof viewport === 'string') {
+    dimensions = VIEWPORT_PRESETS[viewport] ?? VIEWPORT_PRESETS.desktop;
+  } else if (viewport && typeof viewport === 'object') {
+    dimensions = viewport;
+  } else {
+    dimensions = VIEWPORT_PRESETS.desktop;
+  }
+
+  const isResponsive = dimensions.width === '100%';
+
+  let style;
+  if (fillHeight) {
+    // Fill available height — for prototype tab with iframe content
+    style = { width: '100%', height: '100%' };
+  } else if (fixed) {
+    // Fixed pixel dimensions for canvas/screens view
+    // Responsive falls back to wide-desktop dimensions so frames don't collapse
+    const fixedDimensions = isResponsive
+      ? { width: 1440, height: 900 }
+      : dimensions;
+    style = { width: `${fixedDimensions.width}px`, height: `${fixedDimensions.height}px`, maxWidth: '100%' };
+  } else {
+    // Fluid — fills available width, maintains aspect ratio
+    style = isResponsive
+      ? { width: '100%', height: 'auto', minHeight: '400px' }
+      : { width: '100%', aspectRatio: `${dimensions.width} / ${dimensions.height}` };
+  }
+
+  let themeClass = '';
+  if (syncTheme) {
+    themeClass = isDark ? ' folio-theme-dark' : ' folio-theme-light';
+  }
+
+  return (
+    <figure
+      aria-label="Prototype window"
+      style={style}
+      className={`relative bg-white dark:bg-neutral-800 border border-neutral-300 dark:border-neutral-700 rounded-lg shadow-sm dark:shadow-lg overflow-hidden${themeClass}`}
+    >
+      {children}
+    </figure>
+  );
+}