Frontend Architecture - HubSpot Form Builder

Overview

The frontend is a React 18 single-page application (SPA) built with TypeScript and Vite. It provides a visual editor for customizing HubSpot forms with drag-and-drop functionality and live preview.

Tech Stack

React 18.3 - UI library with concurrent features
TypeScript 5.5 - Type-safe JavaScript
Vite 5.4 - Fast build tool and dev server
Zustand 4.5 - Lightweight state management
@dnd-kit - Modern drag-and-drop library
JSZip 3.10 - ZIP file generation for module export

Component Architecture

Main Application Component

File: frontend/src/App.tsx The root component orchestrates all major features:

import { DndContext } from '@dnd-kit/core';
import { Sidebar } from './components/Sidebar';
import { LayoutBuilder } from './components/LayoutBuilder';
import { PreviewPanel } from './components/PreviewPanel';
import { useHubSpotForms } from './hooks/useHubSpotForms';
import { useLayoutStore } from './hooks/useLayoutStore';
import { useLayoutDnd } from './hooks/useLayoutDnd';

export default function App() {
  const { forms, schema, connected } = useHubSpotForms();
  const layout = useLayoutStore((state) => state.layout);
  const dnd = useLayoutDnd(schema);
  
  return (
    <DndContext
      sensors={dnd.sensors}
      onDragStart={dnd.handleDragStart}
      onDragEnd={dnd.handleDragEnd}
    >
      <Sidebar forms={forms} schema={schema} />
      <main className="canvas">
        <LayoutBuilder schema={schema} />
        <PreviewPanel schema={schema} layout={layout} />
      </main>
    </DndContext>
  );
}

Component Hierarchy

App.tsx
├── Sidebar
│   ├── HubSpotConnect
│   ├── FormSelector
│   └── DetectedFieldItem (draggable)
│
└── Canvas (main)
    ├── Header
    │   ├── View Tabs (Edit / Preview)
    │   ├── Zoom Controls
    │   └── Export Controls
    │
    ├── LayoutBuilder (Edit view)
    │   └── SortableStep (multiple)
    │       └── FieldItem (draggable)
    │
    └── PreviewPanel (Preview view)
        └── Shadow DOM (isolated preview)

Core Components

1. HubSpotConnect

File: frontend/src/components/HubSpotConnect.tsx Handles OAuth connection to HubSpot.

export function HubSpotConnect({ connected, onRefresh }: Props) {
  const handleConnect = () => {
    window.location.href = API_ENDPOINTS.oauthInstall;
  };

  const handleLogout = async () => {
    const response = await fetch(API_ENDPOINTS.oauthLogout, {
      method: 'POST',
    });
    if (response.ok) {
      window.location.reload();
    }
  };

  return (
    <div className="hubspot-connect">
      {connected ? (
        <button onClick={handleLogout}>Logout</button>
      ) : (
        <button onClick={handleConnect}>Connect to HubSpot</button>
      )}
    </div>
  );
}

2. FormSelector

File: frontend/src/components/FormSelector.tsx Dropdown for selecting a HubSpot form.

export function FormSelector({ forms, selectedFormId, onSelectFormId }: Props) {
  return (
    <select value={selectedFormId} onChange={(e) => onSelectFormId(e.target.value)}>
      <option value="">Choose a form</option>
      {forms.map((form) => (
        <option key={form.id} value={form.id}>
          {form.name}
        </option>
      ))}
    </select>
  );
}

File: frontend/src/components/Sidebar.tsx Left panel containing connection status, form selector, layout options, and field palette. Key Features:

Shows available fields (not yet added to layout)
Fields are draggable using useDraggable from @dnd-kit
Layout mode toggle (single-step / multi-step)
Add step button

function DetectedFieldItem({ field }: Props) {
  const { attributes, listeners, setNodeRef, transform, isDragging } = useDraggable({
    id: `palette:${field.name}`,
    data: { type: 'palette-field', fieldId: field.name },
  });

  return (
    <li ref={setNodeRef} {...attributes} {...listeners}>
      {field.label}
    </li>
  );
}

4. LayoutBuilder

File: frontend/src/components/LayoutBuilder.tsx Drag-and-drop canvas for building form layout. Key Features:

Multi-step support
Sortable steps (drag to reorder)
Sortable fields within steps
Up to 3 fields per row
Visual drop indicators

export function LayoutBuilder({ schema, dropPositions }: Props) {
  const layout = useLayoutStore((state) => state.layout);

  return (
    <div className="layout-builder">
      <SortableContext items={layout.steps.map((s) => s.id)}>
        <div className="steps-grid">
          {layout.steps.map((step) => (
            <SortableStep key={step.id} step={step} fields={schema.fields} />
          ))}
        </div>
      </SortableContext>
    </div>
  );
}

SortableStep Component:

function SortableStep({ step, fields }: Props) {
  const { setNodeRef, transform, isDragging } = useSortable({
    id: step.id,
    data: { type: 'step' },
  });

  const { setNodeRef: setDropRef, isOver } = useDroppable({
    id: `step-drop:${step.id}`,
    data: { type: 'step-drop', stepId: step.id },
  });

  return (
    <div ref={setNodeRef} style={{ transform: CSS.Transform.toString(transform) }}>
      <div className="step-header">
        <input value={step.title} onChange={(e) => renameStep(step.id, e.target.value)} />
        <button onClick={() => removeStep(step.id)}>Delete</button>
      </div>
      <div ref={setDropRef} className={isOver ? 'is-over' : ''}>
        {step.rows.map((row) => (
          <div key={row.id} className="field-row">
            {row.fields.map((fieldId) => (
              <FieldItem key={fieldId} fieldId={fieldId} />
            ))}
          </div>
        ))}
      </div>
    </div>
  );
}

5. PreviewPanel

File: frontend/src/components/PreviewPanel.tsx Renders live preview of form using Shadow DOM for style isolation. Key Features:

Shadow DOM isolation (no style conflicts)
Multi-step navigation
Form validation
Checkbox/radio support
Responsive field groups

export function PreviewPanel({ schema, layout }: Props) {
  const containerRef = useRef<HTMLDivElement>(null);
  const shadowRootRef = useRef<ShadowRoot | null>(null);
  const [currentStep, setCurrentStep] = useState(0);
  const [formData, setFormData] = useState<FormData>({});

  useEffect(() => {
    if (!containerRef.current) return;
    
    if (!shadowRootRef.current) {
      shadowRootRef.current = containerRef.current.attachShadow({ mode: 'open' });
    }
    
    renderPreview(shadowRootRef.current);
  }, [schema, layout, currentStep]);

  const renderPreview = (shadowRoot: ShadowRoot) => {
    shadowRoot.innerHTML = `
      <style>${PREVIEW_STYLES}</style>
      <div class="preview-container">
        <!-- Form HTML -->
      </div>
    `;
    
    // Attach event listeners
    attachEventListeners(shadowRoot);
  };

  return <div ref={containerRef} className="preview-panel" />;
}

Custom Hooks

useHubSpotForms

File: frontend/src/hooks/useHubSpotForms.ts Manages HubSpot API interactions.

export function useHubSpotForms() {
  const [forms, setForms] = useState<HubSpotForm[]>([]);
  const [schema, setSchema] = useState<FormSchema | null>(null);
  const [connected, setConnected] = useState(false);

  const checkStatus = useCallback(async () => {
    const res = await fetch(API_ENDPOINTS.oauthStatus);
    const data = await res.json();
    setConnected(data.connected);
  }, []);

  const fetchForms = useCallback(async () => {
    const res = await fetch(API_ENDPOINTS.forms);
    if (res.status === 401) {
      setConnected(false);
      throw new Error('Session expired');
    }
    const data = await res.json();
    setForms(data.forms || []);
  }, []);

  const fetchFormSchema = useCallback(async (formId: string) => {
    const res = await fetch(API_ENDPOINTS.formDetails(formId));
    const data = await res.json();
    setSchema(data.schema || null);
  }, []);

  return { forms, schema, connected, fetchForms, fetchFormSchema, checkStatus };
}

useLayoutStore

File: frontend/src/hooks/useLayoutStore.ts Zustand store for managing layout state.

import { create } from 'zustand';
import type { FormSchema, LayoutState } from 'shared';

type LayoutStore = {
  layout: LayoutState | null;
  setLayout: (layout: LayoutState) => void;
  initializeFromSchema: (schema: FormSchema) => void;
  setMode: (mode: 'one-step' | 'multi-step') => void;
  addStep: () => void;
  removeStep: (stepId: string) => void;
  renameStep: (stepId: string, title: string) => void;
  moveFieldBetweenSteps: (fieldId: string, fromIndex: number, toIndex: number) => void;
  removeFieldFromStep: (stepId: string, fieldName: string) => void;
  addFieldToNewRow: (stepId: string, fieldId: string, insertIndex?: number) => void;
  addFieldToRow: (stepId: string, fieldId: string, rowId: string, insertIndex: number) => void;
  moveFieldToNewRow: (stepId: string, fieldId: string, insertIndex?: number) => void;
  moveFieldWithinStep: (stepId: string, fieldId: string, fromRowId: string, toRowId: string, toIndex: number) => void;
};

export const useLayoutStore = create<LayoutStore>((set, get) => ({
  layout: null,
  setLayout: (layout) => set({ layout }),
  initializeFromSchema: (schema, mode = 'one-step') => {
    const fieldNames = schema.fields.map((field) => field.name);
    set({ layout: buildLayout(fieldNames, mode) });
  },
  // ... other actions
}));

Key Store Actions:

initializeFromSchema - Creates initial layout from form schema
setMode - Switches between single-step and multi-step
addStep - Adds a new step
removeStep - Removes a step (moves fields to first step)
renameStep - Updates step title
moveFieldBetweenSteps - Moves field from one step to another
addFieldToNewRow - Adds field from palette to new row
addFieldToRow - Adds field to existing row (max 3 per row)
moveFieldToNewRow - Splits field into its own row
moveFieldWithinStep - Reorders fields within a step

useLayoutDnd

File: frontend/src/hooks/useLayoutDnd.ts Manages drag-and-drop logic using @dnd-kit.

export function useLayoutDnd(schema: FormSchema | null) {
  const sensors = useSensors(
    useSensor(PointerSensor, {
      activationConstraint: { distance: 8 },
    })
  );

  const [activeId, setActiveId] = useState<string | null>(null);
  const [dropPositions, setDropPositions] = useState(new Map());

  const handleDragStart = (event: DragStartEvent) => {
    const type = event.active.data.current?.type;
    setActiveId(String(event.active.id));
  };

  const handleDragOver = (event: DragOverEvent) => {
    // Calculate drop position (before/after/inside)
    // Update visual indicators
  };

  const handleDragEnd = (event: DragEndEvent) => {
    // Execute the move operation
    // Update Zustand store
  };

  return { sensors, activeId, dropPositions, handleDragStart, handleDragOver, handleDragEnd };
}

Drag Types:

palette-field - Field from sidebar (not yet in layout)
field - Field already in layout
step - Entire step (for reordering steps)

Drop Zones:

step-drop - Drop zone for each step (adds to end)
field - Drop on existing field (combine or insert)

Drop Positions:

before - Create new row before target
after - Create new row after target
inside - Add to same row (left/right/center)

Module Generation

Export Flow

import { generateModule, downloadModule } from './utils/exportModule';

const handleGenerateModule = async () => {
  const blob = await generateModule(schema, layout);
  setGeneratedModule(blob);
};

const handleDownloadModule = () => {
  downloadModule(generatedModule, schema.name);
};

Generated Files:

fields.json - HubSpot module field definitions
module.html - HubL template with form markup
module.css - Form styles
module.js - Multi-step navigation logic
meta.json - Module metadata

See: Module Generators

State Management Flow

┌─────────────────┐
│  User Action    │
└────────┬────────┘
         │
         v
┌─────────────────┐
│  Component      │ (e.g., drag field, rename step)
└────────┬────────┘
         │
         v
┌─────────────────┐
│  useLayoutStore │ (Zustand action)
└────────┬────────┘
         │
         v
┌─────────────────┐
│  Layout State   │ (immutable update)
└────────┬────────┘
         │
         v
┌─────────────────┐
│  React Re-render│ (components subscribed to store)
└─────────────────┘

Styling Approach

Pure CSS (no framework like Tailwind)
BEM-like naming (e.g., multistep-form__tabs-item)
CSS custom properties for theming
Responsive design with media queries
Shadow DOM styles isolated in PreviewPanel

API Endpoints

File: frontend/src/config.ts

const API_BASE_URL = import.meta.env.VITE_API_URL || 'http://localhost:3001';

export const API_ENDPOINTS = {
  oauthInstall: `${API_BASE_URL}/oauth/hubspot/install`,
  oauthStatus: `${API_BASE_URL}/oauth/hubspot/status`,
  oauthLogout: `${API_BASE_URL}/oauth/hubspot/logout`,
  forms: `${API_BASE_URL}/api/forms`,
  formDetails: (id: string) => `${API_BASE_URL}/api/forms/${id}`,
};

Build Configuration

File: frontend/vite.config.ts

import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';

export default defineConfig({
  plugins: [react()],
  server: {
    port: 5174,
  },
});

Performance Considerations

React 18 concurrent features - Automatic batching, transitions
Memoization - useMemo/useCallback where appropriate
Virtualization - Can be added for large forms
Code splitting - Dynamic imports for heavy components
Shadow DOM - Prevents style recalculation in preview

Documentation Index

​Overview

​Tech Stack

​Component Architecture

​Main Application Component

​Component Hierarchy

​Core Components

​1. HubSpotConnect

​2. FormSelector

​3. Sidebar

​4. LayoutBuilder

​5. PreviewPanel

​Custom Hooks

​useHubSpotForms

​useLayoutStore

​useLayoutDnd

​Module Generation

​Export Flow

​State Management Flow

​Styling Approach

​API Endpoints

​Build Configuration

​Performance Considerations

​Related Documentation