@mantis-core/ui 0.1.2 → 0.2.0

package/docs/components/multi-select-filter.md

@@ -0,0 +1,20 @@
+# MultiSelectFilter
+
+- Export: `MultiSelectFilter`
+- Import: `import { MultiSelectFilter } from "@mantis-core/ui";`
+- Base library: `primereact/multiselect`
+- Base typing: `Omit<MultiSelectProps, "value" | "onChange"> & { filterProps: ColumnFilterElementTemplateOptions }`
+- Required styles: `@mantis-core/styles/scss/inputs.scss`
+
+## Example
+
+```tsx
+filterElement={(filterProps) => (
+  <MultiSelectFilter
+    filterProps={filterProps}
+    options={statusOptions}
+    optionLabel="label"
+    optionValue="value"
+  />
+)}
+```

package/docs/components/multi-select.md

@@ -0,0 +1,23 @@
+# MultiSelect
+
+- Export: `MultiSelect`
+- Import: `import { MultiSelect } from "@mantis-core/ui";`
+- Base library: `primereact/multiselect`
+- Base typing: `Omit<PrimeMultiSelectProps, "name" | "defaultValue"> & { controller: ControllerProps; block?: boolean }`
+- Form contract: [`ControllerProps`](../contracts/controller-props.md)
+- Required styles: `@mantis-core/styles/scss/inputs.scss`
+
+## Example
+
+```tsx
+<MultiSelect
+  controller={{ name: "tags", control: form.control }}
+  block
+  options={[
+    { label: "Featured", value: "featured" },
+    { label: "Luxury", value: "luxury" },
+  ]}
+  optionLabel="label"
+  optionValue="value"
+/>
+```

package/docs/components/number-input.md

@@ -0,0 +1,20 @@
+# NumberInput
+
+- Export: `NumberInput`
+- Extra exports: `NumberInputProps`
+- Import: `import { NumberInput } from "@mantis-core/ui";`
+- Base library: `primereact/inputnumber`
+- Base typing: `Omit<InputNumberProps, "name" | "defaultValue"> & { controller: ControllerProps; block?: boolean }`
+- Form contract: [`ControllerProps`](../contracts/controller-props.md)
+- Required styles: `@mantis-core/styles/scss/inputs.scss`
+
+## Example
+
+```tsx
+<NumberInput
+  controller={{ name: "price", control: form.control }}
+  block
+  mode="currency"
+  currency="USD"
+/>
+```

package/docs/components/page-title.md

@@ -0,0 +1,13 @@
+# PageTitle
+
+- Export: `PageTitle`
+- Import: `import { PageTitle } from "@mantis-core/ui";`
+- Base library: custom typographic wrapper
+- Base typing: `PropsWithChildren`
+- Required styles: none
+
+## Example
+
+```tsx
+<PageTitle>Inventory Overview</PageTitle>
+```

package/docs/components/paginated-table.md

@@ -0,0 +1,35 @@
+# PaginatedTable
+
+- Export: `PaginatedTable`
+- Extra exports: `PaginatedTableProps`
+- Import: `import { PaginatedTable } from "@mantis-core/ui";`
+- Base library: `primereact/datatable` + `primereact/column`
+- Base typing: `DataTableBaseProps<TValue> & { showIndexColumn?; showActionColumn?; useMantisCoreStyles?; indexColumnProps?; actionColumnProps?; actionColumnItems? }`
+- Required styles: `@mantis-core/styles/scss/table.scss`
+
+## Example
+
+```tsx
+import { Column } from "primereact/column";
+
+<PaginatedTable
+  value={rows}
+  totalRecords={total}
+  lazy
+  first={first}
+  rows={pageSize}
+  onPage={onPage}
+  showActionColumn
+  actionColumnItems={(row) => [
+    { label: "Edit", icon: "pi pi-pencil", route: `/admin/listings/${row.id}` },
+  ]}
+>
+  <Column field="name" header="Name" sortable />
+  <Column field="status" header="Status" />
+</PaginatedTable>
+```
+
+## Notes
+
+- It sets Mantis defaults for pagination, stripes, gridlines, sorting, empty state, and responsive layout.
+- Set `useMantisCoreStyles={false}` only if you want plain PrimeReact styling.

package/docs/components/pagination.md

@@ -0,0 +1,27 @@
+# Pagination, PaginationInfo, and PageSizeSelector
+
+- Exports: `Pagination`, `PaginationInfo`, `PageSizeSelector`
+- Extra exports: `PaginationProps`, `PaginationInfoProps`, `PageSizeSelectorProps`
+- Import: `import { Pagination, PaginationInfo, PageSizeSelector } from "@mantis-core/ui";`
+- Base library: custom pagination UI using `@mantis-core/utils`
+- Required styles: none
+
+## Example
+
+```tsx
+<Pagination
+  currentPage={page}
+  totalPages={totalPages}
+  onPageChange={setPage}
+  maxVisible={5}
+/>
+
+<PaginationInfo currentPage={page} pageSize={pageSize} totalCount={total} />
+
+<PageSizeSelector pageSize={pageSize} onPageSizeChange={setPageSize} />
+```
+
+## Notes
+
+- This is not PrimeReact `Paginator`.
+- `paginator.scss` styles PrimeReact paginator markup, not these exports.

package/docs/components/render-field.md

@@ -0,0 +1,24 @@
+# RenderField
+
+- Export: `RenderField`
+- Extra exports: `RenderFieldProps`
+- Import: `import { RenderField } from "@mantis-core/ui";`
+- Base library: `react-hook-form` `Controller`
+- Base typing: `{ name: string; defaultValue?: any; control?: Control; render: (props: RenderProps) => ReactElement; rules?: RegisterOptions }`
+- Required styles: none
+
+## Example
+
+```tsx
+<RenderField
+  name="featured"
+  control={form.control}
+  render={({ field }) => (
+    <input
+      type="checkbox"
+      checked={!!field.value}
+      onChange={(e) => field.onChange(e.target.checked)}
+    />
+  )}
+/>
+```

package/docs/components/rich-text-preview.md

@@ -0,0 +1,18 @@
+# RichTextPreview
+
+- Export: `RichTextPreview`
+- Extra exports: `RichTextPreviewProps`
+- Import: `import { RichTextPreview } from "@mantis-core/ui";`
+- Base library: sanitized HTML renderer via `@mantis-core/utils`
+- Base typing: `{ html?: string | null; className?: string; sanitize?: boolean; size?: "sm" | "md" | "lg"; emptyFallback?: ReactNode }`
+- Required styles: `@mantis-core/styles/scss/rich-text-preview.scss`
+
+## Example
+
+```tsx
+<RichTextPreview
+  html={post.bodyHtml}
+  size="lg"
+  emptyFallback={<p>No content yet.</p>}
+/>
+```

package/docs/components/select.md

@@ -0,0 +1,28 @@
+# Select
+
+- Export: `Select`
+- Import: `import { Select } from "@mantis-core/ui";`
+- Base library: `react-select` or `react-select/creatable`
+- Base typing: `Omit<ReactSelectProps, "name" | "defaultValue"> & { controller: ControllerProps; block?: boolean; variant?: ButtonVariant; isCreatable?: boolean; onCreateOption?; formatCreateLabel? }`
+- Form contract: [`ControllerProps`](../contracts/controller-props.md)
+- Required styles: `@mantis-core/styles/scss/select.scss`
+
+## Example
+
+```tsx
+<Select
+  controller={{ name: "agent", control: form.control }}
+  block
+  variant="secondary"
+  options={[
+    { label: "Alice", value: "alice" },
+    { label: "Bob", value: "bob" },
+  ]}
+  isClearable
+/>
+```
+
+## Notes
+
+- This is not PrimeReact.
+- Keep `classNamePrefix="react-select"` behavior so the shared SCSS continues to match.

package/docs/components/status-badge.md

@@ -0,0 +1,14 @@
+# StatusBadge
+
+- Export: `StatusBadge`
+- Extra exports: `StatusBadgeProps`, `StatusBadgeTone`, `StatusBadgeSize`
+- Import: `import { StatusBadge } from "@mantis-core/ui";`
+- Base library: custom span primitive
+- Base typing: `Omit<HTMLAttributes<HTMLSpanElement>, "children"> & { label?: ReactNode; tone?: "success" | "muted" | "warning" | "info" | "danger"; size?: "sm" | "md"; block?: boolean; children?: ReactNode }`
+- Required styles: `@mantis-core/styles/scss/status-badge.scss`
+
+## Example
+
+```tsx
+<StatusBadge tone="success" size="sm" label="Published" />
+```

package/docs/components/switch.md

@@ -0,0 +1,27 @@
+# Switch
+
+- Export: `Switch`
+- Extra exports: `SwitchProps`
+- Import: `import { Switch } from "@mantis-core/ui";`
+- Base library: custom bootstrap-switch-like markup
+- Base typing: `ControllerProps & { onLabel?; offLabel?; size?; onStyle?; offStyle?; width?; height?; disabled?; onChange?; className?; style? }`
+- Form contract: [`ControllerProps`](../contracts/controller-props.md)
+- Required styles: `@mantis-core/styles/scss/switch.scss`
+
+## Example
+
+```tsx
+<Switch
+  name="enabled"
+  control={form.control}
+  defaultValue={true}
+  onLabel="Enabled"
+  offLabel="Disabled"
+  onStyle="success"
+  offStyle="light"
+/>
+```
+
+## Notes
+
+- This is not PrimeReact `InputSwitch`.

package/docs/components/table-filter-field.md

@@ -0,0 +1,21 @@
+# TableFilterField
+
+- Export: `TableFilterField`
+- Extra exports: `TableFilterFieldProps`
+- Import: `import { TableFilterField } from "@mantis-core/ui";`
+- Base library: custom filter wrapper
+- Base typing: `{ label: ReactNode; htmlFor: string; children: ReactNode; className?: string; labelClassName?: string }`
+- Required styles: `@mantis-core/styles/scss/table.scss`
+
+## Example
+
+```tsx
+<TableFilterField label="Status" htmlFor="status-filter">
+  <DropDown
+    controller={{ name: "status", control: form.control }}
+    block
+    inputId="status-filter"
+    options={statusOptions}
+  />
+</TableFilterField>
+```

package/docs/components/table-toolbar.md

@@ -0,0 +1,19 @@
+# TableToolbar
+
+- Export: `TableToolbar`
+- Extra exports: `TableToolbarProps`
+- Import: `import { TableToolbar } from "@mantis-core/ui";`
+- Base library: custom layout
+- Base typing: `{ title?: ReactNode; totalRecords?: number; meta?: ReactNode; actions?: ReactNode; className?: string; copyClassName?: string; actionsClassName?: string }`
+- Required styles: `@mantis-core/styles/scss/table.scss`
+
+## Example
+
+```tsx
+<TableToolbar
+  title="Listings"
+  totalRecords={total}
+  meta="Updated today"
+  actions={<Button label="New listing" icon="pi pi-plus" />}
+/>
+```

package/docs/components/text-area.md

@@ -0,0 +1,20 @@
+# TextArea
+
+- Export: `TextArea`
+- Extra exports: `TextAreaProps`
+- Import: `import { TextArea } from "@mantis-core/ui";`
+- Base library: `primereact/inputtextarea`
+- Base typing: `Omit<InputTextareaProps, "name" | "defaultValue" | "ref" | "onChange"> & { controller: ControllerProps; block?: boolean; loading?: boolean }`
+- Form contract: [`ControllerProps`](../contracts/controller-props.md)
+- Required styles: `@mantis-core/styles/scss/inputs.scss`
+
+## Example
+
+```tsx
+<TextArea
+  controller={{ name: "description", control: form.control }}
+  block
+  rows={6}
+  autoResize
+/>
+```

package/docs/components/text-input.md

@@ -0,0 +1,23 @@
+# TextInput
+
+- Export: `TextInput`
+- Extra exports: `TextInputProps`
+- Import: `import { TextInput } from "@mantis-core/ui";`
+- Base library: `primereact/inputtext`
+- Base typing: `Omit<InputTextProps, "name" | "defaultValue"> & { controller: ControllerProps; block?: boolean; defaultValue?: string }`
+- Form contract: [`ControllerProps`](../contracts/controller-props.md)
+- Required styles: `@mantis-core/styles/scss/inputs.scss`
+
+## Example
+
+```tsx
+<TextInput
+  controller={{ name: "title", control: form.control }}
+  block
+  placeholder="Listing title"
+/>
+```
+
+## Notes
+
+- Use this when you want PrimeReact `InputText` behavior with `react-hook-form` wiring.

package/docs/components/time-picker.md

@@ -0,0 +1,22 @@
+# TimePicker
+
+- Export: `TimePicker`
+- Import: `import { TimePicker } from "@mantis-core/ui";`
+- Base library: `react-datepicker`
+- Base typing: explicit `TimePickerProps`
+- Form contract: [`ControllerProps`](../contracts/controller-props.md)
+- Required styles: none
+
+## Example
+
+```tsx
+<TimePicker
+  controller={{ name: "openingTime", control: form.control }}
+  block
+  datePicker={{ showTimeSelectOnly: true, timeIntervals: 30 }}
+/>
+```
+
+## Notes
+
+- This is not PrimeReact `Calendar`.

package/docs/components/toggle-inline-button.md

@@ -0,0 +1,22 @@
+# ToggleInlineButton
+
+- Export: `ToggleInlineButton`
+- Extra exports: `ToggleInlineButtonProps`
+- Import: `import { ToggleInlineButton } from "@mantis-core/ui";`
+- Base library: `primereact/selectbutton`
+- Base typing: `{ controller: ControllerProps; options: any[]; variant?: ButtonVariant; multiple?: boolean }`
+- Form contract: [`ControllerProps`](../contracts/controller-props.md)
+- Required styles: `@mantis-core/styles/scss/select-button.scss`
+
+## Example
+
+```tsx
+<ToggleInlineButton
+  controller={{ name: "visibility", control: form.control }}
+  variant="accent"
+  options={[
+    { label: "Public", value: "public" },
+    { label: "Private", value: "private" },
+  ]}
+/>
+```

package/docs/components/toggle.md

@@ -0,0 +1,21 @@
+# Toggle
+
+- Export: `Toggle`
+- Extra exports: `ToggleProps`
+- Import: `import { Toggle } from "@mantis-core/ui";`
+- Base library: `primereact/checkbox`
+- Base typing: `ControllerProps & { on?; off?; size?; offstyle?; onstyle?; onClick?; active? }`
+- Form contract: [`ControllerProps`](../contracts/controller-props.md)
+- Required styles: none
+
+## Example
+
+```tsx
+<Toggle
+  name="published"
+  control={form.control}
+  defaultValue={false}
+  on="YES"
+  off="NO"
+/>
+```

package/docs/components/upload-files-preview.md

@@ -0,0 +1,26 @@
+# UploadFilesPreview
+
+- Export: `UploadFilesPreview`
+- Extra exports: `UploadFilesPreviewProps`, `UploadPreviewItem`, `UploadFilesPreviewCopy`
+- Import: `import { UploadFilesPreview } from "@mantis-core/ui";`
+- Base library: custom upload queue and sortable preview grid
+- Base typing: `UploadFilesPreviewProps<TItem extends UploadPreviewItem = UploadPreviewItem>`
+- Required styles: none
+
+## Example
+
+```tsx
+type PhotoItem = {
+  id: string;
+  fullUrl: string;
+  storagePath: string;
+};
+
+<UploadFilesPreview<PhotoItem>
+  previews={photos}
+  onUploadFile={uploadPhoto}
+  onFileUploaded={(photo) => setPhotos((prev) => [...prev, photo])}
+  onRemoveFile={(photo) => removePhoto(photo.id)}
+  onReorder={setPhotos}
+/>
+```

package/docs/contracts/controller-props.md

@@ -0,0 +1,28 @@
+# Controller Props
+
+Shared form wrappers in `@mantis-core/ui` use this contract:
+
+```ts
+export interface ControllerProps {
+  name: string;
+  rules?: RegisterOptions;
+  shouldUnregister?: boolean;
+  defaultValue?: any;
+  control?: Control;
+}
+```
+
+## Usage
+
+```tsx
+controller={{
+  name: "title",
+  control: form.control,
+  rules: { required: "Title is required" },
+}}
+```
+
+## Notes
+
+- Components that expose `controller: ControllerProps` are designed for `react-hook-form`.
+- Some components, such as `FileDropzone`, also support plain controlled mode without `controller`.

package/docs/contracts/dependency-map.md

@@ -0,0 +1,57 @@
+# Underlying Library Map
+
+Use this file when you need to know which base library a component wraps.
+
+## PrimeReact wrappers
+
+- `Button`: `primereact/button`
+- `DateInput`: `primereact/calendar`
+- `DropDown`: `primereact/dropdown`
+- `MultiSelect`: `primereact/multiselect`
+- `NumberInput`: `primereact/inputnumber`
+- `TextInput`: `primereact/inputtext`
+- `TextArea`: `primereact/inputtextarea`
+- `Toggle`: `primereact/checkbox`
+- `ToggleInlineButton`: `primereact/selectbutton`
+- `PaginatedTable`: `primereact/datatable`
+- `ActionColumn`: `primereact/column`
+- `IndexColumn`: `primereact/column`
+- `MenuButton`: `primereact/tieredmenu`
+- `FilterPannel`: `primereact/sidebar`
+- `MultiSelectFilter`: `primereact/multiselect`
+- `ConfirmDialog`: `primereact/dialog`
+
+## Non-PrimeReact wrappers
+
+- `Select`: `react-select`
+- `AsyncSelect`: `react-select/async`
+- `CKEditorInput`: `@ckeditor/ckeditor5-react` + `ckeditor5`
+- `TimePicker`: `react-datepicker`
+- `MapPickerClient`: `react-leaflet` + `leaflet`
+- `MapPickerOSM`: Leaflet loaded from CDN
+- `MapPicker`: `next/dynamic` wrapper over `MapPickerClient`
+
+## Custom components
+
+- `Loading`
+- `FileDropzone`
+- `UploadFilesPreview`
+- `FormActionsBar`
+- `FormFieldRender`
+- `RenderField`
+- `DirtyFormGuard`
+- `useDirtyFormGuard`
+- `TableToolbar`
+- `TableFilterField`
+- `PageTitle`
+- `FormSection`
+- `AdminPageHeader`
+- `AdminPageLayoutProvider`
+- `AdminPageConfigurator`
+- `AdminPageLayoutShell`
+- `Pagination`
+- `PaginationInfo`
+- `PageSizeSelector`
+- `RichTextPreview`
+- `StatusBadge`
+- `DataState`

package/docs/contracts/style-imports.md

@@ -0,0 +1,27 @@
+# Style Import Guide
+
+`@mantis-core/ui` does not inject CSS automatically. Import the matching partials from `@mantis-core/styles`.
+
+## Common imports
+
+```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/select-button.scss";
+@use "@mantis-core/styles/scss/table.scss";
+@use "@mantis-core/styles/scss/status-badge.scss";
+@use "@mantis-core/styles/scss/data-state.scss";
+@use "@mantis-core/styles/scss/confirm-dialog.scss";
+@use "@mantis-core/styles/scss/form-actions.scss";
+@use "@mantis-core/styles/scss/file-dropzone.scss";
+@use "@mantis-core/styles/scss/ckeditor.scss";
+@use "@mantis-core/styles/scss/rich-text-preview.scss";
+@use "@mantis-core/styles/scss/switch.scss";
+```
+
+## Notes
+
+- `Pagination` is a custom component and does not use `paginator.scss`.
+- `Select` and `AsyncSelect` require `select.scss`, not PrimeReact input styles.
+- Components like `Loading`, `UploadFilesPreview`, `PageTitle`, and `FormSection` rely mainly on utility classes or inline styles.

package/package.json

@@ -1,9 +1,15 @@
 {
   "name": "@mantis-core/ui",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "private": false,
   "description": "Reusable React UI components for Mantis Core.",
   "type": "module",
+  "license": "MIT",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20.0.0",
+    "pnpm": ">=10.0.0"
+  },
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {
@@ -26,8 +32,10 @@
   },
   "files": [
     "dist",
+    "docs",
     "README.md",
-    "COMPONENTS.md"
+    "COMPONENTS.md",
+    "PRIMEREACT_MAPPING.md"
   ],
   "publishConfig": {
     "access": "public"
@@ -37,7 +45,8 @@
     "primeicons": "^7.0.0",
     "primereact": "^10.9.0",
     "react": "^19.0.0",
-    "react-dom": "^19.0.0"
+    "react-dom": "^19.0.0",
+    "react-hook-form": "^7.68.0"
   },
   "dependencies": {
     "@ckeditor/ckeditor5-react": "^11.0.0",
@@ -47,11 +56,9 @@
     "leaflet": "^1.9.4",
     "lucide-react": "^0.556.0",
     "react-datepicker": "^9.0.0",
-    "react-hook-form": "^7.68.0",
     "react-leaflet": "^5.0.0",
     "react-select": "^5.10.2",
-    "@mantis-core/supabase-core": "^0.1.1",
-    "@mantis-core/utils": "^0.2.0"
+    "@mantis-core/utils": "^0.4.0"
   },
   "repository": {
     "type": "git",
@@ -70,7 +77,7 @@
   ],
   "scripts": {
     "clean": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"",
-    "build": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.build.json",
+    "build": "tsc -p tsconfig.build.json",
     "typecheck": "tsc -p tsconfig.build.json --noEmit"
   }
 }