/building-react-quill-canvases

name: building-react-quill-canvases
description: >
  Author the React + Quill implementation of a PostHog canvas: the single-component contract, the
  allowed imports, Quill (PostHog's design system) component and composition rules, theme-aware
  design tokens, loading skeletons, and the in-canvas date picker. Use after building-canvases has
  routed a canvas request to a React implementation — dashboards, data boards, forms, tools, or any
  canvas that should look native to PostHog.

Building React + Quill canvases

The whole application is one React/TSX file (`src/canvas.tsx` in the source project). It must `export default` a single React component that takes no props — the host mounts it. Do not import react-dom or call createRoot.

Start from the working scaffold in [references/starter-scaffold.md](references/starter-scaffold.md) on a first build: it already wires the date picker, theme tokens, per-card skeletons, and correct typed-node result reading. Keep that wiring; replace the sample metric and layout.

Imports

Import only from: `react`, `react-dom`, `react-dom/client`, `@posthog/quill`, `recharts`, `lucide-react`, `dayjs`. Anything else — including dynamic `import()`, `require()`, `fetch()`, `<script>` tags, or remote code — fails validation. Use `@posthog/quill` for UI, `recharts` for charts, `lucide-react` for icons, `dayjs` for dates.

Quill component rules

A PostHog data board must be built entirely from `@posthog/quill` components — never a native control or a styled `<div>` standing in for one:

• Dropdown/picker → `Select` (never a native `<select>`); button → `Button` (never `<button>`);

text field → `Input`/`Textarea`; checkbox → `Checkbox`; label → `Label`.

• Table → `Table` (`TableHeader` > `TableRow` > `TableHead`, then `TableBody` > `TableRow` > `TableCell`);

panel → `Card` (`CardHeader` + `CardTitle` + `CardContent`); pill → `Badge`; titles → `Heading`; body → `Text`.

• The only non-Quill tags allowed are plain layout `<div>`s and `recharts` elements.
• Quill is built on Base UI: compose compound parts (`Select` + `SelectTrigger`/`SelectContent`/`SelectItem`),

use controlled `value` + `onValueChange`, and swap a part's element with the `render` prop (e.g. `<PopoverTrigger render={<Button …/>} />`) instead of wrapping it.

• Quill components are already themed — never restyle one with Tailwind classes or inline `style`;

use their `variant`/`size` props. Put layout utilities (`flex`, `grid`, `gap-4`, `p-4`) on your own wrapper `<div>`s.

• Buttons: default to `variant="outline"`; `variant="primary"` for the one main action only.

Styling and theme

• Style with Tailwind utilities and Quill components; reserve inline `style` for genuinely dynamic

runtime values (fixed sizes use arbitrary-value utilities like `h-[280px]`).

• The canvas follows the user's PostHog theme; a `.dark` class on the document root flips at runtime.

Color only from the design-token utilities — surfaces `bg-background bg-card bg-muted bg-primary bg-success bg-warning bg-info bg-destructive`; text `text-foreground text-muted-foreground text-card-foreground`; borders `border-border`. Never a hardcoded hex or light-only color.

• Status tokens invert the usual convention: the bare token (`bg-success`) is a pale background fill

and `-foreground` (`text-success-foreground`) is the strong readable color. Colored text or icons always use the `-foreground` utility; a filled pill pairs `bg-success text-success-foreground`. Prefer the Quill `Badge` (`variant="success"`/`"destructive"`) for deltas so you don't hand-pick.

• `bg-secondary`, `text-secondary`, `bg-accent`, and `bg-popover` are not defined in the canvas — avoid them.
• recharts strokes/fills use token CSS variables (`stroke="var(--primary)"`, grid/axes in

`var(--border)`/`var(--muted-foreground)`).

• Write Unicode glyphs (curly quotes, ellipsis, arrows, emoji) as literal characters in JSX —

`\uXXXX` escapes render verbatim in JSX text.

Loading, error, and empty states

Every data point renders a skeleton in its own `Card` while loading or refreshing: `SkeletonText` (matching `lines` and text-size `className`) for text/number values, `Skeleton` for blocks/charts. Drive `isLoading` off the data calls and set it true again on refresh; never show a blank or a jumping layout.

A failed query and an empty result are different states — never let one render as the other. `.catch` on every `ph.query`/`ph.loadInsight` must set an error state that renders visibly (the message plus a Retry button wired to the refresh nonce, as in the starter scaffold), not fall through to zeros, an empty chart, or a "no data yet" message. A query that silently swallows its error makes real breakage (a missing table, an auth failure, a bad query) look like missing data. Reserve the empty state for a query that succeeded with no rows.

Date window

A data board owns its own date control — render Quill's `DateTimePicker` (never a custom Select or native date input) inside a `Popover` whose trigger is a Quill `Button`. `PopoverContent` gets exactly `className="w-auto p-0"` and nothing is added to `DateTimePicker` beyond `value`/`onApply`/`onCancel` (it self-sizes; don't pass `compact` or widths). Re-run every query when the window changes — see the `querying-canvas-data` skill for feeding it into `dateRange`.