kanto-ds 1.6.0 → 1.7.0

package/dist/docs/kt-input.md

@@ -0,0 +1,137 @@
+# `<kt-input>`
+
+A single-line text field.
+
+Kanto fields are borderless: a fill on `--color-dark-12` that gains a 2px
+**outline** — grey on hover, primary on focus, danger on error. An outline sits
+outside the box, so none of those states reflow the layout.
+
+```html
+<kt-input placeholder="Search everything..." icon="search"></kt-input>
+<kt-input type="password" name="password"></kt-input>
+<kt-input error="Invalid email address" value="not-an-address"></kt-input>
+<kt-input size="small" placeholder="Filtrer"></kt-input>
+```
+
+## Forms
+
+`<kt-input>` is a form-associated custom element. It serialises into `FormData`
+under its `name`, resets with the form, and reports validity like a native
+input — no hidden mirror input, no manual wiring.
+
+```html
+<form>
+  <kt-input name="email" type="email" required></kt-input>
+  <kt-button type="submit">Send</kt-button>
+</form>
+```
+
+```js
+new FormData(form).get('email'); // the field's value
+```
+
+## Reading the value
+
+`value` is a property, and a `value` attribute seeds it and becomes the reset
+value. Listn for `kt-change` for a committed value, `kt-input` for every
+keystroke:
+
+```js
+input.addEventListener('kt-change', (e) => console.log(e.detail.value));
+```
+
+The inner `change` event is stopped at the boundary rather than allowed to leak
+out retargeted and untyped.
+
+## Password and clear
+
+`type="password"` adds a reveal toggle. Any non-empty field shows a clear
+button, which rotates 90° on hover; set `clearable="false"` to suppress it.
+Both are `tabindex="-1"` — they are conveniences for the mouse, and putting
+them in the tab order would double the number of stops in a form.
+
+## Phone mode
+
+`type="tel"` adds a country picker: flag, dial code, and a searchable panel.
+
+```html
+<kt-input type="tel" name="phone" country="be"></kt-input>
+```
+
+`value` holds the **national digits only** — `612345678` — and the field
+displays them grouped the way the country's `format` groups them
+(`1 23 45 67 89` for France gives `6 12 34 56 78`). What the _form_ receives is
+the full international number, `+33612345678`: submitting national digits
+without the country would throw away the thing the user just picked.
+
+A number typed with the country's trunk prefix — `06 12 34 56 78` after +33 —
+puts the field in its error state: `+330612345678` does not exist. The message
+shows in a tooltip on the alert icon — on hover, and while the field has focus
+so it reaches keyboard users too, until Escape puts it away — is read out
+through the control's description, and the form sees a `patternMismatch`. Countries where a leading 0
+belongs to the number, like Italy, have no `trunkPrefix` and are never flagged.
+An `error` set by the application wins over this check.
+
+About 95 countries ship by default, sorted by name. Pass your own list to
+narrow or widen it:
+
+```js
+input.countries = [
+  { id: 'fr', name: 'France', dialCode: '33', format: '1 23 45 67 89', trunkPrefix: '0' },
+  { id: 'it', name: 'Italy', dialCode: '39', format: '312 345 6789' },
+];
+```
+
+Phone mode is reached **only** through `type="tel"`. Sniffing the placeholder,
+the name or the icon for `/tel|phone/` instead would turn any field named
+`telephone_verifie` into a country picker.
+
+## Labelling
+
+Wrap the field in `<kt-label-input>`, or give it a `label` when there is no
+visible one:
+
+```html
+<kt-label-input label="Email address" required>
+  <kt-input name="email" type="email" required></kt-input>
+</kt-label-input>
+
+<kt-input label="Search" icon="search"></kt-input>
+```
+
+## API
+
+| Property       | Attribute      | Type                             | Default    |
+| -------------- | -------------- | -------------------------------- | ---------- |
+| `value`        | `value`        | `string`                         | `''`       |
+| `name`         | `name`         | `string`                         | `''`       |
+| `type`         | `type`         | `string`                         | `'text'`   |
+| `placeholder`  | `placeholder`  | `string`                         | `''`       |
+| `size`         | `size`         | `'small' \| 'medium' \| 'large'` | `'medium'` |
+| `disabled`     | `disabled`     | `boolean`                        | `false`    |
+| `readonly`     | `readonly`     | `boolean`                        | `false`    |
+| `required`     | `required`     | `boolean`                        | `false`    |
+| `icon`         | `icon`         | `string`                         | `''`       |
+| `error`        | `error`        | `string`                         | `''`       |
+| `clearable`    | `clearable`    | `boolean`                        | `true`     |
+| `label`        | `label`        | `string`                         | `''`       |
+| `autocomplete` | `autocomplete` | `string`                         | `''`       |
+| `maxlength`    | `maxlength`    | `number`                         | —          |
+
+| Method     | Description                  |
+| ---------- | ---------------------------- |
+| `focus()`  | Focuses the inner input      |
+| `blur()`   | Blurs it                     |
+| `select()` | Selects the field's contents |
+
+| Event       | Detail              | Fired when                   |
+| ----------- | ------------------- | ---------------------------- |
+| `kt-input`  | `{ value: string }` | On every keystroke           |
+| `kt-change` | `{ value: string }` | On commit (blur or Enter)    |
+| `kt-clear`  | —                   | The clear button was pressed |
+
+| Part      | Description           |
+| --------- | --------------------- |
+| `base`    | The field container   |
+| `control` | The native `<input>`  |
+| `actions` | The trailing icon row |

package/dist/docs/kt-kbd.md

@@ -0,0 +1,44 @@
+# `<kt-kbd>`
+
+A keyboard shortcut, rendered per platform.
+
+```html
+<kt-kbd keys="mod k"></kt-kbd>
+<kt-kbd keys="ctrl shift p"></kt-kbd>
+<kt-kbd>/</kt-kbd>
+```
+
+`mod k` shows `⌘ K` on a Mac and `Ctrl K` everywhere else. A shortcut printed
+with the wrong modifier is worse than no shortcut at all — the reader tries it,
+nothing happens, and they stop trusting the hints.
+
+## `mod` versus `meta`
+
+Reach for **`mod`**: it means "the primary shortcut modifier", which is Command
+on a Mac and Control elsewhere.
+
+`meta` stays honest — on Windows the Meta key really is the Windows key, so that
+is what it prints. Most design systems quietly map `meta` to Ctrl and are wrong
+about it on one platform.
+
+| Key                              | Mac         | Elsewhere               |
+| -------------------------------- | ----------- | ----------------------- |
+| `mod`                            | ⌘           | Ctrl                    |
+| `meta`                           | ⌘           | Win                     |
+| `ctrl`                           | ⌃           | Ctrl                    |
+| `alt` / `option`                 | ⌥           | Alt                     |
+| `shift`                          | ⇧           | Shift                   |
+| `enter` / `escape` / `backspace` | ↵ / esc / ⌫ | Enter / Esc / Backspace |
+
+Anything else is passed through uppercased.
+
+## API
+
+| Property   | Attribute  | Type                         | Default  |
+| ---------- | ---------- | ---------------------------- | -------- |
+| `keys`     | `keys`     | `string` (space-separated)   | `''`     |
+| `platform` | `platform` | `'auto' \| 'mac' \| 'other'` | `'auto'` |
+
+| Getter   | Returns                            |
+| -------- | ---------------------------------- |
+| `labels` | The keys as they will be displayed |

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

@@ -0,0 +1,54 @@
+# `<kt-label-input>`
+
+A label above a form control, with a red asterisk when it is required.
+
+```html
+<kt-label-input label="Email address" required>
+  <kt-input name="email" type="email" required></kt-input>
+</kt-label-input>
+```
+
+## Why it is not a `<label>`
+
+Native label association does not cross a shadow boundary. `for="..."` needs the
+control's id in the same tree, and wrapping a control in a `<label>` only works
+when both are in that tree — a slotted `<kt-input>` is not.
+
+So this element passes its text down to the slotted control's `label` property,
+which the control turns into its own `aria-label`. Controls without that
+property get `aria-label` set directly. Clicking the label focuses the control,
+the way a real label does.
+
+That means the asterisk is `aria-hidden`: screen readers get "required" from the
+control's own `required` attribute, not from a decorative star in the label.
+
+## Works with anything
+
+```html
+<kt-label-input label="Notes">
+  <kt-textarea maxlength="500"></kt-textarea>
+</kt-label-input>
+
+<kt-label-input label="Region">
+  <kt-select></kt-select>
+</kt-label-input>
+
+<kt-label-input label="File">
+  <input type="file" />
+</kt-label-input>
+```
+
+## API
+
+| Property   | Attribute  | Type      | Default |
+| ---------- | ---------- | --------- | ------- |
+| `label`    | `label`    | `string`  | `''`    |
+| `required` | `required` | `boolean` | `false` |
+
+| Slot      | Description          |
+| --------- | -------------------- |
+| _default_ | The control to label |
+
+| Part    | Description   |
+| ------- | ------------- |
+| `label` | The `<label>` |

package/dist/docs/kt-meter.md

@@ -0,0 +1,79 @@
+# `<kt-meter>`
+
+How a fixed total is spent: storage by file type, a budget by category, seats by
+role.
+
+```html
+<kt-meter label="Storage" used="25.8 GB used" total="of 983 GB" value="3"></kt-meter>
+```
+
+```js
+meter.segments = [
+  { label: 'Documents', value: 16.14 },
+  { label: 'Photos', value: 3.94 },
+  { label: 'Other', value: 5.72 },
+];
+meter.max = 983;
+meter.showLegend = true;
+meter.format = (n) => `${n} GB`;
+```
+
+## Against `<kt-progress-bar>`
+
+A progress bar answers **how far along**: it fills toward completion, and
+reaching the end is good news — which is why it turns green there. A meter
+answers **how it is divided**: it is full from the moment it renders, and
+reaching the end is bad news.
+
+Different question, different component. A bar that shows one and means the
+other is a common way to mislead a reader, so the two are not a variant of each
+other here.
+
+## Segments and colour
+
+Segments take `--chart-series-N` by position — the same fixed, never-cycled
+order the charts use, so a category is the same colour in the meter and in the
+chart beside it. Pass `color` to override one. Past eight, fold the tail into
+an "Other" segment rather than starting the palette again under a new meaning.
+
+Adjacent fills are separated by a 2px gap of the surface, so two segments of
+similar hue still read as two.
+
+Without `max`, segments are measured against their own sum and the bar is full.
+With `max`, they are measured against it and the remainder stays empty — which
+is what "25.8 GB of 983 GB" means.
+
+## API
+
+| Property     | Attribute     | Type                        | Default         |
+| ------------ | ------------- | --------------------------- | --------------- |
+| `label`      | `label`       | `string`                    | `''`            |
+| `used`       | `used`        | `string`                    | `''`            |
+| `total`      | `total`       | `string`                    | `''`            |
+| `value`      | `value`       | `number` (0–100)            | `0`             |
+| `segments`   | —             | `KtMeterSegment[]`          | `[]`            |
+| `max`        | `max`         | `number`                    | `0` (their sum) |
+| `showLegend` | `show-legend` | `boolean`                   | `false`         |
+| `format`     | —             | `(value: number) => string` | `String`        |
+
+`used` and `total` are free strings rather than numbers, because the caption is
+prose — "25.8 GB used", "of 983 GB", "7 of 20 seats" — and formatting it is the
+application's job, not the meter's.
+
+```ts
+interface KtMeterSegment {
+  label: string;
+  value: number;
+  color?: string;
+}
+```
+
+| CSS property        | Description      | Default |
+| ------------------- | ---------------- | ------- |
+| `--kt-meter-height` | The bar's height | `8px`   |
+
+| Part     | Description     |
+| -------- | --------------- |
+| `base`   | The container   |
+| `track`  | The bar         |
+| `legend` | The legend list |

package/dist/docs/kt-modal.md

@@ -0,0 +1,62 @@
+# `<kt-modal>`
+
+A centred dialog for anything that is not a yes/no question.
+
+```html
+<kt-modal open heading="Compose" description="This goes to the whole team.">
+  <kt-textarea rows="6" placeholder="Write something..."></kt-textarea>
+  <kt-button slot="footer" variant="dark">Save draft</kt-button>
+  <kt-button slot="footer" icon="send">Send</kt-button>
+</kt-modal>
+```
+
+## Against `<kt-confirm-dialog>`
+
+The confirm dialog asks one thing and offers two answers, and its defaults are
+tuned for that — Cancel takes focus, the confirm button is red. This one holds
+_content_: a compose window, a command palette, a picker. You choose the footer.
+
+Both are native `<dialog>`s, so the top layer, focus containment, page
+inertness and Escape come from the platform rather than from a focus trap that
+leaks.
+
+## Guarding unsaved work
+
+`kt-close` is cancelable, and that covers Escape too:
+
+```js
+modal.addEventListener('kt-close', (e) => {
+  if (!draft.dirty) return;
+  e.preventDefault();
+  confirmDiscard.open = true;
+});
+```
+
+`no-close-button` and `no-backdrop-close` narrow the ways out, but **Escape
+always works**. A modal you cannot leave is a trap; cancelling `kt-close` is the
+right way to guard one.
+
+## API
+
+| Property          | Attribute           | Type                                       | Default    |
+| ----------------- | ------------------- | ------------------------------------------ | ---------- |
+| `open`            | `open`              | `boolean`                                  | `false`    |
+| `heading`         | `heading`           | `string`                                   | `''`       |
+| `description`     | `description`       | `string`                                   | `''`       |
+| `size`            | `size`              | `'small' \| 'medium' \| 'large' \| 'full'` | `'medium'` |
+| `noCloseButton`   | `no-close-button`   | `boolean`                                  | `false`    |
+| `noBackdropClose` | `no-backdrop-close` | `boolean`                                  | `false`    |
+
+| Method           | Description                               |
+| ---------------- | ----------------------------------------- |
+| `requestClose()` | Fires `kt-close`, closes unless cancelled |
+
+| Slot      | Description                      |
+| --------- | -------------------------------- |
+| _default_ | The body                         |
+| `header`  | Replaces the `heading` attribute |
+| `footer`  | Actions. Hidden when empty.      |
+
+| Event      | Description                      |
+| ---------- | -------------------------------- |
+| `kt-close` | Dismissal requested. Cancelable. |

package/dist/docs/kt-multi-select.md

@@ -0,0 +1,115 @@
+# `<kt-multi-select>`
+
+Several choices from a list: type to narrow it, pick as many as you need.
+
+```html
+<kt-multi-select label="Regions" placeholder="Any region"></kt-multi-select>
+```
+
+```js
+select.options = [
+  { id: 'ne', label: 'North East' },
+  { id: 'sw', label: 'South West' },
+  { id: 'nw', label: 'North West' },
+];
+select.value = ['ne'];
+
+select.addEventListener('kt-change', (e) => filter(e.detail.value));
+```
+
+## Against the alternatives
+
+Reach for it when a filter takes several values from a list long enough to
+search — regions, owners, tags. For two or three options that all fit on
+screen, a `<kt-toggle-button-group multiple>` shows them without a click. For
+one value, `<kt-input-menu>` or `<kt-select>`.
+
+## One line, whatever is chosen
+
+Each choice shows in the field as a chip: a fill set into the field, the same
+distance from its top, bottom and left edge, with its own remove button — the
+family of a chosen option, not an outlined tag. The field keeps to one line:
+the chips that do not fit collapse into a quiet **+N** beside the ones that do,
+or into "3 selected" when not one fits, so the field sits in a row of filters
+without changing its height.
+The open list shows every option, the chosen ones ticked — which is where the
+hidden ones can be seen and taken out. Widen the field and more chips come
+back.
+
+## Choosing
+
+The list stays open after each choice, since the point is to make several.
+Clicking a chosen option, or pressing Enter on it, takes it out again; the
+order of `value` is the order things were chosen. Disabled options can be seen
+but not chosen.
+
+`kt-change` fires with the whole new `value` and the matching `options`, not
+the one that changed: a filter usually wants the full set.
+
+## Server-side filtering
+
+`kt-filter` fires on every keystroke, as on `<kt-input-menu>`: assign the
+results to `options` and the list follows. Chosen values stay chosen while
+their options are filtered out — a chip whose option is no longer in `options`
+shows its id.
+
+```js
+select.addEventListener('kt-filter', async (e) => {
+  select.options = await search(e.detail.query);
+});
+```
+
+## In a form
+
+A form control, submitted like `<select multiple>`: one entry per chosen id
+under `name`, and nothing at all while empty — read them with
+`formData.getAll(name)`. `required` blocks submission until at least one value
+is chosen, `form.reset()` puts back the values it started with, and a
+`<fieldset disabled>` disables it.
+
+## Accessibility
+
+The field is an ARIA combobox over a listbox marked `aria-multiselectable`,
+each option `aria-selected` when chosen. The number chosen is part of the
+field's description ("2 selected"), since the chips may not all be visible.
+Each chip's remove button is named after it — "Remove North East".
+
+## Keyboard
+
+| Key            | Does                                               |
+| -------------- | -------------------------------------------------- |
+| `↓` / `↑`      | Opens the list, then moves the active option       |
+| `Home` / `End` | First / last match                                 |
+| `Enter`        | Adds or removes the active option; the list stays  |
+| `Backspace`    | In an empty field, removes the last chip           |
+| `Escape`       | Closes and forgets the query, keeping every choice |
+| `Tab`          | Closes and moves on                                |
+
+## API
+
+| Property      | Attribute     | Type                   | Default         |
+| ------------- | ------------- | ---------------------- | --------------- |
+| `options`     | —             | `KtOption[]`           | `[]`            |
+| `value`       | —             | `(string \| number)[]` | `[]`            |
+| `placeholder` | `placeholder` | `string`               | `''`            |
+| `name`        | `name`        | `string`               | `''`            |
+| `disabled`    | `disabled`    | `boolean`              | `false`         |
+| `required`    | `required`    | `boolean`              | `false`         |
+| `error`       | `error`       | `string`               | `''`            |
+| `label`       | `label`       | `string`               | `''`            |
+| `emptyText`   | `empty-text`  | `string`               | `'No options…'` |
+
+`selectedOptions` (read-only) is the chosen options, in the order chosen.
+
+| Event       | Detail               |
+| ----------- | -------------------- |
+| `kt-change` | `{ value, options }` |
+| `kt-filter` | `{ query: string }`  |
+
+| Part      | Description          |
+| --------- | -------------------- |
+| `control` | The field            |
+| `chips`   | The row of chips     |
+| `input`   | The native `<input>` |
+| `popup`   | The option list      |
+| `option`  | An option row        |

package/dist/docs/kt-page-header.md

@@ -0,0 +1,53 @@
+# `<kt-page-header>`
+
+The block every screen opens with: an overline, a title, a sentence, and the
+actions that belong to the page rather than to anything on it.
+
+```html
+<kt-page-header
+  eyebrow="Dashboard"
+  heading="Good evening"
+  description="An overview of your workspace: recent files, integrations and activity."
+>
+  <kt-button slot="actions" variant="dark" icon="upload">Upload a file</kt-button>
+  <kt-button slot="actions" icon="plus">New document</kt-button>
+</kt-page-header>
+```
+
+It exists because it was being rebuilt on every screen, and the copies drifted:
+different heading levels, different gaps, actions sometimes above the title and
+sometimes beside it. None of those are decisions worth making twice.
+
+## Two levels
+
+`level="page"` (the default) renders an `<h1>` at display scale — one per
+screen. `level="section"` renders an `<h2>` at body scale, for a region inside
+a page, where the trailing action is usually a link onward rather than a button:
+
+```html
+<kt-page-header level="section" heading="Recently opened">
+  <a slot="actions" href="#/files">See all files</a>
+</kt-page-header>
+```
+
+Both wrap on a narrow screen: the actions drop under the copy rather than
+squeezing the title.
+
+## API
+
+| Property      | Attribute     | Type                  | Default  |
+| ------------- | ------------- | --------------------- | -------- |
+| `eyebrow`     | `eyebrow`     | `string`              | `''`     |
+| `heading`     | `heading`     | `string`              | `''`     |
+| `description` | `description` | `string`              | `''`     |
+| `level`       | `level`       | `'page' \| 'section'` | `'page'` |
+
+| Slot      | Description                                 |
+| --------- | ------------------------------------------- |
+| _default_ | Extra content under the description         |
+| `actions` | Buttons or a link, trailing on wide screens |
+
+| Part      | Description         |
+| --------- | ------------------- |
+| `base`    | The container       |
+| `heading` | The heading element |

package/dist/docs/kt-pagination.md

@@ -0,0 +1,36 @@
+# `<kt-pagination>`
+
+Previous / next paging, with the position between them.
+
+```html
+<kt-pagination page="2" total-pages="7"></kt-pagination>
+```
+
+```js
+pager.addEventListener('kt-page-change', (e) => load(e.detail.page));
+```
+
+`<kt-table>` uses it in its own footer; it is separate so a card list or a
+gallery can page the same way a table does.
+
+The page number is `aria-live="polite"`, so a change is announced without
+interrupting whatever the reader is already working through. The element clamps
+to the range: it will not emit a page below 1 or past `total-pages`.
+
+## API
+
+| Property     | Attribute     | Type     | Default        |
+| ------------ | ------------- | -------- | -------------- |
+| `page`       | `page`        | `number` | `1`            |
+| `totalPages` | `total-pages` | `number` | `1`            |
+| `label`      | `label`       | `string` | `'Pagination'` |
+
+| Event            | Detail             |
+| ---------------- | ------------------ |
+| `kt-page-change` | `{ page: number }` |
+
+| Part       | Description           |
+| ---------- | --------------------- |
+| `previous` | The previous button   |
+| `next`     | The next button       |
+| `info`     | The "Page 2 / 7" text |

package/dist/docs/kt-progress-bar.md

@@ -0,0 +1,66 @@
+# `<kt-progress-bar>`
+
+A determinate progress bar.
+
+```html
+<kt-progress-bar value="64" show-value show-label label="Importing entities"></kt-progress-bar>
+<kt-progress-bar value="90" variant="warning" striped animated></kt-progress-bar>
+<kt-progress-bar value="4" max="7" size="small"></kt-progress-bar>
+```
+
+## The caption
+
+`show-value` puts the percentage in a caption **above** the track, not inside
+it. A label centred over an 8px bar is half on the fill and half off it, so it
+is unreadable at one end of the range whatever colour it is given — and at
+`size="small"` the 4px track clips it outright. Above the bar it reads in every
+theme, at every size, at every value.
+
+`show-label` puts `label` in the same row, on the left. Without it `label` stays
+the accessible name and nothing visible changes, which is right when the copy
+around the bar already says what is progressing.
+
+Reaching `max` switches the fill to the success colour whatever the variant, so
+"done" reads at a glance without the caller swapping anything.
+
+Out-of-range values are clamped and a `max` of zero is treated as 100 — a
+progress bar should never be the thing that puts `NaN%` on screen.
+
+## Stripes
+
+The animated stripe is the one decorative animation in Kanto, and it earns its
+place: it is how an operation says it is still working when the number is not
+moving. It needs both `striped` and `animated`, and it stops under
+`prefers-reduced-motion`.
+
+## Accessibility
+
+`role="progressbar"` with `aria-valuenow`/`aria-valuemax`, plus an
+`aria-valuetext` of `"64 %"` so it is read as a percentage rather than a bare
+number. Give it a `label` saying _what_ is progressing.
+
+## API
+
+| Property    | Attribute    | Type                                                                     | Default     |
+| ----------- | ------------ | ------------------------------------------------------------------------ | ----------- |
+| `value`     | `value`      | `number`                                                                 | `0`         |
+| `max`       | `max`        | `number`                                                                 | `100`       |
+| `size`      | `size`       | `'small' \| 'medium' \| 'large'`                                         | `'medium'`  |
+| `showLabel` | `show-label` | `boolean`                                                                | `false`     |
+| `variant`   | `variant`    | `'primary' \| 'info' \| 'success' \| 'warning' \| 'danger' \| 'neutral'` | `'primary'` |
+| `showValue` | `show-value` | `boolean`                                                                | `false`     |
+| `striped`   | `striped`    | `boolean`                                                                | `false`     |
+| `animated`  | `animated`   | `boolean`                                                                | `false`     |
+| `label`     | `label`      | `string`                                                                 | `''`        |
+
+| Getter    | Returns                 |
+| --------- | ----------------------- |
+| `percent` | Whole percentage, 0–100 |
+
+| Part      | Description             |
+| --------- | ----------------------- |
+| `base`    | The container           |
+| `caption` | The row above the track |
+| `value`   | The percentage          |
+| `track`   | The groove              |
+| `fill`    | The filled portion      |