Skip to content

Commit

Permalink
docs: add docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@DavideMininni-Fincons
DavideMininni-Fincons committed Mar 18, 2024
1 parent fbfb260 commit 82bf733
Show file tree
Hide file tree
Showing 7 changed files with 332 additions and 159 deletions.
57 changes: 24 additions & 33 deletions src/components/autocomplete-grid/autocomplete-grid-actions/readme.md
View file
Original file line number Diff line number Diff line change
@@ -1,45 +1,36 @@
> 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 `sbb-autocomplete-grid-actions` is a component . . .
The `sbb-autocomplete-grid-actions` component wraps one of more [sbb-autocomplete-grid-button](/docs/components-sbb-autocomplete-grid-sbb-autocomplete-grid-button--docs)
inside a [sbb-autocomplete-grid](/docs/components-sbb-autocomplete-grid-sbb-autocomplete-grid--docs)

```html
<sbb-autocomplete-grid-actions></sbb-autocomplete-grid-actions>
<sbb-form-field label="Label">
<input />
<sbb-autocomplete-grid>
<sbb-autocomplete-grid-row>
<sbb-autocomplete-grid-option value="1">Option 1</sbb-autocomplete-grid-option>
<sbb-autocomplete-grid-actions>
<sbb-autocomplete-grid-button icon-name="pen-small"></sbb-autocomplete-grid-button>
</sbb-autocomplete-grid-actions>
</sbb-autocomplete-grid-row>
<sbb-autocomplete-grid-row>
<sbb-autocomplete-grid-option value="2">Option 2</sbb-autocomplete-grid-option>
<sbb-autocomplete-grid-actions>
<sbb-autocomplete-grid-button icon-name="trash-small"></sbb-autocomplete-grid-button>
</sbb-autocomplete-grid-actions>
</sbb-autocomplete-grid-row>
</sbb-autocomplete-grid>
</sbb-form-field>
```

## 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. |
The component has an unnamed slot which is used to project the `sbb-autocomplete-grid-buttons`.

## Accessibility

> Describe how accessibility is implemented and if there are issues or suggested best-practice for the consumers.
The `sbb-autocomplete-grid` follows the combobox `grid` pattern;
this means that the `sbb-autocomplete-grid-actions` has a `gridcell` role and its child would receive an `id`
based on the `sbb-autocomplete-grid-actions`'s `id`,
which is needed to correctly set the `aria-activedescendant` on the related `input`.

<!-- Auto Generated Below -->

Expand Down
86 changes: 65 additions & 21 deletions src/components/autocomplete-grid/autocomplete-grid-button/readme.md
View file
Original file line number Diff line number Diff line change
@@ -1,45 +1,89 @@
> 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 `sbb-autocomplete-grid-button` is a component . . .
The `sbb-autocomplete-grid-button` component provides the same functionality as a native icon-only `<button>` enhanced with the SBB Design.
It's mainly designed to be used within the [sbb-autocomplete-grid-actions](/docs/components-sbb-autocomplete-grid-sbb-autocomplete-grid-actions--docs)
inside a [sbb-autocomplete-grid](/docs/components-sbb-autocomplete-grid-sbb-autocomplete-grid--docs).

```html
<sbb-autocomplete-grid-button></sbb-autocomplete-grid-button>
<sbb-form-field label="Label">
<input />
<sbb-autocomplete-grid>
<sbb-autocomplete-grid-row>
<sbb-autocomplete-grid-option value="1">Option 1</sbb-autocomplete-grid-option>
<sbb-autocomplete-grid-actions>
<sbb-autocomplete-grid-button icon-name="pen-small"></sbb-autocomplete-grid-button>
</sbb-autocomplete-grid-actions>
</sbb-autocomplete-grid-row>
<sbb-autocomplete-grid-row>
<sbb-autocomplete-grid-option value="2">Option 2</sbb-autocomplete-grid-option>
<sbb-autocomplete-grid-actions>
<sbb-autocomplete-grid-button icon-name="trash-small"></sbb-autocomplete-grid-button>
</sbb-autocomplete-grid-actions>
</sbb-autocomplete-grid-row>
</sbb-autocomplete-grid>
</sbb-form-field>
```

## Slots

> Describe slot naming and usage and provide an example of slotted content.
The component can display a `sbb-icon` using the `iconName` property or via custom content using the `icon` slot.

```html
<sbb-autocomplete-grid-button icon-name="pen-small"></sbb-autocomplete-grid-button>

<sbb-autocomplete-grid-button>
<sbb-icon slot="icon" name="info"></sbb-icon>
</sbb-autocomplete-grid-button>
```

## Button properties

## States
The component is internally rendered as a button,
accepting its associated properties (`type`, `name`, `value` and `form`).

> Describe the component states (`disabled`, `readonly`, etc.) and provide examples.
```html
<sbb-autocomplete-grid-button
icon-name="coins-small"
type="button"
name="tickets"
form="buy"
value="tickets"
>
</sbb-autocomplete-grid-button>
```

## Style

> Describe the properties which change the component visualization (`size`, `negative`, etc.) and provide examples.
The component has a negative variant which can be set using the `negative` property.

## Interactions
The component can be displayed in `disabled` state using the self-named property.

```html
<sbb-autocomplete-grid-button icon-name="pen-small" negative></sbb-autocomplete-grid-button>

> Describe how it's possible to interact with the component (open and close a `sbb-dialog`, dismiss a `sbb-alert`, etc.) and provide examples.
<sbb-autocomplete-grid-button icon-name="pen-small" disabled></sbb-autocomplete-grid-button>
```

## Events
If the component is used within a [sbb-autocomplete-grid-optgroup](/docs/components-sbb-autocomplete-grid-sbb-autocomplete-grid-optgroup--docs),
it can be disabled by disabling the group.

> Describe events triggered by the component and possibly how to get information from the payload.
### Focus outline

## Keyboard interaction
Please make sure that the focus outline appears in the correct color if the component is used on a dark background.
You can set it by re-defining the css var on `sbb-autocomplete-grid-button` or any parent element:

> If the component has logic for keyboard navigation (as the `sbb-calendar` or the `sbb-select`) describe it.
```css
sbb-autocomplete-grid-button {
--sbb-focus-outline-color: var(--sbb-focus-outline-color-dark);
}
```

## Interactions

| Keyboard | Action |
| -------------- | ------------- |
| <kbd>Key</kbd> | What it does. |
When the button is clicked, an event is triggered; the behavior is up to the consumer.
It's possible to fetch the button's related `sbb-autocomplete-grid-option` using the `optionOnSameRow` method.

## Accessibility

> Describe how accessibility is implemented and if there are issues or suggested best-practice for the consumers.
Use the accessibility properties to describe the purpose of the `sbb-autocomplete-grid-button` for screen-reader users.

<!-- Auto Generated Below -->

Expand Down
83 changes: 52 additions & 31 deletions src/components/autocomplete-grid/autocomplete-grid-optgroup/readme.md
View file
Original file line number Diff line number Diff line change
@@ -1,45 +1,66 @@
> 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 `sbb-optgroup` is a component used to group more [sbb-autocomplete-grid-option](/docs/components-sbb-autocomplete-grid-sbb-autocomplete-grid-option--docs)
within a [sbb-autocomplete-grid](/docs/components-sbb-autocomplete-grid-sbb-autocomplete-grid--docs).

The `sbb-autocomplete-grid-optgroup` is a component . . .
A [sbb-divider](/docs/components-sbb-divider--docs) is displayed at the bottom of the component.

```html
<sbb-autocomplete-grid-optgroup></sbb-autocomplete-grid-optgroup>
<sbb-form-field label="Label">
<input />
<sbb-autocomplete-grid>
<sbb-autocomplete-grid-optgroup>
<sbb-autocomplete-grid-row>
<sbb-autocomplete-grid-option value="1">Option 1</sbb-autocomplete-grid-option>
<sbb-autocomplete-grid-actions>
<sbb-autocomplete-grid-button icon-name="pen-small"></sbb-autocomplete-grid-button>
</sbb-autocomplete-grid-actions>
</sbb-autocomplete-grid-row>
<sbb-autocomplete-grid-row>
<sbb-autocomplete-grid-option value="2">Option 2</sbb-autocomplete-grid-option>
<sbb-autocomplete-grid-actions>
<sbb-autocomplete-grid-button icon-name="trash-small"></sbb-autocomplete-grid-button>
</sbb-autocomplete-grid-actions>
</sbb-autocomplete-grid-row>
</sbb-autocomplete-grid-optgroup>
</sbb-autocomplete-grid>
</sbb-form-field>
```

## Slots

> Describe slot naming and usage and provide an example of slotted content.
It is possible to provide a set of `sbb-autocomplete-grid-option` via an unnamed slot;
the component has also a `label` property as name of the group.

## 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.
```html
<sbb-autocomplete-grid-optgroup label="Group">
<sbb-autocomplete-grid-row>
<sbb-autocomplete-grid-option value="1" selected>1</sbb-autocomplete-grid-option>
</sbb-autocomplete-grid-row>
<sbb-autocomplete-grid-row>
<sbb-autocomplete-grid-option value="2">2</sbb-autocomplete-grid-option>
</sbb-autocomplete-grid-row>
<sbb-autocomplete-grid-row>
<sbb-autocomplete-grid-option value="3">3</sbb-autocomplete-grid-option>
</sbb-autocomplete-grid-row>
</sbb-autocomplete-grid-optgroup>
```

| Keyboard | Action |
| -------------- | ------------- |
| <kbd>Key</kbd> | What it does. |
## States

## Accessibility
The component has a `disabled` property which sets all the `sbb-autocomplete-grid-option` in the group as disabled.

> Describe how accessibility is implemented and if there are issues or suggested best-practice for the consumers.
```html
<sbb-autocomplete-grid-optgroup label="Disabled group" disabled>
<sbb-autocomplete-grid-row>
<sbb-autocomplete-grid-option value="A">A</sbb-autocomplete-grid-option>
</sbb-autocomplete-grid-row>
<sbb-autocomplete-grid-row>
<sbb-autocomplete-grid-option value="B">B</sbb-autocomplete-grid-option>
</sbb-autocomplete-grid-row>
<sbb-autocomplete-grid-row>
<sbb-autocomplete-grid-option value="C">C</sbb-autocomplete-grid-option>
</sbb-autocomplete-grid-row>
</sbb-autocomplete-grid-optgroup>
```

<!-- Auto Generated Below -->

Expand Down
81 changes: 61 additions & 20 deletions src/components/autocomplete-grid/autocomplete-grid-option/readme.md
View file
Original file line number Diff line number Diff line change
@@ -1,45 +1,86 @@
> 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 `sbb-autocomplete-grid-option` is a component . . .
The `sbb-autocomplete-grid-option` is a component which can be used to display items in the
[sbb-autocomplete-grid](/docs/components-sbb-autocomplete-sbb-autocomplete-grid--docs).

```html
<sbb-autocomplete-grid-option></sbb-autocomplete-grid-option>
<sbb-form-field label="Label">
<input />
<sbb-autocomplete-grid>
<sbb-autocomplete-grid-row>
<sbb-autocomplete-grid-option value="1">Option 1</sbb-autocomplete-grid-option>
<sbb-autocomplete-grid-actions>
<sbb-autocomplete-grid-button icon-name="pen-small"></sbb-autocomplete-grid-button>
</sbb-autocomplete-grid-actions>
</sbb-autocomplete-grid-row>
<sbb-autocomplete-grid-row>
<sbb-autocomplete-grid-option value="2">Option 2</sbb-autocomplete-grid-option>
<sbb-autocomplete-grid-actions>
<sbb-autocomplete-grid-button icon-name="trash-small"></sbb-autocomplete-grid-button>
</sbb-autocomplete-grid-actions>
</sbb-autocomplete-grid-row>
</sbb-autocomplete-grid>
</sbb-form-field>
```

## Slots

> Describe slot naming and usage and provide an example of slotted content.
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.

```html
<sbb-autocomplete-grid-option value="1">Option 1</sbb-autocomplete-grid-option>

<sbb-autocomplete-grid-option value="1" icon-name="coins-small"
>Option 1</sbb-autocomplete-grid-option
>
```

## States

> Describe the component states (`disabled`, `readonly`, etc.) and provide examples.
Like the native `option`, the component has a `value` property.

## Style
The `selected`, `disabled` and `active` properties are connected to the self-named states.
When disabled, the selection via click is prevented.
If the `sbb-autocomplete-grid-option` is nested in a `sbb-autocomplete-grid-optgroup` component, it inherits from the parent the `disabled` state.

> Describe the properties which change the component visualization (`size`, `negative`, etc.) and provide examples.
```html
<sbb-autocomplete-grid-option value="value" selected>Option label</sbb-autocomplete-grid-option>

## Interactions
<sbb-autocomplete-grid-option value="value" active>Option label</sbb-autocomplete-grid-option>

> Describe how it's possible to interact with the component (open and close a `sbb-dialog`, dismiss a `sbb-alert`, etc.) and provide examples.
<sbb-autocomplete-grid-option value="value" disabled>Option label</sbb-autocomplete-grid-option>
```

## Events

> Describe events triggered by the component and possibly how to get information from the payload.
Consumers can listen to the `optionSelected` event on the `sbb-autocomplete-grid-option` component to intercept the selected value;
the event is triggered if the element has been selected by some user interaction. Alternatively,
the `selectionChange` event can be listened to, which is triggered if the element has been both selected or deselected.

## Keyboard interaction
## Style

> If the component has logic for keyboard navigation (as the `sbb-calendar` or the `sbb-select`) describe it.
If the label slot contains only a **text node**, it is possible to search for text in the `sbb-autocomplete-grid-option` using the
`highlight` method, passing the desired text; if the text is present it will be highlighted in bold.

| Keyboard | Action |
| -------------- | ------------- |
| <kbd>Key</kbd> | What it does. |
```html
<!-- Supported scenario -->
<sbb-autocomplete-grid-option> Highlightable caption</sbb-autocomplete-grid-option>

<!-- Not supported scenarios -->
<sbb-autocomplete-grid-option>
<span>Not highlightable caption</span>
</sbb-autocomplete-grid-option>

<sbb-autocomplete-grid-option>
<img src="..." />
Highlightable caption
</sbb-autocomplete-grid-option>
```

## Accessibility

> Describe how accessibility is implemented and if there are issues or suggested best-practice for the consumers.
The `sbb-autocomplete-grid` follows the combobox `grid` pattern;
this means that the `sbb-autocomplete-grid-option` has a `gridcell` role and its `id` is set from `sbb-autocomplete-grid-row`'s `id`,
which is needed to correctly set the `aria-activedescendant` on the related `input`.

<!-- Auto Generated Below -->

Expand Down
Loading

0 comments on commit 82bf733

Please sign in to comment.