kanto-ds 1.7.0 → 1.8.0

package/dist/docs/kt-command-palette.md

@@ -0,0 +1,99 @@
+# `<kt-command-palette>`
+
+The palette a product opens on Cmd+K: every action and page, a few keystrokes away.
+
+```html
+<kt-command-palette></kt-command-palette>
+```
+
+```js
+palette.commands = [
+  { id: 'new-invoice', label: 'New invoice', group: 'Create', shortcut: 'mod i' },
+  { id: 'new-customer', label: 'New customer', group: 'Create', keywords: ['client'] },
+  { id: 'settings', label: 'Open settings', group: 'Navigate', icon: 'settings' },
+  { id: 'export', label: 'Export as CSV', group: 'Actions', disabled: true },
+];
+palette.addEventListener('kt-select', (e) => run(e.detail.id));
+```
+
+## Opening it
+
+Cmd+K on a Mac, Ctrl+K elsewhere, opens and closes it from anywhere on the
+page — inside a field too, as people expect. `hotkey` sets another letter;
+`hotkey=""` turns the shortcut off, for a page that opens it from a button of
+its own (`palette.open = true`). Each opening starts from an empty search.
+
+## Finding a command
+
+Typing narrows the list. Every word typed must appear, in any order, in the
+command's label, one of its `keywords` or its `group`, ignoring case and
+accents — "client" finds New customer, "preferences" finds Préférences. What
+remains ranks by how it matched:
+
+1. a label that starts with the search;
+2. a label in which each word starts a word;
+3. a label that holds the search anywhere;
+4. a match on a keyword or the group only.
+
+Commands that tie keep the order you gave them, so the list reads the way you
+wrote it. A disabled command stays listed — its absence would be a mystery —
+and cannot be run.
+
+## Keyboard
+
+| Key          | Does                                                           |
+| ------------ | -------------------------------------------------------------- |
+| `↑` / `↓`    | the previous or next command, skipping disabled ones, wrapping |
+| `Home`/`End` | the first or last command                                      |
+| `Enter`      | runs the active command, and closes                            |
+| `Escape`     | closes, and gives the focus back to where it was               |
+
+A click runs a command too; a click outside the panel closes it.
+
+## Commands
+
+```ts
+interface KtCommand {
+  id: string;
+  label: string;
+  group?: string; // the heading it is listed under
+  icon?: string; // a Lucide name
+  keywords?: string[]; // other words it answers to
+  shortcut?: string; // keys shown beside it, as <kt-kbd keys> takes them
+  disabled?: boolean;
+}
+```
+
+Groups appear in the order their first command does. A shortcut is only shown:
+binding it is the application's work.
+
+## API
+
+| Property      | Attribute     | Type          | Default           |
+| ------------- | ------------- | ------------- | ----------------- |
+| `commands`    | —             | `KtCommand[]` | `[]`              |
+| `open`        | `open`        | `boolean`     | `false`           |
+| `hotkey`      | `hotkey`      | `string`      | `'k'`             |
+| `placeholder` | `placeholder` | `string`      | from `setStrings` |
+
+| Event       | Detail                               |
+| ----------- | ------------------------------------ |
+| `kt-select` | `{ id: string, command: KtCommand }` |
+| `kt-open`   | —                                    |
+| `kt-close`  | —                                    |
+
+| Part     | Description        |
+| -------- | ------------------ |
+| `dialog` | The `<dialog>`     |
+| `input`  | The search field   |
+| `list`   | The scrolling list |
+| `footer` | The keyboard hints |
+
+## Accessibility
+
+Built on the native `<dialog>`: the top layer, focus containment and the inert
+page come from the platform. The field is a `combobox` over a `listbox`; the
+active command is its `aria-activedescendant`, so a screen reader reads each
+command as the arrows reach it, and each group is a `group` named by its
+heading. The focus goes to the field on opening and back to where it was on
+closing.

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

@@ -0,0 +1,77 @@
+# `<kt-number-input>`
+
+A number field with − and + beside it: a quantity, a seat count, an amount.
+
+```html
+<kt-number-input label="Seats" min="1" max="50" value="5"></kt-number-input>
+```
+
+```js
+amount.formatOptions = { style: 'currency', currency: 'EUR' };
+```
+
+## Typing and stepping
+
+Type a number the way your language writes one — `1 234,5` in French,
+`1,234.5` in English — or step it:
+
+| Key            | Does                 |
+| -------------- | -------------------- |
+| `↑` / `↓`      | one step up or down  |
+| `Page Up/Down` | ten steps            |
+| `Home`/`End`   | to `min` or `max`    |
+| `Enter`        | reads what was typed |
+
+The − and + buttons step too, and grey out at the bounds. They stay out of the
+tab order: the arrows already do their work from the field.
+
+What is typed is read when the field is left, or on Enter, and kept within
+`min` and `max` and on `step`. Text that is no number puts back the value the
+field had; an emptied field holds `null`.
+
+## Reading at rest
+
+While the field has the focus it shows the plain number, easy to edit. At rest
+it reads the way the locale writes it, through `formatOptions` — any
+`Intl.NumberFormat` option: a currency, a percentage, a unit, a number of
+decimals. A screen reader hears that text as the value.
+
+## In a form
+
+A form control: it submits the number under `name`, and nothing while empty.
+`required` blocks submission while it is empty, `error` shows a message, and
+`form.reset()` puts back the first value.
+
+## API
+
+| Property        | Attribute     | Type                             | Default            |
+| --------------- | ------------- | -------------------------------- | ------------------ |
+| `value`         | `value`       | `number \| null`                 | `null`             |
+| `min`           | `min`         | `number`                         | none               |
+| `max`           | `max`         | `number`                         | none               |
+| `step`          | `step`        | `number`                         | `1`                |
+| `formatOptions` | —             | `Intl.NumberFormatOptions`       | `{}`               |
+| `locale`        | `locale`      | `string`                         | page, then browser |
+| `name`          | `name`        | `string`                         | `''`               |
+| `label`         | `label`       | `string`                         | `''`               |
+| `placeholder`   | `placeholder` | `string`                         | `''`               |
+| `size`          | `size`        | `'small' \| 'medium' \| 'large'` | `'medium'`         |
+| `disabled`      | `disabled`    | `boolean`                        | `false`            |
+| `required`      | `required`    | `boolean`                        | `false`            |
+| `error`         | `error`       | `string`                         | `''`               |
+
+| Event       | Detail                      |
+| ----------- | --------------------------- |
+| `kt-change` | `{ value: number \| null }` |
+
+| Part       | Description    |
+| ---------- | -------------- |
+| `field`    | The field      |
+| `input`    | The text field |
+| `decrease` | The − button   |
+| `increase` | The + button   |
+
+## Accessibility
+
+The field is a `spinbutton` with its bounds, its value and the text it shows;
+`error` is announced with it.

package/dist/docs/kt-slider.md

@@ -0,0 +1,76 @@
+# `<kt-slider>`
+
+A value picked by sliding along a range: a volume, a threshold, or with `range`, a price between two ends.
+
+```html
+<kt-slider label="Volume" value="40" show-value></kt-slider>
+<kt-slider label="Price" range min="0" max="500" step="10" value="50/300" show-value></kt-slider>
+```
+
+## Native underneath
+
+Each thumb is a native `<input type="range">`, laid over a track Kanto draws.
+The keyboard comes from the platform — arrows and Page Up/Down step, Home and
+End go to the bounds — and so does what a screen reader announces. A `range`
+lays two inputs over one track; each thumb catches its own pointer.
+
+## The value
+
+The value is text, as a form field's is: `"40"`, or with `range`, `"20/80"` —
+low, then high. It is kept within `min` and `max` and on `step`: `value="42"`
+with `step="5"` reads `40`. Without a value, a slider starts at `min`, and a
+range at its two bounds. The two thumbs of a range never cross: the low end
+stops at the high one.
+
+`kt-input` fires while sliding, `kt-change` once the thumb is let go — the one
+to save on.
+
+## Showing the value
+
+`show-value` puts the label and the current value above the slider. `format`
+says how a number reads, there and to a screen reader:
+
+```js
+slider.format = (n) => `$${n.toLocaleString('en-US')}`;
+```
+
+## In a form
+
+A form control: it submits its value under `name` — `"20/80"` for a range —
+and `form.reset()` puts back the first value. A disabled fieldset disables it.
+
+## API
+
+| Property    | Attribute    | Type                    | Default     |
+| ----------- | ------------ | ----------------------- | ----------- |
+| `value`     | `value`      | `string`                | `min`       |
+| `min`       | `min`        | `number`                | `0`         |
+| `max`       | `max`        | `number`                | `100`       |
+| `step`      | `step`       | `number`                | `1`         |
+| `range`     | `range`      | `boolean`               | `false`     |
+| `label`     | `label`      | `string`                | `''`        |
+| `name`      | `name`       | `string`                | `''`        |
+| `showValue` | `show-value` | `boolean`               | `false`     |
+| `format`    | —            | `(n: number) => string` | `String(n)` |
+| `disabled`  | `disabled`   | `boolean`               | `false`     |
+
+| Event       | Detail              |
+| ----------- | ------------------- |
+| `kt-input`  | `{ value: string }` |
+| `kt-change` | `{ value: string }` |
+
+| Part    | Description                        |
+| ------- | ---------------------------------- |
+| `track` | The rail                           |
+| `fill`  | The selected stretch of it         |
+| `value` | The shown value, with `show-value` |
+
+| Property            | Description          | Default |
+| ------------------- | -------------------- | ------- |
+| `--kt-slider-thumb` | The thumb's diameter | `18px`  |
+| `--kt-slider-track` | The rail's thickness | `6px`   |
+
+## Accessibility
+
+Each thumb is a native slider named by `label` — "Price, minimum" and "Price,
+maximum" for a range — announcing its value through `format`.

package/dist/docs/kt-steps.md

@@ -0,0 +1,79 @@
+# `<kt-steps>`
+
+The steps of a flow — sign-up, checkout, onboarding — and where the reader is in it.
+
+```html
+<kt-steps label="Sign-up" current="billing"></kt-steps>
+```
+
+```js
+steps.steps = [
+  { id: 'account', label: 'Account' },
+  { id: 'billing', label: 'Billing', description: 'Card or invoice' },
+  { id: 'team', label: 'Team' },
+  { id: 'done', label: 'Done' },
+];
+```
+
+## States
+
+Steps before `current` are complete and show a tick; `current` is ringed; the
+rest are to come, numbered. A step with `error: true` shows an alert in the
+danger colour wherever it sits — a field it holds failed on submit — so the
+reader knows where to go back to.
+
+Each state is also said in words for a screen reader — "Completed", "Current
+step", "Not started", "Needs attention" — from `setStrings`.
+
+## Going back
+
+With `navigable`, every completed step is a button: picking one sets
+`current` to it and fires `kt-change`. Steps ahead are never buttons: a flow
+moves forward by its own Next button, once what the current step asks for is
+done.
+
+```html
+<kt-steps label="Checkout" current="payment" navigable></kt-steps>
+```
+
+## Orientation
+
+Across by default, the steps sharing the width with a connector between them.
+`orientation="vertical"` stacks them down a rail — for a side column, or for
+steps with long descriptions.
+
+## API
+
+| Property      | Attribute     | Type                         | Default        |
+| ------------- | ------------- | ---------------------------- | -------------- |
+| `steps`       | —             | `KtStep[]`                   | `[]`           |
+| `current`     | `current`     | `string`                     | `''`           |
+| `label`       | `label`       | `string`                     | `''`           |
+| `orientation` | `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` |
+| `navigable`   | `navigable`   | `boolean`                    | `false`        |
+
+```ts
+interface KtStep {
+  id: string;
+  label: string;
+  description?: string;
+  error?: boolean;
+}
+```
+
+| Event       | Detail           |
+| ----------- | ---------------- |
+| `kt-change` | `{ id: string }` |
+
+| Part        | Description                      |
+| ----------- | -------------------------------- |
+| `list`      | The `<ol>`                       |
+| `step`      | A step                           |
+| `marker`    | A step's number, tick or alert   |
+| `connector` | The line from a step to the next |
+
+## Accessibility
+
+An ordered list named by `label`: the number is each step's place.
+`aria-current="step"` marks the current one, and each state is said in words,
+not only shown in colour.

package/dist/index.d.ts

@@ -38,6 +38,8 @@ export type { KtRadioGroupOrientation } from './components/forms/kt-radio-group/
 export { KtSelect } from './components/forms/kt-select/kt-select.js';
 export type { KtSelectSize } from './components/forms/kt-select/kt-select.js';
 export { KtTextarea } from './components/forms/kt-textarea/kt-textarea.js';
+export { KtSlider } from './components/forms/kt-slider/kt-slider.js';
+export { KtNumberInput } from './components/forms/kt-number-input/kt-number-input.js';
 export { KtTimeInput } from './components/forms/kt-time-input/kt-time-input.js';
 export type { KtHourCycle } from './components/forms/kt-time-input/kt-time-input.js';
 export { KtToggle } from './components/forms/kt-toggle/kt-toggle.js';
@@ -49,6 +51,8 @@ export { KtSegmentedControl } from './components/navigation/kt-segmented-control
 export type { KtSegmentedOption, KtSegmentedSize, } from './components/navigation/kt-segmented-control/kt-segmented-control.js';
 export { KtSubMenuNavigation } from './components/navigation/kt-sub-menu-navigation/kt-sub-menu-navigation.js';
 export { KtTabs } from './components/navigation/kt-tabs/kt-tabs.js';
+export { KtSteps } from './components/navigation/kt-steps/kt-steps.js';
+export type { KtStep, KtStepsOrientation } from './components/navigation/kt-steps/kt-steps.js';
 export type { KtTab } from './components/navigation/kt-tabs/kt-tabs.js';
 export { KtHeader } from './components/navigation/kt-header/kt-header.js';
 export type { KtNavItem, KtNavSection, } from './components/navigation/kt-sub-menu-navigation/kt-sub-menu-navigation.js';
@@ -75,6 +79,8 @@ export type { KtConfirmVariant } from './components/overlays/kt-confirm-dialog/k
 export { KtDropdown } from './components/overlays/kt-dropdown/kt-dropdown.js';
 export type { KtDropdownAlign, KtDropdownPlacement, } from './components/overlays/kt-dropdown/kt-dropdown.js';
 export { KtModal } from './components/overlays/kt-modal/kt-modal.js';
+export { KtCommandPalette } from './components/overlays/kt-command-palette/kt-command-palette.js';
+export type { KtCommand } from './components/overlays/kt-command-palette/kt-command-palette.js';
 export type { KtModalSize } from './components/overlays/kt-modal/kt-modal.js';
 export { KtSidePanel } from './components/overlays/kt-side-panel/kt-side-panel.js';
 export { KtChart } from './components/data/kt-chart/kt-chart.js';