@apps-megafy/ui

Reusable React UI components for Megafy admission agents — chat widgets (ChatInput, MessageArea, MessageBubble, ConsentViewer, CameraCapture, ChoiceCardPanel, QuestionCardPanel, ProgressSteps, FrontendWidgetsArea with Leaflet maps, …) plus primitives (Button, Dialog, Avatar).

Also includes a reusable data table: DataTable (config-driven, on TanStack Table — client-side or server-side/manual mode) plus Table primitives, StatusBadge, Pagination, DataTableToolbar, and RowActionsMenu. For back-office table pages wired to Mendix, see @apps-megafy/backoffice-controller.

And the backoffice building blocks an admin console is assembled from: layout (AppShell, NavSidebar, PageHeader, Breadcrumb, UserMenu), surfaces and forms (Card, Input/Textarea/Select, Checkbox, FormField/FormRow, FormDialog, ImagePickerField, OrderedTokenList), feedback (AlertBanner, AsyncState/EmptyState, ConfirmDialog + useConfirm(), StatusScreen) and data display (MetricCard, DescriptionList). They carry no client wording: labels, columns and business rules stay in the consuming module.

Built with Radix UI + Tailwind (shadcn conventions), class-variance-authority, lucide-react, @tanstack/react-table, and leaflet.

Install

npm install @apps-megafy/ui react react-dom

react/react-dom are peer dependencies, supported across ^18.0.0 || ^19.0.0 (see React compatibility below).

Styling — one import, no Tailwind setup required

The package ships a fully precompiled stylesheet. You do not need Tailwind in the consuming project. Import the CSS once, at your app/widget entry:

import "@apps-megafy/ui/styles.css";

That single file contains: the design tokens (CSS variables), every Tailwind utility used by the library components (this package and the companion @apps-megafy/agentic-chat controller), the custom animations, and the Leaflet CSS (inlined). This is what makes the library drop cleanly into build systems that know nothing about Tailwind — including Mendix pluggable-widget builds.

Isolation is two mechanisms, always changed together:

• every generated utility is prefixed mfy- (mfy-flex, hover:mfy-bg-primary), so a bare Atlas or Bootstrap class (.table, .active, .hidden) can never collide with one of ours;
• every utility is emitted scoped to a [data-mfy-ui] host, so it can only apply inside our subtree.

The stylesheet has no Tailwind preflight or global page reset, and rem values are compiled to px so Atlas root font-size changes cannot rescale the widget. AdmissionChat and BackofficeController render this host themselves. When composing raw components, provide it explicitly:

<div data-mfy-ui>
  <Button>Continue</Button>
</div>

The precompiled CSS covers classes the library uses. If your own code adds new Tailwind utility classes, run Tailwind in your build with a config that matches this one — prefix: "mfy-", important: "[data-mfy-ui]", preflight disabled — and content pointing at your source and @apps-megafy/{ui,agentic-chat}/dist. If you use tailwind-merge, build it with extendTailwindMerge({ prefix: "mfy-" }); a plain twMerge does not recognise prefixed classes and silently stops deduplicating them. See the repo root README.md for the full Mendix integration guide.

Dark mode

Tokens are defined for light and .dark. Put dark on the scoped host (or a descendant inside it) to switch themes:

<div data-mfy-ui class="dark"> … </div>

Usage

import { Button, MessageBubble } from "@apps-megafy/ui";
import "@apps-megafy/ui/styles.css";

export function Example() {
  return (
    <div data-mfy-ui>
      <MessageBubble role="assistant" content="Hello!" />
      <Button variant="glow">Continue</Button>
    </div>
  );
}

React version compatibility

The components support React 18 and 19, covering the active Mendix targets:

| Mendix | React provided by the client | | --- | --- | | 10.x (incl. 10.24.1) | React 18 | | 11.0 – 11.5 | React 18 (widget tools 11.3.x still pin ^18.2.0) | | 11.6.0+ | React 19 |

Widgets receive React as a runtime-provided external — map react/react-dom to that external in your widget build; do not bundle your own. The package is built internally against React 19 and the Mendix 10 compatibility cell verifies React 18 independently. Public API types resolve against the consuming project's own @types/react.

pnpm compat:mendix10 # React 18 on :5174

Storybook (component catalog + theming)

Interactive catalog of every component with live prop controls and a per-client theme switcher:

pnpm --filter @apps-megafy/ui storybook       # dev server on :6006
pnpm --filter @apps-megafy/ui build-storybook # static build

• Client and Mode toolbars (top) switch brand theme + light/dark. Themes are pure CSS-variable overrides (.storybook/themes.ts) — the same mechanism a Mendix widget uses to rebrand: set those variables on the widget root.
• Overview → Theming is a composed panel that rebrands live across every component.
• Stories live next to components (src/**/*.stories.tsx) and are excluded from the published build.
• Storybook documents components, variants, states, interactions, and composition. Final assembled page scenarios live in the local-only, gitignored frontend/ mocks instead of stories.

Build (contributors)

pnpm --filter @apps-megafy/ui build

Runs tsc (JS + .d.ts) then a PostCSS pipeline (postcss-import → tailwindcss → autoprefixer) that compiles src/styles.css into dist/styles.css. Tailwind config: tailwind.config.ts (color tokens map to the CSS variables in src/styles.css; the custom animations agent-in, soft-sheen, stream-pulse, record-ring are defined there).