kanto-ds 1.7.0 → 1.9.0

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

@@ -0,0 +1,50 @@
+# `<kt-copy-button>`
+
+Copies a value to the clipboard and says it did: an API key, an install
+command, a share link.
+
+```html
+<kt-copy-button value="npm install kanto-ds"></kt-copy-button>
+<kt-copy-button value="sk_live_51H8…" icon-only label="Copy the API key"></kt-copy-button>
+```
+
+## Copying
+
+A click — or `copy()` from script — writes `value` to the clipboard. It is
+built on `kt-button`'s `run()`:
+
+- on success the tick comes in and the label reads "Copied" for two seconds,
+  announced to a screen reader; `kt-copy` fires with the value;
+- if the browser refuses the clipboard — no permission, an insecure origin —
+  the button shakes, `copy()` rejects, and nothing is said to have been copied.
+
+## Options
+
+`icon-only` draws the icon alone, named by `label`. `label` and `copied-label`
+replace the translated "Copy" and "Copied" — "Copy the key", "Key copied".
+`variant` and `size` are the button's own, `secondary` and `medium` by default.
+
+## Accessibility
+
+A real button, named by its words or, icon-only, by `label`. The confirmation
+is announced through the button's status, so a person who cannot see the tick
+still hears that it worked.
+
+## API
+
+| Property      | Attribute      | Type                             | Default       |
+| ------------- | -------------- | -------------------------------- | ------------- |
+| `value`       | `value`        | `string`                         | `''`          |
+| `label`       | `label`        | `string`                         | `''`          |
+| `copiedLabel` | `copied-label` | `string`                         | `''`          |
+| `iconOnly`    | `icon-only`    | `boolean`                        | `false`       |
+| `variant`     | `variant`      | `KtButtonVariant`                | `'secondary'` |
+| `size`        | `size`         | `'small' \| 'medium' \| 'large'` | `'medium'`    |
+
+| Method   | Description                                               |
+| -------- | --------------------------------------------------------- |
+| `copy()` | Copies `value`; resolves once copied, rejects if refused. |
+
+| Event     | Detail              |
+| --------- | ------------------- |
+| `kt-copy` | `{ value: string }` |

package/dist/docs/kt-cta.md

@@ -0,0 +1,45 @@
+# `<kt-cta>`
+
+The ask at the end of a page: a heading, a line, and the button that acts on
+them.
+
+```html
+<kt-cta heading="Start sending invoices" lead="Your first invoice goes out in two minutes.">
+  <kt-button slot="actions" size="large">Start free</kt-button>
+  <kt-button slot="actions" size="large" variant="secondary">Talk to sales</kt-button>
+  <span slot="note">Free for three months. No card needed.</span>
+</kt-cta>
+```
+
+## Variants and layout
+
+| `variant` | What it does                                          |
+| --------- | ----------------------------------------------------- |
+| `panel`   | The default: on a tinted panel, the page's last word. |
+| `plain`   | On the page, for a call to action between sections.   |
+
+`stacked`, the default layout, puts the actions under the words; `inline`
+sets them at the end, beside the words, once the block is 720px wide — under
+them below. `align` centres the words, the default, or keeps them at the
+`start`. An empty slot takes no room.
+
+## Accessibility
+
+A section named by its heading, an `<h2>` by default (`heading-level`). Say
+what the button does — Start free, not Click here.
+
+## API
+
+| Property       | Attribute       | Type                    | Default     |
+| -------------- | --------------- | ----------------------- | ----------- |
+| `heading`      | `heading`       | `string`                | `''`        |
+| `lead`         | `lead`          | `string`                | `''`        |
+| `variant`      | `variant`       | `'panel' \| 'plain'`    | `'panel'`   |
+| `layout`       | `layout`        | `'stacked' \| 'inline'` | `'stacked'` |
+| `align`        | `align`         | `'center' \| 'start'`   | `'center'`  |
+| `headingLevel` | `heading-level` | `number`                | `2`         |
+
+| Slot      | What goes in it                           |
+| --------- | ----------------------------------------- |
+| `actions` | The buttons.                              |
+| `note`    | Under them: what it costs, what it needs. |

package/dist/docs/kt-description-list.md

@@ -0,0 +1,58 @@
+# `<kt-description-list>`
+
+Terms and their details — an invoice's number, customer and amount; a person's
+email and role — the body of a detail page.
+
+```html
+<kt-description-list label="Invoice" bordered></kt-description-list>
+
+<script>
+  document.querySelector('kt-description-list').items = [
+    { term: 'Invoice', detail: 'INV-2041' },
+    { term: 'Customer', detail: 'Acme Corp' },
+    { term: 'Amount', detail: '$1,200' },
+    { term: 'Purchase order', detail: '' },
+  ];
+</script>
+```
+
+## Items
+
+`items` is a list of `{ term, detail }`, drawn as a real `<dl>`: each term and
+its detail grouped in a `<div>`, as the HTML specification allows. An empty
+detail shows a dash, so a missing value reads as missing rather than as a gap
+someone forgot to fill.
+
+## Layout
+
+| `layout`     | What it is                                                                                |
+| ------------ | ----------------------------------------------------------------------------------------- |
+| `horizontal` | The default: each term beside its detail, in a column `--kt-description-term-width` wide. |
+| `stacked`    | Each term over its detail; `columns` (1–4) sets them side by side.                        |
+
+Both follow the list's **own width**: below 480px a horizontal list stacks and
+a stacked one drops to a single column, in a narrow panel as on a phone.
+`bordered` draws a rule under each item.
+
+## Accessibility
+
+A description list is announced as such, with the number of its items; name it
+with `label` when the page has more than one. Terms are muted and details full
+strength, so the eye reads the values while a screen reader reads both.
+
+## API
+
+| Property   | Attribute  | Type                        | Default        |
+| ---------- | ---------- | --------------------------- | -------------- |
+| `items`    | —          | `KtDescriptionItem[]`       | `[]`           |
+| `layout`   | `layout`   | `'horizontal' \| 'stacked'` | `'horizontal'` |
+| `columns`  | `columns`  | `number` (1–4)              | `1`            |
+| `bordered` | `bordered` | `boolean`                   | `false`        |
+| `label`    | `label`    | `string`                    | `''`           |
+
+| Part     | Description             |
+| -------- | ----------------------- |
+| `list`   | The `<dl>`              |
+| `item`   | One term and its detail |
+| `term`   | The `<dt>`              |
+| `detail` | The `<dd>`              |

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

@@ -0,0 +1,92 @@
+# `<kt-empty-page>`
+
+The page a new account lands on, before there is anything in it: a welcome,
+and the first steps that fill it — what is done, what is next, and the way to
+each.
+
+```html
+<kt-empty-page id="welcome" heading="Welcome, Ada" lead="Three steps and you are sending invoices.">
+  <a slot="actions" href="/app">Skip for now</a>
+</kt-empty-page>
+<script>
+  welcome.steps = [
+    {
+      id: 'company',
+      title: 'Add your company',
+      description: 'Name, address and logo.',
+      done: true,
+    },
+    {
+      id: 'customer',
+      title: 'Add a customer',
+      description: 'Who you bill.',
+      action: 'Add customer',
+    },
+    {
+      id: 'invoice',
+      title: 'Send your first invoice',
+      action: 'New invoice',
+      href: '/invoices/new',
+    },
+  ];
+  welcome.addEventListener('kt-step', (e) => open(e.detail.id));
+</script>
+```
+
+For a list or a panel with nothing in it, `kt-empty-state`; this is the whole
+page, the first time.
+
+## Steps
+
+| Field         | What it is                                                      |
+| ------------- | --------------------------------------------------------------- |
+| `id`          | What `kt-step` carries.                                         |
+| `title`       | The step, said as something to do.                              |
+| `description` | Optional: what it needs, or why.                                |
+| `action`      | Optional: the button's words. Start by default.                 |
+| `href`        | Optional: makes the action a link; without it, `kt-step` fires. |
+| `done`        | The step is taken: ticked, struck through, no action.           |
+
+The steps are numbered in order, with how far along it is over them — 1 of 3
+done. The first step not done is the next one: its action is the primary
+button, the others are secondary. On a narrow screen the action goes under its
+step's words.
+
+## Slots
+
+| Slot      | What goes in it                            |
+| --------- | ------------------------------------------ |
+| `media`   | Over the heading: an illustration, a logo. |
+| `actions` | Under the steps: Skip for now, the docs.   |
+
+## Words
+
+```js
+welcome.texts = {
+  progress: (done, total) => `${done} sur ${total} faits`,
+  done: 'Fait :',
+  start: 'Commencer',
+};
+```
+
+## Accessibility
+
+A section named by its heading — an `<h1>`, since it is the page;
+`heading-level` changes it. The steps are an ordered list, each title one
+level under. A done step's title is read with "Done:" before it, since the
+tick and the line through are only seen. The progress bar is named with the
+same words it shows.
+
+## API
+
+| Property       | Attribute       | Type                        | Default |
+| -------------- | --------------- | --------------------------- | ------- |
+| `heading`      | `heading`       | `string`                    | `''`    |
+| `lead`         | `lead`          | `string`                    | `''`    |
+| `steps`        | —               | `KtFirstStep[]`             | `[]`    |
+| `headingLevel` | `heading-level` | `number`                    | `1`     |
+| `texts`        | —               | `Partial<KtEmptyPageTexts>` | `{}`    |
+
+| Event     | Detail   |
+| --------- | -------- |
+| `kt-step` | `{ id }` |

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

@@ -0,0 +1,64 @@
+# `<kt-error-page>`
+
+The page a person lands on when the one they wanted is not there: not found,
+broken, or down for maintenance — said plainly, with the way on.
+
+```html
+<kt-error-page fill home-href="/app"></kt-error-page>
+<kt-error-page kind="error">
+  <span>Request id: 7f3a9c</span>
+</kt-error-page>
+<kt-error-page kind="maintenance"></kt-error-page>
+```
+
+## Kinds
+
+| `kind`        | Code | Says                 | Offers                  |
+| ------------- | ---- | -------------------- | ----------------------- |
+| `not-found`   | 404  | Page not found       | Go home                 |
+| `error`       | 500  | Something went wrong | Try again, then Go home |
+| `maintenance` | 503  | Back in a moment     | Nothing it cannot do    |
+
+`code` shows another code — 410, 403. `home-href` is where Go home leads, `/`
+by default. Try again fires `kt-retry`; cancel it to retry your own way —
+refetch the data, re-render the route — otherwise the page reloads.
+
+The `actions` slot replaces the buttons — a search field, a link to the status
+page — and the default slot goes under them, for a contact line or a request
+id to quote to support.
+
+## Layout and words
+
+`fill` makes it take its container's height and centre itself in it, as a page
+on its own. Every word is in `texts`, English until given others;
+`heading-level` sets the heading's level, 1 by default.
+
+```js
+page.texts = { notFoundHeading: 'Page introuvable', goHome: "Retour à l'accueil" };
+```
+
+## Accessibility
+
+The heading says what happened; the large code is decoration to a screen
+reader, which hears the heading instead. Go home is a link, since it goes
+somewhere; Try again is a button, since it does something.
+
+## API
+
+| Property       | Attribute       | Type                        | Default       |
+| -------------- | --------------- | --------------------------- | ------------- |
+| `kind`         | `kind`          | `KtErrorPageKind`           | `'not-found'` |
+| `code`         | `code`          | `string`                    | `''`          |
+| `homeHref`     | `home-href`     | `string`                    | `'/'`         |
+| `headingLevel` | `heading-level` | `number`                    | `1`           |
+| `fill`         | `fill`          | `boolean`                   | `false`       |
+| `texts`        | —               | `Partial<KtErrorPageTexts>` | `{}`          |
+
+| Event      | Detail                                       |
+| ---------- | -------------------------------------------- |
+| `kt-retry` | — Cancelable; uncancelled, the page reloads. |
+
+| Slot      | Where                             |
+| --------- | --------------------------------- |
+| `actions` | Replaces the buttons              |
+| _default_ | Under them: contact, a request id |

package/dist/docs/kt-faq.md

@@ -0,0 +1,54 @@
+# `<kt-faq>`
+
+The questions people ask before they sign up, answered: an accordion under a
+heading, one answer open at a time.
+
+```html
+<kt-faq id="faq" heading="Questions" layout="split">
+  <span slot="note">Something else? <a href="/contact">Ask us</a>.</span>
+</kt-faq>
+<script>
+  faq.items = [
+    {
+      question: 'Can I cancel any time?',
+      answer: 'Yes, from Settings. You keep every invoice you sent.',
+    },
+    { question: 'Do you take card payments?', answer: 'Cards, bank transfers and direct debits.' },
+  ];
+</script>
+```
+
+## Questions
+
+Each item is a `question` and its `answer`, drawn as a
+`kt-collapsible` in a `kt-accordion`: opening one
+folds the one that was open. `multiple` lets each open on its own;
+`open-first` opens the first.
+
+## Layout
+
+`stacked`, the default, puts the head over the questions; `split` sets it at
+the start, beside them, once the block is 880px wide — and holds it there
+while the questions scroll (`--kt-faq-sticky-top`, 24px, clears a sticky
+header). The `note` slot sits under the head: where to ask what is not
+answered.
+
+## Accessibility
+
+A section named by its heading, an `<h2>` by default (`heading-level`). Each
+question is a `<details>` summary — a real control, announced as expanded or
+collapsed — and the arrows move between them. Find-in-page opens the answer
+that holds a match.
+
+## API
+
+| Property       | Attribute       | Type                   | Default     |
+| -------------- | --------------- | ---------------------- | ----------- |
+| `heading`      | `heading`       | `string`               | `''`        |
+| `lead`         | `lead`          | `string`               | `''`        |
+| `items`        | —               | `KtFaqItem[]`          | `[]`        |
+| `multiple`     | `multiple`      | `boolean`              | `false`     |
+| `openFirst`    | `open-first`    | `boolean`              | `false`     |
+| `layout`       | `layout`        | `'stacked' \| 'split'` | `'stacked'` |
+| `align`        | `align`         | `'center' \| 'start'`  | `'center'`  |
+| `headingLevel` | `heading-level` | `number`               | `2`         |

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

@@ -0,0 +1,53 @@
+# `<kt-feature-grid>`
+
+What the product does, a feature at a time: an icon, a title and a line, in a
+grid.
+
+```html
+<kt-feature-grid
+  id="why"
+  heading="Why teams switch"
+  lead="Less chasing, more paid."
+></kt-feature-grid>
+<script>
+  why.features = [
+    { icon: 'send', title: 'Sent in a second', description: 'From the quote, in one click.' },
+    { icon: 'refresh-cw', title: 'Chased for you', description: 'Polite reminders, on schedule.' },
+    { icon: 'check', title: 'Reconciled', description: 'Matched to the bank.', href: '/bank' },
+  ];
+</script>
+```
+
+## Features
+
+| Field         | What it is                                                       |
+| ------------- | ---------------------------------------------------------------- |
+| `title`       | The feature's name.                                              |
+| `description` | A line on what it does for the reader.                           |
+| `icon`        | Optional: an icon's name, in a tinted square.                    |
+| `href`        | Optional: makes the title a link — the whole feature answers it. |
+
+## Layout
+
+`columns` sets how many features per row — 2, 3 (the default) or 4 — where
+there is room: under 760px the grid has two columns at most, under 480px one.
+It follows the grid's own width. `variant="card"` puts each feature on a
+card.
+
+## Accessibility
+
+A section named by its heading, an `<h2>` by default (`heading-level`). The
+features are a list; each title sits one level under the heading. Icons are
+decoration and hidden from assistive tech.
+
+## API
+
+| Property       | Attribute       | Type                  | Default    |
+| -------------- | --------------- | --------------------- | ---------- |
+| `heading`      | `heading`       | `string`              | `''`       |
+| `lead`         | `lead`          | `string`              | `''`       |
+| `features`     | —               | `KtFeature[]`         | `[]`       |
+| `columns`      | `columns`       | `2 \| 3 \| 4`         | `3`        |
+| `variant`      | `variant`       | `'plain' \| 'card'`   | `'plain'`  |
+| `align`        | `align`         | `'center' \| 'start'` | `'center'` |
+| `headingLevel` | `heading-level` | `number`              | `2`        |

package/dist/docs/kt-footer.md

@@ -0,0 +1,115 @@
+# `<kt-footer>`
+
+The site footer: a contentinfo landmark holding the brand and a word about the
+product, columns of links, actions, and a legal line under them.
+
+```html
+<kt-footer label="Site">
+  <a slot="brand" href="/">ACME</a>
+  Invoicing for small teams.
+  <kt-button slot="actions" size="small" variant="secondary" icon="mail">Contact us</kt-button>
+  <span slot="legal">© 2026 Acme. All rights reserved.</span>
+</kt-footer>
+
+<script>
+  document.querySelector('kt-footer').columns = [
+    {
+      heading: 'Product',
+      links: [
+        { label: 'Features', href: '/features' },
+        { label: 'Pricing', href: '/pricing' },
+      ],
+    },
+    {
+      heading: 'Company',
+      links: [
+        { label: 'About', href: '/about' },
+        { label: 'GitHub', href: 'https://github.com/acme', external: true },
+      ],
+    },
+  ];
+</script>
+```
+
+## Columns
+
+The links are data, set as a property: `columns` is a list of
+`{ heading, links }`, and each link is `{ label, href, external? }`. Every
+column is laid out, named and marked the same way, so a footer cannot drift
+into a mix of styles.
+
+An `external` link — one that leaves the site — gets the external-link icon,
+hidden from screen readers, and `rel="noopener"`. It opens where the reader
+is, as every other link does.
+
+The headings are `<h2>` by default, since a footer sits under the page's `h1`.
+Set `heading-level` to 3–6 when the footer sits deeper in the outline.
+
+## Variants
+
+| `variant` | What it is                                                         |
+| --------- | ------------------------------------------------------------------ |
+| `columns` | The default: the brand on one side, a column per heading opposite. |
+| `simple`  | One row: the brand, then every link run together. No headings.     |
+
+`simple` is for a page that needs a footer rather than a site map: an app's
+settings, a sign-in screen, a single-page product.
+
+## Slots
+
+| Slot      | Where                                                                         |
+| --------- | ----------------------------------------------------------------------------- |
+| `brand`   | Logo or wordmark.                                                             |
+| _default_ | A word under the brand: what the product is. Hidden in `simple`.              |
+| `actions` | Under it: social links, a newsletter form, a contact button.                  |
+| `legal`   | The bottom line — copyright, terms, privacy. Its row is left out while empty. |
+
+## Layout
+
+The footer lays itself out from **its own width**, not the viewport's: side by
+side once it is 720px wide, stacked below that — in a narrow panel as on a
+phone. `--kt-footer-max-width` keeps the content to a column on a wide page
+while the background and the rule run edge to edge.
+
+```css
+kt-footer {
+  --kt-footer-max-width: 1200px;
+}
+```
+
+Set `--kt-footer-padding-inline: 0` to line the footer up with the content of
+a page that already has its own margins.
+
+`bordered`, on by default, draws a rule along the top; turn it off where the
+footer sits on a surface of its own.
+
+## Accessibility
+
+A `<footer role="contentinfo">`, named by `label` when the page has more than
+one. Put it outside `<main>` — beside it, at the end of the page — since a
+contentinfo landmark must not sit inside another. The columns are one `<nav>`
+with the same name, a heading over each list. Links keep the theme's focus ring
+and read 4.5:1 in both themes.
+
+## API
+
+| Property       | Attribute       | Type                    | Default     |
+| -------------- | --------------- | ----------------------- | ----------- |
+| `columns`      | —               | `KtFooterColumn[]`      | `[]`        |
+| `variant`      | `variant`       | `'columns' \| 'simple'` | `'columns'` |
+| `bordered`     | `bordered`      | `boolean`               | `true`      |
+| `headingLevel` | `heading-level` | `number` (2–6)          | `2`         |
+| `label`        | `label`         | `string`                | `''`        |
+
+| Part      | Description                         |
+| --------- | ----------------------------------- |
+| `base`    | The `<footer>`                      |
+| `brand`   | The brand, its text and the actions |
+| `columns` | The navigation holding the columns  |
+| `column`  | One column                          |
+| `bottom`  | The legal row                       |
+
+| CSS property                 | Default               |
+| ---------------------------- | --------------------- |
+| `--kt-footer-max-width`      | `none`                |
+| `--kt-footer-padding-inline` | `var(--padding-card)` |

package/dist/docs/kt-hero.md

@@ -0,0 +1,53 @@
+# `<kt-hero>`
+
+The top of a page: what the product is, in a heading and a line, and the way
+in.
+
+```html
+<kt-hero heading="Invoices that pay themselves" lead="Send, chase and reconcile, in one place.">
+  <a slot="announcement" href="/changelog">New: recurring invoices</a>
+  <kt-button slot="actions" size="large">Start free</kt-button>
+  <kt-button slot="actions" size="large" variant="secondary">Book a demo</kt-button>
+  <span slot="note">Free for three months. No card needed.</span>
+  <img slot="media" src="/screenshot.png" alt="The invoices screen" />
+</kt-hero>
+```
+
+## Layout
+
+| `layout`  | What it does                                                              |
+| --------- | ------------------------------------------------------------------------- |
+| `stacked` | The default: the media under the words — a screenshot, a live demo.       |
+| `split`   | The media beside the words once the hero is 880px wide; under them below. |
+
+`align` centres the words — the default — or keeps them at the `start`. The
+layout follows the hero's own width, so it holds in a preview as on a page.
+An empty slot takes no room.
+
+## Slots
+
+| Slot           | Where                                                 |
+| -------------- | ----------------------------------------------------- |
+| `announcement` | Above the heading: what is new, as a link or a badge. |
+| `actions`      | Under the lead: the buttons.                          |
+| `note`         | Under the actions: what it costs, what it needs.      |
+| `media`        | A screenshot, an illustration, a live demo.           |
+
+## Accessibility
+
+A section named by its heading — an `<h1>`, since a hero opens its page;
+`heading-level` changes it. An image in `media` needs its own `alt`.
+
+## API
+
+| Property       | Attribute       | Type                   | Default     |
+| -------------- | --------------- | ---------------------- | ----------- |
+| `heading`      | `heading`       | `string`               | `''`        |
+| `lead`         | `lead`          | `string`               | `''`        |
+| `align`        | `align`         | `'center' \| 'start'`  | `'center'`  |
+| `layout`       | `layout`        | `'stacked' \| 'split'` | `'stacked'` |
+| `headingLevel` | `heading-level` | `number`               | `1`         |
+
+| CSS property         | What it sets                                |
+| -------------------- | ------------------------------------------- |
+| `--kt-block-padding` | The room above and below, as in every block |

package/dist/docs/kt-logo-cloud.md

@@ -0,0 +1,41 @@
+# `<kt-logo-cloud>`
+
+Who uses it, in their logos: a line of marks under a caption.
+
+```html
+<kt-logo-cloud heading="Trusted by finance teams at">
+  <img src="/logos/northwind.svg" alt="Northwind" />
+  <img src="/logos/kiln.svg" alt="Kiln" />
+  <svg role="img" aria-label="Sato Ceramics" viewBox="0 0 120 28">…</svg>
+</kt-logo-cloud>
+```
+
+## Logos
+
+The logos are the default slot: images or inline SVGs. They are drawn at one
+height — `--kt-logo-height`, 28px — and up to 160px wide, grey until hovered,
+so no brand shouts over another. `colour` keeps their colours. An inline SVG
+drawn in `currentColor` takes the muted text colour.
+
+They wrap onto as many lines as they need, centred, or at the `start` with
+`align="start"`.
+
+## Accessibility
+
+A section named by its caption — a heading, an `<h2>` by default
+(`heading-level`), set small. Each logo needs its company's name: `alt` on an
+image, `role="img"` and `aria-label` on an SVG. A logo that links to a case
+study goes in an `<a>` with that name.
+
+## API
+
+| Property       | Attribute       | Type                  | Default    |
+| -------------- | --------------- | --------------------- | ---------- |
+| `heading`      | `heading`       | `string`              | `''`       |
+| `colour`       | `colour`        | `boolean`             | `false`    |
+| `align`        | `align`         | `'center' \| 'start'` | `'center'` |
+| `headingLevel` | `heading-level` | `number`              | `2`        |
+
+| CSS property       | Default |
+| ------------------ | ------- |
+| `--kt-logo-height` | `28px`  |