kanto-ds 1.7.0 → 1.9.0

package/dist/docs/kt-newsletter.md

@@ -0,0 +1,69 @@
+# `<kt-newsletter>`
+
+A way to hear from you again: a heading, a line, an email field and the
+button that subscribes it.
+
+```html
+<kt-newsletter id="letter" heading="Notes, monthly" lead="What we shipped, and what we learned.">
+  <span slot="note">One email a month. Unsubscribe in one click.</span>
+</kt-newsletter>
+<script>
+  letter.addEventListener('kt-subscribe', (e) => e.detail.wait(api.subscribe(e.detail.email)));
+</script>
+```
+
+## Subscribing
+
+The button, or Enter in the field, checks the address first: one that is not
+an address says so on the field, and nothing is sent. Then `kt-subscribe`
+carries the `email` and `wait(promise)`:
+
+- hand `wait` the request, and the button shows it running;
+- when it resolves, the field gives way to a thanks, announced to screen
+  readers, and `subscribed` is set;
+- when it rejects, its message — or a plain one — shows on the field.
+
+Without a `wait`, it thanks at once. `subscribe()` does what the button does.
+
+## Variants and layout
+
+`panel`, the default, sets it on a tinted panel; `plain` on the page.
+`stacked` puts the field under the words; `inline` beside them, once the block
+is 760px wide. On a narrow screen the button goes under the field.
+
+## Words
+
+```js
+letter.texts = {
+  email: 'Adresse e-mail',
+  placeholder: 'vous@exemple.fr',
+  subscribe: "S'abonner",
+  invalid: 'Saisissez une adresse e-mail, comme nom@exemple.fr.',
+  failed: "Ça n'est pas passé. Réessayez dans un instant.",
+  done: 'C’est fait. Confirmez depuis votre boîte de réception.',
+};
+```
+
+## Accessibility
+
+A section named by its heading, an `<h2>` by default (`heading-level`). The
+field is named — Email address — and asks for an email, so phones show the
+right keyboard and browsers offer the reader's own. An error is said on the
+field; the thanks sits in a status region, read out when it appears.
+
+## API
+
+| Property       | Attribute       | Type                         | Default     |
+| -------------- | --------------- | ---------------------------- | ----------- |
+| `heading`      | `heading`       | `string`                     | `''`        |
+| `lead`         | `lead`          | `string`                     | `''`        |
+| `variant`      | `variant`       | `'panel' \| 'plain'`         | `'panel'`   |
+| `layout`       | `layout`        | `'stacked' \| 'inline'`      | `'stacked'` |
+| `subscribed`   | `subscribed`    | `boolean`                    | `false`     |
+| `align`        | `align`         | `'center' \| 'start'`        | `'center'`  |
+| `headingLevel` | `heading-level` | `number`                     | `2`         |
+| `texts`        | —               | `Partial<KtNewsletterTexts>` | `{}`        |
+
+| Event          | Detail                     |
+| -------------- | -------------------------- |
+| `kt-subscribe` | `{ email, wait(promise) }` |

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-otp-input.md

@@ -0,0 +1,68 @@
+# `<kt-otp-input>`
+
+A one-time code — the six digits of a sign-in, a verification, a second factor —
+one box per character.
+
+```html
+<form>
+  <kt-otp-input label="Verification code" name="code" required></kt-otp-input>
+</form>
+
+<script>
+  document.querySelector('kt-otp-input').addEventListener('kt-complete', (event) => {
+    verify(event.detail.value);
+  });
+</script>
+```
+
+## Typing
+
+Typing moves to the next box. Backspace clears a box, and from an empty one
+steps back and clears the one before. The arrows, Home and End move between
+boxes. A pasted code — with spaces or dashes, as codes are often written — is
+cleaned and spread over the boxes from the one it was pasted into.
+
+The first box asks the browser for `autocomplete="one-time-code"`, so a code
+that arrived by text message fills itself in on a phone. `kt-change` fires as
+the code changes, `kt-complete` once it is whole.
+
+`length` sets how many characters the code has (6 by default). `type="numeric"`,
+the default, takes digits and opens the number pad; `type="alphanumeric"` takes
+letters and digits, shown in capitals.
+
+## Forms
+
+A form control: submitted under `name`, `required` until the code is whole
+("Enter the whole code."), reset to its first `value` with the form, disabled
+with a disabled fieldset. `error` shows a message under the boxes, announced
+with each of them.
+
+## Accessibility
+
+A group named by `label`, each box named by its place — "Character 2 of 6" — so
+a screen reader says where the person is in the code. Translate both strings
+through `setStrings` as `otpCharacter` and `otpRequired`.
+
+## API
+
+| Property   | Attribute  | Type                          | Default     |
+| ---------- | ---------- | ----------------------------- | ----------- |
+| `value`    | `value`    | `string`                      | `''`        |
+| `length`   | `length`   | `number`                      | `6`         |
+| `type`     | `type`     | `'numeric' \| 'alphanumeric'` | `'numeric'` |
+| `label`    | `label`    | `string`                      | `''`        |
+| `name`     | `name`     | `string`                      | `''`        |
+| `required` | `required` | `boolean`                     | `false`     |
+| `disabled` | `disabled` | `boolean`                     | `false`     |
+| `error`    | `error`    | `string`                      | `''`        |
+
+| Event         | Detail              |
+| ------------- | ------------------- |
+| `kt-change`   | `{ value: string }` |
+| `kt-complete` | `{ value: string }` |
+
+| Part    | Description       |
+| ------- | ----------------- |
+| `group` | The boxes         |
+| `box`   | One box           |
+| `error` | The error message |

package/dist/docs/kt-post-grid.md

@@ -0,0 +1,66 @@
+# `<kt-post-grid>`
+
+The latest posts, each a card that leads to it: a cover, a title, a line, and
+who wrote it when.
+
+```html
+<kt-post-grid id="latest" heading="From the blog">
+  <a slot="more" href="/blog">Every post</a>
+</kt-post-grid>
+<script>
+  latest.posts = [
+    {
+      title: 'Closing the month in a day',
+      href: '/blog/close',
+      excerpt: 'What changed when the bank feed matched itself.',
+      date: '2026-09-14',
+      image: '/covers/close.jpg',
+      author: { name: 'Ada Park', avatar: '/ada.jpg' },
+      tags: ['Finance'],
+    },
+  ];
+</script>
+```
+
+## Posts
+
+| Field      | What it is                                                  |
+| ---------- | ----------------------------------------------------------- |
+| `title`    | The post's title, a link to it — the whole card answers it. |
+| `href`     | Where the post is.                                          |
+| `excerpt`  | Optional: a line on what it says.                           |
+| `date`     | Optional: when it was published, `2026-09-14`.              |
+| `image`    | Optional: a cover, cropped to 16:9.                         |
+| `imageAlt` | Optional: the cover's text alternative; empty by default.   |
+| `author`   | Optional: `{ name, avatar }`.                               |
+| `tags`     | Optional: a few words over the title.                       |
+
+Dates are written for people — Sep 14, 2026 — in `locale`, the page's
+language when it is empty, and kept for machines in a `<time datetime>`.
+
+## Layout
+
+`grid`, the default, sets the posts in `columns` — 3 or 2 — where there is
+room: two at most under 760px, one under 520px. `list` puts one under
+another, the cover beside the words once the block is 640px wide. The
+`more` slot sits under the posts: a link to every one.
+
+## Accessibility
+
+A section named by its heading, an `<h2>` by default (`heading-level`). The
+posts are a list of `<article>`s; each title is a link one level under the
+heading. A cover is decoration unless given `imageAlt` — the title already
+says what the post is.
+
+## API
+
+| Property       | Attribute       | Type                  | Default    |
+| -------------- | --------------- | --------------------- | ---------- |
+| `heading`      | `heading`       | `string`              | `''`       |
+| `lead`         | `lead`          | `string`              | `''`       |
+| `posts`        | —               | `KtPost[]`            | `[]`       |
+| `columns`      | `columns`       | `2 \| 3`              | `3`        |
+| `layout`       | `layout`        | `'grid' \| 'list'`    | `'grid'`   |
+| `locale`       | `locale`        | `string`              | `''`       |
+| `align`        | `align`         | `'center' \| 'start'` | `'center'` |
+| `headingLevel` | `heading-level` | `number`              | `2`        |

package/dist/docs/kt-pricing-table.md

@@ -0,0 +1,101 @@
+# `<kt-pricing-table>`
+
+The plans, side by side: what each costs, what it includes, and the way in —
+with a switch between monthly and yearly prices when the plans have both.
+
+```html
+<kt-pricing-table id="pricing" heading="Pricing" currency="EUR" yearly-note="Two months free">
+  <a slot="note" href="/compare">Compare every feature</a>
+</kt-pricing-table>
+<script>
+  pricing.plans = [
+    {
+      id: 'starter',
+      name: 'Starter',
+      price: { monthly: 0, yearly: 0 },
+      features: ['10 invoices a month'],
+    },
+    {
+      id: 'team',
+      name: 'Team',
+      description: 'For a team that bills.',
+      price: { monthly: 29, yearly: 290 },
+      features: ['Unlimited invoices', 'Bank reconciliation'],
+      featured: true,
+      action: 'Start a trial',
+    },
+    {
+      id: 'scale',
+      name: 'Scale',
+      price: 'Custom',
+      features: ['SSO'],
+      href: '/sales',
+      action: 'Talk to sales',
+    },
+  ];
+  pricing.addEventListener('kt-plan', (e) => checkout(e.detail.id, e.detail.billing));
+</script>
+```
+
+## Plans
+
+| Field         | What it is                                                                         |
+| ------------- | ---------------------------------------------------------------------------------- |
+| `id`          | What `kt-plan` carries.                                                            |
+| `name`        | The plan's name, a heading.                                                        |
+| `description` | Optional: who it is for.                                                           |
+| `price`       | A number, formatted in `currency`; a string, as written; or `{ monthly, yearly }`. |
+| `features`    | What it includes, a line each, ticked.                                             |
+| `action`      | The button's words. Get started by default.                                        |
+| `href`        | Makes the button a link; without it, the button fires `kt-plan`.                   |
+| `featured`    | The plan to pick: outlined and badged.                                             |
+
+## Billing
+
+When a plan has a price per period, a switch shows over the plans, monthly
+first. `billing` sets the period shown; changing it fires `kt-billing`. A
+yearly price is the year's — `290` reads $290/year. `yearly-note` sits beside
+the switch: what paying yearly saves.
+
+Prices follow `locale`, the page's language when it is empty.
+
+## Words
+
+Every word is in `texts`, English until given others:
+
+```js
+pricing.texts = {
+  monthly: 'Mensuel',
+  yearly: 'Annuel',
+  perMonth: '/mois',
+  perYear: '/an',
+  featured: 'Le plus choisi',
+  action: 'Commencer',
+};
+```
+
+## Accessibility
+
+A section named by its heading, an `<h2>` by default (`heading-level`); the
+plans are a list, each name one level under. The switch is a radio group,
+one tab stop, moved with the arrows.
+
+## API
+
+| Property       | Attribute       | Type                           | Default     |
+| -------------- | --------------- | ------------------------------ | ----------- |
+| `heading`      | `heading`       | `string`                       | `''`        |
+| `lead`         | `lead`          | `string`                       | `''`        |
+| `plans`        | —               | `KtPlan[]`                     | `[]`        |
+| `billing`      | `billing`       | `'monthly' \| 'yearly'`        | `'monthly'` |
+| `currency`     | `currency`      | `string`                       | `'USD'`     |
+| `locale`       | `locale`        | `string`                       | `''`        |
+| `yearlyNote`   | `yearly-note`   | `string`                       | `''`        |
+| `align`        | `align`         | `'center' \| 'start'`          | `'center'`  |
+| `headingLevel` | `heading-level` | `number`                       | `2`         |
+| `texts`        | —               | `Partial<KtPricingTableTexts>` | `{}`        |
+
+| Event        | Detail            |
+| ------------ | ----------------- |
+| `kt-billing` | `{ billing }`     |
+| `kt-plan`    | `{ id, billing }` |

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

@@ -0,0 +1,86 @@
+# `<kt-prompt-input>`
+
+The field a person writes to an assistant in: it grows with what is written,
+sends on Enter, and shows the sending on its own send button.
+
+```html
+<kt-prompt-input placeholder="Ask Northwind anything"></kt-prompt-input>
+
+<script>
+  const prompt = document.querySelector('kt-prompt-input');
+  prompt.addEventListener('kt-submit', (event) => {
+    event.detail.wait(api.ask(event.detail.value));
+  });
+</script>
+```
+
+## Sending
+
+Enter sends; Shift+Enter starts a new line. With `submit-on="mod-enter"`,
+Enter starts a new line and Cmd or Ctrl+Enter sends — for long messages,
+where a stray Enter should not send half a thought. An input method composing
+a character keeps Enter for itself.
+
+`kt-submit` carries the text and `wait(promise)`. Hand it the request:
+
+- the send button runs it — its plane turns into the spinner, then flies off;
+- the field holds the text, read-only, until the request settles;
+- on success the field empties; on failure the text stays, to send again.
+
+Without `wait`, the field empties as soon as it sends. `submit()` sends from
+script, as Enter would. Nothing is sent while the text is blank — the send
+button says so by being disabled — nor while `disabled`.
+
+## Growing
+
+The field starts one line tall and grows with each line, up to `max-rows`
+(8 by default); past that it scrolls.
+
+## Slots
+
+| Slot          | Where                                                                         |
+| ------------- | ----------------------------------------------------------------------------- |
+| `attachments` | Above the text: files or context added to the message. Collapses while empty. |
+| `actions`     | Beside the send button: attach, a model picker, a mode.                       |
+
+```html
+<kt-prompt-input>
+  <kt-badge slot="attachments" icon="file" removable>q3-report.pdf</kt-badge>
+  <kt-button
+    slot="actions"
+    size="small"
+    variant="secondary-no-bg"
+    icon="paperclip"
+    label="Attach a file"
+  ></kt-button>
+</kt-prompt-input>
+```
+
+## Accessibility
+
+A `<textarea>` named by `label` — "Message" by default — and a send button
+named "Send", both translated through `setStrings`. The button is a real
+button, reached by Tab after the field. While a message is sending, the field
+is read-only rather than disabled, so the focus stays where the person left it.
+
+## API
+
+| Property      | Attribute     | Type                     | Default   |
+| ------------- | ------------- | ------------------------ | --------- |
+| `value`       | `value`       | `string`                 | `''`      |
+| `placeholder` | `placeholder` | `string`                 | `''`      |
+| `label`       | `label`       | `string`                 | `''`      |
+| `disabled`    | `disabled`    | `boolean`                | `false`   |
+| `maxRows`     | `max-rows`    | `number`                 | `8`       |
+| `submitOn`    | `submit-on`   | `'enter' \| 'mod-enter'` | `'enter'` |
+
+| Event       | Detail                             |
+| ----------- | ---------------------------------- |
+| `kt-input`  | `{ value: string }`                |
+| `kt-submit` | `{ value: string, wait(promise) }` |
+
+| Part       | Description             |
+| ---------- | ----------------------- |
+| `base`     | The field               |
+| `textarea` | The native `<textarea>` |
+| `send`     | The send button         |

package/dist/docs/kt-settings-section.md

@@ -0,0 +1,65 @@
+# `<kt-settings-section>`
+
+One part of a settings page: what it is about, the fields that change it, and
+the button that saves them.
+
+```html
+<kt-settings-section heading="Profile" description="How others see you in the workspace.">
+  <kt-label-input label="Name"><kt-input value="Ada Park"></kt-input></kt-label-input>
+  <kt-label-input label="Email"
+    ><kt-input type="email" value="ada@northwind.com"></kt-input
+  ></kt-label-input>
+  <span slot="note">Saved 2 minutes ago</span>
+  <kt-button slot="actions">Save</kt-button>
+</kt-settings-section>
+
+<kt-settings-section
+  danger
+  heading="Delete workspace"
+  description="Everything in it goes, for good."
+>
+  <kt-button slot="actions" variant="delete">Delete workspace</kt-button>
+</kt-settings-section>
+```
+
+A settings page is several of these, one under another.
+
+## Layout
+
+`split`, the default, sets the heading and its description beside the fields
+once the section is 760px wide — a third for the words, two thirds for the
+card — and over them below. `stacked` always puts them over the fields.
+
+## Slots
+
+| Slot      | What goes in it                                      |
+| --------- | ---------------------------------------------------- |
+| (default) | The fields, spaced as a form.                        |
+| `actions` | In the card's footer, at the end: Save, Cancel.      |
+| `note`    | In the footer, at the start: when it was last saved. |
+
+The footer shows only when it has actions or a note; a card with only actions
+— a danger zone — is just its footer.
+
+## Danger
+
+`danger` turns the heading and the card's border red: the section that
+deletes the workspace or the account. Pair it with a `delete` button and a
+`kt-confirm-dialog`.
+
+## Accessibility
+
+A section named by its heading — an `<h2>` by default, `heading-level`
+changes it — and described by its description. The section does not make a
+form: wrap the page's sections in a `<form>` or a `<kt-form>`, or each one,
+to save them together or apart.
+
+## API
+
+| Property       | Attribute       | Type                   | Default   |
+| -------------- | --------------- | ---------------------- | --------- |
+| `heading`      | `heading`       | `string`               | `''`      |
+| `description`  | `description`   | `string`               | `''`      |
+| `layout`       | `layout`        | `'split' \| 'stacked'` | `'split'` |
+| `danger`       | `danger`        | `boolean`              | `false`   |
+| `headingLevel` | `heading-level` | `number`               | `2`       |

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`.