@availity/mui-controlled-form 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,26 @@
+# Changelog
+
+This file was generated using [@jscutlery/semver](https://github.com/jscutlery/semver).
+
+## 0.1.0 (2025-01-23)
+
+### Dependency Updates
+
+* `mui-button` updated to version `0.1.0`
+* `mui-layout` updated to version `0.1.0`
+* `mui-menu` updated to version `0.1.0`
+* `mui-paper` updated to version `0.1.0`
+* `mui-typography` updated to version `0.1.0`
+* `mui-autocomplete` updated to version `0.1.0`
+* `mui-checkbox` updated to version `0.1.0`
+* `mui-datepicker` updated to version `0.1.0`
+* `mui-form-utils` updated to version `0.1.0`
+* `mui-textfield` updated to version `0.1.0`
+* `theme-provider` updated to version `0.1.0`
+
+### Features
+
+* **mui-controlled-form:** add ControlledDatepicker ([db89204](https://github.com/Availity/element/commit/db89204ac8c92bebcf1dae3f65be84718d87474a))
+* **mui-controlled-form:** add yup resolver support ([16c16b9](https://github.com/Availity/element/commit/16c16b98743f8bae504a02709936cc252f4a82e1))
+* **mui-controlled-form:** allow user to pass any validation resolver ([fa7daf3](https://github.com/Availity/element/commit/fa7daf3db9da8d02065cda3b89421064ea98f3bc))
+* **mui-controlled-form:** initial commit ([827e8af](https://github.com/Availity/element/commit/827e8af9b0b29a912c08e2632f33cd6ee6708416))

package/README.md

@@ -0,0 +1,65 @@
+# @availity/mui-controlled-form
+
+> Availity MUI Form components integrated with react-hook-form to be used with @availity/element design system.
+
+[![Version](https://img.shields.io/npm/v/@availity/mui-controlled-form.svg?style=for-the-badge)](https://www.npmjs.com/package/@availity/mui-controlled-form)
+[![NPM Downloads](https://img.shields.io/npm/dt/@availity/mui-controlled-form.svg?style=for-the-badge)](https://www.npmjs.com/package/@availity/mui-controlled-form)
+[![Dependency Status](https://img.shields.io/librariesio/release/npm/@availity/mui-controlled-form?style=for-the-badge)](https://github.com/Availity/element/blob/main/packages/mui-controlled-form/package.json)
+
+## Documentation
+
+This package extends the Element's Form components with [react-hook-form](https://react-hook-form.com/). The goal of this package is to decrease the amount of setup involved with building a form using Element components and react-hook-form. If you would like to use another form library, the raw Element form components are also available.
+
+Live demo and documentation in our [Storybook](https://availity.github.io/element/?path=/docs/form-components-controlled-form-introduction--docs)
+
+Availity standards for design and usage can be found in the [Availity Design Guide](https://zeroheight.com/2e36e50c7)
+
+## Installation
+
+### Import Through @availity/element (Recommended)
+
+#### NPM
+
+```bash
+npm install @availity/element
+```
+
+#### Yarn
+
+```bash
+yarn add @availity/element
+```
+
+### Direct Import
+
+#### NPM
+
+_This package has a few peer dependencies. Add `@mui/material` & `@emotion/react` to your project if not already installed._
+
+```bash
+npm install @availity/mui-controlled-form
+```
+
+#### Yarn
+
+```bash
+yarn add @availity/mui-controlled-form
+```
+
+### Usage
+
+#### Import through @availity/element
+
+```tsx
+import { ControlledForm } from '@availity/element';
+```
+
+#### Direct import
+
+```tsx
+import { ControlledForm } from '@availity/mui-controlled-form';
+```
+
+### Form Validation
+
+Form validation can be on a component-by-component basis, or by passing a valid schema and schema resolver. For more information on react-hook-form's schema resolvers see: https://github.com/react-hook-form/resolvers#quickstart

package/dist/index.d.mts

@@ -0,0 +1,20 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { FormHTMLAttributes } from 'react';
+import { SubmitHandler, Resolver } from 'react-hook-form';
+
+type ControlledFormProps = {
+    /** This function will receive the form data if form validation is successful. */
+    onSubmit: SubmitHandler<any>;
+    /** Reactive values to update the form values. */
+    values: Record<string, any>;
+    /** The schema used by the validationResolver. */
+    schema?: unknown;
+    /** Integrates with your preferred schema validation library.
+     * More information on react-hook-form's resolvers can be
+     * found here: https://github.com/react-hook-form/resolvers#quickstart
+     */
+    validationResolver?: (schema: unknown) => Resolver;
+} & FormHTMLAttributes<HTMLFormElement>;
+declare const ControlledForm: ({ onSubmit, values, schema, validationResolver, ...rest }: ControlledFormProps) => react_jsx_runtime.JSX.Element;
+
+export { ControlledForm, type ControlledFormProps };

package/dist/index.d.ts

@@ -0,0 +1,20 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { FormHTMLAttributes } from 'react';
+import { SubmitHandler, Resolver } from 'react-hook-form';
+
+type ControlledFormProps = {
+    /** This function will receive the form data if form validation is successful. */
+    onSubmit: SubmitHandler<any>;
+    /** Reactive values to update the form values. */
+    values: Record<string, any>;
+    /** The schema used by the validationResolver. */
+    schema?: unknown;
+    /** Integrates with your preferred schema validation library.
+     * More information on react-hook-form's resolvers can be
+     * found here: https://github.com/react-hook-form/resolvers#quickstart
+     */
+    validationResolver?: (schema: unknown) => Resolver;
+} & FormHTMLAttributes<HTMLFormElement>;
+declare const ControlledForm: ({ onSubmit, values, schema, validationResolver, ...rest }: ControlledFormProps) => react_jsx_runtime.JSX.Element;
+
+export { ControlledForm, type ControlledFormProps };

package/dist/index.js

@@ -0,0 +1,71 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __defProps = Object.defineProperties;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropDescs = Object.getOwnPropertyDescriptors;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getOwnPropSymbols = Object.getOwnPropertySymbols;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __propIsEnum = Object.prototype.propertyIsEnumerable;
+var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __spreadValues = (a, b) => {
+  for (var prop in b || (b = {}))
+    if (__hasOwnProp.call(b, prop))
+      __defNormalProp(a, prop, b[prop]);
+  if (__getOwnPropSymbols)
+    for (var prop of __getOwnPropSymbols(b)) {
+      if (__propIsEnum.call(b, prop))
+        __defNormalProp(a, prop, b[prop]);
+    }
+  return a;
+};
+var __spreadProps = (a, b) => __defProps(a, __getOwnPropDescs(b));
+var __objRest = (source, exclude) => {
+  var target = {};
+  for (var prop in source)
+    if (__hasOwnProp.call(source, prop) && exclude.indexOf(prop) < 0)
+      target[prop] = source[prop];
+  if (source != null && __getOwnPropSymbols)
+    for (var prop of __getOwnPropSymbols(source)) {
+      if (exclude.indexOf(prop) < 0 && __propIsEnum.call(source, prop))
+        target[prop] = source[prop];
+    }
+  return target;
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var src_exports = {};
+__export(src_exports, {
+  ControlledForm: () => ControlledForm
+});
+module.exports = __toCommonJS(src_exports);
+
+// src/lib/ControlledForm.tsx
+var import_react_hook_form = require("react-hook-form");
+var import_jsx_runtime = require("react/jsx-runtime");
+var ControlledForm = (_a) => {
+  var _b = _a, { onSubmit, values, schema, validationResolver } = _b, rest = __objRest(_b, ["onSubmit", "values", "schema", "validationResolver"]);
+  const useFormOptions = { values };
+  if (schema && validationResolver) {
+    useFormOptions.resolver = validationResolver(schema);
+  }
+  const methods = (0, import_react_hook_form.useForm)(useFormOptions);
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(import_react_hook_form.FormProvider, __spreadProps(__spreadValues({}, methods), { children: /* @__PURE__ */ (0, import_jsx_runtime.jsx)("form", __spreadValues({ onSubmit: methods.handleSubmit(onSubmit) }, rest)) }));
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ControlledForm
+});

package/dist/index.mjs

@@ -0,0 +1,47 @@
+var __defProp = Object.defineProperty;
+var __defProps = Object.defineProperties;
+var __getOwnPropDescs = Object.getOwnPropertyDescriptors;
+var __getOwnPropSymbols = Object.getOwnPropertySymbols;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __propIsEnum = Object.prototype.propertyIsEnumerable;
+var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __spreadValues = (a, b) => {
+  for (var prop in b || (b = {}))
+    if (__hasOwnProp.call(b, prop))
+      __defNormalProp(a, prop, b[prop]);
+  if (__getOwnPropSymbols)
+    for (var prop of __getOwnPropSymbols(b)) {
+      if (__propIsEnum.call(b, prop))
+        __defNormalProp(a, prop, b[prop]);
+    }
+  return a;
+};
+var __spreadProps = (a, b) => __defProps(a, __getOwnPropDescs(b));
+var __objRest = (source, exclude) => {
+  var target = {};
+  for (var prop in source)
+    if (__hasOwnProp.call(source, prop) && exclude.indexOf(prop) < 0)
+      target[prop] = source[prop];
+  if (source != null && __getOwnPropSymbols)
+    for (var prop of __getOwnPropSymbols(source)) {
+      if (exclude.indexOf(prop) < 0 && __propIsEnum.call(source, prop))
+        target[prop] = source[prop];
+    }
+  return target;
+};
+
+// src/lib/ControlledForm.tsx
+import { useForm, FormProvider } from "react-hook-form";
+import { jsx } from "react/jsx-runtime";
+var ControlledForm = (_a) => {
+  var _b = _a, { onSubmit, values, schema, validationResolver } = _b, rest = __objRest(_b, ["onSubmit", "values", "schema", "validationResolver"]);
+  const useFormOptions = { values };
+  if (schema && validationResolver) {
+    useFormOptions.resolver = validationResolver(schema);
+  }
+  const methods = useForm(useFormOptions);
+  return /* @__PURE__ */ jsx(FormProvider, __spreadProps(__spreadValues({}, methods), { children: /* @__PURE__ */ jsx("form", __spreadValues({ onSubmit: methods.handleSubmit(onSubmit) }, rest)) }));
+};
+export {
+  ControlledForm
+};

package/docs/propDefinitions.tsx

@@ -0,0 +1,31 @@
+export const missingRHFprops = {
+  name: {
+    description: 'Unique name of your input.',
+  },
+  deps: {
+    description: 'Validation will be triggered for the dependent inputs, it only limited to register api not trigger.',
+  },
+  max: {
+    description: 'The maximum value to accept for this input.',
+  },
+  maxLength: {
+    description: 'The maximum length of the value to accept for this input.',
+  },
+  min: {
+    description: 'The minimum value to accept for this input.',
+  },
+  minLength: {
+    description: 'The minimum length of the value to accept for this input.',
+  },
+  pattern: {
+    description: 'The regex pattern for the input.',
+  },
+  shouldUnregister: {
+    description:
+      'Input will be unregistered after unmount and defaultValues will be removed as well. Note: this prop should be avoided when using with useFieldArray as unregister function gets called after input unmount/remount and reorder.',
+  },
+  required: {
+    description:
+      'A Boolean which, if true, indicates that the input must have a value before the form can be submitted. You can assign a string to return an error message in the errors object. Note: This config aligns with web constrained API for required input validation, for object or array type of input use validate function instead.',
+  },
+};

package/introduction.stories.mdx

@@ -0,0 +1,7 @@
+import { Markdown } from '@storybook/blocks';
+import { Meta } from '@storybook/addon-docs';
+import ReadMe from './README.md?raw';
+
+<Meta title="Form Components/Controlled Form/Introduction" />
+
+<Markdown>{ReadMe}</Markdown>

package/jest.config.js

@@ -0,0 +1,7 @@
+const global = require('../../jest.config.global');
+
+module.exports = {
+  ...global,
+  displayName: 'controlled-form',
+  coverageDirectory: '../../coverage/controlled-form',
+};

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@availity/mui-controlled-form",
+  "version": "0.1.0",
+  "description": "Availity MUI ControlledForm Component - part of the @availity/element design system",
+  "keywords": [
+    "react",
+    "typescript",
+    "availity",
+    "mui"
+  ],
+  "homepage": "https://availity.github.io/element/?path=/docs/components-controlled-form-introduction--docs",
+  "bugs": {
+    "url": "https://github.com/Availity/element/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Availity/element.git",
+    "directory": "packages/controlled-form"
+  },
+  "license": "MIT",
+  "author": "Availity Developers <AVOSS@availity.com>",
+  "browser": "./dist/index.js",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts",
+    "dev": "tsup src/index.ts --format esm,cjs --watch --dts",
+    "clean": "rm -rf dist",
+    "clean:nm": "rm -rf node_modules",
+    "publish": "yarn npm publish --tolerate-republish --access public",
+    "publish:canary": "yarn npm publish --access public --tag canary"
+  },
+  "dependencies": {
+    "@availity/mui-autocomplete": "^0.9.9",
+    "@availity/mui-checkbox": "^0.2.5",
+    "@availity/mui-datepicker": "^0.5.0",
+    "@availity/mui-form-utils": "^0.16.4",
+    "@availity/mui-textfield": "^0.6.18",
+    "react-hook-form": "^7.51.3"
+  },
+  "devDependencies": {
+    "@availity/api-axios": "^9.0.6",
+    "@availity/mui-button": "^0.6.15",
+    "@availity/mui-layout": "^0.2.0",
+    "@availity/mui-menu": "^0.2.15",
+    "@availity/mui-paper": "^0.1.9",
+    "@availity/mui-typography": "^0.2.1",
+    "@hookform/resolvers": "^3.10.0",
+    "@mui/material": "^5.15.15",
+    "@tanstack/react-query": "^4.36.1",
+    "dayjs": "^1.11.13",
+    "react": "18.2.0",
+    "react-dom": "18.2.0",
+    "tsup": "^8.0.2",
+    "typescript": "^5.4.5",
+    "yup": "^1.6.1"
+  },
+  "peerDependencies": {
+    "@mui/material": "^5.11.9",
+    "react": ">=16.3.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/project.json

@@ -0,0 +1,41 @@
+{
+  "name": "mui-controlled-form",
+  "$schema": "../../node_modules/nx/schemas/project-schema.json",
+  "sourceRoot": "packages/controlled-form/src",
+  "projectType": "library",
+  "tags": [],
+  "targets": {
+    "lint": {
+      "executor": "@nx/eslint:lint",
+      "options": {
+        "eslintConfig": ".eslintrc.json",
+        "silent": false,
+        "fix": false,
+        "cache": true,
+        "cacheLocation": "./node_modules/.cache/controlled-form/.eslintcache",
+        "maxWarnings": -1,
+        "quiet": false,
+        "noEslintrc": false,
+        "hasTypeAwareRules": true,
+        "cacheStrategy": "metadata"
+      }
+    },
+    "test": {
+      "executor": "@nx/jest:jest",
+      "outputs": ["{workspaceRoot}/coverage/controlled-form"],
+      "options": {
+        "jestConfig": "packages/controlled-form/jest.config.js"
+      }
+    },
+    "version": {
+      "executor": "@jscutlery/semver:version",
+      "options": {
+        "preset": "conventional",
+        "commitMessageFormat": "chore({projectName}): release version ${version} [skip ci]",
+        "tagPrefix": "@availity/{projectName}@",
+        "trackDeps": true,
+        "skipCommitTypes": ["docs"]
+      }
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1 @@
+export * from './lib/ControlledForm';

package/src/lib/AsyncAutocomplete.stories.tsx

@@ -0,0 +1,113 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { ControlledAsyncAutocomplete } from './AsyncAutocomplete';
+import { ControlledForm } from './ControlledForm';
+import { Button } from '@availity/mui-button';
+import { useFormContext } from 'react-hook-form';
+import { Paper } from '@availity/mui-paper';
+import { Typography } from '@availity/mui-typography';
+import { Grid } from '@availity/mui-layout';
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import AvApi, { ApiConfig } from '@availity/api-axios';
+import { missingRHFprops } from '../../docs/propDefinitions';
+
+const meta: Meta<typeof ControlledAsyncAutocomplete> = {
+  title: 'Form Components/Controlled Form/Autocomplete/ControlledAsyncAutocomplete',
+  component: ControlledAsyncAutocomplete,
+  tags: ['autodocs'],
+  argTypes: missingRHFprops,
+};
+
+export default meta;
+
+const api = new AvApi({ name: 'example' } as ApiConfig);
+
+type Option = {
+  label: string;
+  value: number;
+};
+
+type ExampleResponse = {
+  totalCount: number;
+  options: Option[];
+  count: number;
+};
+
+const getResults = async (offset: number, limit: number) => {
+  // const offset = page * limit;
+  const resp = await api.post<ExampleResponse>({ offset, limit }, { params: {} });
+
+  return {
+    totalCount: resp.data.totalCount,
+    offset,
+    limit,
+    options: resp.data.options,
+    count: resp.data.count,
+  };
+};
+
+const loadOptions = async (offset: number, limit: number) => {
+  const { options, totalCount } = await getResults(offset, limit);
+
+  return {
+    options,
+    hasMore: offset + limit < totalCount,
+    offset,
+  };
+};
+
+const client = new QueryClient({
+  defaultOptions: {
+    queries: {
+      refetchOnWindowFocus: false,
+    },
+  },
+});
+
+export const _ControlledAsyncAutoComplete: StoryObj<typeof ControlledAsyncAutocomplete> = {
+  render: (args) => {
+    const SubmittedValues = () => {
+      const {
+        getValues,
+        formState: { isSubmitSuccessful },
+      } = useFormContext();
+
+      return isSubmitSuccessful ? (
+        <Paper sx={{ padding: '1.5rem', marginTop: '1.5rem' }}>
+          <Typography variant="h2">Submitted Values</Typography>
+          <pre>{JSON.stringify(getValues(), null, 2)}</pre>
+        </Paper>
+      ) : null;
+    };
+
+    const Actions = () => {
+      const {
+        reset,
+        formState: { isSubmitSuccessful },
+      } = useFormContext();
+      return (
+        <Grid container direction="row" justifyContent="space-between" marginTop={1}>
+          <Button disabled={!isSubmitSuccessful} children="Reset" color="secondary" onClick={() => reset()} />
+          <Button type="submit" disabled={isSubmitSuccessful} children="Submit" />
+        </Grid>
+      );
+    };
+    return (
+      <QueryClientProvider client={client}>
+        <ControlledForm values={{ controlledAutocomplete: undefined }} onSubmit={(data) => data}>
+          <ControlledAsyncAutocomplete {...args} />
+          <Actions />
+          <SubmittedValues />
+        </ControlledForm>
+      </QueryClientProvider>
+    );
+  },
+  args: {
+    name: 'controlledAsyncAutocomplete',
+    FieldProps: { label: 'Async Select', helperText: 'Helper Text', fullWidth: false },
+    getOptionLabel: (val: Option) => val.label,
+    loadOptions,
+    limit: 10,
+    queryKey: 'example',
+    required: 'This is required.',
+  },
+};