From 1ae72aecfce5c9c8de09f0e727a3707cc3027696 Mon Sep 17 00:00:00 2001 From: Davide Mininni Date: Mon, 11 Sep 2023 17:36:08 +0200 Subject: [PATCH 01/22] docs: first refactor --- .../generate-component/boilerplate/readme.md | 10 +- src/components/sbb-accordion/readme.md | 2 +- src/components/sbb-action-group/readme.md | 66 +++++---- src/components/sbb-alert/readme.md | 67 +++++---- src/components/sbb-autocomplete/readme.md | 50 ++++--- src/components/sbb-breadcrumb-group/readme.md | 28 ++-- src/components/sbb-breadcrumb/readme.md | 24 +-- src/components/sbb-calendar/readme.md | 67 +++++---- src/components/sbb-card-badge/readme.md | 16 +- src/components/sbb-card/readme.md | 37 ++++- src/components/sbb-checkbox-group/readme.md | 57 ++++--- src/components/sbb-checkbox/readme.md | 55 ++++--- src/components/sbb-clock/readme.md | 2 +- .../sbb-datepicker-next-day/readme.md | 30 ++-- .../sbb-datepicker-previous-day/readme.md | 32 ++-- .../sbb-datepicker-toggle/readme.md | 31 ++-- src/components/sbb-datepicker/readme.md | 139 +++++++++--------- src/components/sbb-dialog/readme.md | 10 +- src/components/sbb-divider/readme.md | 2 +- 19 files changed, 412 insertions(+), 313 deletions(-) diff --git a/convenience/generate-component/boilerplate/readme.md b/convenience/generate-component/boilerplate/readme.md index abc7b19278..ad92aa4f19 100644 --- a/convenience/generate-component/boilerplate/readme.md +++ b/convenience/generate-component/boilerplate/readme.md @@ -1,3 +1,11 @@ -to be documented... +To be documented... + +### Prop, event, method, accessibility... + +Brief description + +```html +<__name__> +``` \ No newline at end of file diff --git a/src/components/sbb-accordion/readme.md b/src/components/sbb-accordion/readme.md index 3483372657..7bfc1cacc0 100644 --- a/src/components/sbb-accordion/readme.md +++ b/src/components/sbb-accordion/readme.md @@ -28,7 +28,7 @@ In the following example, all the `sbb-expansion-panel-header` would be wrapped ### Multi -The `multi` property, if set, allows to have more than one panel expanded at the same time. +The `multi` property, if set, allows having more than one panel expanded at the same time. ```html diff --git a/src/components/sbb-action-group/readme.md b/src/components/sbb-action-group/readme.md index 13ee6e3f66..540fe616fb 100644 --- a/src/components/sbb-action-group/readme.md +++ b/src/components/sbb-action-group/readme.md @@ -1,12 +1,45 @@ The `` component is a generic content container which can contain up to three action items (`` or `` or other HTML elements) in various allocations. -The `orientation` property is used to set items orientation. Possible values are `horizontal` -(default) and `vertical`. +### Orientation and horizontal-from -The optional property `horizontalFrom` indicates the minimum breakpoint from which the orientation -changes to `horizontal`. +The `orientation` property is used to set item's orientation. +Possible values are `horizontal` (default) and `vertical`. +The optional property `horizontalFrom` can be used in combination with `orientation='vertical'` to +indicate the minimum breakpoint from which the orientation changes to `horizontal`. +```html + + Action 1 + Action 2 + + Action 3 + + +``` + +### Button-size and link-size + +The two props `button-size` and `link-size` can be used to override, respectively, the size of the inner `sbb-button` and `sbb-link`. +Default values are `l` for `sbb-button` and `m` for `sbb-link`. + +```html + + Action 1 + + Action 3 + + +``` + +### Align-group and align-self The `align-group` property can be used to set the default alignment of the contained elements; possible values are `start`, `center`, `stretch` and `end`. @@ -17,33 +50,12 @@ opposite direction to the group; possible values are `start`, `center` or `end`. property with nested `` and the `buttonSize` property with the nested `` instances. -## Usage - -The examples below shows how to use the `` component using `` and `` as action items. - ```html - - Action 1 - Action 2 - - - + Action 1 Action 2 Action 3 - - - Action 1 - Action 2 - - Action 3 - - ``` ## Allocations @@ -63,7 +75,7 @@ and we consider a template like the following one (possibly removing the link fo ``` -the values for `align-group` and `align-self` for the various allocations are as follows. +The values for `align-group` and `align-self` for the various allocations are as follows: ### Horizontal diff --git a/src/components/sbb-alert/readme.md b/src/components/sbb-alert/readme.md index 32eb1f1e03..e0a8d30b65 100644 --- a/src/components/sbb-alert/readme.md +++ b/src/components/sbb-alert/readme.md @@ -1,64 +1,79 @@ -The alert component should be used to display important messages to a client. -There are two sizes available and a `sbb-alert` can optionally be hidden by a user. -It's possible to place an action, which by clicking navigates somewhere to display more information. +The `sbb-alert` component should be used to display important messages to a client. -**Note:** Clicking on the close button does not remove it from the DOM, this would be in responsibility -of the library consumer to do it by reacting to the specific event. -See also the `sbb-alert-group` which automatically removes an alert after clicking the close button. - -## Accessibility -The description text is wrapped into an `

` element to guarantee the semantic meaning. -Avoid slotting block elements (e.g. `

`) as this violates semantic rules and can have negative effects on screen readers. +### Slots -## Usage +The text content is projected using and unnamed slot, while the title uses the slot named `title` or alternatively the `titleContent` property. +The component can optionally display a `` at the component start using the `iconName` property or via custom content using the `icon` slot. -Default with link: +Basic usage: ```html - + Between Bern and Olten from 03.11.2021 to 05.12.2022 each time from 22:30 to 06:00 o'clock construction work will take place. You have to expect changed travel times and changed connections. ``` -Without link: +Usage with slots: ```html - + + Interruption between Berne and Olten + Between Bern and Olten from 03.11.2021 to 05.12.2022 each time from 22:30 to 06:00 o'clock construction work will take place. You have to expect changed travel times and changed connections. ``` -Readonly (no close button): + +### Size + +Users can choose between two `size`, `m` (default) and `l`. ```html - - Between Bern and Olten from 03.11.2021 to 05.12.2022 each time from 22:30 to 06:00 o'clock - construction work will take place. - You have to expect changed travel times and changed connections. + + ... ``` -Slot variant: + +### Action + +It's possible to place an action, which by clicking navigates somewhere to display more information. +This can be done using the `linkContent` property combined with the `href` one. +The `target` and `rel` property are also configurable via the self-named properties. ```html - - Interruption between Berne and Olten - + + ... + +``` + + +### Dismiss + +The `sbb-alert` can optionally be hidden by a user, if the `readonly` prop is not set. +Please note that clicking on the close button does not remove it from the DOM, this would be the responsibility +of the library consumer to do it by reacting to the specific event. +See also the `sbb-alert-group` which automatically removes an alert after clicking the close button. + +```html + Between Bern and Olten from 03.11.2021 to 05.12.2022 each time from 22:30 to 06:00 o'clock construction work will take place. You have to expect changed travel times and changed connections. ``` -## Accessibility -Accessibility is mainly done by wrapping the alerts into the `sbb-alert-group`. +### Accessibility +Accessibility is mainly done by wrapping the alerts into the `sbb-alert-group`. +The description text is wrapped into an `

` element to guarantee the semantic meaning. +Avoid slotting block elements (e.g. `

`) as this violates semantic rules and can have negative effects on screen readers. diff --git a/src/components/sbb-autocomplete/readme.md b/src/components/sbb-autocomplete/readme.md index 9bfd4eec9c..a1de5bcb92 100644 --- a/src/components/sbb-autocomplete/readme.md +++ b/src/components/sbb-autocomplete/readme.md @@ -1,23 +1,11 @@ The `sbb-autocomplete` is a component that can be used to display a panel of suggested options connected to a text input. +### Connections + If the component is used within a `sbb-form-field`, it will automatically connect to the native `input` as trigger and will display the option panel above or below the `sbb-form-field`; otherwise, it's possible to set the panel `origin` and the input `trigger` passing an id or an element reference. -The options panel opens on `focus`, `click` or `input` on the trigger element, or on `ArrowDown` keypress; -it can be closed on backdrop click, or using the `Escape` or `Tab` keys. - -### Events - -The `sbb-option` will emit the `option-selected` event when selected via user interaction. - -### Option highlight - -By default, the autocomplete will highlight the label of the `sbb-option` in the panel, if it matches the typed text. -See the [sbb-option](../sbb-option/readme.md) for more details. - -## Usage - In a form field: ```html @@ -50,8 +38,15 @@ Standalone, by setting the `origin` and `trigger` properties: Option C ``` + +### Option highlight + +By default, the autocomplete will highlight the label of the `sbb-option` in the panel, if it matches the typed text. +See the [sbb-option](../sbb-option/readme.md) for more details. + ### Option grouping -`sbb-option` can be collected into groups using `sbb-optgroup` element: + +The `sbb-option` can be collected into groups using `sbb-optgroup` element: ```html @@ -72,19 +67,28 @@ Standalone, by setting the `origin` and `trigger` properties: ``` +### Events + +The `sbb-option` will emit the `option-selected` event when selected via user interaction. + ## Keyboard interaction -| Keyboard shortcut | Action | -|----------------------------------------|----------------------------------------------------------------| -| Down Arrow | Navigate to the next option. Open the panel, if closed. | -| Up Arrow | Navigate to the previous option. | -| Enter | Select the active option. | -| Escape | Close the autocomplete panel. | + +The options panel opens on `focus`, `click` or `input` on the trigger element, or on `ArrowDown` keypress; +it can be closed on backdrop click, or using the `Escape` or `Tab` keys. + +| Keyboard | Action | +|-----------------------|---------------------------------------------------------| +| Down Arrow | Navigate to the next option. Open the panel, if closed. | +| Up Arrow | Navigate to the previous option. | +| Enter | Select the active option. | +| Escape | Close the autocomplete panel. | ## Accessibility + `sbb-autocomplete` implements the ARIA combobox interaction pattern. The text input trigger specifies `role="combobox"` while the content of the pop-up applies `role="listbox"`. -Because of this listbox pattern, you should not put other interactive controls, such as buttons or checkboxes, inside an autocomplete option. -Nesting interactive controls like this interferes with most assistive technology. +Because of this `listbox` pattern, you should not put other interactive controls, such as buttons or checkboxes, inside an autocomplete option. +Nesting interactive controls like this interferes with many assistive technologies. `sbb-autocomplete` preserves focus on the input trigger, using `aria-activedescendant` to support navigation though the autocomplete options. diff --git a/src/components/sbb-breadcrumb-group/readme.md b/src/components/sbb-breadcrumb-group/readme.md index 11373c940a..2a6cba891e 100644 --- a/src/components/sbb-breadcrumb-group/readme.md +++ b/src/components/sbb-breadcrumb-group/readme.md @@ -1,21 +1,6 @@ The `sbb-breadcrumb-group` component is a container for one or more `sbb-breadcrumb`, which are meant to represent the hierarchy of visited pages before arriving to the current one. -If the width of all the nested breadcrumbs exceeds the container width, only the first and the last breadcrumb are displayed, -and a new one with the ellipsis symbol appears between them. -Clicking on this breadcrumb will make the ellipsis disappear and will restore the full list (the action is not reversible). - -## Accessibility - -It is strongly recommended to place an `aria-label` attribute on the `sbb-breadcrumb-group`, to describe -what context the breadcrumbs have. -Whenever the `sbb-breadcrumb` list within the component is loaded or updated, the last element of the list -receive the attribute `aria-current` set to `page`. - -## Usage - -`sbb-breadcrumb-group` with home icon as first `sbb-breadcrumb`: - ```html @@ -28,6 +13,19 @@ receive the attribute `aria-current` set to `page`. ``` +### Ellipsis + +If the width of all the nested breadcrumbs exceeds the container width, only the first and the last breadcrumb are displayed, +and a new one with the ellipsis symbol appears between them. +Clicking on this breadcrumb will make the ellipsis disappear and will restore the full list (the action is not reversible). + +## Accessibility + +It is strongly recommended to place an `aria-label` attribute on the `sbb-breadcrumb-group`, to describe +what context the breadcrumbs have. +Whenever the `sbb-breadcrumb` list within the component is loaded or updated, the last element of the list +receive the attribute `aria-current` set to `page`. + diff --git a/src/components/sbb-breadcrumb/readme.md b/src/components/sbb-breadcrumb/readme.md index d17d9e6d89..b46ad9402d 100644 --- a/src/components/sbb-breadcrumb/readme.md +++ b/src/components/sbb-breadcrumb/readme.md @@ -1,25 +1,16 @@ The `sbb-breadcrumb` is a component used to display a link to a page; when it's used within the `sbb-breadcrumb-group` component, it can display the list of the links the user visited to arrive at the current page. +### Slots + It is possible to provide a text via an unnamed slot; the component can optionally display a `` at the component start using the `iconName` property or via custom content using the `icon` slot. Text and icon are not exclusive and can be used together. -It's possible to set all the link related properties (`download`, `href`, `rel` and `target`). - -## Accessibility -The `aria-current` property should be used to make the breadcrumb read correctly by screen-readers when the component -is used in the `sbb-breadcrumb-group`. -By default, the `sbb-breadcrumb-group` component sets `aria-current="page"` on the last slotted `sbb-breadcrumb`. - -## Usage - Breadcrumb with text: ```html - - Contact us - +Contact us ``` Breadcrumb with icon: @@ -37,6 +28,15 @@ Breadcrumb with text and slotted icon: ``` +### Link + +It's possible to set all the link related properties (`download`, `href`, `rel` and `target`). + +## Accessibility +The `aria-current` property should be used to make the breadcrumb read correctly by screen-readers when the component +is used in the `sbb-breadcrumb-group`. +By default, the `sbb-breadcrumb-group` component sets `aria-current="page"` on the last slotted `sbb-breadcrumb`. + diff --git a/src/components/sbb-calendar/readme.md b/src/components/sbb-calendar/readme.md index 7784c178fe..c3627dc8ef 100644 --- a/src/components/sbb-calendar/readme.md +++ b/src/components/sbb-calendar/readme.md @@ -1,45 +1,54 @@ -The `sbb-calendar` component displays a calendar that allows the user to select a date. For accessibility purposes, it's rendered as a native table element and each day is a button. - +The `sbb-calendar` component displays a calendar that allows the user to select a date. +For accessibility purposes, it's rendered as a native table element and each day is a button. While being deeply linked to the implementation of the `sbb-datepicker-toggle` component, it can be used on its own. -For date inputs (`min`, `max`, `selected-date`) the accepted formats are: -- Date objects -- ISO String -- Unix Timestamp (number of seconds since Jan 1, 1970) -and it's recommended to set the time to 00:00:00. +### Select a date and boundaries -The component displays one month by default; two months can be displayed setting the `wide` property to `true`. It's also -possible to filter out unwanted date using the `dateFilter` function property. +It's possible to set a date using the `dateSelected` property. Also, it's possible to place limits on the selection +using the two properties name `min` and `max`. For these three properties, the accepted formats are: -Consumers can listen to the `dateSelected` event on the `sbb-calendar` component to intercept the selected date -which can be read from `event.detail`. +- Date objects +- ISO String +- Unix Timestamp (number of seconds since 1 Jan 1970) -Note that using the `dateFilter` function as a replacement for the `min` and `max` properties will most likely result in a significant loss of performance. +And it's recommended to set the time to 00:00:00. -## Accessibility +```html + +``` -Keyboard navigation summary: -- Left arrow: go to previous day -- Right arrow: go to next day -- Up arrow: go to the same day in the previous week -- Down arrow: go to the same day in the next week -- Home: go to the first day of the month -- End: go to the last day of the month -- Page Up: go to the top of the column of the currently selected day -- Page Down: go to the bottom of the column of the currently selected day +### Date filter -## Usage +It's possible to filter out unwanted date using the `dateFilter` function property. +Note that using the `dateFilter` function as a replacement for the `min` and `max` properties will most likely result in a significant loss of performance. -Calendar with selected date and bounds: +### Wide +The component displays one month by default; two months can be displayed setting the `wide` property to `true`. ```html - + ``` +### Events + +Consumers can listen to the `dateSelected` event on the `sbb-calendar` component to intercept the selected date +which can be read from `event.detail`. + +## Accessibility + +It's possible to move within the component using the keyboard. + +| Keyboard | Action | +|------------------------|---------------------------------------------------------------| +| Left Arrow | Go to previous day. | +| Right Arrow | Go to next day. | +| Up Arrow | Go to the same day in the previous week. | +| Down Arrow | Go to the same day in the next week. | +| Home | Go to the first day of the month. | +| End | Go to the last day of the month. | +| Page Up | Go to the top of the column of the currently selected day. | +| Page Down | Go to the bottom of the column of the currently selected day. | + ## Testing To specify a specific date for the current datetime, you can use the `data-now` attribute (timestamp in milliseconds). diff --git a/src/components/sbb-card-badge/readme.md b/src/components/sbb-card-badge/readme.md index 1dab962805..7518c3c43d 100644 --- a/src/components/sbb-card-badge/readme.md +++ b/src/components/sbb-card-badge/readme.md @@ -1,16 +1,9 @@ -The `` can contain some information like prices -or discounts and is e.g. used in `` or ``. +The `` can contain some information like prices or discounts and is +e.g. used in `` or ``. To achieve the correct spacing between elements inside the card badge, we recommend to use ``-elements. All content parts are presented with a predefined gap in between. -## Accessibility - -It's recommended to place an `aria-label` on `` to describe -the displayed information in a full sentence. - -### Example with `sbb-card` - ```html @@ -22,6 +15,11 @@ the displayed information in a full sentence. ``` +## Accessibility + +It's recommended to place an `aria-label` on `` to describe +the displayed information in a full sentence. + diff --git a/src/components/sbb-card/readme.md b/src/components/sbb-card/readme.md index e082821d67..6d36fc590d 100644 --- a/src/components/sbb-card/readme.md +++ b/src/components/sbb-card/readme.md @@ -1,10 +1,29 @@ The `sbb-card` component is a generic content container; its task is to contain content related to a single subject. -There are various sizes (affecting paddings) and colors available. + +### Size + +It's possible to choose among seven different values for the `size` property (from `xs` to `xxxl`); +the choice mainly affect the content's padding (default is `m`). ```html - - Card content - +Card content +Card content +Card content +Card content +Card content +Card content +Card content +``` + +### Color + +The component has four different values to choose from for the `color` property; default is `white`. + +```html +Card content +Card content +Card content +Card content ``` ## Card With Badge @@ -39,9 +58,13 @@ For API details see the [`sbb-card-action` docs](/docs/components-sbb-card-sbb-c ## Accessibility It's **important** that a descriptive message is being slotted into the unnamed slot of `` -as it is used for search engines and screen reader users. E.g. `Buy a half-fare ticket now`. +as it is used for search engines and screen reader users. + +```html +Buy a half-fare ticket now +``` -Normally, a `` should be a single action, however it's possible to place other interactive elements +Normally, a `` should be a single action, however, it's possible to place other interactive elements in the card content. Interactive content will automatically be detected and made accessible to click / focus. In cases where there should be only a visual button or link inside the card content without a different action, the `is-static` attribute should be set (e.g. ``). @@ -51,7 +74,7 @@ In cases where there should be only a visual button or link inside the card cont In high contrast mode, all the content of a link or a button receives a specific color which overrides every other color. However, as the content of the card is not directly inside the button or link, this does not happen when the slotted content has a specific color set. -To improve coloring, it's needed to manually define styles for windows high contrast mode (setting `LinkText` or `ButtonText`). +To improve coloring, it's needed to manually define styles for Window high contrast mode (setting `LinkText` or `ButtonText`). diff --git a/src/components/sbb-checkbox-group/readme.md b/src/components/sbb-checkbox-group/readme.md index 37a94f16fc..1e7d64504b 100644 --- a/src/components/sbb-checkbox-group/readme.md +++ b/src/components/sbb-checkbox-group/readme.md @@ -1,17 +1,5 @@ The `` component is used as a container for one or multiple `` components, -which are projected inside an unnamed slot. - -The `orientation` property is used to set items orientation. Possible values are `horizontal` (default) and `vertical`. -The optional property `horizontalFrom` can be used in combination with `orientation='vertical'` to -indicate the minimum breakpoint from which the orientation changes to `horizontal`. - -It is possible to mark the entire group as disabled or required using the properties `disabled` and `required`. - -The component can display one or more `` components right below the `` using the `error` slot. - -## Usage - -Basic usage: +which are projected inside an unnamed slot. ```html @@ -21,26 +9,51 @@ Basic usage: ``` -Required `sbb-checkbox-group` with error message: +### Orientation and horizontal-from + +The `orientation` property is used to set item orientation. Possible values are `horizontal` (default) and `vertical`. +The optional property `horizontalFrom` can be used in combination with `orientation='vertical'` to +indicate the minimum breakpoint from which the orientation changes to `horizontal`. + +```html + + ... + +``` + +### States + +It is possible to mark the entire group as disabled or required using the properties `disabled` and `required`. +The component has a `size` property too, which can be used to change the size of all the inner `sbb-checkbox`. + ```html - + - Label 1 - Label 2 - Label 3 - You must accept all the terms and conditions. + ... + + + + + ... + + + + + ... ``` -Disabled `sbb-checkbox-group` with vertical orientation below `large` breakpoint and horizontal above: +### Error + +The component can display one or more `` components right below the `` using the `error` slot. ```html - - + Label 1 Label 2 Label 3 + You must accept all the terms and conditions. ``` diff --git a/src/components/sbb-checkbox/readme.md b/src/components/sbb-checkbox/readme.md index 2d1cad3725..a5e6a8dc7d 100644 --- a/src/components/sbb-checkbox/readme.md +++ b/src/components/sbb-checkbox/readme.md @@ -1,50 +1,57 @@ The `` component provides the same functionality as a native `` enhanced with the SBB Design. -The component has two `size`, named `s` (default) and `m`. -It could be checked or not depending on the value of the `checked` attribute. -It has a third state too, which is set if the `indeterminate` property is true. This is useful when multiple dependent -checkboxes are used (e.g. a parent which is checked only if all the children are checked, otherwise is in indeterminate state). -Clicking on a `sbb-checkbox` in this state sets `checked` to `true` and `indeterminate` to false. - -The component can be displayed in disabled or required state by using the self-named properties. +### Slots -It is possible to provide a label via an unnamed slot; the component can optionally display a `` using +It is possible to provide a label via an unnamed slot; the component can optionally display a `` using the `iconName` property or via custom SVG using the `icon` slot. The icon can be placed before or after the label based on the value of the `iconPlacement` property (default: end). -Consumers can listen to the native `change` event on the `sbb-checkbox` component to intercept the input's change; -the current state can be read from `event.target.checked`, while the value from `event.target.value`. +```html +Example + +Icon + +Icon at start +``` -## Usage +### States -Checked: +The component could be checked or not depending on the value of the `checked` attribute. ```html - - Example - +Checked state ``` -Unchecked and disabled with icon +It has a third state too, which is set if the `indeterminate` property is true. +This is useful when multiple dependent checkboxes are used +(e.g., a parent which is checked only if all the children are checked, otherwise is in indeterminate state). +Clicking on a `sbb-checkbox` in this state sets `checked` to `true` and `indeterminate` to false. ```html - - Example - +Indeterminate state ``` -Indeterminate and required with icon placed before the label +The component can be displayed in disabled or required state by using the self-named properties. ```html - - Example - +Required + +Disabled ``` +### Size + +The component has two `size`, named `s` (default) and `m`. + +### Events + +Consumers can listen to the native `change` event on the `sbb-checkbox` component to intercept the input's change; +the current state can be read from `event.target.checked`, while the value from `event.target.value`. + ## Accessibility The component uses an internal `` element to provide an accessible experience. -This internal checkbox receives focus and is automatically labelled by the text content of the +This internal checkbox receives focus and is automatically labeled by the text content of the `` element. Avoid adding other interactive controls into the content of ``, as this degrades the experience for users of assistive technology. diff --git a/src/components/sbb-clock/readme.md b/src/components/sbb-clock/readme.md index 779bacfc60..716e9abf22 100644 --- a/src/components/sbb-clock/readme.md +++ b/src/components/sbb-clock/readme.md @@ -1,5 +1,5 @@ The `sbb-clock` component displays an analog clock face in the style of the classic SBB station clock. -It mimics also its behavior, completing a rotation in approximately 58.5 seconds, +It mimics its behavior too, completing a rotation in approximately 58.5 seconds, then it briefly pauses at the clock top before starting a new rotation. ## Testing diff --git a/src/components/sbb-datepicker-next-day/readme.md b/src/components/sbb-datepicker-next-day/readme.md index e950229e7c..5689b48440 100644 --- a/src/components/sbb-datepicker-next-day/readme.md +++ b/src/components/sbb-datepicker-next-day/readme.md @@ -2,26 +2,30 @@ The `sbb-datepicker-next-day` is a component closely connected to the `sbb-datep when the two are used together, the `sbb-datepicker-next-day` can be used to choose the date after the selected date, or tomorrow's date if the date-picker's input has no defined value. -If the two components are used within a `sbb-form-field`, they are automatically linked and -the `sbb-datepicker-next-day` will be projected in the `suffix` slot of the `sbb-form-field`; otherwise, -they can be connected using the `datePicker` property, which accepts the id of the `sbb-datepicker`, +The components can be connected using the `datePicker` property, which accepts the id of the `sbb-datepicker`, or directly its reference. -The `sbb-datepicker-next-day` has an internal disabled state, which is set looking at the `sbb-datepicker`'s input: -if it is disabled, or if the selected date is equal to the input's `max` attribute, the component is disabled. +```html + + + +``` +### In `sbb-form-field` -## Usage +If the two components are used within a `sbb-form-field`, they are automatically linked and +the `sbb-datepicker-next-day` will be projected in the `suffix` slot of the `sbb-form-field`; +otherwise, they can be connected using the `datePicker` property as described above. -Inside `sbb-form-field`: +The `sbb-datepicker-next-day` has an internal disabled state, which is set looking at the `sbb-datepicker`'s input: +if it is disabled, or if the selected date is equal to the input's `max` attribute, the component is disabled. ```html - - - - - - + + + + + ``` diff --git a/src/components/sbb-datepicker-previous-day/readme.md b/src/components/sbb-datepicker-previous-day/readme.md index 319d4defbb..62d2e1033a 100644 --- a/src/components/sbb-datepicker-previous-day/readme.md +++ b/src/components/sbb-datepicker-previous-day/readme.md @@ -2,26 +2,30 @@ The `sbb-datepicker-previous-day` is a component closely connected to the `sbb-d when the two are used together, the `sbb-datepicker-previous-day` can be used to choose the date before the selected date, or yesterday's date if the date-picker's input has no defined value. -If the two components are used within a `sbb-form-field`, they are automatically linked and -the `sbb-datepicker-previous-day` will be projected in the `prefix` slot of the `sbb-form-field`; otherwise, -they can be connected using the `datePicker` property, which accepts the id of the `sbb-datepicker`, -or directly its reference. +The components can be connected using the `datePicker` property, which accepts the id of the `sbb-datepicker`, +or directly its reference. -The `sbb-datepicker-previous-day` has an internal disabled state, which is set looking at the `sbb-datepicker`'s input: -if it is disabled, or if the selected date is equal to the input's `min` attribute, the component is disabled. +```html + + + +``` +### In `sbb-form-field` -## Usage +If the two components are used within a `sbb-form-field`, they are automatically linked and +the `sbb-datepicker-previous-day` will be projected in the `prefix` slot of the `sbb-form-field`; +otherwise, they can be connected using the `datePicker` property as described above. -Inside `sbb-form-field`: +The `sbb-datepicker-previous-day` has an internal disabled state, which is set looking at the `sbb-datepicker`'s input: +if it is disabled, or if the selected date is equal to the input's `min` attribute, the component is disabled. ```html - - - - - - + + + + + ``` diff --git a/src/components/sbb-datepicker-toggle/readme.md b/src/components/sbb-datepicker-toggle/readme.md index 82a65af0bb..74763e68b0 100644 --- a/src/components/sbb-datepicker-toggle/readme.md +++ b/src/components/sbb-datepicker-toggle/readme.md @@ -3,27 +3,30 @@ When the two are used together, the `sbb-datepicker-toggle` can be used to link a change in the latter, like selecting a date, is propagated to the former; and conversely, changes in the `sbb-datepicker` properties, or in the date-picker's input attributes, are propagated to the `sbb-calendar` to modify its appearance. -If the two components are used within a `sbb-form-field`, they are automatically linked and -the `sbb-datepicker-toggle` will be projected in the `prefix` slot of the `sbb-form-field`; otherwise, -they can be connected using the `datePicker` property, which accepts the id of the `sbb-datepicker`, +The components can be connected using the `datePicker` property, which accepts the id of the `sbb-datepicker`, or directly its reference. -The `wide` property from the `sbb-datepicker` can be used to display the calendar in a two months -view, while the `dateFilter` property can be used to filter unwanted dates. +```html + + + +``` +### In `sbb-form-field` -## Usage +If the two components are used within a `sbb-form-field`, they are automatically linked and +the `sbb-datepicker-toggle` will be projected in the `prefix` slot of the `sbb-form-field`; +otherwise, they can be connected using the `datePicker` property as described above. -Inside `sbb-form-field`: +The `wide` property from the `sbb-datepicker` can be used to display the calendar in a two-months +view, while the `dateFilter` property can be used to filter unwanted dates. ```html - - - - - - - + + + + + ``` diff --git a/src/components/sbb-datepicker/readme.md b/src/components/sbb-datepicker/readme.md index 14573b7600..43d650e10a 100644 --- a/src/components/sbb-datepicker/readme.md +++ b/src/components/sbb-datepicker/readme.md @@ -4,95 +4,94 @@ as a formatted date (dd.MM.yyyy). The component allows the insertion of up to 10 numbers, possibly with separators like `.`, `-`, ` `, `,` or `/`, then automatically formats the value as date and displays it. It also exposes methods to get/set the value formatted as Date. -If the `sbb-datepicker` is used within a `sbb-form-field` with a native input, they are automatically linked; otherwise, -they can be connected using the `input` property, which accepts the id of the native input, or directly its reference. +The component and the native input can be connected using the `input` property, +which accepts the id of the native input, or directly its reference. -When the two are linked, the component sets the input placeholder, and the input's type as `text`, then reads -the `disabled`, `readonly`, `min` and `max` attributes from the input and emits then as payload of the `inputUpdated` event. -If the input's value changes, it is formatted then a `change` event is emitted with the new value. If it's an invalid date, the `data-sbb-invalid` attribute is added to the input. The component also listens for changes in its two properties, `wide` and `dateFilter`, and emits a `datePickerUpdated` event when changed. - -Consumers can listen to the native `change` and `input` events on the `sbb-datepicker` component to intercept date changes, the current value can be read from the async method `event.target.getValueAsDate()`. -To set the value programmatically it's recommended to use the `setValueAsDate()` method of the ``. -Each time the user changes the date by using the calendar, the next and previous day arrow, or by using the `setValueAsDate()` method, a `blur` event is fired on the input to ensure compatibility with any framework that relies on that event to update the current state. +```html + + +``` -Note that using the `dateFilter` function as a replacement for the `min` and `max` properties will most likely result in a significant loss of performance. +### In `sbb-form-field` -## Custom date formats +If the `sbb-datepicker` is used within a `sbb-form-field` with a native input, they are automatically linked; +the component sets the input placeholder and the input's type as `text`, then reads the `disabled`, `readonly`, +`min` and `max` attributes from the input and emits then as payload of the `inputUpdated` event. +It's possible to remove unwanted dates from selection using the `dateFilter` function, however, this should **not** +be used as a replacement for the `min` and `max` properties will most likely result in a significant loss of performance. +It's also possible to display a two-months view using the `wide` property. -Using a combination of the `dateParser` and `format` properties, it's possible to configure the datepicker to accept date formats other than the default `EE, dd.mm.yyyy`. -In the following example the datepicker is set to accept dates in the format `yyyy-mm-dd`. In particular, `dateParser` is the function that the component uses internally to decode strings and parse them into `Date` objects, while the `format` function is the one that the component uses internally to display a given `Date` object as a string. - -```ts - // datePicker is a HTMLSbbDatepickerElement - datePicker.dateParser = (value: string) => { - // You should implement some kind of input validation - if (!value || !isValid(value)) { - return undefined; - } - - return new Date(value); - }; - - datePicker.format = (value: Date) => { - if (!value) { - return ''; - } - - const offset = value.getTimezoneOffset(); - value = new Date(yourDate.getTime() - (offset * 60 * 1000)); - return yourDate.toISOString().split('T')[0]; - }; +```html + + + + ``` -Usually these functions need to be changed together, although in simple cases where the default `dateParser` might still work properly (e.g. in case we wanted to accept the format `dd.mm.yyyy`), it's possible to provide just the `format` function. -For custom `format` functions is recommended to use the `Intl.DateTimeFormat` API, as it's done in the default implementation. - - +```html + + + + + + + + +``` -## Validation Change +### Events -Whenever the validation state changes (e.g. a valid value becomes invalid or vice versa), the `validationChange` event is emitted. +If the input's value changes, it is formatted then a `change` event is emitted with the new value. +If it's an invalid date, the `data-sbb-invalid` attribute is added to the input. +The component also listens for changes in its two properties, `wide` and `dateFilter`, and emits a `datePickerUpdated` event when changed. +Consumers can listen to the native `change` and `input` events on the `sbb-datepicker` component to intercept date changes, +the current value can be read from the async method `event.target.getValueAsDate()`. +To set the value programmatically, it's recommended to use the `setValueAsDate()` method of the ``. -## Usage +Each time the user changes the date by using the calendar, or the next and previous day arrow, or by using the `setValueAsDate()` method, +a `blur` event is fired on the input to ensure compatibility with any framework that relies on that event to update the current state. -Without `sbb-form-field`: -```html - - -``` +## Custom date formats -Without `sbb-form-field`, with all related components: +Using a combination of the `dateParser` and `format` properties, it's possible to configure the datepicker +to accept date formats other than the default `EE, dd.mm.yyyy`. +In the following example the datepicker is set to accept dates in the format `yyyy-mm-dd`. +In particular, `dateParser` is the function that the component uses internally to decode strings and parse them into `Date` objects, +while the `format` function is the one that the component uses internally to display a given `Date` object as a string. -```html - - - - - +```ts +// datePicker is a HTMLSbbDatepickerElement +datePicker.dateParser = (value: string) => { + // You should implement some kind of input validation + if (!value || !isValid(value)) { + return undefined; + } + + return new Date(value); +}; + +datePicker.format = (value: Date) => { + if (!value) { + return ''; + } + + const offset = value.getTimezoneOffset(); + value = new Date(yourDate.getTime() - (offset * 60 * 1000)); + return yourDate.toISOString().split('T')[0]; +}; ``` -With `sbb-form-field`, and input params set: +Usually these functions need to be changed together, although in simple cases where the default `dateParser` might still work properly +(e.g., in case we wanted to accept the format `dd.mm.yyyy`), it's possible to provide just the `format` function. +For custom `format` functions is recommended to use the `Intl.DateTimeFormat` API, as it's done in the default implementation. -```html - - - - -``` + -With `sbb-form-field` and all related components, input's value set, `wide` set to true: +## Validation Change -```html - - - - - - - -``` +Whenever the validation state changes (e.g. a valid value becomes invalid or vice versa), the `validationChange` event is emitted. ## Testing diff --git a/src/components/sbb-dialog/readme.md b/src/components/sbb-dialog/readme.md index 3f8e09ba02..11bf433eed 100644 --- a/src/components/sbb-dialog/readme.md +++ b/src/components/sbb-dialog/readme.md @@ -1,7 +1,7 @@ -The dialog component provides a way to present content on top of the app's content and can be used +The `sbb-dialog` component provides a way to present content on top of the app's content and can be used in several contexts. The dialog offers the following features: -- creates a backdrop, for disabling interaction below the modal; +- creates a backdrop for disabling interaction below the modal; - disables scrolling of the page content while open; - manages focus properly by setting it on the first focusable element; - can have a header and a footer, both of which are optional; @@ -17,7 +17,8 @@ pressing the `Esc` key. `action-group` slot. ## Usage -In order to show a modal you need to call the `open(event?: PointerEvent)` method on the + +In order to show a modal, you need to call the `open(event?: PointerEvent)` method on the `` component: ```html @@ -38,13 +39,14 @@ In order to show a modal you need to call the `open(event?: PointerEvent)` metho Note that it is necessary to pass the event object to the `open()` method to allow the dialog to detect whether it has been opened by click or keyboard, so that the focus can be better handled. -To dismiss the dialog you need to get a reference to the `` element and call +To dismiss the dialog, you need to get a reference to the `` element and call the `close(result?: any, target?: HTMLElement)` method, which will close the dialog element and emit a close event with an optional result as a payload. You can also indicate that an element within the dialog content should close the dialog when clicked by marking it with the `sbb-dialog-close` attribute. ### Usage notes + The default `z-index` of the component is set to `1000`; to specify a custom stack order, the `z-index` can be changed by defining the CSS variable `--sbb-dialog-z-index`. diff --git a/src/components/sbb-divider/readme.md b/src/components/sbb-divider/readme.md index d72f6ab602..9c0fd78ae1 100644 --- a/src/components/sbb-divider/readme.md +++ b/src/components/sbb-divider/readme.md @@ -1,6 +1,6 @@ The `sbb-divider` is used to visually divide sections. -Based on the orientation property, the `sbb-divider` can be displayed vertically or horizontally. +Based on the `orientation` property, the `sbb-divider` can be displayed vertically or horizontally. From 7e9d0f7e689b23f8b090fabcf8b08ab5e9d4f859 Mon Sep 17 00:00:00 2001 From: Davide Mininni Date: Thu, 14 Sep 2023 16:15:08 +0200 Subject: [PATCH 02/22] docs: second refactor --- src/components.d.ts | 4 +- src/components/sbb-action-group/readme.md | 6 +- src/components/sbb-card/readme.md | 8 +-- src/components/sbb-checkbox-group/readme.md | 2 +- src/components/sbb-expansion-panel/readme.md | 2 +- src/components/sbb-footer/readme.md | 39 ++++++++---- src/components/sbb-form-error/readme.md | 12 ++-- src/components/sbb-form-field-clear/readme.md | 7 --- .../sbb-form-field-clear.tsx | 3 - src/components/sbb-form-field/readme.md | 4 +- src/components/sbb-header-action/readme.md | 31 +++++++--- src/components/sbb-header/readme.md | 62 +++++++++---------- src/components/sbb-icon/readme.md | 2 +- src/components/sbb-journey-header/readme.md | 40 ++++++------ src/components/sbb-link-list/readme.md | 33 +++++++--- src/components/sbb-link/readme.md | 58 +++++++++++++++-- src/components/sbb-logo/readme.md | 25 ++++++-- src/components/sbb-map-container/readme.md | 22 +++++-- src/components/sbb-menu-action/readme.md | 34 ++++++++-- src/components/sbb-menu/readme.md | 56 +++++++++-------- src/components/sbb-message/readme.md | 30 +++++---- src/components/sbb-message/sbb-message.tsx | 6 +- 22 files changed, 312 insertions(+), 174 deletions(-) diff --git a/src/components.d.ts b/src/components.d.ts index f8acbbdd23..fe85ed0377 100644 --- a/src/components.d.ts +++ b/src/components.d.ts @@ -1141,7 +1141,7 @@ export namespace Components { */ "titleContent"?: string; /** - * Level of title, will be rendered as heading tag (e.g. h3). Defaults to level 3. + * Level of title, it will be rendered as heading tag (e.g., h3). Defaults to level 3. */ "titleLevel": InterfaceTitleAttributes['level']; } @@ -3947,7 +3947,7 @@ declare namespace LocalJSX { */ "titleContent"?: string; /** - * Level of title, will be rendered as heading tag (e.g. h3). Defaults to level 3. + * Level of title, it will be rendered as heading tag (e.g., h3). Defaults to level 3. */ "titleLevel"?: InterfaceTitleAttributes['level']; } diff --git a/src/components/sbb-action-group/readme.md b/src/components/sbb-action-group/readme.md index 540fe616fb..a65cfb2d99 100644 --- a/src/components/sbb-action-group/readme.md +++ b/src/components/sbb-action-group/readme.md @@ -1,7 +1,7 @@ -The `` component is a generic content container which can contain up to three -action items (`` or `` or other HTML elements) in various allocations. +The `sbb-action-group` component is a generic content container which can contain up to three +action items (`sbb-button` or `sbb-link` or other HTML elements) in various allocations. -### Orientation and horizontal-from +### Orientation The `orientation` property is used to set item's orientation. Possible values are `horizontal` (default) and `vertical`. diff --git a/src/components/sbb-card/readme.md b/src/components/sbb-card/readme.md index 6d36fc590d..2d339d7554 100644 --- a/src/components/sbb-card/readme.md +++ b/src/components/sbb-card/readme.md @@ -44,8 +44,8 @@ The badge is hidden with card sizes `xs` or `s`. ## Card With Action -To add an action to a card, add a `` to the main slot. With the `` -all the card area becomes clickable. +To add an action to a card, add a `sbb-card-action` to the main slot. +With the `sbb-card-action` all the card area becomes clickable. For API details see the [`sbb-card-action` docs](/docs/components-sbb-card-sbb-card-action--docs). ```html @@ -57,14 +57,14 @@ For API details see the [`sbb-card-action` docs](/docs/components-sbb-card-sbb-c ## Accessibility -It's **important** that a descriptive message is being slotted into the unnamed slot of `` +It's **important** that a descriptive message is being slotted into the unnamed slot of `sbb-card-action` as it is used for search engines and screen reader users. ```html Buy a half-fare ticket now ``` -Normally, a `` should be a single action, however, it's possible to place other interactive elements +Normally, a `sbb-card` should be a single action, however, it's possible to place other interactive elements in the card content. Interactive content will automatically be detected and made accessible to click / focus. In cases where there should be only a visual button or link inside the card content without a different action, the `is-static` attribute should be set (e.g. ``). diff --git a/src/components/sbb-checkbox-group/readme.md b/src/components/sbb-checkbox-group/readme.md index 1e7d64504b..1edafabfdb 100644 --- a/src/components/sbb-checkbox-group/readme.md +++ b/src/components/sbb-checkbox-group/readme.md @@ -9,7 +9,7 @@ which are projected inside an unnamed slot. ``` -### Orientation and horizontal-from +### Orientation The `orientation` property is used to set item orientation. Possible values are `horizontal` (default) and `vertical`. The optional property `horizontalFrom` can be used in combination with `orientation='vertical'` to diff --git a/src/components/sbb-expansion-panel/readme.md b/src/components/sbb-expansion-panel/readme.md index 7d65308cda..479d24fbe8 100644 --- a/src/components/sbb-expansion-panel/readme.md +++ b/src/components/sbb-expansion-panel/readme.md @@ -37,7 +37,7 @@ The component has two background options that can be set using the `color` varia ### Disabled -The `disabled` state can be set using the self-named variable. In this state the component can not be collapsed or expanded. +The `disabled` state can be set using the self-named variable. In this state, the component can not be collapsed or expanded. ```html diff --git a/src/components/sbb-footer/readme.md b/src/components/sbb-footer/readme.md index 9d5ca58687..5d0040a01c 100644 --- a/src/components/sbb-footer/readme.md +++ b/src/components/sbb-footer/readme.md @@ -1,19 +1,17 @@ -The `` component is used to display page related information like copyright, contact or other -content related links. There are two variants of the footer. The default, which displays the slotted content in regular -block element approach and the clock-columns variant, which uses a css-grid for displaying the content over different -breakpoints. +The `sbb-footer` component is used to display page related information like copyright, contact or other +content related links. -**Negative variant:** -If using the footer in negative variant, please also apply the negative attribute -to the content where needed (e.g. `sbb-link-list`, `sbb-link` and `sbb-divider`). +### Variants -**Note:** -Content, like sbb-link-list that could come along with a button, needs to be wrapped with a `
` element with a helper -class (`class="sbb-link-list-button-group"`) to be displayed correctly. +There are two variants of the footer: the `variant='default'`, which displays the slotted content in regular +block element approach and the `variant='clock-columns'`, which uses a css-grid for displaying the content over different +breakpoints. -## Usage +**Note:** +Content, like `sbb-link-list` that could come along with a button, needs to be wrapped with a `
` element with a helper +class (`class="sbb-link-list-button-group"`) to be displayed correctly. -Default +Default variant: ```html @@ -58,9 +56,26 @@ Variant clock-columns with wrapped link-list with button: Praise Report property damage + +``` +### Negative + +It's possible to display the footer in `negative` variant; please also apply the negative attribute +to the content where needed (e.g. `sbb-link-list`, `sbb-link` and `sbb-divider`). + +```html + + + Refunds + Lost property office + Complaints + Praise + Report property damage + ``` + diff --git a/src/components/sbb-form-error/readme.md b/src/components/sbb-form-error/readme.md index 17a2b1ec1d..5bba8a5c97 100644 --- a/src/components/sbb-form-error/readme.md +++ b/src/components/sbb-form-error/readme.md @@ -1,21 +1,21 @@ The `sbb-form-error` component can be used to provide an error message. -## Usage +### Slots -The examples below shows how the component is used: +It is possible to provide the error message via an unnamed slot; +the component displays an icon by default, and it can be changed using the `icon` slot. ```html -This field is required! + + This is a required field. + - This is a required field. ``` - - diff --git a/src/components/sbb-form-field-clear/readme.md b/src/components/sbb-form-field-clear/readme.md index 00bf3dfcdd..cc621e1dc2 100644 --- a/src/components/sbb-form-field-clear/readme.md +++ b/src/components/sbb-form-field-clear/readme.md @@ -21,13 +21,6 @@ It currently works with simple inputs and does not support, for example, `select | `negative` | `negative` | Negative coloring variant flag. | `boolean` | `false` | -## Slots - -| Slot | Description | -| ----------- | --------------------------- | -| `"unnamed"` | Slot to render the content. | - - ## Dependencies ### Depends on diff --git a/src/components/sbb-form-field-clear/sbb-form-field-clear.tsx b/src/components/sbb-form-field-clear/sbb-form-field-clear.tsx index 80fc0e9043..80519bc082 100644 --- a/src/components/sbb-form-field-clear/sbb-form-field-clear.tsx +++ b/src/components/sbb-form-field-clear/sbb-form-field-clear.tsx @@ -19,9 +19,6 @@ import { } from '../../global/eventing'; import { i18nClearInput } from '../../global/i18n'; -/** - * @slot unnamed - Slot to render the content. - */ @Component({ shadow: true, styleUrl: 'sbb-form-field-clear.scss', diff --git a/src/components/sbb-form-field/readme.md b/src/components/sbb-form-field/readme.md index d295c7577c..a78e6161e2 100644 --- a/src/components/sbb-form-field/readme.md +++ b/src/components/sbb-form-field/readme.md @@ -1,8 +1,8 @@ -`` is intended to be used as a form input wrapper with label and errors. +The `sbb-form-field` component is intended to be used as a form input wrapper with label and errors. In this document, "form field" refers to the wrapper component `` and "form field control" refers to the component that the `` is wrapping -(e.g. the input, select, etc.) +(e.g., the input, select, etc.) The following components are designed to work inside a ``: diff --git a/src/components/sbb-header-action/readme.md b/src/components/sbb-header-action/readme.md index 8dbfa2f13c..6ce2539fb4 100644 --- a/src/components/sbb-header-action/readme.md +++ b/src/components/sbb-header-action/readme.md @@ -1,20 +1,35 @@ The component represents an action element contained by the [sbb-header](../sbb-header/readme.md) component. -As the [sbb-link](../sbb-link/readme.md), it can be internally rendered as a button or as a link. -Consumers can set the icon and the label; the property `expandFrom` defines the minimum breakpoint -from which the label is displayed. +### Slots -## Usage -Simple button +It is possible to provide a label via an unnamed slot; the component can optionally display a `` +at the component start using the `iconName` property or via custom content using the `icon` slot. ```html -Button text +Text + +Another text +``` + +### Hide label + +If the component's icon is set, the property `expandFrom` can be used to define the minimum breakpoint +from which the label is displayed; below that, only the icon is visible. + +```html +Text ``` -Simple link +### Link/button properties + +As the [sbb-link](../sbb-link/readme.md), the component can be internally rendered as a button or as a link, +depending on the value of the `href` property, so the associated properties are available +(`href`, `target`, `rel` and `download` for link; `type`, `name`, `value` and `form` for button). ```html -Link text +Link + +Button ``` diff --git a/src/components/sbb-header/readme.md b/src/components/sbb-header/readme.md index f26812801f..553564aa4f 100644 --- a/src/components/sbb-header/readme.md +++ b/src/components/sbb-header/readme.md @@ -1,12 +1,25 @@ The `sbb-header` component is a container for actions and a logo, and it is displayed at the top of the page. +### Slots + It has two slots: the first one can contain one or more [sbb-header-action](../sbb-header-action/readme.md) or other action items like `sbb-button` or `sbb-link`, and it is displayed at the left end of the component; the second slot is displayed at the right end, and it can contain a logo, which by default is the [sbb-logo](../sbb-logo/readme.md). +```html + + Menu + Search + +``` + +### Positioning and visibility + The height of the header can be overridden by re-defining the css variable `--sbb-header-height`. +Setting the `expanded` property will cause the `sbb-header` component to take up the full width of the page. + By default, the `sbb-header` has a fixed position at the top of the page; when the page is scrolled down, a box-shadow appears below it and the component remains visible. It's possible to change this behavior by setting the `hideOnScroll` property to `true`, or adding the `hide-on-scroll` @@ -14,9 +27,18 @@ attribute: in this case, the box-shadow is still set, but the component disappea then reappears as soon as it's scrolled up. It's also possible to bind this behaviour to something other than the `document`, using the `scrollOrigin` property, which accepts an `HTMLElement` or the id of the element to search for. +```html + + Search + + + + +``` + To avoid that tabbed/focused elements get hidden behind the header, it's recommended to set the CSS property `scroll-padding-top` -of the `` tag to `var(--sbb-header-height)` or a greater value. With this it's ensured that content -will be visible all the time. +of the `` tag to `var(--sbb-header-height)` or a greater value. +With this, it's ensured that content will be visible all the time. ## Style @@ -27,14 +49,14 @@ Users can customize position and behaviour of actions inside the `sbb-header` co by adding classes to `sbb-header-action` elements and then defining their own style rules. An example has been created with the following requirements: -- 4 action item (with custom icons); +- Four action items (with custom icons); - the first item is always left aligned and has `expand-from` set to `small`; -- the other 3 items are left aligned in breakpoints zero to medium, and right aligned from large to ultra; +- the other three items are left aligned in breakpoints zero to medium, and right aligned from large to ultra; - the last item is not visible in breakpoints zero to small. To achieve this result, a `div` tag with a CSS class named `sbb-header-spacer` was added between the first and the second `sbb-header-action` item, then a class named `last-element` was added to the last one. -Finally, the following custom CSS has been added*. The result can be seen in the home and home--logged-in stories. +Finally, the following custom CSS has been added(*). The result can be seen in the home and home--logged-in stories. ```css .last-element { @@ -73,38 +95,10 @@ set the CSS class `sbb-header-shrinkable` on the desired `sbb-header-action`. ``` -*Technical note: Due the presence of media-query rules, it was not possible to add those rules directly +(*) Technical note: Due the presence of media-query rules, it was not possible to add those rules directly in the component's stories (see also [this Storybook issue](https://github.com/storybookjs/storybook/issues/8820)), so they were wrapped into a `style` tag and added to the Storybook's configuration file named `preview-head.html`. -## Usage - -The examples below shows how to use the component (with shadow on). - -```html - - - Menu - - Search - -``` - -Header with logo link and slotted sbb-logo: - -```html - - Search - - - - -``` - diff --git a/src/components/sbb-icon/readme.md b/src/components/sbb-icon/readme.md index 67035c6cac..6c50b5b8a9 100644 --- a/src/components/sbb-icon/readme.md +++ b/src/components/sbb-icon/readme.md @@ -17,7 +17,7 @@ The example below shows how to render an icon named `app-icon-medium` that point ### Accessibility Similar to an `` element, an icon alone does not convey any useful information for a -screen-reader user. The user of `` must provide additional information pertaining to how +screen-reader user. The user of `sbb-icon` must provide additional information pertaining to how the icon is used. Based on the use-cases described below, `sbb-icon` is marked as `aria-hidden="true"` by default, but this can be overridden by adding `aria-hidden="false"` to the element. diff --git a/src/components/sbb-journey-header/readme.md b/src/components/sbb-journey-header/readme.md index c488129549..c7dd659696 100644 --- a/src/components/sbb-journey-header/readme.md +++ b/src/components/sbb-journey-header/readme.md @@ -1,13 +1,31 @@ The `sbb-journey-header` is a component used to display the journey's details. -The component has two required properties, named `origin` and `destination`, which are the two ends of the journey. +### Origin and destination + +The component has two required properties, named `origin` and `destination`, which represents the two ends of the journey. An icon is placed between them: if the property `roundTrip` is set to false (default), the icon is an arrow pointing to the `destination`, otherwise it is a double arrow to display the round-trip. +```html + + + +``` + +### Display properties + The component has a `level` property, which is passed to its inner `sbb-title` component; it is rendered as a heading from `h1` to `h6`. Default `level` is `3`. The component also has two sizes, named `m` (default) and `l`, and a `negative` background variant. +```html + + + + + +``` + ### Accessibility The component has some hidden elements in order to be correctly read from a screen-reader. @@ -24,26 +42,6 @@ The following one will be read as (locale: ENG): `Connection from Point A to Poi ``` -### Usage - -Basic usage, rendered as `

`: - -```html - -``` - -Size `l`, rendered as `

`: - -```html - -``` - -Negative variant, round-trip: - -```html - -``` - diff --git a/src/components/sbb-link-list/readme.md b/src/components/sbb-link-list/readme.md index 9df05065c5..5546e3d787 100644 --- a/src/components/sbb-link-list/readme.md +++ b/src/components/sbb-link-list/readme.md @@ -1,18 +1,35 @@ -The `` is a collection of sbb-links. It has an optional title which is visually -shown as a level 5 ``. The title is used as the aria-labelledby attribute of the ul -element. The list can be oriented vertically or horizontally. The title will not be display in the -horizontal orientation. +The `` is a component that can be used to collect more `sbb-link`s; +it will automatically set variant `block` on nested `sbb-link` instances, +and it will sync the `textSize` and `negative` property. + +### Title + +The component can display an optional title, which is visually shown as a level-5 `sbb-title` +and is used as the `aria-labelledby` attribute of the `ul` element. +The title is projected using the `title` slot or, alternatively, the `titleContent` property. ```html - + Refunds Loss Report ... ``` - -**NOTE**: `` will automatically set variant `block` on nested `` instances - and will sync the `textSize` and `negative` property. + +### Orientation + +The `orientation` property is used to set links' orientation; possible values are `horizontal` and `vertical` (default). +The optional property `horizontalFrom` can be used in combination with `orientation='vertical'` +to indicate the minimum breakpoint from which the orientation changes to `horizontal`. +The title will not be displayed in the horizontal orientation. + +```html + +Refunds +Loss Report +... + +``` diff --git a/src/components/sbb-link/readme.md b/src/components/sbb-link/readme.md index debdb3b38e..8edeb2eef4 100644 --- a/src/components/sbb-link/readme.md +++ b/src/components/sbb-link/readme.md @@ -1,7 +1,57 @@ -The ``can both be used as an anchor (``) -(if the href property is set) or as a button. If the `` is placed inside another -anchor or button tag, it is internally rendered as a span in order to not break HTML functionality. - +The `` is a component which mimics the native `` tag. + +### Slots + +The link text is provided via an unnamed slot; the component can optionally display a `` using +the `iconName` property or via custom content using the `icon` slot. +By default, the icon is placed at the component's end, but this can be changed using the `iconPlacement` property. + +```html + + Help + + + + Contact + +``` + +### Link/button properties + +The component can be internally rendered as a button or as a link, +depending on the value of the `href` property, so the associated properties are available +(`href`, `target`, `rel` and `download` for link; `type`, `name`, `value` and `form` for button). +If `isStatic` is set, the component will be rendered as a link without any user interaction. +Please note that if the `sbb-link` is placed inside another anchor or button tag, +it is internally rendered as a span in order to not break HTML functionality. + +```html + + Travel-cards and tickets + + + + Travel-cards and tickets + +``` + +### Variants + +The component has two variants (`block`, which is the default, and `inline`), that can be set using the `variant` property, +and it has also three sizes (`xs`, `s`, which is the default, and `m`) that are relevant only in `variant='block`'. +The component can be displayed in `disabled` state using the self-named property. + +```html +Refunds + +

+ Some informative text. + Show more. +

+ +Refunds +``` + diff --git a/src/components/sbb-logo/readme.md b/src/components/sbb-logo/readme.md index 8a0b147444..fa232b6e6d 100644 --- a/src/components/sbb-logo/readme.md +++ b/src/components/sbb-logo/readme.md @@ -1,7 +1,5 @@ -The `` ensures his aspect ratio and protective room. To use the logo, -please define the desired height or width on ``. - -## Usage +The `sbb-logo` is used as a wrapper for the SBB logo and ensures his aspect ratio and protective room. +To use the component, please define the desired height or width on ``. ```html - + +``` + +### Negative + +The component has a negative variant which can be set using the `negative` property. + +```html + +``` + +### Aspect ratio + +The aspect ratio of the logo can be changed using the `protectiveRoom` property. +Possible values are `ideal` (default), `minimal` and `none`. + +```html + ``` diff --git a/src/components/sbb-map-container/readme.md b/src/components/sbb-map-container/readme.md index c685223ad3..6020280be8 100644 --- a/src/components/sbb-map-container/readme.md +++ b/src/components/sbb-map-container/readme.md @@ -1,8 +1,22 @@ This component is the layout container for the disruption map, the level 3 navigation and the -future ATLAS. It provides two slots. One unnamed slot for the sidebar content and one named ("map") slot for map. -On mobile the map is sticky above the sidebar and the sidebar content is scrolling over the map. On desktop is the sidebar -and the map in a two column layout side by side.The component come along with a height calculation that subtracts the height -of the header. The header height can be overriden with --sbb-map-container-margin-start if needed. +future ATLAS. + +### Slots +It provides two slots: one unnamed slot for the sidebar content, and one named `map` for the map. + +```html + +
Content
+
Here comes the map.
+ +``` +On mobile, the map is sticky above the sidebar, and the sidebar content is scrolling over the map. +On desktop, the sidebar and the map are shown in a two column layout side by side. + +### Style + +The component comes along with a height calculation that subtracts the height of the header. +The header height can be overridden setting the variable `--sbb-map-container-margin-start`, if needed. diff --git a/src/components/sbb-menu-action/readme.md b/src/components/sbb-menu-action/readme.md index 9e539943fc..5b87b26e2e 100644 --- a/src/components/sbb-menu-action/readme.md +++ b/src/components/sbb-menu-action/readme.md @@ -1,15 +1,37 @@ The component represents an action element contained by the [sbb-menu](../sbb-menu/readme.md) component. -As the [sbb-link](../sbb-link/readme.md), it can be internally rendered as a button or as a link, -depending on the value of the `href` property. +### Slots -A [sbb-icon](../sbb-icon/readme.md) will be rendered via the `icon-name` property; otherwise consumers can provide -their own content via slot named `icon`. +It is possible to provide a label via an unnamed slot; the component can optionally display a `` +at the component start using the `iconName` property or via custom content using the `icon` slot. -An amount can be rendered at the end of the action element as white text in a red circle via the `amount` property. +```html +Text +Another text +``` + +### Amount + +An amount can be rendered at the end of the action element as white text in a red circle via the `amount` property. + +```html +Amount text +``` + +### Link/button properties + +As the [sbb-link](../sbb-link/readme.md), the component can be internally rendered as a button or as a link, +depending on the value of the `href` property, so the associated properties are available +(`href`, `target`, `rel` and `download` for link; `type`, `name`, `value` and `form` for button). + +```html +Link + +Button +``` -### Spacing +### Style For cases where smaller outer paddings are needed, you can set the css variable `--sbb-menu-action-outer-horizontal-padding` to your desired outer padding. diff --git a/src/components/sbb-menu/readme.md b/src/components/sbb-menu/readme.md index 5c571dd59e..f0f51a150f 100644 --- a/src/components/sbb-menu/readme.md +++ b/src/components/sbb-menu/readme.md @@ -1,16 +1,16 @@ -The `sbb-menu` is a component that can be attached to any element (trigger) to display a context menu. -The menu appears on trigger left click. +The `sbb-menu` is a component that can be attached to any element to open and display a custom context menu, +which allows to perform actions relevant to the current task or to navigate within or outside the application +by using the `sbb-menu-action` component along with it. -On mobile, the menu is displayed as a sheet with a backdrop; -on desktop it will be shown as a floating menu and will calculate the optimal position relative to the trigger element -by evaluating the available space with the following priority: start/below, start/above, end/below, end/above. +### Trigger and content -If only `sbb-menu-action` components are provided inside the menu, the items are automatically grouped within a list using `