kanto-ds 1.6.1 → 1.7.0

package/dist/docs/kt-table.md

@@ -0,0 +1,179 @@
+# `<kt-table>`
+
+A data table: tri-state sorting, single or multiple selection, paging.
+
+```js
+table.columns = [
+  { key: 'name', label: 'Nom', sortable: true },
+  { key: 'amount', label: 'Amount', sortable: true, align: 'right' },
+  { key: 'status', label: 'Status' },
+];
+table.data = rows;
+table.pageSize = 20;
+```
+
+## Sorting
+
+Sortable headers are **buttons**, not clickable `<th>`s. A header you can only
+sort with a mouse is a table half the users cannot sort.
+
+Each press cycles: unsorted → ascending → descending → unsorted. The third press
+restoring the original order is what makes sorting undoable.
+
+Text sorts through `Intl.Collator` with `numeric: true`, in the table's
+`locale`, else the page's `<html lang>`, else the browser's language. Each
+language files accents its own way — "Ångström" next to "Angstrom" in English,
+after "Zeta" in Swedish — and "Entity 2" comes before "Entity 10". Empty values sort to the end whichever way the column points — a
+descending sort should not open with a screen of blanks.
+
+`aria-sort` on the header reflects the state.
+
+The rows are sorted once per change of `data` or of the order, not on every
+render, so hovering and selecting stay quick on a few thousand rows. That relies
+on `data` being replaced, not edited: assign a new array
+(`table.data = [...rows, added]`) rather than pushing into the old one.
+
+## Server-side data
+
+With `manual`, the table sorts and pages nothing itself: `data` is the page the
+server sent, shown as it is, and `total-rows` is how many rows the server holds,
+which the pager counts from. Headers and the pager still update `sortKey`,
+`sortDirection` and `page` and fire their events; the application loads what
+they ask for.
+
+```js
+table.manual = true;
+table.pageSize = 25;
+
+async function load() {
+  table.loading = true;
+  const { rows, total } = await api.customers({
+    page: table.page,
+    size: table.pageSize,
+    sort: table.sortKey,
+    direction: table.sortDirection,
+  });
+  table.data = rows;
+  table.totalRows = total;
+  table.loading = false;
+}
+
+table.addEventListener('kt-sort-change', load);
+table.addEventListener('kt-page-change', load);
+load();
+```
+
+A new sort sends `page` back to 1 and fires only `kt-sort-change` — one event,
+one reload. While `loading`, a table that already shows a page keeps it on
+screen, dimmed and `aria-busy`, so the pager that asked for the next one keeps
+its place and its focus; the loading message only replaces the table before
+anything has loaded.
+
+Selection is kept by row identity, so it survives paging. `selectedRows` can
+only return the selected rows of the page on screen: keep the rows themselves
+on your side if you need them across pages.
+
+## Thousands of rows
+
+`virtual` renders only the rows in view — a few dozen, whatever the length of
+`data` — so five thousand rows scroll as smoothly as fifty, without paging. The
+table then scrolls inside its own box, under a header that stays on top: give
+it a height.
+
+```html
+<kt-table virtual style="height: 480px"></kt-table>
+```
+
+Every row must be the same height. The first one rendered is measured, so
+`compact` and your own padding are followed, but a custom cell taller than the
+rest would put the scroll position out of step with the rows.
+
+Sorting and selection work on the data, not on what is rendered: the header box
+selects every row, not only those on screen. `aria-rowcount` and
+`aria-rowindex` let a screen reader announce "row 1,204 of 5,000" with thirty
+rows in the page. A `page-size` takes precedence over `virtual`.
+
+## Selection
+
+```html
+<kt-table selectable selection-mode="multiple"></kt-table>
+```
+
+Rows are identified by `id`, then `uid`, then the row object itself. `selected`
+holds those identities; `selectedRows` gives you the rows.
+
+Multiple mode adds a select-all box in the header, which goes indeterminate on
+a partial selection.
+
+```js
+table.addEventListener('kt-selection-change', (e) => {
+  console.log(e.detail.selected, e.detail.rows);
+});
+```
+
+## Custom cells
+
+`renderCell` returns anything Lit can render — or `undefined` to fall back to
+the raw value, so it only has to handle the columns it cares about.
+
+```js
+table.renderCell = (row, column) =>
+  column.key === 'status'
+    ? html`<kt-badge variant="category" color="var(--color-success-base)">${row.status}</kt-badge>`
+    : undefined;
+```
+
+## API
+
+| Property        | Attribute        | Type                       | Default                   |
+| --------------- | ---------------- | -------------------------- | ------------------------- |
+| `columns`       | —                | `KtTableColumn[]`          | `[]`                      |
+| `data`          | —                | `KtTableRow[]`             | `[]`                      |
+| `selectable`    | `selectable`     | `boolean`                  | `false`                   |
+| `selectionMode` | `selection-mode` | `'single' \| 'multiple'`   | `'multiple'`              |
+| `selected`      | —                | `unknown[]`                | `[]`                      |
+| `pageSize`      | `page-size`      | `number` (0 = no paging)   | `0`                       |
+| `page`          | `page`           | `number`, from 1           | `1`                       |
+| `manual`        | `manual`         | `boolean`                  | `false`                   |
+| `totalRows`     | `total-rows`     | `number` (manual mode)     | `0`                       |
+| `virtual`       | `virtual`        | `boolean`                  | `false`                   |
+| `loading`       | `loading`        | `boolean`                  | `false`                   |
+| `compact`       | `compact`        | `boolean`                  | `false`                   |
+| `sortKey`       | `sort-key`       | `string \| null`           | `null`                    |
+| `sortDirection` | `sort-direction` | `'asc' \| 'desc' \| null`  | `null`                    |
+| `renderCell`    | —                | `(row, column) => unknown` | —                         |
+| `emptyText`     | `empty-text`     | `string`                   | `'No data to display'`    |
+| `loadingText`   | `loading-text`   | `string`                   | `'Loading…'`              |
+| `label`         | `label`          | `string`                   | `''`                      |
+| `locale`        | `locale`         | `string` (BCP 47)          | `''` (page, then browser) |
+
+```ts
+interface KtTableColumn {
+  key: string;
+  label?: string; // falls back to key
+  sortable?: boolean;
+  align?: 'left' | 'center' | 'right';
+  width?: string;
+}
+```
+
+| Getter         | Returns                         |
+| -------------- | ------------------------------- |
+| `sortedRows`   | All rows, sorted, before paging |
+| `visibleRows`  | The rows currently on screen    |
+| `selectedRows` | The selected rows themselves    |
+| `totalPages`   | Page count                      |
+
+| Event                 | Detail               |
+| --------------------- | -------------------- |
+| `kt-sort-change`      | `{ key, direction }` |
+| `kt-selection-change` | `{ selected, rows }` |
+| `kt-row-click`        | `{ row, index }`     |
+| `kt-page-change`      | `{ page }`           |
+
+| Part          | Description   |
+| ------------- | ------------- |
+| `table`       | The `<table>` |
+| `header-cell` | A `<th>`      |
+| `row`         | A `<tr>`      |
+| `cell`        | A `<td>`      |

package/dist/docs/kt-tabs.md

@@ -0,0 +1,87 @@
+# `<kt-tabs>`
+
+An underlined tab bar.
+
+```js
+tabs.tabs = [
+  { value: 'usage', label: 'Usage' },
+  { value: 'api', label: 'API', icon: 'code' },
+  { value: 'theme', label: 'Theme', disabled: true },
+];
+tabs.value = 'usage';
+tabs.addEventListener('kt-change', (e) => show(e.detail.value));
+```
+
+## Against `<kt-segmented-control>`
+
+They look similar in a screenshot and mean different things.
+
+A **segmented control** picks a _value_ — a date range, a unit, a sort order —
+and belongs inside a form or a toolbar. **Tabs** switch which _region of the
+page_ you are looking at; they read as part of the page structure rather than
+as a control sitting on it.
+
+The shapes say so: an inset track with a raised pill, versus a rule with one
+segment underlined. Using the wrong one is not a styling mistake, it is telling
+the reader the wrong thing about what will happen.
+
+## Panels
+
+`<kt-tabs>` manages selection only — swapping the panel is yours, the same
+contract as the segmented control. Give each tab a `panel` id and the tab
+carries `aria-controls`, so the pairing is announced:
+
+```html
+<kt-tabs></kt-tabs>
+<section id="usage-panel" role="tabpanel">…</section>
+```
+
+```js
+tabs.tabs = [{ value: 'usage', label: 'Usage', panel: 'usage-panel' }];
+```
+
+## Loading
+
+`loading` renders three placeholder tabs instead of the real ones, so a bar
+waiting on a fetch reserves its height rather than appearing under the content
+already on screen.
+
+## Keyboard
+
+One tab stop for the whole bar, as a tablist should have.
+
+| Key            | Does                                |
+| -------------- | ----------------------------------- |
+| `←` / `→`      | Previous / next tab, and selects it |
+| `Home` / `End` | First / last selectable tab         |
+
+Disabled tabs are skipped, and selection wraps at both ends.
+
+## API
+
+| Property   | Attribute  | Type                       | Default |
+| ---------- | ---------- | -------------------------- | ------- |
+| `tabs`     | —          | `KtTab[]`                  | `[]`    |
+| `value`    | `value`    | `string \| number \| null` | `null`  |
+| `disabled` | `disabled` | `boolean`                  | `false` |
+| `loading`  | `loading`  | `boolean`                  | `false` |
+| `label`    | `label`    | `string`                   | `''`    |
+
+```ts
+interface KtTab {
+  value: string | number;
+  label?: string; // falls back to String(value)
+  icon?: string; // Lucide name, kebab-case
+  disabled?: boolean;
+  panel?: string; // id of the region it controls
+}
+```
+
+| Event       | Detail                                                            |
+| ----------- | ----------------------------------------------------------------- |
+| `kt-change` | `{ value, tab }` — not fired when the active tab is clicked again |
+
+| Part   | Description |
+| ------ | ----------- |
+| `base` | The tablist |
+| `tab`  | One tab     |

package/dist/docs/kt-textarea.md

@@ -0,0 +1,59 @@
+# `<kt-textarea>`
+
+A multi-line field, with the same borderless fill and outline states as
+`<kt-input>`.
+
+```html
+<kt-textarea placeholder="Describe the incident..." rows="5"></kt-textarea>
+<kt-textarea maxlength="280" name="bio"></kt-textarea>
+<kt-textarea error="280 characters maximum"></kt-textarea>
+<kt-textarea resize="vertical" placeholder="As long as it needs to be"></kt-textarea>
+```
+
+## Resizing
+
+Off by default. The grip is drawn by the operating system, lands on the field's
+rounded corner and belongs to no design system — and a field the layout sized is
+not usually the reader's to resize. Set `resize="vertical"` where the content
+genuinely varies and the extra height will not break the screen around it.
+
+## The counter
+
+Setting `maxlength` shows a `0 / 280` counter, which turns red at the limit.
+It exists because a `maxlength` alone is a silent failure: the browser simply
+stops accepting keystrokes, with nothing on screen to explain why.
+
+The counter is `aria-live="polite"`, so it is announced as the user approaches
+the limit rather than on every character.
+
+## Form participation
+
+Form-associated, like `<kt-input>`: it serialises under its `name`, resets with
+the form, and reports `valueMissing` when `required` and empty.
+
+## API
+
+| Property      | Attribute     | Type                   | Default  |
+| ------------- | ------------- | ---------------------- | -------- |
+| `value`       | `value`       | `string`               | `''`     |
+| `name`        | `name`        | `string`               | `''`     |
+| `placeholder` | `placeholder` | `string`               | `''`     |
+| `rows`        | `rows`        | `number`               | `3`      |
+| `maxlength`   | `maxlength`   | `number`               | —        |
+| `disabled`    | `disabled`    | `boolean`              | `false`  |
+| `readonly`    | `readonly`    | `boolean`              | `false`  |
+| `required`    | `required`    | `boolean`              | `false`  |
+| `error`       | `error`       | `string`               | `''`     |
+| `label`       | `label`       | `string`               | `''`     |
+| `resize`      | `resize`      | `'vertical' \| 'none'` | `'none'` |
+
+| Event       | Detail              |
+| ----------- | ------------------- |
+| `kt-input`  | `{ value: string }` |
+| `kt-change` | `{ value: string }` |
+
+| Part      | Description             |
+| --------- | ----------------------- |
+| `base`    | The field container     |
+| `control` | The native `<textarea>` |
+| `counter` | The character counter   |

package/dist/docs/kt-time-input.md

@@ -0,0 +1,88 @@
+# `<kt-time-input>`
+
+A time of day typed into its parts — hours, minutes and, if asked, seconds.
+
+```html
+<kt-time-input label="Starts at" name="start" step="15" min="08:00" max="20:00"></kt-time-input>
+<kt-time-input label="Logged at" seconds value="09:15:30"></kt-time-input>
+```
+
+It shares its keyboard with [`<kt-date-input>`](./kt-date-input.md):
+each part is a segment, typed digit by digit, stepped with the arrows, the
+focus moving on as each fills — `1430` is half past two in the afternoon.
+
+## The reader's clock
+
+The clock is the one the reader's language reads: `14:30` in London and
+Paris, `02:30 PM` in New York, `14.30` in Copenhagen. `hour-cycle` sets it
+instead — `h12` for hours from 1 to 12 with AM/PM, `h23` for 0 to 23. The
+locale is `locale` if set, else the page's `lang`, else the browser's
+language.
+
+On a 12-hour clock the AM/PM segment takes the first letter of either — `a`
+or `p` — or the arrows. The hour reads with it: 12 AM is midnight, 12 PM noon.
+
+## The value
+
+Whatever the clock shows, the value is the 24-hour time `<input type="time">`
+and a server speak: `14:30`, or `14:30:05` with `seconds`. It is `null` until
+every segment is filled; a segment left at one digit is written out when the
+focus leaves it, `9` becoming `09`. `kt-change` fires once per time, not per
+keystroke.
+
+`step` is how many minutes the arrows move by: with `step="15"`, `↑` from
+`09:07` goes to `09:15`. Typed minutes are not rounded.
+
+A time before `min` or after `max` puts the field in its error state, the
+message in a tooltip on the alert icon. The value is `null` and the form sees
+a `badInput`.
+
+| Key           | Does                                                  |
+| ------------- | ----------------------------------------------------- |
+| digits        | fill the segment in focus                             |
+| `a` / `p`     | AM or PM, on a 12-hour clock                          |
+| `↑` / `↓`     | step the segment, wrapping round the clock            |
+| `Home`/`End`  | the segment's first or last value                     |
+| `←` / `→`     | the segment before or after                           |
+| `Backspace`   | erases a digit, then steps back to the segment before |
+| `:` `.` space | the next segment                                      |
+
+## In a form
+
+A form control: it submits the value under `name`, and nothing while the time
+is incomplete. `required` blocks submission while it is empty, `error` shows a
+message, and `form.reset()` puts back the initial value.
+
+## API
+
+| Property    | Attribute    | Type                             | Default            |
+| ----------- | ------------ | -------------------------------- | ------------------ |
+| `value`     | `value`      | `string \| null`                 | `null`             |
+| `seconds`   | `seconds`    | `boolean`                        | `false`            |
+| `hourCycle` | `hour-cycle` | `'h12' \| 'h23' \| ''`           | `''`, the locale's |
+| `step`      | `step`       | `number`                         | `1`                |
+| `min`       | `min`        | `string`                         | `''`               |
+| `max`       | `max`        | `string`                         | `''`               |
+| `name`      | `name`       | `string`                         | `''`               |
+| `label`     | `label`      | `string`                         | `''`               |
+| `locale`    | `locale`     | `string`                         | page, then browser |
+| `size`      | `size`       | `'small' \| 'medium' \| 'large'` | `'medium'`         |
+| `disabled`  | `disabled`   | `boolean`                        | `false`            |
+| `required`  | `required`   | `boolean`                        | `false`            |
+| `error`     | `error`      | `string`                         | `''`               |
+
+| Event       | Detail                                                    |
+| ----------- | --------------------------------------------------------- |
+| `kt-change` | `{ value: string \| null }` — `HH:MM`, `HH:MM:SS`, `null` |
+
+| Part      | Description                              |
+| --------- | ---------------------------------------- |
+| `field`   | The field                                |
+| `segment` | An hour, minute, second or AM/PM segment |
+
+## Accessibility
+
+The field is a `group` named by `label`. Each segment is a `spinbutton` named
+"Hour", "Minute", "Second" or "AM or PM", with its range and value. `Tab`
+walks the segments. On a phone, the number segments bring up the numeric
+keypad.

package/dist/docs/kt-timeline.md

@@ -0,0 +1,63 @@
+# `<kt-timeline>`
+
+An ordered run of events on a rail.
+
+```html
+<kt-timeline>
+  <kt-timeline-item heading="Deployed" time="09:24" variant="success" icon="rocket">
+    Build 4210 went to production.
+  </kt-timeline-item>
+  <kt-timeline-item heading="Review requested" time="09:02" icon="eye">
+    Two files, forty lines.
+  </kt-timeline-item>
+  <kt-timeline-item heading="Branch opened" time="08:41"></kt-timeline-item>
+</kt-timeline>
+```
+
+The same shape keeps reappearing — an activity feed, an audit log, a changelog,
+the stages of a delivery, the roles on a résumé — and every time it gets rebuilt
+out of a list, a pseudo-element line and a hand-placed dot.
+
+The fiddly part is the rail. It must start at the first dot and stop at the
+last, which a border on the list cannot do: a border runs the full height, so
+the line overshoots below the final event. Here each item draws its own segment
+hanging below its marker, and the last item drops it. The item cannot work out
+on its own that it is last — `:last-child` matches in the light tree, which the
+item's own shadow styles cannot reach — so `<kt-timeline>` reads its slot and
+sets `last` on the final child, again whenever the list changes.
+
+Without an `icon` the marker is a 9px dot; with one it is a 24px tinted circle.
+Mixing the two in one list is fine and reads as emphasis — give the events that
+matter an icon and leave the rest as dots.
+
+`variant` only colours the marker. As with every status colour in Kanto, it
+never carries the meaning alone: the heading says what happened.
+
+## API
+
+### `<kt-timeline>`
+
+| Property  | Attribute | Type      | Default |
+| --------- | --------- | --------- | ------- |
+| `compact` | `compact` | `boolean` | `false` |
+
+`compact` is passed down to every item, so set it once on the list.
+
+### `<kt-timeline-item>`
+
+| Property  | Attribute | Type                                                         | Default     |
+| --------- | --------- | ------------------------------------------------------------ | ----------- |
+| `heading` | `heading` | `string`                                                     | `''`        |
+| `time`    | `time`    | `string`                                                     | `''`        |
+| `icon`    | `icon`    | `string`                                                     | `''`        |
+| `variant` | `variant` | `neutral \| primary \| success \| warning \| danger \| info` | `'neutral'` |
+| `last`    | `last`    | `boolean`                                                    | `false`     |
+
+`time` is a free string — `09:24`, `2 days ago`, `June 2026` — because a
+timeline is as often a résumé as it is a log. `last` is managed by the parent;
+set it yourself only if you are laying items out without `<kt-timeline>`.
+
+| Slot      | Description                                 |
+| --------- | ------------------------------------------- |
+| _default_ | The body of the event                       |
+| `actions` | Trailing controls, aligned with the heading |

package/dist/docs/kt-toast-container.md

@@ -0,0 +1,69 @@
+# `<kt-toast-container>` / `toaster`
+
+The stack that owns the toasts on screen, and the imperative shortcut to it.
+
+## `toaster` — the usual way
+
+```js
+import { toaster } from 'kanto-ds';
+
+toaster.success('Entity created');
+toaster.error('Could not save', { description: 'Try again in a moment.' });
+```
+
+It creates one `<kt-toast-container>` on `<body>` the first time it is called
+and reuses it — including one you already put in your own markup, which it
+adopts rather than duplicating.
+
+Defaults that encode the intent: success and info dismiss after 4s, warnings
+after 6s, and **errors never dismiss themselves**. An error the user did not
+happen to be looking at is an error they never saw.
+
+## `<kt-toast-container>` — when placement matters
+
+```html
+<kt-toast-container position="top-right" limit="3"></kt-toast-container>
+```
+
+```js
+container.show({ variant: 'success', heading: 'Entity created', duration: 4000 });
+```
+
+The container owns the toasts: it appends them, and removes them when they ask
+to go. A toast that removes itself from a list it does not own is how you end up
+with two on screen and neither leaving.
+
+Newest toasts stack towards the screen edge, so the newest is always nearest the
+corner. Past `limit`, the oldest is dropped.
+
+**Hovering the stack pauses every countdown**, and leaving it resumes them —
+otherwise a toast expires under the pointer of someone reading it.
+
+The container itself does not intercept pointer events; only the toasts inside
+it do, so the rest of the corner stays clickable.
+
+## API — `<kt-toast-container>`
+
+| Property   | Attribute  | Type                                                           | Default          |
+| ---------- | ---------- | -------------------------------------------------------------- | ---------------- |
+| `position` | `position` | `'top-left' \| 'top-right' \| 'bottom-left' \| 'bottom-right'` | `'bottom-right'` |
+| `limit`    | `limit`    | `number`                                                       | `5`              |
+
+| Method / getter  | Description                   |
+| ---------------- | ----------------------------- |
+| `show(options)`  | Raises a toast, returns it    |
+| `dismiss(toast)` | Removes one                   |
+| `clear()`        | Removes all                   |
+| `toasts`         | Those on screen, oldest first |
+
+## API — `toaster`
+
+| Member                                          | Description                          |
+| ----------------------------------------------- | ------------------------------------ |
+| `success/info/warning/error(heading, options?)` | Raises a toast, returns it           |
+| `show(options)`                                 | The general form                     |
+| `getContainer()`                                | The container, creating it if needed |
+| `clear()`                                       | Clears the stack                     |
+| `position`                                      | Where an auto-created container sits |
+
+See [`<kt-toast>`](./kt-toast.md) for a single notification.

package/dist/docs/kt-toast.md

@@ -0,0 +1,41 @@
+# `<kt-toast>`
+
+A transient notification.
+
+For raising one, reach for [`toaster`](./kt-toast-container.md)
+— this page is the element itself.
+
+## Usage
+
+```html
+<kt-toast variant="warning" heading="Approaching your quota" dismissible duration="6000"></kt-toast>
+```
+
+`heading`, not `title`: every element already has a `title`, and shadowing it
+would turn the toast into its own tooltip.
+
+Errors are `role="alert"` / `aria-live="assertive"` and interrupt the screen
+reader; everything else is `role="status"` / `polite` and waits its turn.
+
+This is the only element in Kanto with a real shadow, and the only one that
+blurs what is behind it. A toast floats above the page, so it says so.
+
+## API
+
+| Property      | Attribute     | Type                                                 | Default         |
+| ------------- | ------------- | ---------------------------------------------------- | --------------- |
+| `variant`     | `variant`     | `'success' \| 'information' \| 'warning' \| 'error'` | `'information'` |
+| `heading`     | `heading`     | `string`                                             | `''`            |
+| `description` | `description` | `string`                                             | `''`            |
+| `dismissible` | `dismissible` | `boolean`                                            | `false`         |
+| `duration`    | `duration`    | `number` (ms, 0 = stays)                             | `0`             |
+
+| Method     | Description                 |
+| ---------- | --------------------------- |
+| `close()`  | Fires `kt-toast-close`      |
+| `pause()`  | Freezes the countdown       |
+| `resume()` | Resumes it where it stopped |
+
+| Event            | Fired when                   |
+| ---------------- | ---------------------------- |
+| `kt-toast-close` | The toast asks to be removed |

package/dist/docs/kt-toggle-button-group.md

@@ -0,0 +1,67 @@
+# `<kt-toggle-button-group>`
+
+Joins `<kt-toggle-button>`s into one bar and owns their selection.
+
+```html
+<kt-toggle-button-group label="View">
+  <kt-toggle-button value="list">List</kt-toggle-button>
+  <kt-toggle-button value="grid">Grid</kt-toggle-button>
+  <kt-toggle-button value="map">Map</kt-toggle-button>
+</kt-toggle-button-group>
+```
+
+```js
+group.addEventListener('kt-change', (e) => console.log(e.detail.value));
+```
+
+## The group owns the selection
+
+Buttons are slotted rather than described by an options array, so a label can be
+anything — an icon, a count, a badge.
+
+Inside a group a button becomes **controlled**: it no longer flips itself and no
+longer emits. The group reads the click, works out what the selection now is,
+and writes `selected` back down. That is what keeps one press from producing two
+contradictory `kt-change` events.
+
+So: listen on the group, never on its buttons.
+
+## Single and multiple
+
+Single mode behaves like a radio group with a deselect — pressing the active
+button clears it, and `value` is a string or `null`.
+
+`multiple` makes it a set of checkboxes drawn together, and `value` becomes an
+array.
+
+```html
+<kt-toggle-button-group multiple orientation="vertical"></kt-toggle-button-group>
+```
+
+Corner rounding belongs to the group, which is the only thing that knows which
+button is first and which is last; it drives `--kt-toggle-button-radius` on each
+child through CSS.
+
+## API
+
+| Property      | Attribute     | Type                         | Default        |
+| ------------- | ------------- | ---------------------------- | -------------- |
+| `value`       | —             | `string \| string[] \| null` | `null`         |
+| `multiple`    | `multiple`    | `boolean`                    | `false`        |
+| `orientation` | `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` |
+| `label`       | `label`       | `string`                     | `''`           |
+
+| Event       | Detail      |
+| ----------- | ----------- |
+| `kt-change` | `{ value }` |
+
+| Slot      | Description                   |
+| --------- | ----------------------------- |
+| _default_ | `<kt-toggle-button>` children |
+
+| Part   | Description         |
+| ------ | ------------------- |
+| `base` | The group container |
+
+See [`<kt-toggle-button>`](./kt-toggle-button.md) for the
+button itself.