Replace the mandatory PrimeReact foundation with Cratis-owned React Aria components

[woksin]

Consumer problem

Components 3 is backed by PrimeReact 11. PrimeUI licensing explicitly continues to apply when applications consume PrimeUI through an internal wrapper or design system, and the public OEM guidance leaves framework/toolkit distribution requiring written clarification. PrimeReact types and pass-through slots also leak renderer details into the public Components contract.

A stabilization release deliberately kept that architecture unchanged so accessibility and correctness fixes could ship without forcing a renderer migration. The next major release should make the default Components package renderer-independent and openly licensed.

Decision

Build the public @cratis/components API on Cratis-owned markup, styling contracts, and types, using React Aria Components for accessible interaction behavior and TanStack Table only where advanced table state requires it.

Keep the foundation internal: consumers continue importing @cratis/components/*, not React Aria. A PrimeReact compatibility package may be provided as @cratis/components.primereact only after PrimeTek confirms the applicable redistribution/OEM terms in writing.

Arc command/query/dialog bindings remain owned by @cratis/arc.react; Components should not hide them behind optional rendering peers.

Consumer requirements

• Preserve custom design systems through Cratis-owned CSS variables, classes, stable part names, state data attributes, and per-part overrides.
• Preserve current command, query, dialog, selection, validation, pending/empty, localization, and accessibility behavior through shared contract specs.
• Publish no PrimeReact runtime imports or PrimeReact references in declarations from the default package.
• Keep JavaScript Date compatibility at the public boundary while using internationalized date values internally where needed.
• Keep server filtering, sorting, and paging authoritative for query-backed tables.
• Provide a complete migration guide for provider setup, styling, pass-through replacement, direct Prime imports, dates, tables, dialogs, and notifications.

Validation gates

• Packed npm artifact works with npm, pnpm, and Yarn PnP.
• Arc 20, 21, and 22 consumer fixtures compile and load.
• Representative downstream applications compile against the packed artifact.
• Keyboard, focus, axe/browser, Storybook, SSR, light/dark, forced-colors, and responsive scenarios pass.
• Bundle and rendering performance are measured against the stabilization release.
• Existing public behavior specs pass against the new implementation.
• PrimeReact compatibility packaging does not ship until licensing/OEM scope is confirmed.

Deferred issues

This architecture is the intended resolution path for #162 and #163. Complete-result filtering from #159 must be designed as server-side filtering before paging rather than client filtering over one loaded page.

[woksin]

Components 4 is ready for maintainer/RC review in #177 and remains intentionally unmerged.

Acceptance evidence for the exact candidate:

• 262/262 test files, 795/795 tests
• 25/25 published subpaths load
• emitted JS/declarations are Prime-free
• npm Arc 20.3.1 / 21.19.4 / 22.1.0, pnpm, and Yarn PnP exact-artifact checks pass
• package source maps, prefixed/no-Preflight CSS, licenses/notices, fonts, Storybook, Markdown, and AI corpus pass
• Storybook baseline light/dark/product/mobile visual review plus a11y addon and automated axe foundation scan
• Custom-token design-system representative compile passes after strict provider migration
• Deeply customized canvas/compositor host representative Dialog/Stepper/Toolbar compile passes
• exact artifact: 404 KB, SHA-256 1d769e97283d4f57ce70aa2a9ce85952d9e96c182d3d045026b2cfe8e0d71fe2

The PR documents the licensing rationale, Cratis/React Aria boundary, Lara-adjacent accessible baseline, token/part contract, four representative consumer-archetype migrations, Storybook contract, and future plan.

This issue should close only if/when #177 merges. Before stable publication, run the documented full RC runtime/visual pilots for the custom-token design-system and multi-entry advanced-table archetypes. The assistant will not merge #177; @woksin and @einari review is required.

[woksin]

Final PR #177 update: latest head 3d340d6 is fully green. The documentation gate now checks 101 files / 107 local links / 0 broken; aggregate CodeQL is green after deterministic parsing replaced two new checker alerts, with both threads outdated/resolved. PR remains open and unmerged with no human review yet.

[cratis-stagehand]

Thanks for opening this - it has been received and will be looked at.

---

Posted by Stagehand (AI) - an autonomous agent, not a person. Review accordingly.