From 8e728d5c4db614d11d7e7602f298d629cdd6ea05 Mon Sep 17 00:00:00 2001 From: Davide Mininni Date: Wed, 20 Sep 2023 17:38:32 +0200 Subject: [PATCH] docs: add cross-reference links, general review (part four) --- src/components/sbb-autocomplete/readme.md | 2 +- .../sbb-navigation-action/readme.md | 3 +- src/components/sbb-navigation-list/readme.md | 5 +- .../sbb-navigation-marker/readme.md | 4 +- src/components/sbb-navigation/readme.md | 13 +++-- src/components/sbb-notification/readme.md | 31 ++++++++---- src/components/sbb-optgroup/readme.md | 11 +++-- src/components/sbb-option/readme.md | 9 ++-- .../sbb-radio-button-group/readme.md | 15 +++--- src/components/sbb-radio-button/readme.md | 21 +++++--- src/components/sbb-select/readme.md | 49 ++++++++++--------- src/components/sbb-selection-panel/readme.md | 11 +++-- src/components/sbb-signet/readme.md | 4 +- src/components/sbb-skiplink-list/readme.md | 3 +- src/components/sbb-slider/readme.md | 4 +- 15 files changed, 111 insertions(+), 74 deletions(-) diff --git a/src/components/sbb-autocomplete/readme.md b/src/components/sbb-autocomplete/readme.md index 1ae3cfcce4a..3f39d9ffc85 100644 --- a/src/components/sbb-autocomplete/readme.md +++ b/src/components/sbb-autocomplete/readme.md @@ -72,7 +72,7 @@ The displayed `sbb-option` can be collected into groups using `sbb-optgroup` ele The `sbb-option` emits the `option-selected` event when selected via user interaction. -## Keyboard interaction +### Keyboard interaction The options panel opens on `focus`, `click` or `input` events on the trigger element, or on `ArrowDown` keypress; it can be closed on backdrop click, or using the `Escape` or `Tab` keys. diff --git a/src/components/sbb-navigation-action/readme.md b/src/components/sbb-navigation-action/readme.md index bf6ba9fccdd..30e852a04a3 100644 --- a/src/components/sbb-navigation-action/readme.md +++ b/src/components/sbb-navigation-action/readme.md @@ -1,5 +1,6 @@ The `sbb-navigation-action` component is an action element contained by -a [sbb-navigation-list](../sbb-navigation-list/readme.md) component or a [sbb-navigation-marker](../sbb-navigation-marker/readme.md) component. +a [sbb-navigation-list](/docs/components-sbb-navigation-sbb-navigation-list--docs) component +or a [sbb-navigation-marker](/docs/components-sbb-navigation-sbb-navigation-marker--docs) component. ### Link / button properties diff --git a/src/components/sbb-navigation-list/readme.md b/src/components/sbb-navigation-list/readme.md index 04ffa6cb5a3..b65498f790a 100644 --- a/src/components/sbb-navigation-list/readme.md +++ b/src/components/sbb-navigation-list/readme.md @@ -1,5 +1,5 @@ -The `sbb-navigation-list` component is a collection of [sbb-navigation-action](../sbb-navigation-action/readme.md). -Its intended use is inside a [sbb-navigation-section](../sbb-navigation-section/readme.md) component. +The `sbb-navigation-list` component is a collection of [sbb-navigation-action](/docs/components-sbb-navigation-sbb-navigation-action--docs). +Its intended use is inside a [sbb-navigation-section](/docs/components-sbb-navigation-sbb-navigation-section--docs) component. Optionally, a label can be provided via slot via the self-named property or the self-named slot. ```html @@ -10,7 +10,6 @@ Optionally, a label can be provided via slot via the self-named property or the ``` - diff --git a/src/components/sbb-navigation-marker/readme.md b/src/components/sbb-navigation-marker/readme.md index 1bae51dce46..12be545f461 100644 --- a/src/components/sbb-navigation-marker/readme.md +++ b/src/components/sbb-navigation-marker/readme.md @@ -1,5 +1,5 @@ -The `sbb-navigation-marker` component is a collection of [sbb-navigation-action](../sbb-navigation-action/readme.md). -Its intended use is inside a [sbb-navigation](../sbb-navigation/readme.md) component. +The `sbb-navigation-marker` component is a collection of [sbb-navigation-action](/docs/components-sbb-navigation-sbb-navigation-action--docs). +Its intended use is inside a [sbb-navigation](/docs/components-sbb-navigation-sbb-navigation--docs) component. ```html diff --git a/src/components/sbb-navigation/readme.md b/src/components/sbb-navigation/readme.md index 41fc5084ef3..b93f5f40cd4 100644 --- a/src/components/sbb-navigation/readme.md +++ b/src/components/sbb-navigation/readme.md @@ -6,15 +6,15 @@ Some of its features are: - creates a backdrop for disabling interaction below the navigation; - disables scrolling of the page content while open; - manages focus properly by setting it on the first focusable element; -- can act as a host for components as [sbb-navigation-list](../sbb-navigation-list/readme.md), [sbb-navigation-marker](../sbb-navigation-marker/readme.md) and [sbb-navigation-section](../sbb-navigation-section/readme.md); +- can act as a host for components as [sbb-navigation-list](/docs/components-sbb-navigation-sbb-navigation-list--docs), + [sbb-navigation-marker](/docs/components-sbb-navigation-sbb-navigation-marker--docs) + and [sbb-navigation-section](/docs/components-sbb-navigation-sbb-navigation-section--docs); -## Trigger +### Interaction To display the `sbb-navigation` component you can either provide a trigger element using the `trigger` property, or call the `open()` method on the `sbb-navigation` component. -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-navigation-z-index`. - ```html Navigation trigger @@ -48,6 +48,11 @@ The default `z-index` of the component is set to `1000`; to specify a custom sta ``` +### Style + +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-navigation-z-index`. + ## Accessibility When a navigation action is marked to indicate the user is currently on that page, `aria-current="page"` should be set on that action. diff --git a/src/components/sbb-notification/readme.md b/src/components/sbb-notification/readme.md index 97cb30a03da..757a8029037 100644 --- a/src/components/sbb-notification/readme.md +++ b/src/components/sbb-notification/readme.md @@ -21,7 +21,18 @@ The `sbb-notification` is structured in the following way: Note that the notification only supports inline links, therefore any slotted link will be forced to be a `variant="inline"` link. -### Type +### States + +It is possible to display the component in `readonly` state by using the self-named property. +In this case, the close button will not be shown. + +```html + + ... + +``` + +### Variants The `sbb-notification` supports four types: `info` (default), `success`, `warn` and `error`, based on the type of the information displayed. @@ -33,7 +44,7 @@ The `sbb-notification` supports four types: `info` (default), `success`, `warn` ... ``` -### Dismissal +### Interaction Inline notifications do not dismiss automatically. They persist on the page until the user dismisses them or takes action that resolves the notification. @@ -41,7 +52,7 @@ They persist on the page until the user dismisses them or takes action that reso By default, a close button is displayed to dismiss inline notifications. Including the close button is optional and should not be included if it is critical for a user to read or interact with the notification by setting the `readonly` property to `true`. -### Animation +### Style If the `sbb-notification` host needs a margin, in order to properly animate it on open/close, we suggest using the `--sbb-notification-margin` variable to set it. @@ -52,13 +63,13 @@ For example, use `--sbb-notification-margin: 0 0 var(--sbb-spacing-fixed-4x) 0` ## Properties -| Property | Attribute | Description | Type | Default | -| ------------------ | ------------------- | ------------------------------------------------------------------------------------------------------- | ------------------------------------------ | ----------- | -| `disableAnimation` | `disable-animation` | Whether the animation is enabled. | `boolean` | `false` | -| `readonly` | `readonly` | Whether the notification is readonly. In readonly mode, there is no dismiss button offered to the user. | `boolean` | `false` | -| `titleContent` | `title-content` | Content of title. | `string` | `undefined` | -| `titleLevel` | `title-level` | Level of title, will be rendered as heading tag (e.g. h3). Defaults to level 3. | `"1" \| "2" \| "3" \| "4" \| "5" \| "6"` | `'3'` | -| `type` | `type` | The type of the notification. | `"error" \| "info" \| "success" \| "warn"` | `'info'` | +| Property | Attribute | Description | Type | Default | +| ------------------ | ------------------- | --------------------------------------------------------------------------------------------------------- | ------------------------------------------ | ----------- | +| `disableAnimation` | `disable-animation` | Whether the animation is enabled. | `boolean` | `false` | +| `readonly` | `readonly` | Whether the notification is readonly. In readonly mode, there is no dismissal button offered to the user. | `boolean` | `false` | +| `titleContent` | `title-content` | Content of title. | `string` | `undefined` | +| `titleLevel` | `title-level` | Level of title,0it will be rendered as heading tag (e.g. h3). Defaults to level 3. | `"1" \| "2" \| "3" \| "4" \| "5" \| "6"` | `'3'` | +| `type` | `type` | The type of the notification. | `"error" \| "info" \| "success" \| "warn"` | `'info'` | ## Events diff --git a/src/components/sbb-optgroup/readme.md b/src/components/sbb-optgroup/readme.md index a4f5c0e8583..aa4cfd690d5 100644 --- a/src/components/sbb-optgroup/readme.md +++ b/src/components/sbb-optgroup/readme.md @@ -1,7 +1,10 @@ -The `sbb-optgroup` is a component used to group more `sbb-option` within a `sbb-autocomplete` or a `sbb-select` component. -A `sbb-divider` is displayed at the bottom of the component. +The `sbb-optgroup` is a component used to group more [sbb-option](/docs/components-sbb-option-sbb-option--docs) +within a [sbb-autocomplete](/docs/components-sbb-autocomplete--docs) +or a [sbb-select](/docs/components-sbb-select--docs) component. -### Slot +A [sbb-divider](/docs/components-sbb-divider--docs) is displayed at the bottom of the component. + +### Slots It is possible to provide a set of `sbb-option` via an unnamed slot; the component has also a `label` property as name of the group. @@ -16,7 +19,7 @@ the component has also a `label` property as name of the group. ### States -The component has a `disabled` property which, if set to `true`, sets all the `sbb-option` in the group as disabled. +The component has a `disabled` property which sets all the `sbb-option` in the group as disabled. ```html diff --git a/src/components/sbb-option/readme.md b/src/components/sbb-option/readme.md index 34b573a8d15..7490efaa2d1 100644 --- a/src/components/sbb-option/readme.md +++ b/src/components/sbb-option/readme.md @@ -1,4 +1,5 @@ -The `sbb-option` is a component which can be used to display items in components like `sbb-autocomplete` or `sbb-select`. +The `sbb-option` is a component which can be used to display items in components like +[sbb-autocomplete](/docs/components-sbb-autocomplete--docs) or a [sbb-select](/docs/components-sbb-select--docs). ### Slots @@ -14,8 +15,10 @@ Icon space can be reserved even if the `iconName` property is not set by overrid ### States -Like the native `option`, the component has a `value` property. The `selected`, `disabled` and `active` properties are -connected to the self-named states. When disabled, the selection via click is prevented. +Like the native `option`, the component has a `value` property. + +The `selected`, `disabled` and `active` properties are connected to the self-named states. +When disabled, the selection via click is prevented. If the `sbb-option` is nested in a `sbb-optgroup` component, it inherits from the parent the `disabled` state. ```html diff --git a/src/components/sbb-radio-button-group/readme.md b/src/components/sbb-radio-button-group/readme.md index 91d29c76181..a3dc27d3411 100644 --- a/src/components/sbb-radio-button-group/readme.md +++ b/src/components/sbb-radio-button-group/readme.md @@ -1,7 +1,6 @@ -The `sbb-radio-button-group` is a component which can be used as a wrapper for a collection of `sbb-radio-button`, -or, alternatively, for a collection of `sbb-selection-panel`. -Pressing a `sbb-radio-button` checks it and unchecks the previously selected one, if any. -They can also be controlled programmatically by setting the value property of the parent radio group to the value of the radio. +The `sbb-radio-button-group` is a component which can be used as a wrapper for +a collection of [sbb-radio-button](/docs/components-sbb-radio-button-sbb-radio-button--docs)s, +or, alternatively, for a collection of [sbb-selection-panel](/docs/components-sbb-selection-panel--docs)s. ```html @@ -12,6 +11,10 @@ They can also be controlled programmatically by setting the value property of th ``` + +Pressing a `sbb-radio-button` checks it and unchecks the previously selected one, if any. +They can also be controlled programmatically by setting the value property of the parent radio group to the value of the radio. + Please note that within a `sbb-radio-button-group`, only one `sbb-radio-button` can be selected at a time; if you need to select more than one item, it is recommended to use the `sbb-checkbox-group` component. @@ -34,8 +37,6 @@ The radio group can have different states: ``` -### Deselecting Radios - In order to deselect a `sbb-radio-button` inside the `sbb-radio-button-group`, you can use the `allowEmptySelection` property, which will be proxied to the inner `sbb-radio-button` enabling their deselection (by default, a selected `sbb-radio-button` cannot be deselected). @@ -46,7 +47,7 @@ enabling their deselection (by default, a selected `sbb-radio-button` cannot be ``` -### Orientation +### Style 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-radio-button/readme.md b/src/components/sbb-radio-button/readme.md index 9d7f80f3832..044ef604427 100644 --- a/src/components/sbb-radio-button/readme.md +++ b/src/components/sbb-radio-button/readme.md @@ -1,5 +1,6 @@ -The `sbb-radio-button` component provides the same functionality as a native `` -enhanced with the SBB Design: use multiple `sbb-radio-button` components inside a `sbb-radio-button-group` component +The `sbb-radio-button` component provides the same functionality +as a native `` enhanced with the SBB Design: use multiple `sbb-radio-button` components +inside a [sbb-radio-button-group](/docs/components-sbb-radio-button-sbb-radio-button-group--docs) component in order to display a radio input within a group. ```html @@ -11,14 +12,22 @@ in order to display a radio input within a group. ### States -It is possible to display the component in `disabled` or `checked` state by using the self-named property. -The component has a `required` property, which can be useful for setting a custom `sbb-form-error` message within a `sbb-form-field`. +It is possible to display the component in `disabled` or `checked` state by using the self-named properties. + +The component has a `required` property, which can be useful +for setting a custom [sbb-form-error](/docs/components-sbb-form-field-sbb-form-error--docs) message +within a [sbb-form-field](/docs/components-sbb-form-field-sbb-form-field--docs). + The `allowEmptySelection` property allows user to deselect the component. ```html -Option one +Option one + +Option two + +Option three -Option two +Option four ``` ### Style diff --git a/src/components/sbb-select/readme.md b/src/components/sbb-select/readme.md index 9672ecec5c2..1515658e2d7 100644 --- a/src/components/sbb-select/readme.md +++ b/src/components/sbb-select/readme.md @@ -1,11 +1,13 @@ The `sbb-select` is a component which provides a list of selectable options in an overlay panel, -emulating the behaviour of a native `select`. +emulating the behaviour of a native `