@mantis-core/ui 0.1.3 → 0.3.0

package/docs/components/ckeditor-input.md

@@ -0,0 +1,24 @@
+# CKEditorInput
+
+- Export: `CKEditorInput`
+- Extra exports: `CKEditorInputProps`, `CKEditorContentMetrics`
+- Import: `import { CKEditorInput } from "@mantis-core/ui";`
+- Base library: `@ckeditor/ckeditor5-react` + `ckeditor5`
+- Base typing: explicit `CKEditorInputProps`
+- Form contract: [`ControllerProps`](../contracts/controller-props.md)
+- Required styles: `@mantis-core/styles/scss/ckeditor.scss`
+
+## Example
+
+```tsx
+<CKEditorInput
+  controller={{ name: "body", control: form.control }}
+  minHeight="20rem"
+  showStats
+  onMetricsChange={(metrics) => console.log(metrics.words)}
+/>
+```
+
+## Notes
+
+- This wrapper adds metrics, presets, and optional non-empty HTML validation on top of CKEditor.

package/docs/components/confirm-dialog.md

@@ -0,0 +1,21 @@
+# ConfirmDialog
+
+- Export: `ConfirmDialog`
+- Extra exports: `ConfirmDialogProps`, `ConfirmDialogSeverity`
+- Import: `import { ConfirmDialog } from "@mantis-core/ui";`
+- Base library: `primereact/dialog`
+- Base typing: explicit `ConfirmDialogProps`
+- Required styles: `@mantis-core/styles/scss/confirm-dialog.scss`
+
+## Example
+
+```tsx
+<ConfirmDialog
+  visible={open}
+  title="Delete listing"
+  message="This action cannot be undone."
+  confirmSeverity="danger"
+  onConfirm={handleDelete}
+  onCancel={() => setOpen(false)}
+/>
+```

package/docs/components/data-state.md

@@ -0,0 +1,19 @@
+# DataState
+
+- Export: `DataState`
+- Extra exports: `DataStateProps`, `DataStateStatus`
+- Import: `import { DataState } from "@mantis-core/ui";`
+- Base library: custom state wrapper + `Button`
+- Base typing: explicit `DataStateProps`
+- Required styles: `@mantis-core/styles/scss/data-state.scss`
+
+## Example
+
+```tsx
+<DataState
+  status={query.isError ? "error" : query.isLoading ? "loading" : rows.length === 0 ? "empty" : "ready"}
+  onRetry={() => query.refetch()}
+>
+  <PaginatedTable value={rows}>{/* columns */}</PaginatedTable>
+</DataState>
+```

package/docs/components/date-input.md

@@ -0,0 +1,22 @@
+# DateInput
+
+- Export: `DateInput`
+- Extra exports: `DateInputProps`
+- Import: `import { DateInput } from "@mantis-core/ui";`
+- Base library: `primereact/calendar`
+- Base typing: `Omit<CalendarProps, "name" | "defaultValue"> & { controller: ControllerProps; block?: boolean }`
+- Form contract: [`ControllerProps`](../contracts/controller-props.md)
+- Required styles:
+  - `@mantis-core/styles/scss/inputs.scss`
+  - `@mantis-core/styles/scss/date-picker.scss`
+
+## Example
+
+```tsx
+<DateInput
+  controller={{ name: "publishAt", control: form.control }}
+  block
+  showIcon
+  dateFormat="yy-mm-dd"
+/>
+```

package/docs/components/dirty-form-guard.md

@@ -0,0 +1,31 @@
+# DirtyFormGuard and useDirtyFormGuard
+
+- Exports: `DirtyFormGuard`, `useDirtyFormGuard`
+- Extra exports: `DirtyFormGuardProps`, `UseDirtyFormGuardOptions`, `UseDirtyFormGuardResult`
+- Base library: browser `beforeunload` + `window.confirm`
+- Required styles: none
+
+## Component example
+
+```tsx
+<DirtyFormGuard
+  isDirty={form.formState.isDirty}
+  message="You have unsaved changes."
+/>
+```
+
+## Hook example
+
+```tsx
+const guard = useDirtyFormGuard({
+  isDirty: form.formState.isDirty,
+  message: "Leave without saving?",
+});
+
+void guard.confirmIfDirty(async () => router.push("/admin"));
+```
+
+## Notes
+
+- Use the component for declarative page guards.
+- Use the hook when you need to wrap specific navigation or destructive actions.

package/docs/components/drop-down.md

@@ -0,0 +1,28 @@
+# DropDown
+
+- Export: `DropDown`
+- Extra exports: `DropDownProps`
+- Import: `import { DropDown } from "@mantis-core/ui";`
+- Base library: `primereact/dropdown`
+- Base typing: `Omit<DropdownProps, "name" | "defaultValue"> & { controller: ControllerProps; block?: boolean }`
+- Form contract: [`ControllerProps`](../contracts/controller-props.md)
+- Required styles: `@mantis-core/styles/scss/inputs.scss`
+
+## Example
+
+```tsx
+<DropDown
+  controller={{ name: "status", control: form.control }}
+  block
+  options={[
+    { label: "Draft", value: "draft" },
+    { label: "Published", value: "published" },
+  ]}
+  optionLabel="label"
+  optionValue="value"
+/>
+```
+
+## Notes
+
+- This is the PrimeReact dropdown wrapper, not the `react-select` wrapper.

package/docs/components/error-message.md

@@ -0,0 +1,13 @@
+# ErrorMessage
+
+- Export: `ErrorMessage`
+- Import: `import { ErrorMessage } from "@mantis-core/ui";`
+- Base library: `@hookform/error-message`
+- Base typing: wrapper export around hook-form error rendering
+- Required styles: none
+
+## Example
+
+```tsx
+<ErrorMessage errors={form.formState.errors} name="title" />
+```

package/docs/components/file-dropzone.md

@@ -0,0 +1,25 @@
+# FileDropzone
+
+- Export: `FileDropzone`
+- Extra exports: `FileDropzoneProps`, `FileDropzoneRejectedFile`, `FileDropzoneRejectCode`
+- Import: `import { FileDropzone } from "@mantis-core/ui";`
+- Base library: custom drag-and-drop file input
+- Base typing: explicit `FileDropzoneProps`
+- Required styles: `@mantis-core/styles/scss/file-dropzone.scss`
+
+## Example
+
+```tsx
+<FileDropzone
+  controller={{ name: "attachments", control: form.control, defaultValue: [] }}
+  accept={["image/*", ".pdf"]}
+  maxFiles={5}
+  maxSizeBytes={5 * 1024 * 1024}
+  label="Attachments"
+/>
+```
+
+## Notes
+
+- Supports both `react-hook-form` mode and plain controlled mode with `value` and `onChange`.
+- Rejections are normalized into `FileDropzoneRejectedFile`.

package/docs/components/filter-pannel.md

@@ -0,0 +1,23 @@
+# FilterPannel
+
+- Export: `FilterPannel`
+- Import: `import { FilterPannel } from "@mantis-core/ui";`
+- Base library: `primereact/sidebar` + `react-hook-form`
+- Base typing: `PropsWithChildren<{ onApplyFilter: (data: T) => Promise<void> }>`
+- Required styles: none
+
+## Example
+
+```tsx
+<FilterPannel<{ status: string | null; city: string | null }>
+  onApplyFilter={async (filters) => setFilters(filters)}
+>
+  <DropDown controller={{ name: "status" }} options={statusOptions} />
+  <DropDown controller={{ name: "city" }} options={cityOptions} />
+</FilterPannel>
+```
+
+## Notes
+
+- The component creates its own `FormProvider`.
+- Empty values are normalized to `null` before `onApplyFilter`.

package/docs/components/form-actions-bar.md

@@ -0,0 +1,22 @@
+# FormActionsBar
+
+- Export: `FormActionsBar`
+- Import: `import { FormActionsBar } from "@mantis-core/ui";`
+- Base library: custom layout + `Button`
+- Base typing: explicit `FormActionsBarProps`
+- Required styles: `@mantis-core/styles/scss/form-actions.scss`
+
+## Example
+
+```tsx
+<FormActionsBar
+  align="between"
+  sticky
+  leftSlot={<span>Unsaved changes</span>}
+  primaryLabel="Save"
+  primaryType="submit"
+  secondaryLabel="Cancel"
+  secondaryOutlined
+  onSecondaryClick={() => router.back()}
+/>
+```

package/docs/components/form-field-render.md

@@ -0,0 +1,20 @@
+# FormFieldRender
+
+- Export: `FormFieldRender`
+- Extra exports: `FormFieldRenderProps`
+- Import: `import { FormFieldRender } from "@mantis-core/ui";`
+- Base library: custom label and error wrapper
+- Base typing: `{ name: string; label: string | ReactElement; labelProps?; containerClassName?; render: ({ name }) => ReactElement | ReactNode }`
+- Required styles: none
+
+## Example
+
+```tsx
+<FormFieldRender
+  name="email"
+  label="Email"
+  render={({ name }) => (
+    <TextInput controller={{ name, control: form.control }} block />
+  )}
+/>
+```

package/docs/components/form-section.md

@@ -0,0 +1,15 @@
+# FormSection
+
+- Export: `FormSection`
+- Import: `import { FormSection } from "@mantis-core/ui";`
+- Base library: custom card section
+- Base typing: `{ title: string; description?: string; icon?: ReactNode; children: ReactNode; className?: string }`
+- Required styles: none
+
+## Example
+
+```tsx
+<FormSection title="Publishing" description="Visibility and timing controls">
+  <Switch name="published" control={form.control} />
+</FormSection>
+```

package/docs/components/hidden-field.md

@@ -0,0 +1,19 @@
+# HiddenField
+
+- Export: `HiddenField`
+- Extra exports: `HiddenFieldProps`
+- Import: `import { HiddenField } from "@mantis-core/ui";`
+- Base library: `react-hook-form`
+- Base typing: `ControllerProps & { hidden?: boolean }`
+- Form contract: [`ControllerProps`](../contracts/controller-props.md)
+- Required styles: none
+
+## Example
+
+```tsx
+<HiddenField
+  name="tenantId"
+  control={form.control}
+  defaultValue={tenantId}
+/>
+```

package/docs/components/index-column.md

@@ -0,0 +1,13 @@
+# IndexColumn
+
+- Export: `IndexColumn`
+- Import: `import { IndexColumn } from "@mantis-core/ui";`
+- Base library: `primereact/column`
+- Base typing: `(props?: ColumnProps) => JSX.Element`
+- Required styles: none beyond table context
+
+## Example
+
+```tsx
+<IndexColumn style={{ width: "4rem" }} />
+```

package/docs/components/loading.md

@@ -0,0 +1,21 @@
+# Loading
+
+- Export: `Loading`
+- Extra exports: `LoadingWrapperProps`
+- Import: `import { Loading } from "@mantis-core/ui";`
+- Base library: custom full-screen overlay
+- Base typing: `PropsWithChildren<{ loading?: boolean; texto?: string; className?: string }>`
+- Required styles: none
+
+## Example
+
+```tsx
+<Loading loading={isSubmitting} texto="Saving changes...">
+  <FormScreen />
+</Loading>
+```
+
+## Notes
+
+- When `loading` is `false`, it returns `children` unchanged.
+- This is a page overlay, not an inline spinner primitive.

package/docs/components/map-picker-client.md

@@ -0,0 +1,22 @@
+# MapPickerClient
+
+- Export: `MapPickerClient`
+- Extra exports: `MapPickerClientProps`
+- Import: `import { MapPickerClient } from "@mantis-core/ui";`
+- Base library: `react-leaflet` + `leaflet`
+- Base typing: `{ onLocationSelect: (lat: number, lng: number) => void; initialLat?: number | null; initialLng?: number | null }`
+- Required styles: Leaflet CSS is imported by the component
+
+## Example
+
+```tsx
+<MapPickerClient
+  initialLat={-2.9}
+  initialLng={-79.0}
+  onLocationSelect={(lat, lng) => console.log(lat, lng)}
+/>
+```
+
+## Notes
+
+- Marker assets are expected under `/leaflet/*`.

package/docs/components/map-picker-osm.md

@@ -0,0 +1,18 @@
+# MapPickerOSM
+
+- Export: `MapPickerOSM`
+- Extra exports: `MapPickerOSMProps`, `LatLng`
+- Import: `import { MapPickerOSM } from "@mantis-core/ui";`
+- Base library: Leaflet loaded from CDN
+- Base typing: `{ initialPosition?: LatLng; zoom?: number; height?: string; onChange?: (pos: LatLng) => void; onSave?: (pos: LatLng) => void }`
+- Required styles: no `@mantis-core/styles` partial; Leaflet CSS is injected from CDN
+
+## Example
+
+```tsx
+<MapPickerOSM
+  initialPosition={{ lat: -12.0464, lng: -77.0428 }}
+  onChange={(pos) => console.log(pos)}
+  onSave={(pos) => saveCoordinates(pos)}
+/>
+```

package/docs/components/map-picker.md

@@ -0,0 +1,21 @@
+# MapPicker
+
+- Export: `MapPicker`
+- Extra exports: `MapPickerProps`
+- Import: `import { MapPicker } from "@mantis-core/ui";`
+- Base library: `next/dynamic` wrapper over `MapPickerClient`
+- Base typing: `{ onLocationSelect: (lat: number, lng: number) => void; initialLat?: number | null; initialLng?: number | null }`
+- Required styles: Leaflet CSS comes from the client implementation
+
+## Example
+
+```tsx
+<MapPicker
+  initialLat={-2.9}
+  initialLng={-79.0}
+  onLocationSelect={(lat, lng) => {
+    form.setValue("lat", lat);
+    form.setValue("lng", lng);
+  }}
+/>
+```

package/docs/components/menu-button.md

@@ -0,0 +1,22 @@
+# MenuButton
+
+- Export: `MenuButton`
+- Extra exports: `MenuButtonProps`, `ActionMenuItem`
+- Import: `import { MenuButton } from "@mantis-core/ui";`
+- Base library: `primereact/tieredmenu`
+- Base typing:
+  - `ActionMenuItem extends MenuItem { route?: string; items?: ActionMenuItem[] | ActionMenuItem[][] }`
+  - `MenuButtonProps = { label?: string; icon?: string; items?: ActionMenuItem[] }`
+- Required styles: [`buttons.scss`](../../../../packages/mantis-core-styles/docs/styles/buttons.md) indirectly through `Button`
+
+## Example
+
+```tsx
+<MenuButton
+  label="Actions"
+  items={[
+    { label: "Edit", icon: "pi pi-pencil", route: "/admin/listings/1" },
+    { label: "Delete", icon: "pi pi-trash", command: () => setOpen(true) },
+  ]}
+/>
+```

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" />
+```