doe-sdk 0.1.0

package/templates/extension/src/hooks/useOnboarding.ts

@@ -0,0 +1,264 @@
+/**
+ * useOnboarding - Onboarding State Management Hook
+ *
+ * Manages onboarding flow state with persistence via DOE storage API.
+ * Supports step navigation, progress tracking, and skip functionality.
+ */
+import { useState, useCallback, useEffect } from "react";
+import type { DOEExtensionAPI } from "doe-sdk/runtime";
+
+// ============================================================================
+// TYPES
+// ============================================================================
+
+export type OnboardingScreen = "welcome" | "steps" | "complete" | "playground";
+
+export type StepId =
+  | "canvas"
+  | "storage"
+  | "config"
+  | "ui"
+  | "clipboard"
+  | "events"
+  | "network"
+  | "info";
+
+export interface OnboardingState {
+  /** Current screen being displayed */
+  screen: OnboardingScreen;
+  /** Current step index (0-based) when in steps screen */
+  currentStep: number;
+  /** Completed step IDs */
+  completedSteps: StepId[];
+  /** Whether onboarding was skipped */
+  skipped: boolean;
+  /** Whether state has been loaded from storage */
+  isLoaded: boolean;
+}
+
+export interface UseOnboardingResult {
+  state: OnboardingState;
+  /** Navigate to a specific screen */
+  goToScreen: (screen: OnboardingScreen) => void;
+  /** Go to next step */
+  nextStep: () => void;
+  /** Go to previous step */
+  prevStep: () => void;
+  /** Mark current step as completed and advance */
+  completeStep: () => void;
+  /** Skip onboarding and go to playground */
+  skip: () => void;
+  /** Restart onboarding from welcome */
+  restart: () => void;
+  /** Total number of steps */
+  totalSteps: number;
+  /** Whether all steps are completed */
+  isComplete: boolean;
+  /** Get current step ID */
+  currentStepId: StepId;
+}
+
+// ============================================================================
+// CONSTANTS
+// ============================================================================
+
+const STORAGE_KEY = "onboarding_state";
+
+export const STEPS: StepId[] = [
+  "canvas",
+  "storage",
+  "config",
+  "ui",
+  "clipboard",
+  "events",
+  "network",
+  "info",
+];
+
+export const STEP_INFO: Record<
+  StepId,
+  { title: string; description: string; icon: string }
+> = {
+  canvas: {
+    title: "Canvas API",
+    description: "Navigate the canvas and query selected shapes",
+    icon: "🎨",
+  },
+  storage: {
+    title: "Storage API",
+    description: "Persist data locally with key-value storage",
+    icon: "💾",
+  },
+  config: {
+    title: "Config API",
+    description: "Manage user-configurable settings",
+    icon: "⚙️",
+  },
+  ui: {
+    title: "UI API",
+    description: "Show notifications and confirmation dialogs",
+    icon: "🔔",
+  },
+  clipboard: {
+    title: "Clipboard API",
+    description: "Read and write to the system clipboard",
+    icon: "📋",
+  },
+  events: {
+    title: "Events API",
+    description: "React to selection and canvas changes",
+    icon: "📡",
+  },
+  network: {
+    title: "Network API",
+    description: "Call external APIs like GitHub, weather services, and more",
+    icon: "🌐",
+  },
+  info: {
+    title: "Workspace & Theme",
+    description: "Access workspace info and theme tokens",
+    icon: "ℹ️",
+  },
+};
+
+// ============================================================================
+// INITIAL STATE
+// ============================================================================
+
+const initialState: OnboardingState = {
+  screen: "welcome",
+  currentStep: 0,
+  completedSteps: [],
+  skipped: false,
+  isLoaded: false,
+};
+
+// ============================================================================
+// HOOK
+// ============================================================================
+
+export function useOnboarding(api: DOEExtensionAPI | null): UseOnboardingResult {
+  const [state, setState] = useState<OnboardingState>(initialState);
+
+  // Load state from storage on mount
+  useEffect(() => {
+    if (!api) return;
+
+    api.storage.get<OnboardingState>(STORAGE_KEY).then((savedState) => {
+      if (savedState && savedState.screen) {
+        setState({ ...savedState, isLoaded: true });
+      } else {
+        setState((s) => ({ ...s, isLoaded: true }));
+      }
+    });
+  }, [api]);
+
+  // Persist state to storage
+  const persistState = useCallback(
+    (newState: OnboardingState) => {
+      if (!api) return;
+      api.storage.set(STORAGE_KEY, newState);
+    },
+    [api]
+  );
+
+  const goToScreen = useCallback(
+    (screen: OnboardingScreen) => {
+      setState((prev) => {
+        const newState = { ...prev, screen };
+        persistState(newState);
+        return newState;
+      });
+    },
+    [persistState]
+  );
+
+  const nextStep = useCallback(() => {
+    setState((prev) => {
+      if (prev.currentStep >= STEPS.length - 1) {
+        // Move to complete screen
+        const newState = { ...prev, screen: "complete" as OnboardingScreen };
+        persistState(newState);
+        return newState;
+      }
+      const newState = { ...prev, currentStep: prev.currentStep + 1 };
+      persistState(newState);
+      return newState;
+    });
+  }, [persistState]);
+
+  const prevStep = useCallback(() => {
+    setState((prev) => {
+      if (prev.currentStep <= 0) return prev;
+      const newState = { ...prev, currentStep: prev.currentStep - 1 };
+      persistState(newState);
+      return newState;
+    });
+  }, [persistState]);
+
+  const completeStep = useCallback(() => {
+    setState((prev) => {
+      const stepId = STEPS[prev.currentStep];
+      const alreadyCompleted = prev.completedSteps.includes(stepId);
+      const completedSteps = alreadyCompleted
+        ? prev.completedSteps
+        : [...prev.completedSteps, stepId];
+
+      if (prev.currentStep >= STEPS.length - 1) {
+        // All steps done
+        const newState = {
+          ...prev,
+          completedSteps,
+          screen: "complete" as OnboardingScreen,
+        };
+        persistState(newState);
+        return newState;
+      }
+
+      const newState = {
+        ...prev,
+        completedSteps,
+        currentStep: prev.currentStep + 1,
+      };
+      persistState(newState);
+      return newState;
+    });
+  }, [persistState]);
+
+  const skip = useCallback(() => {
+    setState((prev) => {
+      const newState = {
+        ...prev,
+        skipped: true,
+        screen: "playground" as OnboardingScreen,
+      };
+      persistState(newState);
+      return newState;
+    });
+  }, [persistState]);
+
+  const restart = useCallback(() => {
+    const newState = {
+      ...initialState,
+      isLoaded: true,
+    };
+    persistState(newState);
+    setState(newState);
+  }, [persistState]);
+
+  const isComplete = state.completedSteps.length === STEPS.length;
+  const currentStepId = STEPS[state.currentStep];
+
+  return {
+    state,
+    goToScreen,
+    nextStep,
+    prevStep,
+    completeStep,
+    skip,
+    restart,
+    totalSteps: STEPS.length,
+    isComplete,
+    currentStepId,
+  };
+}

package/templates/extension/src/hooks/usePointerHandlers.ts

@@ -0,0 +1,105 @@
+/**
+ * Pointer Handler Hooks for DOE Extensions
+ *
+ * These hooks help manage pointer events in extension UIs to ensure
+ * proper interaction between extension content and the DOE canvas.
+ *
+ * Extensions use `pointerEvents: "auto"`, which means the extension captures
+ * all pointer events. For interactive areas (buttons, inputs, scrollable content),
+ * you must use stopPropagation() to prevent those events from triggering
+ * canvas drag or other canvas actions.
+ */
+import { useCallback, useEffect, type RefObject } from "react";
+
+/**
+ * Hook for interactive areas that should NOT start a canvas drag.
+ * Use on buttons, inputs, scrollable content, dropdown menus, etc.
+ *
+ * @example
+ * ```tsx
+ * function MyExtension() {
+ *   const handleInteractive = useInteractivePointerDown();
+ *
+ *   return (
+ *     <div>
+ *       <button onPointerDown={handleInteractive}>Click me</button>
+ *       <input onPointerDown={handleInteractive} />
+ *       <textarea onPointerDown={handleInteractive} />
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export function useInteractivePointerDown(): (e: React.PointerEvent) => void {
+  return useCallback((e: React.PointerEvent) => {
+    e.stopPropagation();
+  }, []);
+}
+
+/**
+ * Hook to prevent canvas zoom when scrolling inside extension.
+ * Use on scrollable containers to ensure scroll wheel events
+ * scroll the content instead of zooming the canvas.
+ *
+ * @param ref - Reference to the scrollable element
+ *
+ * @example
+ * ```tsx
+ * function MyExtension() {
+ *   const scrollRef = useRef<HTMLDivElement>(null);
+ *   usePreventCanvasZoom(scrollRef);
+ *
+ *   return (
+ *     <div ref={scrollRef} className="overflow-auto h-64">
+ *       {/* Long scrollable content *\/}
+ *       <div className="h-[1000px]">Content...</div>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export function usePreventCanvasZoom(ref: RefObject<HTMLElement | null>): void {
+  useEffect(() => {
+    const el = ref.current;
+    if (!el) return;
+
+    const handleWheel = (e: WheelEvent) => {
+      e.stopPropagation();
+    };
+
+    el.addEventListener("wheel", handleWheel, { capture: true, passive: false });
+    return () => el.removeEventListener("wheel", handleWheel, { capture: true });
+  }, [ref]);
+}
+
+/**
+ * Combined hook for scrollable interactive areas.
+ * Provides both pointer down handler and wheel event blocking.
+ *
+ * @param ref - Reference to the scrollable element
+ * @returns Handler for onPointerDown events
+ *
+ * @example
+ * ```tsx
+ * function MyExtension() {
+ *   const scrollRef = useRef<HTMLDivElement>(null);
+ *   const handleInteractive = useScrollableArea(scrollRef);
+ *
+ *   return (
+ *     <div
+ *       ref={scrollRef}
+ *       className="overflow-auto"
+ *       onPointerDown={handleInteractive}
+ *     >
+ *       Scrollable content...
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export function useScrollableArea(
+  ref: RefObject<HTMLElement | null>
+): (e: React.PointerEvent) => void {
+  usePreventCanvasZoom(ref);
+  return useInteractivePointerDown();
+}

package/templates/extension/src/main.tsx

@@ -0,0 +1,18 @@
+/**
+ * {{displayName}} - React Entry Point
+ *
+ * Renders React immediately. DOE connection is handled by useDoe hook.
+ * This allows the extension to work both standalone (for development)
+ * and inside DOE (for production).
+ */
+import { createRoot } from "react-dom/client";
+import { App } from "./App";
+
+// Mount React immediately
+const container = document.getElementById("root");
+if (!container) {
+  throw new Error("Root element not found");
+}
+
+const root = createRoot(container);
+root.render(<App />);

package/templates/extension/src/styles.ts

@@ -0,0 +1,265 @@
+/**
+ * Shared Styles for Extension Template
+ *
+ * CSS custom properties and reusable style objects for consistent theming.
+ * Uses inline styles (consistent with existing template pattern).
+ */
+import type { CSSProperties } from "react";
+
+// ============================================================================
+// SPACING SCALE (4px base)
+// ============================================================================
+export const spacing = {
+  xs: 4,
+  sm: 8,
+  md: 16,
+  lg: 24,
+  xl: 32,
+  xxl: 48,
+} as const;
+
+// ============================================================================
+// COLORS
+// ============================================================================
+export const colors = {
+  // Primary
+  primary: "#3b82f6",
+  primaryHover: "#2563eb",
+  primaryLight: "#dbeafe",
+
+  // Success
+  success: "#22c55e",
+  successLight: "#dcfce7",
+
+  // Warning
+  warning: "#f59e0b",
+  warningLight: "#fef3c7",
+
+  // Error
+  error: "#ef4444",
+  errorLight: "#fee2e2",
+
+  // Neutral
+  text: "#111827",
+  textSecondary: "#6b7280",
+  textMuted: "#9ca3af",
+  border: "#e5e7eb",
+  borderLight: "#f3f4f6",
+  background: "#ffffff",
+  backgroundSecondary: "#f9fafb",
+  backgroundHover: "#f3f4f6",
+  backgroundCode: "#1e293b",
+} as const;
+
+// ============================================================================
+// TYPOGRAPHY
+// ============================================================================
+export const typography = {
+  fontFamily:
+    '-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif',
+  sizes: {
+    xs: 11,
+    sm: 12,
+    base: 14,
+    lg: 16,
+    xl: 20,
+    xxl: 24,
+  },
+  weights: {
+    normal: 400,
+    medium: 500,
+    semibold: 600,
+  },
+} as const;
+
+// ============================================================================
+// SHARED STYLE OBJECTS
+// ============================================================================
+
+export const buttonStyles = {
+  primary: {
+    padding: `${spacing.sm}px ${spacing.lg}px`,
+    background: colors.primary,
+    color: "white",
+    border: "none",
+    borderRadius: 8,
+    fontSize: typography.sizes.base,
+    fontWeight: typography.weights.medium,
+    cursor: "pointer",
+    transition: "all 0.15s ease",
+    display: "inline-flex",
+    alignItems: "center",
+    justifyContent: "center",
+    gap: spacing.sm,
+  } as CSSProperties,
+
+  secondary: {
+    padding: `${spacing.sm}px ${spacing.lg}px`,
+    background: "transparent",
+    color: colors.textSecondary,
+    border: `1px solid ${colors.border}`,
+    borderRadius: 8,
+    fontSize: typography.sizes.base,
+    fontWeight: typography.weights.medium,
+    cursor: "pointer",
+    transition: "all 0.15s ease",
+    display: "inline-flex",
+    alignItems: "center",
+    justifyContent: "center",
+    gap: spacing.sm,
+  } as CSSProperties,
+
+  link: {
+    padding: `${spacing.xs}px ${spacing.sm}px`,
+    background: "transparent",
+    color: colors.textSecondary,
+    border: "none",
+    fontSize: typography.sizes.sm,
+    cursor: "pointer",
+    textDecoration: "underline",
+    transition: "color 0.15s ease",
+  } as CSSProperties,
+};
+
+export const inputStyles = {
+  base: {
+    width: "100%",
+    padding: `${spacing.sm}px ${spacing.md}px`,
+    border: `1px solid ${colors.border}`,
+    borderRadius: 8,
+    fontSize: typography.sizes.base,
+    outline: "none",
+    transition: "border-color 0.15s ease",
+    boxSizing: "border-box",
+  } as CSSProperties,
+};
+
+export const cardStyles = {
+  base: {
+    background: colors.backgroundSecondary,
+    borderRadius: 12,
+    padding: spacing.md,
+    border: `1px solid ${colors.borderLight}`,
+  } as CSSProperties,
+
+  interactive: {
+    background: colors.backgroundSecondary,
+    borderRadius: 12,
+    padding: spacing.md,
+    border: `1px solid ${colors.borderLight}`,
+    cursor: "pointer",
+    transition: "all 0.15s ease",
+  } as CSSProperties,
+};
+
+// ============================================================================
+// ANIMATION KEYFRAMES (as CSS string)
+// ============================================================================
+export const animationStyles = `
+  @keyframes fadeIn {
+    from { opacity: 0; }
+    to { opacity: 1; }
+  }
+
+  @keyframes slideInUp {
+    from {
+      opacity: 0;
+      transform: translateY(16px);
+    }
+    to {
+      opacity: 1;
+      transform: translateY(0);
+    }
+  }
+
+  @keyframes slideInLeft {
+    from {
+      opacity: 0;
+      transform: translateX(-16px);
+    }
+    to {
+      opacity: 1;
+      transform: translateX(0);
+    }
+  }
+
+  @keyframes slideInRight {
+    from {
+      opacity: 0;
+      transform: translateX(16px);
+    }
+    to {
+      opacity: 1;
+      transform: translateX(0);
+    }
+  }
+
+  @keyframes pulse {
+    0%, 100% { opacity: 1; }
+    50% { opacity: 0.5; }
+  }
+
+  @keyframes checkmark {
+    0% {
+      stroke-dashoffset: 50;
+    }
+    100% {
+      stroke-dashoffset: 0;
+    }
+  }
+
+  @keyframes scaleIn {
+    from {
+      opacity: 0;
+      transform: scale(0.9);
+    }
+    to {
+      opacity: 1;
+      transform: scale(1);
+    }
+  }
+`;
+
+// ============================================================================
+// LAYOUT HELPERS
+// ============================================================================
+export const flexCenter: CSSProperties = {
+  display: "flex",
+  alignItems: "center",
+  justifyContent: "center",
+};
+
+export const flexBetween: CSSProperties = {
+  display: "flex",
+  alignItems: "center",
+  justifyContent: "space-between",
+};
+
+export const flexColumn: CSSProperties = {
+  display: "flex",
+  flexDirection: "column",
+};
+
+// ============================================================================
+// CODE DISPLAY STYLES
+// ============================================================================
+export const codeStyles = {
+  container: {
+    background: "#1e1e1e",
+    borderRadius: 8,
+    padding: spacing.md,
+    overflow: "auto",
+    fontSize: typography.sizes.sm,
+    fontFamily: 'Monaco, Menlo, "Ubuntu Mono", Consolas, monospace',
+    lineHeight: 1.5,
+  } as CSSProperties,
+
+  keyword: { color: "#569cd6" },
+  string: { color: "#ce9178" },
+  comment: { color: "#6a9955" },
+  function: { color: "#dcdcaa" },
+  variable: { color: "#9cdcfe" },
+  property: { color: "#4ec9b0" },
+  operator: { color: "#d4d4d4" },
+  plain: { color: "#d4d4d4" },
+};

package/templates/extension/tsconfig.json

@@ -0,0 +1,28 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "jsx": "react-jsx",
+    "strict": true,
+    "declaration": false,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noFallthroughCasesInSwitch": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "noEmit": true,
+    "paths": {
+      "doe-sdk": ["../../dist/index.d.ts"],
+      "doe-sdk/*": ["../../dist/*"]
+    }
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}

package/templates/extension/vite.config.ts

@@ -0,0 +1,32 @@
+/**
+ * Vite Configuration for DOE Extension
+ *
+ * Builds the extension as a single HTML + JS bundle that can be loaded in DOE.
+ */
+import { defineConfig } from "vite";
+import react from "@vitejs/plugin-react";
+
+export default defineConfig({
+  plugins: [react()],
+  base: "./", // Use relative paths for DOE custom protocol
+  build: {
+    outDir: "dist",
+    // Inline all assets for simpler loading
+    assetsInlineLimit: 100000,
+    rollupOptions: {
+      output: {
+        // Single JS file
+        entryFileNames: "assets/[name].js",
+        chunkFileNames: "assets/[name].js",
+        assetFileNames: "assets/[name].[ext]",
+      },
+    },
+    target: "esnext",
+    minify: true,
+    sourcemap: false,
+  },
+  server: {
+    port: 3001,
+    strictPort: true,
+  },
+});