kanto-ds 1.6.1 → 1.7.0

package/dist/docs/kt-radio-group.md

@@ -0,0 +1,73 @@
+# `<kt-radio-group>`
+
+One choice among a few, all visible at once. The options are `<kt-radio>`
+children.
+
+```html
+<kt-radio-group label="Billing" name="billing" value="monthly">
+  <kt-radio value="monthly">Monthly</kt-radio>
+  <kt-radio value="yearly">Yearly — two months free</kt-radio>
+  <kt-radio value="custom" disabled>Custom contract</kt-radio>
+</kt-radio-group>
+```
+
+## Radio group, select or segmented control
+
+- **Radio group** — few enough options to show them all, and seeing them side
+  by side helps the choice. Options can be a sentence long.
+- **`<kt-select>`** — more options than fit, or the choice is minor.
+- **`<kt-segmented-control>`** — two to five short options in a toolbar, such
+  as a view switch.
+
+## Keyboard
+
+Native radios cannot form a group across shadow roots, so this is the ARIA
+radio group pattern — the one a screen reader expects:
+
+| Key       | Does                                                    |
+| --------- | ------------------------------------------------------- |
+| `Tab`     | Enters and leaves the group: one tab stop for all of it |
+| `↓` / `→` | Next option, and selects it                             |
+| `↑` / `←` | Previous option, and selects it                         |
+| `Space`   | Selects the focused option                              |
+
+The arrows wrap at the ends and skip disabled options. The tab stop sits on the
+chosen option, or on the first enabled one while nothing is chosen.
+
+## In a form
+
+A form control: it submits the chosen `value` under `name`, and nothing while
+none is chosen. `required` blocks submission until an option is chosen, `error`
+shows a message and marks every option, and `form.reset()` puts back the
+initial `value`.
+
+## API
+
+`<kt-radio-group>`
+
+| Property      | Attribute     | Type                         | Default      |
+| ------------- | ------------- | ---------------------------- | ------------ |
+| `value`       | `value`       | `string \| null`             | `null`       |
+| `name`        | `name`        | `string`                     | `''`         |
+| `label`       | `label`       | `string`                     | `''`         |
+| `disabled`    | `disabled`    | `boolean`                    | `false`      |
+| `required`    | `required`    | `boolean`                    | `false`      |
+| `orientation` | `orientation` | `'vertical' \| 'horizontal'` | `'vertical'` |
+| `error`       | `error`       | `string`                     | `''`         |
+
+`<kt-radio>`
+
+| Property   | Attribute  | Type      | Default |
+| ---------- | ---------- | --------- | ------- |
+| `value`    | `value`    | `string`  | `''`    |
+| `disabled` | `disabled` | `boolean` | `false` |
+
+| Event       | Detail                      |
+| ----------- | --------------------------- |
+| `kt-change` | `{ value: string \| null }` |
+
+| Part     | Element          | Description                 |
+| -------- | ---------------- | --------------------------- |
+| `base`   | `kt-radio-group` | The `role="radiogroup"` box |
+| `base`   | `kt-radio`       | The `role="radio"` row      |
+| `circle` | `kt-radio`       | The drawn circle            |

package/dist/docs/kt-segmented-control.md

@@ -0,0 +1,70 @@
+# `<kt-segmented-control>`
+
+A small set of mutually exclusive choices, drawn as one inset track with the
+selected segment raised out of it.
+
+```js
+control.options = [
+  { value: 'day', label: 'Day' },
+  { value: 'week', label: 'Week' },
+  { value: 'month', label: 'Month' },
+];
+control.value = 'week';
+control.addEventListener('kt-change', (e) => setRange(e.detail.value));
+```
+
+Two to five options that all fit on screen — a view switch, a date range. Past
+that, `<kt-select>`.
+
+## Keyboard
+
+It is a radio group, so the whole control is **one tab stop** and the arrows
+move between segments — a five-option control does not add five stops to the
+page.
+
+| Key                  | Does                                    |
+| -------------------- | --------------------------------------- |
+| `←` / `→`            | Previous / next segment, and selects it |
+| `↑` / `↓` (vertical) | Same, along the other axis              |
+| `Home` / `End`       | First / last segment                    |
+
+Arrows both move and select, which is standard radio-group behaviour. Disabled
+segments are skipped, and the selection wraps at the ends.
+
+## In a form
+
+It is a form control: inside a `<form>` it submits the chosen `value` under
+`name`, `required` blocks submission until a segment is chosen, and
+`form.reset()` puts back the initial value. Use it for a choice the form sends —
+a billing period, a plan — as readily as for a view switch.
+
+## API
+
+| Property      | Attribute     | Type                             | Default        |
+| ------------- | ------------- | -------------------------------- | -------------- |
+| `options`     | —             | `KtSegmentedOption[]`            | `[]`           |
+| `value`       | `value`       | `string \| number \| null`       | `null`         |
+| `size`        | `size`        | `'small' \| 'medium' \| 'large'` | `'medium'`     |
+| `orientation` | `orientation` | `'horizontal' \| 'vertical'`     | `'horizontal'` |
+| `disabled`    | `disabled`    | `boolean`                        | `false`        |
+| `label`       | `label`       | `string`                         | `''`           |
+| `name`        | `name`        | `string`                         | `''`           |
+| `required`    | `required`    | `boolean`                        | `false`        |
+
+```ts
+interface KtSegmentedOption {
+  value: string | number;
+  label?: string; // omit with an icon for an icon-only segment
+  icon?: string;
+  disabled?: boolean;
+}
+```
+
+| Event       | Detail                                                                 |
+| ----------- | ---------------------------------------------------------------------- |
+| `kt-change` | `{ value, option }` — not fired when the active segment is re-selected |
+
+| Part     | Description |
+| -------- | ----------- |
+| `base`   | The track   |
+| `option` | A segment   |

package/dist/docs/kt-select.md

@@ -0,0 +1,80 @@
+# `<kt-select>`
+
+A single-choice dropdown.
+
+```html
+<kt-select placeholder="Select a region" name="region"></kt-select>
+```
+
+```js
+select.options = [
+  { id: 'ne', label: 'North East' },
+  { id: 'sw', label: 'South West' },
+  { id: 'nw', label: 'North West', disabled: true },
+];
+
+select.addEventListener('kt-change', (e) => console.log(e.detail.value, e.detail.option));
+```
+
+`options` is a **property, not an attribute** — it is data, and serialising an
+array of objects through an HTML attribute is a mistake you only make once.
+
+## Keyboard
+
+This is a real listbox, not a button next to a floating div:
+
+| Key               | Does                                         |
+| ----------------- | -------------------------------------------- |
+| `↓` / `↑`         | Opens the list, then moves the active option |
+| `Home` / `End`    | Jumps to the first / last selectable option  |
+| `Enter` / `Space` | Opens, then commits the active option        |
+| `Escape`          | Closes, changing nothing                     |
+| `Tab`             | Closes and moves on                          |
+
+Disabled options are skipped by the arrows rather than merely being
+unclickable, and the trigger carries `aria-activedescendant` so a screen reader
+follows the highlight.
+
+## Animation
+
+The popup stays in the DOM and animates through `opacity` and `transform`, held
+out of the way with `visibility: hidden`. A popup that unmounts cannot animate
+out; one that only toggles `display` cannot animate at all.
+
+## API
+
+| Property      | Attribute     | Type                             | Default         |
+| ------------- | ------------- | -------------------------------- | --------------- |
+| `options`     | —             | `KtOption[]`                     | `[]`            |
+| `value`       | `value`       | `string \| number \| null`       | `null`          |
+| `placeholder` | `placeholder` | `string`                         | `'Select'`      |
+| `name`        | `name`        | `string`                         | `''`            |
+| `size`        | `size`        | `'small' \| 'medium' \| 'large'` | `'medium'`      |
+| `disabled`    | `disabled`    | `boolean`                        | `false`         |
+| `required`    | `required`    | `boolean`                        | `false`         |
+| `error`       | `error`       | `string`                         | `''`            |
+| `clearable`   | `clearable`   | `boolean`                        | `true`          |
+| `label`       | `label`       | `string`                         | `''`            |
+| `emptyText`   | `empty-text`  | `string`                         | `'No options…'` |
+
+```ts
+interface KtOption {
+  id: string | number;
+  label?: string; // falls back to String(id)
+  disabled?: boolean;
+}
+```
+
+| Getter           | Returns                             |
+| ---------------- | ----------------------------------- |
+| `selectedOption` | The chosen `KtOption`, or undefined |
+
+| Event       | Detail                                                          |
+| ----------- | --------------------------------------------------------------- |
+| `kt-change` | `{ value: string \| number \| null, option: KtOption \| null }` |
+
+| Part      | Description     |
+| --------- | --------------- |
+| `trigger` | The button      |
+| `popup`   | The option list |
+| `option`  | An option row   |

package/dist/docs/kt-side-panel.md

@@ -0,0 +1,59 @@
+# `<kt-side-panel>`
+
+A drawer sliding in from the right, for viewing or editing one record without
+losing the list behind it.
+
+```html
+<kt-side-panel open eyebrow="Details" heading="Entity 4812">
+  <kt-label-input label="Nom"><kt-input value="Entity 4812"></kt-input></kt-label-input>
+  <kt-button slot="footer" full-width>Save</kt-button>
+</kt-side-panel>
+```
+
+## Built on `<dialog>`
+
+`showModal()` is doing real work here. It puts the panel in the **top layer**,
+above every stacking context — which no z-index can guarantee — traps focus
+inside it, makes the rest of the page inert, and handles Escape.
+
+The fixed-position div this replaces did none of that: tabbing walked straight
+out of the panel into the page behind it.
+
+## Guarding unsaved changes
+
+`kt-close` is cancelable. Cancel it and the panel stays open — including when
+Escape was what triggered it.
+
+```js
+panel.addEventListener('kt-close', (e) => {
+  if (!form.dirty) return;
+  e.preventDefault();
+  confirmDialog.open = true;
+});
+```
+
+`no-backdrop-close` removes backdrop dismissal. Escape still works: a modal you
+cannot escape from is a trap, and cancelling `kt-close` is the right way to
+guard it.
+
+## API
+
+| Property          | Attribute           | Type      | Default     |
+| ----------------- | ------------------- | --------- | ----------- |
+| `open`            | `open`              | `boolean` | `false`     |
+| `eyebrow`         | `eyebrow`           | `string`  | `'Details'` |
+| `heading`         | `heading`           | `string`  | `''`        |
+| `noBackdropClose` | `no-backdrop-close` | `boolean` | `false`     |
+
+| Method           | Description                               |
+| ---------------- | ----------------------------------------- |
+| `requestClose()` | Fires `kt-close`, closes unless cancelled |
+
+| Event      | Description                      |
+| ---------- | -------------------------------- |
+| `kt-close` | Dismissal requested. Cancelable. |
+
+| Slot      | Description           |
+| --------- | --------------------- |
+| _default_ | Panel body            |
+| `footer`  | Pinned below the body |

package/dist/docs/kt-skeleton.md

@@ -0,0 +1,46 @@
+# `<kt-skeleton>`
+
+A loading placeholder, pulsing between `--surface-raised` and `--surface-hover`
+— the same elevation ramp everything else in Kanto uses, so it reads as part of
+the page rather than as a grey rectangle pasted onto it.
+
+```html
+<kt-skeleton count="3"></kt-skeleton>
+<kt-skeleton variant="circle" width="48px" height="48px"></kt-skeleton>
+<kt-skeleton variant="rect" height="180px"></kt-skeleton>
+```
+
+With `count` above one the last line is drawn at 60% width, which is the shape a
+paragraph actually has. Without it, a skeleton reads as stacked bars rather than
+as text.
+
+## Accessibility
+
+The element sets `aria-hidden` on itself: it is a picture of content that is not
+there yet, and reading out a dozen empty boxes is worse than silence.
+
+Announce the loading state on the region that owns it:
+
+```html
+<section aria-busy="true">
+  <kt-skeleton count="4"></kt-skeleton>
+</section>
+```
+
+The pulse stops under `prefers-reduced-motion`.
+
+## API
+
+| Property   | Attribute  | Type                           | Default  |
+| ---------- | ---------- | ------------------------------ | -------- |
+| `variant`  | `variant`  | `'text' \| 'rect' \| 'circle'` | `'text'` |
+| `width`    | `width`    | `string` (any CSS length)      | `''`     |
+| `height`   | `height`   | `string`                       | `''`     |
+| `count`    | `count`    | `number`                       | `1`      |
+| `animated` | `animated` | `boolean`                      | `true`   |
+
+Defaults per variant: text 100% × 14px, rect 100% × 80px, circle 40 × 40px.
+
+| Part   | Description          |
+| ------ | -------------------- |
+| `line` | One placeholder line |

package/dist/docs/kt-split-button.md

@@ -0,0 +1,105 @@
+# `<kt-split-button>`
+
+One button carrying a menu of related actions. The body runs the action a user
+wants nine times out of ten; the caret opens the rest.
+
+```html
+<kt-split-button>Save</kt-split-button>
+```
+
+```js
+save.items = [
+  { id: 'close', label: 'Save and close' },
+  { id: 'copy', label: 'Save a copy' },
+  { id: 'pdf', label: 'Export as PDF', icon: 'file' },
+  { id: 'discard', label: 'Discard changes', variant: 'danger' },
+];
+save.addEventListener('click', () => save());
+save.addEventListener('kt-select', (e) => run(e.detail.value));
+```
+
+## When not to use it
+
+**The rows must be variations on the primary action.** "Save and close" belongs
+under "Save"; "Delete" does not. For an unrelated set of actions there is no
+default worth promoting — use `<kt-dropdown>`, which offers none.
+
+**One primary button per screen still holds.** A split button is one button,
+not two, so it counts once.
+
+## The two segments
+
+A press on the caret never surfaces as a `click` on the host. A single `click`
+listener therefore means the primary action and nothing else — no checking what
+was pressed, no accidental double handling.
+
+`variant` and `size` are forwarded to both segments, so the pair always reads as
+one control. The seam between them is a hairline of the page showing through,
+the same way elevation works everywhere else in the system.
+
+## Items
+
+| Field      | Type                    |                                 |
+| ---------- | ----------------------- | ------------------------------- |
+| `id`       | `string \| number`      | Carried in `kt-select`          |
+| `label`    | `string`                | Falls back to `id`              |
+| `icon`     | `string`                | Lucide name, kebab-case         |
+| `disabled` | `boolean`               | Stays visible, cannot be chosen |
+| `variant`  | `'default' \| 'danger'` | `danger` tints the row red      |
+
+## Keyboard
+
+| Key                 | Does                                        |
+| ------------------- | ------------------------------------------- |
+| `Enter` / `Space`   | Runs the focused segment or row             |
+| `Arrow down` / `up` | Walks the rows, wrapping, skipping disabled |
+| `Home` / `End`      | First / last selectable row                 |
+| `Escape`            | Closes the menu                             |
+
+Opening the menu moves focus to the first selectable row. Closing it hands
+focus back to the caret — unless a click outside already took focus elsewhere,
+in which case it is left where the user put it.
+
+## Placement
+
+The menu hangs off the right edge of the button and flips above it when there is
+not enough room below. `preferred-placement="top"` reverses the preference.
+
+## API
+
+| Property             | Attribute             | Type                             | Default          |
+| -------------------- | --------------------- | -------------------------------- | ---------------- |
+| `items`              | —                     | `KtSplitButtonItem[]`            | `[]`             |
+| `variant`            | `variant`             | same ten as `<kt-button>`        | `'primary'`      |
+| `size`               | `size`                | `'small' \| 'medium' \| 'large'` | `'medium'`       |
+| `disabled`           | `disabled`            | `boolean`                        | `false`          |
+| `icon`               | `icon`                | `string`                         | `''`             |
+| `menuLabel`          | `menu-label`          | `string`                         | `'More actions'` |
+| `preferredPlacement` | `preferred-placement` | `'bottom' \| 'top'`              | `'bottom'`       |
+| `emptyText`          | `empty-text`          | `string`                         | `'No actions'`   |
+
+| Method / getter | Description                 |
+| --------------- | --------------------------- |
+| `show()`        | Opens the menu              |
+| `hide()`        | Closes it                   |
+| `toggle()`      | Either                      |
+| `isOpen`        | Whether it is open          |
+| `focus()`       | Focuses the primary segment |
+
+| Event       | Detail                      |
+| ----------- | --------------------------- |
+| `click`     | native — the primary action |
+| `kt-select` | `{ value, item }`           |
+| `kt-open`   | —                           |
+| `kt-close`  | —                           |
+
+| Slot      | Description                |
+| --------- | -------------------------- |
+| _default_ | The primary action's label |
+
+| Part     | Description                        |
+| -------- | ---------------------------------- |
+| `action` | The primary `<kt-button>`          |
+| `caret`  | The `<kt-button>` opening the menu |
+| `menu`   | The list of rows                   |
+| `item`   | A menu row                         |

package/dist/docs/kt-stat.md

@@ -0,0 +1,57 @@
+# `<kt-stat>`
+
+One headline figure: a label, a value, and how it moved.
+
+```html
+<kt-stat label="Revenue" value="$292,342" delta="-3%" trend="down" icon="dollar-sign"></kt-stat>
+<kt-stat label="Customers" value="712" delta="+12%" trend="up" icon="users"></kt-stat>
+<kt-stat label="Churn" value="2.1%" delta="-0.4%" trend="down" inverted></kt-stat>
+```
+
+## The colour comes from the meaning, not the sign
+
+This is the mistake every dashboard makes. `-3%` on revenue is bad news; `-0.4%`
+on churn is good news. The sign is identical.
+
+So `trend` says which way the number went, and `inverted` says that down is the
+direction you wanted. The badge takes its colour from the two together — never
+from the minus sign.
+
+| `trend` | `inverted` | Badge   |
+| ------- | ---------- | ------- |
+| `up`    | no         | success |
+| `down`  | no         | danger  |
+| `up`    | yes        | danger  |
+| `down`  | yes        | success |
+| `flat`  | either     | neutral |
+
+Leave `trend` off and the badge stays neutral, which is the right default: a
+number with no stated direction should not be coloured as though it had one.
+
+## Anatomy
+
+The icon sits on a tinted disc rather than bare — at this size a lone glyph
+reads as noise next to the figure. The label is an overline, deliberately
+quieter than the number it introduces.
+
+The default slot takes anything that belongs under the value — a sparkline, a
+caption, a breakdown.
+
+## API
+
+| Property   | Attribute  | Type                       | Default    |
+| ---------- | ---------- | -------------------------- | ---------- |
+| `label`    | `label`    | `string`                   | `''`       |
+| `value`    | `value`    | `string`                   | `''`       |
+| `delta`    | `delta`    | `string`                   | `''`       |
+| `trend`    | `trend`    | `'up' \| 'down' \| 'flat'` | `'flat'`   |
+| `inverted` | `inverted` | `boolean`                  | `false`    |
+| `icon`     | `icon`     | `string`                   | `''`       |
+| `caption`  | `caption`  | `string`                   | `''`       |
+| `size`     | `size`     | `'small' \| 'medium'`      | `'medium'` |
+| `loading`  | `loading`  | `boolean`                  | `false`    |
+
+| Part    | Description |
+| ------- | ----------- |
+| `base`  | The tile    |
+| `value` | The figure  |

package/dist/docs/kt-sub-menu-navigation.md

@@ -0,0 +1,118 @@
+# `<kt-sub-menu-navigation>`
+
+The sidebar: uppercase overline section titles over lists of links, to any
+depth. This is the navigation both the Kanto docs shell and the console
+application use.
+
+```js
+nav.sections = [
+  {
+    title: 'Workspace',
+    items: [
+      { label: 'Home', href: '#/home', icon: 'house' },
+      { label: 'Inbox', href: '#/inbox', icon: 'inbox', badge: '4' },
+      {
+        label: 'Settings',
+        icon: 'settings',
+        children: [
+          { label: 'General', href: '#/settings/general' },
+          {
+            label: 'Members',
+            children: [{ label: 'Roles', href: '#/settings/members/roles' }],
+          },
+        ],
+      },
+    ],
+  },
+];
+nav.activeHref = location.hash;
+```
+
+A section without a `title` renders as a bare list — useful for a trailing group
+of links that needs no heading.
+
+## Nesting
+
+The recursion is the point. Every product grows a third level eventually —
+Settings holds Members holds Roles — and the usual answer is to hand-roll that
+one branch beside the component, which is how two navigation styles end up on
+one screen. Here a branch renders exactly like the level above it: same row,
+same states, indented by its depth, with a chevron instead of an href.
+
+An item with `children` is a `<button aria-expanded>`, not a link, because it
+goes nowhere. Give a branch `open: true` to start it expanded.
+
+**A branch holding the current page opens itself**, whatever was clicked, and
+refuses to fold while it still does — arriving on a page the sidebar does not
+show is worse than losing a fold. It is marked `within` rather than `active`:
+the current page is below it, not it.
+
+## Active state
+
+Set `activeHref` and the matching link is highlighted, marked
+`aria-current="page"` and given an accent bar. The bar matters: it is what
+survives a forced-colours mode, where the tint does not. An item can also force
+the state with `active: true`, for routes that do not map to a single href.
+
+## In a sidebar
+
+`flush` drops the card background, padding and radius, for a full-height
+sidebar that already owns its surface. `collapsed` reduces every row to its
+icon; labels, badges and open branches are hidden rather than clipped, because
+a label sliced in half at 48px reads as a bug rather than as a narrow sidebar.
+
+```html
+<kt-sub-menu-navigation flush collapsed></kt-sub-menu-navigation>
+```
+
+## Client-side routing
+
+Same contract as `<kt-breadcrumb>`: `kt-navigate` is cancelable, and modified
+clicks are left to the browser.
+
+```js
+nav.addEventListener('kt-navigate', (e) => {
+  e.preventDefault();
+  router.push(e.detail.item.href);
+});
+```
+
+## API
+
+| Property     | Attribute     | Type             | Default                  |
+| ------------ | ------------- | ---------------- | ------------------------ |
+| `sections`   | —             | `KtNavSection[]` | `[]`                     |
+| `activeHref` | `active-href` | `string`         | `''`                     |
+| `label`      | `label`       | `string`         | `'Secondary navigation'` |
+| `flush`      | `flush`       | `boolean`        | `false`                  |
+| `collapsed`  | `collapsed`   | `boolean`        | `false`                  |
+
+```ts
+interface KtNavSection {
+  title?: string;
+  items: KtNavItem[];
+}
+
+interface KtNavItem {
+  label: string;
+  href?: string;
+  icon?: string; // lucide name; conventionally only the top level carries one
+  badge?: string; // a count or a short status, right-aligned
+  active?: boolean;
+  disabled?: boolean;
+  children?: KtNavItem[]; // any depth
+  open?: boolean; // expanded on first render
+}
+```
+
+| Event         | Detail                  |
+| ------------- | ----------------------- |
+| `kt-navigate` | `{ item }` — cancelable |
+| `kt-toggle`   | `{ item, open }`        |
+
+| Part      | Description                            |
+| --------- | -------------------------------------- |
+| `nav`     | The `<nav>`                            |
+| `section` | A section                              |
+| `title`   | A section title                        |
+| `item`    | A navigation link or branch, any depth |