@iress-oss/ids-components 6.0.0-alpha.3 → 6.0.0-alpha.30

package/.ai/patterns/breadcrumbs.md

@@ -0,0 +1,164 @@
+# Breadcrumbs
+
+Breadcrumbs are a secondary navigation aid that helps users understand their current location within the site hierarchy and provides a simple way to navigate back to higher-level pages.
+
+> **Pattern:** `import { IressBreadcrumbs } from '@iress-oss/ids-components'`
+> **Storybook:** [Breadcrumbs in Storybook](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/components_patterns-breadcrumbs--docs)
+
+## Quick Start
+
+```tsx
+import { IressBreadcrumbs } from '@iress-oss/ids-components';
+
+<IressBreadcrumbs />
+```
+
+import {
+  ComponentOverview,
+  ComponentExample,
+} from '@iress-oss/ids-storybook-config';
+
+## Usage
+
+### Items
+
+This is the only required prop for the `IressBreadcrumbs` component, which defines the breadcrumb items to be displayed.
+
+- **label**: The text displayed for the breadcrumb item
+- **href**: The URL to navigate to when the item is clicked (optional for the current page)
+- **element**: The component used for rendering links, allowing integration with routing libraries
+
+[View "Default" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_patterns-breadcrumbs--default)
+
+### When to Use
+
+- **Site hierarchy navigation**: Help users understand where they are in a multi-level site structure
+- **Secondary navigation**: Provide an alternative way to navigate back to parent pages
+- **Context awareness**: Show the current page's relationship to parent sections
+
+### When Not to Use
+
+- **Single-level sites**: If your site has no hierarchy, breadcrumbs aren't necessary
+- **Primary navigation**: Breadcrumbs are supplementary; don't rely on them as the only navigation
+
+### Best Practices
+
+1. **Keep labels concise**: Use short, descriptive labels that clearly identify each level
+2. **Current page**: The last item should represent the current page and not be clickable
+3. **Consistent placement**: Position breadcrumbs near the top of the page, below primary navigation and close to the current page title
+4. **Mobile consideration**: On small screens, consider showing only the parent page link
+
+## Behaviour
+
+The Breadcrumb component follows WCAG 2.1 AA guidelines and includes:
+
+- **Semantic HTML**: Uses `<nav>`, `<ol>`, and `<li>` elements for proper structure
+- **ARIA labels**: `aria-label` identifies the navigation as breadcrumbs
+- **Current page**: `aria-current="page"` marks the current page item
+- **Keyboard navigation**: All links are keyboard accessible via Tab key
+- **Screen readers**: Separators are hidden from screen readers with `aria-hidden="true"`
+- **Focus indicators**: Visible focus rings for keyboard navigation
+
+## Examples
+
+This example demonstrates all supported breadcrumb configurations side by side.
+
+```tsx
+<IressPanel>
+<IressStack gap="xl">
+<IressStack>
+<IressText element="h3">2 Breadcrumbs</IressText>
+<IressBreadcrumbs items={[{ label: 'Home', href: '/' }, { label: 'Current' }]}
+/>
+</IressStack>
+
+<IressStack>
+<IressText element="h3">3 Breadcrumbs</IressText>
+<IressBreadcrumbs items={[
+{ label: 'Home', href: '/' },
+{ label: 'Products', href: '/products' },
+{ label: 'Details' },
+]}
+/>
+</IressStack>
+
+<IressStack>
+<IressText element="h3">4 Breadcrumbs</IressText>
+<IressBreadcrumbs items={[
+{ label: 'Home', href: '/' },
+{ label: 'Category', href: '/category' },
+{ label: 'Subcategory', href: '/subcategory' },
+{ label: 'Details' },
+]}
+/>
+</IressStack>
+
+<IressStack>
+<IressText element="h3">
+5+ Breadcrumbs (with default overflow)
+</IressText>
+<IressBreadcrumbs items={[
+{ label: 'Home', href: '/' },
+{ label: 'Level 1', href: '/l1' },
+{ label: 'Level 2', href: '/l2' },
+{ label: 'Level 3', href: '/l3' },
+{ label: 'Level 4', href: '/l4' },
+{ label: 'Current' },
+]}
+/>
+</IressStack>
+
+<IressStack>
+<IressText element="h3">
+5+ Breadcrumbs (with overflow disabled)
+</IressText>
+<IressBreadcrumbs items={[
+{ label: 'Home', href: '/' },
+{ label: 'Level 1', href: '/l1' },
+{ label: 'Level 2', href: '/l2' },
+{ label: 'Level 3', href: '/l3' },
+{ label: 'Level 4', href: '/l4' },
+{ label: 'Current' },
+]}
+limit={0}
+/>
+</IressStack>
+</IressStack>
+</IressPanel>
+```
+
+[View "AllConfigurations" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_patterns-breadcrumbs--all-configurations)
+
+### Integration with Routing Libraries
+
+The Breadcrumb component supports custom elements for integration with routing libraries:
+
+#### React Router
+
+```tsx
+
+<IressBreadcrumb
+  items={[
+    { label: 'Home', href: '/', element: RouterLink },
+    { label: 'Products', href: '/products', element: RouterLink },
+    { label: 'Details' },
+  ]}
+/>;
+```
+
+#### Next.js
+
+```tsx
+
+<IressBreadcrumb
+  items={[
+    { label: 'Home', href: '/', element: Link },
+    { label: 'Products', href: '/products', element: Link },
+    { label: 'Details' },
+  ]}
+/>;
+```
+
+---
+
+*View interactive examples: [https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/components_patterns-breadcrumbs--docs](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/components_patterns-breadcrumbs--docs)*

package/.ai/patterns/contextual-menu.md

@@ -0,0 +1,131 @@
+# Contextual Menu
+
+A compact overflow action pattern that surfaces contextual actions in a popover menu. Use this pattern for row-level or card-level secondary actions where space is constrained.
+
+> **Pattern:** `import { IressContextualMenu } from '@iress-oss/ids-components'`
+> **Storybook:** [Contextual Menu in Storybook](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/components_patterns-contextual-menu--docs)
+
+## Quick Start
+
+```tsx
+import { IressContextualMenu } from '@iress-oss/ids-components';
+
+<IressContextualMenu />
+```
+
+import {
+  ComponentExample,
+  ComponentOverview,
+} from '@iress-oss/ids-storybook-config';
+
+## Usage
+
+Use `IressContextualMenu` when actions are related to a specific item (such as a row, card or panel) and should not dominate the layout.
+
+- Keep menus short and action-focused.
+- Prefer verbs for labels (`Edit`, `Lock`, `Delete`).
+- Place destructive actions at the end of the list.
+
+### Items
+
+Pass an array of items with `key`, `label`, optional `icon` and `onClick` handler.
+
+[View "Default" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_patterns-contextual-menu--default)
+
+## Examples
+
+### Size
+
+Use `size="small"` or `size="medium"` to match surrounding density.
+
+```tsx
+<IressStack gap="sm">
+<IressContextualMenu size="small" />
+<IressContextualMenu size="medium" />
+</IressStack>
+```
+
+[View "Sizes" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_patterns-contextual-menu--sizes)
+
+### Align
+
+Use `align` to align the menu relative to the trigger. If there is not enough space in the preferred direction, it will flip to the opposite side.
+
+```tsx
+<IressStyled p="spacing.10">
+<IressStack gap="md">
+<IressInline horizontalAlign="center" gap="sm">
+<IressContextualMenu align="top-start" />
+<IressContextualMenu align="top" />
+<IressContextualMenu align="top-end" />
+</IressInline>
+<IressInline horizontalAlign="between">
+<IressStack gap="sm">
+<IressInline horizontalAlign="left">
+<IressContextualMenu align="left-start" />
+</IressInline>
+<IressInline horizontalAlign="left">
+<IressContextualMenu align="left" />
+</IressInline>
+<IressInline horizontalAlign="left">
+<IressContextualMenu align="left-end" />
+</IressInline>
+</IressStack>
+<IressStack gap="sm">
+<IressInline horizontalAlign="right">
+<IressContextualMenu align="right-start" />
+</IressInline>
+<IressInline horizontalAlign="right">
+<IressContextualMenu align="right" />
+</IressInline>
+<IressInline horizontalAlign="right">
+<IressContextualMenu align="right-end" />
+</IressInline>
+</IressStack>
+</IressInline>
+<IressInline horizontalAlign="center" gap="sm">
+<IressContextualMenu align="bottom-start" />
+<IressContextualMenu align="bottom" />
+<IressContextualMenu align="bottom-end" />
+</IressInline>
+</IressStack>
+</IressStyled>
+```
+
+[View "Align" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_patterns-contextual-menu--align)
+
+### Bordered Trigger
+
+Use `bordered` when the trigger needs stronger visual affordance.
+
+```tsx
+<IressInline gap="sm">
+<IressContextualMenu />
+<IressContextualMenu bordered />
+</IressInline>
+```
+
+[View "Bordered" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_patterns-contextual-menu--bordered)
+
+### Themes
+
+Use `theme="dark"` on panels using `colour.neutral.20` or darker backgrounds.
+
+```tsx
+<IressInline gap="sm" bg="alt" borderRadius="radius.system.layout" p="lg">
+<IressContextualMenu />
+<IressContextualMenu bordered />
+</IressInline>
+```
+
+[View "Themes" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_patterns-contextual-menu--themes)
+
+## Accessibility
+
+- Provide a meaningful `ariaLabel` that describes the menu purpose in context. By default it is `More options...`.
+- Ensure destructive labels are explicit (for example, `Delete account`).
+- Keep item labels concise and unique within the menu.
+
+---
+
+*View interactive examples: [https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/components_patterns-contextual-menu--docs](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/components_patterns-contextual-menu--docs)*

package/.ai/patterns/dropdown-menu.md

@@ -0,0 +1,195 @@
+# Dropdown Menu
+
+A component designed to filter a section based on a list of options and quickly navigate to relevant content.
+
+> **Pattern:** `import { IressDropdownMenu } from '@iress-oss/ids-components'`
+> **Storybook:** [Dropdown Menu in Storybook](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/components_patterns-dropdown-menu--docs)
+
+## Quick Start
+
+```tsx
+import { IressDropdownMenu } from '@iress-oss/ids-components';
+
+<IressDropdownMenu label="Select an option" />
+```
+
+import {
+  ComponentExample,
+  ComponentOverview,
+} from '@iress-oss/ids-storybook-config';
+
+## Usage
+
+The `IressDropdownMenu` component is a fully controlled component. It is designed to be used in situations where the selection of an option(s) should trigger an immediate update to the rendered data.
+
+Some examples of usage include:
+
+- Filtering a table based on a list of options
+- Navigating to a different section based on a list of options
+- Updating a chart based on a list of options
+
+This component is **not** designed to be used within forms and should be used to provide instant updates to rendered data. Instead, in forms, you should use components like `IressSelect`, `IressRadioGroup` or `IressCheckboxGroup`.
+
+Here is an example using multiple `IressDropdownMenu`s to filter an `IressTable`.
+
+```tsx
+<TableWithFilters />
+```
+
+[View "SearchTable" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_patterns-dropdown-menu--search-table)
+
+### Controlled
+
+The `value` prop can be used to completely control the state of the component. Use the `onChange` and `onReset` props to sync your state with the component.
+
+**Note:** The `value` prop is not checked against the options provided, allowing it to work with asynchronous options.
+
+```tsx
+<ControlledDropdownMenu />
+```
+
+[View "Controlled" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_patterns-dropdown-menu--controlled)
+
+### Multiple selection
+
+Using the `multiSelect` prop, the `IressDropdownMenu` will allow the user to make multiple selections.
+
+```tsx
+<ControlledDropdownMenuMultiselect />
+```
+
+[View "MultiSelect" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_patterns-dropdown-menu--multi-select)
+
+### Providing options
+
+#### `options`
+
+The `options` prop is required for the combobox. You can provide an array of `LabelValueMeta[]` objects to the `options` prop. Filtering is done based on the `label` property. Unique selected value(s) will be determined by the `value` property, falling back to `label` if `value` is not provided.
+
+```tsx
+<IressDropdownMenu label="Options" />
+```
+
+[View "Options" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_patterns-dropdown-menu--options)
+
+#### Asynchronous `options`
+
+If you would like to render suggestions from the server, you can pass a function to the `options` prop. It accepts a string parameter and returns a promise that resolves to an array of `LabelValueMeta[]` objects. No filtering is done for asynchronous options, you must filter the options yourself using the query.
+
+**Note:** Asynchronous `options` will automatically set the `searchable` prop to true.
+
+```tsx
+<ControlledDropdownMenuAsync />
+```
+
+[View "AsyncOptions" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_patterns-dropdown-menu--async-options)
+
+#### `initialOptions`
+
+If you want to provide initial options to the user, you can use the `initialOptions` prop. This is useful when you want to provide a list of options to the user before they start typing (eg. recommended search terms).
+
+**Note:** `initialOptions` only works if `searchable` is true.
+
+```tsx
+<IressDropdownMenu label="Select an option" searchable />
+```
+
+[View "InitialOptions" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_patterns-dropdown-menu--initial-options)
+
+### Complex Options
+
+The options prop also accepts further properties for each option. This is useful for displaying other data that compliments the main label.
+
+- append: accepts a ReactNode to append to the end of the option, usually a badge.
+- meta: accepts a ReactNode to display additional information about the option.
+- prepend: accepts a ReactNode to add to the start of the option, usually an icon.
+
+All `IressDropdownMenu`s accept meta as an attribute in the option array.
+
+```tsx
+<IressDropdownMenu label="Contact" />
+```
+
+[View "ComplexOptions" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_patterns-dropdown-menu--complex-options)
+
+## Behaviour
+
+- When the activator is tapped, the filter will open
+- Up and Down Arrow keys are used to navigate the options
+- When focus is on the search input:
+  - Pressing the down key will move focus to the first menu item
+  - If `visibleResetButton` is set to true, pressing the down key will focus the reset button instead
+- When focus is on the reset button:
+  - Pressing the down key will move focus to the first menu item
+- Pressing the Space or Enter keys when focussed on an option will select it
+- Pressing the Escape key will close the filter and place focus back on to the activator button
+
+## Examples
+
+### Input props
+
+You can customise some settings of the query input by setting the `inputProps`.
+
+It does have some defaults to help with user experience. `prepend` automatically has a search icon, and `clearable` is set to true by default.
+
+```tsx
+<IressDropdownMenu searchable />
+```
+
+[View "InputProps" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_patterns-dropdown-menu--input-props)
+
+### Searchable
+
+When an `IressDropdownMenu` has 10 or more options, it is recommended that you enable the search functionality. This can be done by adding the `searchable` prop.
+
+**Note:** When using asynchronous options, the `searchable` prop is automatically set to true.
+
+```tsx
+<IressDropdownMenu searchable />
+```
+
+[View "Searchable" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_patterns-dropdown-menu--searchable)
+
+### Reset filters
+
+Adding the `visibleResetButton` prop adds a way for the user a way to easily reset their choices. This works for single and multiple selection filters.
+
+Below are examples of both single selects and multi selects with `visibleResetButton` enabled.
+
+```tsx
+<IressDropdownMenu visibleResetButton />
+```
+
+[View "ResetFilters" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_patterns-dropdown-menu--reset-filters)
+
+### No results
+
+If you would like to show a message when there are no results, you can use the `searchNoResultsText` prop. It accepts any React node.
+
+```tsx
+<IressDropdownMenu searchable />
+```
+
+[View "NoResultsText" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_patterns-dropdown-menu--no-results-text)
+
+### Popover props
+
+Under the hood, filter uses `IressPopover` to display the filter options. You can customise this with `popoverProps`. It accepts `align`, `className`, `container` and `displayMode`.
+
+There are two additional props that filter accepts to customise the popover: `header` and `footer`. You can place additional content above or below the results using these props.
+
+[View "PopoverProps" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_patterns-dropdown-menu--popover-props)
+
+### Selected options text
+
+In `multiSelect` mode, the selections options are displayed using the `selectedOptionsText` prop. You can customise this text to suit your needs. It will replace `{{numOptions}}` with the number of selected options.
+
+```tsx
+<IressDropdownMenu multiSelect selectedOptionsText=" - " />
+```
+
+[View "SelectedOptionsText" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_patterns-dropdown-menu--selected-options-text)
+
+---
+
+*View interactive examples: [https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/components_patterns-dropdown-menu--docs](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/components_patterns-dropdown-menu--docs)*

package/.ai/patterns/form-recipes.md

@@ -0,0 +1,160 @@
+# Recipes
+
+Form pattern documentation.
+
+> **Pattern:** `@iress-oss/ids-components`
+> **Storybook:** [Recipes in Storybook](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/components_patterns-form--docs)
+
+## With readonly data
+
+You can use `IressForm` with readonly data by setting the `readOnly` prop to `true` on controlled elements. This will disable those form controls, but will include the values in the form submission.
+
+Please take note of the following when displaying read only data.
+
+- It is best to keep readonly data in a separate section of the form, to further avoid confusion with editable fields.
+
+```tsx
+<WithReadonlyDataForm />
+```
+
+[View "WithReadonlyData" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_patterns-form--with-readonly-data)
+
+## Switching between readonly and edit modes
+
+It is recommended to use a button to toggle between read-only and editable input modes.
+
+Please take note of the following when switching between modes:
+
+- Switching is done on a per-section basis, not on a per-field basis.
+- When the user saves the data, it should switch back to read-only mode to avoid any confusion about whether the changes have been saved.
+
+```tsx
+<SwitchEditReadonlyForm />
+```
+
+[View "SwitchEditReadonly" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_patterns-form--switch-edit-readonly)
+
+## Alternative form validation
+
+`IressForm` is always recommended for all validation, as it is the cleanest way (least code) to provide the best form user experience for your users. Please visit the [`IressForm` documentation](/docs/components-form--docs) for different validation examples.
+
+However, if you have more complex requirements and you find `IressForm` too opinionated for your needs, you can always bring your own form validation using a native `form` element and the other IDS components such as `IressField`.
+
+Here is an example showcasing a form using the native form constraints API to achieve validation using IDS components. There are other libraries such as: [Yup](https://github.com/jquense/yup), [Joi](https://github.com/hapijs/joi) or [Zod](https://zod.dev/)) which can improve scalability, with the downside being you will have to maintain all validation yourself.
+
+```tsx
+<NativeValidationForm />
+```
+
+[View "NativeValidation" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_patterns-form--native-validation)
+
+## Nested forms
+
+Unfortunately, it is [forbidden to nest form elements as per the HTML specifications](https://developer.mozilla.org/en-US/docs/Learn/Forms/How_to_structure_a_web_form).
+
+To achieve a similar effect, you can use multiple `IressForm` components, and trigger validation in multiple ways:
+
+1. You can trigger specific forms using the `form` attribute of `IressButton`. The [`form` attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#form) allows you to specify the form ID to submit when the button is clicked, which can be any form on the page, and will take precedence over the parent form of a button.
+2. If you need to trigger multiple forms, you can use the [`requestSubmit` method](https://developer.mozilla.org/en-US/docs/Web/API/HTMLFormElement/requestSubmit) on the form element to trigger the validation of multiple forms.
+3. If you only want to trigger validation and not trigger submission even if the validation passes, you can use the `ref` attribute of `IressForm` and trigger validation manually using `ref.current?.api.trigger()`, which is based on the [React Hook Form API](https://react-hook-form.com/docs/useform/trigger).
+
+The example here showcases triggering validation using the `form` attribute of `IressButton` and the `requestSubmit` method on the form element.
+
+```tsx
+<NestedFormsExample />
+```
+
+[View "NestedForms" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_patterns-form--nested-forms)
+
+## Form Groups
+
+Powered by [React Hook Form](https://react-hook-form.com/docs/usefieldarray)'s `useFieldArray`, this example allows you add/edit/delete multiple children sections within ONE form (not nested form).
+
+```tsx
+<FormGroupsExample />
+```
+
+[View "FormGroups" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_patterns-form--form-groups)
+
+## Forms in expanders (lazy loading)
+
+If you are using forms in expanders, or in other scenarios when the loading of the form may be delayed, it is recommended to only load the form when it is required. This will improve performance of your application, and make it more predictable. It may also fix act warnings in tests if you are seeing some appearing due to conditionally loaded `IressForm` elements.
+
+```tsx
+<FormExpanders />
+```
+
+[View "FormsInExpanders" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_patterns-form--forms-in-expanders)
+
+## Conditional fields (`useWatch`)
+
+When you have fields that are conditionally shown, you can use the `useWatch` hook to watch the value of another field and conditionally render the field.
+
+**Notes:**
+
+- You can use the `api.watch` method on the `IressForm`'s ref to watch the value of a field, but it is recommended to use the hook for better performance by isolating re-rendering at the component level.
+
+```tsx
+<UseWatchForm />
+```
+
+[View "UseWatch" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_patterns-form--use-watch)
+
+## Hidden inputs
+
+You can use hidden inputs to store data that you do not want to display to the user, but still need to include in the form submission. This is useful for storing metadata or other information that is not editable by the user.
+
+> [!WARNING]
+> **Warning**
+>
+> This is not a recommended practice, as it can lead to security issues if
+>   sensitive data is stored in hidden inputs. It is better to use a variable to
+>   store your data, and include it in the form submission using the `onSubmit`
+>   handler.
+
+```tsx
+<HiddenInputsForm />
+```
+
+[View "HiddenInputs" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_patterns-form--hidden-inputs)
+
+## Validation depend on other fields
+
+This example shows how to validate one field based on another field's value.
+
+The budget amount input validates against the selected budget range using the custom `validateBudgetInput` rules.
+
+```tsx
+<ValidationDependOnOtherFieldsExample />
+```
+
+[View "ValidationDependOnOtherFields" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_patterns-form--validation-depend-on-other-fields)
+
+## Custom form field components
+
+You can integrate custom components within `IressFormField` to create enhanced form experiences.
+
+This demo showcases how to embed a custom `TranscriptTextBox` component into `IressFormField` while leveraging its built-in validation rules, error handling, and state management without additional implementation.
+
+**Reminder:** When building custom form components, avoid managing error message state internally. This helps maintain the IressForm as the single source of truth and ensures consistent, predictable UI behavior.
+
+Key features demonstrated:
+
+- **Universal Integration Pattern**: Shows how any custom component can be embedded in IressFormField
+- **Built-in Validation**: Leverages IressFormField's validation rules with custom validation logic
+- **Multiple Error Messages**: Displays simultaneous validation errors (e.g., wrong file type AND too large)
+- **Drag & Drop**: Files can be dragged and dropped directly onto the textarea
+- **File Upload Button**: Traditional file selection via button click
+- **Visual Feedback**: UI changes during drag operations with border and background updates
+- **Form State Management**: Automatically integrates with form context using controlled props
+- **File Management**: Display uploaded files with remove functionality using `IressPanel`
+
+```tsx
+<CustomFormFieldComponentsExample />
+```
+
+[View "CustomFormFieldComponents" example in Storybook →](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/story/components_patterns-form--custom-form-field-components)
+
+---
+
+*View interactive examples: [https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/components_patterns-form--docs](https://main--691abcc79dfa560a36d0a74f.chromatic.com/?path=/docs/components_patterns-form--docs)*