@fragments-sdk/viewer 0.2.1

package/src/hooks/useUrlState.ts

@@ -0,0 +1,318 @@
+/**
+ * URL State Management Hook
+ *
+ * Manages URL-based state for deep linking and sharing:
+ * - Component path
+ * - Variant index/name
+ * - Edited props
+ * - View settings (zoom, viewport)
+ *
+ * URL format: #/ComponentName/VariantName?props=base64&zoom=100
+ */
+
+import { useState, useEffect, useCallback, useMemo } from "react";
+
+export interface UrlState {
+  /** Component path or name */
+  component: string | null;
+  /** Variant name or index */
+  variant: string | null;
+  /** Encoded props */
+  props: Record<string, unknown>;
+  /** View settings */
+  zoom: number;
+  viewport: string;
+  customWidth: number | null;
+  customHeight: number | null;
+}
+
+const DEFAULT_STATE: UrlState = {
+  component: null,
+  variant: null,
+  props: {},
+  zoom: 100,
+  viewport: "responsive",
+  customWidth: null,
+  customHeight: null,
+};
+
+/**
+ * Encode props to a URL-safe base64 string
+ */
+function encodeProps(props: Record<string, unknown>): string | null {
+  if (Object.keys(props).length === 0) return null;
+  try {
+    const json = JSON.stringify(props);
+    return btoa(encodeURIComponent(json));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Decode props from a URL-safe base64 string
+ */
+function decodeProps(encoded: string): Record<string, unknown> {
+  try {
+    const json = decodeURIComponent(atob(encoded));
+    return JSON.parse(json);
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Parse the current URL into state
+ */
+function parseUrl(): UrlState {
+  const state = { ...DEFAULT_STATE };
+
+  try {
+    const hash = window.location.hash.slice(1); // Remove leading #
+    const [path, queryString] = hash.split("?");
+    const params = new URLSearchParams(queryString || "");
+
+    // Parse path: /ComponentName/VariantName
+    if (path) {
+      const parts = path.split("/").filter(Boolean);
+      if (parts.length >= 1) {
+        state.component = decodeURIComponent(parts[0]);
+      }
+      if (parts.length >= 2) {
+        state.variant = decodeURIComponent(parts[1]);
+      }
+    }
+
+    // Parse query params
+    const propsParam = params.get("props");
+    if (propsParam) {
+      state.props = decodeProps(propsParam);
+    }
+
+    const zoom = params.get("zoom");
+    if (zoom) {
+      const zoomNum = parseInt(zoom, 10);
+      if ([50, 75, 100, 150, 200].includes(zoomNum)) {
+        state.zoom = zoomNum;
+      }
+    }
+
+    const viewport = params.get("viewport");
+    if (viewport && ["responsive", "desktop", "tablet", "mobile", "custom"].includes(viewport)) {
+      state.viewport = viewport;
+    }
+
+    const vw = params.get("vw");
+    if (vw) {
+      state.customWidth = parseInt(vw, 10) || null;
+    }
+
+    const vh = params.get("vh");
+    if (vh) {
+      state.customHeight = parseInt(vh, 10) || null;
+    }
+  } catch {
+    // Return default state on parse error
+  }
+
+  return state;
+}
+
+/**
+ * Build a URL from state
+ */
+function buildUrl(state: Partial<UrlState>): string {
+  const parts: string[] = [];
+
+  // Build path
+  if (state.component) {
+    parts.push(encodeURIComponent(state.component));
+    if (state.variant) {
+      parts.push(encodeURIComponent(state.variant));
+    }
+  }
+
+  const path = parts.length > 0 ? `/${parts.join("/")}` : "";
+
+  // Build query params
+  const params = new URLSearchParams();
+
+  if (state.props && Object.keys(state.props).length > 0) {
+    const encoded = encodeProps(state.props);
+    if (encoded) {
+      params.set("props", encoded);
+    }
+  }
+
+  if (state.zoom && state.zoom !== 100) {
+    params.set("zoom", String(state.zoom));
+  }
+
+  if (state.viewport && state.viewport !== "responsive") {
+    params.set("viewport", state.viewport);
+  }
+
+  if (state.viewport === "custom") {
+    if (state.customWidth) {
+      params.set("vw", String(state.customWidth));
+    }
+    if (state.customHeight) {
+      params.set("vh", String(state.customHeight));
+    }
+  }
+
+  const queryString = params.toString();
+  return `#${path}${queryString ? `?${queryString}` : ""}`;
+}
+
+/**
+ * Hook to manage URL-based state
+ */
+export function useUrlState() {
+  const [state, setState] = useState<UrlState>(parseUrl);
+
+  // Update state when URL changes (browser back/forward)
+  useEffect(() => {
+    const handleHashChange = () => {
+      setState(parseUrl());
+    };
+
+    window.addEventListener("hashchange", handleHashChange);
+    window.addEventListener("popstate", handleHashChange);
+
+    return () => {
+      window.removeEventListener("hashchange", handleHashChange);
+      window.removeEventListener("popstate", handleHashChange);
+    };
+  }, []);
+
+  // Update URL when state changes
+  const updateUrl = useCallback((updates: Partial<UrlState>, replace = false) => {
+    setState((prev) => {
+      const newState = { ...prev, ...updates };
+      const url = buildUrl(newState);
+
+      // Update URL without triggering hashchange event
+      if (replace) {
+        window.history.replaceState(null, "", url);
+      } else {
+        window.history.pushState(null, "", url);
+      }
+
+      return newState;
+    });
+  }, []);
+
+  // Set component (creates new history entry)
+  const setComponent = useCallback(
+    (component: string | null, variant?: string | null) => {
+      updateUrl({
+        component,
+        variant: variant ?? null,
+        props: {}, // Reset props when changing component
+      });
+    },
+    [updateUrl]
+  );
+
+  // Set variant (creates new history entry)
+  const setVariant = useCallback(
+    (variant: string | null) => {
+      updateUrl({
+        variant,
+        props: {}, // Reset props when changing variant
+      });
+    },
+    [updateUrl]
+  );
+
+  // Set props (replaces current history entry to avoid spam)
+  const setProps = useCallback(
+    (props: Record<string, unknown>) => {
+      updateUrl({ props }, true);
+    },
+    [updateUrl]
+  );
+
+  // Set view settings (replaces current history entry)
+  const setViewSettings = useCallback(
+    (settings: {
+      zoom?: number;
+      viewport?: string;
+      customWidth?: number | null;
+      customHeight?: number | null;
+    }) => {
+      updateUrl(settings, true);
+    },
+    [updateUrl]
+  );
+
+  // Get shareable URL
+  const getShareableUrl = useCallback(() => {
+    const url = new URL(window.location.href);
+    url.hash = buildUrl(state).slice(1); // Remove leading #
+    return url.toString();
+  }, [state]);
+
+  // Copy URL to clipboard
+  const copyUrl = useCallback(async () => {
+    const url = getShareableUrl();
+    try {
+      await navigator.clipboard.writeText(url);
+      return true;
+    } catch {
+      return false;
+    }
+  }, [getShareableUrl]);
+
+  return {
+    state,
+    setComponent,
+    setVariant,
+    setProps,
+    setViewSettings,
+    getShareableUrl,
+    copyUrl,
+    updateUrl,
+  };
+}
+
+/**
+ * Find a fragment by name or path
+ * Generic to preserve the full type of the fragment
+ */
+export function findFragmentByName<T extends { path: string; fragment: { meta: { name: string } } }>(
+  fragments: T[],
+  nameOrPath: string
+): T | undefined {
+  // Try exact path match first
+  const byPath = fragments.find((s) => s.path === nameOrPath);
+  if (byPath) return byPath;
+
+  // Try name match (case-insensitive)
+  const nameLower = nameOrPath.toLowerCase();
+  return fragments.find((s) => s.fragment.meta.name.toLowerCase() === nameLower);
+}
+
+/**
+ * Find a variant by name or index
+ */
+export function findVariantIndex(
+  variants: Array<{ name: string }> | undefined,
+  nameOrIndex: string | null
+): number {
+  if (!variants || !nameOrIndex) return 0;
+
+  // Try as index
+  const index = parseInt(nameOrIndex, 10);
+  if (!isNaN(index) && index >= 0 && index < variants.length) {
+    return index;
+  }
+
+  // Try as name (case-insensitive)
+  const nameLower = nameOrIndex.toLowerCase();
+  const foundIndex = variants.findIndex((v) => v.name.toLowerCase() === nameLower);
+  return foundIndex >= 0 ? foundIndex : 0;
+}
+
+export default useUrlState;

package/src/hooks/useViewSettings.ts

@@ -0,0 +1,111 @@
+/**
+ * View settings state management.
+ * Handles zoom, viewport, and theme settings with URL sync.
+ */
+
+import { useReducer, useCallback, useMemo } from 'react';
+import type { ZoomLevel, ViewportPreset, ViewportSize } from '../constants/ui.js';
+
+// Preview theme type (for canvas theming)
+export type PreviewTheme = 'light' | 'dark';
+
+interface ViewSettings {
+  zoom: ZoomLevel;
+  viewport: ViewportPreset;
+  customSize: ViewportSize;
+  previewTheme: PreviewTheme;
+}
+
+type ViewSettingsAction =
+  | { type: 'SET_ZOOM'; payload: ZoomLevel }
+  | { type: 'SET_VIEWPORT'; payload: ViewportPreset }
+  | { type: 'SET_CUSTOM_SIZE'; payload: ViewportSize }
+  | { type: 'SET_PREVIEW_THEME'; payload: PreviewTheme }
+  | { type: 'TOGGLE_THEME' }
+  | { type: 'RESET' };
+
+interface ViewSettingsInit {
+  zoom?: ZoomLevel;
+  viewport?: ViewportPreset;
+  customSize?: ViewportSize;
+  previewTheme?: PreviewTheme;
+}
+
+function createInitialState(init?: ViewSettingsInit): ViewSettings {
+  return {
+    zoom: init?.zoom ?? 100,
+    viewport: init?.viewport ?? 'responsive',
+    customSize: init?.customSize ?? { width: null, height: null },
+    previewTheme: init?.previewTheme ?? 'light',
+  };
+}
+
+function viewSettingsReducer(state: ViewSettings, action: ViewSettingsAction): ViewSettings {
+  switch (action.type) {
+    case 'SET_ZOOM':
+      return { ...state, zoom: action.payload };
+    case 'SET_VIEWPORT':
+      return { ...state, viewport: action.payload };
+    case 'SET_CUSTOM_SIZE':
+      return { ...state, customSize: action.payload, viewport: 'custom' };
+    case 'SET_PREVIEW_THEME':
+      return { ...state, previewTheme: action.payload };
+    case 'TOGGLE_THEME':
+      return { ...state, previewTheme: state.previewTheme === 'light' ? 'dark' : 'light' };
+    case 'RESET':
+      return createInitialState();
+    default:
+      return state;
+  }
+}
+
+interface UseViewSettingsOptions {
+  initialState?: ViewSettingsInit;
+  onZoomChange?: (zoom: ZoomLevel) => void;
+  onViewportChange?: (viewport: ViewportPreset, customSize?: ViewportSize) => void;
+}
+
+export function useViewSettings(options: UseViewSettingsOptions = {}) {
+  const { initialState: init, onZoomChange, onViewportChange } = options;
+
+  const [state, dispatch] = useReducer(
+    viewSettingsReducer,
+    init,
+    createInitialState
+  );
+
+  const setZoom = useCallback((zoom: ZoomLevel) => {
+    dispatch({ type: 'SET_ZOOM', payload: zoom });
+    onZoomChange?.(zoom);
+  }, [onZoomChange]);
+
+  const setViewport = useCallback((viewport: ViewportPreset) => {
+    dispatch({ type: 'SET_VIEWPORT', payload: viewport });
+    onViewportChange?.(viewport);
+  }, [onViewportChange]);
+
+  const setCustomSize = useCallback((size: ViewportSize) => {
+    dispatch({ type: 'SET_CUSTOM_SIZE', payload: size });
+    onViewportChange?.('custom', size);
+  }, [onViewportChange]);
+
+  const setPreviewTheme = useCallback((theme: PreviewTheme) => {
+    dispatch({ type: 'SET_PREVIEW_THEME', payload: theme });
+  }, []);
+
+  const toggleTheme = useCallback(() => {
+    dispatch({ type: 'TOGGLE_THEME' });
+  }, []);
+
+  const actions = useMemo(() => ({
+    setZoom,
+    setViewport,
+    setCustomSize,
+    setPreviewTheme,
+    toggleTheme,
+  }), [setZoom, setViewport, setCustomSize, setPreviewTheme, toggleTheme]);
+
+  return { ...state, ...actions };
+}
+
+export type { ViewSettings, ViewSettingsInit };