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

Also unify links.

packages/web-twig/README.md

@@ -78,6 +78,24 @@ For available components see the [components directory](https://github.com/lmc-e
 if you want to extend these components, an example guide is [here](./docs/extendComponents.md).
 if you want to contribute, read the guide [here](./CONTRIBUTING.md).
 
+## 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.
+
 ## Styling
 
 Spirit components are designed to be consistent across all LMC applications. They include built-in styling that has been

packages/web-twig/src/Resources/components/Accordion/README.md

@@ -1,6 +1,6 @@
 # Accordion
 
-This is Twig implementation of the [Accordion] component.
+This is Twig implementation of the [Accordion][accordion] component.
 
 ## Default usage (Stay open)
 
@@ -214,10 +214,9 @@ The Accordion itself consists of several components which cannot be used indepen
 | `labelledById` | `string` | `null`  | ✔        | AccordionHeader ID                                                          |
 | `parent`       | `string` | `null`  | ✕        | A parent element selector that ensures that only one item is open at a time |
 
-On top of the API options, you can add `data-*` or `aria-*` attributes to
-further extend component's descriptiveness and accessibility. Also, UNSAFE styling props are available,
-see the [Escape hatches][escape-hatches] section in README to learn how and when to use them.
-These attributes will be passed to the topmost HTML element of the 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].
 
 ## JavaScript Plugin
 
@@ -233,7 +232,9 @@ Or, feel free to write the controlling script yourself.
 
 👉 Check the [component's docs in the web package][web-js-api] to see the full documentation and API of the plugin.
 
+[accordion]: https://github.com/lmc-eu/spirit-design-system/tree/main/packages/web/src/scss/components/Accordion
+[readme-additional-attributes]: https://github.com/lmc-eu/spirit-design-system/blob/main/packages/web-twig/README.md#additional-attributes
+[readme-style-props]: https://github.com/lmc-eu/spirit-design-system/blob/main/packages/web-twig/README.md#style-props
+[readme-escape-hatches]: https://github.com/lmc-eu/spirit-design-system/blob/main/packages/web-twig/README.md#escape-hatches
 [web-js-api]: https://github.com/lmc-eu/spirit-design-system/blob/main/packages/web/src/scss/components/Accordion/README.md#javascript-plugin
 [web-readme]: https://github.com/lmc-eu/spirit-design-system/blob/main/packages/web/README.md
-[accordion]: https://github.com/lmc-eu/spirit-design-system/tree/main/packages/web/src/scss/components/Accordion
-[escape-hatches]: https://github.com/lmc-eu/spirit-design-system/tree/main/packages/web-twig/README.md#escape-hatches

packages/web-twig/src/Resources/components/Alert/README.md

@@ -1,6 +1,6 @@
 # Alert
 
-This is Twig implementation of the [Alert] component.
+This is Twig implementation of the [Alert][alert] component.
 
 Basic example usage:
 
@@ -47,14 +47,16 @@ Without lexer:
 | `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).
 
-You can add `id`, `data-*` or `aria-*` attributes to further extend the component's
-descriptiveness and accessibility. Also, UNSAFE styling props are available,
-see the [Escape hatches][escape-hatches] section in README to learn how and when to use them.
+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].
 
 [alert]: https://github.com/lmc-eu/spirit-design-system/tree/main/packages/web/src/scss/components/Alert
 [dictionary-color]: https://github.com/lmc-eu/spirit-design-system/tree/main/docs/DICTIONARIES.md#color
-[escape-hatches]: https://github.com/lmc-eu/spirit-design-system/tree/main/packages/web-twig/README.md#escape-hatches
-[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-twig/README.md#additional-attributes
+[readme-style-props]: https://github.com/lmc-eu/spirit-design-system/blob/main/packages/web-twig/README.md#style-props
+[readme-escape-hatches]: https://github.com/lmc-eu/spirit-design-system/blob/main/packages/web-twig/README.md#escape-hatches

packages/web-twig/src/Resources/components/Breadcrumbs/README.md

@@ -1,6 +1,6 @@
 # Breadcrumbs
 
-This is the Twig implementation of the [Breadcrumbs] component.
+This is the Twig implementation of the [Breadcrumbs][breadcrumbs] component.
 
 Basic example usage:
 
@@ -101,9 +101,9 @@ content can be overridden by any custom block content.
 | `goBackTitle` | `string` | —       | ✕        | Title/translation for back link to previous page on mobile. It's essential to be set along with items. If items property is not passed, backlink is to be created within children property. [**Optional DEPRECATED**][deprecated] Will be **required** in the next major version. |
 | `items`       | `array`  | `[]`    | ✕        | Navigation menu items                                                                                                                                                                                                                                                             |
 
-You can add `id`, `data-*` or `aria-*` attributes to further extend the component's
-descriptiveness and accessibility. Also, UNSAFE styling props are available,
-see the [Escape hatches][escape-hatches] section in README to learn how and when to use them.
+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].
 
 ## BreadcrumbsItem
 
@@ -133,9 +133,9 @@ Use the `BreadcrumbsItem` component for the ordered list as the component's chil
 
 (\*) Optional only for the current page.
 
-You can add `id`, `data-*` or `aria-*` attributes to further extend the component's
-descriptiveness and accessibility. Also, UNSAFE styling props are available,
-see the [Escape hatches][escape-hatches] section in README to learn how and when to use them.
+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].
 
 ### Dealing with long titles
 
@@ -151,5 +151,7 @@ Additional option is to use helper class `text-truncate` with defined width.
 
 [breadcrumbs]: https://github.com/lmc-eu/spirit-design-system/tree/main/packages/web/src/scss/components/Breadcrumbs
 [deprecated]: https://github.com/lmc-eu/spirit-design-system/tree/main/packages/web-twig/README.md#deprecations
-[escape-hatches]: https://github.com/lmc-eu/spirit-design-system/tree/main/packages/web-twig/README.md#escape-hatches
+[readme-additional-attributes]: https://github.com/lmc-eu/spirit-design-system/blob/main/packages/web-twig/README.md#additional-attributes
+[readme-style-props]: https://github.com/lmc-eu/spirit-design-system/blob/main/packages/web-twig/README.md#style-props
+[readme-escape-hatches]: https://github.com/lmc-eu/spirit-design-system/blob/main/packages/web-twig/README.md#escape-hatches
 [twig-truncate]: https://twig.symfony.com/doc/3.x/filters/u.html

packages/web-twig/src/Resources/components/Button/README.md

@@ -1,6 +1,6 @@
 # Button
 
-This is Twig implementation of the [Button] component.
+This is Twig implementation of the [Button][button] component.
 
 Basic example usage:
 
@@ -46,11 +46,13 @@ Without lexer:
 | `size`       | [Size dictionary][dictionary-size]                                                        | `medium`  | ✕        | Size variant                                                               |
 | `type`       | `string`                                                                                  | `button`  | ✕        | Type of the Button                                                         |
 
-You can add `id`, `data-*` or `aria-*` attributes to further extend component's
-descriptiveness and accessibility. Also, UNSAFE styling props are available,
-see the [Escape hatches][escape-hatches] section in README to learn how and when to use them.
+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].
 
 [button]: https://github.com/lmc-eu/spirit-design-system/tree/main/packages/web/src/scss/components/Button
 [dictionary-color]: https://github.com/lmc-eu/spirit-design-system/tree/main/docs/DICTIONARIES.md#color
 [dictionary-size]: https://github.com/lmc-eu/spirit-design-system/tree/main/docs/DICTIONARIES.md#size
-[escape-hatches]: https://github.com/lmc-eu/spirit-design-system/tree/main/packages/web-twig/README.md#escape-hatches
+[readme-additional-attributes]: https://github.com/lmc-eu/spirit-design-system/blob/main/packages/web-twig/README.md#additional-attributes
+[readme-style-props]: https://github.com/lmc-eu/spirit-design-system/blob/main/packages/web-twig/README.md#style-props
+[readme-escape-hatches]: https://github.com/lmc-eu/spirit-design-system/blob/main/packages/web-twig/README.md#escape-hatches

packages/web-twig/src/Resources/components/ButtonLink/README.md

@@ -1,6 +1,6 @@
 # ButtonLink
 
-This is Twig implementation of the [ButtonLink] component.
+This is Twig implementation of the [ButtonLink][button] component.
 
 Basic example usage:
 
@@ -41,11 +41,13 @@ Without lexer:
 | `target`     | `string`                                                                                  | `null`    | ✕        | Browsing context for the link                                                  |
 | `title`      | `string`                                                                                  | `null`    | ✕        | Optional title to display on hover                                             |
 
-You can add `id`, `data-*` or `aria-*` attributes to further extend component's
-descriptiveness and accessibility. Also, UNSAFE styling props are available,
-see the [Escape hatches][escape-hatches] section in README to learn how and when to use them.
+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].
 
-[buttonLink]: https://github.com/lmc-eu/spirit-design-system/tree/main/packages/web/src/scss/components/Button
+[button]: https://github.com/lmc-eu/spirit-design-system/tree/main/packages/web/src/scss/components/Button
 [dictionary-color]: https://github.com/lmc-eu/spirit-design-system/tree/main/docs/DICTIONARIES.md#color
 [dictionary-size]: https://github.com/lmc-eu/spirit-design-system/tree/main/docs/DICTIONARIES.md#size
-[escape-hatches]: https://github.com/lmc-eu/spirit-design-system/tree/main/packages/web-twig/README.md#escape-hatches
+[readme-additional-attributes]: https://github.com/lmc-eu/spirit-design-system/blob/main/packages/web-twig/README.md#additional-attributes
+[readme-style-props]: https://github.com/lmc-eu/spirit-design-system/blob/main/packages/web-twig/README.md#style-props
+[readme-escape-hatches]: https://github.com/lmc-eu/spirit-design-system/blob/main/packages/web-twig/README.md#escape-hatches

packages/web-twig/src/Resources/components/Checkbox/README.md

@@ -1,6 +1,6 @@
 # Checkbox
 
-This is Twig implementation of the [Checkbox] component.
+This is Twig implementation of the [Checkbox][checkbox] component.
 
 Basic example usage:
 
@@ -61,13 +61,14 @@ Without lexer:
 (\*) Label is required. You can use the `label` for simple text or `UNSAFE_label` for HTML content.
 (\*\*) Props with and without `UNSAFE_` prefix are mutually exclusive.
 
-On top of the API options, you can add `data-*` or `aria-*` attributes to
-further extend component's descriptiveness and accessibility. Also, UNSAFE styling props are available,
-see the [Escape hatches][escape-hatches] section in README to learn how and when to use them.
-These attributes will be passed to the topmost HTML element of the 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].
 
+[autocomplete-attr]: https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/autocomplete
 [checkbox]: https://github.com/lmc-eu/spirit-design-system/tree/main/packages/web/src/scss/components/Checkbox
-[item]: https://github.com/lmc-eu/spirit-design-system/blob/main/packages/web-twig/src/Resources/components/Item/README.md
 [dictionary-validation]: https://github.com/lmc-eu/spirit-design-system/blob/main/docs/DICTIONARIES.md#validation
-[escape-hatches]: https://github.com/lmc-eu/spirit-design-system/tree/main/packages/web-twig/README.md#escape-hatches
-[autocomplete-attr]: https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/autocomplete
+[item]: https://github.com/lmc-eu/spirit-design-system/blob/main/packages/web-twig/src/Resources/components/Item/README.md
+[readme-additional-attributes]: https://github.com/lmc-eu/spirit-design-system/blob/main/packages/web-twig/README.md#additional-attributes
+[readme-style-props]: https://github.com/lmc-eu/spirit-design-system/blob/main/packages/web-twig/README.md#style-props
+[readme-escape-hatches]: https://github.com/lmc-eu/spirit-design-system/blob/main/packages/web-twig/README.md#escape-hatches

packages/web-twig/src/Resources/components/Collapse/README.md

@@ -1,6 +1,6 @@
 # Collapse
 
-This is Twig implementation of the [Collapse] component.
+This is Twig implementation of the [Collapse][collapse] component.
 
 Basic example usage:
 
@@ -63,9 +63,9 @@ attributes to register trigger events.
 
 (\*) Attribute for Accordion implementation
 
-You can add `data-*` or `aria-*` attributes to further extend the component's
-descriptiveness and accessibility. Also, UNSAFE styling props are available,
-see the [Escape hatches][escape-hatches] section in README to learn how and when to use them.
+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].
 
 ## Trigger attributes
 
@@ -94,7 +94,9 @@ Or, feel free to write the controlling script yourself.
 
 👉 Check the [component's docs in the web package][web-js-api] to see the full documentation and API of the plugin.
 
+[collapse]: https://github.com/lmc-eu/spirit-design-system/tree/main/packages/web/src/scss/components/Collapse
+[readme-additional-attributes]: https://github.com/lmc-eu/spirit-design-system/blob/main/packages/web-twig/README.md#additional-attributes
+[readme-style-props]: https://github.com/lmc-eu/spirit-design-system/blob/main/packages/web-twig/README.md#style-props
+[readme-escape-hatches]: https://github.com/lmc-eu/spirit-design-system/blob/main/packages/web-twig/README.md#escape-hatches
 [web-js-api]: https://github.com/lmc-eu/spirit-design-system/blob/main/packages/web/src/scss/components/Collapse/README.md#javascript-plugin
 [web-readme]: https://github.com/lmc-eu/spirit-design-system/blob/main/packages/web/README.md
-[collapse]: https://github.com/lmc-eu/spirit-design-system/tree/main/packages/web/src/scss/components/Collapse
-[escape-hatches]: https://github.com/lmc-eu/spirit-design-system/tree/main/packages/web-twig/README.md#escape-hatches

packages/web-twig/src/Resources/components/Container/README.md

@@ -1,6 +1,6 @@
 # Container
 
-This is Twig implementation of the [Container] component.
+This is Twig implementation of the [Container][container] component.
 
 Basic example usage:
 
@@ -22,9 +22,11 @@ Without lexer:
 
 There is no API for Container.
 
-You can add `id`, `data-*` or `aria-*` attributes to further extend component's
-descriptiveness and accessibility. Also, UNSAFE styling props are available,
-see the [Escape hatches][escape-hatches] section in README to learn how and when to use them.
+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].
 
 [container]: https://github.com/lmc-eu/spirit-design-system/tree/main/packages/web/src/scss/components/Container
-[escape-hatches]: https://github.com/lmc-eu/spirit-design-system/tree/main/packages/web-twig/README.md#escape-hatches
+[readme-additional-attributes]: https://github.com/lmc-eu/spirit-design-system/blob/main/packages/web-twig/README.md#additional-attributes
+[readme-style-props]: https://github.com/lmc-eu/spirit-design-system/blob/main/packages/web-twig/README.md#style-props
+[readme-escape-hatches]: https://github.com/lmc-eu/spirit-design-system/blob/main/packages/web-twig/README.md#escape-hatches