chore(forms): Extended features docs (#2978)

Doing the following (inside the Forms-extension): - Rewrite Extended feature page with sections instead of automatic component lists - Moving DataContext and Value from "Create your own component" to "Extended features" - Moving Field from "Create your own component" to a separate menu item above the field components in the left menu - Remove duplicated list of components between the Field page and the two Base/Feature field pages --------- Co-authored-by: Anders <[email protected]>
dnbexperience · Dec 8, 2023 · 6fb8d4a · 6fb8d4a
1 parent c954bab
commit 6fb8d4a
Show file tree

Hide file tree

Showing 92 changed files with 166 additions and 247 deletions.
diff --git a/packages/dnb-design-system-portal/src/docs/uilib/extensions/forms.mdx b/packages/dnb-design-system-portal/src/docs/uilib/extensions/forms.mdx
@@ -91,7 +91,7 @@ In summary:
 - State management using the declarative [JSON Pointer](https://datatracker.ietf.org/doc/html/draft-ietf-appsawg-json-pointer-03) directive (i.e `path="/firstName"`).
 - Simple validation (like `minLength` on text fields) as well as [Ajv JSON schema validator](https://ajv.js.org/) support on both single fields and the whole data set.
 - Building blocks for [creating custom field components](/uilib/extensions/forms/create-component).
-- Static [value components](/uilib/extensions/forms/create-component/Value/) for displaying data with proper formatting.
+- Static [value components](/uilib/extensions/forms/extended-features/Value/) for displaying data with proper formatting.
 
 ### Basic field usage
 
@@ -168,7 +168,7 @@ To build an entire form, there are surrounding components such as [Form.Handler]
 
 ### Value components
 
-Beside the interactive [Field](/uilib/extensions/forms/create-component/Field/) components, there are also the static [Value](/uilib/extensions/forms/create-component/Value/) components. Use these to show summaries or read-only parts of your application with benefits such as linking to source data and standardized formatting based on the type of data to be displayed.
+Beside the interactive [Field](/uilib/extensions/forms/fields/) components, there are also the static [Value](/uilib/extensions/forms/extended-features/Value/) components. Use these to show summaries or read-only parts of your application with benefits such as linking to source data and standardized formatting based on the type of data to be displayed.
 
 ## Create your own components
 

diff --git a/packages/dnb-design-system-portal/src/docs/uilib/extensions/forms/base-fields.mdx b/packages/dnb-design-system-portal/src/docs/uilib/extensions/forms/base-fields.mdx
@@ -1,6 +1,6 @@
 ---
 title: 'Base fields'
-order: 1
+order: 2
 breadcrumb:
   - text: Forms
     href: /uilib/extensions/forms/

diff --git a/...sign-system-portal/src/docs/uilib/extensions/forms/base-fields/Boolean/info.mdx b/...sign-system-portal/src/docs/uilib/extensions/forms/base-fields/Boolean/info.mdx
@@ -6,4 +6,4 @@ showTabs: true
 
 `Field.Boolean` is the base component for receiving user input where the target data is of type `boolean`.
 
-There is a corresponding [Value.Boolean](/uilib/extensions/forms/create-component/Value/Boolean) component.
+There is a corresponding [Value.Boolean](/uilib/extensions/forms/extended-features/Value/Boolean) component.
diff --git a/...esign-system-portal/src/docs/uilib/extensions/forms/base-fields/Number/info.mdx b/...esign-system-portal/src/docs/uilib/extensions/forms/base-fields/Number/info.mdx
@@ -6,7 +6,7 @@ showTabs: true
 
 `Field.Number` is the base component for receiving user input where the target data is of type `number`.
 
-There is a corresponding [Value.Number](/uilib/extensions/forms/create-component/Value/Number) component.
+There is a corresponding [Value.Number](/uilib/extensions/forms/extended-features/Value/Number) component.
 
 ## When to use and not to use
 

diff --git a/...esign-system-portal/src/docs/uilib/extensions/forms/base-fields/Option/info.mdx b/...esign-system-portal/src/docs/uilib/extensions/forms/base-fields/Option/info.mdx
@@ -5,5 +5,3 @@ showTabs: true
 ## Description
 
 `Field.Option` is a part for building selection inputs with Field.Select.
-
-There is a corresponding [Value.Option](/uilib/extensions/forms/create-component/Value/Option) component.
diff --git a/...esign-system-portal/src/docs/uilib/extensions/forms/base-fields/String/info.mdx b/...esign-system-portal/src/docs/uilib/extensions/forms/base-fields/String/info.mdx
@@ -6,7 +6,7 @@ showTabs: true
 
 `Field.String` is the base component for receiving user input where the target data is of type `string`.
 
-There is a corresponding [Value.String](/uilib/extensions/forms/create-component/Value/String) component.
+There is a corresponding [Value.String](/uilib/extensions/forms/extended-features/Value/String) component.
 
 ## Autocomplete and autofill
 

diff --git a/...s/dnb-design-system-portal/src/docs/uilib/extensions/forms/create-component.mdx b/...s/dnb-design-system-portal/src/docs/uilib/extensions/forms/create-component.mdx
@@ -1,6 +1,6 @@
 ---
 title: 'Create your own component'
-order: 4
+order: 5
 breadcrumb:
   - text: Forms
     href: /uilib/extensions/forms/

diff --git a/...portal/src/docs/uilib/extensions/forms/create-component/DataContext/Context.mdx b/...portal/src/docs/uilib/extensions/forms/create-component/DataContext/Context.mdx
diff --git a/...-design-system-portal/src/docs/uilib/extensions/forms/create-component/Field/Examples.tsx b/...-design-system-portal/src/docs/uilib/extensions/forms/create-component/Field/Examples.tsx
diff --git a/...tem-portal/src/docs/uilib/extensions/forms/create-component/FieldBlock/info.mdx b/...tem-portal/src/docs/uilib/extensions/forms/create-component/FieldBlock/info.mdx
@@ -6,7 +6,7 @@ import Demos from 'Docs/uilib/extensions/forms/create-component/FieldBlock/demos
 
 ## Description
 
-`FieldBlock` is a reusable wrapper for building [Field](/uilib/extensions/forms/create-component/Field) or [Value](/uilib/extensions/forms/create-component/Value) components.
+`FieldBlock` is a reusable wrapper for building [Field](/uilib/extensions/forms/fields) or [Value](/uilib/extensions/forms/extended-features/Value) components.
 
 It shows surrounding elements through properties from `FieldProps` like `label` and `error`, and ensure that spacing between different fields work as required when put into surrounding components like [Flex.Container](/uilib/layout/flex/container/) or [Card](/uilib/components/card/).
 

diff --git a/...rtal/src/docs/uilib/extensions/forms/create-component/FieldBlock/properties.mdx b/...rtal/src/docs/uilib/extensions/forms/create-component/FieldBlock/properties.mdx
@@ -4,11 +4,11 @@ showTabs: true
 
 ## Properties
 
-| Property                                                                                                         | Type                | Description                                                                                                 |
-| ---------------------------------------------------------------------------------------------------------------- | ------------------- | ----------------------------------------------------------------------------------------------------------- |
-| `width`                                                                                                          | `string` or `false` | _(optional)_ `small`, `medium`, `large`, `stretch` or `false` for predefined standard widths.               |
-| `contentsWidth`                                                                                                  | `string` or `false` | _(optional)_ `small`, `medium`, `large`, `stretch` or `false` for predefined standard widths.               |
-| `size`                                                                                                           | `string` or `false` | _(optional)_ define one of the following [heading size](/uilib/elements/heading/): `medium` or `large`.     |
-| `asFieldset`                                                                                                     | `boolean`           | _(optional)_ use `true` when you have several form elements. This way a `fieldset` with a `legend` is used. |
-| `disabled`                                                                                                       | `boolean`           | _(optional)_ set `true` to make the inner [FormLabel](/uilib/components/form-label/) behave as disabled.    |
-| `FieldProps` such as [Value.String-properties](/uilib/extensions/forms/create-component/Value/String/properties) | Various             | _(optional)_ `FieldProps` properties.                                                                       |
+| Property                                                                                                          | Type                | Description                                                                                                 |
+| ----------------------------------------------------------------------------------------------------------------- | ------------------- | ----------------------------------------------------------------------------------------------------------- |
+| `width`                                                                                                           | `string` or `false` | _(optional)_ `small`, `medium`, `large`, `stretch` or `false` for predefined standard widths.               |
+| `contentsWidth`                                                                                                   | `string` or `false` | _(optional)_ `small`, `medium`, `large`, `stretch` or `false` for predefined standard widths.               |
+| `size`                                                                                                            | `string` or `false` | _(optional)_ define one of the following [heading size](/uilib/elements/heading/): `medium` or `large`.     |
+| `asFieldset`                                                                                                      | `boolean`           | _(optional)_ use `true` when you have several form elements. This way a `fieldset` with a `legend` is used. |
+| `disabled`                                                                                                        | `boolean`           | _(optional)_ set `true` to make the inner [FormLabel](/uilib/components/form-label/) behave as disabled.    |
+| `FieldProps` such as [Value.String-properties](/uilib/extensions/forms/extended-features/Value/String/properties) | Various             | _(optional)_ `FieldProps` properties.                                                                       |
diff --git a/...tem-portal/src/docs/uilib/extensions/forms/create-component/ValueBlock/info.mdx b/...tem-portal/src/docs/uilib/extensions/forms/create-component/ValueBlock/info.mdx
@@ -6,7 +6,7 @@ import Demos from 'Docs/uilib/extensions/forms/create-component/ValueBlock/demos
 
 ## Description
 
-`ValueBlock` is a reusable wrapper component that can be used to easily create custom [Value-components](/uilib/extensions/forms/create-component/Value) that will display in the same way as other Value-components.
+`ValueBlock` is a reusable wrapper component that can be used to easily create custom [Value-components](/uilib/extensions/forms/extended-features/Value) that will display in the same way as other Value-components.
 
 ```jsx
 import { ValueBlock } from '@dnb/eufemia/extensions/forms'

diff --git a/.../dnb-design-system-portal/src/docs/uilib/extensions/forms/extended-features.mdx b/.../dnb-design-system-portal/src/docs/uilib/extensions/forms/extended-features.mdx
@@ -1,15 +1,13 @@
 ---
 title: 'Extended features'
-order: 3
+order: 4
 breadcrumb:
   - text: Forms
     href: /uilib/extensions/forms/
   - text: Extended features
     href: /uilib/extensions/forms/extended-features/
 ---
 
-import ListAdvancedAPIs from './extended-features/ListAdvancedAPIs'
-
 # Extended features
 
 Forms is a flexible set of building blocks for form functionality. Besides field components and data display, it consists of more complex functionality for surrounding processes such as data flow, validation and building UI.
@@ -35,6 +33,10 @@ render(
 
 `Forms.Handler` supports [JSON Schema](https://json-schema.org/) validation. JSON Schema is a flexible standard that makes it possible to describe the data's structure and validation needs, both for the individual value, and more complex rules across the data set. Descriptions and examples of such validation can be found [on a separate page](/uilib/extensions/forms/extended-features/Form/schema-validation).
 
+## [Data context](/uilib/extensions/forms/extended-features/DataContext/)
+
+`DataContext` builds a surrounding [React context](https://react.dev/learn/passing-data-deeply-with-context) that binds an entire source dataset together with the fields placed within. It enables fields and other components to retrieve data from the source data using `path` parameters that identify where in the source data the target value is located, and the same components will report changes to the data back so the context can update the dataset.
+
 ## [Steps layout](/uilib/extensions/forms/extended-features/StepsLayout)
 
 StepsLayout is a wrapper component for showing forms with a StepIndicator for navigation between several steps. It also includes components for navigating between steps.
@@ -52,6 +54,14 @@ render(
 )
 ```
 
-## Components
+## [Value](/uilib/extensions/forms/extended-features/Value/)
+
+Value components are in practice like a field component whose value cannot be changed. They can be displayed with or without a label, and they format the value based on given rules. They can also connect to the surrounding [DataContext](/uilib/extensions/forms/extended-features/DataContext/).
+
+## [Iterate](/uilib/extensions/forms/extended-features/Iterate/)
+
+`Iterate` is components and functionality for traversing values and parts of data sets such as arrays, which contain a varying number of elements where the number of components on the screen depends on how many elements the data consists of.
+
+## [Visibility](/uilib/extensions/forms/extended-features/Visibility/)
 
-<ListAdvancedAPIs />
+`Visibility` makes it possible to hide components and elements on the screen based on the dynamic state of data.
diff --git a/...ns/forms/create-component/DataContext.mdx → ...s/forms/extended-features/DataContext.mdx b/...ns/forms/create-component/DataContext.mdx → ...s/forms/extended-features/DataContext.mdx
@@ -1,23 +1,23 @@
 ---
 title: 'DataContext'
 description: '`DataContext` interweaves your data-set with your form fields.'
-componentType: 'basis-api'
+componentType: 'advanced-api'
 hideInMenu: true
 showTabs: false
 breadcrumb:
   - text: Forms
     href: /uilib/extensions/forms/
-  - text: Create your component
-    href: /uilib/extensions/forms/create-component/
+  - text: Extended features
+    href: /uilib/extensions/forms/extended-features/
   - text: DataContext
-    href: /uilib/extensions/forms/create-component/DataContext/
+    href: /uilib/extensions/forms/extended-features/DataContext/
 ---
 
 import ListDataContextComponents from './DataContext/ListDataContextComponents'
 
 # DataContext
 
-The `DataContext` interweaves your data-set with your form fields.
+`DataContext` builds a surrounding [React context](https://react.dev/learn/passing-data-deeply-with-context) that binds an entire source dataset together with the fields placed within. It enables fields and other components to retrieve data from the source data using `path` parameters that identify where in the source data the target value is located, and the same components will report changes to the data back so the context can update the dataset.
 
 Example of using the `DataContext.Provider`:
 
@@ -27,15 +27,15 @@ Example of using the `DataContext.Provider`:
 </DataContext.Provider>
 ```
 
-Please use [Form.Handler](/uilib/extensions/forms/extended-features/Form/Handler) for application forms.
+For a more complete feature set tailored to building forms, please use [Form.Handler](/uilib/extensions/forms/extended-features/Form/Handler). It uses DataContext internally.
 
 ## Components
 
 <ListDataContextComponents />
 
 ## More details
 
-If you don't want to repeat all the logic that drills down to values in the source data, and ensure that changes are sent to the right place, you can surround the components with a [DataContext.Provider](/uilib/extensions/forms/create-component/DataContext/Provider) component. This means that you feed the form with source data in one place, and give it only one `onChange` callback. Then you only send the individual fields instructions about where in the data set the value that field is to process is located. The components then communicate internally and ensure that the values are retrieved and sent to the correct location.
+If you don't want to repeat all the logic that drills down to values in the source data, and ensure that changes are sent to the right place, you can surround the components with a [DataContext.Provider](/uilib/extensions/forms/extended-features/DataContext/Provider) component. This means that you feed the form with source data in one place, and give it only one `onChange` callback. Then you only send the individual fields instructions about where in the data set the value that field is to process is located. The components then communicate internally and ensure that the values are retrieved and sent to the correct location.
 
 The reference to a specific field's value in the dataset is given with a prop called `path`. Paths are defined in a syntax called JSON Pointer, which is basically a slash-separated string that can go several levels, and consist of both object-properties and array indexes. Examples of paths are: `/firstName`, `/nested/path/to/value` and `/list/2/keyInThirdObject`. More information about JSON Pointers can be found on [the website of JSON Schema](https://json-schema.org/draft/2020-12/relative-json-pointer.html).
 

diff --git a/...forms/create-component/DataContext/At.mdx → ...orms/extended-features/DataContext/At.mdx b/...forms/create-component/DataContext/At.mdx → ...orms/extended-features/DataContext/At.mdx
@@ -13,16 +13,16 @@ tabs:
 breadcrumb:
   - text: Forms
     href: /uilib/extensions/forms/
-  - text: Create your component
-    href: /uilib/extensions/forms/create-component/
+  - text: Extended features
+    href: /uilib/extensions/forms/extended-features/
   - text: DataContext
-    href: /uilib/extensions/forms/create-component/DataContext/
+    href: /uilib/extensions/forms/extended-features/DataContext/
   - text: At
-    href: /uilib/extensions/forms/create-component/DataContext/At/
+    href: /uilib/extensions/forms/extended-features/DataContext/At/
 ---
 
-import Info from 'Docs/uilib/extensions/forms/create-component/DataContext/At/info'
-import Demos from 'Docs/uilib/extensions/forms/create-component/DataContext/At/demos'
+import Info from 'Docs/uilib/extensions/forms/extended-features/DataContext/At/info'
+import Demos from 'Docs/uilib/extensions/forms/extended-features/DataContext/At/demos'
 
 <Info />
 <Demos />
diff --git a/...ate-component/DataContext/At/Examples.tsx → ...nded-features/DataContext/At/Examples.tsx b/...ate-component/DataContext/At/Examples.tsx → ...nded-features/DataContext/At/Examples.tsx
diff --git a/...create-component/DataContext/At/demos.mdx → ...xtended-features/DataContext/At/demos.mdx b/...create-component/DataContext/At/demos.mdx → ...xtended-features/DataContext/At/demos.mdx
diff --git a/.../create-component/DataContext/At/info.mdx → ...extended-features/DataContext/At/info.mdx b/.../create-component/DataContext/At/info.mdx → ...extended-features/DataContext/At/info.mdx
diff --git a/...e-component/DataContext/At/properties.mdx → ...ed-features/DataContext/At/properties.mdx b/...e-component/DataContext/At/properties.mdx → ...ed-features/DataContext/At/properties.mdx
diff --git a/...ortal/src/docs/uilib/extensions/forms/extended-features/DataContext/Context.mdx b/...ortal/src/docs/uilib/extensions/forms/extended-features/DataContext/Context.mdx
@@ -0,0 +1,21 @@
+---
+title: 'Context'
+description: 'The context object used in `DataContext.Provider`.'
+showTabs: false
+hideInMenu: true
+breadcrumb:
+  - text: Forms
+    href: /uilib/extensions/forms/
+  - text: Extended features
+    href: /uilib/extensions/forms/extended-features/
+  - text: DataContext
+    href: /uilib/extensions/forms/extended-features/DataContext/
+  - text: Context
+    href: /uilib/extensions/forms/extended-features/DataContext/Context/
+---
+
+# DataContext.Context
+
+## Description
+
+The main context for [DataContext.Provider](/uilib/extensions/forms/extended-features/DataContext/Provider) which the [Field](/uilib/extensions/forms/base-fields/) and [Value](/uilib/extensions/forms/extended-features/Value/) components connect to (optional) for sources and callbacks when it is present. It can be used for creating custom components in similar ways.
diff --git a/...DataContext/ListDataContextComponents.tsx → ...DataContext/ListDataContextComponents.tsx b/...DataContext/ListDataContextComponents.tsx → ...DataContext/ListDataContextComponents.tsx
@@ -12,7 +12,7 @@ export default function ListDataContextComponents() {
           frontmatter: { title: { ne: null }, draft: { ne: true } }
           internal: {
             contentFilePath: {
-              glob: "**/uilib/extensions/forms/create-component/DataContext/**/*"
+              glob: "**/uilib/extensions/forms/extended-features/DataContext/**/*"
             }
           }
         }

diff --git a/...create-component/DataContext/Provider.mdx → ...xtended-features/DataContext/Provider.mdx b/...create-component/DataContext/Provider.mdx → ...xtended-features/DataContext/Provider.mdx
@@ -15,16 +15,16 @@ tabs:
 breadcrumb:
   - text: Forms
     href: /uilib/extensions/forms/
-  - text: Create your component
-    href: /uilib/extensions/forms/create-component/
+  - text: Extended features
+    href: /uilib/extensions/forms/extended-features/
   - text: DataContext
-    href: /uilib/extensions/forms/create-component/DataContext/
+    href: /uilib/extensions/forms/extended-features/DataContext/
   - text: Provider
-    href: /uilib/extensions/forms/create-component/DataContext/Provider/
+    href: /uilib/extensions/forms/extended-features/DataContext/Provider/
 ---
 
-import Info from 'Docs/uilib/extensions/forms/create-component/DataContext/Provider/info'
-import Demos from 'Docs/uilib/extensions/forms/create-component/DataContext/Provider/demos'
+import Info from 'Docs/uilib/extensions/forms/extended-features/DataContext/Provider/info'
+import Demos from 'Docs/uilib/extensions/forms/extended-features/DataContext/Provider/demos'
 
 <Info />
 <Demos />
diff --git a/...mponent/DataContext/Provider/Examples.tsx → ...eatures/DataContext/Provider/Examples.tsx b/...mponent/DataContext/Provider/Examples.tsx → ...eatures/DataContext/Provider/Examples.tsx
diff --git a/...-component/DataContext/Provider/demos.mdx → ...d-features/DataContext/Provider/demos.mdx b/...-component/DataContext/Provider/demos.mdx → ...d-features/DataContext/Provider/demos.mdx
diff --git a/...component/DataContext/Provider/events.mdx → ...-features/DataContext/Provider/events.mdx b/...component/DataContext/Provider/events.mdx → ...-features/DataContext/Provider/events.mdx
diff --git a/...e-component/DataContext/Provider/info.mdx → ...ed-features/DataContext/Provider/info.mdx b/...e-component/DataContext/Provider/info.mdx → ...ed-features/DataContext/Provider/info.mdx
@@ -6,4 +6,4 @@ showTabs: true
 
 `DataContext.Provider` is the context provider that has to wrap the features if components of Field and Value is to be used with a common source instead of distributing values and events individually.
 
-Please use [Form.Handler](/uilib/extensions/forms/extended-features/Form/Handler) for application forms.
+For a more complete feature set tailored to building forms, please use [Form.Handler](/uilib/extensions/forms/extended-features/Form/Handler). It uses DataContext internally.
diff --git a/...onent/DataContext/Provider/properties.mdx → ...tures/DataContext/Provider/properties.mdx b/...onent/DataContext/Provider/properties.mdx → ...tures/DataContext/Provider/properties.mdx
Original file line number	Diff line number	Diff line change
Expand Up		@@ -6,4 +6,4 @@ showTabs: true

		`Field.Boolean` is the base component for receiving user input where the target data is of type `boolean`.

		There is a corresponding [Value.Boolean](/uilib/extensions/forms/create-component/Value/Boolean) component.
		There is a corresponding [Value.Boolean](/uilib/extensions/forms/extended-features/Value/Boolean) component.
Original file line number	Diff line number	Diff line change
Expand Up		@@ -5,5 +5,3 @@ showTabs: true
		## Description

		`Field.Option` is a part for building selection inputs with Field.Select.

		There is a corresponding [Value.Option](/uilib/extensions/forms/create-component/Value/Option) component.
Original file line number	Diff line number	Diff line change
Expand Up		@@ -6,4 +6,4 @@ showTabs: true

		`DataContext.Provider` is the context provider that has to wrap the features if components of Field and Value is to be used with a common source instead of distributing values and events individually.

		Please use [Form.Handler](/uilib/extensions/forms/extended-features/Form/Handler) for application forms.
		For a more complete feature set tailored to building forms, please use [Form.Handler](/uilib/extensions/forms/extended-features/Form/Handler). It uses DataContext internally.