kanto-ds 1.6.1 → 1.7.0

package/dist/chunks/{floating-B33g-M_1.js → floating-C9RLa6cZ.js}

@@ -3,7 +3,7 @@ import { p as r } from "./position-Cx_ZH5zh.js";
 const p = n`
   .floating {
     position: fixed;
-    inset: auto;
+    inset: 0 auto auto 0;
     display: block;
     /* As wide as what it holds, wherever it is placed: a box sized from its
        position would change size when moved, and be moved again. */
@@ -60,4 +60,4 @@ export {
   d as F,
   p as f
 };
-//# sourceMappingURL=floating-B33g-M_1.js.map
+//# sourceMappingURL=floating-C9RLa6cZ.js.map

package/dist/chunks/floating-C9RLa6cZ.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"floating-C9RLa6cZ.js","sources":["../../src/internal/floating.ts"],"sourcesContent":["import { css, type ReactiveController, type ReactiveControllerHost } from 'lit';\nimport { placeFloating, type Align, type Side } from './position.js';\n\n/**\n * A panel that opens from a trigger — a select's list, a date picker's\n * calendar, a menu — drawn in the top layer and placed from the trigger.\n *\n * A panel positioned inside its element was cut off by any ancestor with\n * `overflow: hidden`: a table cell, a side panel, an app's scrolling main\n * area. In the top layer, nothing clips it. It opens on the side asked for, or\n * the other one when that has no room, and follows the trigger as the page\n * scrolls.\n */\n\nexport interface FloatingOptions {\n  /** The panel, which carries `popover=\"manual\"` and the `floating` class. */\n  readonly panel: () => HTMLElement | null | undefined;\n  /** What the panel opens from. */\n  readonly anchor: () => Element | null | undefined;\n  /** The side it prefers. */\n  readonly side?: () => Side;\n  /** Which edge of the anchor it lines up with; its start by default. */\n  readonly align?: () => Align;\n  /** Sizes the panel to the anchor's width — a list under its field. */\n  readonly matchWidth?: boolean;\n  /** Told the side it opened on, for the direction of its entrance. */\n  readonly onPlace?: (side: Side) => void;\n}\n\n/**\n * The panel's own styles. Closed, it keeps the display and the hidden,\n * animatable state its element gives it, so it can fade out after it leaves\n * the top layer: `display` here only undoes the popover's `display: none`, and\n * a panel's own `display` still wins.\n *\n * Until it is first placed it sits top left. With auto insets a closed panel\n * sat where the flow put it — beside a right-hand trigger, past the edge of\n * the page, which then scrolled sideways.\n */\nexport const floatingStyles = css`\n  .floating {\n    position: fixed;\n    inset: 0 auto auto 0;\n    display: block;\n    /* As wide as what it holds, wherever it is placed: a box sized from its\n       position would change size when moved, and be moved again. */\n    width: max-content;\n    margin: 0;\n    color: inherit;\n    /* Set apart from the page by the theme: a lighter surface in the dark,\n       an edge and a soft shadow in the light. */\n    border: var(--border-width) solid var(--border-popover);\n    box-shadow: var(--shadow-popover);\n  }\n`;\n\nexport class FloatingController implements ReactiveController {\n  private open = false;\n  private frame = 0;\n  /** Places the panel again when its size changes — content drawn after it opened. */\n  private resizeObserver: ResizeObserver | undefined;\n\n  constructor(\n    host: ReactiveControllerHost,\n    private readonly options: FloatingOptions,\n  ) {\n    host.addController(this);\n  }\n\n  /**\n   * Call from the host's `updated()` with whether the panel is open. While it\n   * is, every update re-places it: its content — a filtered list — can change\n   * its size.\n   */\n  sync(open: boolean): void {\n    // First, and whatever the panel: one rendered only while open is already\n    // gone when it closes, and its listeners must go with it.\n    if (open !== this.open) {\n      this.open = open;\n      const method = open ? 'addEventListener' : 'removeEventListener';\n      window[method]('scroll', this.follow, { capture: true, passive: true });\n      window[method]('resize', this.follow);\n    }\n\n    const panel = this.options.panel();\n    // Where popovers are missing — a test DOM — the panel stays where it is.\n    if (!panel || typeof panel.showPopover !== 'function') return;\n\n    if (open) {\n      if (!panel.matches(':popover-open')) panel.showPopover();\n      this.place();\n      // A panel measured at opening may grow once what it holds has drawn —\n      // a calendar is an element of its own — and must be placed again.\n      if (!this.resizeObserver && typeof ResizeObserver !== 'undefined') {\n        this.resizeObserver = new ResizeObserver(this.follow);\n        this.resizeObserver.observe(panel);\n      }\n    } else {\n      this.unobserve();\n      if (panel.matches(':popover-open')) panel.hidePopover();\n    }\n  }\n\n  private unobserve(): void {\n    this.resizeObserver?.disconnect();\n    this.resizeObserver = undefined;\n  }\n\n  hostDisconnected(): void {\n    this.sync(false);\n    this.unobserve();\n    cancelAnimationFrame(this.frame);\n  }\n\n  private follow = (): void => {\n    cancelAnimationFrame(this.frame);\n    this.frame = requestAnimationFrame(() => this.place());\n  };\n\n  private place(): void {\n    const panel = this.options.panel();\n    const anchor = this.options.anchor()?.getBoundingClientRect();\n    if (!panel || !anchor) return;\n\n    if (this.options.matchWidth) panel.style.width = `${anchor.width}px`;\n    // Untransformed size: the entrance animation scales and slides the panel.\n    const { x, y, placement } = placeFloating(\n      anchor,\n      { width: panel.offsetWidth, height: panel.offsetHeight },\n      { width: window.innerWidth, height: window.innerHeight },\n      this.options.side?.() ?? 'bottom',\n      this.options.align?.() ?? 'start',\n    );\n    panel.style.left = `${x}px`;\n    panel.style.top = `${y}px`;\n    this.options.onPlace?.(placement);\n  }\n}\n"],"names":["floatingStyles","css","FloatingController","host","options","open","method","panel","anchor","x","y","placement","placeFloating"],"mappings":";;AAuCO,MAAMA,IAAiBC;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAiBvB,MAAMC,EAAiD;AAAA,EAM5D,YACEC,GACiBC,GACjB;AADiB,SAAA,UAAAA,GAPnB,KAAQ,OAAO,IACf,KAAQ,QAAQ,GAwDhB,KAAQ,SAAS,MAAY;AAC3B,2BAAqB,KAAK,KAAK,GAC/B,KAAK,QAAQ,sBAAsB,MAAM,KAAK,OAAO;AAAA,IACvD,GAnDED,EAAK,cAAc,IAAI;AAAA,EACzB;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOA,KAAKE,GAAqB;AAGxB,QAAIA,MAAS,KAAK,MAAM;AACtB,WAAK,OAAOA;AACZ,YAAMC,IAASD,IAAO,qBAAqB;AAC3C,aAAOC,CAAM,EAAE,UAAU,KAAK,QAAQ,EAAE,SAAS,IAAM,SAAS,IAAM,GACtE,OAAOA,CAAM,EAAE,UAAU,KAAK,MAAM;AAAA,IACtC;AAEA,UAAMC,IAAQ,KAAK,QAAQ,MAAA;AAE3B,IAAI,CAACA,KAAS,OAAOA,EAAM,eAAgB,eAEvCF,KACGE,EAAM,QAAQ,eAAe,OAAS,YAAA,GAC3C,KAAK,MAAA,GAGD,CAAC,KAAK,kBAAkB,OAAO,iBAAmB,QACpD,KAAK,iBAAiB,IAAI,eAAe,KAAK,MAAM,GACpD,KAAK,eAAe,QAAQA,CAAK,OAGnC,KAAK,UAAA,GACDA,EAAM,QAAQ,eAAe,OAAS,YAAA;AAAA,EAE9C;AAAA,EAEQ,YAAkB;AACxB,SAAK,gBAAgB,WAAA,GACrB,KAAK,iBAAiB;AAAA,EACxB;AAAA,EAEA,mBAAyB;AACvB,SAAK,KAAK,EAAK,GACf,KAAK,UAAA,GACL,qBAAqB,KAAK,KAAK;AAAA,EACjC;AAAA,EAOQ,QAAc;AACpB,UAAMA,IAAQ,KAAK,QAAQ,MAAA,GACrBC,IAAS,KAAK,QAAQ,OAAA,GAAU,sBAAA;AACtC,QAAI,CAACD,KAAS,CAACC,EAAQ;AAEvB,IAAI,KAAK,QAAQ,eAAYD,EAAM,MAAM,QAAQ,GAAGC,EAAO,KAAK;AAEhE,UAAM,EAAE,GAAAC,GAAG,GAAAC,GAAG,WAAAC,EAAA,IAAcC;AAAA,MAC1BJ;AAAA,MACA,EAAE,OAAOD,EAAM,aAAa,QAAQA,EAAM,aAAA;AAAA,MAC1C,EAAE,OAAO,OAAO,YAAY,QAAQ,OAAO,YAAA;AAAA,MAC3C,KAAK,QAAQ,OAAA,KAAY;AAAA,MACzB,KAAK,QAAQ,aAAa;AAAA,IAAA;AAE5B,IAAAA,EAAM,MAAM,OAAO,GAAGE,CAAC,MACvBF,EAAM,MAAM,MAAM,GAAGG,CAAC,MACtB,KAAK,QAAQ,UAAUC,CAAS;AAAA,EAClC;AACF;"}

package/dist/components/forms/kt-date-input/kt-date-input.js

@@ -3,7 +3,7 @@ import { property as w, state as x, query as $ } from "lit/decorators.js";
 import { classMap as C } from "lit/directives/class-map.js";
 import { d as P } from "../../../chunks/kt-element-T0VbIBNp.js";
 import { u as S, t as I } from "../../../chunks/events-r51msXNf.js";
-import { F as q, f as E } from "../../../chunks/floating-B33g-M_1.js";
+import { F as q, f as E } from "../../../chunks/floating-C9RLa6cZ.js";
 import { K as f } from "../../../chunks/segmented-field-BBXR4XFL.js";
 import { d as y, p as u, t as v, c as b, f as Y } from "../../../chunks/kt-calendar-CtwOby1R.js";
 import { d as K, e as L, t as M } from "../../../chunks/typed-date-CPAUNHzr.js";

package/dist/components/forms/kt-date-picker/kt-date-picker.js

@@ -5,7 +5,7 @@ import { live as O } from "lit/directives/live.js";
 import { K as D, d as R } from "../../../chunks/kt-element-T0VbIBNp.js";
 import { u as q, t as E, e as v } from "../../../chunks/events-r51msXNf.js";
 import { a as B, s as F, b as L } from "../../../chunks/form-control-B74_EHtG.js";
-import { F as z, f as K } from "../../../chunks/floating-B33g-M_1.js";
+import { F as z, f as K } from "../../../chunks/floating-C9RLa6cZ.js";
 import { r as M, d as _ } from "../../../chunks/locale-C5xLkGx5.js";
 import { s as f } from "../../../chunks/index-TWJzttLX.js";
 import { a as P, p as u, c as g, b as w, t as m, e as k, f as C, g as V, h as I, d as W } from "../../../chunks/kt-calendar-CtwOby1R.js";

package/dist/components/forms/kt-input/kt-input.js

@@ -5,7 +5,7 @@ import { live as w } from "lit/directives/live.js";
 import { K as g, d as $ } from "../../../chunks/kt-element-T0VbIBNp.js";
 import { t as C, e as c } from "../../../chunks/events-r51msXNf.js";
 import { a as S, s as b, b as E } from "../../../chunks/form-control-B74_EHtG.js";
-import { F as O, f as z } from "../../../chunks/floating-B33g-M_1.js";
+import { F as O, f as z } from "../../../chunks/floating-C9RLa6cZ.js";
 import { s as u } from "../../../chunks/index-TWJzttLX.js";
 import "../../core/kt-icon/kt-icon.js";
 import "../../feedback/kt-tooltip/kt-tooltip.js";

package/dist/components/forms/kt-input-menu/kt-input-menu.js

@@ -6,7 +6,7 @@ import { K as m, d as $ } from "../../../chunks/kt-element-T0VbIBNp.js";
 import { u as I, t as y, e as f } from "../../../chunks/events-r51msXNf.js";
 import { a as D, s as q, b as O } from "../../../chunks/form-control-B74_EHtG.js";
 import { a as S, b as C, o as g, f as v, l as P, n as E } from "../../../chunks/listbox-LsUEyGhQ.js";
-import { F as L, f as A } from "../../../chunks/floating-B33g-M_1.js";
+import { F as L, f as A } from "../../../chunks/floating-C9RLa6cZ.js";
 import { s as l } from "../../../chunks/index-TWJzttLX.js";
 import "../../core/kt-icon/kt-icon.js";
 var V = Object.defineProperty, i = (u, t, o, r) => {

package/dist/components/forms/kt-multi-select/kt-multi-select.js

@@ -6,7 +6,7 @@ import { K as $, d as P } from "../../../chunks/kt-element-T0VbIBNp.js";
 import { u as C, t as I, e as D } from "../../../chunks/events-r51msXNf.js";
 import { a as L, s as z, b as B } from "../../../chunks/form-control-B74_EHtG.js";
 import { a as T, b as F, f as y, l as V, n as _, o as w } from "../../../chunks/listbox-LsUEyGhQ.js";
-import { F as A, f as W } from "../../../chunks/floating-B33g-M_1.js";
+import { F as A, f as W } from "../../../chunks/floating-C9RLa6cZ.js";
 import { s as p } from "../../../chunks/index-TWJzttLX.js";
 import "../../core/kt-icon/kt-icon.js";
 var K = Object.defineProperty, r = (m, t, i, e) => {

package/dist/components/forms/kt-select/kt-select.js

@@ -5,7 +5,7 @@ import { K as v, d as w } from "../../../chunks/kt-element-T0VbIBNp.js";
 import { u as k, t as g, e as m } from "../../../chunks/events-r51msXNf.js";
 import { a as $, s as I, b as D } from "../../../chunks/form-control-B74_EHtG.js";
 import { a as S, f as b, l as L, n as C, o as y } from "../../../chunks/listbox-LsUEyGhQ.js";
-import { F as E, f as P } from "../../../chunks/floating-B33g-M_1.js";
+import { F as E, f as P } from "../../../chunks/floating-C9RLa6cZ.js";
 import { s as l } from "../../../chunks/index-TWJzttLX.js";
 import "../../core/kt-icon/kt-icon.js";
 var q = Object.defineProperty, i = (c, e, o, a) => {

package/dist/components/overlays/kt-dropdown/kt-dropdown.js

@@ -4,7 +4,7 @@ import { classMap as u } from "lit/directives/class-map.js";
 import { K as c, d as b } from "../../../chunks/kt-element-T0VbIBNp.js";
 import { t as m, e as d } from "../../../chunks/events-r51msXNf.js";
 import { o as x } from "../../../chunks/listbox-LsUEyGhQ.js";
-import { F as w, f as k } from "../../../chunks/floating-B33g-M_1.js";
+import { F as w, f as k } from "../../../chunks/floating-C9RLa6cZ.js";
 import { s as $ } from "../../../chunks/index-TWJzttLX.js";
 var P = Object.defineProperty, r = (i, t, s, a) => {
   for (var o = void 0, l = i.length - 1, g; l >= 0; l--)

package/dist/docs/kt-alert.md

@@ -0,0 +1,52 @@
+# `<kt-alert>`
+
+A message that stays on the page.
+
+```html
+<kt-alert
+  variant="warning"
+  heading="Storage almost full"
+  description="You are using 88% of your quota."
+  dismissible
+>
+  <kt-button slot="actions" size="small" variant="warning">Upgrade</kt-button>
+</kt-alert>
+```
+
+## Against a toast
+
+A **toast** is transient and interrupts; it belongs to the moment. An **alert**
+sits in the layout and waits; it belongs to the page.
+
+A form that failed to save, a trial about to expire, a consent notice — all
+alerts. "Saved", "Copied", "3 rows deleted" — all toasts. Getting this backwards
+is how important messages disappear after four seconds.
+
+## Colour and urgency
+
+The whole block takes the variant's tint and border, so the message's
+temperature is legible before a word is read. `danger` is `aria-live="assertive"`
+and interrupts the screen reader; everything else is polite and waits its turn.
+
+`dismissible` adds the button and fires `kt-close` — **removing the alert is
+yours**, because only the caller knows whether it should come back.
+
+## API
+
+| Property      | Attribute     | Type                                                        | Default  |
+| ------------- | ------------- | ----------------------------------------------------------- | -------- |
+| `variant`     | `variant`     | `'info' \| 'success' \| 'warning' \| 'danger' \| 'neutral'` | `'info'` |
+| `heading`     | `heading`     | `string`                                                    | `''`     |
+| `description` | `description` | `string`                                                    | `''`     |
+| `dismissible` | `dismissible` | `boolean`                                                   | `false`  |
+| `noIcon`      | `no-icon`     | `boolean`                                                   | `false`  |
+| `icon`        | `icon`        | `string`                                                    | `''`     |
+
+| Slot      | Description                          |
+| --------- | ------------------------------------ |
+| _default_ | Body, when `description` is not used |
+| `actions` | Buttons, at the end                  |
+
+| Event      | Description                    |
+| ---------- | ------------------------------ |
+| `kt-close` | The dismiss button was pressed |

package/dist/docs/kt-avatar.md

@@ -0,0 +1,46 @@
+# `<kt-avatar>`
+
+A person or an organisation, as a picture or as their initials.
+
+```html
+<kt-avatar name="Benjamin Canac"></kt-avatar>
+<kt-avatar name="Emma Davis" src="/emma.jpg" status="online"></kt-avatar>
+<kt-avatar name="Kanto Studio" square size="large"></kt-avatar>
+```
+
+## The fallback is the main path
+
+Most rows in most products have no photo, so the initials are what actually
+renders. They are derived from the name — first and last word, or the first two
+letters of a single word — and an email address is read as one, so
+`emma.davis@example.com` becomes `ED`.
+
+The colour is picked from the name, which means **the same person is the same
+colour on every screen**. That is not decoration: it lets the eye find a row
+before it has read it. Override it with `color` when the entity has a brand of
+its own.
+
+A photo that fails to load falls back to the initials rather than to a broken
+image. Changing `src` clears that failure, so a retry is a property assignment.
+
+## API
+
+| Property | Attribute | Type                                        | Default    |
+| -------- | --------- | ------------------------------------------- | ---------- |
+| `name`   | `name`    | `string`                                    | `''`       |
+| `src`    | `src`     | `string`                                    | `''`       |
+| `size`   | `size`    | `'small' \| 'medium' \| 'large'`            | `'medium'` |
+| `square` | `square`  | `boolean`                                   | `false`    |
+| `status` | `status`  | `'online' \| 'away' \| 'busy' \| 'offline'` | —          |
+| `color`  | `color`   | `string`                                    | `''`       |
+
+Sizes are 24 / 32 / 48px, and everything inside scales from
+`--kt-avatar-size`, so overriding that one property resizes the whole thing.
+
+| Part    | Description |
+| ------- | ----------- |
+| `base`  | The circle  |
+| `image` | The `<img>` |
+
+`initialsOf(name)` is exported too, for the cases where you need the same
+letters somewhere else.

package/dist/docs/kt-badge.md

@@ -0,0 +1,104 @@
+# `<kt-badge>`
+
+A compact label: a pill `tag`, a monospaced `code` token, a `category` tinted
+with a colour of your choosing, or a `count`.
+
+```html
+<kt-badge>Design systems</kt-badge>
+<kt-badge tone="success">Active</kt-badge>
+<kt-badge variant="code">--surface-card</kt-badge>
+<kt-badge variant="category" color="#3987e5">Infrastructure</kt-badge>
+<kt-badge variant="count" tone="danger" max="99">128</kt-badge>
+<kt-badge icon="user" removable>Assigned to me</kt-badge>
+```
+
+## Shape and colour are separate
+
+`variant` is the **shape** — what kind of thing this is. `tone` is the
+**colour** — what it means. They are separate properties because they answer
+different questions: a tag can be neutral or dangerous, and so can a count.
+Folding them into one list would give you nine variants and still no way to say
+"a tag, but this one is a warning".
+
+| `variant`  | What it is                                           |
+| ---------- | ---------------------------------------------------- |
+| `tag`      | The default. A pill: a label, a filter, a topic.     |
+| `code`     | A monospaced token — a property name, a flag, a key. |
+| `category` | Tinted with `color`, for a palette the data owns.    |
+| `count`    | A number pinned to something else.                   |
+
+`count` is the one shape with no border. A number on a nav item is a mark on
+the thing it counts, not a label with an outline of its own — and at that size
+a border is most of what you see.
+
+`tone` uses the system's tinted pair throughout: the colour behind at low
+opacity, the colour itself as the ink. The same pair a secondary button, a
+danger button and an avatar wear, so a badge beside any of them reads as one
+family.
+
+## Categories
+
+`category` takes any CSS colour and fills at 20% of it:
+
+```html
+<kt-badge variant="category" color="var(--color-success-base)">Delivered</kt-badge>
+<kt-badge variant="category" color="rgb(57, 135, 229)">Infrastructure</kt-badge>
+```
+
+The mixing is `color-mix`, which is honest for every notation. The build this
+replaced concatenated a `"33"` onto the string and produced garbage for
+`rgb()` and for named colours.
+
+Reach for `tone` when the meaning is one of the system's six states, and
+`category` when the palette belongs to the data — a project colour, a label the
+user picked.
+
+## Counting
+
+`max` caps a numeric label: `max="99"` on `128` shows `99+`. A non-numeric
+label is left alone, so `max` is safe to set from a template that does not know
+what it will be given.
+
+## Interaction
+
+Neither `clickable` nor `removable` is on by default, because most badges are
+labels and a label that looks pressable is a lie.
+
+`clickable` makes it a real control — `role="button"`, a tab stop, Enter and
+Space — and fires `kt-badge-click`. `removable` adds a remove button that fires
+a cancelable `kt-remove`; cancel it and remove the badge yourself once the
+server agrees. A badge that is both does not report the click when the remove
+button is what was pressed.
+
+## API
+
+| Property    | Attribute   | Type                                                                     | Default     |
+| ----------- | ----------- | ------------------------------------------------------------------------ | ----------- |
+| `variant`   | `variant`   | `'tag' \| 'code' \| 'category' \| 'count'`                               | `'tag'`     |
+| `tone`      | `tone`      | `'neutral' \| 'primary' \| 'success' \| 'warning' \| 'danger' \| 'info'` | `'neutral'` |
+| `size`      | `size`      | `'small' \| 'medium'`                                                    | `'medium'`  |
+| `label`     | `label`     | `string`                                                                 | `''`        |
+| `color`     | `color`     | `string` — any CSS colour, for `category`                                | `''`        |
+| `icon`      | `icon`      | `string` — lucide name, before the text                                  | `''`        |
+| `clickable` | `clickable` | `boolean`                                                                | `false`     |
+| `removable` | `removable` | `boolean`                                                                | `false`     |
+| `max`       | `max`       | `number`                                                                 | —           |
+| `error`     | `error`     | `boolean` — shorthand for `tone="danger"`                                | `false`     |
+
+| Event            | Detail       |
+| ---------------- | ------------ |
+| `kt-badge-click` | — cancelable |
+| `kt-remove`      | — cancelable |
+
+| Slot      | Description                      |
+| --------- | -------------------------------- |
+| _default_ | The text. Falls back to `label`. |
+
+| CSS property       | Description                          |
+| ------------------ | ------------------------------------ |
+| `--kt-badge-color` | Category hue; the fill is it at 20%. |
+
+| Part     | Description                         |
+| -------- | ----------------------------------- |
+| `base`   | The container                       |
+| `remove` | The remove button, when `removable` |

package/dist/docs/kt-breadcrumb.md

@@ -0,0 +1,53 @@
+# `<kt-breadcrumb>`
+
+A trail showing where the current page sits.
+
+```js
+trail.items = [
+  { label: 'Home', href: '/' },
+  { label: 'Entities', href: '/entites' },
+  { label: 'Entity 4812' },
+];
+```
+
+The last entry is the current page: rendered as text with `aria-current="page"`,
+not as a link. A breadcrumb whose final item links to the page you are already
+on is a dead control.
+
+## Client-side routing
+
+`kt-navigate` is cancelable. Cancel it and the browser will not follow the
+href; leave it alone and the link behaves like a link.
+
+```js
+trail.addEventListener('kt-navigate', (e) => {
+  e.preventDefault();
+  router.push(e.detail.item.href);
+});
+```
+
+Modified clicks — ⌘, Ctrl, Shift, middle button — are never intercepted. The
+user is asking the browser for a new tab, and the element stays out of it.
+
+## API
+
+| Property | Attribute | Type                 | Default        |
+| -------- | --------- | -------------------- | -------------- |
+| `items`  | —         | `KtBreadcrumbItem[]` | `[]`           |
+| `label`  | `label`   | `string`             | `"Breadcrumb"` |
+
+```ts
+interface KtBreadcrumbItem {
+  label: string;
+  href?: string;
+}
+```
+
+| Event         | Detail                         |
+| ------------- | ------------------------------ |
+| `kt-navigate` | `{ item, index }` — cancelable |
+
+| Part   | Description   |
+| ------ | ------------- |
+| `nav`  | The `<nav>`   |
+| `item` | A trail entry |

package/dist/docs/kt-button.md

@@ -0,0 +1,72 @@
+# `<kt-button>`
+
+The Kanto action button. Ten variants, three sizes, an optional Lucide icon.
+
+```html
+<kt-button icon="plus">New entity</kt-button>
+<kt-button variant="secondary" icon="refresh-cw">Refresh</kt-button>
+<kt-button variant="danger">Delete</kt-button>
+<kt-button variant="text">View full history</kt-button>
+```
+
+## Choosing a variant
+
+| Variant                    | Use for                                                         |
+| -------------------------- | --------------------------------------------------------------- |
+| `primary`                  | The one action a screen is about. At most one per view.         |
+| `secondary`                | Supporting actions. Soft indigo tint.                           |
+| `secondary-no-bg`          | The same, with no resting background — for toolbars.            |
+| `dark`                     | Neutral actions that must not compete for attention.            |
+| `danger`                   | Destructive, but recoverable. Tinted red.                       |
+| `delete`                   | Irreversible. The only solid red in the system — use sparingly. |
+| `warning` `info` `success` | Status-carrying actions inside a matching context.              |
+| `text`                     | Inline, link-like. No padding, no height.                       |
+
+## Icon-only
+
+An `icon` with no slotted text collapses the button to a square. It then has no
+accessible name of its own, so `label` is required:
+
+```html
+<kt-button icon="x" label="Close" variant="secondary-no-bg"></kt-button>
+```
+
+## Forms
+
+A button inside a shadow root is invisible to the enclosing form, so
+`type="submit"` would normally do nothing. `<kt-button>` bridges that: it runs
+the form's constraint validation, fires a real `submit` event, and carries
+`name` / `value` into the submission.
+
+```html
+<form>
+  <kt-input name="email" type="email" required></kt-input>
+  <kt-button type="submit">Send</kt-button>
+</form>
+```
+
+## API
+
+| Property       | Attribute       | Type                              | Default     |
+| -------------- | --------------- | --------------------------------- | ----------- |
+| `variant`      | `variant`       | see table above                   | `'primary'` |
+| `size`         | `size`          | `'small' \| 'medium' \| 'large'`  | `'medium'`  |
+| `disabled`     | `disabled`      | `boolean`                         | `false`     |
+| `type`         | `type`          | `'button' \| 'submit' \| 'reset'` | `'button'`  |
+| `icon`         | `icon`          | `string`                          | `''`        |
+| `iconPosition` | `icon-position` | `'left' \| 'right'`               | `'left'`    |
+| `label`        | `label`         | `string`                          | `''`        |
+| `fullWidth`    | `full-width`    | `boolean`                         | `false`     |
+| `name`         | `name`          | `string`                          | `''`        |
+| `value`        | `value`         | `string`                          | `''`        |
+
+| Slot      | Description      |
+| --------- | ---------------- |
+| _default_ | The button label |
+
+| Part     | Description           |
+| -------- | --------------------- |
+| `button` | The native `<button>` |
+| `icon`   | The icon, when set    |
+
+Emits no custom events — listen for `click` as on any button.

package/dist/docs/kt-calendar.md

@@ -0,0 +1,98 @@
+# `<kt-calendar>`
+
+A month calendar to pick a day or a period from, shown in the page.
+
+```html
+<kt-calendar value="2026-09-25"></kt-calendar>
+<kt-calendar range value="2026-09-07/2026-09-18" min="2026-01-01"></kt-calendar>
+```
+
+It is the calendar `<kt-date-picker>` opens in its popup. Use it on its own
+when the calendar _is_ the interface — a booking page, a dashboard's date
+filter, a planning view — and `<kt-date-picker>` when it is only a way to fill
+a field.
+
+## A month and a year in two clicks
+
+The title — "September 2026" — opens one panel: a scrolling list of years
+beside the twelve months of the one chosen. Pick the year, then the month, and
+the days are back, the day of the month kept: from 25 September, choosing March
+1987 lands on 25 March 1987. The list opens on the chosen year, centred, and
+reaches from `min` to `max` — or, without them, 120 years back and 50 ahead,
+birthdays to plans. Typing four digits in the list jumps to that year. Months
+wholly outside `min`/`max` are disabled.
+
+The arrows beside the title page a month at a time; they are the only thing
+that does.
+
+## Two months
+
+`months="2"` shows two months side by side — what `<kt-date-picker range>`
+does, so a period across a month's end is two clicks. Each grid holds its own
+days only, so none shows twice, and the keyboard moves across both, paging
+only once it leaves the second.
+
+## Keyboard
+
+In the days, the WAI-ARIA date grid pattern:
+
+| Key                          | Does                            |
+| ---------------------------- | ------------------------------- |
+| `←` / `→`                    | Previous / next day             |
+| `↑` / `↓`                    | Same day, previous / next week  |
+| `Home` / `End`               | First / last day of the week    |
+| `Page Up` / `Page Down`      | Same day, previous / next month |
+| `Shift` + `Page Up` / `Down` | Same day, previous / next year  |
+| `Enter` / `Space`            | Choose the day in focus         |
+
+In the year list:
+
+| Key                     | Does                                                                 |
+| ----------------------- | -------------------------------------------------------------------- |
+| `↑` / `↓`               | Previous / next year                                                 |
+| `Page Up` / `Page Down` | Ten years back / ahead                                               |
+| `Home` / `End`          | First / last year offered                                            |
+| Four digits             | That year                                                            |
+| `Enter`, `Tab`          | On to the months                                                     |
+| `Escape`                | Back to the days — and no further, so an enclosing dialog stays open |
+
+In the months: the arrows, three to a row; `Page Up`/`Page Down` by year;
+`Enter` to choose; `Escape` back to the days.
+
+Focus follows every switch, so the keys keep working without a click in
+between.
+
+## ISO values and locales
+
+As for `<kt-date-picker>`: the value is ISO 8601 text — `2026-09-25`, or
+`2026-09-07/2026-09-18` with `range` — and names, the first day of the week
+and every accessible label follow `locale`, else the page's `lang`, else the
+browser's language. A period takes two picks in either order and fires
+`kt-change` once, with the whole period.
+
+`<kt-calendar>` is not a form control; inside a form, use `<kt-date-picker>`.
+
+## API
+
+| Property | Attribute | Type             | Default            |
+| -------- | --------- | ---------------- | ------------------ |
+| `value`  | `value`   | `string \| null` | `null`             |
+| `range`  | `range`   | `boolean`        | `false`            |
+| `min`    | `min`     | `string`         | `''`               |
+| `max`    | `max`     | `string`         | `''`               |
+| `months` | `months`  | `1 \| 2`         | `1`                |
+| `locale` | `locale`  | `string`         | page, then browser |
+| `label`  | `label`   | `string`         | from `setStrings`  |
+
+| Method    | Description                                |
+| --------- | ------------------------------------------ |
+| `focus()` | Focuses the current day — chosen, or today |
+
+| Event       | Detail                                     |
+| ----------- | ------------------------------------------ |
+| `kt-change` | `{ value: string }` — ISO date or interval |
+
+| Part   | Description  |
+| ------ | ------------ |
+| `base` | The calendar |
+| `day`  | A day cell   |

package/dist/docs/kt-card.md

@@ -0,0 +1,93 @@
+# `<kt-card>`
+
+The system's content surface: 12px radius, a 1px `--border-subtle` border, 24px
+of padding, 20px between its rows. Transparent at rest — a card reads as a
+grouping, not as an elevation.
+
+```html
+<kt-card>
+  <h6 slot="header">Recent transactions</h6>
+  <kt-table></kt-table>
+  <kt-button slot="footer" variant="text">View full history</kt-button>
+</kt-card>
+```
+
+Empty `header` and `footer` slots collapse, so an omitted footer costs no gap.
+
+## Clickable cards
+
+```html
+<kt-card clickable>Entity 4812</kt-card>
+```
+
+`clickable` gives the card `role="button"`, a tab stop, hover and active
+states, and Enter/Space activation, then fires `kt-card-click`. The
+div-with-a-click-handler it replaces did none of that.
+
+Do not nest interactive elements inside a clickable card — a button inside a
+button is invalid, and the two hit targets fight. Either the card is the
+control, or the things inside it are.
+
+## Selected cards
+
+`selected` marks a card as chosen — one filter of several, a picked plan:
+
+```html
+<kt-card clickable selected>Pending</kt-card>
+```
+
+It tints the card, outlines it in the primary colour and sets `aria-pressed`,
+so the state is announced and not merely drawn.
+
+Pair it with `clickable`. A card the user cannot toggle has no business looking
+toggled, so a `selected` card that is not `clickable` gets the styling but no
+`aria-pressed` — there is nothing to press, and claiming otherwise would be a
+lie to a screen reader.
+
+The outline lives on the card's own box rather than on the host element. An
+outline only follows a `border-radius` declared on the same element, and the
+host has none — put one on the host and you get sharp corners around a rounded
+card.
+
+## Media
+
+`image` is the convenience path; the `media` slot takes anything else.
+
+```html
+<kt-card image="/preview.png" image-alt="Preview" image-position="top" image-size="160px"></kt-card>
+
+<kt-card image-position="right" image-size="200px">
+  <canvas slot="media"></canvas>
+  Monthly breakdown
+</kt-card>
+```
+
+`image-size` sets the width for `left`/`right` and the height for `top`/`bottom`.
+
+## API
+
+| Property        | Attribute        | Type                                     | Default   |
+| --------------- | ---------------- | ---------------------------------------- | --------- |
+| `clickable`     | `clickable`      | `boolean`                                | `false`   |
+| `selected`      | `selected`       | `boolean`                                | `false`   |
+| `image`         | `image`          | `string`                                 | `''`      |
+| `imageAlt`      | `image-alt`      | `string`                                 | `''`      |
+| `imagePosition` | `image-position` | `'left' \| 'right' \| 'top' \| 'bottom'` | `'left'`  |
+| `imageSize`     | `image-size`     | `string`                                 | `'120px'` |
+
+| Slot      | Description                    |
+| --------- | ------------------------------ |
+| _default_ | Card body                      |
+| `header`  | Above the body                 |
+| `footer`  | Below the body                 |
+| `media`   | Replaces the `image` attribute |
+
+| Event           | Detail | Fired when                                   |
+| --------------- | ------ | -------------------------------------------- |
+| `kt-card-click` | —      | A `clickable` card is activated. Cancelable. |
+
+| Part    | Description                  |
+| ------- | ---------------------------- |
+| `base`  | The card container           |
+| `media` | The image or media well      |
+| `body`  | Header/content/footer column |