@form-eng/fluent 1.0.0

package/README.md

@@ -0,0 +1,136 @@
+# @form-eng/fluent
+
+Fluent UI v9 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/fluent
+```
+
+Peer dependencies: `react`, `react-dom`, `react-hook-form`, `@fluentui/react-components`, `@form-eng/core`
+
+## Quick Start
+
+```tsx
+import {
+  RulesEngineProvider,
+  InjectedFieldProvider,
+  UseInjectedFieldContext,
+  FormEngine,
+} from "@form-eng/core";
+import { createFluentFieldRegistry } from "@form-eng/fluent";
+import { FluentProvider, webLightTheme } from "@fluentui/react-components";
+import { useEffect } from "react";
+
+function FieldRegistrar({ children }: { children: React.ReactNode }) {
+  const { setInjectedFields } = UseInjectedFieldContext();
+  useEffect(() => {
+    setInjectedFields(createFluentFieldRegistry());
+  }, []);
+  return <>{children}</>;
+}
+
+function App() {
+  return (
+    <FluentProvider theme={webLightTheme}>
+      <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>
+    </FluentProvider>
+  );
+}
+```
+
+## Available Fields
+
+### Editable Fields
+
+| Component Key | Component | Description |
+|---------------|-----------|-------------|
+| `Textbox` | `HookTextbox` | Single-line text input |
+| `Number` | `HookNumber` | Numeric input with validation |
+| `Toggle` | `HookToggle` | Boolean toggle switch |
+| `Dropdown` | `HookDropdown` | Single-select dropdown |
+| `Multiselect` | `HookMultiSelect` | Multi-select dropdown |
+| `DateControl` | `HookDateControl` | Date picker with clear button |
+| `Slider` | `HookSlider` | Numeric slider |
+| `SimpleDropdown` | `HookSimpleDropdown` | Dropdown from string array in config |
+| `MultiSelectSearch` | `HookMultiSelectSearch` | Searchable multi-select (ComboBox) |
+| `Textarea` | `HookPopOutEditor` | Multiline text with expand-to-modal |
+| `DocumentLinks` | `HookDocumentLinks` | URL link CRUD |
+| `StatusDropdown` | `HookStatusDropdown` | Dropdown with color status indicator |
+| `DynamicFragment` | `HookFragment` | Hidden field (form state only) |
+
+### Read-Only Fields
+
+| Component Key | Component | Description |
+|---------------|-----------|-------------|
+| `ReadOnly` | `HookReadOnly` | Plain text display |
+| `ReadOnlyArray` | `HookReadOnlyArray` | Array of strings |
+| `ReadOnlyDateTime` | `HookReadOnlyDateTime` | Formatted date/time |
+| `ReadOnlyCumulativeNumber` | `HookReadOnlyCumulativeNumber` | Computed sum of other fields |
+| `ReadOnlyRichText` | `HookReadOnlyRichText` | Rendered HTML |
+| `ReadOnlyWithButton` | `HookReadOnlyWithButton` | Text with action button |
+
+## Registry Setup
+
+`createFluentFieldRegistry()` returns a `Dictionary<JSX.Element>` mapping all component keys to their Fluent UI implementations. You can extend or override individual fields:
+
+```tsx
+import { createFluentFieldRegistry } from "@form-eng/fluent";
+
+const fields = {
+  ...createFluentFieldRegistry(),
+  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
+- **`StatusMessage`** -- Error/warning/saving status messages
+- **`HookFormLoading`** -- Shimmer loading placeholder
+
+## 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,190 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { IFieldProps, Dictionary, IOption } from '@form-eng/core';
+import React from 'react';
+import { FieldError } from 'react-hook-form';
+import { OptionOnSelectData } from '@fluentui/react-components';
+
+interface IHookTextboxProps {
+    ellipsifyTextCharacters?: number;
+    placeHolder?: string;
+    multiline?: boolean;
+}
+declare const Textbox: (props: IFieldProps<IHookTextboxProps>) => 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 IHookDropdownProps {
+    placeHolder?: string;
+    setDefaultKeyIfOnlyOneOption?: boolean;
+}
+declare const DropdownField: (props: IFieldProps<IHookDropdownProps>) => 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 IHookSliderProps {
+    max?: number;
+    min?: number;
+    step?: number;
+}
+declare const SliderField: (props: IFieldProps<IHookSliderProps>) => react_jsx_runtime.JSX.Element;
+
+declare const Fragment: (props: IFieldProps<{}>) => react_jsx_runtime.JSX.Element;
+
+interface IHookSimpleDropdownProps {
+    dropdownOptions?: string[];
+    placeHolder?: string;
+}
+declare const SimpleDropdown: (props: IFieldProps<IHookSimpleDropdownProps>) => react_jsx_runtime.JSX.Element;
+
+declare const MultiSelectSearch: (props: IFieldProps<{}>) => react_jsx_runtime.JSX.Element;
+
+interface IHookPopOutEditorProps {
+    autoAdjustHeight?: boolean;
+    numberOfRows?: number;
+    ellipsifyTextCharacters?: number;
+    additionalInfo?: string;
+    maxLimit?: number;
+    saveCallback?: () => void;
+    renderExtraModalFooter?: () => React.ReactNode;
+}
+declare const PopOutEditor: (props: IFieldProps<IHookPopOutEditorProps>) => react_jsx_runtime.JSX.Element;
+
+declare const DocumentLinksField: (props: IFieldProps<{}>) => react_jsx_runtime.JSX.Element;
+
+interface IHookStatusDropdownProps {
+    placeHolder?: string;
+    statusColors?: Dictionary<string>;
+}
+declare const StatusDropdownField: (props: IFieldProps<IHookStatusDropdownProps>) => 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 IHookReadOnlyProps extends IReadOnlyFieldProps {
+}
+declare const ReadOnly: (props: IFieldProps<IHookReadOnlyProps>) => react_jsx_runtime.JSX.Element;
+
+declare const ReadOnlyArray: (props: IFieldProps<IReadOnlyFieldProps>) => react_jsx_runtime.JSX.Element;
+
+interface IHookReadOnlyDateTimeProps {
+    isListView?: boolean;
+    hidetimeStamp?: boolean;
+}
+declare const ReadOnlyDateTime: (props: IFieldProps<IHookReadOnlyDateTimeProps>) => react_jsx_runtime.JSX.Element;
+
+interface IHookReadOnlyCumulativeNumberProps extends IReadOnlyFieldProps {
+    dependencyFields?: string[];
+}
+declare const ReadOnlyCumulativeNumber: (props: IFieldProps<IHookReadOnlyCumulativeNumberProps>) => 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;
+
+interface IStatusColorProps {
+    statusColors: Dictionary<string>;
+    status: string;
+}
+declare const StatusColor: (props: IStatusColorProps) => react_jsx_runtime.JSX.Element;
+
+interface IStatusDropdownProps {
+    className: string;
+    entityId?: string;
+    entityType?: string;
+    programName?: string;
+    fieldName: string;
+    status: string;
+    dropdownOptions: IOption[];
+    meta?: Record<string, unknown>;
+    onOptionSelect: (event: unknown, data: OptionOnSelectData) => void;
+}
+declare const StatusDropdown: (props: IStatusDropdownProps) => react_jsx_runtime.JSX.Element;
+
+interface IDocumentLink {
+    title: string;
+    url: string;
+}
+interface IDocumentLinksProps {
+    fieldName: string;
+    programName?: string;
+    entityType?: string;
+    entityId?: string;
+    className?: string;
+    readOnly?: boolean;
+    links: IDocumentLink[];
+    onUpdateLinks?: (newLink: IDocumentLink, addNewLink?: boolean, index?: number) => void;
+    onDeleteLink?: (index: number) => void;
+}
+declare const DocumentLinks: (props: IDocumentLinksProps) => react_jsx_runtime.JSX.Element;
+
+interface IDocumentLinkProps {
+    fieldName: string;
+    programName?: string;
+    entityType?: string;
+    entityId?: string;
+    readOnly?: boolean;
+    index?: number;
+    title?: string;
+    url?: string;
+    addNewLink?: boolean;
+    saveLinks: (newLink: IDocumentLink, addNewLink?: boolean, index?: number) => void;
+    onCancelAddLink?: () => void;
+    onConfirmDeleteLink?: (index: number) => void;
+}
+declare const DocumentLink: (props: IDocumentLinkProps) => react_jsx_runtime.JSX.Element;
+
+/** Creates the default Fluent UI v9 field registry for use with InjectedFieldProvider */
+declare function createFluentFieldRegistry(): 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, DocumentLink, DocumentLinks, DocumentLinksField, DocumentLinksStrings, DropdownField, FieldClassName, FormLoading, Fragment, GetFieldDataTestId, type IDocumentLink, type IReadOnlyFieldProps, MultiSelect, MultiSelectSearch, NumberField, PopOutEditor, ReadOnly, ReadOnlyArray, ReadOnlyCumulativeNumber, ReadOnlyDateTime, ReadOnlyRichText, ReadOnlyText, ReadOnlyWithButton, SimpleDropdown, SliderField, StatusColor, StatusDropdown, StatusDropdownField, StatusMessage, Textbox, Toggle, createFluentFieldRegistry, formatDateTime };

package/dist/index.d.ts

@@ -0,0 +1,190 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { IFieldProps, Dictionary, IOption } from '@form-eng/core';
+import React from 'react';
+import { FieldError } from 'react-hook-form';
+import { OptionOnSelectData } from '@fluentui/react-components';
+
+interface IHookTextboxProps {
+    ellipsifyTextCharacters?: number;
+    placeHolder?: string;
+    multiline?: boolean;
+}
+declare const Textbox: (props: IFieldProps<IHookTextboxProps>) => 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 IHookDropdownProps {
+    placeHolder?: string;
+    setDefaultKeyIfOnlyOneOption?: boolean;
+}
+declare const DropdownField: (props: IFieldProps<IHookDropdownProps>) => 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 IHookSliderProps {
+    max?: number;
+    min?: number;
+    step?: number;
+}
+declare const SliderField: (props: IFieldProps<IHookSliderProps>) => react_jsx_runtime.JSX.Element;
+
+declare const Fragment: (props: IFieldProps<{}>) => react_jsx_runtime.JSX.Element;
+
+interface IHookSimpleDropdownProps {
+    dropdownOptions?: string[];
+    placeHolder?: string;
+}
+declare const SimpleDropdown: (props: IFieldProps<IHookSimpleDropdownProps>) => react_jsx_runtime.JSX.Element;
+
+declare const MultiSelectSearch: (props: IFieldProps<{}>) => react_jsx_runtime.JSX.Element;
+
+interface IHookPopOutEditorProps {
+    autoAdjustHeight?: boolean;
+    numberOfRows?: number;
+    ellipsifyTextCharacters?: number;
+    additionalInfo?: string;
+    maxLimit?: number;
+    saveCallback?: () => void;
+    renderExtraModalFooter?: () => React.ReactNode;
+}
+declare const PopOutEditor: (props: IFieldProps<IHookPopOutEditorProps>) => react_jsx_runtime.JSX.Element;
+
+declare const DocumentLinksField: (props: IFieldProps<{}>) => react_jsx_runtime.JSX.Element;
+
+interface IHookStatusDropdownProps {
+    placeHolder?: string;
+    statusColors?: Dictionary<string>;
+}
+declare const StatusDropdownField: (props: IFieldProps<IHookStatusDropdownProps>) => 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 IHookReadOnlyProps extends IReadOnlyFieldProps {
+}
+declare const ReadOnly: (props: IFieldProps<IHookReadOnlyProps>) => react_jsx_runtime.JSX.Element;
+
+declare const ReadOnlyArray: (props: IFieldProps<IReadOnlyFieldProps>) => react_jsx_runtime.JSX.Element;
+
+interface IHookReadOnlyDateTimeProps {
+    isListView?: boolean;
+    hidetimeStamp?: boolean;
+}
+declare const ReadOnlyDateTime: (props: IFieldProps<IHookReadOnlyDateTimeProps>) => react_jsx_runtime.JSX.Element;
+
+interface IHookReadOnlyCumulativeNumberProps extends IReadOnlyFieldProps {
+    dependencyFields?: string[];
+}
+declare const ReadOnlyCumulativeNumber: (props: IFieldProps<IHookReadOnlyCumulativeNumberProps>) => 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;
+
+interface IStatusColorProps {
+    statusColors: Dictionary<string>;
+    status: string;
+}
+declare const StatusColor: (props: IStatusColorProps) => react_jsx_runtime.JSX.Element;
+
+interface IStatusDropdownProps {
+    className: string;
+    entityId?: string;
+    entityType?: string;
+    programName?: string;
+    fieldName: string;
+    status: string;
+    dropdownOptions: IOption[];
+    meta?: Record<string, unknown>;
+    onOptionSelect: (event: unknown, data: OptionOnSelectData) => void;
+}
+declare const StatusDropdown: (props: IStatusDropdownProps) => react_jsx_runtime.JSX.Element;
+
+interface IDocumentLink {
+    title: string;
+    url: string;
+}
+interface IDocumentLinksProps {
+    fieldName: string;
+    programName?: string;
+    entityType?: string;
+    entityId?: string;
+    className?: string;
+    readOnly?: boolean;
+    links: IDocumentLink[];
+    onUpdateLinks?: (newLink: IDocumentLink, addNewLink?: boolean, index?: number) => void;
+    onDeleteLink?: (index: number) => void;
+}
+declare const DocumentLinks: (props: IDocumentLinksProps) => react_jsx_runtime.JSX.Element;
+
+interface IDocumentLinkProps {
+    fieldName: string;
+    programName?: string;
+    entityType?: string;
+    entityId?: string;
+    readOnly?: boolean;
+    index?: number;
+    title?: string;
+    url?: string;
+    addNewLink?: boolean;
+    saveLinks: (newLink: IDocumentLink, addNewLink?: boolean, index?: number) => void;
+    onCancelAddLink?: () => void;
+    onConfirmDeleteLink?: (index: number) => void;
+}
+declare const DocumentLink: (props: IDocumentLinkProps) => react_jsx_runtime.JSX.Element;
+
+/** Creates the default Fluent UI v9 field registry for use with InjectedFieldProvider */
+declare function createFluentFieldRegistry(): 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, DocumentLink, DocumentLinks, DocumentLinksField, DocumentLinksStrings, DropdownField, FieldClassName, FormLoading, Fragment, GetFieldDataTestId, type IDocumentLink, type IReadOnlyFieldProps, MultiSelect, MultiSelectSearch, NumberField, PopOutEditor, ReadOnly, ReadOnlyArray, ReadOnlyCumulativeNumber, ReadOnlyDateTime, ReadOnlyRichText, ReadOnlyText, ReadOnlyWithButton, SimpleDropdown, SliderField, StatusColor, StatusDropdown, StatusDropdownField, StatusMessage, Textbox, Toggle, createFluentFieldRegistry, formatDateTime };