@mantis-core/ui 0.5.0 → 0.7.0

package/docs/components/forgot-password-form.md

@@ -2,17 +2,35 @@
 name: ForgotPasswordForm
 category: auth
 import: '@mantis-core/ui/components/auth/ForgotPasswordForm'
-whenToUse: Email-only form to trigger password reset; caller owns the reset logic.
+whenToUse: Email-only form to trigger a password-reset email; caller owns the actual reset request.
 baseLibrary: custom
+requiredStyles: []
+relatedComponents: [LoginForm, ResetPasswordForm]
 relatedNextCore: []
 props:
-  - { name: onSubmit, type: '(values: { email: string }) => void | Promise<void>', required: true }
-  - { name: title, type: string, required: false }
-  - { name: backSlot, type: ReactNode, required: false }
+  - { name: onSubmit, type: '(values: ForgotPasswordFormValues) => void | Promise<void>', required: true, description: 'Receives { email }; form manages isSubmitting via RHF.' }
+  - { name: title, type: string, required: false, default: '"Recuperar contraseña"' }
+  - { name: subtitle, type: string, required: false }
+  - { name: submitLabel, type: string, required: false, default: '"Enviar enlace"' }
+  - { name: backSlot, type: ReactNode, required: false, description: 'Rendered below the submit button (e.g. a "back to login" link).' }
   - { name: className, type: string, required: false }
 ---
+
 ## Example
 
 ```tsx
-<ForgotPasswordForm onSubmit={({ email }) => sendResetEmail(email)} />
+import ForgotPasswordForm from '@mantis-core/ui/components/auth/ForgotPasswordForm';
+import type { ForgotPasswordFormValues } from '@mantis-core/ui/components/auth/ForgotPasswordForm';
+
+function Example() {
+  const handleSubmit = async ({ email }: ForgotPasswordFormValues) => {
+    await fetch('/api/auth/forgot-password', { method: 'POST', body: JSON.stringify({ email }) });
+  };
+
+  return <ForgotPasswordForm onSubmit={handleSubmit} />;
+}
 ```
+
+## Notes
+
+- Single `TextField` (email, `emailRule()`), own `useForm<ForgotPasswordFormValues>({ mode: 'onChange' })`.

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

@@ -5,7 +5,7 @@ import: '@mantis-core/ui/components/Forms/FormActionsBar'
 whenToUse: Sticky-capable action bar with primary/secondary buttons and optional left/right slots for form pages.
 baseLibrary: custom
 requiredStyles: [scss/form-actions.scss]
-relatedComponents: [FormFieldRender, DirtyFormGuard]
+relatedComponents: [FormWizard, DirtyFormGuard]
 relatedNextCore: []
 props:
   - { name: className, type: string, required: false, description: 'Additional CSS class on the root element' }
@@ -26,8 +26,27 @@ props:
   - { name: secondaryDisabled, type: boolean, required: false, default: 'false', description: 'Disable secondary button' }
   - { name: onSecondaryClick, type: '() => void', required: false, description: 'Click handler for secondary button' }
 ---
+
 ## Example
 
 ```tsx
-{/* TODO: add example */}
+import FormActionsBar from '@mantis-core/ui/components/Forms/FormActionsBar';
+
+function Example() {
+  return (
+    <FormActionsBar
+      primaryLabel='Save'
+      secondaryLabel='Cancel'
+      onPrimaryClick={() => {}}
+      onSecondaryClick={() => {}}
+    />
+  );
+}
 ```
+
+## Notes
+
+- `primaryType` defaults to `submit` — inside a `<form onSubmit={handleSubmit(onSubmit)}>` the
+  primary button submits without an explicit `onPrimaryClick`.
+- `secondaryDisabled` is OR-ed with `primaryLoading`, so the secondary action is blocked while the
+  primary one is in flight.

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

@@ -2,19 +2,47 @@
 name: FormFieldRender
 category: forms
 import: '@mantis-core/ui/components/Forms/FormFieldRender'
-whenToUse: 'Wrapper that renders a label, the input slot, and a validation error message; use to compose any form control.'
+whenToUse: 'Composes a label, a render-prop input slot, and an inline ErrorMessage for one field; use to wrap a custom/non-Mantis input with the same label+error layout as the field wrappers.'
 baseLibrary: custom
-relatedComponents: [TextInput, FormActionsBar]
+relatedComponents: ['ErrorMessage', 'RenderField']
 relatedNextCore: []
 props:
-  - { name: label, type: string, required: false }
-  - { name: htmlFor, type: string, required: false }
-  - { name: error, type: 'string | FieldError', required: false }
-  - { name: required, type: boolean, required: false }
-  - { name: className, type: string, required: false }
+  - { name: name, type: string, required: true, description: 'RHF field name; forwarded to `render` and to the inline ErrorMessage.' }
+  - { name: label, type: 'string | ReactElement', required: true }
+  - { name: labelProps, type: 'LabelHTMLAttributes<HTMLLabelElement>', required: false }
+  - { name: containerClassName, type: string, required: false }
+  - { name: render, type: '({ name }: { name: string }) => ReactElement | ReactNode', required: true, description: 'Renders the actual input; receives `name` to wire to your own Controller/register call.' }
 ---
+
 ## Example
 
 ```tsx
-<FormFieldRender label='Email' htmlFor='email' error={errors.email}><TextInput controller={{ name: 'email' }} id='email' block /></FormFieldRender>
+import FormFieldRender from '@mantis-core/ui/components/Forms/FormFieldRender';
+import { Controller, FormProvider, useForm, type FieldValues } from 'react-hook-form';
+
+function Example() {
+  const methods = useForm<FieldValues>({ defaultValues: { email: '' } });
+  return (
+    <FormProvider {...methods}>
+      <FormFieldRender
+        name='email'
+        label='Email'
+        render={({ name }) => (
+          <Controller
+            name={name}
+            control={methods.control}
+            render={({ field }) => <input {...field} id={name} />}
+          />
+        )}
+      />
+    </FormProvider>
+  );
+}
 ```
+
+## Notes
+
+- Pre-`FieldControllerProps` composition primitive: `render` gets only `{ name }`, not `control` —
+  wire the actual RHF binding yourself (e.g. with `Controller`, or `RenderField`).
+- Renders an `ErrorMessage` internally, which reads react-hook-form via context — this component
+  must be used inside a `<FormProvider>`.

package/docs/components/form-section.md

@@ -12,8 +12,20 @@ props:
   - { name: children, type: ReactNode, required: true }
   - { name: className, type: string, required: false }
 ---
+
 ## Example
 
 ```tsx
-<FormSection title='Contact Info' description='Public contact details'><TextInput controller={{ name: 'email' }} block /></FormSection>
+import FormSection from '@mantis-core/ui/components/pages/FormSection';
+import { TextField } from '@mantis-core/ui/components/Forms/TextField';
+import { useForm } from 'react-hook-form';
+
+function Example() {
+  const { control } = useForm({ defaultValues: { email: '' } });
+  return (
+    <FormSection title='Contact Info' description='Public contact details'>
+      <TextField name='email' control={control} label='Email' />
+    </FormSection>
+  );
+}
 ```

package/docs/components/form-wizard.md

@@ -2,17 +2,46 @@
 name: FormWizard
 category: forms
 import: '@mantis-core/ui/components/Forms/FormWizard'
-whenToUse: 'Multi-step form navigator with step indicator and per-step validation; must render inside a FormProvider, parent owns the <form onSubmit>.'
-baseLibrary: custom
+whenToUse: 'Multi-step form navigator with a PR11 Stepper step indicator and per-step field validation; must render inside a FormProvider, parent owns the <form onSubmit>.'
+baseLibrary: '@primereact/ui/stepper'
+requiredStyles: []
+relatedComponents: [FormActionsBar, DirtyFormGuard]
 relatedNextCore: []
 props:
-  - { name: steps, type: 'FormWizardStep[]', required: true }
-  - { name: onComplete, type: '() => void | Promise<void>', required: false }
+  - { name: steps, type: 'FormWizardStep[]', required: true, description: 'Each step: `{ label, fields?: string[], content: ReactNode }`. `fields` are validated (via `trigger`) before advancing.' }
+  - { name: onComplete, type: '() => void | Promise<void>', required: false, description: 'Escape hatch for wizard usage outside a <form> element; when set, the final step''s button uses type="button" instead of "submit".' }
   - { name: submitLabel, type: string, required: false, default: '''Finalizar''' }
   - { name: className, type: string, required: false }
 ---
+
 ## Example
 
 ```tsx
-<FormProvider {...form}><form onSubmit={form.handleSubmit(onSubmit)}><FormWizard steps={[{ label: 'Datos', fields: ['name', 'email'], content: <Step1 /> }, { label: 'Confirmar', content: <Step2 /> }]} submitLabel='Guardar' /></form></FormProvider>
+import FormWizard from '@mantis-core/ui/components/Forms/FormWizard';
+import { FormProvider, useForm } from 'react-hook-form';
+
+function Example() {
+  const form = useForm({ defaultValues: { name: '', email: '' } });
+  return (
+    <FormProvider {...form}>
+      <form onSubmit={form.handleSubmit(() => {})}>
+        <FormWizard
+          steps={[
+            { label: 'Data', fields: ['name', 'email'], content: <div>Step 1</div> },
+            { label: 'Confirm', content: <div>Step 2</div> },
+          ]}
+          submitLabel='Save'
+        />
+      </form>
+    </FormProvider>
+  );
+}
 ```
+
+## Notes
+
+- `Stepper.Root` (PR11) is uncontrolled — its `value` only sets the initial step, so the indicator
+  is remounted via `key={active}` + `defaultValue={active}` to track the wizard's own step state.
+- Without `onComplete`, the final step's button is `type="submit"` — the surrounding
+  `<form onSubmit={handleSubmit(onSubmit)}>` fires with no extra wiring.
+- Steps with no `fields` skip validation entirely on "Siguiente"/next.

package/docs/components/hidden-field.md

@@ -2,15 +2,31 @@
 name: HiddenField
 category: forms
 import: '@mantis-core/ui/components/Forms/HiddenField'
-whenToUse: Registers a hidden value in react-hook-form without rendering any UI.
-baseLibrary: react-hook-form
-formContract: ControllerProps
+whenToUse: Registers a react-hook-form value with no visible UI.
+baseLibrary: custom
+formContract: FieldControllerProps
+relatedComponents: ['TextField']
 relatedNextCore: []
-props:
-  - { name: controller, type: ControllerProps, required: true }
+props: []
 ---
+
 ## Example
 
 ```tsx
-<HiddenField controller={{ name: 'id' }} />
+import { HiddenField } from '@mantis-core/ui/components/Forms/HiddenField';
+import { useForm } from 'react-hook-form';
+
+function Example() {
+  const { control } = useForm({ defaultValues: { id: '' } });
+  return <HiddenField name='id' control={control} />;
+}
 ```
+
+## Notes
+
+- Not the full `FieldControllerProps`: only the RHF-binding subset —
+  `name | control | rules | defaultValue | shouldUnregister | id` — since there is no visible
+  control, so `label`/`labelMode`/`addonBefore`/`variant`/`size`/`fluid`/`required`/`helpText`
+  don't apply. Passing them fails to compile, not just render wrong.
+- Renders a real `<input type="hidden">` (mirrors `field.value`) so the value participates in
+  native form serialization.

package/docs/components/index-column.md

@@ -2,15 +2,35 @@
 name: IndexColumn
 category: tables
 import: '@mantis-core/ui/components/Tables/IndexColumn'
-whenToUse: Returns a PrimeReact Column that renders the row's 1-based visual index; call as IndexColumn(colProps).
-baseLibrary: primereact/column
-relatedComponents: [PaginatedTable]
+whenToUse: 'Factory that returns a 1-based row-number `ColumnDef` for MantisDataTable/PaginatedTable''s `columns` array.'
+baseLibrary: '@primereact/ui/datatable'
+relatedComponents: [MantisDataTable, PaginatedTable]
 relatedNextCore: []
 props:
-  - { name: props, type: ColumnProps, required: false }
+  - { name: overrides, type: 'Partial<ColumnDef<T>>', required: false, description: 'Overrides merged onto the default index ColumnDef (field/header/width/body).' }
 ---
+
 ## Example
 
 ```tsx
-{IndexColumn({ style: { width: '50px' } })}
+import { indexColumn } from '@mantis-core/ui/components/Tables/IndexColumn';
+import { MantisDataTable } from '@mantis-core/ui/components/Tables/MantisDataTable';
+import type { ColumnDef } from '@mantis-core/ui/components/Tables/columns';
+
+interface Property {
+  id: string;
+  name: string;
+}
+
+function Example() {
+  const rows: Property[] = [{ id: '1', name: 'Casa Ceibos' }];
+  const columns: ColumnDef<Property>[] = [indexColumn<Property>({ width: '3rem' }), { field: 'name', header: 'Name' }];
+  return <MantisDataTable rows={rows} columns={columns} />;
+}
 ```
+
+## Notes
+
+- Reshaped from the PR10 `<Column/>` JSX element to a `ColumnDef<T>` factory — the canonical table is descriptor-driven, not JSX-children-driven.
+- `field` on the returned descriptor is the non-data key `"__index__"` (required by `ColumnDef` but unused for the cell); the cell renders `index + 1` via the `body` render-prop.
+- `PaginatedTable`'s `showIndexColumn`/`indexColumnOptions` props call this factory for you — reach for those first before prepending `indexColumn` by hand.

package/docs/components/line-chart.md

@@ -2,20 +2,38 @@
 name: LineChart
 category: charts
 import: '@mantis-core/ui/components/charts/LineChart'
-whenToUse: Time-series or trend data rendered as a line chart. Zero-config defaults with full options override.
-baseLibrary: custom
+whenToUse: Time-series/trend data rendered as a line chart, zero-config over chart.js defaults.
+baseLibrary: chart.js
+requiredStyles: []
 relatedComponents: [BarChart, DonutChart]
 relatedNextCore: []
 props:
   - { name: labels, type: 'string[]', required: true }
-  - { name: datasets, type: 'LineChartDataset[]', required: true, description: 'Array of ChartDataset<''line''> minus ''data'' field, which is number[]' }
-  - { name: options, type: 'ChartOptions<''line''>', required: false, description: Deep-merged over defaults }
-  - { name: colors, type: 'string[]', required: false, default: DEFAULT_COLORS palette }
-  - { name: height, type: number, required: false, default: '300' }
+  - { name: datasets, type: 'LineChartDataset[]', required: true, description: 'ChartDataset<''line''> minus ''data'', plus data: number[].' }
+  - { name: options, type: 'ChartOptions<''line''>', required: false, description: 'Deep-merged over defaultLineOptions (plugins/scales merge shallowly one level).' }
+  - { name: colors, type: 'string[]', required: false, default: 'DEFAULT_COLORS (8-color palette)', description: 'Applied per-dataset (cycled by index) to datasets that don''t specify their own borderColor/backgroundColor.' }
+  - { name: height, type: number, required: false, default: '300', description: 'Container height in px.' }
   - { name: className, type: string, required: false }
 ---
+
 ## Example
 
 ```tsx
-<LineChart labels={['Jan','Feb','Mar']} datasets={[{ label: 'Revenue', data: [100,200,150] }]} height={250} />
+import LineChart from '@mantis-core/ui/components/charts/LineChart';
+
+function Example() {
+  return (
+    <LineChart
+      labels={['Jan', 'Feb', 'Mar']}
+      datasets={[{ label: 'Revenue', data: [100, 200, 150] }]}
+      height={250}
+    />
+  );
+}
 ```
+
+## Notes
+
+- Not re-exported from the package root — import from the deep path above (`@mantis-core/ui/components/charts/LineChart`), not `@mantis-core/ui`.
+- Calls `registerCharts()` (module-level, from `./chart-setup`) on import — no separate chart.js registration needed.
+- Default `tension: 0.3` (curved line) and a 20%-opacity fill color per dataset unless overridden.

package/docs/components/loading.md

@@ -2,22 +2,31 @@
 name: Loading
 category: feedback
 import: '@mantis-core/ui/components/Loaders/Loading'
-whenToUse: 'Full-screen loading overlay with animated spinner; renders children when loading=false.'
-baseLibrary: custom
+whenToUse: Full-screen loading overlay with a themed spinner; renders children unchanged when not loading.
+baseLibrary: '@primereact/ui/progressspinner'
 relatedNextCore: []
 props:
   - { name: loading, type: boolean, required: false, default: 'false' }
-  - { name: texto, type: string, required: false, default: '''Cargando...''' }
+  - { name: texto, type: string, required: false, default: "'Cargando...'" }
   - { name: className, type: string, required: false }
   - { name: children, type: ReactNode, required: false }
 ---
+
 ## Example
 
 ```tsx
-<Loading loading={isLoading}><PageContent /></Loading>
+import Loading from '@mantis-core/ui/components/Loaders/Loading';
+
+function Example() {
+  return (
+    <Loading loading={true} texto='Loading...'>
+      <div>Page content</div>
+    </Loading>
+  );
+}
 ```
 
 ## Notes
 
 - When `loading` is `false`, it returns `children` unchanged.
-- This is a page overlay, not an inline spinner primitive.
+- This is a fixed, full-viewport overlay (indeterminate PR11 `ProgressSpinner`), not an inline spinner primitive.

package/docs/components/login-form.md

@@ -2,21 +2,46 @@
 name: LoginForm
 category: auth
 import: '@mantis-core/ui/components/auth/LoginForm'
-whenToUse: Self-contained login form with email/username + password fields; pass onSubmit to wire signIn/Supabase from the app layer.
+whenToUse: Self-contained login form (identifier + password) built on migrated TextField/PasswordInput/Button; pass onSubmit to wire signIn/Supabase from the app layer.
 baseLibrary: custom
+requiredStyles: []
+relatedComponents: [ForgotPasswordForm, ResetPasswordForm, ChangePasswordForm, UserMenu]
 relatedNextCore: []
 props:
-  - { name: onSubmit, type: '(values: LoginFormValues) => void | Promise<void>', required: true }
-  - { name: brand, type: ReactNode, required: false }
+  - { name: onSubmit, type: '(values: LoginFormValues) => void | Promise<void>', required: true, description: 'Receives { identifier, password }; form manages isSubmitting via RHF.' }
+  - { name: brand, type: ReactNode, required: false, description: 'Rendered above the title.' }
   - { name: title, type: string, required: false, default: '"Iniciar sesión"' }
   - { name: subtitle, type: string, required: false }
-  - { name: footer, type: ReactNode, required: false }
-  - { name: identifierField, type: '''email'' | ''username''', required: false, default: '"email"' }
+  - { name: footer, type: ReactNode, required: false, description: 'Rendered below the submit button (e.g. forgot-password link).' }
+  - { name: identifierField, type: '''email'' | ''username''', required: false, default: '"email"', description: 'Switches the identifier field''s validation, type, and autoComplete between email and plain username.' }
+  - { name: identifierLabel, type: string, required: false, description: 'Overrides the default label ("Correo electrónico" / "Usuario") derived from identifierField.' }
+  - { name: identifierPlaceholder, type: string, required: false }
+  - { name: passwordLabel, type: string, required: false, default: '"Contraseña"' }
+  - { name: passwordPlaceholder, type: string, required: false }
   - { name: submitLabel, type: string, required: false, default: '"Ingresar"' }
   - { name: className, type: string, required: false }
 ---
+
 ## Example
 
 ```tsx
-<LoginForm onSubmit={async (v) => { await signIn('credentials', { email: v.identifier, password: v.password }); }} brand={<Logo />} />
+import LoginForm from '@mantis-core/ui/components/auth/LoginForm';
+import type { LoginFormValues } from '@mantis-core/ui/components/auth/LoginForm';
+
+function Example() {
+  const handleSubmit = async (values: LoginFormValues) => {
+    await fetch('/api/auth/login', { method: 'POST', body: JSON.stringify(values) });
+  };
+
+  return <LoginForm onSubmit={handleSubmit} identifierField='email' />;
+}
 ```
+
+## Notes
+
+- Owns its own `useForm<LoginFormValues>({ mode: 'onChange' })` — it is not a field wrapper, so
+  there is no `control`/`FieldControllerProps` to pass in from outside.
+- `identifierField='email'` applies `emailRule()` + `notEmptyRule()`; `'username'` applies only
+  `notEmptyRule()`. Both cases still submit the value under the `identifier` key.
+- Submit `Button` shows `loading`/`disabled` from `form.formState.isSubmitting` — no extra wiring
+  needed for a pending state.

package/docs/components/mantis-data-table.md

@@ -0,0 +1,61 @@
+---
+name: MantisDataTable
+category: tables
+import: '@mantis-core/ui/components/Tables/MantisDataTable'
+whenToUse: 'The 90% shortcut over PR11''s compound DataTable — one flat `columns: ColumnDef[]` array renders the whole TableContainer→Table→THead→TBody→EmptyTBody tree with striped rows + gridlines. Default table for any grid; drop to `PaginatedTable` for pagination + index/action columns baked in.'
+baseLibrary: '@primereact/ui/datatable'
+requiredStyles: [scss/table.scss]
+relatedComponents: [PaginatedTable, ActionColumn, IndexColumn, MenuButton, FilterPannel, MultiSelectFilter]
+relatedNextCore: []
+props:
+  - { name: rows, type: 'T[]', required: true, description: 'Row data (PR11''s `data`, renamed since PR11 root''s own `rows` means page size).' }
+  - { name: columns, type: 'ColumnDef<T>[]', required: true, description: 'Flat column descriptor array — see ColumnDef shape below.' }
+  - { name: rowsPerPage, type: number, required: false, description: 'Forwarded to PR11 Root''s `rows` (page size). Only relevant with `paginator`.' }
+  - { name: selectable, type: boolean, required: false, default: 'false', description: 'Prepends a checkbox selection column. Requires `selectionMode` on the passthrough root props.' }
+  - { name: emptyMessage, type: ReactNode, required: false, default: "'No records'" }
+  - { name: filters, type: 'Record<string, string>', required: false, description: 'Current per-field filter values (page-owned state, not RHF).' }
+  - { name: onFilterChange, type: '(field: string, value: string) => void', required: false, description: 'Fires when a header filter control (text/dropdown preset or custom filterElement) changes.' }
+---
+
+## Example
+
+```tsx
+import { MantisDataTable } from '@mantis-core/ui/components/Tables/MantisDataTable';
+import { currencyCell, badgeCell } from '@mantis-core/ui/components/Tables/cell-presets';
+import type { ColumnDef } from '@mantis-core/ui/components/Tables/columns';
+
+interface Property {
+  id: string;
+  name: string;
+  price: number;
+  status: string;
+}
+
+const COLUMNS: ColumnDef<Property>[] = [
+  { field: 'name', header: 'Name', sortable: true, filter: 'text' },
+  { field: 'price', header: 'Price', cell: currencyCell({ currency: 'USD' }) },
+  {
+    field: 'status',
+    header: 'Status',
+    cell: badgeCell({ styles: { active: 'bg-green-100 text-green-700' } }),
+    filter: 'dropdown',
+    filterOptions: [
+      { label: 'Active', value: 'active' },
+      { label: 'Draft', value: 'draft' },
+    ],
+  },
+];
+
+function Example() {
+  const rows: Property[] = [{ id: '1', name: 'Casa Ceibos', price: 125000, status: 'active' }];
+  return <MantisDataTable rows={rows} columns={COLUMNS} emptyMessage='No properties yet' />;
+}
+```
+
+## Notes
+
+- `ColumnDef<T>` fields: `field` (`keyof T & string`, also the sort/filter key), `header`, `sortable?`, `width?`; cell rendering via preset `cell?: CellRenderer` or escape hatch `body?: (item: T, index: number) => ReactNode` (escape hatch always wins); filtering via preset `filter?: 'text' | 'dropdown'` (+ `filterOptions?` for dropdown) or escape hatch `filterElement?: (ctx: { value, onChange }) => ReactNode` (escape hatch always wins).
+- Cell presets from `./cell-presets`: `currencyCell({ currency?, locale? })` (defaults USD/en-US, no decimals), `dateCell({ locale?, options? })` (short localized date), `badgeCell({ styles?, className? })` (maps a cell value to Tailwind tone classes).
+- Column factories `indexColumn()` and `actionColumn()` live in `IndexColumn`/`ActionColumn` and return a `ColumnDef<T>` to prepend/append — see their own docs, or reach for `PaginatedTable`'s `showIndexColumn`/`showActionColumn` shortcuts instead of wiring them by hand.
+- Any `DataTableRootProps` not owned by this wrapper (e.g. `paginator`, `selectionMode`, `lazy`, `sortField`, `onLazyLoad`, `dataKey`) passes straight through to PR11's `DataTable.Root`.
+- The `dropdown` filter preset renders the themed PR11 `Select` (page-owned scalar value, not RHF); pagination UI only renders when `paginator` is passed through and true.

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

@@ -2,21 +2,42 @@
 name: MapPickerClient
 category: maps
 import: '@mantis-core/ui/components/Maps/MapPickerClient'
-whenToUse: Client-only Leaflet map that lets the user click to pick a coordinate; controlled via initialLat/initialLng.
-baseLibrary: react-leaflet
-relatedComponents: [MapPicker]
+whenToUse: Client-only react-leaflet map (click-to-pick marker); the piece MapPicker lazy-loads. Use directly only if you already own the ssr:false boundary.
+baseLibrary: leaflet
+requiredStyles: []
+relatedComponents: [MapPicker, MapPickerOSM]
 relatedNextCore: []
 props:
-  - { name: onLocationSelect, type: '(lat: number, lng: number) => void', required: true, description: 'Callback fired on map click with the selected coordinates' }
-  - { name: initialLat, type: 'number | null', required: false, description: 'Initial latitude for the marker and map center' }
-  - { name: initialLng, type: 'number | null', required: false, description: 'Initial longitude for the marker and map center' }
+  - { name: onLocationSelect, type: '(lat: number, lng: number) => void', required: true, description: 'Fired on map click with the picked coordinates.' }
+  - { name: initialLat, type: 'number | null', required: false, description: 'Initial marker/center latitude; defaults to a fixed Yunguilla-area center when omitted.' }
+  - { name: initialLng, type: 'number | null', required: false, description: 'Initial marker/center longitude; defaults to a fixed Yunguilla-area center when omitted.' }
 ---
+
 ## Example
 
 ```tsx
-{/* TODO: add example */}
+'use client';
+import { useState } from 'react';
+import MapPickerClient from '@mantis-core/ui/components/Maps/MapPickerClient';
+
+function Example() {
+  const [coords, setCoords] = useState<{ lat: number; lng: number } | null>(null);
+
+  return (
+    <MapPickerClient
+      onLocationSelect={(lat, lng) => setCoords({ lat, lng })}
+      initialLat={-3.26}
+      initialLng={-79.28}
+    />
+  );
+}
 ```
 
 ## Notes
 
-- Marker assets are expected under `/leaflet/*`.
+- `"use client"` component — imports `leaflet/dist/leaflet.css` and `react-leaflet` directly, so it
+  cannot render during SSR. Prefer `MapPicker` unless the caller already guarantees a client-only tree.
+- Marker icon assets are expected at `/leaflet/marker-icon.png`, `/leaflet/marker-icon-2x.png`,
+  `/leaflet/marker-shadow.png` (served from the consuming app's `public/`).
+- Internally handles container resize (`ResizeObserver` + `map.invalidateSize`) and recenters when
+  `initialLat`/`initialLng` change — no manual `invalidateSize` call needed from the caller.

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

@@ -2,19 +2,37 @@
 name: MapPickerOSM
 category: maps
 import: '@mantis-core/ui/components/Maps/MapPickerOSM'
-whenToUse: Script-injected Leaflet map (no SSR bundle cost) with click/drag marker and a save-location button.
-baseLibrary: custom
-relatedComponents: [MapPicker]
+whenToUse: Script-injected Leaflet map (no react-leaflet/SSR bundle cost) with a draggable marker and an explicit "save location" button.
+baseLibrary: leaflet
+requiredStyles: []
+relatedComponents: [MapPicker, MapPickerClient]
 relatedNextCore: []
 props:
-  - { name: initialPosition, type: LatLng, required: false, default: '{ lat: -12.0464, lng: -77.0428 }', description: 'Initial marker and center position' }
-  - { name: zoom, type: number, required: false, default: '12', description: 'Initial zoom level' }
-  - { name: height, type: string, required: false, default: '''400px''', description: 'CSS height of the map container' }
-  - { name: onChange, type: '(pos: LatLng) => void', required: false, description: 'Called on every click or marker drag' }
-  - { name: onSave, type: '(pos: LatLng) => void', required: false, description: 'Called when user clicks "Guardar ubicación"' }
+  - { name: initialPosition, type: LatLng, required: false, default: '{ lat: -12.0464, lng: -77.0428 }', description: 'Initial marker/center position.' }
+  - { name: zoom, type: number, required: false, default: '12' }
+  - { name: height, type: string, required: false, default: '''400px''', description: 'CSS height of the map container.' }
+  - { name: onChange, type: '(pos: LatLng) => void', required: false, description: 'Fired on every click or marker drag.' }
+  - { name: onSave, type: '(pos: LatLng) => void', required: false, description: 'Fired only when the user clicks the "Guardar ubicación" button.' }
 ---
+
 ## Example
 
 ```tsx
-{/* TODO: add example */}
+'use client';
+import MapPickerOSM from '@mantis-core/ui/components/Maps/MapPickerOSM';
+import type { LatLng } from '@mantis-core/ui/components/Maps/MapPickerOSM';
+
+function Example() {
+  const handleSave = (pos: LatLng) => console.log('saved', pos);
+
+  return <MapPickerOSM initialPosition={{ lat: -3.26, lng: -79.28 }} onSave={handleSave} />;
+}
 ```
+
+## Notes
+
+- Loads Leaflet from the `unpkg.com` CDN at runtime (script + stylesheet injected into
+  `document.head`/`document.body`) instead of importing the `leaflet` package — no bundler cost, but
+  requires network access to `unpkg.com` and has no offline/self-hosted mode.
+- Spanish-only UI strings are hardcoded ("Cargando mapa...", "Guardar ubicación", error text) — not
+  currently prop-configurable.

package/docs/components/map-picker.md

@@ -2,17 +2,38 @@
 name: MapPicker
 category: maps
 import: '@mantis-core/ui/components/Maps/MapPicker'
-whenToUse: Interactive Leaflet map that lets the user click to select a lat/lng coordinate; SSR-safe via next/dynamic.
-baseLibrary: next/dynamic
+whenToUse: SSR-safe entry point for the Leaflet lat/lng picker; lazy-loads MapPickerClient via next/dynamic (ssr:false).
+baseLibrary: leaflet
+requiredStyles: []
 relatedComponents: [MapPickerClient, MapPickerOSM]
 relatedNextCore: []
 props:
-  - { name: onLocationSelect, type: '(lat: number, lng: number) => void', required: true }
+  - { name: onLocationSelect, type: '(lat: number, lng: number) => void', required: true, description: 'Fired on map click with the picked coordinates.' }
   - { name: initialLat, type: 'number | null', required: false }
   - { name: initialLng, type: 'number | null', required: false }
 ---
+
 ## Example
 
 ```tsx
-<MapPicker onLocationSelect={(lat, lng) => setValue('coords', { lat, lng })} initialLat={-3.26} initialLng={-79.28} />
+import { useState } from 'react';
+import MapPicker from '@mantis-core/ui/components/Maps/MapPicker';
+
+function Example() {
+  const [coords, setCoords] = useState<{ lat: number; lng: number } | null>(null);
+
+  return (
+    <MapPicker
+      onLocationSelect={(lat, lng) => setCoords({ lat, lng })}
+      initialLat={-3.26}
+      initialLng={-79.28}
+    />
+  );
+}
 ```
+
+## Notes
+
+- Just a `next/dynamic(() => import('./MapPickerClient'), { ssr: false })` wrapper — use this
+  (not `MapPickerClient` directly) in App Router pages/layouts to avoid a `leaflet` SSR crash.
+- Loading fallback is a plain `<p>Loading map...</p>` (not themed) while the client chunk loads.