docs: rearrange form and upgrade pages

.github/CONTRIBUTING.md

@@ -18,16 +18,16 @@ This monorepo is managed using [yarn](https://yarnpkg.com/getting-started) and [
 
 ## Installation
 
-The currently recommended version of node to use when developing in this repo is: `v20`. We recommend using [fnm](https://github.com/Schniz/fnm#readme) to have your node version automatically changed when you `cd` into the repo.
+The currently recommended version of node to use when developing in this repo is: `v24`. We recommend using [fnm](https://github.com/Schniz/fnm#readme) to have your node version automatically changed when you `cd` into the repo.
 
-We use `yarn berry` (aka yarn v3) to manage dependencies. Install `yarn` globally:
+We use `yarn berry` (aka yarn v4) to manage dependencies. Install `yarn` globally:
 
 ```sh
 node --version
 npm -i -g yarn
 ```
 
-> This command will install yarn v1. When we run the next command then yarn v3 will be added.
+> This command will install yarn v1. When we run the next command then yarn v4 will be added.
 
 Then install the dependencies:
 
@@ -104,12 +104,14 @@ The generator assumes the package is a wrapper for an MUI component, as such:
 - `@mui/material` is a peer dependency
 - MUI link in README generated assuming package name is same as corresponding MUI component name
 - Default component code is a wrapper for the MUI `Card` component. Replace `Card` with whatever component you're building a wrapper for, or remove the `Card` references entirely.
+- Only original component generated that matches package name is added to the `@availity/element` exports. Any additional exports will need to be added manually.
 
 ### Dos and Don'ts
 
-- Don't add a default export to the package, this will affect `@availity/element`
 - Do create separate stories files for each exported component. The storybook automated documentation creates the arguments table based on the component in the `Meta` of that file.
 - Do make sure components stick to the Availity Design Standards. Add the corresponding component theme information to the themes in `@availity/theme`
+- Don't forget to add additional package exports to `@availity/element`, the generator only handles the namesake component.
+- Don't merge before setting up trusted publishing for the new package. We recommend publishing a canary version so the package is available in npm to setup trusted publishing, however don't push up the canary version version commit. _You can manually add the package tag if there's a certain major version you're targetting, i.e. matching the current major version of element `@availity/mui-<package-name>@2.0.0`_
 
 ## Commits
 

apps/element-storybook/.storybook/manager.ts

@@ -7,7 +7,7 @@ addons.setConfig({
   theme: elementTheme,
   sidebar: {
     collapsedRoots: [
-      'bs4-migration',
+      'upgrading',
       'sample-layouts',
       'design-system',
     ],

apps/element-storybook/.storybook/preview.tsx

@@ -74,12 +74,12 @@ const preview: Preview = {
           'Element',
           'Contributing',
           'Introduction',
-          'BS4 Migration',
-          ['Getting Started', 'Form Migration', '*', 'Upload'],
+          'Upgrading',
+          ['BS4 Migration', ['Getting Started', 'Form Migration', '*', 'Upload']],
           'Sample Layouts',
           'Design System',
           'Form Components',
-          ['Component Guide', 'Controlled Form', 'FormUtils'],
+          ['Component Guide', 'Controlled Form', ['*', 'README'], 'Uncontrolled Fields', ['Autocomplete', ['*', 'README'], '*', 'Datepicker', ['*', 'README'], 'TextField', ['*', 'README']], 'Uncontrolled FormUtils', ['*', 'README']],
           'Components',
         ],
       },

apps/element-storybook/src/FormComponents.mdx

@@ -29,9 +29,9 @@ import {
 
 Element form components can be split into three categories
 
-- Controlled: Prebuilt fields integrated with `react-hook-form`
-- Fields: Prebuilt fields, i.e. `TextField`, `Autocomplete`, `DatePicker`
-- Form Utils: The base components needed to build your own field, i.e. `Label`, `Input`, `HelperText`, etc
+- Controlled Components: Prebuilt fields and utils integrated with `react-hook-form`
+- Uncontrolled Fields: Prebuilt fields, i.e. `TextField`, `Autocomplete`, `DatePicker`
+- Uncontrolled Form Utils: The base components needed to build your own field, i.e. `Label`, `Input`, `HelperText`, etc
 
 <br />
 
@@ -41,7 +41,7 @@ Element form components can be split into three categories
 
 ### Controlled
 
-The [`Controlled Form`](./?path=/docs/form-components-controlled-form-introduction--docs) package contains
+The [`Controlled Form`](./?path=/docs/form-components-controlled-form-readme--docs) package contains
 controlled counterparts for the most used Form/Field components:
 
 - `ControlledAsyncAutocomplete`
@@ -60,15 +60,15 @@ Fully assembled fields with `Label`, `Input`, `HelperText`, and `FormControl`
 
 | Component | Description | Package | Example |
 | --------- | ----------- | ------- | ------- |
-| Autocomplete | Select field with autocomplete abilities. | [`Autocomplete`](./?path=/docs/form-components-autocomplete-introduction--docs) | <AutocompleteExample/> |
-| AsyncAutocomplete | Autocomplete with loader while options are fetched | [`Autocomplete`](./?path=/docs/form-components-autocomplete-introduction--docs) | <AsyncAutocompleteExample/> |
-| CodesAutocomplete, <br />OrganizationAutocomplete, <br />ProviderAutocomplete | Specialized autocomplete fields | [`Autocomplete`](./?path=/docs/form-components-autocomplete-introduction--docs) | <CodesAutocompleteExample/> |
-| Datepicker | DatePicker field <br />*Note: No DateRangePicker component - a code example is available for reference* | [`Datepicker`](./?path=/docs/form-components-datepicker-introduction--docs) | <DatepickerExample/> |
-| TextField | Generic input field. Handles text input or basic select, however `Autocomplete` is preferred for select fields. | [`TextField`](./?path=/docs/form-components-textfield-introduction--docs) | <TextFieldExample/> |
+| Autocomplete | Select field with autocomplete abilities. | [`Autocomplete`](./?path=/docs/form-components-uncontrolled-fields-autocomplete-readme--docs) | <AutocompleteExample/> |
+| AsyncAutocomplete | Autocomplete with loader while options are fetched | [`Autocomplete`](./?path=/docs/form-components-uncontrolled-fields-autocomplete-readme--docs) | <AsyncAutocompleteExample/> |
+| CodesAutocomplete, <br />OrganizationAutocomplete, <br />ProviderAutocomplete | Specialized autocomplete fields | [`Autocomplete`](./?path=/docs/form-components-uncontrolled-fields-autocomplete-readme--docs) | <CodesAutocompleteExample/> |
+| Datepicker | DatePicker field <br />*Note: No DateRangePicker component - a code example is available for reference* | [`Datepicker`](./?path=/docs/form-components-uncontrolled-fields-datepicker-readme--docs) | <DatepickerExample/> |
+| TextField | Generic input field. Handles text input or basic select, however `Autocomplete` is preferred for select fields. | [`TextField`](./?path=/docs/form-components-uncontrolled-fields-textfield-readme--docs) | <TextFieldExample/> |
 
 ### Form Utils
 
-Predominantly in the [`@availity/mui-form-utils`](./?path=/docs/form-components-formutils-introduction--docs) package,
+Predominantly in the [`@availity/mui-form-utils`](./?path=/docs/form-components-uncontrolled-formutils-readme--docs) package,
 includes the most basic subcomponents of a field. While `TextField` and other field components handle most uses,
 manual field composition will be needed for items like `Checkbox`, `Radio`, `Switch`, and `FormGroup`.
 

apps/element-storybook/src/bs4-migration/FormMigration.stories.tsx

@@ -28,7 +28,7 @@ import {
 import FormMigration from './form-migration.md?raw';
 
 const meta: Meta = {
-  title: 'BS4 Migration/Form Migration',
+  title: 'Upgrading/BS4 Migration/Form Migration',
   tags: ['autodocs'],
   parameters: { docs: {
     description: { component: `${FormMigration}`},

apps/element-storybook/src/bs4-migration/form-migration.md

@@ -1,7 +1,7 @@
 There are two main changes made with the form components in `@availity/element`:
 
 - Removed `formik`
-- Updated [usage guidelines](./?path=/docs/bs4-migration-form-migration--disabled-fields)  for `disabled` fields and the new `read-only` fields
+- Updated [usage guidelines](./?path=/docs/upgrading/bs4-migration-form-migration--disabled-fields)  for `disabled` fields and the new `read-only` fields
 
 ## Why did we remove formik?
 
@@ -33,15 +33,15 @@ using it with `yup`+`@hookform/resolvers/yup` (don't worry,
 | availity-react<br />formik | element<br />react-hook-form | element<br />Not Controlled | Description |
 | ---------------------------- | ---------------------------- | --------------------------- | ----------- |
 | CheckboxGroup | _N/A_ | _N/A - built with `FormControl`, `FormLabel`, & `FormGroup`_ | Full checkbox group field |
-| CurrencyInput | _N/A_ | _N/A - built with `TextField` and replacing input. See [Input Masking](./?path=/docs/form-components-textfield-textfield--docs&args=#input-masking)_ | Field with currency input masking |
+| CurrencyInput | _N/A_ | _N/A - built with `TextField` and replacing input. See [Input Masking](./?path=/docs/form-components-uncontrolled-fields-textfield--docs&args=#input-masking)_ | Field with currency input masking |
 | DateField | ControlledDatepicker | Datepicker | Date field with picker |
-| DateRangeField | _N/A_ | _N/A - see [date range code example](./?path=/docs/form-components-datepicker-datepicker--docs#date-range-picker)_ | Date range field(s) with picker |
+| DateRangeField | _N/A_ | _N/A - see [date range code example](./?path=/docs/form-components-uncontrolled-fields-datepicker-datepicker--docs#date-range-picker)_ | Date range field(s) with picker |
 | Field | ControlledTextField | TextField | Text input field |
 | FieldHelpIcon | _N/A_ | FieldHelpIcon | Availity help topic link |
 | FormGroup | _N/A_ | FormControl | Context wrapper for a field. Syncs state, i.e. error, required, disabled, focused, etc |
 | Input | _N/A_ | Input | Bare input |
 | Label | _N/A_ | FormLabel<br />FormControlLabel | Label for input/group |
-| Phone | _N/A_ | _N/A - built with `TextField` and replacing input. See [Input Masking](./?path=/docs/form-components-textfield-textfield--docs&args=#input-masking)_ | Field with phone masking |
+| Phone | _N/A_ | _N/A - built with `TextField` and replacing input. See [Input Masking](./?path=/docs/form-components-uncontrolled-fields-textfield--docs&args=#input-masking)_ | Field with phone masking |
 | RadioGroup | ControlledRadioGroup | _N/A - built with `FormControl`, `FormLabel`, & `RadioGroup`_ | Full radio group field |
 | SelectField | ControlledAutocomplete | Autocomplete | Select field with autocompletion |
 | ResourceSelect | ControlledAsyncAutocomplete | AsyncAutocomplete | Select field with loader while loading options |

apps/element-storybook/src/bs4-migration/migration.mdx

@@ -13,15 +13,15 @@ import {
   InputGroupAddonExample,
 } from './MigrationExamples';
 
-<Meta title="BS4 Migration/Getting Started" />
+<Meta title="Upgrading/BS4 Migration/Getting Started" />
 
 <Markdown># Getting Started</Markdown>
 
 <br />
 
 <Markdown>## Planning and Strategy</Markdown>
 
-_Our guide is written assuming you're planning migration one component swap at a time. However, if you're doing whole sections at a time pay extra attention to the [Components Without a Drop-in Option](./?path=/docs/bs4-migration-getting-started--docs&args=#components-without-a-drop-in-option) section to plan accordingly._
+_Our guide is written assuming you're planning migration one component swap at a time. However, if you're doing whole sections at a time pay extra attention to the [Components Without a Drop-in Option](./?path=/docs/upgrading/bs4-migration-getting-started--docs&args=#components-without-a-drop-in-option) section to plan accordingly._
 
 ### Drop-in Components and the Migration Theme
 
@@ -42,7 +42,7 @@ The migration theme is accessible by passing `theme='legacyBS'` to the `ThemePro
 
 Where you're coming from will determine your strategy for form migration. We have moved away from `formik` (used by `@availity/form`) in favor of `react-hook-form`. We have also provided the base components to utilize with your own logic/libraries.
 
-There's additional pattern changes around the usage of `disabled` fields. See the [Form migration](./?path=/docs/bs4-migration-form-migration--docs) docs for more information.
+There's additional pattern changes around the usage of `disabled` fields. See the [Form migration](./?path=/docs/upgrading/bs4-migration-form-migration--docs) docs for more information.
 
 <Markdown>### Components Without a Drop-in Option</Markdown>
 
@@ -174,12 +174,12 @@ Not all classes/components from Bootstrap/Reactstrap have a similar name or 1:1
 | `Badge`<sup>2</sup>                                 | [`Chip`](./?path=/docs/components-chip-chip--docs)                                                                                                                                        | Inline colored label/descriptor                                                                                                          |       <ChipExample/>       |
 | `Column`/`Row`                                      | [`Grid`](./?path=/docs/components-layout-grid--docs)                                                                                                                                      | Horizontal and Vertical layout                                                                                                           |       <GridExample/>       |
 | `Dropdown`                                          | [`Menu`](./?path=/docs/components-menu-menu--docs)                                                                                                                                        | Display a list on temporary surface                                                                                                      |       <MenuExample/>       |
-| `InputGroupAddon`                                   | [`InputAdornment`](./?path=/docs/form-components-formutils-input--docs) used in the `startAdornment` or `endAdornment` prop on the Input component or any component that takes InputProps | Extend form controls by adding text, buttons, or button groups on either side of textual inputs, custom selects, and custom file inputs. | <InputGroupAddonExample /> |
+| `InputGroupAddon`                                   | [`InputAdornment`](./?path=/docs/form-components-uncontrolled-formutils-input--docs) used in the `startAdornment` or `endAdornment` prop on the Input component or any component that takes InputProps | Extend form controls by adding text, buttons, or button groups on either side of textual inputs, custom selects, and custom file inputs. | <InputGroupAddonExample /> |
 | `ListGroup`, `ListGroupItem`, `ListGroupItemStatus` | [`List`](./?path=/docs/components-list-list--docs)                                                                                                                                        | List, ListItem, ListItemStatusCard                                                                                                       |     <ListItemExample/>     |
 | `ListGroupItemHeading`                              | [`Typography`](./?path=/docs/components-typography-typography--docs)                                                                                                                      | No longer a separate component                                                                                                           |                            |
 | `Modal`                                             | [`Dialog`](./?path=/docs/components-dialog-dialog--docs)                                                                                                                                  | Popover Dialog (Blocking and Non-Blocking)                                                                                               |      <DialogExample/>      |
 | `Nav`                                               | [`Tabs`](./?path=/docs/components-tabs-tabs--docs)                                                                                                                                        | Tab Navigation                                                                                                                           |       <TabExample/>        |
-| `Phone`                                             | [`TextField` with phone masking](https://availity.github.io/element/?path=/story/form-components-textfield-textfield--phone-with-ext)                                                     | TextField that auto-formats phone numbers                                                                                                |      <PhoneExample />      |
+| `Phone`                                             | [`TextField` with phone masking](https://availity.github.io/element/?path=/story/form-components-uncontrolled-fields-textfield--phone-with-ext)                                                     | TextField that auto-formats phone numbers                                                                                                |      <PhoneExample />      |
 | `Toast`                                             | [`Snackbar`](./?path=/docs/components-snackbar-snackbar--docs)                                                                                                                            | Brief Notifications                                                                                                                      |     <SnackbarExample/>     |
 | `Upload`                                            | [`FileSelector`](./?path=/docs/components-file-selector-file-selector--docs)                                                                                                              | Select a file to upload                                                                                                                  |                            |
 | `Wizard`                                            | [`Stepper`](./?path=/docs/components-stepper-stepper--docs)                                                                                                                               | Convey progress through numbered steps                                                                                                   |     <StepperExample/>      |

apps/element-storybook/src/templates/bs4migration.mdx

@@ -1,6 +1,6 @@
 import { Meta, Source } from '@storybook/blocks';
 
-<Meta title="BS4 Migration/Component" />
+<Meta title="Upgrading/BS4 Migration/Component" />
 *Copy file into package*
 
 # Component Migration

apps/element-storybook/src/upgrading-to-v1.mdx

@@ -1,6 +1,6 @@
 import { Meta } from '@storybook/addon-docs/blocks';
 
-<Meta title="Upgrading to v1" />
+<Meta title="Upgrading/Upgrading to v1" />
 
 ## Upgrading to Element v1
 

apps/element-storybook/src/upgrading-to-v2.mdx

@@ -1,6 +1,6 @@
 import { Meta } from '@storybook/addon-docs/blocks';
 
-<Meta title="Upgrading to v2" />
+<Meta title="Upgrading/Upgrading to v2" />
 
 ## Upgrading to Element v2
 

packages/autocomplete/README.md

@@ -10,7 +10,7 @@
 
 This package extends the MUI Autocomplete component: [MUI Autocomplete Docs](https://mui.com/components/autocomplete/)
 
-Live demo and documentation in our [Storybook](https://availity.github.io/element/?path=/docs/form-components-autocomplete-introduction--docs)
+Live demo and documentation in our [Storybook](https://availity.github.io/element/?path=/docs/form-components-uncontrolled-fields-autocomplete-readme--docs)
 
 Availity standards for design and usage can be found in the [Availity Design Guide](https://design.availity.com/2e36e50c7)
 

packages/autocomplete/introduction.mdx

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

packages/autocomplete/package.json

@@ -8,7 +8,7 @@
     "availity",
     "mui"
   ],
-  "homepage": "https://availity.github.io/element/?path=/docs/form-components-autocomplete-introduction--docs",
+  "homepage": "https://availity.github.io/element/?path=/docs/form-components-uncontrolled-fields-autocomplete-readme--docs",
   "bugs": {
     "url": "https://github.com/Availity/element/issues"
   },