@mantis-core/ui 0.1.1

package/COMPONENTS.md

@@ -0,0 +1,147 @@
+# @mantis-core/ui Component Catalog
+
+This document describes what each exported UI component does, when to use it, and key integration notes.
+
+## Export Groups
+
+## Buttons
+
+- `Button`
+  - Generic action button with variant support.
+  - Use for reusable actions, not domain-specific behavior.
+
+## Loaders
+
+- `Loading`
+  - Wrapper and spinner/loading utilities for async states.
+
+## Forms
+
+- `CKEditorInput`
+  - Rich text editor input built around CKEditor.
+  - Includes content metrics type export.
+- `DateInput`
+  - Date picker field.
+- `DropDown`
+  - PrimeReact dropdown wrapper.
+- `ErrorMessage`
+  - Standardized field error rendering.
+- `FormFieldRender`
+  - Label + render prop + error wrapper for fields.
+- `HiddenField`
+  - Hidden input field support.
+- `MultiSelect`
+  - Multi-select control wrapper.
+- `NumberInput`
+  - Numeric input control.
+- `RenderField`
+  - Field renderer utility.
+- `Select`
+  - Select component wrapper.
+- `Switch`
+  - Boolean switch input.
+- `TextArea`
+  - Multi-line text input.
+- `TextInput`
+  - Standard text input.
+- `TimePicker`
+  - Time selection input.
+- `Toggle`
+  - Toggle control.
+- `ToggleInlineButton`
+  - Inline toggle button.
+- `UploadFilesPreview`
+  - Upload preview component with item/copy types.
+- `ControllerProps` (type)
+  - Shared control typing contract.
+
+## Tables
+
+- `TableToolbar`
+  - Header area for title, meta, and actions.
+- `TableFilterField`
+  - Wrapper for consistent table filter controls.
+- `ActionColumn`
+  - Action menu column helper.
+- `FilterPannel`
+  - Filter container panel.
+- `MultiSelectFilter`
+  - Multi-select filter utility for tables.
+- `IndexColumn`
+  - Index/ordinal column helper.
+- `MenuButton`
+  - Row action menu button.
+- `PaginatedTable`
+  - PrimeReact `DataTable` wrapper with Mantis Core defaults.
+  - Key props:
+    - `showIndexColumn`
+    - `showActionColumn`
+    - `useMantisCoreStyles`
+    - `actionColumnItems`
+
+## Page and Admin Layout
+
+- `FormSection`
+  - Structured form section block.
+- `PageTitle`
+  - Page heading helper.
+- `AdminPageHeader`
+  - Page header presentation component.
+- `AdminPageConfigurator`
+  - Configures admin page layout context.
+- `AdminPageLayoutProvider`
+  - Context provider for admin layout.
+- `useAdminPageLayout`
+  - Hook to read/update admin layout state.
+- `AdminPageLayoutShell`
+  - Shared admin page shell renderer.
+- `AdminBreadcrumbItem`, `AdminPageLayoutConfig` (types)
+  - Layout contract types.
+
+## Generic UI
+
+- `Pagination`
+  - Page navigation component.
+- `PaginationInfo`
+  - Current page range summary.
+- `PageSizeSelector`
+  - Page size control.
+- `RichTextPreview`
+  - Sanitized rich-text display helper.
+
+## Maps
+
+- `MapPicker`
+  - Dynamic import wrapper for client map rendering.
+- `MapPickerClient`
+  - Leaflet/react-leaflet map picker implementation.
+- `MapPickerOSM`
+  - OpenStreetMap picker variant.
+- `LatLng`, `MapPicker*Props` (types)
+  - Map contracts.
+
+## Runtime Notes
+
+1. Many components are client-side (`"use client"`).
+2. Map components depend on Leaflet assets and browser APIs.
+3. Table and paginator visuals depend on `@mantis-core/styles` classes.
+
+## Integration Rules
+
+1. Keep domain logic outside this package.
+2. Keep text/content generic when possible.
+3. If a component cannot be generic, keep it in app layer instead.
+4. Any new export must be added to:
+   - `src/index.ts`
+   - this file (`COMPONENTS.md`)
+   - package README if category-level behavior changes.
+
+## Suggested Validation For New Components
+
+```bash
+pnpm --filter @mantis-core/ui build
+pnpm --filter @mantis-core/ui typecheck
+pnpm lint
+```
+
+Also validate in at least one consuming app route.

package/README.md

@@ -0,0 +1,120 @@
+# @mantis-core/ui
+
+Reusable React component library for Mantis Core apps.
+
+## Purpose
+
+`@mantis-core/ui` centralizes shared UI primitives so feature teams can build pages without duplicating component logic across projects.
+
+## Scope
+
+- Generic UI components for forms, tables, admin layout, maps, and pagination.
+- Components intended to be reused by multiple verticals/apps.
+- Components designed to work with `@mantis-core/styles` (`mantis-core-*` class contract).
+
+## Out Of Scope
+
+- Domain-specific workflows (real estate, restaurant, carpentry, etc).
+- Business rules and domain orchestration.
+- App-level provider setup (handled by `@mantis-core/next-core`).
+
+## Installation
+
+```bash
+pnpm add @mantis-core/ui @mantis-core/styles
+```
+
+Make sure peer dependencies exist in the app (`react`, `react-dom`, `next`, `primereact`, `primeicons`).
+
+## Styling Requirement
+
+Components rely on style contracts from `@mantis-core/styles`.
+Import the required SCSS modules in your app, for example:
+
+```scss
+@use "@mantis-core/styles/scss/table.scss";
+@use "@mantis-core/styles/scss/paginator.scss";
+@use "@mantis-core/styles/scss/inputs.scss";
+```
+
+## Public API Strategy
+
+Preferred import style:
+
+```ts
+import { PaginatedTable, TableToolbar, FormFieldRender } from "@mantis-core/ui";
+```
+
+Supported subpath imports:
+
+- `@mantis-core/ui/components/*`
+- `@mantis-core/ui/table-toolbar`
+- `@mantis-core/ui/table-filter-field`
+
+Use subpaths only when you need explicit boundaries.
+
+## Component Catalog
+
+See full catalog in [COMPONENTS.md](./COMPONENTS.md).
+
+Top-level categories:
+
+- Buttons: `Button`
+- Loaders: `Loading`
+- Forms: `CKEditorInput`, `TextInput`, `Select`, `Switch`, `UploadFilesPreview`, etc
+- Tables: `PaginatedTable`, `TableToolbar`, `TableFilterField`, `ActionColumn`, etc
+- Page/Admin layout: `AdminPageConfigurator`, `AdminPageLayoutProvider`, `AdminPageLayoutShell`
+- Generic UI: `Pagination`, `PaginationInfo`, `PageSizeSelector`, `RichTextPreview`
+- Maps: `MapPicker`, `MapPickerClient`, `MapPickerOSM`
+
+## Core Usage Patterns
+
+### 1) Forms
+
+- Compose fields with `FormFieldRender` + specific input components.
+- Keep validation/business rules in the app layer.
+
+### 2) Data Tables
+
+Recommended stack:
+
+1. `TableToolbar`
+2. `TableFilterField` / `FilterPannel`
+3. `PaginatedTable`
+4. `Pagination` helpers when needed
+
+### 3) Admin Page Layout
+
+Use the layout contract together:
+
+- `AdminPageLayoutProvider`
+- `AdminPageLayoutShell`
+- `AdminPageConfigurator`
+
+### 4) Maps
+
+- `MapPicker` is dynamic/SSR-safe wrapper.
+- `MapPickerClient` and `MapPickerOSM` run on client.
+
+## Architecture Rules For Contributors
+
+1. New components must be domain-agnostic.
+2. Avoid direct business terms in props, labels, or naming.
+3. Keep runtime boundaries explicit (`"use client"` only when required).
+4. Export through `src/index.ts` and document in `COMPONENTS.md`.
+5. Preserve `mantis-core-*` visual contract for shared styles.
+
+## Build
+
+```bash
+pnpm --filter @mantis-core/ui build
+pnpm --filter @mantis-core/ui typecheck
+```
+
+## Release Checklist
+
+1. Component behavior verified in consuming app.
+2. Props/types documented.
+3. `src/index.ts` export updated.
+4. `COMPONENTS.md` updated.
+5. Add changeset.

package/dist/components/Buttons/Button.d.ts

@@ -0,0 +1,19 @@
+import { Button as PrimeButton, ButtonProps as PrimeButtonProps } from "primereact/button";
+import React from "react";
+export type ButtonVariant = "primary" | "secondary" | "accent" | "success" | "warning" | "error" | "info" | "gray" | "danger";
+interface BaseProps extends Omit<PrimeButtonProps, "onClick" | "ref"> {
+    href?: string;
+    variant?: ButtonVariant;
+    outlined?: boolean;
+    block?: boolean;
+    sm?: boolean;
+    lg?: boolean;
+    text?: boolean;
+    rounded?: boolean;
+    accessKey?: string;
+    onClick?: PrimeButtonProps["onClick"];
+}
+export type ButtonProps = BaseProps;
+declare const Button: React.ForwardRefExoticComponent<BaseProps & React.RefAttributes<PrimeButton>>;
+export default Button;
+//# sourceMappingURL=Button.d.ts.map

package/dist/components/Buttons/Button.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Button.d.ts","sourceRoot":"","sources":["../../../src/components/Buttons/Button.tsx"],"names":[],"mappings":"AAGA,OAAO,EAAE,MAAM,IAAI,WAAW,EAAE,WAAW,IAAI,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAC3F,OAAO,KAAuD,MAAM,OAAO,CAAC;AAM5E,MAAM,MAAM,aAAa,GACrB,SAAS,GACT,WAAW,GACX,QAAQ,GACR,SAAS,GACT,SAAS,GACT,OAAO,GACP,MAAM,GACN,MAAM,GACN,QAAQ,CAAC;AAEb,UAAU,SAAU,SAAQ,IAAI,CAAC,gBAAgB,EAAE,SAAS,GAAG,KAAK,CAAC;IACnE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,aAAa,CAAC;IACxB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,EAAE,CAAC,EAAE,OAAO,CAAC;IACb,EAAE,CAAC,EAAE,OAAO,CAAC;IACb,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,gBAAgB,CAAC,SAAS,CAAC,CAAC;CACvC;AAKD,MAAM,MAAM,WAAW,GAAG,SAAS,CAAC;AAGpC,QAAA,MAAM,MAAM,+EAkEX,CAAC;AAGF,eAAe,MAAM,CAAC"}

package/dist/components/Buttons/Button.js

@@ -0,0 +1,27 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import classNames from "classnames";
+import { useRouter } from "next/navigation";
+import { Button as PrimeButton } from "primereact/button";
+import { forwardRef, useCallback, useMemo } from "react";
+const Button = forwardRef(({ sm = false, lg = false, block = false, outlined = false, href, text = false, rounded = false, accessKey, variant = "primary", className, onClick, type = "button", children, ...rest }, ref) => {
+    const router = useRouter();
+    // stable handler avoids re-renders of downstream memoized components
+    const handleClick = useCallback((evt) => {
+        onClick?.(evt);
+        if (href) {
+            router.push(href);
+        }
+    }, [onClick, href, router]);
+    const classes = useMemo(() => classNames(`p-button-${variant}`, {
+        "w-full": block,
+    }, className), [variant, block, className]);
+    // Because PrimeReact button comes with a couple of generic size
+    // values we keep the prop around but don't hard‑code the string
+    // (previously ignored with ts‑ignore). When the library adds more
+    // sizes we can expose them here.
+    return (_jsx(PrimeButton, { ref: ref, className: classes, text: text, outlined: outlined, rounded: rounded, size: sm ? "small" : lg ? "large" : undefined, onClick: handleClick, type: type, accessKey: accessKey, ...rest, children: children }));
+});
+Button.displayName = "Button";
+export default Button;
+//# sourceMappingURL=Button.js.map

package/dist/components/Buttons/Button.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Button.js","sourceRoot":"","sources":["../../../src/components/Buttons/Button.tsx"],"names":[],"mappings":"AAAA,YAAY,CAAC;;AACb,OAAO,UAAU,MAAM,YAAY,CAAC;AACpC,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,OAAO,EAAE,MAAM,IAAI,WAAW,EAAmC,MAAM,mBAAmB,CAAC;AAC3F,OAAc,EAAE,UAAU,EAAc,WAAW,EAAE,OAAO,EAAE,MAAM,OAAO,CAAC;AAoC5E,MAAM,MAAM,GAAG,UAAU,CACvB,CACE,EACE,EAAE,GAAG,KAAK,EACV,EAAE,GAAG,KAAK,EACV,KAAK,GAAG,KAAK,EACb,QAAQ,GAAG,KAAK,EAChB,IAAI,EACJ,IAAI,GAAG,KAAK,EACZ,OAAO,GAAG,KAAK,EACf,SAAS,EACT,OAAO,GAAG,SAAS,EACnB,SAAS,EACT,OAAO,EACP,IAAI,GAAG,QAAQ,EACf,QAAQ,EACR,GAAG,IAAI,EACR,EACD,GAAG,EACH,EAAE;IACF,MAAM,MAAM,GAAG,SAAS,EAAE,CAAC;IAE3B,qEAAqE;IACrE,MAAM,WAAW,GAAG,WAAW,CAC7B,CAAC,GAAkC,EAAE,EAAE;QACrC,OAAO,EAAE,CAAC,GAAU,CAAC,CAAC;QACtB,IAAI,IAAI,EAAE,CAAC;YACT,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACpB,CAAC;IACH,CAAC,EACD,CAAC,OAAO,EAAE,IAAI,EAAE,MAAM,CAAC,CACxB,CAAC;IAEF,MAAM,OAAO,GAAG,OAAO,CACrB,GAAG,EAAE,CACH,UAAU,CACR,YAAY,OAAO,EAAE,EACrB;QACE,QAAQ,EAAE,KAAK;KAChB,EACD,SAAS,CACV,EACH,CAAC,OAAO,EAAE,KAAK,EAAE,SAAS,CAAC,CAC5B,CAAC;IAEF,gEAAgE;IAChE,gEAAgE;IAChE,kEAAkE;IAClE,iCAAiC;IAEjC,OAAO,CACL,KAAC,WAAW,IACV,GAAG,EAAE,GAAG,EACR,SAAS,EAAE,OAAO,EAClB,IAAI,EAAE,IAAI,EACV,QAAQ,EAAE,QAAQ,EAClB,OAAO,EAAE,OAAO,EAChB,IAAI,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,EAC7C,OAAO,EAAE,WAAW,EACpB,IAAI,EAAE,IAAI,EACV,SAAS,EAAE,SAAS,KAChB,IAAI,YACP,QAAQ,GACG,CACf,CAAC;AACJ,CAAC,CACF,CAAC;AACF,MAAM,CAAC,WAAW,GAAG,QAAQ,CAAC;AAE9B,eAAe,MAAM,CAAC"}

package/dist/components/Forms/CKEditorInput.d.ts

@@ -0,0 +1,32 @@
+import { EditorConfig } from "ckeditor5";
+import React from "react";
+import { ControllerProps } from "./types";
+type CKEditorPreset = "default" | "blog" | "property" | "note";
+export type CKEditorContentMetrics = {
+    plainText: string;
+    words: number;
+    characters: number;
+    readTimeMinutes: number;
+};
+export interface CKEditorInputProps {
+    controller: ControllerProps;
+    placeholder?: string;
+    disabled?: boolean;
+    readOnly?: boolean;
+    className?: string;
+    preset?: CKEditorPreset;
+    toolbarItems?: string[];
+    minHeight?: string;
+    maxHeight?: string;
+    showStats?: boolean;
+    validateNonEmptyHtml?: boolean;
+    requiredMessage?: string;
+    config?: EditorConfig;
+    onReady?: (editor: any) => void;
+    onHtmlChange?: (html: string) => void;
+    onPlainTextChange?: (plainText: string) => void;
+    onMetricsChange?: (metrics: CKEditorContentMetrics) => void;
+}
+declare const CKEditorInput: React.FC<CKEditorInputProps>;
+export default CKEditorInput;
+//# sourceMappingURL=CKEditorInput.d.ts.map

package/dist/components/Forms/CKEditorInput.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CKEditorInput.d.ts","sourceRoot":"","sources":["../../../src/components/Forms/CKEditorInput.tsx"],"names":[],"mappings":"AAGA,OAAO,EAKL,YAAY,EAqBb,MAAM,WAAW,CAAC;AAGnB,OAAO,KAA0B,MAAM,OAAO,CAAC;AAE/C,OAAO,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAE1C,KAAK,cAAc,GAAG,SAAS,GAAG,MAAM,GAAG,UAAU,GAAG,MAAM,CAAC;AA6K/D,MAAM,MAAM,sBAAsB,GAAG;IACnC,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,eAAe,EAAE,MAAM,CAAC;CACzB,CAAC;AAmEF,MAAM,WAAW,kBAAkB;IACjC,UAAU,EAAE,eAAe,CAAC;IAC5B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,cAAc,CAAC;IACxB,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB,OAAO,CAAC,EAAE,CAAC,MAAM,EAAE,GAAG,KAAK,IAAI,CAAC;IAChC,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACtC,iBAAiB,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,IAAI,CAAC;IAChD,eAAe,CAAC,EAAE,CAAC,OAAO,EAAE,sBAAsB,KAAK,IAAI,CAAC;CAC7D;AAED,QAAA,MAAM,aAAa,EAAE,KAAK,CAAC,EAAE,CAAC,kBAAkB,CAiN/C,CAAC;AAEF,eAAe,aAAa,CAAC"}