Adding upstream version 0.46.upstream/0.46

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 162 insertions, 0 deletions

diff --git a/docs/content/ui/tabs.md b/docs/content/ui/tabs.md
new file mode 100644
index 0000000..094e271
--- /dev/null
+++ b/docs/content/ui/tabs.md
@@ -0,0 +1,162 @@
+---
+title: Tabs
+description: Easily create accessible, fully customizable tab interfaces, with robust focus management and keyboard navigation support.
+---
+
+<Header title="Tabs" section="UI components">
+  Easily create accessible, fully customizable tab interfaces, with robust focus management and keyboard navigation support.
+</Header>
+
+<ExampleTabs
+  prefix="demo"
+  panels={{ {
+    'Result': 'ui.Tabs.DemoResult',
+    'HTML': 'ui.Tabs.DemoHTML',
+    'CSS': 'ui.Tabs.DemoCSS',
+  } }}
+/>
+
+Tabs are built using the `TabGroup`, `TabList`, `Tab`, and `TabPanel` components. Clicking on any tab or selecting it with the keyboard will activate the corresponding panel.
+
+
+## Styling states
+
+| CSS selector     | Description
+| ---------------  | --------------
+| `.ui-hidden`     | Added to all `TabPanel` except the one that is active.
+| `.ui-selected`   | Added to the selected `Tab`.
+| `.ui-disabled`   | Added to disabled `Tab`s.
+
+
+## Disabling a tab
+
+To disable a tab, use the disabled attribute on the `Tab` component. Disabled tabs cannot be selected with the mouse, and are also skipped when navigating the tab list using the keyboard.
+
+<Callout type="warning">
+Disabling tabs might be confusing for users. Instead, I reccomend you either remove it or explain why there is no content for that tab when is selected.
+</Callout>
+
+
+## Manually activating tabs
+
+By default, tabs are automatically selected as the user navigates through them using the arrow kbds.
+
+If you'd rather not change the current tab until the user presses <kbd>Enter</kbd> or <kbd>Space</kbd>, use the `manual` attribute on the `TabGroup` component.
+
+Remember to add styles to the `:focus` state of the tab so is clear to the user that the tab is focused.
+
+<ExampleTabs
+  prefix="manual"
+  panels={{{
+    'HTML': 'ui.Tabs.ManualHTML',
+    'Result': 'ui.Tabs.ManualResult',
+  } }}
+/>
+
+The manual prop has no impact on mouse interactions — tabs will still be selected as soon as they are clicked.
+
+
+## Vertical tabs
+
+If you've styled your `TabList` to appear vertically, use the `vertical` attribute to enable navigating with the <kbd title="arrow up">↑</kbd> and <kbd title="arrow down">↓</kbd> arrow kbds instead of <kbd title="arrow left">←</kbd> and <kbd title="arrow right">→</kbd>, and to update the `aria-orientation` attribute for assistive technologies.
+
+<ExampleTabs
+  prefix="vertical"
+  panels={{ {
+    'HTML': 'ui.Tabs.VerticalHTML',
+    'Result': 'ui.Tabs.VerticalResult',
+  } }}
+/>
+
+
+## Controlling the tabs with a `<select>`
+
+Sometimes, you want to display a `<select>` element in addition to tabs. To do so, use the `TabSelect` and `TabOption` components.
+A `TabSelect` component is a wrapper for a `<select>` element, and it accepts `TabOption` components as children.
+
+Note that a `TabSelect` **is not a replacement for a `TabList`**. For accessibility the `TabList` must be remain in your code, even if it's visually hidden.
+
+<ExampleTabs
+  prefix="select"
+  :panels="{
+    'HTML': 'ui.Tabs.SelectHTML',
+    'Result': 'ui.Tabs.SelectResult',
+  }"
+/>
+
+
+## Component arguments
+
+### TabGroup
+
+| Argument    | Type     | Default    | Description
+| ----------- | -------- | ---------- | --------------
+| tag         | `str`    | `"div"`    | HTML tag used for rendering the wrapper.
+
+### TabList
+
+| Argument    | Type     | Default    | Description
+| ----------- | -------- | ---------- | --------------
+| vertical    | `bool`   | `false`    | Use the <kbd title="arrow up">↑</kbd> and <kbd title="arrow down">↓</kbd> arrow kbds to move between tabs instead of the defaults <kbd title="arrow left">←</kbd> and <kbd title="arrow right">→</kbd> arrow kbds.
+| manual      | `bool`   | `false`    | If `true`, selecting a tab with the keyboard won't activate it, you must press <kbd>Enter</kbd> os <kbd>Space</kbd> kbds to do it.
+| tag         | `str`    | `"nav"`    | HTML tag used for rendering the wrapper.
+
+
+### Tab
+
+| Argument    | Type     | Default    | Description
+| ----------- | -------- | ---------- | --------------
+| target      | `str`    |            | Required. HTML id of the panel associated with this tab.
+| selected    | `bool`   | `false`    | Initially selected tab. Only one tab in the `TabList` can be selected at the time.
+| disabled    | `bool`   | `false`    | If the tab can be selected.
+| tag         | `str`    | `"button"` | HTML tag used for rendering the tab.
+
+### TabPanel
+
+| Argument    | Type     | Default    | Description
+| ----------- | -------- | ---------- | --------------
+| hidden      | `bool`   | `false`    | Initially hidden panel.
+| tag         | `bool`   | `"div"`    | HTML tag used for rendering the panel.
+
+
+### TabSelect
+
+No arguments.
+
+
+### TabOption
+
+| Argument    | Type     | Default    | Description
+| ----------- | -------- | ---------- | --------------
+| target      | `str`    |            | Required. HTML id of the panel associated with this tab.
+| disabled    | `bool`   | `false`    | Display the option but not allow to select it.
+
+
+## Events
+
+A tab emits a `jxui:tab:selected` event every time is selected. The event contains the `target` property with the tag node.
+
+```js
+document.addEventListener("jxui:tab:selected", (event) => {
+  console.log(`'${event.target.textContent}' tab selected`);
+});
+```
+
+
+## Accessibility notes
+
+### Mouse interaction
+
+Clicking a `Tab` will select that tab and display the corresponding `TabPanel`.
+
+### Keyboard interaction
+
+All interactions apply when a `Tab` component is focused.
+
+| Command                                                                                           | Description
+| -------------------------------------------------------------------------------------             | -----------
+| <kbd title="arrow left">←</kbd> / <kbd title="arrow right">→</kbd> arrow kbds                     | Selects the previous/next non-disabled tab, cycling from last to first and vice versa.
+| <kbd title="arrow up">↑</kbd> / <kbd title="arrow down">↓</kbd> arrow kbds when `vertical` is set | Selects the previous/next non-disabled tab, cycling from last to first and vice versa.
+| <kbd>Enter</kbd> or <kbd>Space</kbd> when `manual` is set                                         | Activates the selected tab
+| <kbd>Home</kbd> or <kbd>PageUp</kbd>                                                              | Activates the **first** tab
+| <kbd>End</kbd> or <kbd>PageDown</kbd>                                                             | Activates the **last** tab