diff --git a/packages/web-react/README.md b/packages/web-react/README.md index d41a5807e1..a3d5307752 100644 --- 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 ; ``` +## 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 index 039b7fe551..4de487b30e 100644 --- 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 index b977ec178d..a0248ddae3 100644 --- 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 diff --git a/packages/web-react/src/components/Breadcrumbs/README.md b/packages/web-react/src/components/Breadcrumbs/README.md index 4bdb3fb4bb..95fbc2a832 100644 --- a/packages/web-react/src/components/Breadcrumbs/README.md +++ b/packages/web-react/src/components/Breadcrumbs/README.md @@ -55,14 +55,16 @@ Use custom content for the ordered list as component's children instead of passi ### API -| Name | Type | Default | Required | Description | -| ------------------ | ------------------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `children` | `ReactNode` | — | ✕ | Custom content to override items rendering from array | -| `elementType` | `ElementType` | `nav` | ✕ | Type of element used as wrapper | -| `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, the back link is to be created within children property. | -| `items` | `BreadcrumbsItem[]` | — | ✕ | Navigation menu items | -| `UNSAFE_className` | `string` | — | ✕ | Wrapper custom class name | -| `UNSAFE_style` | `CSSProperties` | — | ✕ | Wrapper custom style | +| Name | Type | Default | Required | Description | +| ------------- | ------------------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `children` | `ReactNode` | — | ✕ | Custom content to override items rendering from array | +| `elementType` | `ElementType` | `nav` | ✕ | Type of element used as wrapper | +| `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, the back link is to be created within children property. | +| `items` | `BreadcrumbsItem[]` | — | ✕ | Navigation menu items | + +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 @@ -80,19 +82,21 @@ Use the `BreadcrumbsItem` component for the ordered list as the component's chil ### API -| Name | Type | Default | Required | Description | -| ------------------ | --------------- | --------------- | -------- | ----------------------------------------------------- | -| `children` | `ReactNode` | — | ✕ | Children node | -| `href` | `string` | — | ✕ \* | URL, if not set, the item is rendered as a plain text | -| `iconNameEnd` | `string` | `chevron-right` | ✕ | Icon name at the end of the item | -| `iconNameStart` | `string` | `chevron-left` | ✕ | Icon name at the start of the item | -| `isCurrent` | `boolean` | `false` | ✕ | Whether is the item the current page | -| `isGoBackOnly` | `boolean` | `false` | ✕ | Whether should be displayed in go back mode | -| `UNSAFE_className` | `string` | — | ✕ | Wrapper custom class name | -| `UNSAFE_style` | `CSSProperties` | — | ✕ | Wrapper custom style | +| Name | Type | Default | Required | Description | +| --------------- | ----------- | --------------- | -------- | ----------------------------------------------------- | +| `children` | `ReactNode` | — | ✕ | Children node | +| `href` | `string` | — | ✕ \* | URL, if not set, the item is rendered as a plain text | +| `iconNameEnd` | `string` | `chevron-right` | ✕ | Icon name at the end of the item | +| `iconNameStart` | `string` | `chevron-left` | ✕ | Icon name at the start of the item | +| `isCurrent` | `boolean` | `false` | ✕ | Whether is the item the current page | +| `isGoBackOnly` | `boolean` | `false` | ✕ | Whether should be displayed in go back mode | (\*) Optional only for the current page. +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 When you need to shorten the title of the BreadcrumbsItem the preferred way is to use platform native helpers. @@ -104,5 +108,8 @@ You can also use any of the existing [npm packages which deal with truncating th For detailed information see [Breadcrumbs][breadcrumbs] component. -[truncate-npm-search]: https://www.npmjs.com/search?q=truncate [breadcrumbs]: https://github.com/lmc-eu/spirit-design-system/blob/main/packages/web/src/scss/components/Breadcrumbs/README.md +[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 +[truncate-npm-search]: https://www.npmjs.com/search?q=truncate diff --git a/packages/web-react/src/components/Button/README.md b/packages/web-react/src/components/Button/README.md index 10077609cd..fa9dd270c1 100644 --- a/packages/web-react/src/components/Button/README.md +++ b/packages/web-react/src/components/Button/README.md @@ -33,26 +33,31 @@ import { RouterLink } from 'react-router-dom'; ### API -| Name | Type | Default | Required | Description | -| ------------------ | ----------------------------------------------------------------------------------------- | --------- | -------- | -------------------------------------------------------------------------- | -| `children` | `ReactNode` | `null` | ✕ | Content of the Button | -| `color` | [Action Color dictionary][dictionary-color], [Emotion Color dictionary][dictionary-color] | `primary` | ✕ | Color variant | -| `elementType` | `ElementType` | `button` | ✕ | Type of element | -| `isBlock` | `bool` | `false` | ✕ | Span the element to the full width of its parent | -| `isDisabled` | `bool` | `false` | ✕ | If true, Button is disabled | -| `isLoading` | `bool` | `false` | ✕ | If true, Button is in a loading state, disabled and the Spinner is visible | -| `isSquare` | `bool` | `false` | ✕ | If true, Button is square, usually only with an Icon | -| `name` | `string` | — | ✕ | For use a button as a form data reference | -| `onClick` | `string` | `null` | ✕ | JS function to call on click | -| `ref` | `ForwardedRef` | — | ✕ | Button element reference | -| `size` | [Size dictionary][dictionary-size] | `medium` | ✕ | Size variant | -| `type` | `string` | `button` | ✕ | Type of the Button | -| `UNSAFE_className` | `string` | — | ✕ | Wrapper custom class name | -| `UNSAFE_style` | `CSSProperties` | — | ✕ | Wrapper custom style | +| Name | Type | Default | Required | Description | +| ------------- | ----------------------------------------------------------------------------------------- | --------- | -------- | -------------------------------------------------------------------------- | +| `children` | `ReactNode` | `null` | ✕ | Content of the Button | +| `color` | [Action Color dictionary][dictionary-color], [Emotion Color dictionary][dictionary-color] | `primary` | ✕ | Color variant | +| `elementType` | `ElementType` | `button` | ✕ | Type of element | +| `isBlock` | `bool` | `false` | ✕ | Span the element to the full width of its parent | +| `isDisabled` | `bool` | `false` | ✕ | If true, Button is disabled | +| `isLoading` | `bool` | `false` | ✕ | If true, Button is in a loading state, disabled and the Spinner is visible | +| `isSquare` | `bool` | `false` | ✕ | If true, Button is square, usually only with an Icon | +| `name` | `string` | — | ✕ | For use a button as a form data reference | +| `onClick` | `string` | `null` | ✕ | JS function to call on click | +| `ref` | `ForwardedRef` | — | ✕ | Button element reference | +| `size` | [Size dictionary][dictionary-size] | `medium` | ✕ | Size variant | +| `type` | `string` | `button` | ✕ | Type of the Button | For more information see [Button][button] component. Button also contain all the appropriate attributes according to the type of element. The default element type for Button is `