docs: readme refactoring (#1996)

sbb-design-systems · Oct 11, 2023 · 95bb0d5 · 95bb0d5
1 parent dddaca5
commit 95bb0d5
Show file tree

Hide file tree

Showing 97 changed files with 2,253 additions and 1,325 deletions.
diff --git 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
@@ -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.<br>
+> If you reference other components, link their documentation at least once (the path must start from _/docs/..._ ).<br>
+> For the examples, use triple backticks with file extension (```` ```html <code here>``` ````).<br>
+> The following list of paragraphs is only suggested; remove, create and adapt as needed.
+
+The `__name__` is a component . . .
+
+```html
+<__name__></__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        |
+|----------------|---------------|
+| <kbd>Key</kbd> | What it does. |
+
+## Accessibility
+
+> Describe how accessibility is implemented and if there are issues or suggested best-practice for the consumers.
 
 <!-- Auto Generated Below -->
diff --git 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,15 +3249,15 @@ declare namespace LocalJSX {
         "input"?: string | HTMLElement;
         "onChange"?: (event: SbbDatepickerCustomEvent<any>) => void;
         /**
-          * Notifies that the attributes of the datepicker has changes.
+          * Notifies that the attributes of the datepicker have changes.
          */
         "onDatePickerUpdated"?: (event: SbbDatepickerCustomEvent<any>) => void;
         /**
           * @deprecated only used for React. Will probably be removed once React 19 is available.
          */
         "onDidChange"?: (event: SbbDatepickerCustomEvent<any>) => 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<InputUpdateEvent>) => 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<HTMLSbbTabTitleElement>;
             "sbb-tag": LocalJSX.SbbTag & JSXBase.HTMLAttributes<HTMLSbbTagElement>;
             "sbb-tag-group": LocalJSX.SbbTagGroup & JSXBase.HTMLAttributes<HTMLSbbTagGroupElement>;
-            /**
-             * Generalized Teaser - for displaying an image, title and paragraph
-             */
             "sbb-teaser": LocalJSX.SbbTeaser & JSXBase.HTMLAttributes<HTMLSbbTeaserElement>;
             "sbb-teaser-hero": LocalJSX.SbbTeaserHero & JSXBase.HTMLAttributes<HTMLSbbTeaserHeroElement>;
             "sbb-time-input": LocalJSX.SbbTimeInput & JSXBase.HTMLAttributes<HTMLSbbTimeInputElement>;

diff --git 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
 <sbb-accordion>
@@ -14,35 +14,29 @@ the content is projected inside the unnamed slot.
 </sbb-accordion>
 ```
 
-### 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
-<sbb-accordion title-level='3'>
-  ...
-</sbb-accordion>
-```
-
-### 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
 <sbb-accordion multi>
   ...
 </sbb-accordion>
 ```
 
-### 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
-<sbb-accordion disable-animation>
+<sbb-accordion title-level='3'>
+  <sbb-expansion-panel>
+    <sbb-expansion-panel-header>Header 1</sbb-expansion-panel-header>
+    <sbb-expansion-panel-content>Content 1</sbb-expansion-panel-content>
+  </sbb-expansion-panel>
   ...
 </sbb-accordion>
 ```

diff --git a/src/components/sbb-action-group/readme.md b/src/components/sbb-action-group/readme.md
@@ -1,43 +1,40 @@
-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.
+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**: `<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.
-
-## Usage
-
-The examples below shows how to use the `<sbb-action-group>` component using `<sbb-button>` and `<sbb-link>` 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
-<sbb-action-group>
+<sbb-action-group orientation="vertical" horizontal-from='small'>
   <sbb-button variant="secondary">Action 1</sbb-button>
   <sbb-button>Action 2</sbb-button>
+  <sbb-link
+    align-self="end"
+    icon-name="chevron-small-left-small"
+    href="https://github.com/lyne-design-system/lyne-components"
+  >
+    Action 3
+  </sbb-link>
 </sbb-action-group>
+```
 
-<sbb-action-group align="end">
-  <sbb-button align-self="start" variant="secondary">Action 1</sbb-button>
-  <sbb-button variant="secondary">Action 2</sbb-button>
-  <sbb-button>Action 3</sbb-button>
-</sbb-action-group>
+### Button-size and link-size
 
-<sbb-action-group orientation="vertical">
+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
+<sbb-action-group button-size='m' link-size='s'>
   <sbb-button variant="secondary">Action 1</sbb-button>
-  <sbb-button variant="secondary">Action 2</sbb-button>
   <sbb-link
-    align-self="end"
     icon-name="chevron-small-left-small"
     href="https://github.com/lyne-design-system/lyne-components"
   >
@@ -46,6 +43,26 @@ The examples below shows how to use the `<sbb-action-group>` component using `<s
 </sbb-action-group>
 ```
 
+### 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
+<sbb-action-group align-group="end">
+  <sbb-button align-self="start" variant="secondary">Action 1</sbb-button>
+  <sbb-button variant="secondary">Action 2</sbb-button>
+  <sbb-button>Action 3</sbb-button>
+</sbb-action-group>
+```
+
 ## 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
 </sbb-action-group>
 ```
 
-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