@simoncomputing/mui-bueno-v3 0.1.17 → 0.2.1

package/README.md

@@ -41,7 +41,7 @@ In the application repo:
 
 ```shell
 # Update package to look for this file in the proper directory.
-npm i ~/git/mui-bueno-v3/simoncomputing-mui-bueno-v3-0.1.17.tgz
+npm i ~/git/mui-bueno-v3/simoncomputing-mui-bueno-v3-0.2.1.tgz
 
 # Install
 npm install

package/dist/components/Form/MForm/MForm2.d.ts

@@ -0,0 +1,115 @@
+import { FieldValues } from 'react-hook-form';
+import { MFormProvider2Props } from './MFormProvider2';
+import * as React from 'react';
+/**
+ * # MForm2 Documentation
+ *
+ * ## What this module is
+ * `MForm2` is a **thin convenience wrapper** around `MFormProvider2` that:
+ * - Renders the actual HTML `<form>` element.
+ * - Wires the form’s `onSubmit` event to the provider’s `submit()` function.
+ * - Preserves the ability to use either:
+ *   - **Normal children** (`ReactNode`), or
+ *   - **Render-prop children** that receive `{ methods, submit }`.
+ *
+ * `MForm2` exists so most consumers don’t need to manually place `<form>` tags or call `submit()`.
+ *
+ * ## Responsibilities
+ * 1) Delegates all RHF setup/ownership and submit logic to `MFormProvider2`.
+ * 2) Adds a `<form>` boundary with:
+ *    - `noValidate` to disable browser-native validation bubbles
+ *    - `onSubmit` to call `submit()` (which runs RHF validation + submit wrapper)
+ * 3) Exposes basic styling/identification props for the `<form>`:
+ *    - `formId`, `className`, `style`
+ *
+ * ## What MForm2 does NOT do
+ * - It does not call `useForm()` directly.
+ * - It does not implement validation logic itself.
+ * - It does not map server errors itself.
+ * - It does not manage reinitialization itself.
+ * All of those are handled by `MFormProvider2`.
+ *
+ * ## Props (high level)
+ * `MForm2Props<T>` is:
+ * - all props accepted by `MFormProvider2` (owned or controlled),
+ * - plus `MForm2BaseProps` for the `<form>` element itself.
+ *
+ * ### Base props (MForm2BaseProps)
+ * - `formId?: string`
+ *   - Applied as the `<form id="...">`.
+ *   - Useful when your submit button is outside the form (e.g., MUI DialogActions):
+ *     `<Button type="submit" form="your-form-id">Save</Button>`
+ *
+ * - `className?: string`
+ *   - Passed to the `<form>` element.
+ *
+ * - `style?: React.CSSProperties`
+ *   - Inline styles for the `<form>` element.
+ *
+ * ### Provider props (from MFormProvider2Props<T>)
+ * MForm2 supports both provider modes via the same prop union:
+ *
+ * **Controlled mode**
+ * - pass `methods: UseFormReturn<T>` to re-use an existing RHF form instance
+ *
+ * **Owned mode**
+ * - pass `defaultValues: DefaultValues<T>` (required)
+ * - optionally pass `validationSchema` (Yup) and/or `resolver`, `useFormProps`, `reinitializeKey`, etc.
+ *
+ * ## Default values (source of truth)
+ * MForm2 does not define its own default values. It forwards props to `MFormProvider2`, which chooses:
+ *
+ * - Controlled mode: default values are whatever the caller used when creating `methods` via `useForm({ defaultValues })`.
+ * - Owned mode: default values come from the required `defaultValues` prop.
+ *
+ * There are no additional default values introduced by MForm2 itself; it only forwards and wraps.
+ *
+ * ## Render-prop children
+ * Children can be either:
+ * - Regular JSX:
+ *   ```tsx
+ *   <MForm2 ...>
+ *     <MyFields />
+ *   </MForm2>
+ *   ```
+ * - Or a render function that receives:
+ *   - `methods`: RHF methods object (UseFormReturn<T>)
+ *   - `submit`: programmatic submit function (runs RHF handleSubmit)
+ *   ```tsx
+ *   <MForm2 ...>
+ *     {({ methods, submit }) => (
+ *       <>
+ *         <MyFields />
+ *         <button type="button" onClick={() => void submit()}>Save</button>
+ *       </>
+ *     )}
+ *   </MForm2>
+ *   ```
+ *
+ * ## Submit behavior
+ * The `<form onSubmit>` handler:
+ * - calls `e.preventDefault()` to avoid browser navigation,
+ * - calls `submit()` from `MFormProvider2`, which:
+ *   - runs RHF validation
+ *   - calls `onSubmit(values)` when valid
+ *   - calls `onInvalid(errors)` when invalid (if provided)
+ *   - optionally maps Axios 422 field errors into RHF errors
+ *
+ * ## Testing note
+ * In unit tests, prefer submitting via user interaction when possible:
+ * - `await user.click(button)` or `fireEvent.submit(form)`
+ * If you call `submitRef.current()` programmatically, ensure the test awaits resulting UI changes
+ * (e.g., `await waitFor(...)` / `await findBy...`) to avoid act warnings.
+ */
+export type MForm2BaseProps = {
+    formId?: string;
+    className?: string;
+    style?: React.CSSProperties;
+};
+export type MForm2Props<T extends FieldValues> = MFormProvider2Props<T> & MForm2BaseProps;
+/**
+ * MForm2:
+ * - Wraps children with MFormProvider2
+ * - Renders a <form> and wires onSubmit to provider's submit()
+ */
+export declare function MForm2<T extends FieldValues>(props: MForm2Props<T>): React.JSX.Element;

package/dist/components/Form/MForm/MFormProvider2.d.ts

@@ -0,0 +1,236 @@
+import { DefaultValues, FieldValues, Resolver, SubmitErrorHandler, SubmitHandler, UseFormProps, UseFormReturn } from 'react-hook-form';
+import { AnyObjectSchema } from 'yup';
+import * as React from 'react';
+/**
+ * # MFormProvider2 Documentation
+ *
+ * ## What this module is
+ * `MFormProvider2` is a **thin React Hook Form (RHF) wrapper** that:
+ * - Provides a `FormProvider` context for descendants (so `useFormContext()` works).
+ * - Standardizes submit behavior (including optional Axios 422 → field error mapping).
+ * - Supports two modes:
+ *   - **Controlled**: you create the RHF methods with `useForm()` elsewhere and pass `methods`.
+ *   - **Owned**: this provider calls `useForm()` internally using `defaultValues`/resolver.
+ * - Optionally exposes a programmatic submit function via:
+ *   - `submitRef` (imperative ref),
+ *   - and/or an internal context + `useMForm2()` hook.
+ *
+ * Importantly, this component does **not** render a `<form>` element. That is handled by `MForm2`
+ * (or any parent component that wants to place the `<form>` tag wherever it needs to).
+ *
+ * ## When to use MFormProvider2 vs MForm2
+ * - Use **MFormProvider2** when you need RHF context and submit helpers but want to control the `<form>` tag placement.
+ * - Use **MForm2** (a separate wrapper) when you want a ready-to-use `<form>` element around your children.
+ *
+ * ## Primary responsibilities
+ * 1) **RHF context**: wraps children with `<FormProvider {...methods}>`.
+ * 2) **Submit orchestration**:
+ *    - Calls `methods.handleSubmit(submitWrapped, onInvalid)`
+ *    - `submitWrapped` calls your `onSubmit(values)` and catches optional Axios 422 errors.
+ * 3) **Server validation errors** (optional):
+ *    - If `applyAxios422Errors` is enabled and the submit throws an axios-ish 422 error, it maps response field errors
+ *      to RHF’s `setError()` so the UI can display them like any other validation error.
+ * 4) **Programmatic submit**:
+ *    - Exposes `submit()` to render-prop children,
+ *    - optionally stores it into `submitRef.current`,
+ *    - optionally provides it via `useMForm2()` context.
+ *
+ * ## Concepts: Controlled vs Owned
+ *
+ * ### Controlled mode
+ * You provide the RHF methods object:
+ * ```ts
+ * const methods = useForm<MyValues>({ defaultValues });
+ * <MFormProvider2 methods={methods} onSubmit={...}>{...}</MFormProvider2>
+ * ```
+ *
+ * Use this when:
+ * - You need `methods` in the parent component (e.g., `useFieldArray()` at the dialog level),
+ * - You want to configure RHF outside of the wrapper.
+ *
+ * Note: in controlled mode, `validationSchema` is not accepted because the resolver must be configured
+ * when you create `methods` via `useForm({ resolver: ... })`.
+ *
+ * ### Owned mode
+ * You provide `defaultValues` (and optionally `validationSchema`, `resolver`, `useFormProps`, etc.):
+ * ```ts
+ * <MFormProvider2 defaultValues={...} validationSchema={...} onSubmit={...}>{...}</MFormProvider2>
+ * ```
+ *
+ * Owned mode is the recommended path when you want minimal call-site configuration.
+ *
+ * ## Error mapping (Axios 422 → RHF errors)
+ *
+ * Many APIs return validation errors in a 422 response like:
+ * ```json
+ * { "Name": "Name is required" }
+ * ```
+ *
+ * If `applyAxios422Errors` is true (default is true), `submitWrapped` catches that error and:
+ * - Lowercases the first character of the field name (`Name` → `name`) to match typical TS/RHF casing
+ * - Applies the message to RHF via `setError("name", { message: "..." })`
+ *
+ * ### Custom mapping
+ * If your backend response shape differs, provide `mapAxios422` to adapt it.
+ *
+ * ## Reinitialization (owned mode only)
+ * Owned mode supports `reinitializeKey`: when the key changes, the provider calls `methods.reset(defaultValues)`.
+ * This is intentionally more predictable than “reset whenever defaultValues changes”.
+ *
+ * A common pattern is:
+ * - `reinitializeKey = divisionId` or a dialog open counter
+ * - `defaultValues` comes from your loaded entity
+ *
+ * ## validateOnMount
+ * If `validateOnMount` is true (default is false), the provider calls `methods.trigger()` after mount. This runs validation immediately.
+ * (Note: this can cause async updates in tests; prefer `findBy...`/`waitFor` to await the UI.)
+ *
+ * ## Programmatic submit
+ *
+ * There are three ways to submit without a submit button:
+ *
+ * 1) Render-prop children receive `submit()`:
+ * ```tsx
+ * <MFormProvider2 ...>
+ *   {({ submit }) => <button onClick={() => void submit()}>Save</button>}
+ * </MFormProvider2>
+ * ```
+ *
+ * 2) Use `submitRef`:
+ * ```ts
+ * const submitRef = useRef<(() => Promise<void>) | null>(null);
+ * <MFormProvider2 submitRef={submitRef} ... />
+ * // later
+ * await submitRef.current?.();
+ * ```
+ *
+ * 3) Use `useMForm2()` anywhere under the provider:
+ * ```ts
+ * const { submit } = useMForm2<MyValues>();
+ * ```
+ *
+ * ## File-level map of what’s below
+ * - Server error helpers (`applyServerErrors`, `Axios422Mapper`)
+ * - Optional context + `useMForm2()`
+ * - Prop types for owned/controlled
+ * - `MFormProvider2WithMethods`: shared implementation given a `methods` object
+ * - `MFormProvider2ControlledInner`: controlled mode implementation
+ * - `MFormProvider2OwnedInner`: owned mode implementation (calls `useForm()`)
+ * - `MFormProvider2`: public selector (chooses controlled vs owned)
+ */
+/** ---------------- Server errors ---------------- */
+export type ServerErrorMap = Record<string, string>;
+/**
+ * Apply the server errors to RHF errors.
+ * Server errors are a map of fieldName -> error message.
+ *
+ * Notes:
+ * - `focusFirst` (default is true) controls whether RHF should focus the first errored field.
+ * - Field names are normalized (`Name` -> `name`) via `lowerCaseFieldName`.
+ */
+export declare function applyServerErrors<T extends FieldValues>(setError: UseFormReturn<T>['setError'], errors: ServerErrorMap, focusFirst?: boolean): void;
+/**
+ * Converts a thrown error (usually Axios) into either:
+ * - `{ ok: true, errors: ServerErrorMap }` if it is a 422 validation error, or
+ * - `{ ok: false }` if it is not.
+ *
+ * This is intentionally generic so applications can replace it with their own mapping logic.
+ */
+export type Axios422Mapper = (err: unknown) => {
+    ok: true;
+    errors: ServerErrorMap;
+} | {
+    ok: false;
+};
+/**
+ * Default mapping for axios-ish errors:
+ * - expects `err.response.status === 422`
+ * - expects `err.response.data` to be an object of `{ field: message }`
+ */
+export declare const defaultAxios422Mapper: Axios422Mapper;
+/** ---------------- Context (optional) ---------------- */
+/**
+ * Context is optional but convenient. It allows any descendant to access:
+ * - `submit()` (programmatic submit),
+ * - RHF `methods`,
+ * - and `applyServerErrors()` without needing prop drilling.
+ */
+type MForm2ContextValue<T extends FieldValues> = {
+    submit: () => Promise<void>;
+    methods: UseFormReturn<T>;
+    applyServerErrors: (errors: ServerErrorMap, focusFirst?: boolean) => void;
+};
+/**
+ * Hook to access MFormProvider2 utilities from descendants.
+ * Must be called under `<MFormProvider2>` (or `<MForm2>` if it wraps provider+form).
+ */
+export declare function useMForm2<T extends FieldValues>(): MForm2ContextValue<T>;
+/** ---------------- Props ---------------- */
+/**
+ * Render-prop signature for children:
+ * - `methods`: RHF methods object
+ * - `submit`: programmatic submit (runs handleSubmit with error mapping + onInvalid)
+ */
+export type MFormProvider2RenderArgs<T extends FieldValues> = {
+    methods: UseFormReturn<T>;
+    submit: () => Promise<void>;
+};
+/**
+ * Common props shared by owned and controlled usage.
+ *
+ * - `onSubmit`: called with validated values
+ * - `onInvalid`: called with RHF errors when invalid
+ * - `validateOnMount`: runs validation immediately on mount via `trigger()`
+ * - `applyAxios422Errors` + `mapAxios422`: server validation mapping support
+ * - `submitRef`: imperative handle to the `submit()` function
+ * - `children`: ReactNode or render-prop (receives methods+submit)
+ */
+type CommonProps<T extends FieldValues> = {
+    onSubmit: SubmitHandler<T> | ((values: T) => Promise<void>);
+    onInvalid?: SubmitErrorHandler<T>;
+    validateOnMount?: boolean;
+    applyAxios422Errors?: boolean;
+    mapAxios422?: Axios422Mapper;
+    submitRef?: React.RefObject<(() => Promise<void>) | null>;
+    children: React.ReactNode | ((args: MFormProvider2RenderArgs<T>) => React.ReactNode);
+};
+/**
+ * Controlled mode: consumer provides RHF `methods`.
+ */
+export type MFormProvider2ControlledProps<T extends FieldValues> = CommonProps<T> & {
+    methods: UseFormReturn<T>;
+};
+/**
+ * Owned mode: provider creates RHF `methods` using `useForm()`.
+ */
+export type MFormProvider2OwnedProps<T extends FieldValues> = CommonProps<T> & {
+    defaultValues: DefaultValues<T>;
+    /**
+     * Yup schema for validation (owned mode convenience).
+     * If provided and `resolver` is not provided, the provider will use `yupResolver(validationSchema)`.
+     */
+    validationSchema?: AnyObjectSchema;
+    /**
+     * Explicit resolver override.
+     * If provided, it takes precedence over `validationSchema`.
+     */
+    resolver?: Resolver<T>;
+    shouldFocusError?: boolean;
+    useFormProps?: Omit<UseFormProps<T>, 'defaultValues' | 'resolver' | 'shouldFocusError'>;
+    /** Reset only when this key changes (owned mode only). */
+    reinitializeKey?: string | number;
+    resetOptions?: Parameters<UseFormReturn<T>['reset']>[1];
+};
+export type MFormProvider2Props<T extends FieldValues> = MFormProvider2ControlledProps<T> | MFormProvider2OwnedProps<T>;
+/** ---------------- Public provider ---------------- */
+/**
+ * Public entry point:
+ * - Uses a discriminant check: `'methods' in props`
+ * - If present -> controlled mode
+ * - Otherwise -> owned mode
+ *
+ * Note: This is safe with React hooks because hooks are only called inside the
+ * owned-mode component, not conditionally within a single component body.
+ */
+export declare function MFormProvider2<T extends FieldValues>(props: MFormProvider2Props<T>): React.JSX.Element;
+export {};