diff --git a/CODING_STANDARDS.md b/CODING_STANDARDS.md index 7315833dfa..229940c917 100644 --- a/CODING_STANDARDS.md +++ b/CODING_STANDARDS.md @@ -45,6 +45,21 @@ In SCSS code, always use `//` style comments. In HTML code, use `` comments, which will be stripped when packaging a build. +#### Write clear and exhaustive documentation + +Every time a component is created, a `readme.md` file is generated; +don't underestimate its value, as it will be the documentation entry point for consumers. + +The `generate` script will create a base structure for the component description; try to stick at it if you can. + +Start with a brief sentence which describes the main purpose of the component and why it should be used; +if it is related to other components, mention them and add a link to their documentation. + +Then describe how the component should be used, adding code examples: +if it's a presentational one explain its graphic variants using the `### Style` paragraph, +while if it's a complex one you could use the `### Interaction` paragraph. +Almost all the components has `### Slots` and can have different `### States`; describe how they can be used. + #### Prefer small, focused modules Keeping modules to a single responsibility makes the code easier to test, consume, and maintain. diff --git a/convenience/generate-component/boilerplate/readme.md b/convenience/generate-component/boilerplate/readme.md index abc7b19278..2d8d6beb30 100644 --- a/convenience/generate-component/boilerplate/readme.md +++ b/convenience/generate-component/boilerplate/readme.md @@ -1,3 +1,44 @@ -to be documented... +> Explain the use and the purpose of the component; add minor details if needed and provide a basic example.
+> If you reference other components, link their documentation at least once (the path must start from _/docs/..._ ).
+> For the examples, use triple backticks with file extension (```` ```html ``` ````).
+> The following list of paragraphs is only suggested; remove, create and adapt as needed. + +The `__name__` is a component . . . + +```html +<__name__> +``` + +## Slots + +> Describe slot naming and usage and provide an example of slotted content. + +## States + +> Describe the component states (`disabled`, `readonly`, etc.) and provide examples. + +## Style + +> Describe the properties which change the component visualization (`size`, `negative`, etc.) and provide examples. + +## Interactions + +> Describe how it's possible to interact with the component (open and close a `sbb-dialog`, dismiss a `sbb-alert`, etc.) and provide examples. + +## Events + +> Describe events triggered by the component and possibly how to get information from the payload. + +## Keyboard interaction + +> If the component has logic for keyboard navigation (as the `sbb-calendar` or the `sbb-select`) describe it. + +| Keyboard | Action | +|----------------|---------------| +| Key | What it does. | + +## Accessibility + +> Describe how accessibility is implemented and if there are issues or suggested best-practice for the consumers. \ No newline at end of file diff --git a/src/components.d.ts b/src/components.d.ts index f8acbbdd23..6bc7051a54 100644 --- a/src/components.d.ts +++ b/src/components.d.ts @@ -334,7 +334,7 @@ export namespace Components { */ "selectedDate": Date | string | number; /** - * If set to true, two months are displayed + * If set to true, two months are displayed. */ "wide": boolean; } @@ -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']; } @@ -1262,7 +1262,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']; /** @@ -1319,7 +1319,7 @@ export namespace Components { */ "disableAnimation"?: boolean; /** - * define the legs of the pearl-chain. Format: `{"legs": [{"duration": 25}, ...]}` `duration` in minutes. Duration of the leg is relative to the total travel time. Example: departure 16:30, change at 16:40, arrival at 17:00. So the change should have a duration of 33.33%. + * Define the legs of the pearl-chain. Format: `{"legs": [{"duration": 25}, ...]}` `duration` in minutes. Duration of the leg is relative to the total travel time. Example: departure 16:30, change at 16:40, arrival at 17:00. So the change should have a duration of 33.33%. */ "legs": Leg[]; } @@ -1353,7 +1353,7 @@ export namespace Components { } interface SbbPearlChainVerticalItem { /** - * If true the position won't be animated. + * If true, the position won't be animated. */ "disableAnimation"?: boolean; /** @@ -1635,9 +1635,6 @@ export namespace Components { */ "value": string | string[] | null; } - /** - * Generalized Teaser - for displaying an image, title and paragraph - */ interface SbbTeaser { /** * The href value you want to link to. @@ -1873,7 +1870,7 @@ export namespace Components { */ "disabled": boolean; /** - * If true set the width of the component fixed; if false the width is dynamic based on the label of the sbb-toggle-option. + * If true, set the width of the component fixed; if false, the width is dynamic based on the label of the sbb-toggle-option. */ "even": boolean; /** @@ -2591,9 +2588,6 @@ declare global { prototype: HTMLSbbTagGroupElement; new (): HTMLSbbTagGroupElement; }; - /** - * Generalized Teaser - for displaying an image, title and paragraph - */ interface HTMLSbbTeaserElement extends Components.SbbTeaser, HTMLStencilElement { } var HTMLSbbTeaserElement: { @@ -3105,7 +3099,7 @@ declare namespace LocalJSX { */ "selectedDate"?: Date | string | number; /** - * If set to true, two months are displayed + * If set to true, two months are displayed. */ "wide"?: boolean; } @@ -3255,7 +3249,7 @@ declare namespace LocalJSX { "input"?: string | HTMLElement; "onChange"?: (event: SbbDatepickerCustomEvent) => void; /** - * Notifies that the attributes of the datepicker has changes. + * Notifies that the attributes of the datepicker have changes. */ "onDatePickerUpdated"?: (event: SbbDatepickerCustomEvent) => void; /** @@ -3263,7 +3257,7 @@ declare namespace LocalJSX { */ "onDidChange"?: (event: SbbDatepickerCustomEvent) => void; /** - * Notifies that the attributes of the input connected to the datepicker has changes. + * Notifies that the attributes of the input connected to the datepicker have changes. */ "onInputUpdated"?: (event: SbbDatepickerCustomEvent) => void; /** @@ -3947,7 +3941,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']; } @@ -4081,7 +4075,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']; /** @@ -4135,7 +4129,7 @@ declare namespace LocalJSX { */ "disableAnimation"?: boolean; /** - * define the legs of the pearl-chain. Format: `{"legs": [{"duration": 25}, ...]}` `duration` in minutes. Duration of the leg is relative to the total travel time. Example: departure 16:30, change at 16:40, arrival at 17:00. So the change should have a duration of 33.33%. + * Define the legs of the pearl-chain. Format: `{"legs": [{"duration": 25}, ...]}` `duration` in minutes. Duration of the leg is relative to the total travel time. Example: departure 16:30, change at 16:40, arrival at 17:00. So the change should have a duration of 33.33%. */ "legs"?: Leg[]; } @@ -4169,7 +4163,7 @@ declare namespace LocalJSX { } interface SbbPearlChainVerticalItem { /** - * If true the position won't be animated. + * If true, the position won't be animated. */ "disableAnimation"?: boolean; /** @@ -4503,9 +4497,6 @@ declare namespace LocalJSX { */ "value"?: string | string[] | null; } - /** - * Generalized Teaser - for displaying an image, title and paragraph - */ interface SbbTeaser { /** * The href value you want to link to. @@ -4749,7 +4740,7 @@ declare namespace LocalJSX { */ "disabled"?: boolean; /** - * If true set the width of the component fixed; if false the width is dynamic based on the label of the sbb-toggle-option. + * If true, set the width of the component fixed; if false, the width is dynamic based on the label of the sbb-toggle-option. */ "even"?: boolean; /** @@ -5141,9 +5132,6 @@ declare module "@stencil/core" { "sbb-tab-title": LocalJSX.SbbTabTitle & JSXBase.HTMLAttributes; "sbb-tag": LocalJSX.SbbTag & JSXBase.HTMLAttributes; "sbb-tag-group": LocalJSX.SbbTagGroup & JSXBase.HTMLAttributes; - /** - * Generalized Teaser - for displaying an image, title and paragraph - */ "sbb-teaser": LocalJSX.SbbTeaser & JSXBase.HTMLAttributes; "sbb-teaser-hero": LocalJSX.SbbTeaserHero & JSXBase.HTMLAttributes; "sbb-time-input": LocalJSX.SbbTimeInput & JSXBase.HTMLAttributes; diff --git a/src/components/sbb-accordion/readme.md b/src/components/sbb-accordion/readme.md index 3483372657..409fba485c 100644 --- a/src/components/sbb-accordion/readme.md +++ b/src/components/sbb-accordion/readme.md @@ -1,5 +1,5 @@ -The `sbb-accordion` is a component which acts as a container for one or more `sbb-expansion-panel`; -the content is projected inside the unnamed slot. +The `sbb-accordion` is a component which acts as a container +for one or more [sbb-expansion-panel](/docs/components-sbb-accordion-sbb-expansion-panel--docs). ```html @@ -14,21 +14,9 @@ the content is projected inside the unnamed slot. ``` -### Title level +## Interaction -The component has a `titleLevel` property, which is proxied to the `sbb-expansion-panel-header`, and can be used -to wrap the header of each `sbb-expansion-panel` in a heading tag; if the property is unset, a `div` is used. -In the following example, all the `sbb-expansion-panel-header` would be wrapped in a `h3` heading tag. - -```html - - ... - -``` - -### 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 `sbb-expansion-panel` expanded at the same time. ```html @@ -36,13 +24,19 @@ The `multi` property, if set, allows to have more than one panel expanded at the ``` -### Animations +## Style -Animations can be disabled setting the `disableAnimation` property to `true`; -this will set the property on each `sbb-expansion-panel` inside the component. +The component has a `titleLevel` property, which is proxied to each inner `sbb-expansion-panel-header`, and can be used +to wrap the header of each `sbb-expansion-panel` in a heading tag; if the property is unset, a `div` is used. + +In the following example, all the `sbb-expansion-panel-header` would be wrapped in a `h3` heading tag. ```html - + + + Header 1 + Content 1 + ... ``` diff --git a/src/components/sbb-action-group/readme.md b/src/components/sbb-action-group/readme.md index 13ee6e3f66..3f58c2116b 100644 --- a/src/components/sbb-action-group/readme.md +++ b/src/components/sbb-action-group/readme.md @@ -1,43 +1,40 @@ -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](/docs/components-sbb-button--docs) or [sbb-link](/docs/components-sbb-link--docs) or other HTML elements) +in various [allocations](#allocations). -The `orientation` property is used to set items orientation. Possible values are `horizontal` -(default) and `vertical`. +## Style -The optional property `horizontalFrom` indicates the minimum breakpoint from which the orientation -changes to `horizontal`. +### Orientation -The `align-group` property can be used to set the default alignment of the contained elements; -possible values are `start`, `center`, `stretch` and `end`. - -It is also possible to set the `align-self` attribute on action items in order to move them in the -opposite direction to the group; possible values are `start`, `center` or `end`. +The `orientation` property is used to set item's orientation. +Possible values are `horizontal` (default) and `vertical`. -**NOTE**: `` will automatically set variant `block` and will sync the `linkSize` - 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. +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 + +``` - - 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 2 @@ -46,6 +43,26 @@ The examples below shows how to use the `` component using ` ``` +### 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`. + +It is also possible to set the `align-self` attribute on action items in order to move them in the +opposite direction to the group; possible values are `start`, `center` or `end`. + +**NOTE**: The `sbb-action-group` will automatically set variant `block` and will sync the `linkSize` + property with nested `sbb-link` and the `buttonSize` property with the nested `sbb-button` + instances. + +```html + + Action 1 + Action 2 + Action 3 + +``` + ## Allocations Items can be displayed inside `sbb-action-group` in different allocations. @@ -63,7 +80,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-group/readme.md b/src/components/sbb-alert-group/readme.md index 6c937d1884..deef26a15e 100644 --- a/src/components/sbb-alert-group/readme.md +++ b/src/components/sbb-alert-group/readme.md @@ -1,4 +1,5 @@ -The `sbb-alert-group` manages the dismissal and accessibility of alerts and also its visual gap between each other. +The `sbb-alert-group` manages the dismissal and accessibility of one or multiple +[sbb-alert](/docs/components-sbb-alert-sbb-alert--docs) and also its visual gap between each other. ```html @@ -17,21 +18,26 @@ The `sbb-alert-group` manages the dismissal and accessibility of alerts and also ``` +## Interactions + +If all the `sbb-alert`s are dismissed, it's recommended to completely remove the `sbb-alert-group` from DOM. + +You can catch this moment by listening to `empty` event and react accordingly. + ## Accessibility + By specifying the `accessibility-title` it's possible to add a hidden title to the `sbb-alert-group`. The heading level can be set via `accessibility-title-level`. By default, the `sbb-alert-group` has the role `status` which means that if a new alert arrives, it will be read out as soon as the user is idle (equal to [aria-live="polite"](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/ARIA_Live_Regions)). + You can change the `role` or `aria-live` attributes to fit your needs. For example, you can set the `role` to `alert` which implicitly sets `aria-live` to `assertive` -and therefore interrupts screen reader flow, to immediately read out the alert content. **Note that with role `alert`, -in some combinations of screen readers and browsers not every part of the alert is fully read.** - -If all alerts are dismissed, it's recommended to completely remove the `sbb-alert-group` from DOM. -You can catch this moment by listening to `empty` event and react accordingly. +and therefore interrupts screen reader flow, to immediately read out the alert content. +**Note that with role `alert`, in some combinations of screen readers and browsers not every part of the alert is fully read.** diff --git a/src/components/sbb-alert/readme.md b/src/components/sbb-alert/readme.md index 32eb1f1e03..4a0d81d2a0 100644 --- a/src/components/sbb-alert/readme.md +++ b/src/components/sbb-alert/readme.md @@ -1,39 +1,46 @@ -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` is a component which 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. +Multiple instances of this component can be used within +the [sbb-alert-group](/docs/components-sbb-alert-sbb-alert-group--docs) component. -## 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. - -## Usage +## Slots -Default with link: +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 `sbb-icon` at the component start using the `iconName` property or via custom content using the `icon` slot. ```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: - -```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): +## Interactions + +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 + + ... + +``` + +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](/docs/components-sbb-alert-sbb-alert-group--docs) +which automatically removes an alert after clicking the close button. ```html @@ -43,15 +50,13 @@ Readonly (no close button): ``` -Slot variant: +## Style + +Users can choose between two `size`, `m` (default) and `l`. ```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. + + ... ``` @@ -59,6 +64,9 @@ Slot variant: 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..d96744f98d 100644 --- a/src/components/sbb-autocomplete/readme.md +++ b/src/components/sbb-autocomplete/readme.md @@ -1,24 +1,27 @@ The `sbb-autocomplete` is a component that can be used to display a panel of suggested options connected to a text input. -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. +It's possible to set the element to which the component's panel will be attached using the `origin` prop, +and the input which will work as a trigger using the `trigger` prop. +Both accept 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. +```html + +
Another origin
-### 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 A + Option B + Option C + +``` -## Usage +## In `sbb-form-field` -In a form field: +If the component is used within a [sbb-form-field](/docs/components-sbb-form-field-sbb-form-field--docs), +it will automatically connect to the native `` as trigger and will display the option panel above or below the `sbb-form-field`. ```html @@ -35,23 +38,16 @@ In a form field: ``` -Standalone, by setting the `origin` and `trigger` properties: +## Style -```html - -
Another origin
+### 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](/docs/components-sbb-option-sbb-option--docs) for more details. - - Option A - Option B - Option C - -``` ### Option grouping -`sbb-option` can be collected into groups using `sbb-optgroup` element: + +The displayed `sbb-option` can be collected into groups using `sbb-optgroup` element: ```html @@ -72,21 +68,32 @@ Standalone, by setting the `origin` and `trigger` properties: ``` +## Events + +The `sbb-option` emits 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` events 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 `sbb-autocomplete` implements the [ARIA combobox interaction pattern](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/). + 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. +The component 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..6d25dfc254 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`, +The `sbb-breadcrumb-group` component is a container for one or more [sbb-breadcrumb](/docs/components-sbb-breadcrumb-sbb-breadcrumb--docs), 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,20 @@ receive the attribute `aria-current` set to `page`. ``` +## Style + +If the width of all the nested `sbb-breadcrumb` 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 `sbb-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`, as in the example above, +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 receives the attribute `aria-current="page"`. + diff --git a/src/components/sbb-breadcrumb/readme.md b/src/components/sbb-breadcrumb/readme.md index d17d9e6d89..a7d42dfeee 100644 --- a/src/components/sbb-breadcrumb/readme.md +++ b/src/components/sbb-breadcrumb/readme.md @@ -1,41 +1,39 @@ -The `sbb-breadcrumb` is a component used to display a link to a page; when it's used within the `sbb-breadcrumb-group` component, +The `sbb-breadcrumb` is a component used to display a link to a page. + +When it's used within the [sbb-breadcrumb-group](/docs/components-sbb-breadcrumb-sbb-breadcrumb-group--docs) component, it can display the list of the links the user visited to arrive at the current page. -It is possible to provide a text via an unnamed slot; the component can optionally display a `` +## Slots + +It is possible to provide a text 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. 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 +```html +Contact us -Breadcrumb with text: + -```html - - Contact us + + Info + ``` -Breadcrumb with icon: +## Link properties + +It's possible to set all the link related properties (`download`, `href`, `rel` and `target`). ```html - +Info ``` -Breadcrumb with text and slotted icon: +## Accessibility -```html - - Info - - -``` +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-button/readme.md b/src/components/sbb-button/readme.md index 8f4b8e9c30..c9067c85ac 100644 --- a/src/components/sbb-button/readme.md +++ b/src/components/sbb-button/readme.md @@ -1,36 +1,71 @@ -If the `href` property is set, it will internally be rendered as link, otherwise as a button. -If the `` is placed inside another action element (e.g. button, link, ...), -it is internally rendered as a `` in order to not break HTML structure. -It's also possible to set the `` manually into static state by applying `is-static` property. -If the `` is placed inside an ``, it renders with the correct styling. - -## Usage -Simple button +The `sbb-button` component provides the same functionality as a native `