React Webview Architecture

Patterns and conventions for React webviews in vscode-documentdb.

Related skills (do not duplicate):

• webview-trpc-messaging — tRPC routers, procedures, telemetry, AbortSignal, subscriptions, WebviewController
• accessibility-aria-expert — ARIA labels, Announcer, focus management, screen reader patterns

Full reference: See references/REACT_ARCHITECTURE_GUIDELINES.md

When to Use

• Creating or modifying a webview (DocumentView, CollectionView)
• Adding new components inside src/webviews/
• Working with CollectionView context or state management
• Integrating Monaco Editor or SlickGrid
• Debugging stale closure issues in event handlers

Rendering Pipeline

Every webview boots through src/webviews/index.tsx:

root.render(
  <VSCodeFluentProvider>
    <WithWebviewContext vscodeApi={vscodeApi}>
      <Component />
    </WithWebviewContext>
  </VSCodeFluentProvider>,
);

• VSCodeFluentProvider — adapts Fluent UI theming to VS Code's active color theme. Lives in @microsoft/vscode-ext-webview-fluentui, not in src/; importing it also injects that package's Fluent overrides.
• WithWebviewContext — provides vscodeApi (postMessage) via React Context
• WebviewRegistry — maps webview names → React components (in _integration/WebviewRegistry)

Configuration from the extension host is read via useConfiguration<T>().

File Organization

viewName/
├── ViewName.tsx            # Main component
├── viewName.scss           # Styles
├── viewNameContext.ts      # Context + state types (if complex)
├── viewNameController.ts   # WebviewController subclass (extension-side)
├── viewNameRouter.ts       # tRPC router (extension-side, see webview-trpc-messaging skill)
├── constants.ts
├── components/             # Sub-components
├── hooks/                  # Custom React hooks
├── types/                  # TypeScript types
└── utils/                  # Helpers

Component Hierarchy

DocumentView (simpler, good reference pattern):

DocumentView
├── ProgressBar (conditional: isLoading)
├── ToolbarDocuments
└── MonacoEditor

CollectionView (complex, multi-tab):

CollectionView
├── ProgressBar (conditional)
├── ToolbarMainView
├── QueryEditor
│   └── MonacoAutoHeight (multiple: filter, project, sort)
├── TabList (Results | Query Insights [PREVIEW])
├── Results Tab:
│   ├── ToolbarViewNavigation + ToolbarDocumentManipulation + ViewSwitcher
│   ├── DataViewPanelTable / DataViewPanelTree / DataViewPanelJSON
│   └── ToolbarTableNavigation (Table View only)
└── Query Insights Tab:
    └── QueryInsightsMain (3-stage progressive loading)

State Management

Simple views (DocumentView): local useState + props

Complex views (CollectionView): React Context with [state, setState] tuple

export const CollectionViewContext = createContext<
    [CollectionViewContextType, React.Dispatch<React.SetStateAction<CollectionViewContextType>>]
>([DefaultCollectionViewContext, () => {}]);

// Provider in parent
const [currentContext, setCurrentContext] = useState(DefaultCollectionViewContext);
<CollectionViewContext.Provider value={[currentContext, setCurrentContext]}>

// Consumer in child
const [currentContext, setCurrentContext] = useContext(CollectionViewContext);

Always use functional updates when state depends on previous value:

setCurrentContext((prev) => ({
  ...prev,
  isLoading: true,
  activeQuery: { ...prev.activeQuery, pageNumber: 1 },
}));

Stale Closure Pattern (CRITICAL)

Third-party components (SlickGrid) bind event handlers at initialization — they don't update when state changes. Always use refs to access current data in those handlers:

const dataRef = useRef(data);
useEffect(() => {
  dataRef.current = data;
}, [data]);

const onCellDblClick = useCallback((event) => {
  const item = dataRef.current[event.detail.args.row]; // ✅ always current
  // NOT: data[event.detail.args.row]; ❌ stale closure
}, []); // stable deps only

Why: SlickGrid binds handlers once at init time. Without refs, handlers see the data from initialization, not the latest state. This caused multiple hard-to-debug issues.

Monaco Editor

Required patterns:

1. Manual layout — Monaco doesn't auto-resize:

useEffect(() => {
  const handler = debounce(() => editorRef.current?.layout(), 200);
  window.addEventListener('resize', handler);
  handleResize(); // initial layout
  return () => window.removeEventListener('resize', handler);
}, []);

2. Dispose on unmount:

return () => {
  editorRef.current?.dispose();
};

3. MonacoAutoHeight — self-sizing editor for query fields:

<MonacoAutoHeight
  adaptiveHeight={{ enabled: true, maxLines: 10, minLines: 1, lineHeight: 19 }}
  onExecuteRequest={() => onExecuteRequest()}
  onMount={(editor, monaco) => handleEditorDidMount(editor, monaco)}
/>

4. JSON Schema delay — Monaco's JSON worker may not be ready immediately after mount. An AbortController-guarded delay is used (see QueryEditor for the pattern).

Fluent UI Integration

Use @fluentui/react-components (v9), themed via VSCodeFluentProvider:

Animations: Collapse from @fluentui/react-motion-components-preview

Styling

• Each component gets its own .scss file, imported directly
• Shared styles in sharedStyles.scss, applied via @extend
• Consistent spacing unit: 10px with flexbox row-gap/column-gap
• No inline styles — move to SCSS files
• Avoid negative margins — fix layout with proper flexbox

.documentView {
  display: flex;
  flex-direction: column;
  height: 100vh;
  row-gap: 10px;
}

Custom Hooks

Conditional Rendering Patterns

Object-based switch:

{{
    'Table View': <DataViewPanelTable {...props} />,
    'Tree View': <DataViewPanelTree {...props} />,
    'JSON View': <DataViewPanelJSON {...props} />,
}[currentContext.currentView]}

Loading State

const [isLoading, setIsLoading] = useState(false);
setIsLoading(true);
try {
  await op();
} finally {
  setIsLoading(false);
}

// In render:
{
  isLoading && <ProgressBar thickness="large" shape="square" className="progressBar" />;
}

Common Pitfalls

1. Forgetting refs with third-party components → stale data in event handlers
2. Not cleaning up event listeners, Monaco instances, AbortControllers in useEffect return
3. Not calling editor.layout() after resize → blank Monaco panels
4. Using any → use proper types or unknown with type guards
5. Missing l10n.t() on user-facing strings
6. Inline styles instead of SCSS files
7. Negative margins to fix spacing — restructure layout with flexbox gap instead