From 9283d04ab0d0f98b28b21982df38f1c78906ada4 Mon Sep 17 00:00:00 2001 From: Davide Mininni Date: Wed, 20 Sep 2023 18:07:41 +0200 Subject: [PATCH] docs: add cross-reference links, general review (part five) --- src/components/sbb-tab-group/readme.md | 9 ++-- src/components/sbb-tab-title/readme.md | 43 ++++++++------------ src/components/sbb-tag-group/readme.md | 15 ++++--- src/components/sbb-tag/readme.md | 4 +- src/components/sbb-time-input/readme.md | 7 ++-- src/components/sbb-title/readme.md | 2 +- src/components/sbb-toast/readme.md | 6 +-- src/components/sbb-toggle-check/readme.md | 7 ++-- src/components/sbb-toggle-option/readme.md | 3 +- src/components/sbb-toggle/readme.md | 8 ++-- src/components/sbb-tooltip-trigger/readme.md | 3 +- src/components/sbb-tooltip/readme.md | 28 +++++++------ 12 files changed, 71 insertions(+), 64 deletions(-) diff --git a/src/components/sbb-tab-group/readme.md b/src/components/sbb-tab-group/readme.md index 2c9ae337a86..177a86073fc 100644 --- a/src/components/sbb-tab-group/readme.md +++ b/src/components/sbb-tab-group/readme.md @@ -1,6 +1,7 @@ The `sbb-tab-group` is a component used to organize and gather tabs that the user can navigate through; use it when you want to provide navigation within blocks of content, instead of showing everything in one place or requiring the user to navigate between several different views. + Each tab has a related content, distinct from other tabs' content; tab panels can present different sections of content and include text, images, forms, other tab groups, etc. @@ -17,9 +18,10 @@ tab panels can present different sections of content and include text, images, f ``` -In order to display a tab label within the tab bar, provide an `sbb-tab-title` right before the related tab content; -please refer to the `sbb-tab-title` documentation for more details. -The content element should be wrapped in a `div`, a `section` or an `article` and placed right after its relative tab title. +In order to display a tab label within the tab bar, provide a `sbb-tab-title` right before its related tab content; +please refer to the [sbb-tab-title](/docs/components-sbb-tab-sbb-tab-title--docs) documentation for more details. + +**Note:** the content element should be wrapped in a `div`, a `section` or an `article` and placed right after its relative `sbb-tab-title`. Tab groups can also be nested, which means that a tab's content block can be represented by another `sbb-tab-group`, as shown in the "Nested Tab Groups" example. @@ -27,6 +29,7 @@ as shown in the "Nested Tab Groups" example. A tab can be selected, unselected, or in `disabled` state; disable a tab to mark it as unavailable. Disabled tabs cannot be focused and may be invisible to assistive technologies such as screen readers. + It's possible to set the first selected tab using the `initialSelectedIndex` property. ```html diff --git a/src/components/sbb-tab-title/readme.md b/src/components/sbb-tab-title/readme.md index cdfc28ec735..e7182ba59e5 100644 --- a/src/components/sbb-tab-title/readme.md +++ b/src/components/sbb-tab-title/readme.md @@ -1,35 +1,30 @@ -The `sbb-tab-title` is a component which is meant to be used in combination with the `sbb-tab-group` component +The `sbb-tab-title` is a component which is meant to be used in combination with the +[sbb-tab-group](/docs/components-sbb-tab-sbb-tab-group--docs) component in order to display a tab label within the tab bar. ```html - - - Tab Label - - +Tab Label ``` ### Slots It is possible to provide a label via an unnamed slot; the component can optionally display a `sbb-icon` at the component start using the `iconName` property or via custom content using the `icon` slot. + It's also possible to display a numeric amount at the component's end using the `amount` property or slot. -It's possible to change the label's heading tag using the `level` property. + +The label's heading tag can be changed using the `level` property. ```html - - - Tab Label - - - - - - - Tab Label - 123 - - + + Tab Label + + + + + Tab Label + 123 + ``` ### States @@ -37,11 +32,9 @@ It's possible to change the label's heading tag using the `level` property. It is possible to display the component in `disabled` state by using the self-named property. ```html - - - Tab Label - - + + Tab Label + ``` diff --git a/src/components/sbb-tag-group/readme.md b/src/components/sbb-tag-group/readme.md index f6085fee34c..39d8f8d9cdb 100644 --- a/src/components/sbb-tag-group/readme.md +++ b/src/components/sbb-tag-group/readme.md @@ -1,7 +1,8 @@ The `sbb-tag-group` component is used as a container for one or multiple `sbb-tag` components, which are projected inside the unnamed slot. -To work properly, it's mandatory to provide a value to each `sbb-tag`. See its documentation for more details. +To work properly, it's mandatory to provide a value to each `sbb-tag`. +See [its documentation]((/docs/components-sbb-tag-sbb-tag--docs)) for more details. ```html @@ -12,7 +13,9 @@ To work properly, it's mandatory to provide a value to each `sbb-tag`. See its d ``` -## Exclusive selection vs. multiple selection +### Interaction + +#### Exclusive selection vs. multiple selection By default, `sbb-tag-group` acts like a radio-button group: only one item can be selected. In this mode, the value of the `sbb-tag-group` will reflect the value of the selected `sbb-tag`. @@ -29,12 +32,12 @@ In this mode the value of the `sbb-tag-group` is an array containing all values ``` -### Changing multiple property during run time +#### Changing multiple property during run time There is no support for changing multiple mode during run time (e.g., update value automatically). So this flag should be provided at component's instantiation time. -### Advanced usage: multiple and exclusive mixed +#### Advanced usage: multiple and exclusive mixed ```ts const uncheckAllTag = () => { @@ -65,8 +68,8 @@ const uncheckTags = () => { The property `listAccessibilityLabel` is forwarded as `aria-label` to the inner list that the component uses to display the tags, to use the implicit `role="list"` of the `ul`. -If the `listAccessibilityLabel` property is not defined, the `sbb-tag-group` surrounding the buttons -applies `role="group"` to convey the association between the individual `sbb-tag`s. +If the `listAccessibilityLabel` property is not defined, the `sbb-tag-group` surrounding the buttons applies `role="group"` +to convey the association between the individual `sbb-tag`s. When using the `role="group"`, each `sbb-tag-group` element should be given a label with `aria-label` or `aria-labelledby`, that communicates the collective meaning of all `sbb-tag`s. diff --git a/src/components/sbb-tag/readme.md b/src/components/sbb-tag/readme.md index 0ea528708d4..b8852c9b07c 100644 --- a/src/components/sbb-tag/readme.md +++ b/src/components/sbb-tag/readme.md @@ -1,5 +1,5 @@ The `sbb-tag` is a component that can be used as a filter in order to categorize a large amount of information. -It's intended to be used inside an `sbb-tag-group`. +It's intended to be used inside the [sbb-tag-group](/docs/components-sbb-tag-sbb-tag-group--docs) component. ```html All @@ -9,6 +9,7 @@ It's intended to be used inside an `sbb-tag-group`. It is possible to provide a label via an unnamed slot; the component can optionally display a `sbb-icon` at the component start using the `iconName` property or via custom content using the `icon` slot. + It's also possible to display a numeric amount at the component's end using the `amount` property or slot. ```html @@ -44,7 +45,6 @@ It's recommended to check the parent's `sbb-tag-group` for the value. The component imitates an `button` element to provide an accessible experience. The state is reflected via `aria-pressed` attribute. - diff --git a/src/components/sbb-time-input/readme.md b/src/components/sbb-time-input/readme.md index 1461468391f..ca21494684b 100644 --- a/src/components/sbb-time-input/readme.md +++ b/src/components/sbb-time-input/readme.md @@ -1,7 +1,7 @@ The `sbb-time-input` is a component that displays the typed value as a formatted time (HH:mm). The component allows the insertion of up to 4 numbers, possibly with a separator char like `.`, `:`, `,` or `-`, -then automatically formats the value as time and displays it (see the "Format example" paragraph). +then automatically formats the value as time and displays it (see ["Format example"](#format-example)). 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. @@ -25,11 +25,12 @@ If the `sbb-time-input` is used within a `sbb-form-field` with a native input, t The initial value can be set using the `value` property (string) of the `input`or the `setValueAsDate()` method of the `sbb-time-input`. When the input changes, if it is valid, the component updates the `value` of the `input`. + To get the value as a `Date` object, the `getValueAsDate()` method of the `sbb-time-input` can be called. The date is constructed like following: the start date is set to 01.01.1970, 00:00:00 UTC, then the typed hours and minuted are added, e.g.: with a value of `12:34`, the `getValueAsDate()` will be 01.01.1970, 12:34:00 UTC. -If the value is invalid because not real (e.g., 12:61 or 25:30), the component does not format the `value`, +If the value is invalid because not real (e.g. 12:61 or 25:30), the component does not format the `value`, and will return `null` if `getValueAsDate()` was called. ### Format example @@ -51,7 +52,7 @@ See the table below for some formatting examples: | 12,34 | 12:34 | | 12-34 | 12:34 | -## Validation Change +## Events Whenever the validation state changes (e.g., a valid value becomes invalid or vice-versa), the `validationChange` event is emitted. diff --git a/src/components/sbb-title/readme.md b/src/components/sbb-title/readme.md index 45944c82891..575742745bb 100644 --- a/src/components/sbb-title/readme.md +++ b/src/components/sbb-title/readme.md @@ -1,4 +1,4 @@ -The `sbb-title` is a component which renders an heading element according to the provided `level` (default: `1`). +The `sbb-title` is a component which renders a heading element according to the provided `level` (default: `1`). ```html Hello diff --git a/src/components/sbb-toast/readme.md b/src/components/sbb-toast/readme.md index a1f21574dda..ef0d8ed98c9 100644 --- a/src/components/sbb-toast/readme.md +++ b/src/components/sbb-toast/readme.md @@ -13,7 +13,7 @@ if a new `sbb-toast` is opened while a previous message is still showing, the ol ### Important note You should carefully consider every use of the `sbb-toast` component since it can be a source of stress for people with visual impairments -(see the [accessibility](#accessibility) section for more info). +(see the ["Accessibility"](#accessibility) section for more info). Here are a few tips for correct usage: * Try to avoid actions inside a `sbb-toast` since they are not easily reachable; @@ -54,7 +54,7 @@ The time before the component auto-closing can be set with the `timeout` propert The position on the page where the toast will be opened can be configured with the `position` property, which accepts all the combinations of the vertical positions `top` and `bottom` -with the horizontal positions `left`, `start`, `center`, `right` and `end` (default: 'bottom-center'). +with the horizontal positions `left`, `start`, `center`, `right` and `end` (default: `bottom-center`). ```html document.querySelector('sbb-toast').open() } /> @@ -77,7 +77,7 @@ Check [ARIA live regions](https://developer.mozilla.org/en-US/docs/Web/Accessibi The `sbb-toast` does not move focus to the toast element, because it would disrupt users in the middle of a workflow. For any action offered in the `sbb-toast`, your application should provide an alternative way to perform the action -(e.g., a keyboard combination). +(e.g. a keyboard combination). Avoid setting a `timeout` for toasts that have an action available, as screen reader users may want to navigate to the toast element to activate the action. diff --git a/src/components/sbb-toggle-check/readme.md b/src/components/sbb-toggle-check/readme.md index b789bb731b7..11a002a58a7 100644 --- a/src/components/sbb-toggle-check/readme.md +++ b/src/components/sbb-toggle-check/readme.md @@ -9,7 +9,7 @@ enhanced with the SBB Design. It is possible to provide a label via an unnamed slot; the component can optionally display a `sbb-icon` using the `iconName` property or via custom content using the `icon` slot. -The icon can be at the component start or end based on the value of `labelPosition` property (default: `after`). +The icon can be at the component start or end based on the value of the `labelPosition` property (default: `after`). ```html @@ -21,8 +21,6 @@ The icon can be at the component start or end based on the value of `labelPositi ``` -If you don't want the label to appear next to the toggle-check, you can use `aria-label` to specify an appropriate label. - ### States The component can be displayed in `checked` or `disabled` states using the self-named properties. @@ -44,7 +42,8 @@ The `sbb-toggle-check` component uses an internal `` to This internal checkbox receives focus and is automatically labelled by the text content of the `sbb-toggle-check` element. Avoid adding other interactive controls into the content of `sbb-toggle-check`, as this degrades the experience for users of assistive technology. -Always provide an accessible label via `aria-label` for checkboxes without descriptive text content. +If you don't want the label to appear next to the `sbb-toggle-check` component, +you can not provide it and then use `aria-label` to specify an appropriate label for screen-readers. ```html diff --git a/src/components/sbb-toggle-option/readme.md b/src/components/sbb-toggle-option/readme.md index c1c6f932edd..f7b39ec5760 100644 --- a/src/components/sbb-toggle-option/readme.md +++ b/src/components/sbb-toggle-option/readme.md @@ -1,4 +1,5 @@ -The `sbb-toggle-option` component is used inside the `sbb-toggle` in order to render the toggle's options. +The `sbb-toggle-option` component is used inside the +[sbb-toggle](/docs/components-sbb-toggle-sbb-toggle--docs) in order to render the toggle's options. ```html Option diff --git a/src/components/sbb-toggle/readme.md b/src/components/sbb-toggle/readme.md index 867f14a992e..5c84676f16d 100644 --- a/src/components/sbb-toggle/readme.md +++ b/src/components/sbb-toggle/readme.md @@ -1,7 +1,9 @@ -The `sbb-toggle` component is a wrapper for two `sbb-toggle-option` that can be selected by the user. +The `sbb-toggle` component is a wrapper for a couple of [sbb-toggle-option](/docs/components-sbb-toggle-sbb-toggle-option--docs)s +that can be selected by the user; it is useful for switching between views within the content -Their behavior is similar to `sbb-tab-group` or `sbb-radio-button-group`, where selecting an option deselects the previously selected one. -The `sbb-toggle` component is useful for switching between views within the content. +Their behavior is similar to [sbb-tab-group](/docs/components-sbb-tab-sbb-tab-group--docs) +or [sbb-radio-button-group](/docs/components-sbb-radio-button-sbb-radio-button-group--docs), +where selecting an option deselects the previously selected one. ```html diff --git a/src/components/sbb-tooltip-trigger/readme.md b/src/components/sbb-tooltip-trigger/readme.md index ccd8d0c05ea..c173b07750b 100644 --- a/src/components/sbb-tooltip-trigger/readme.md +++ b/src/components/sbb-tooltip-trigger/readme.md @@ -1,4 +1,5 @@ -The `sbb-tooltip-trigger` component is used to trigger a tooltip by pressing or hovering on a button. +The `sbb-tooltip-trigger` component is used to trigger a [sbb-tooltip](/docs/components-sbb-tooltip-sbb-tooltip--docs) +by pressing or hovering on it. ```html diff --git a/src/components/sbb-tooltip/readme.md b/src/components/sbb-tooltip/readme.md index ad136ef71f3..713977cde75 100644 --- a/src/components/sbb-tooltip/readme.md +++ b/src/components/sbb-tooltip/readme.md @@ -1,9 +1,15 @@ -The `sbb-tooltip` component can be useful for displaying additional information on mouse hover or click of a trigger element. -The information included should be contextual, useful, and provide additional communication and clarity to the user. +The `sbb-tooltip` component can be useful for displaying contextual and additional information on mouse hover or click of a trigger element. + +The component could be used: + +- to describe icons and buttons; +- when more information is useful to help a user make decisions; +- when an element needs more context or explanation; +- when defining a term or inline item. The component must be connected with the trigger element using the `trigger` property, which accepts the id of the element, or directly its reference; -the `sbb-tooltip-trigger` is meant to be used as trigger. +the [sbb-tooltip-trigger](/docs/components-sbb-tooltip-sbb-tooltip-trigger--docs) is meant to be used as trigger. ```html @@ -13,8 +19,11 @@ the `sbb-tooltip-trigger` is meant to be used as trigger. ``` +### Interaction + The `sbb-tooltip` can be dismissed by clicking on an interactive element within its content, by clicking on the close button or by performing another action on the page. + You can also indicate that an element within the tooltip content should close the `sbb-tooltip` when clicked by marking it with the `sbb-tooltip-close` attribute; it's also possible to hide the default close button using the `hideCloseButton` property. @@ -32,6 +41,7 @@ it's also possible to hide the default close button using the `hideCloseButton` You can also indicate that the `sbb-tooltip` should be shown on hover with the property `hoverTrigger` and set a custom delay for the open and close animations (defaults to 0). In this case, the default close button is hidden. + If hover is not supported by the current device, the component will be triggered on click/tap as default. The `sbb-tooltip` will automatically disappear after the hiding delay if neither the trigger element nor the tooltip are on hover or if another action is performed on the page. @@ -52,17 +62,13 @@ The `sbb-tooltip` automatically calculates where it should place itself, based o 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-tooltip-z-index`. -### When to use - -- Describe icons and buttons. -- When more information is useful to help a user make decisions. -- When an element needs more context or explanation. -- When defining a term or inline item. - ## Accessibility +As the tooltip opens, the focus will automatically be set to the first focusable item within the component. + To make screen-readers announce the tooltip content when the trigger is focused, associate the trigger with the `sbb-tooltip` via `aria-describedby` and `id` as shown below. + If the tooltip trigger is a `sbb-tooltip-trigger` component, set `role="button"` on it, since the `aria-describedby` attribute can be used with semantic HTML elements and with elements that have an ARIA `role`. @@ -89,8 +95,6 @@ that have an ARIA `role`. ``` -As the tooltip opens, the focus will automatically be set to the first focusable item within the component. -