@polyxd/react

@polyxd/react

Renders Polyxd UI documents in React. Behaviour comes from Radix primitives (the same ones shadcn/ui uses); the look comes entirely from a design-system pack's semantic tokens, compiled to CSS variables.

import { PolyxdSurface } from "@polyxd/react";
import "@polyxd/react/styles.css";
import "@polyxd/react/themes/material3.css"; // one file per pack: carbon.css, polaris.css, govuk.css…

<PolyxdSurface
  document={doc}                  // a Polyxd UI document (validated with @polyxd/spec)
  data={hostData}                 // data comes from the host, never from the model
  theme="material3"
  mode="light"
  onAction={({ name, context }) => handlers[name]?.(context)}   // capability intents
  onDismiss={() => close()}
  resolveMedia={(ref) => imageUrls[ref]}                        // generated UIs never contain URLs
/>

What the renderer decides (not the model)

• Controls from semantics. A Choice with 2–4 short options renders as a segmented control, 5–10 as radios, more than 10 as a filterable list; a Toggle with an action is a switch, without one a checkbox.
• Layout from the surface's own width (container queries): tables become stacked label/value cards, action bars stack with the primary first, detail lists go single-column.
• Headings follow nesting depth. Formatting of numbers, currency, dates and relative times is localised with Intl.
• Charts pick their form from intent (trend → line, comparison → bars, composition → share bar), always show the written takeaway, and include the data as a table.
• Confirm is an alert dialog that portals inside the surface so it stays themed; typed confirmation disables the button until it matches.

Themes

npm run build:themes -w @polyxd/react compiles every packages/ds-* pack into themes/<pack>.css, scoped by [data-pxd-theme][data-pxd-mode]. Only contract tokens are emitted. Each theme also sets shadcn/ui's variable names (--primary, --background, --radius, …), so an existing shadcn app follows the same pack.

Adapters

Pass components={{ Status: MyStatus }} to replace any component renderer. The default adapter is Radix + tokens; others (for example Astryx, see docs/decisions/0002-astryx.md) plug in the same way.

Tests

npm test -w @polyxd/react builds, server-renders all 20 spec examples, checks formatting, table, chart and heading semantics, and verifies every pack compiles and the stylesheet only uses contract tokens. The gallery (apps/gallery, npm run dev -w @polyxd/gallery) is for looking at and clicking through every example in every pack, mode and width.