openforms-mui

name

openforms-mui

description

Author, render, preview and debug OpenForms FormSchemaJSON form definitions as idiomatic, themed, accessible MUI (React). Use when the user wants to design an OpenForms form, render an OpenForms schema with Material UI, convert an OpenForms JSON schema into a React MUI form, preview a form schema, or debug conditional-logic / calculated fields / cross-field validation in an OpenForms schema. This is the OpenForms *form-builder* schema (github.com/henriquefps/open-forms) — NOT the "open-form.dev" documents-as-code framework, which this skill does not cover.

openforms-mui

Runtime interpreter that renders an OpenForms FormSchemaJSON as MUI. Walk the schema on every render — no code generation, no emitted per-form files. The component mirrors the upstream OpenFormRenderer API so migration is a mechanical substitution.

What this skill is (and is not)

• Is: a React + MUI runtime for the visual form-builder schema from github.com/henriquefps/open-forms (Apache 2.0). It implements all 14 field types, both conditional-logic systems, calculated fields, and validation.
• Is not: the open-form.dev "documents as code" framework. If a request is about open-form.dev, this skill does not apply.

Where it lives

~/.pi/agent/skills/openforms-mui/
  SKILL.md
  references/            # load only the one you need
    schema.md            # FormSchemaJSON structure
    field-widget-map.md  # 14 types → MUI widget → value shape
    logic.md             # CNF andGroups, operators, formula grammar
    theme-bridge.md      # tokens → createTheme(); host theme provider
    a11y.md              # matrix / repeater / signature pitfalls
    hu-locale.md         # Hungarian conventions (opt-in via locale)
  tools/                 # the TypeScript library + preview harness
    src/                 # component, schema, logic, validation, theme, i18n
    preview/             # Vite three-panel harness + CLI
    tests/               # vitest suite
    mockups/             # approved token layer (tokens.css, ui-contract.tokens.json)

The skill is user-global — usable from any working directory, with no assumption about any particular project or document archive.

Using the component in a project

import { OpenFormsMui } from "openforms-mui"; // resolves to tools/src/index.ts

<OpenFormsMui
  schema={schema}
  answers={initialAnswers}
  readOnly={false}
  locale="en"                 // "hu" enables the Hungarian UI dictionary
  onSubmit={(answers, meta) => {
    // answers: upstream-shaped, keyed by field key (applicable fields only)
    // meta.submissionContext: your supplementary data, segregated from answers
    // meta.diagnostics: non-blocking findings (e.g. disabled/calculated violations)
  }}
  onFieldChange={(all) => {/* COMPLETE state incl. retained hidden values — not the payload */}}
/>

Single-instance resolution (required)

This is the first user-global skill to ship a package.json with installed dependencies. A consuming project that imports the component out of this directory must resolve React, react-dom, @mui/material, @mui/x-date-pickers, @emotion/react and @emotion/styled to one instance — a second React instance makes hooks throw an invalid hook call, and Emotion/MUI theme context break because they rely on module-level singletons.

These packages are declared as peerDependencies (the consumer supplies them) and additionally as devDependencies (so the preview harness runs standalone). They are never plain dependencies.

Resolve to one instance at the bundler level:

• Vite: resolve.dedupe: ["react", "react-dom", "@mui/material", "@emotion/react", "@emotion/styled"]
• Webpack: resolve.alias each of the above to the consumer's copy, or use resolve.dedupe/a single node_modules.
• A monorepo: hoist these packages so one copy is shared.

The preview harness and the vitest config already dedupe; a regression test (tests/singleton.test.tsx) pins single-instance resolution.

Preview & diagnose (CLI)

From tools/:

npm run diagnose -- path/to/schema.json      # print findings; exit 1 on any error
npm run preview  -- path/to/schema.json       # three-panel Vite harness
npm run preview  -- path/to/schema.json --reference   # side-by-side upstream 1.0.7

The harness shows: the rendered MUI form (with a Rendered form ↔ Schema source view switch), the live answers JSON with validation errors, and a CNF rule-debug panel showing each condition's operand values and outcome. It reloads on schema-file save (answers preserved) and inspects mobile/tablet/ desktop widths. --reference loads the pinned upstream vanilla renderer in an isolated frame for fidelity checking — this is the only place upstream code is loaded and it is never part of the shipped library.

Rendering a form on the pi-dashboard canvas

The npm run preview harness is a Vite dev server — great for local inspection, but it does not render on the pi-dashboard canvas. The dashboard loads a loopback canvas(kind:"url") target inside a sandbox="allow-scripts" iframe with no allow-same-origin (opaque origin), proxied under /live/<id>/. Two things break there:

1. Vite dev → blank. Vite emits absolute asset paths (/main.tsx, /@vite/client) and the harness fetches /__schema.json; under the /live/<id>/ prefix these resolve to the dashboard root → 404 → blank.
2. Static build without CORS → blank. In the opaque-origin iframe a <script type="module"> is fetched in CORS mode with Origin: null, so the static server must send Access-Control-Allow-Origin: * or the module is blocked (a plain python3 -m http.server renders blank).

Working recipe (reusable assets live in tools/):

cd tools
# 1. Static build with RELATIVE base + statically-imported schema:
#    preview/canvas-app.tsx, preview/canvas-index.html, vite.canvas.config.ts
npx vite build --config vite.canvas.config.ts        # → canvas-dist/
cp canvas-dist/canvas-index.html canvas-dist/index.html   # proxy root serves it
# 2. Serve with CORS headers (canvas-serve.mjs sets Access-Control-Allow-Origin: *)
node canvas-serve.mjs 5181

Then canvas(target:{kind:"url", url:"http://127.0.0.1:5181/"}). To point the canvas at a different schema, edit the static import in preview/canvas-app.tsx (it imports ../demo-schema.json) and rebuild. Self-verify before touching the canvas by iframing your own server with sandbox="allow-scripts" and screenshotting — that reproduces the exact dashboard sandbox. See the global skill canvas-webapp (bundled with the pi-dashboard extension) for the full rationale and pitfalls (IPv6-only Vite binds, kill %1 not persisting across tool calls).

Guided schema authoring (natural language → FormSchemaJSON)

1. Read the description; enumerate the fields, their types, and any repetition, conditional visibility, requiredness, or cross-field constraints.
2. Choose types from references/field-widget-map.md. Model a repeating group as a repeater, a single-choice grid as a matrix, a derived number as a calculated number (isCalculated + formulaExpression).
3. Express conditions as CNF andGroups (AND between groups, OR within) per references/logic.md. Cross-form constraints go in root crossFieldRules.
4. Run npm run diagnose -- schema.json. Resolve every error finding before presenting the schema as complete (warnings/infos are advisory).
5. npm run preview -- schema.json and iterate.

Iteration loop

Interpret → serve preview → run the automated accessibility check → correct findings → repeat until no serious or critical violations remain. The bundled a11y test (tests/a11y.test.tsx) runs axe over a schema covering all 14 field types; use it as the gate.

Deferred scope (do not attempt)

• Remote option loading (optionsType: "api" / optionsUrl): unsupported. Such a field renders disabled with an empty option list and a diagnostic — that diagnostic is expected, not a bug to fix.
• Upstream visual builder (builder.js): not integrated. Schemas are authored by hand, by an agent, or exported from the upstream builder.

Attribution & provenance

The schema contract originates from OpenForms (github.com/henriquefps/open-forms), which is Apache 2.0 licensed. This skill is a clean-room re-implementation from the published schema reference and observed semantics — no upstream renderer or builder source is vendored. The pinned reference version is 1.0.7 (see tools/src/provenance.ts, the single source of truth used by both this attribution and --reference mode).

Upstream publishes no npm package and its public repository is a single squashed commit mirrored from a private repo, so no release cadence can be assumed. Our TypeScript types and diagnostics pin the schema contract; --reference mode is the mechanism for detecting upstream behavioural drift.