@mantis-core/ui

Reusable React component library for Mantis Core applications.

Purpose

@mantis-core/ui centralizes reusable UI building blocks for forms, tables, admin page layout, generic state handling, and maps. The package is intended to be domain-agnostic and portable across multiple apps.

Scope

• Reusable React components and helper types.
• Wrappers around PrimeReact 11, CKEditor, and Leaflet where Mantis needs a stable contract.
• Components that optionally consume the visual contracts defined in @mantis-core/styles.

Out of Scope

• Business rules and domain-specific workflows.
• App-level providers and framework bootstrapping.
• Client branding logic outside shared tokens and styles.

Installation

pnpm add @mantis-core/ui @mantis-core/styles

Required peers:

• react
• react-dom
• next
• primereact
• primeicons
• react-hook-form

Some exports also require optional peers already pulled by this package surface, such as CKEditor, leaflet, react-leaflet, chart.js, and react-chartjs-2.

Import Strategy

Preferred:

import { PaginatedTable, TableToolbar, TextField } from "@mantis-core/ui";

Supported subpaths:

• @mantis-core/ui/components/*
• @mantis-core/ui/table-toolbar
• @mantis-core/ui/table-filter-field

Use subpaths only when you need a narrow import boundary.

Styling Model

This package does not inject CSS automatically.

• PrimeReact wrappers inherit your PrimeReact theme plus any Mantis SCSS overrides you import.
• Components with mantis-core-* classes require the matching partial from @mantis-core/styles.
• Some components use utility classes or inline styles and do not depend on a Mantis SCSS partial.

Example:

@use "@mantis-core/styles/scss/buttons.scss";
@use "@mantis-core/styles/scss/inputs.scss";
@use "@mantis-core/styles/scss/select.scss";
@use "@mantis-core/styles/scss/table.scss";
@use "@mantis-core/styles/scss/confirm-dialog.scss";

Documentation Index

• docs/README.md: package documentation index
• COMPONENTS.md: lightweight component index
• docs/contracts/dependency-map.md: which underlying PrimeReact 11 module each component wraps (generated via pnpm gen:catalog)

LLM discovery

This package ships llms.txt (component index), catalog.json (machine-readable catalog), and per-component docs/ as published files, so a consuming app's LLM can read them straight from node_modules/@mantis-core/ui/. To point the LLM at them, run once per consuming project:

pnpm exec mantis-llm      # or: npx mantis-llm  ·  yarn mantis-llm

This writes a managed pointer block into the project's CLAUDE.md / AGENTS.md (idempotent; --check for CI). See the "LLM discovery" section in the repo root docs/consumir/GETTING_STARTED.md.

Public API Summary

Main export groups:

• Buttons: Button
• Loaders: Loading
• Forms: TextField, TextArea, NumberField, SelectField, AutoCompleteField, DateField, CheckboxField, SwitchField, RadioGroup, ToggleInlineButton, CKEditorInput, FileDropzone, UploadFilesPreview — every field wrapper extends FieldControllerProps (flat name/control/rules/label, no controller={{...}} object); see docs/contracts/field-controller.md
• Form helpers: RenderField, FormFieldRender, FormActionsBar, DirtyFormGuard, useDirtyFormGuard, ErrorMessage, HiddenField
• Tables: PaginatedTable, TableToolbar, TableFilterField, ActionColumn, MenuButton, IndexColumn, FilterPannel, MultiSelectFilter
• Page layout: AdminPageConfigurator, AdminPageLayoutProvider, useAdminPageLayout, AdminPageLayoutShell, AdminPageHeader, FormSection, PageTitle
• Generic UI: Pagination, PaginationInfo, PageSizeSelector, RichTextPreview, StatusBadge, DataState, ConfirmDialog
• Maps: MapPicker, MapPickerClient, MapPickerOSM

Contributor Rules

1. Keep new exports domain-agnostic.
2. Keep the public API anchored in src/index.ts.
3. Document new exports in COMPONENTS.md.
4. Run pnpm gen:catalog to regenerate docs/contracts/dependency-map.md (and catalog.json) when the underlying implementation library changes — edit the per-component .md in docs/components/, not the generated files.
5. Preserve the mantis-core-* style contract where shared styles are intended.

Local Validation

pnpm --filter @mantis-core/ui build
pnpm --filter @mantis-core/ui typecheck