create-vizcraft-playground 0.1.0

package/template/src/components/Landing/Landing.scss

@@ -0,0 +1,85 @@
+@use "sass:color";
+
+.landing {
+  width: 100%;
+  min-height: 100vh;
+  background: #0f172a;
+  color: #e2e8f0;
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  padding: 4rem 2rem 2rem;
+  box-sizing: border-box;
+
+  &__header {
+    text-align: center;
+    margin-bottom: 3rem;
+  }
+
+  &__title {
+    font-size: 2rem;
+    font-weight: 700;
+    color: #f1f5f9;
+    margin: 0 0 0.5rem;
+  }
+
+  &__subtitle {
+    font-size: 1rem;
+    color: #94a3b8;
+    margin: 0;
+    max-width: 480px;
+  }
+
+  &__grid {
+    display: grid;
+    grid-template-columns: repeat(auto-fill, minmax(320px, 1fr));
+    gap: 1.5rem;
+    width: 100%;
+    max-width: 960px;
+  }
+
+  &__card {
+    background: #1e293b;
+    border: 1px solid #334155;
+    border-radius: 12px;
+    padding: 1.75rem;
+    cursor: pointer;
+    transition:
+      transform 0.15s ease,
+      border-color 0.2s ease,
+      box-shadow 0.2s ease;
+
+    &:hover {
+      transform: translateY(-3px);
+      box-shadow: 0 8px 24px rgba(0, 0, 0, 0.35);
+    }
+  }
+
+  &__card-name {
+    font-size: 1.25rem;
+    font-weight: 600;
+    margin: 0 0 0.5rem;
+  }
+
+  &__card-desc {
+    font-size: 0.875rem;
+    color: #94a3b8;
+    margin: 0 0 1rem;
+    line-height: 1.5;
+  }
+
+  &__card-count {
+    font-size: 0.75rem;
+    color: #64748b;
+    display: flex;
+    align-items: center;
+    gap: 0.35rem;
+  }
+
+  &__dot {
+    width: 8px;
+    height: 8px;
+    border-radius: 50%;
+    display: inline-block;
+  }
+}

package/template/src/components/Landing/Landing.tsx

@@ -0,0 +1,55 @@
+import React from "react";
+import { useNavigate } from "react-router-dom";
+import { categories } from "../../registry";
+import playgroundConfig from "../../playground.config";
+import "./Landing.scss";
+
+const Landing: React.FC = () => {
+  const navigate = useNavigate();
+
+  const handlePickCategory = (categoryId: string, firstPluginId: string) => {
+    navigate(`/${categoryId}/${firstPluginId}`);
+  };
+
+  return (
+    <div className="landing">
+      <div className="landing__header">
+        <h1 className="landing__title">{playgroundConfig.title}</h1>
+        <p className="landing__subtitle">{playgroundConfig.subtitle}</p>
+      </div>
+
+      <div className="landing__grid">
+        {categories.map((cat) => {
+          const firstPlugin = cat.plugins[0];
+          if (!firstPlugin) return null;
+
+          return (
+            <div
+              key={cat.id}
+              className="landing__card"
+              style={{ borderColor: cat.accent }}
+              onClick={() => handlePickCategory(cat.id, firstPlugin.id)}
+              onMouseEnter={(e) => {
+                (e.currentTarget as HTMLElement).style.borderColor = cat.accent;
+              }}
+            >
+              <h2 className="landing__card-name" style={{ color: cat.accent }}>
+                {cat.name}
+              </h2>
+              <p className="landing__card-desc">{cat.description}</p>
+              <span className="landing__card-count">
+                <span
+                  className="landing__dot"
+                  style={{ background: cat.accent }}
+                />
+                {cat.plugins.length} demo{cat.plugins.length !== 1 ? "s" : ""}
+              </span>
+            </div>
+          );
+        })}
+      </div>
+    </div>
+  );
+};
+
+export default Landing;

package/template/src/components/Shell.tsx

@@ -0,0 +1,144 @@
+import React from "react";
+import { useDispatch, useSelector } from "react-redux";
+import { useNavigate } from "react-router-dom";
+import { type RootState } from "../store/store";
+import {
+  nextStep,
+  incrementPass,
+  resetSimulation,
+} from "../store/slices/simulationSlice";
+import type { DemoPlugin, DemoStep } from "../types/ModelPlugin";
+import type { PluginCategory } from "../registry";
+import StepIndicator from "./StepIndicator/StepIndicator";
+
+interface ShellProps {
+  plugin: DemoPlugin;
+  category: PluginCategory;
+}
+
+// Helper to normalize steps to objects
+const normalizeSteps = (steps: (string | DemoStep)[]): DemoStep[] => {
+  return steps.map((s) =>
+    typeof s === "string" ? { label: s, autoAdvance: false } : s,
+  );
+};
+
+const Shell: React.FC<ShellProps> = ({ plugin, category }) => {
+  const dispatch = useDispatch();
+  const navigate = useNavigate();
+  const simulationState = useSelector((state: RootState) => state.simulation);
+
+  // Use the plugin's selector to get its specific state
+  const modelState = useSelector(plugin.selector);
+
+  React.useEffect(() => {
+    // Reset shared simulation state (step 0, pass 0)
+    dispatch(resetSimulation());
+    // Initialize the plugin on mount
+    plugin.init(dispatch);
+  }, [dispatch, plugin]);
+
+  const rawSteps = plugin.getSteps(modelState);
+  const steps = normalizeSteps(rawSteps);
+  const { currentStep, passCount } = simulationState;
+
+  // Track if the current step is actively processing (animating)
+  // Default to true when entering a step, release when animation completes
+  const [isProcessing, setIsProcessing] = React.useState(true);
+
+  // Reset processing state when step changes
+  React.useEffect(() => {
+    setIsProcessing(true);
+  }, [currentStep]);
+
+  const handleAnimationComplete = () => {
+    const currentConfig = steps[currentStep];
+
+    // If autoAdvance is true, proceed automatically.
+    // Otherwise, unlock the "Next" button (isProcessing = false).
+    if (currentConfig?.autoAdvance) {
+      dispatch(nextStep(steps.length));
+    } else {
+      setIsProcessing(false);
+    }
+  };
+
+  return (
+    <div className="app">
+      <header className="app-header">
+        <div className="app-header__nav">
+          <button
+            className="app-header__back"
+            onClick={() => navigate("/")}
+            title="Back to topics"
+          >
+            ←
+          </button>
+
+          <div className="app-header__text">
+            <div className="app-header__breadcrumb">
+              <span
+                className="app-header__category"
+                style={{ color: category.accent }}
+              >
+                {category.name}
+              </span>
+              {category.plugins.length > 1 && (
+                <>
+                  <span className="app-header__sep">/</span>
+                  <select
+                    className="app-header__select"
+                    value={plugin.id}
+                    onChange={(e) =>
+                      navigate(`/${category.id}/${e.target.value}`)
+                    }
+                  >
+                    {category.plugins.map((p) => (
+                      <option key={p.id} value={p.id}>
+                        {p.name}
+                      </option>
+                    ))}
+                  </select>
+                </>
+              )}
+              {category.plugins.length <= 1 && (
+                <>
+                  <span className="app-header__sep">/</span>
+                  <span className="app-header__plugin-name">{plugin.name}</span>
+                </>
+              )}
+            </div>
+            <p>{plugin.description}</p>
+          </div>
+        </div>
+      </header>
+
+      <div className="main-content">
+        <StepIndicator
+          steps={steps.map((s) => s.label)}
+          currentStep={currentStep}
+          onNextStep={() => dispatch(nextStep(steps.length))}
+          onReset={() => {
+            dispatch(resetSimulation());
+            dispatch(incrementPass());
+          }}
+          passCount={passCount}
+          // Button is disabled if processing (waiting for anim)
+          isProcessing={isProcessing}
+          nextButtonConfig={{
+            text: steps[currentStep]?.nextButtonText,
+            processingText: steps[currentStep]?.processingText,
+            color: steps[currentStep]?.nextButtonColor,
+          }}
+          restartButtonConfig={plugin.restartConfig}
+        />
+
+        <div className="visualization-container">
+          <plugin.Component onAnimationComplete={handleAnimationComplete} />
+        </div>
+      </div>
+    </div>
+  );
+};
+
+export default Shell;

package/template/src/components/StepIndicator/StepIndicator.scss

@@ -0,0 +1,151 @@
+.step-indicator {
+  display: flex;
+  flex-direction: column;
+  gap: 0;
+  padding: 2rem;
+  background: #1f2937; // Gray-800
+  border-right: 1px solid #374151; // Gray-700
+  width: 300px;
+  min-width: 300px;
+  overflow-y: auto;
+
+  h2 {
+    color: #f3f4f6;
+    margin-top: 0;
+    margin-bottom: 2rem;
+    font-size: 1.5rem;
+  }
+
+  .step-list {
+    display: flex;
+    flex-direction: column;
+    position: relative;
+  }
+
+  .step-item {
+    display: flex;
+    gap: 1rem;
+    position: relative;
+    padding-bottom: 2rem;
+
+    &:last-child {
+      padding-bottom: 0;
+      
+      .step-line {
+        display: none;
+      }
+    }
+
+    &.completed {
+      .step-circle {
+        background: #10b981; // Emerald-500
+        border-color: #10b981;
+        color: white;
+      }
+      
+      .step-line {
+        background: #10b981;
+      }
+
+      .step-label {
+        color: #d1d5db; // Gray-300
+      }
+    }
+
+    &.active {
+      .step-circle {
+        background: #4f46e5; // Indigo-600
+        border-color: #4f46e5;
+        color: white;
+        box-shadow: 0 0 0 4px rgba(79, 70, 229, 0.3);
+      }
+
+      .step-label {
+        color: #fff;
+        font-weight: 600;
+      }
+    }
+
+    &.pending {
+      .step-circle {
+        background: transparent;
+        border-color: #4b5563; // Gray-600
+        color: #9ca3af; // Gray-400
+      }
+
+      .step-label {
+        color: #6b7280; // Gray-500
+      }
+    }
+  }
+
+  .step-marker {
+    display: flex;
+    flex-direction: column;
+    align-items: center;
+    width: 24px;
+    flex-shrink: 0;
+  }
+
+  .step-circle {
+    width: 24px;
+    height: 24px;
+    border-radius: 50%;
+    border: 2px solid;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    font-size: 12px;
+    background: #1f2937;
+    z-index: 2;
+    transition: all 0.3s ease;
+  }
+
+  .step-line {
+    width: 2px;
+    flex: 1;
+    background: #374151; // Gray-700
+    margin-top: 4px;
+    margin-bottom: 4px;
+    transition: background 0.3s ease;
+  }
+
+  .step-content {
+    padding-top: 2px;
+  }
+
+  .step-label {
+    font-size: 1rem;
+    transition: color 0.3s ease;
+  }
+
+  .controls {
+    margin-top: auto;
+    padding-top: 2rem;
+    display: flex;
+    justify-content: center;
+
+    button {
+      background: #10b981; // Emerald-500
+      color: white;
+      border: none;
+      padding: 0.75rem 2rem;
+      border-radius: 8px;
+      font-weight: 600;
+      font-size: 1rem;
+      cursor: pointer;
+      transition: background 0.2s;
+      width: 100%;
+
+      &:hover {
+        background: #059669; // Emerald-600
+      }
+
+      &:disabled {
+        background: #374151;
+        cursor: not-allowed;
+        opacity: 0.5;
+      }
+    }
+  }
+}

package/template/src/components/StepIndicator/StepIndicator.tsx

@@ -0,0 +1,73 @@
+import React from 'react';
+import './StepIndicator.scss';
+
+interface StepIndicatorProps {
+  steps: string[];
+  currentStep: number;
+  onNextStep: () => void;
+  onReset: () => void;
+  passCount?: number;
+  isProcessing?: boolean;
+  nextButtonConfig?: {
+      text?: string;
+      processingText?: string;
+      color?: string;
+  };
+  restartButtonConfig?: {
+      text?: string;
+      color?: string;
+  };
+}
+
+const StepIndicator: React.FC<StepIndicatorProps> = ({ steps, currentStep, onNextStep, onReset, passCount = 1, isProcessing = false, nextButtonConfig, restartButtonConfig }) => {
+  const isFinished = currentStep >= steps.length;
+
+  return (
+    <div className="step-indicator">
+      <h2>Process Flow <span style={{ fontSize: '0.8em', opacity: 0.6, marginLeft: '10px' }}>Pass {passCount}</span></h2>
+      
+      <div className="step-list">
+        {steps.map((step, index) => {
+          let status = 'pending';
+          if (index < currentStep) status = 'completed';
+          if (index === currentStep) status = 'active';
+
+          return (
+            <div key={index} className={`step-item ${status}`}>
+              <div className="step-marker">
+                <div className="step-circle">
+                  {status === 'completed' ? '✓' : index + 1}
+                </div>
+                {index < steps.length - 1 && <div className="step-line" />}
+              </div>
+              <div className="step-content">
+                <div className="step-label">{step}</div>
+              </div>
+            </div>
+          );
+        })}
+      </div>
+
+      <div className="controls">
+        {isFinished ? (
+          <button onClick={onReset} style={{ background: restartButtonConfig?.color || '#4f46e5' }}>
+            {restartButtonConfig?.text || 'Start Next Pass'}
+          </button>
+        ) : (
+          <button 
+            onClick={onNextStep} 
+            disabled={isProcessing}
+            style={{
+                ...(isProcessing ? { opacity: 0.5, cursor: 'not-allowed' } : {}),
+                ...(nextButtonConfig?.color ? { background: nextButtonConfig.color } : {})
+            }}
+          >
+            {isProcessing ? (nextButtonConfig?.processingText || 'Processing...') : (nextButtonConfig?.text || 'Next Step')}
+          </button>
+        )}
+      </div>
+    </div>
+  );
+};
+
+export default StepIndicator;

package/template/src/components/VizInfoBeacon/VizInfoBeacon.scss

@@ -0,0 +1,41 @@
+.viz-info-beacon {
+  position: absolute;
+  inset: 0;
+  pointer-events: none;
+  z-index: 4;
+  overflow: visible;
+
+  &__hover-region {
+    pointer-events: auto;
+    cursor: default;
+  }
+
+  &__indicator {
+    pointer-events: none;
+    cursor: pointer;
+    opacity: 0;
+    transition:
+      opacity 0.22s ease,
+      transform 0.22s ease;
+    transform-origin: center;
+    transform: scale(0.85);
+    outline: none;
+
+    &--visible {
+      opacity: 1;
+      pointer-events: auto;
+      transform: scale(1);
+    }
+
+    &:hover circle:nth-child(2),
+    &:focus-visible circle:nth-child(2) {
+      filter: brightness(1.3);
+    }
+
+    &:focus-visible {
+      outline: 2px solid currentColor;
+      outline-offset: 4px;
+      border-radius: 50%;
+    }
+  }
+}

package/template/src/components/VizInfoBeacon/VizInfoBeacon.tsx

@@ -0,0 +1,157 @@
+import React, { useCallback, useEffect, useRef, useState } from "react";
+import "./VizInfoBeacon.scss";
+
+export interface VizSceneRect {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+export interface VizScenePoint {
+  x: number;
+  y: number;
+}
+
+export interface VizInfoBeaconProps {
+  viewWidth: number;
+  viewHeight: number;
+  hoverRegion: VizSceneRect;
+  indicatorPosition: VizScenePoint;
+  ariaLabel: string;
+  onActivate: () => void;
+  accentColor?: string;
+  label?: string;
+  hideDelayMs?: number;
+  className?: string;
+}
+
+const VizInfoBeacon: React.FC<VizInfoBeaconProps> = ({
+  viewWidth,
+  viewHeight,
+  hoverRegion,
+  indicatorPosition,
+  ariaLabel,
+  onActivate,
+  accentColor = "#60a5fa",
+  label = "ⓘ",
+  hideDelayMs = 3000,
+  className,
+}) => {
+  const [isVisible, setIsVisible] = useState(false);
+  const hideTimerRef = useRef<number | null>(null);
+  const isHoveringButtonRef = useRef(false);
+
+  const clearHideTimer = useCallback(() => {
+    if (hideTimerRef.current !== null) {
+      window.clearTimeout(hideTimerRef.current);
+      hideTimerRef.current = null;
+    }
+  }, []);
+
+  const show = useCallback(() => {
+    clearHideTimer();
+    setIsVisible(true);
+  }, [clearHideTimer]);
+
+  const scheduleHide = useCallback(() => {
+    clearHideTimer();
+    hideTimerRef.current = window.setTimeout(() => {
+      if (!isHoveringButtonRef.current) {
+        setIsVisible(false);
+      }
+      hideTimerRef.current = null;
+    }, hideDelayMs);
+  }, [clearHideTimer, hideDelayMs]);
+
+  useEffect(() => {
+    return () => clearHideTimer();
+  }, [clearHideTimer]);
+
+  const onButtonEnter = useCallback(() => {
+    isHoveringButtonRef.current = true;
+    clearHideTimer();
+    setIsVisible(true);
+  }, [clearHideTimer]);
+
+  const onButtonLeave = useCallback(() => {
+    isHoveringButtonRef.current = false;
+    scheduleHide();
+  }, [scheduleHide]);
+
+  const ix = indicatorPosition.x;
+  const iy = indicatorPosition.y;
+  const R = 13;
+
+  return (
+    <svg
+      className={`viz-info-beacon ${className ?? ""}`.trim()}
+      viewBox={`0 0 ${viewWidth} ${viewHeight}`}
+      preserveAspectRatio="xMidYMid meet"
+    >
+      {/* Invisible hover region over the node */}
+      <rect
+        className="viz-info-beacon__hover-region"
+        x={hoverRegion.x}
+        y={hoverRegion.y}
+        width={hoverRegion.width}
+        height={hoverRegion.height}
+        fill="transparent"
+        onPointerEnter={show}
+        onPointerLeave={scheduleHide}
+      />
+
+      {/* (i) indicator circle — appears on hover, sticks when hovered itself */}
+      <g
+        className={`viz-info-beacon__indicator ${isVisible ? "viz-info-beacon__indicator--visible" : ""}`}
+        onPointerEnter={onButtonEnter}
+        onPointerLeave={onButtonLeave}
+        onClick={(e) => {
+          e.stopPropagation();
+          onActivate();
+        }}
+        role="button"
+        tabIndex={0}
+        aria-label={ariaLabel}
+        onKeyDown={(e) => {
+          if (e.key === "Enter" || e.key === " ") {
+            e.preventDefault();
+            onActivate();
+          }
+        }}
+        onFocus={show}
+        onBlur={onButtonLeave}
+      >
+        {/* Larger invisible hit area */}
+        <circle cx={ix} cy={iy} r={R + 6} fill="transparent" />
+        {/* Background circle */}
+        <circle
+          cx={ix}
+          cy={iy}
+          r={R}
+          fill="#0f172a"
+          stroke={accentColor}
+          strokeWidth={1.6}
+          opacity={0.95}
+        />
+        {/* Label text */}
+        <text
+          x={ix}
+          y={iy}
+          textAnchor="middle"
+          dominantBaseline="central"
+          fill={accentColor}
+          fontSize={14}
+          fontWeight={700}
+          fontFamily="Georgia, 'Times New Roman', serif"
+          fontStyle="italic"
+          style={{ pointerEvents: "none" }}
+        >
+          {label}
+        </text>
+      </g>
+    </svg>
+  );
+};
+
+export default VizInfoBeacon;