@form-eng/mui 1.0.0

package/README.md

@@ -0,0 +1,138 @@
+# @form-eng/mui
+
+Material UI (MUI) field components for [`@form-eng/core`](https://www.npmjs.com/package/@form-eng/core). Provides 13 editable and 6 read-only field types that plug into the core form engine.
+
+## Install
+
+```bash
+npm install @form-eng/core @form-eng/mui @mui/material @emotion/react @emotion/styled
+```
+
+Peer dependencies: `react`, `react-dom`, `react-hook-form`, `@mui/material`, `@form-eng/core`
+
+## Quick Start
+
+```tsx
+import {
+  RulesEngineProvider,
+  InjectedFieldProvider,
+  UseInjectedFieldContext,
+  FormEngine,
+} from "@form-eng/core";
+import { createMuiFieldRegistry } from "@form-eng/mui";
+import { ThemeProvider, createTheme } from "@mui/material";
+import { useEffect } from "react";
+
+const theme = createTheme();
+
+function FieldRegistrar({ children }: { children: React.ReactNode }) {
+  const { setInjectedFields } = UseInjectedFieldContext();
+  useEffect(() => {
+    setInjectedFields(createMuiFieldRegistry());
+  }, []);
+  return <>{children}</>;
+}
+
+function App() {
+  return (
+    <ThemeProvider theme={theme}>
+      <RulesEngineProvider>
+        <InjectedFieldProvider>
+          <FieldRegistrar>
+            <FormEngine
+              configName="myForm"
+              programName="myApp"
+              fieldConfigs={{
+                name: { type: "Textbox", label: "Name", required: true },
+                status: {
+                  type: "Dropdown",
+                  label: "Status",
+                  options: [
+                    { value: "Active", label: "Active" },
+                    { value: "Inactive", label: "Inactive" },
+                  ],
+                },
+              }}
+              defaultValues={{ name: "", status: "Active" }}
+              saveData={async (data) => data}
+            />
+          </FieldRegistrar>
+        </InjectedFieldProvider>
+      </RulesEngineProvider>
+    </ThemeProvider>
+  );
+}
+```
+
+## Available Fields
+
+### Editable Fields
+
+| Component Key | Component | MUI Component | Description |
+|---------------|-----------|---------------|-------------|
+| `Textbox` | `HookTextbox` | `TextField` | Single-line text input |
+| `Number` | `HookNumber` | `TextField` (type=number) | Numeric input with validation |
+| `Toggle` | `HookToggle` | `Switch` + `FormControlLabel` | Boolean toggle switch |
+| `Dropdown` | `HookDropdown` | `Select` + `MenuItem` | Single-select dropdown |
+| `Multiselect` | `HookMultiSelect` | `Select` (multiple) + `Chip` | Multi-select dropdown |
+| `DateControl` | `HookDateControl` | `TextField` (type=date) | Date picker with clear button |
+| `Slider` | `HookSlider` | `Slider` | Numeric slider |
+| `SimpleDropdown` | `HookSimpleDropdown` | `Select` + `MenuItem` | Dropdown from string array in config |
+| `MultiSelectSearch` | `HookMultiSelectSearch` | `Autocomplete` (multiple) | Searchable multi-select |
+| `Textarea` | `HookPopOutEditor` | `TextField` (multiline) + `Dialog` | Multiline text with expand-to-modal |
+| `DocumentLinks` | `HookDocumentLinks` | `List` + `TextField` + `IconButton` | URL link CRUD |
+| `StatusDropdown` | `HookStatusDropdown` | `Select` with color dots | Dropdown with color status indicator |
+| `DynamicFragment` | `HookFragment` | Hidden input | Hidden field (form state only) |
+
+### Read-Only Fields
+
+| Component Key | Component | MUI Component | Description |
+|---------------|-----------|---------------|-------------|
+| `ReadOnly` | `HookReadOnly` | `Typography` | Plain text display |
+| `ReadOnlyArray` | `HookReadOnlyArray` | `Typography` | Array of strings |
+| `ReadOnlyDateTime` | `HookReadOnlyDateTime` | `Typography` | Formatted date/time |
+| `ReadOnlyCumulativeNumber` | `HookReadOnlyCumulativeNumber` | `Typography` | Computed sum of other fields |
+| `ReadOnlyRichText` | `HookReadOnlyRichText` | `dangerouslySetInnerHTML` | Rendered HTML |
+| `ReadOnlyWithButton` | `HookReadOnlyWithButton` | `Typography` + `Button` | Text with action button |
+
+## Registry Setup
+
+`createMuiFieldRegistry()` returns a `Dictionary<JSX.Element>` mapping all component keys to their MUI implementations. You can extend or override individual fields:
+
+```tsx
+import { createMuiFieldRegistry } from "@form-eng/mui";
+
+const fields = {
+  ...createMuiFieldRegistry(),
+  Textbox: <MyCustomTextbox />, // override built-in
+  RichEditor: <MyRichEditor />, // add new type
+};
+
+setInjectedFields(fields);
+```
+
+## Supporting Components
+
+The package also exports supporting components:
+
+- **`ReadOnlyText`** -- Read-only text display using MUI Typography
+- **`StatusMessage`** -- Error/warning/saving status messages
+- **`HookFormLoading`** -- Skeleton loading placeholder using MUI Skeleton
+
+## Works with Core v1.3.0
+
+When paired with `@form-eng/core` v1.3.0+, you automatically get:
+
+- **Error boundary** -- each field is individually wrapped in `FormErrorBoundary`, so one crashing field does not take down the form
+- **Save reliability** -- AbortController cancels in-flight saves, configurable timeout and retry with exponential backoff
+- **Accessibility** -- focus trap in modals, focus-to-first-error on validation failure, ARIA live regions for status announcements
+- **Draft persistence** -- `useDraftPersistence` hook auto-saves form state to localStorage; `useBeforeUnload` warns on page leave
+- **Theming render props** -- `FieldWrapper` accepts `renderLabel`, `renderError`, `renderStatus` for custom field chrome
+- **CSS custom properties** -- override `--fe-error-color`, `--fe-field-gap`, etc. via optional `styles.css`
+- **DevTools** -- `FormDevTools` component for debugging business rules, form values, and errors
+- **JSON Schema import** -- `jsonSchemaToFieldConfig()` converts JSON Schema to field configs
+- **Lazy field registry** -- `createLazyFieldRegistry()` for on-demand field component loading
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,141 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { IFieldProps, Dictionary } from '@form-eng/core';
+import React from 'react';
+import { FieldError } from 'react-hook-form';
+
+interface ITextboxProps {
+    ellipsifyTextCharacters?: number;
+    placeHolder?: string;
+    multiline?: boolean;
+}
+declare const Textbox: (props: IFieldProps<ITextboxProps>) => react_jsx_runtime.JSX.Element;
+
+declare const NumberField: (props: IFieldProps<{}>) => react_jsx_runtime.JSX.Element;
+
+declare const Toggle: (props: IFieldProps<{}>) => react_jsx_runtime.JSX.Element;
+
+interface IDropdownProps {
+    placeHolder?: string;
+    setDefaultKeyIfOnlyOneOption?: boolean;
+}
+declare const Dropdown: (props: IFieldProps<IDropdownProps>) => react_jsx_runtime.JSX.Element;
+
+declare const MultiSelect: (props: IFieldProps<{}>) => react_jsx_runtime.JSX.Element;
+
+declare const DateControl: (props: IFieldProps<{}>) => react_jsx_runtime.JSX.Element;
+
+interface ISliderProps {
+    max?: number;
+    min?: number;
+    step?: number;
+}
+declare const Slider: (props: IFieldProps<ISliderProps>) => react_jsx_runtime.JSX.Element;
+
+declare const DynamicFragment: (props: IFieldProps<{}>) => react_jsx_runtime.JSX.Element;
+
+interface ISimpleDropdownProps {
+    dropdownOptions?: string[];
+    placeHolder?: string;
+}
+declare const SimpleDropdown: (props: IFieldProps<ISimpleDropdownProps>) => react_jsx_runtime.JSX.Element;
+
+declare const MultiSelectSearch: (props: IFieldProps<{}>) => react_jsx_runtime.JSX.Element;
+
+interface IPopOutEditorProps {
+    autoAdjustHeight?: boolean;
+    numberOfRows?: number;
+    ellipsifyTextCharacters?: number;
+    additionalInfo?: string;
+    maxLimit?: number;
+    saveCallback?: () => void;
+    renderExtraModalFooter?: () => React.ReactNode;
+}
+declare const PopOutEditor: (props: IFieldProps<IPopOutEditorProps>) => react_jsx_runtime.JSX.Element;
+
+interface IDocumentLink {
+    title: string;
+    url: string;
+}
+declare const DocumentLinks: (props: IFieldProps<{}>) => react_jsx_runtime.JSX.Element;
+
+interface IStatusDropdownProps {
+    placeHolder?: string;
+    statusColors?: Dictionary<string>;
+}
+declare const StatusDropdown: (props: IFieldProps<IStatusDropdownProps>) => react_jsx_runtime.JSX.Element;
+
+interface IReadOnlyFieldProps {
+    readonly value?: string;
+    readonly fieldName?: string;
+    readonly labelClassName?: string;
+    readonly valueClassName?: string;
+    readonly showControlOnSide?: boolean;
+    readonly containerClassName?: string;
+    readonly ellipsifyTextCharacters?: number;
+}
+declare const ReadOnlyText: React.FunctionComponent<IReadOnlyFieldProps>;
+
+interface IReadOnlyProps extends IReadOnlyFieldProps {
+}
+declare const ReadOnly: (props: IFieldProps<IReadOnlyProps>) => react_jsx_runtime.JSX.Element;
+
+declare const ReadOnlyArray: (props: IFieldProps<IReadOnlyFieldProps>) => react_jsx_runtime.JSX.Element;
+
+interface IReadOnlyDateTimeProps {
+    isListView?: boolean;
+    hidetimeStamp?: boolean;
+}
+declare const ReadOnlyDateTime: (props: IFieldProps<IReadOnlyDateTimeProps>) => react_jsx_runtime.JSX.Element;
+
+interface IReadOnlyCumulativeNumberProps extends IReadOnlyFieldProps {
+    dependencyFields?: string[];
+}
+declare const ReadOnlyCumulativeNumber: (props: IFieldProps<IReadOnlyCumulativeNumberProps>) => react_jsx_runtime.JSX.Element;
+
+declare const ReadOnlyRichText: (props: IFieldProps<{}>) => react_jsx_runtime.JSX.Element;
+
+interface IReadOnlyWithButtonProps extends IReadOnlyFieldProps {
+    containerClassName?: string;
+    buttonText?: string;
+    onButtonClick?: () => void;
+}
+declare const ReadOnlyWithButton: (props: IFieldProps<IReadOnlyWithButtonProps>) => react_jsx_runtime.JSX.Element;
+
+interface IStatusMessageProps {
+    id?: string;
+    readonly error?: FieldError;
+    readonly errorCount?: number;
+    readonly savePending?: boolean;
+    readonly saving?: boolean;
+}
+declare const StatusMessage: React.FunctionComponent<IStatusMessageProps>;
+
+interface IFormLoadingProps {
+    loadingShimmerCount?: number;
+    loadingFieldShimmerHeight?: number;
+    inPanel?: boolean;
+    hideTitleShimmer?: boolean;
+}
+declare const FormLoading: (props: IFormLoadingProps) => react_jsx_runtime.JSX.Element;
+
+/** Creates the default Material UI field registry for use with InjectedFieldProvider */
+declare function createMuiFieldRegistry(): Dictionary<React.JSX.Element>;
+
+declare const FieldClassName: (className: string, error?: FieldError) => string;
+declare const GetFieldDataTestId: (fieldName: string, programName?: string, entityType?: string, entityId?: string) => string;
+declare function formatDateTime(dateStr: string, options?: {
+    hideTimestamp?: boolean;
+}): string;
+declare const DocumentLinksStrings: {
+    link: string;
+    addLink: string;
+    addAnotherLink: string;
+    deleteLink: string;
+    confirmDeleteLink: string;
+    delete: string;
+    cancel: string;
+    saveChanges: string;
+    save: string;
+};
+
+export { DateControl, DocumentLinks, DocumentLinksStrings, Dropdown, DynamicFragment, FieldClassName, FormLoading, GetFieldDataTestId, type IDocumentLink, type IReadOnlyFieldProps, MultiSelect, MultiSelectSearch, NumberField as Number, PopOutEditor, ReadOnly, ReadOnlyArray, ReadOnlyCumulativeNumber, ReadOnlyDateTime, ReadOnlyRichText, ReadOnlyText, ReadOnlyWithButton, SimpleDropdown, Slider, StatusDropdown, StatusMessage, Textbox, Toggle, createMuiFieldRegistry, formatDateTime };

package/dist/index.d.ts

@@ -0,0 +1,141 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { IFieldProps, Dictionary } from '@form-eng/core';
+import React from 'react';
+import { FieldError } from 'react-hook-form';
+
+interface ITextboxProps {
+    ellipsifyTextCharacters?: number;
+    placeHolder?: string;
+    multiline?: boolean;
+}
+declare const Textbox: (props: IFieldProps<ITextboxProps>) => react_jsx_runtime.JSX.Element;
+
+declare const NumberField: (props: IFieldProps<{}>) => react_jsx_runtime.JSX.Element;
+
+declare const Toggle: (props: IFieldProps<{}>) => react_jsx_runtime.JSX.Element;
+
+interface IDropdownProps {
+    placeHolder?: string;
+    setDefaultKeyIfOnlyOneOption?: boolean;
+}
+declare const Dropdown: (props: IFieldProps<IDropdownProps>) => react_jsx_runtime.JSX.Element;
+
+declare const MultiSelect: (props: IFieldProps<{}>) => react_jsx_runtime.JSX.Element;
+
+declare const DateControl: (props: IFieldProps<{}>) => react_jsx_runtime.JSX.Element;
+
+interface ISliderProps {
+    max?: number;
+    min?: number;
+    step?: number;
+}
+declare const Slider: (props: IFieldProps<ISliderProps>) => react_jsx_runtime.JSX.Element;
+
+declare const DynamicFragment: (props: IFieldProps<{}>) => react_jsx_runtime.JSX.Element;
+
+interface ISimpleDropdownProps {
+    dropdownOptions?: string[];
+    placeHolder?: string;
+}
+declare const SimpleDropdown: (props: IFieldProps<ISimpleDropdownProps>) => react_jsx_runtime.JSX.Element;
+
+declare const MultiSelectSearch: (props: IFieldProps<{}>) => react_jsx_runtime.JSX.Element;
+
+interface IPopOutEditorProps {
+    autoAdjustHeight?: boolean;
+    numberOfRows?: number;
+    ellipsifyTextCharacters?: number;
+    additionalInfo?: string;
+    maxLimit?: number;
+    saveCallback?: () => void;
+    renderExtraModalFooter?: () => React.ReactNode;
+}
+declare const PopOutEditor: (props: IFieldProps<IPopOutEditorProps>) => react_jsx_runtime.JSX.Element;
+
+interface IDocumentLink {
+    title: string;
+    url: string;
+}
+declare const DocumentLinks: (props: IFieldProps<{}>) => react_jsx_runtime.JSX.Element;
+
+interface IStatusDropdownProps {
+    placeHolder?: string;
+    statusColors?: Dictionary<string>;
+}
+declare const StatusDropdown: (props: IFieldProps<IStatusDropdownProps>) => react_jsx_runtime.JSX.Element;
+
+interface IReadOnlyFieldProps {
+    readonly value?: string;
+    readonly fieldName?: string;
+    readonly labelClassName?: string;
+    readonly valueClassName?: string;
+    readonly showControlOnSide?: boolean;
+    readonly containerClassName?: string;
+    readonly ellipsifyTextCharacters?: number;
+}
+declare const ReadOnlyText: React.FunctionComponent<IReadOnlyFieldProps>;
+
+interface IReadOnlyProps extends IReadOnlyFieldProps {
+}
+declare const ReadOnly: (props: IFieldProps<IReadOnlyProps>) => react_jsx_runtime.JSX.Element;
+
+declare const ReadOnlyArray: (props: IFieldProps<IReadOnlyFieldProps>) => react_jsx_runtime.JSX.Element;
+
+interface IReadOnlyDateTimeProps {
+    isListView?: boolean;
+    hidetimeStamp?: boolean;
+}
+declare const ReadOnlyDateTime: (props: IFieldProps<IReadOnlyDateTimeProps>) => react_jsx_runtime.JSX.Element;
+
+interface IReadOnlyCumulativeNumberProps extends IReadOnlyFieldProps {
+    dependencyFields?: string[];
+}
+declare const ReadOnlyCumulativeNumber: (props: IFieldProps<IReadOnlyCumulativeNumberProps>) => react_jsx_runtime.JSX.Element;
+
+declare const ReadOnlyRichText: (props: IFieldProps<{}>) => react_jsx_runtime.JSX.Element;
+
+interface IReadOnlyWithButtonProps extends IReadOnlyFieldProps {
+    containerClassName?: string;
+    buttonText?: string;
+    onButtonClick?: () => void;
+}
+declare const ReadOnlyWithButton: (props: IFieldProps<IReadOnlyWithButtonProps>) => react_jsx_runtime.JSX.Element;
+
+interface IStatusMessageProps {
+    id?: string;
+    readonly error?: FieldError;
+    readonly errorCount?: number;
+    readonly savePending?: boolean;
+    readonly saving?: boolean;
+}
+declare const StatusMessage: React.FunctionComponent<IStatusMessageProps>;
+
+interface IFormLoadingProps {
+    loadingShimmerCount?: number;
+    loadingFieldShimmerHeight?: number;
+    inPanel?: boolean;
+    hideTitleShimmer?: boolean;
+}
+declare const FormLoading: (props: IFormLoadingProps) => react_jsx_runtime.JSX.Element;
+
+/** Creates the default Material UI field registry for use with InjectedFieldProvider */
+declare function createMuiFieldRegistry(): Dictionary<React.JSX.Element>;
+
+declare const FieldClassName: (className: string, error?: FieldError) => string;
+declare const GetFieldDataTestId: (fieldName: string, programName?: string, entityType?: string, entityId?: string) => string;
+declare function formatDateTime(dateStr: string, options?: {
+    hideTimestamp?: boolean;
+}): string;
+declare const DocumentLinksStrings: {
+    link: string;
+    addLink: string;
+    addAnotherLink: string;
+    deleteLink: string;
+    confirmDeleteLink: string;
+    delete: string;
+    cancel: string;
+    saveChanges: string;
+    save: string;
+};
+
+export { DateControl, DocumentLinks, DocumentLinksStrings, Dropdown, DynamicFragment, FieldClassName, FormLoading, GetFieldDataTestId, type IDocumentLink, type IReadOnlyFieldProps, MultiSelect, MultiSelectSearch, NumberField as Number, PopOutEditor, ReadOnly, ReadOnlyArray, ReadOnlyCumulativeNumber, ReadOnlyDateTime, ReadOnlyRichText, ReadOnlyText, ReadOnlyWithButton, SimpleDropdown, Slider, StatusDropdown, StatusMessage, Textbox, Toggle, createMuiFieldRegistry, formatDateTime };