Docs(web-react): Improve additional API options info #DS-1099

Also unify links.
lmc-eu · Feb 6, 2024 · 417f89a · 417f89a
1 parent c0515b5
commit 417f89a
Show file tree

Hide file tree

Showing 35 changed files with 887 additions and 570 deletions.
diff --git a/packages/web-react/README.md b/packages/web-react/README.md
@@ -54,6 +54,26 @@ import { ClassNamePrefixProvider } from '@lmc-eu/spirit-web-react/context/ClassN
 </ClassNamePrefixProvider>;
 ```
 
+## Additional Attributes
+
+All components accept additional attributes that are passed down to the root element of the component.
+This is useful for adding custom event handlers, accessibility attributes, or other attributes that
+are not supported by the component API.
+
+ℹ️ If you need to pass down event handlers to the native form elements in our form components,
+you can use the `inputProps` prop.
+
+Supported attributes are:
+
+- `on*` (eg. `onclick`)
+- `data-*`
+- `aria-*`
+- `id`
+
+If the component sets a value for any of these attributes, the value passed in will be overwritten.
+
+Most components also accept native HTML attributes based on the component's element type.
+
 ## Styling
 
 Spirit components are designed to be consistent across all LMC applications. They include built-in styling that has been

diff --git a/packages/web-react/src/components/Accordion/README.md b/packages/web-react/src/components/Accordion/README.md
@@ -136,54 +136,68 @@ import { AccordionOpenStateType } from '@lmc-eu/spirit-web-react/types';
 
 ## Accordion Props
 
-| Name               | Type                              | Default   | Required | Description                                      |
-| ------------------ | --------------------------------- | --------- | -------- | ------------------------------------------------ |
-| `children`         | `ReactNode`                       | —         | ✔        | Accordion children's nodes                       |
-| `elementType`      | [`section` \| `article` \| `div`] | `section` | ✕        | Type of element used as wrapper                  |
-| `open`             | [`string` \| `string[]`]          | —         | ✕        | Open item or list of open items \*               |
-| `toggle`           | `(id: string) => void`            | —         | ✕        | A generic handler for a single **AccordionItem** |
-| `UNSAFE_className` | `string`                          | —         | ✕        | Wrapper custom class name                        |
-| `UNSAFE_style`     | `CSSProperties`                   | —         | ✕        | Wrapper custom style                             |
+| Name          | Type                              | Default   | Required | Description                                      |
+| ------------- | --------------------------------- | --------- | -------- | ------------------------------------------------ |
+| `children`    | `ReactNode`                       | —         | ✔        | Accordion children's nodes                       |
+| `elementType` | [`section` \| `article` \| `div`] | `section` | ✕        | Type of element used as wrapper                  |
+| `open`        | [`string` \| `string[]`]          | —         | ✕        | Open item or list of open items \*               |
+| `toggle`      | `(id: string) => void`            | —         | ✕        | A generic handler for a single **AccordionItem** |
 
 (\*) Depending on the type of default value, what is set as the default will affect whether one or more will be open at the same time.
 
+On top of the API options, the components accept [additional attributes][readme-additional-attributes].
+If you need more control over the styling of a component, you can use [style props][readme-style-props]
+and [escape hatches][readme-escape-hatches].
+
 ## Uncontrolled Accordion Props
 
-| Name               | Type                              | Default   | Required | Description                                    |
-| ------------------ | --------------------------------- | --------- | -------- | ---------------------------------------------- |
-| `children`         | `ReactNode`                       | —         | ✔        | Accordion children's nodes                     |
-| `defaultOpen`      | [`string` \| `string[]`]          | —         | ✕        | Default open item(s) \*                        |
-| `elementType`      | [`section` \| `article` \| `div`] | `section` | ✕        | Type of element used as wrapper                |
-| `stayOpen`         | `bool`                            | —         | ✕        | Item stay open when another one is also opened |
-| `UNSAFE_className` | `string`                          | —         | ✕        | Wrapper custom class name                      |
-| `UNSAFE_style`     | `CSSProperties`                   | —         | ✕        | Wrapper custom style                           |
+| Name          | Type                              | Default   | Required | Description                                    |
+| ------------- | --------------------------------- | --------- | -------- | ---------------------------------------------- |
+| `children`    | `ReactNode`                       | —         | ✔        | Accordion children's nodes                     |
+| `defaultOpen` | [`string` \| `string[]`]          | —         | ✕        | Default open item(s) \*                        |
+| `elementType` | [`section` \| `article` \| `div`] | `section` | ✕        | Type of element used as wrapper                |
+| `stayOpen`    | `bool`                            | —         | ✕        | Item stay open when another one is also opened |
 
 (\*) If this attribute is an array, then the `stayOpen` parameter should also be set.
 
+On top of the API options, the components accept [additional attributes][readme-additional-attributes].
+If you need more control over the styling of a component, you can use [style props][readme-style-props]
+and [escape hatches][readme-escape-hatches].
+
 ## AccordionItem Props
 
-| Name               | Type                              | Default   | Required | Description                                     |
-| ------------------ | --------------------------------- | --------- | -------- | ----------------------------------------------- |
-| `children`         | `ReactNode`                       | —         | ✔        | Item children node                              |
-| `elementType`      | [`article` \| `section` \| `div`] | `article` | ✕        | Type of element used as wrapper for single item |
-| `id`               | `string`                          | —         | ✔        | Item id                                         |
-| `UNSAFE_className` | `string`                          | —         | ✕        | Item custom class name                          |
-| `UNSAFE_style`     | `CSSProperties`                   | —         | ✕        | Item custom style                               |
+| Name          | Type                              | Default   | Required | Description                                     |
+| ------------- | --------------------------------- | --------- | -------- | ----------------------------------------------- |
+| `children`    | `ReactNode`                       | —         | ✔        | Item children node                              |
+| `elementType` | [`article` \| `section` \| `div`] | `article` | ✕        | Type of element used as wrapper for single item |
+| `id`          | `string`                          | —         | ✔        | Item id                                         |
+
+On top of the API options, the components accept [additional attributes][readme-additional-attributes].
+If you need more control over the styling of a component, you can use [style props][readme-style-props]
+and [escape hatches][readme-escape-hatches].
 
 ## AccordionHeader Props
 
-| Name               | Type            | Default | Required | Description              |
-| ------------------ | --------------- | ------- | -------- | ------------------------ |
-| `children`         | `ReactNode`     | —       | ✔        | Header children node     |
-| `elementType`      | `ElementType`   | `h3`    | ✕        | Type of element          |
-| `slot`             | `ReactNode`     | —       | ✕        | Side slot in the header  |
-| `UNSAFE_className` | `string`        | —       | ✕        | Header custom class name |
-| `UNSAFE_style`     | `CSSProperties` | —       | ✕        | Header custom style      |
+| Name          | Type          | Default | Required | Description             |
+| ------------- | ------------- | ------- | -------- | ----------------------- |
+| `children`    | `ReactNode`   | —       | ✔        | Header children node    |
+| `elementType` | `ElementType` | `h3`    | ✕        | Type of element         |
+| `slot`        | `ReactNode`   | —       | ✕        | Side slot in the header |
+
+On top of the API options, the components accept [additional attributes][readme-additional-attributes].
+If you need more control over the styling of a component, you can use [style props][readme-style-props]
+and [escape hatches][readme-escape-hatches].
 
 ## AccordionContent Props
 
-| Name               | Type            | Default | Required | Description               |
-| ------------------ | --------------- | ------- | -------- | ------------------------- |
-| `children`         | `ReactNode`     | —       | ✔        | Content children node     |
-| `UNSAFE_className` | `string`        | —       | ✕        | Content custom class name |
-| `UNSAFE_style`     | `CSSProperties` | —       | ✕        | Content custom style      |
+| Name       | Type        | Default | Required | Description           |
+| ---------- | ----------- | ------- | -------- | --------------------- |
+| `children` | `ReactNode` | —       | ✔        | Content children node |
+
+On top of the API options, the components accept [additional attributes][readme-additional-attributes].
+If you need more control over the styling of a component, you can use [style props][readme-style-props]
+and [escape hatches][readme-escape-hatches].
+
+[readme-additional-attributes]: https://github.com/lmc-eu/spirit-design-system/blob/main/packages/web-react/README.md#additional-attributes
+[readme-escape-hatches]: https://github.com/lmc-eu/spirit-design-system/blob/main/packages/web-react/README.md#escape-hatches
+[readme-style-props]: https://github.com/lmc-eu/spirit-design-system/blob/main/packages/web-react/README.md#style-props
diff --git a/packages/web-react/src/components/Alert/README.md b/packages/web-react/src/components/Alert/README.md
@@ -27,21 +27,26 @@ import { Alert } from '@lmc-eu/spirit-web-react/components';
 
 ## API
 
-| Name               | Type                                         | Default   | Required | Description                |
-| ------------------ | -------------------------------------------- | --------- | -------- | -------------------------- |
-| `children`         | `ReactNode`                                  | —         | ✔        | Content of the Alert       |
-| `color`            | [Emotion Color dictionary][dictionary-color] | `success` | ✕        | Color of the component     |
-| `iconName`         | `string`                                     | `info` \* | ✕        | Icon used in Alert         |
-| `isCentered` .     | `bool`                                       | `false`   | ✕        | If true, Alert is centered |
-| `UNSAFE_className` | `string`                                     | —         | ✕        | Wrapper custom class name  |
-| `UNSAFE_style`     | `CSSProperties`                              | —         | ✕        | Wrapper custom style       |
+| Name           | Type                                         | Default   | Required | Description                |
+| -------------- | -------------------------------------------- | --------- | -------- | -------------------------- |
+| `children`     | `ReactNode`                                  | —         | ✔        | Content of the Alert       |
+| `color`        | [Emotion Color dictionary][dictionary-color] | `success` | ✕        | Color of the component     |
+| `iconName`     | `string`                                     | `info` \* | ✕        | Icon used in Alert         |
+| `isCentered` . | `bool`                                       | `false`   | ✕        | If true, Alert is centered |
 
 (\*) For each emotion color, a default icon is defined.
-The icons come from the [Icon package], or from your custom source of icons.
+The icons come from the [Icon package][icon-package], or from your custom source of icons.
 Read the section [Default Icons according to Color Variant](#default-icons-according-to-color-variant).
 
-For detailed information see [Alert] component
+On top of the API options, the components accept [additional attributes][readme-additional-attributes].
+If you need more control over the styling of a component, you can use [style props][readme-style-props]
+and [escape hatches][readme-escape-hatches].
+
+For detailed information see [Alert][alert] component.
 
 [alert]: https://github.com/lmc-eu/spirit-design-system/blob/main/packages/web/src/scss/components/Alert/README.md
 [dictionary-color]: https://github.com/lmc-eu/spirit-design-system/tree/main/docs/DICTIONARIES.md#color
-[icon package]: https://github.com/lmc-eu/spirit-design-system/tree/main/packages/icons
+[icon-package]: https://github.com/lmc-eu/spirit-design-system/tree/main/packages/icons
+[readme-additional-attributes]: https://github.com/lmc-eu/spirit-design-system/blob/main/packages/web-react/README.md#additional-attributes
+[readme-escape-hatches]: https://github.com/lmc-eu/spirit-design-system/blob/main/packages/web-react/README.md#escape-hatches
+[readme-style-props]: https://github.com/lmc-eu/spirit-design-system/blob/main/packages/web-react/README.md#style-props