npm package: @mantis-core/ui
Description: Reusable React UI components for Mantis Core.
Latest version: 0.2.0

# @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, `react-select`, 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

```bash
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, `react-select`, `react-datepicker`, `leaflet`, and `react-leaflet`.

## Import Strategy

Preferred:

```ts
import { PaginatedTable, TableToolbar, TextInput } 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:

```scss
@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](./docs/README.md): package documentation index
- [COMPONENTS.md](./COMPONENTS.md): lightweight component index
- [PRIMEREACT_MAPPING.md](./PRIMEREACT_MAPPING.md): lightweight dependency-map pointer

## Public API Summary

Main export groups:

- Buttons: `Button`
- Loaders: `Loading`
- Forms: `TextInput`, `TextArea`, `NumberInput`, `DropDown`, `DateInput`, `Select`, `AsyncSelect`, `Switch`, `Toggle`, `ToggleInlineButton`, `CKEditorInput`, `FileDropzone`, `UploadFilesPreview`
- 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. Update `PRIMEREACT_MAPPING.md` when the underlying implementation library changes.
5. Preserve the `mantis-core-*` style contract where shared styles are intended.

## Local Validation

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