create-vizcraft-playground 0.1.0

package/template/src/components/plugin-kit/CanvasStage.tsx

@@ -0,0 +1,30 @@
+import React from "react";
+
+export interface CanvasStageProps {
+  /** Ref forwarded to the inner canvas div (for VizCraft mounting). */
+  canvasRef?: React.Ref<HTMLDivElement>;
+  /** Content rendered inside the stage but outside the canvas (e.g. VizInfoBeacons). */
+  children?: React.ReactNode;
+  className?: string;
+}
+
+/**
+ * The main visualisation canvas wrapper with grid-dot background.
+ *
+ * @example
+ * <CanvasStage canvasRef={containerRef}>
+ *   <VizInfoBeacon … />
+ * </CanvasStage>
+ */
+const CanvasStage: React.FC<CanvasStageProps> = ({
+  canvasRef,
+  children,
+  className,
+}) => (
+  <div className={`vc-canvas-stage${className ? ` ${className}` : ""}`}>
+    <div className="vc-canvas-stage__canvas" ref={canvasRef} />
+    {children}
+  </div>
+);
+
+export default CanvasStage;

package/template/src/components/plugin-kit/ConceptPills.tsx

@@ -0,0 +1,55 @@
+import React from "react";
+
+export interface PillDef {
+  key: string;
+  label: string;
+  /** CSS class modifier appended as `vc-pill--{variant}`.
+   *  Alternatively supply `color` + `borderColor` inline. */
+  variant?: string;
+  color?: string;
+  borderColor?: string;
+}
+
+export interface ConceptPillsProps {
+  pills: PillDef[];
+  onOpen: (key: string) => void;
+  className?: string;
+}
+
+/**
+ * A horizontal row of clickable concept pills.
+ * Each pill fires `onOpen(pill.key)` — typically to open an InfoModal.
+ *
+ * @example
+ * <ConceptPills
+ *   pills={[
+ *     { key: "kafka", label: "Kafka", variant: "kafka" },
+ *     { key: "partitioning", label: "Partitioning", color: "#fde68a", borderColor: "#f59e0b" },
+ *   ]}
+ *   onOpen={openConcept}
+ * />
+ */
+const ConceptPills: React.FC<ConceptPillsProps> = ({
+  pills,
+  onOpen,
+  className,
+}) => (
+  <div className={`vc-pills${className ? ` ${className}` : ""}`}>
+    {pills.map((p) => (
+      <button
+        key={p.key}
+        className={`vc-pill${p.variant ? ` vc-pill--${p.variant}` : ""}`}
+        style={
+          !p.variant && p.color
+            ? { color: p.color, borderColor: p.borderColor ?? p.color }
+            : undefined
+        }
+        onClick={() => onOpen(p.key)}
+      >
+        {p.label}
+      </button>
+    ))}
+  </div>
+);
+
+export default ConceptPills;

package/template/src/components/plugin-kit/PluginLayout.tsx

@@ -0,0 +1,41 @@
+import React from "react";
+
+export interface PluginLayoutProps {
+  /** Content rendered above the body grid (pills bar, toolbar). */
+  toolbar?: React.ReactNode;
+  /** The main visualisation area (left column). */
+  canvas: React.ReactNode;
+  /** The right-hand sidebar (right column). Omit for full-width canvas. */
+  sidebar?: React.ReactNode;
+  /** Extra class on the root. */
+  className?: string;
+}
+
+/**
+ * Standard two-column plugin layout: toolbar → body (canvas + sidebar).
+ *
+ * @example
+ * <PluginLayout
+ *   toolbar={<ConceptPills pills={pills} onOpen={openConcept} />}
+ *   canvas={<CanvasStage canvasRef={ref} />}
+ *   sidebar={<SidePanel>…</SidePanel>}
+ * />
+ */
+const PluginLayout: React.FC<PluginLayoutProps> = ({
+  toolbar,
+  canvas,
+  sidebar,
+  className,
+}) => (
+  <div className={`vc-plugin-layout${className ? ` ${className}` : ""}`}>
+    {toolbar}
+    <div
+      className={`vc-plugin-layout__body${sidebar ? "" : " vc-plugin-layout__body--full"}`}
+    >
+      {canvas}
+      {sidebar}
+    </div>
+  </div>
+);
+
+export default PluginLayout;

package/template/src/components/plugin-kit/SidePanel.tsx

@@ -0,0 +1,69 @@
+import React from "react";
+
+/* ─── SidePanel ───────────────────────────────────────── */
+
+export interface SidePanelProps {
+  children: React.ReactNode;
+  className?: string;
+}
+
+/**
+ * Scrollable sidebar column. Place `<SideCard>` elements inside.
+ *
+ * @example
+ * <SidePanel>
+ *   <SideCard label="What's happening"><p>{explanation}</p></SideCard>
+ *   <SideCard variant="code" label="Source">…</SideCard>
+ * </SidePanel>
+ */
+const SidePanel: React.FC<SidePanelProps> = ({ children, className }) => (
+  <aside className={`vc-side-panel${className ? ` ${className}` : ""}`}>
+    {children}
+  </aside>
+);
+
+/* ─── SideCard ────────────────────────────────────────── */
+
+export interface SideCardProps {
+  /** Small uppercase label at the top of the card. */
+  label?: string;
+  /** Optional heading + sub rendered in a head row. */
+  heading?: string;
+  sub?: string;
+  /** Extra class for variant styling, e.g. `vc-side-card--explanation`. */
+  variant?: string;
+  children: React.ReactNode;
+  className?: string;
+}
+
+/**
+ * A card inside a SidePanel.
+ *
+ * @example
+ * <SideCard label="What just happened?" variant="explanation">
+ *   <p>{explanation}</p>
+ * </SideCard>
+ */
+const SideCard: React.FC<SideCardProps> = ({
+  label,
+  heading,
+  sub,
+  variant,
+  children,
+  className,
+}) => (
+  <div
+    className={`vc-side-card${variant ? ` vc-side-card--${variant}` : ""}${className ? ` ${className}` : ""}`}
+  >
+    {label && <div className="vc-side-card__label">{label}</div>}
+    {(heading || sub) && (
+      <div className="vc-side-card__head">
+        {heading && <h3>{heading}</h3>}
+        {sub && <span className="vc-side-card__sub">{sub}</span>}
+      </div>
+    )}
+    {children}
+  </div>
+);
+
+export { SidePanel, SideCard };

package/template/src/components/plugin-kit/StageHeader.tsx

@@ -0,0 +1,35 @@
+import React from "react";
+
+export interface StageHeaderProps {
+  title: string;
+  subtitle?: string;
+  /** Slot rendered on the right — typically StatBadge components. */
+  children?: React.ReactNode;
+  className?: string;
+}
+
+/**
+ * Title + subtitle + right-aligned stats area.
+ *
+ * @example
+ * <StageHeader title="ECS Autoscaling" subtitle="Watch containers scale">
+ *   <StatBadge label="Phase" value="alarm" color="#fda4af" />
+ *   <StatBadge label="Tasks" value="3/5" />
+ * </StageHeader>
+ */
+const StageHeader: React.FC<StageHeaderProps> = ({
+  title,
+  subtitle,
+  children,
+  className,
+}) => (
+  <div className={`vc-stage-header${className ? ` ${className}` : ""}`}>
+    <div className="vc-stage-header__text">
+      <h2>{title}</h2>
+      {subtitle && <p>{subtitle}</p>}
+    </div>
+    {children && <div className="vc-stage-header__stats">{children}</div>}
+  </div>
+);
+
+export default StageHeader;

package/template/src/components/plugin-kit/StatBadge.tsx

@@ -0,0 +1,35 @@
+import React from "react";
+
+export interface StatBadgeProps {
+  label: string;
+  value: React.ReactNode;
+  /** Colour applied to the value text. */
+  color?: string;
+  className?: string;
+}
+
+/**
+ * A small stat/phase chip: uppercase label over a bold value.
+ *
+ * @example
+ * <StatBadge label="Phase" value="sync" color="#93c5fd" />
+ * <StatBadge label="Tasks" value="3/5" />
+ */
+const StatBadge: React.FC<StatBadgeProps> = ({
+  label,
+  value,
+  color,
+  className,
+}) => (
+  <div className={`vc-stat-badge${className ? ` ${className}` : ""}`}>
+    <span className="vc-stat-badge__label">{label}</span>
+    <span
+      className="vc-stat-badge__value"
+      style={color ? { color } : undefined}
+    >
+      {value}
+    </span>
+  </div>
+);
+
+export default StatBadge;

package/template/src/components/plugin-kit/index.ts

@@ -0,0 +1,42 @@
+/* ═══════════════════════════════════════════════════════
+ *  VizCraft Plugin Kit
+ *
+ *  Shared, composable building blocks for plugin authors.
+ *
+ *  Usage:
+ *    import {
+ *      ConceptPills,
+ *      useConceptModal,
+ *      PluginLayout,
+ *      StageHeader,
+ *      StatBadge,
+ *      SidePanel,
+ *      SideCard,
+ *      CanvasStage,
+ *    } from "../../components/plugin-kit";
+ *
+ *  Styles:
+ *    @use "../../components/plugin-kit/plugin-kit";
+ *    — or import plugin-kit.scss once in your main.scss
+ * ═══════════════════════════════════════════════════════ */
+
+export { default as ConceptPills } from "./ConceptPills";
+export type { PillDef, ConceptPillsProps } from "./ConceptPills";
+
+export { useConceptModal } from "./useConceptModal";
+export type { ConceptDefinition } from "./useConceptModal";
+
+export { default as PluginLayout } from "./PluginLayout";
+export type { PluginLayoutProps } from "./PluginLayout";
+
+export { default as StageHeader } from "./StageHeader";
+export type { StageHeaderProps } from "./StageHeader";
+
+export { default as StatBadge } from "./StatBadge";
+export type { StatBadgeProps } from "./StatBadge";
+
+export { SidePanel, SideCard } from "./SidePanel";
+export type { SidePanelProps, SideCardProps } from "./SidePanel";
+
+export { default as CanvasStage } from "./CanvasStage";
+export type { CanvasStageProps } from "./CanvasStage";

package/template/src/components/plugin-kit/plugin-kit.scss

@@ -0,0 +1,241 @@
+/* ═══════════════════════════════════════════════════════
+ *  VizCraft Plugin Kit — shared styles
+ *
+ *  Import this once in your plugin's main.scss:
+ *    @use "../../components/plugin-kit/plugin-kit";
+ *
+ *  Or import globally in index.scss.
+ *
+ *  All classes are prefixed `vc-` to avoid collisions
+ *  with plugin-specific styles.
+ * ═══════════════════════════════════════════════════════ */
+
+/* ── Plugin Layout ──────────────────────────────────── */
+.vc-plugin-layout {
+  display: flex;
+  flex-direction: column;
+  width: 100%;
+  height: 100%;
+  overflow: hidden;
+}
+
+.vc-plugin-layout__body {
+  flex: 1;
+  min-height: 0;
+  display: grid;
+  grid-template-columns: minmax(0, 1fr) 320px;
+  gap: 1rem;
+  padding: 1rem;
+
+  &--full {
+    grid-template-columns: 1fr;
+  }
+}
+
+/* ── Concept Pills ──────────────────────────────────── */
+.vc-pills {
+  display: flex;
+  gap: 0.5rem;
+  flex-wrap: wrap;
+  padding: 0.65rem 1rem;
+  flex-shrink: 0;
+  border-bottom: 1px solid rgba(148, 163, 184, 0.12);
+  background: rgba(2, 6, 23, 0.52);
+  backdrop-filter: blur(12px);
+}
+
+.vc-pill {
+  border: 1px solid transparent;
+  border-radius: 999px;
+  padding: 0.32rem 0.75rem;
+  background: rgba(15, 23, 42, 0.9);
+  font-size: 0.72rem;
+  font-weight: 700;
+  color: #fff;
+  cursor: pointer;
+  line-height: 1.3;
+  transition:
+    transform 0.14s ease,
+    background 0.14s ease,
+    border-color 0.14s ease;
+
+  &:hover {
+    transform: translateY(-1px);
+  }
+
+  &:active {
+    transform: translateY(0);
+  }
+}
+
+/* ── Light-theme pills (e.g. Big O) ─────────────────── */
+.vc-pills--light {
+  background: rgba(255, 255, 255, 0.72);
+  backdrop-filter: blur(10px);
+  border-bottom-color: rgba(251, 146, 60, 0.18);
+
+  .vc-pill {
+    background: #fff;
+    color: #1f2937;
+    box-shadow: 0 14px 30px -18px rgba(15, 23, 42, 0.45);
+  }
+}
+
+/* ── Stage Header ───────────────────────────────────── */
+.vc-stage-header {
+  display: flex;
+  align-items: flex-start;
+  justify-content: space-between;
+  gap: 0.8rem;
+  margin-bottom: 0.9rem;
+
+  h2 {
+    margin: 0;
+    font-size: 1.45rem;
+    letter-spacing: -0.02em;
+  }
+
+  p {
+    margin: 0.35rem 0 0;
+    color: #94a3b8;
+    font-size: 0.9rem;
+    line-height: 1.5;
+    max-width: 42rem;
+  }
+}
+
+.vc-stage-header__stats {
+  display: flex;
+  gap: 0.55rem;
+  flex-wrap: wrap;
+  justify-content: flex-end;
+}
+
+/* ── Stat Badge ─────────────────────────────────────── */
+.vc-stat-badge {
+  min-width: 88px;
+  padding: 0.55rem 0.75rem;
+  border-radius: 16px;
+  background: rgba(15, 23, 42, 0.78);
+  border: 1px solid rgba(148, 163, 184, 0.12);
+}
+
+.vc-stat-badge__label {
+  display: block;
+  color: #94a3b8;
+  font-size: 0.66rem;
+  font-weight: 700;
+  text-transform: uppercase;
+  letter-spacing: 0.07em;
+}
+
+.vc-stat-badge__value {
+  display: block;
+  margin-top: 0.2rem;
+  font-weight: 700;
+}
+
+/* ── Side Panel ─────────────────────────────────────── */
+.vc-side-panel {
+  min-height: 0;
+  display: flex;
+  flex-direction: column;
+  gap: 0.8rem;
+  overflow-y: auto;
+  padding-right: 0.15rem;
+}
+
+/* ── Side Card ──────────────────────────────────────── */
+.vc-side-card {
+  border-radius: 20px;
+  padding: 0.95rem 1rem;
+  background: rgba(7, 17, 34, 0.88);
+  border: 1px solid rgba(148, 163, 184, 0.18);
+  box-shadow: 0 20px 42px -28px rgba(0, 0, 0, 0.7);
+
+  h3 {
+    margin: 0;
+    font-size: 0.96rem;
+  }
+
+  p {
+    margin: 0.4rem 0 0;
+    color: #cbd5e1;
+    font-size: 0.84rem;
+    line-height: 1.55;
+  }
+}
+
+.vc-side-card__label {
+  display: block;
+  color: #94a3b8;
+  font-size: 0.66rem;
+  font-weight: 700;
+  text-transform: uppercase;
+  letter-spacing: 0.07em;
+}
+
+.vc-side-card__head {
+  display: flex;
+  align-items: flex-start;
+  justify-content: space-between;
+  gap: 0.8rem;
+}
+
+.vc-side-card__sub {
+  display: block;
+  color: #94a3b8;
+  font-size: 0.66rem;
+  font-weight: 700;
+  text-transform: uppercase;
+  letter-spacing: 0.07em;
+  text-align: right;
+}
+
+.vc-side-card--explanation {
+  background:
+    linear-gradient(135deg, rgba(15, 23, 42, 0.96), rgba(12, 74, 110, 0.44)),
+    rgba(7, 17, 34, 0.88);
+}
+
+/* ── Light-theme card (e.g. Big O) ───────────────────── */
+.vc-side-card--light {
+  background: rgba(255, 255, 255, 0.82);
+  border-color: rgba(148, 163, 184, 0.32);
+  box-shadow: 0 14px 30px -18px rgba(15, 23, 42, 0.45);
+
+  p {
+    color: #4b5563;
+  }
+}
+
+/* ── Canvas Stage ───────────────────────────────────── */
+.vc-canvas-stage {
+  position: relative;
+  flex: 1;
+  min-height: 0;
+  border-radius: 22px;
+  overflow: hidden;
+  border: 1px solid rgba(148, 163, 184, 0.12);
+  background:
+    linear-gradient(180deg, rgba(2, 6, 23, 0.96), rgba(8, 15, 30, 0.96)),
+    repeating-linear-gradient(
+      0deg,
+      rgba(148, 163, 184, 0.03),
+      rgba(148, 163, 184, 0.03) 1px,
+      transparent 1px,
+      transparent 34px
+    ),
+    repeating-linear-gradient(
+      90deg,
+      rgba(148, 163, 184, 0.03),
+      rgba(148, 163, 184, 0.03) 1px,
+      transparent 1px,
+      transparent 34px
+    );
+}
+
+.vc-canvas-stage__canvas {
+  width: 100%;
+  height: 100%;
+}

package/template/src/components/plugin-kit/useConceptModal.tsx

@@ -0,0 +1,51 @@
+import React, { useCallback, useState } from "react";
+import InfoModal from "../InfoModal/InfoModal";
+import type { InfoModalSection } from "../InfoModal/InfoModal";
+
+export interface ConceptDefinition {
+  title: string;
+  subtitle: string;
+  accentColor: string;
+  sections: InfoModalSection[];
+  aside?: React.ReactNode;
+}
+
+/**
+ * Manages concept-modal state for a plugin.
+ *
+ * @example
+ * const { openConcept, ConceptModal } = useConceptModal(concepts);
+ *
+ * return (
+ *   <>
+ *     <ConceptPills pills={pills} onOpen={openConcept} />
+ *     <ConceptModal />
+ *   </>
+ * );
+ */
+export function useConceptModal<K extends string>(
+  concepts: Record<K, ConceptDefinition>,
+) {
+  const [activeConcept, setActiveConcept] = useState<K | null>(null);
+
+  const openConcept = useCallback((key: K) => setActiveConcept(key), []);
+  const closeConcept = useCallback(() => setActiveConcept(null), []);
+
+  const ConceptModal: React.FC = () => {
+    if (!activeConcept) return null;
+    const c = concepts[activeConcept];
+    return (
+      <InfoModal
+        isOpen
+        onClose={closeConcept}
+        title={c.title}
+        subtitle={c.subtitle}
+        accentColor={c.accentColor}
+        sections={c.sections}
+        aside={c.aside}
+      />
+    );
+  };
+
+  return { activeConcept, openConcept, closeConcept, ConceptModal } as const;
+}

package/template/src/index.scss

@@ -0,0 +1,81 @@
+@import "./components/plugin-kit/plugin-kit.scss";
+
+:root {
+  font-family: system-ui, Avenir, Helvetica, Arial, sans-serif;
+  line-height: 1.5;
+  font-weight: 400;
+
+  color-scheme: light dark;
+  color: rgba(255, 255, 255, 0.87);
+  background-color: #242424;
+
+  font-synthesis: none;
+  text-rendering: optimizeLegibility;
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+}
+
+a {
+  font-weight: 500;
+  color: #646cff;
+  text-decoration: inherit;
+}
+a:hover {
+  color: #535bf2;
+}
+
+html,
+body {
+  margin: 0;
+  padding: 0;
+  width: 100%;
+  height: 100%;
+}
+
+body {
+  min-height: 100vh;
+}
+
+#root {
+  width: 100%;
+  height: 100%;
+  display: flex;
+  flex-direction: column;
+}
+
+h1 {
+  font-size: 3.2em;
+  line-height: 1.1;
+}
+
+button {
+  border-radius: 8px;
+  border: 1px solid transparent;
+  padding: 0.6em 1.2em;
+  font-size: 1em;
+  font-weight: 500;
+  font-family: inherit;
+  background-color: #1a1a1a;
+  cursor: pointer;
+  transition: border-color 0.25s;
+}
+button:hover {
+  border-color: #646cff;
+}
+button:focus,
+button:focus-visible {
+  outline: 4px auto -webkit-focus-ring-color;
+}
+
+@media (prefers-color-scheme: light) {
+  :root {
+    color: #213547;
+    background-color: #ffffff;
+  }
+  a:hover {
+    color: #747bff;
+  }
+  button {
+    background-color: #f9f9f9;
+  }
+}

package/template/src/main.tsx

@@ -0,0 +1,14 @@
+import { StrictMode } from 'react'
+import { createRoot } from 'react-dom/client'
+import { Provider } from 'react-redux'
+import { store } from './store/store'
+import './index.scss'
+import App from './App.tsx'
+
+createRoot(document.getElementById('root')!).render(
+  <StrictMode>
+    <Provider store={store}>
+      <App />
+    </Provider>
+  </StrictMode>,
+)