From 4c38f4b82a895fe01f4508e88b5b8b5db4f93963 Mon Sep 17 00:00:00 2001 From: Quentin Le Caignec <12102823+QuentinLeCaignec@users.noreply.github.com> Date: Mon, 9 Sep 2024 14:26:59 +0200 Subject: [PATCH] feat: added DynamicZone docs (#26) * feat: added DynamicZone docs --- docs/haring-react/components/action-list.mdx | 2 +- ...dx => address-gouv-autocomplete-field.mdx} | 8 +- docs/haring-react/form/dynamic-zone.mdx | 114 ++++++++++++++++++ ...Field.mdx => fetch-autocomplete-field.mdx} | 16 +-- docs/shared-types/utility.md | 3 + 5 files changed, 129 insertions(+), 14 deletions(-) rename docs/haring-react/form/{AddressGouvAutocompleteField.mdx => address-gouv-autocomplete-field.mdx} (93%) create mode 100644 docs/haring-react/form/dynamic-zone.mdx rename docs/haring-react/form/{FetchAutocompleteField.mdx => fetch-autocomplete-field.mdx} (81%) create mode 100644 docs/shared-types/utility.md diff --git a/docs/haring-react/components/action-list.mdx b/docs/haring-react/components/action-list.mdx index 42b2bae..c401bab 100644 --- a/docs/haring-react/components/action-list.mdx +++ b/docs/haring-react/components/action-list.mdx @@ -40,5 +40,5 @@ ActionBar takes a `` generic type that extends `Record`. | overflowMenuLabel | `string` | `"Other actions"` | | String used as both the `aria-label` and the Tooltip label of the menu button/icon | | rowActionNumber | `number` | `1` | Index value used to determine which actions will be displayed directly in the action column (before this index) or in the action menu (starting at this index) | -| selectedElements | `Data[]` | - | Array of currently selected elements, necessary for the `actions` to be able to pass those elements along | +| selectedElements | `Data \| Data[]` | - | Array of currently selected elements, necessary for the `actions` to be able to pass those elements along | | ... | - | - | extends [Group props](https://v6.mantine.dev/core/group/?t=props) | diff --git a/docs/haring-react/form/AddressGouvAutocompleteField.mdx b/docs/haring-react/form/address-gouv-autocomplete-field.mdx similarity index 93% rename from docs/haring-react/form/AddressGouvAutocompleteField.mdx rename to docs/haring-react/form/address-gouv-autocomplete-field.mdx index 58f50e9..43d84bc 100644 --- a/docs/haring-react/form/AddressGouvAutocompleteField.mdx +++ b/docs/haring-react/form/address-gouv-autocomplete-field.mdx @@ -1,4 +1,4 @@ -# Address gouv autocomplete field +# Address Gouv Autocomplete Field An autocomplete field which is a [`FetchAutocompleteField - Props`](./FetchAutocompleteField) component configured for the + Props`](./fetch-autocomplete-field) component configured for the [`api-Adresse.data.gouv`](https://adresse.data.gouv.fr/). @@ -36,12 +36,10 @@ | lon | `string` | `''` | To be filled in to prioritize these longitude coordinates in the search results. | | type | `string` | `''` | To be filled in to reduce to specific type of results of the search. | | onFetchData | `(value: string) => Promise[]>` | `A default function getDataAddressGouv that makes a call to the api-adresse.gouv.fr API.` | This callback function return field value to the parameters and to be return `Promise[]>` value. By default this props is defined. | -| ... | - | - | extends [`FetchAutocompleteField Props`](./FetchAutocompleteField/#props) | +| ... | - | - | extends [`FetchAutocompleteField Props`](./fetch-autocomplete-field/#props) | ## IAddressGouvData -IAddressGouvData contain `properties` object with thats types: - | name | type | Description | | ----------- | -------- | ---------------------- | | city | `string` | Name of the city | diff --git a/docs/haring-react/form/dynamic-zone.mdx b/docs/haring-react/form/dynamic-zone.mdx new file mode 100644 index 0000000..e3b731c --- /dev/null +++ b/docs/haring-react/form/dynamic-zone.mdx @@ -0,0 +1,114 @@ +# Dynamic Zone + + + Controlled container that displays a dynamic zone. + +Buttons at the bottom can be clicked to add new blocks into the zone, each block is displayed in the zone with header, footer, actions and the content is rendered through a render function provided by the parent component + + + +## Storybook Docs + + + +## Props + +DynamicZone takes a `` generic type that extends `IBaseBlock`. + +| Name | Type | Default | Description | +| -------------------------------- | ------------------------------------------------------------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------- | +| blockOptions | [`IBaseBlockButton`](#ibaseblockbutton)`[]` | - | Array of `IBaseBlockButton`, displays as buttons to add blocks at the bottom of the zone | +| blocks | `Block[]` | - | Array of `Block`, displays as list of [`DynamicZoneBlock`](#dynamic-zone-block) | +| onAppendBlock | `(blockType: string) => void` | - | Callback function called when a block button is clicked to append a new block | +| onRenderBlockContent | `(block: Block, index: number) => ReactElement` | - | Callback function called when a block is being rendered in the list, parent needs to return the rendered content | +| onToggleBlock | `(block: Block, index: number, opened: boolean) => void` | - | Callback function called when a block's toggle button is clicked to open/close it | +| blockCardProps | [`CardProps`](https://mantine.dev/core/card/?t=props) | - | Extra props for the internal [Card](https://mantine.dev/core/card/) component, root of [`DynamicZoneBlock`](#dynamic-zone-block) | +| blocksStackProps | [`StackProps`](https://mantine.dev/core/stack/?t=props) | - | Extra props for the internal [Stack](https://mantine.dev/core/stack/) component, child of the root Container | +| bottomContainerProps | [`ContainerProps`](https://mantine.dev/core/container/?t=props) | - | Extra props for the internal [Container](https://mantine.dev/core/container/) component, child of the root Container | +| buttonsGroupProps | [`GroupProps`](https://mantine.dev/core/group/?t=props) | - | Extra props for the internal [Group](https://mantine.dev/core/group/) component, container of the button area | +| buttonsText | `string` | - | Content of button area's optional header, inside a [Text](https://mantine.dev/core/text/) component | +| buttonsTextProps | [`TextProps`](https://mantine.dev/core/text/?t=props) | - | Extra props for the internal [Text](https://mantine.dev/core/text/) component, container of the button area's optional header | +| internalBlockCardProps | [`IDynamicZoneBlockInternalComponentProps`](#idynamiczoneblockinternalcomponentprops) | - | Extra internal component props passed to [`DynamicZoneBlock`](#dynamic-zone-block) | +| ... | - | - | extends [`Container Props`](https://mantine.dev/core/container/?t=props), root container | + +## `IBaseBlock` + +| Name | Type | Default | Description | +| ----------------------- | ------------------------------------------------------------------------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------ | +| id | `string` | - | Used internally as keys and for other reasons, should be unique and not be modified once set | +| opened | `boolean` | - | Controlled value that determines if the block is opened or not | +| blockType | `string` | - | Type of the block being rendered, sent back to parent for render, used as a kind of block type ID here and in IBaseBlockButton | +| blockHeader | `ReactNode` | - | Content of the block header | +| blockFooter | `ReactNode` | - | Content of the block footer | +| blockActions | [`IAction`](../../shared-types/actions#iactiont)`<`[`IDynamicZoneBlockReference`](#idynamiczoneblockreference)`>[]` | - | Action(s) displayed to the right of the block header | + +## `IBaseBlockButton` + +| Name | Type | Default | Description | +| --------------------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------ | +| blockType | `string` | - | Type of the block being rendered, sent back to parent for render, used as a kind of block type ID here and in IBaseBlock | +| label | `string` | - | Label of button to add a new block | + +--- + +## Dynamic Zone Block + +Sub-component that renders one block with header, content and footer. + +### Props + +| Name | Type | Default | Description | +| -------------------------- | ------------------------------------------------------------------------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| children | `ReactNode` | - | Main content of block | +| headerChildren | `ReactNode` | - | Content of header | +| onToggle | `(opened: boolean) => void` | - | Callback function called when opening/close button is clicked | +| opened | `boolean` | - | Controlled value the determines if the block's [Collapse](https://mantine.dev/core/collapse/) is open or closed | +| reference | [`IDynamicZoneBlockReference`](#idynamiczoneblockreference) | - | Object used internally and sent back to parent in callbacks, declares a block's `id`, `index` and the total `arrayLength` of blocks | +| actions | [`IAction`](../../shared-types/actions#iactiont)`<`[`IDynamicZoneBlockReference`](#idynamiczoneblockreference)`>[]` | - | Array of [`IAction`](../../shared-types/actions#iactiont) using [`IDynamicZoneBlockReference`](#idynamiczoneblockreference) as `T`, displayed to the right of the header | +| footerChildren | `ReactNode` | - | Optional content of footer | +| internalComponentProps | [`IDynamicZoneBlockInternalComponentProps`](#idynamiczoneblockinternalcomponentprops) | - | Group of extra internal component props | +| ... | - | - | extends [`Card Props`](https://mantine.dev/core/card/?t=props) | + +### `IDynamicZoneBlockReference` + +| Name | Type | Default | Description | +| ----------------------- | -------- | ------- | ------------------------------------------------- | +| arrayLength | `number` | - | Total length of parent's `blocks` array | +| id | `string` | - | ID of the block | +| index | `number` | - | Index of the block in the parent's `blocks` array | +| ... | - | - | extends `Record` | + +### `IDynamicZoneBlockInternalComponentProps` + +| Name | Type | Default | Description | +| ---------------------- | ---------------------------------------------------------------------------------------------------------------------- | ------- | --------------------------------------------------------------------------------------------------- | +| contentCollapseProps | [`CollapseProps`](https://mantine.dev/core/collapse/?t=props) | - | Extra props for the internal [Collapse](https://mantine.dev/core/collapse) component | +| contentContainerProps | [`ContainerProps`](https://mantine.dev/core/container/?t=props) | - | Extra props for the internal [Container](https://mantine.dev/core/container) component | +| footerCardSectionProps | [`CardSectionProps`](https://mantine.dev/core/card/#cardsection) | - | Extra props for the internal [CardSection](https://mantine.dev/core/card/#cardsection) component | +| headerActionListProps | [`IActionListProps`](../components/action-list#props)`<`[`IDynamicZoneBlockReference`](#idynamiczoneblockreference)`>` | - | Extra props for the internal [ActionList](../components/action-list) component | +| headerCardSectionProps | [`CardSectionProps`](https://mantine.dev/core/card/#cardsection) | - | Extra props for the internal [CardSection](https://mantine.dev/core/card/#cardsection) component | +| headerGroupProps | [`GroupProps`](https://mantine.dev/core/group/?t=props) | - | Extra props for the internal [Group](https://mantine.dev/core/group) component | +| toggleComponentProps | [`IDynamicZoneBlockToggleProps`](#idynamiczoneblocktoggleprops) | - | Extra props passed to the internal [ActionIcon](https://mantine.dev/core/action-icon) toggle button | + +### `IDynamicZoneBlockToggleProps` + +| Name | Type | Default | Description | +| --------------- | ------------------------------------------------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------- | +| actionIconProps | [`ActionIconProps`](https://mantine.dev/core/action-icon/?t=props) | - | Extra props for the internal [ActionIcon](https://mantine.dev/core/action-icon) component used as the toggle button | +| downIcon | `ReactNode` | - | Content of toggle button in down state | +| upIcon | `ReactNode` | - | Content of toggle button in up state | diff --git a/docs/haring-react/form/FetchAutocompleteField.mdx b/docs/haring-react/form/fetch-autocomplete-field.mdx similarity index 81% rename from docs/haring-react/form/FetchAutocompleteField.mdx rename to docs/haring-react/form/fetch-autocomplete-field.mdx index ce3448e..d608d5e 100644 --- a/docs/haring-react/form/FetchAutocompleteField.mdx +++ b/docs/haring-react/form/fetch-autocomplete-field.mdx @@ -42,14 +42,14 @@ ## IFetchOption -| Name | Type | Default | Description | -| ---------------- | -------- | ------- | --------------- | -| Key | `string` | - | Key of option | -| Value | `string` | - | Value of option | +| Name | Type | Default | Description | +| ----------------- | -------- | ------- | --------------- | +| key | `string` | - | Key of option | +| value | `string` | - | Value of option | ## IValue`` -| Name | Type | Default | Description | -| ---------------- | -------- | ------- | ------------------------------------------------------------------------------------ | -| label | `string` | - | Label displayed on options list and returned by the onFetchData function | -| Value | `T` | - | The request data part corresponding to the selected option associated with the label | +| Name | Type | Default | Description | +| ----------------- | -------- | ------- | ------------------------------------------------------------------------------------ | +| label | `string` | - | Label displayed on options list and returned by the onFetchData function | +| Value | `T` | - | The request data part corresponding to the selected option associated with the label | diff --git a/docs/shared-types/utility.md b/docs/shared-types/utility.md new file mode 100644 index 0000000..2d8bfcb --- /dev/null +++ b/docs/shared-types/utility.md @@ -0,0 +1,3 @@ +# `IOmitRespectIndexSignature` + +Utility type that is equivalent to Typescript's `` but respects index signatures, such as in a common use-case of string indexes where using `` will aggressively merge some types and remove the correct type-detection on some fields.