kanto-ds 1.6.1 → 1.7.0

package/dist/docs/kt-chart.md

@@ -0,0 +1,230 @@
+# `<kt-chart>`
+
+A chart, drawn from the token layer: line, area and bar — stacked, sideways or
+mixed — plus scatter, bubble, pie, doughnut, polar area and radar.
+
+```js
+chart.labels = ['Jan', 'Feb', 'Mar', 'Apr'];
+chart.series = [{ name: 'Revenue', values: [42, 58, 36, 71] }];
+chart.format = (n) => `$${n.toLocaleString('en-US')}`;
+```
+
+```html
+<kt-chart type="area" label="Revenue by month" height="220"></kt-chart>
+```
+
+Every type shares one data model, one tooltip, one legend and one keyboard
+model, so learning one chart is learning all of them.
+
+## Choosing a type
+
+| Type                 | Use it for                                                                                 |
+| -------------------- | ------------------------------------------------------------------------------------------ |
+| `line`               | A measure over time, where the shape of the change is the point                            |
+| `area`               | The same, when the size under the line matters — or, `stacked`, parts of a total over time |
+| `bar`                | Comparing categories                                                                       |
+| `bar` + `horizontal` | Long category names, or a ranking read top to bottom                                       |
+| `bar` + `stacked`    | A total per category, split into parts                                                     |
+| mixed                | A measure in bars against a target or average as a line                                    |
+| `scatter`            | Whether two measures move together                                                         |
+| `bubble`             | The same, with a third measure as size                                                     |
+| `pie`                | A few parts of one whole — past five slices, use a bar                                     |
+| `doughnut`           | A pie with the total in the middle                                                         |
+| `polar-area`         | Cyclic categories compared by size                                                         |
+| `radar`              | A profile across several measures on the same scale                                        |
+
+## The rules it keeps
+
+**One value axis, always.** There is no second y-scale and there will not be:
+two measures of different magnitude belong in two charts, or indexed to a common
+base. A dual-axis chart lets you imply any correlation you like by sliding one
+scale.
+
+**Bars and areas start at zero.** Their size is their distance from zero, so a
+bar axis that starts at 40 makes 50 look twice 45. Lines follow their data,
+because a line is read by its shape. `min` and `max` override both — use them
+knowingly.
+
+**Area carries the value.** A bubble twice the value is twice the area, not
+twice the radius, and a polar slice's radius is the square root of its value.
+Anything else overstates the big ones.
+
+**Slices are one distribution.** Pie, doughnut and polar area read `labels` as
+the slices and the **first series** as their values. Comparing two
+distributions is a stacked bar's job, not two pies'. Negative values are drawn
+as nothing and kept, as written, in the table.
+
+## Colour
+
+**One series takes the brand hue.** With nothing to tell apart there is no
+identity to encode, and the title names it — so a lone series needs no legend
+either, and does not get one.
+
+**Two or more take the fixed categorical order** in `--chart-series-1…8`,
+assigned by position and never cycled. A ninth series is not a generated hue —
+fold it into "Other", or facet. Slices take the same order, by slice.
+
+Those eight hues are kept clear of the semantic palette, so a line can never be
+mistaken for a status. They are validated against Kanto's own card surface in
+both themes: worst adjacent CVD ΔE 8.4, worst adjacent normal-vision ΔE 19.3.
+
+**Colour follows the entity, not the rank.** Hiding a series from the legend
+never repaints the others. If a filter removes one from the data, pass `color`
+on the survivors so they keep the hue the reader learned:
+
+```js
+chart.series = [{ name: 'Orders', values, color: 'var(--chart-series-2)' }];
+```
+
+Separators — the gap between slices, the ring around a dot — are drawn in
+`--surface-card`. Put the chart on a card surface and they read as the surface
+showing through.
+
+## Stacked, sideways and mixed
+
+```html
+<kt-chart type="bar" stacked></kt-chart>
+
+<kt-chart type="bar" horizontal></kt-chart>
+```
+
+`stacked` piles bars on bars and areas on areas; lines never stack. The tooltip
+adds a total, and so does the table.
+
+A series can be drawn as another mark with its own `type`. Lines are then placed
+at the centre of each bar's band and drawn above the bars:
+
+```js
+chart.type = 'bar';
+chart.series = [
+  { name: 'Signups', values: [320, 410, 380] },
+  { name: 'Target', values: [400, 420, 440], type: 'line' },
+];
+```
+
+`horizontal` applies only when every visible series is a bar.
+
+## Scatter and bubble
+
+These take `points` instead of `values`, and no `labels`:
+
+```js
+chart.type = 'bubble';
+chart.series = [
+  {
+    name: 'Markets',
+    points: [
+      { x: 4, y: 18, r: 120, label: 'France' },
+      { x: 9, y: 24, r: 64, label: 'Germany' },
+    ],
+  },
+];
+chart.format = (n) => `${n}%`; // y
+chart.formatX = (n) => `${n}%`; // x
+```
+
+Neither axis is forced through zero: a scatter plot is about how two measures
+move together, and dragging the origin in crushes the cloud into a corner. A
+`label` names the point in the tooltip and the table.
+
+## Hover and keyboard
+
+The tooltip follows the pointer on every type: a whole category on line, area
+and bar charts, the nearest point on scatter and bubble, a slice or a spoke on
+radial charts. It opens above the mark, or beside it when there is no room —
+never on top of what it describes.
+
+The plot is focusable. **Arrow keys** walk the categories, slices or spokes;
+on scatter and bubble, left and right walk the current series in x order and up
+and down move between series. **Home** and **End** jump to the ends,
+**Escape** lets go. The tooltip is a live region, so a keyboard move is
+announced.
+
+`kt-point-hover` reports every change, so a caption or a figure elsewhere on the
+page can follow along.
+
+## The legend
+
+It appears from two series up, and always for pie, doughnut and polar area,
+whose slices need names. Each item is a toggle: pressing it hides the series or
+slice and rescales the chart around what is left. `kt-series-toggle` is
+cancelable, for a host that wants to decide. New data resets the legend.
+
+## The table is not optional
+
+Every chart also renders its data as a `<table>`, visually hidden and pointed at
+by the plot's `aria-describedby`. It is what a screen reader reads, and it is
+the relief that four of the light-theme series hues require — they sit below 3:1
+on a light surface, which is legal only with a text alternative.
+
+`show-table` puts it on screen, which is often the right call in a report.
+
+## Smoothing is off
+
+`smooth` draws lines and areas through a monotone cubic — one that never
+overshoots the samples, unlike the cardinal spline most charts reach for, which
+invents peaks that are not in the data.
+
+It is still off by default, because a curve between two samples draws values
+nobody measured. Turn it on when the underlying quantity really is continuous
+and the reader knows it. A radar is always drawn straight: a closed curve has no
+monotone version.
+
+## Motion
+
+Marks enter once, when they first appear: bars grow from the baseline, lines
+draw along their length, everything else fades in. Nothing moves on hover.
+The token layer's reduced-motion block turns the entrance off.
+
+## API
+
+| Property      | Attribute      | Type                        | Default   |
+| ------------- | -------------- | --------------------------- | --------- |
+| `type`        | `type`         | `KtChartType`               | `'area'`  |
+| `series`      | —              | `KtSeries[]`                | `[]`      |
+| `labels`      | —              | `string[]`                  | `[]`      |
+| `height`      | `height`       | `number`                    | `200`     |
+| `format`      | —              | `(value: number) => string` | `String`  |
+| `formatX`     | —              | `(value: number) => string` | `String`  |
+| `stacked`     | `stacked`      | `boolean`                   | `false`   |
+| `horizontal`  | `horizontal`   | `boolean`                   | `false`   |
+| `smooth`      | `smooth`       | `boolean`                   | `false`   |
+| `min`         | `min`          | `number \| null`            | `null`    |
+| `max`         | `max`          | `number \| null`            | `null`    |
+| `noGrid`      | `no-grid`      | `boolean`                   | `false`   |
+| `noAxis`      | `no-axis`      | `boolean`                   | `false`   |
+| `showTable`   | `show-table`   | `boolean`                   | `false`   |
+| `centerLabel` | `center-label` | `string`                    | `'Total'` |
+| `totalLabel`  | `total-label`  | `string`                    | `'Total'` |
+| `label`       | `label`        | `string`                    | `''`      |
+
+```ts
+type KtChartType =
+  'line' | 'area' | 'bar' | 'scatter' | 'bubble' | 'pie' | 'doughnut' | 'polar-area' | 'radar';
+
+interface KtSeries {
+  name: string;
+  values?: number[]; // one per label
+  points?: KtPoint[]; // scatter and bubble
+  color?: string; // pins the hue
+  type?: 'line' | 'area' | 'bar'; // mixed charts
+}
+
+interface KtPoint {
+  x: number;
+  y: number;
+  r?: number; // bubble size, as a value
+  label?: string;
+}
+```
+
+| Event              | Detail                                                                                               |
+| ------------------ | ---------------------------------------------------------------------------------------------------- |
+| `kt-point-hover`   | `{ index, series }` — `index` −1 when nothing is active; `series` −1 unless scatter or bubble        |
+| `kt-series-toggle` | `{ series, hidden }` — a series index, or a slice index for pie, doughnut and polar area. Cancelable |
+
+| Part     | Description    |
+| -------- | -------------- |
+| `svg`    | The plot       |
+| `legend` | The legend     |
+| `table`  | The data table |

package/dist/docs/kt-checkbox.md

@@ -0,0 +1,65 @@
+# `<kt-checkbox>`
+
+A checkbox: a choice that applies when the form is submitted.
+
+```html
+<kt-checkbox name="updates" checked>Send me product updates</kt-checkbox>
+<kt-checkbox name="terms" required>I accept the terms</kt-checkbox>
+<kt-checkbox indeterminate>Select all</kt-checkbox>
+<kt-checkbox disabled>Unavailable</kt-checkbox>
+```
+
+## Checkbox, toggle or radio
+
+- **Checkbox** — the choice takes effect when the form is submitted, or it is
+  one of several independent choices in a list.
+- **`<kt-toggle>`** — a setting that applies the moment it is flipped.
+- **`<kt-radio-group>`** — exactly one choice among a few.
+
+## Built on the native input
+
+Under the drawn box sits a real `<input type="checkbox">`, invisible but
+covering it. The keyboard (Space), the click on the label, the indeterminate
+state and what a screen reader announces all come from the platform, so they
+behave exactly like every other checkbox the user has met.
+
+The slotted text is the label: clicking it toggles the box, and it names the
+checkbox for assistive technology. With nothing slotted — a checkbox in a table
+row — give it a `label` instead.
+
+## Indeterminate
+
+`indeterminate` draws a dash: neither checked nor unchecked, for a "select all"
+over a partial selection. It is display state only, as on a native checkbox —
+the first click clears it and checks the box.
+
+## In a form
+
+A form control, like a native checkbox: it submits its `value` (default `on`)
+under `name` when checked, and **nothing** when unchecked. `required` blocks
+submission until it is checked, `error` shows a message and puts it in its
+error state, and `form.reset()` puts back the initial state.
+
+## API
+
+| Property        | Attribute       | Type                             | Default    |
+| --------------- | --------------- | -------------------------------- | ---------- |
+| `checked`       | `checked`       | `boolean`                        | `false`    |
+| `indeterminate` | `indeterminate` | `boolean`                        | `false`    |
+| `disabled`      | `disabled`      | `boolean`                        | `false`    |
+| `required`      | `required`      | `boolean`                        | `false`    |
+| `size`          | `size`          | `'small' \| 'medium' \| 'large'` | `'medium'` |
+| `name`          | `name`          | `string`                         | `''`       |
+| `value`         | `value`         | `string`                         | `'on'`     |
+| `label`         | `label`         | `string`                         | `''`       |
+| `error`         | `error`         | `string`                         | `''`       |
+
+| Event       | Detail                 |
+| ----------- | ---------------------- |
+| `kt-change` | `{ checked: boolean }` |
+
+| Part    | Description                 |
+| ------- | --------------------------- |
+| `base`  | The `<label>` around it all |
+| `input` | The native checkbox         |
+| `box`   | The drawn box               |

package/dist/docs/kt-code.md

@@ -0,0 +1,88 @@
+# `<kt-code>`
+
+A block of code on a recessed surface, with its language and a copy button.
+
+```html
+<kt-code language="js" copy>const total = items.length;</kt-code>
+<kt-code>npm install kanto-ds</kt-code>
+```
+
+Set neither `language` nor `copy` and the header disappears entirely — a bare
+block for a one-line command.
+
+## Highlighting is yours
+
+The element owns the chrome — surface, language label, scrolling, copy — and
+nothing else. Slot in whatever markup a highlighter produced:
+
+```js
+import hljs from 'highlight.js/lib/core';
+
+block.innerHTML = hljs.highlight(source, { language: 'ts' }).value;
+```
+
+A design system that bundled a syntax highlighter would be choosing your bundle
+size and your language set for you. This one does not, which is also why
+`language` is purely a label: it says what the code is, it does not parse it.
+
+Style the highlighter's classes from the token layer and they follow the theme:
+
+```css
+.hljs-keyword {
+  color: var(--color-primary-base);
+}
+.hljs-string {
+  color: var(--color-success-base);
+}
+.hljs-comment {
+  color: var(--color-text-500);
+}
+```
+
+## Against `<kt-badge variant="code">`
+
+`<kt-badge variant="code">` is for a token inside a sentence — an identifier, a
+property name, a custom property. `<kt-code>` is for a block. Both draw on
+`--surface-code`, so they read as the same material at two scales.
+
+## Copying
+
+`copy` adds the button; pressing it writes `code` — the block's plain text, with
+the leading and trailing newlines a template literal leaves behind removed — and
+confirms for a second and a half.
+
+A clipboard that refuses, because permission was denied or the page is not on a
+secure origin, is swallowed: failing loudly over a convenience button helps
+nobody. `kt-copy` fires either way, so a caller that cares can tell.
+
+## Accessibility
+
+The `<pre>` is a tab stop, because it scrolls: a block of code that can only be
+scrolled with a pointer is unreadable without one. Give it a `label` when the
+language alone does not say what it is.
+
+## API
+
+| Property   | Attribute  | Type      | Default |
+| ---------- | ---------- | --------- | ------- |
+| `language` | `language` | `string`  | `''`    |
+| `copy`     | `copy`     | `boolean` | `false` |
+| `label`    | `label`    | `string`  | `''`    |
+
+| Getter | Returns                                        |
+| ------ | ---------------------------------------------- |
+| `code` | The block's plain text, trimmed of blank edges |
+
+| Event     | Detail             |
+| --------- | ------------------ |
+| `kt-copy` | `{ code: string }` |
+
+| Slot      | Description                                  |
+| --------- | -------------------------------------------- |
+| _default_ | The code — plain text, or highlighted markup |
+
+| Part     | Description           |
+| -------- | --------------------- |
+| `base`   | The container         |
+| `header` | The language row      |
+| `pre`    | The scrolling `<pre>` |

package/dist/docs/kt-collapsible.md

@@ -0,0 +1,50 @@
+# `<kt-collapsible>`
+
+A section that folds away.
+
+```html
+<kt-collapsible heading="Notifications" open>
+  <kt-toggle checked>Email me about mentions</kt-toggle>
+  <kt-toggle>Email me a weekly digest</kt-toggle>
+</kt-collapsible>
+```
+
+## Built on `<details>`
+
+Which buys three things for free:
+
+- It **works before the JavaScript loads** — the browser opens and closes it on
+  its own.
+- **Find-in-page opens it.** A browser will expand a closed `<details>` to
+  reveal a match inside it; a div with a click handler hides that text forever.
+- It needs **no ARIA of its own**. `<summary>` is already a button with the
+  right expanded state.
+
+The default disclosure triangle is replaced with a chevron that rotates, which
+is the only cosmetic liberty taken.
+
+## API
+
+| Property  | Attribute | Type      | Default |
+| --------- | --------- | --------- | ------- |
+| `open`    | `open`    | `boolean` | `false` |
+| `heading` | `heading` | `string`  | `''`    |
+| `plain`   | `plain`   | `boolean` | `false` |
+
+`plain` drops the bottom rule, for a collapsible that is not one of a stacked
+list.
+
+| Slot      | Description                      |
+| --------- | -------------------------------- |
+| _default_ | The contents                     |
+| `summary` | Replaces the `heading` attribute |
+
+| Event       | Detail              |
+| ----------- | ------------------- |
+| `kt-toggle` | `{ open: boolean }` |
+
+| Part      | Description        |
+| --------- | ------------------ |
+| `base`    | The `<details>`    |
+| `summary` | The clickable row  |
+| `content` | The revealed panel |

package/dist/docs/kt-confirm-dialog.md

@@ -0,0 +1,52 @@
+# `<kt-confirm-dialog>`
+
+A centred yes/no overlay for an action worth stopping to think about.
+
+```html
+<kt-confirm-dialog
+  heading="Delete this entity?"
+  message="This action cannot be undone."
+  confirm-label="Delete"
+></kt-confirm-dialog>
+```
+
+```js
+dialog.open = true;
+dialog.addEventListener('kt-confirm', () => remove(entity));
+dialog.addEventListener('kt-cancel', () => {});
+```
+
+## When
+
+Destructive or irreversible work only. Editing belongs in a
+`<kt-side-panel>`, which does not block the page behind it. A confirmation on
+something reversible teaches people to dismiss confirmations.
+
+## Defaults that fail safe
+
+`role="alertdialog"`, and **focus lands on Cancel**, not Confirm. A stray Enter
+meant for whatever was behind the dialog should not delete anything.
+
+Escape and a backdrop click both report `kt-cancel` — never `kt-confirm`.
+`variant="danger"` (the default) gives the confirm button the solid red
+treatment, the only place in Kanto that colour is used.
+
+## API
+
+| Property       | Attribute       | Type                    | Default           |
+| -------------- | --------------- | ----------------------- | ----------------- |
+| `open`         | `open`          | `boolean`               | `false`           |
+| `heading`      | `heading`       | `string`                | `'Are you sure?'` |
+| `message`      | `message`       | `string`                | `''`              |
+| `confirmLabel` | `confirm-label` | `string`                | `'Confirm'`       |
+| `cancelLabel`  | `cancel-label`  | `string`                | `'Cancel'`        |
+| `variant`      | `variant`       | `'danger' \| 'primary'` | `'danger'`        |
+
+| Event        | Description                            |
+| ------------ | -------------------------------------- |
+| `kt-confirm` | Confirm pressed                        |
+| `kt-cancel`  | Dismissed — button, Escape or backdrop |
+
+| Slot      | Description                               |
+| --------- | ----------------------------------------- |
+| _default_ | Extra content between message and buttons |

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

@@ -0,0 +1,97 @@
+# `<kt-date-input>`
+
+A date typed into its parts — day, month and year, each its own segment.
+
+```html
+<kt-date-input label="Date of birth" name="born" max="2026-12-31"></kt-date-input>
+<kt-date-input label="Due date" calendar value="2026-09-25"></kt-date-input>
+```
+
+Where [`<kt-date-picker>`](./kt-date-picker.md) leads with a
+calendar, this field leads with the keyboard: a date of birth, a date already
+on paper, a date in a table of a hundred rows. With `calendar` it gets a
+calendar too, a button away.
+
+## The segments
+
+The segments come in the order the reader's language writes a date, with its
+separator: `25/09/2026` in London, `09/25/2026` in New York, `25.09.2026` in
+Berlin. The locale is `locale` if set, else the page's `lang`, else the
+browser's language. An empty segment shows what it wants — `dd`, `mm`, `yyyy`,
+from `setStrings`.
+
+The focus moves on as each segment fills, so a date is eight keystrokes:
+`25092026`. A segment also moves on as soon as no other digit could follow — a
+`4` in the day, a `2` in the month — and on a typed `/`, `.`, `-` or space.
+
+| Key           | Does                                                         |
+| ------------- | ------------------------------------------------------------ |
+| digits        | fill the segment in focus                                    |
+| `↑` / `↓`     | step the segment, wrapping; a day never past its month's end |
+| `Home`/`End`  | the segment's first or last value                            |
+| `←` / `→`     | the segment before or after                                  |
+| `Backspace`   | erases a digit, then steps back to the segment before        |
+| `/` `.` `-` … | the next segment                                             |
+
+A year left at two digits is written out when the focus leaves it: `98` is
+1998, `30` is 2030. Everything else is turned away, so the field never holds
+text that is not a date in the making.
+
+## ISO in and out
+
+The value is ISO 8601 text, `2026-09-25`, and `null` until all three segments
+are filled. `kt-change` fires when the date becomes complete, changes, or stops
+being one — once per date, not per keystroke.
+
+A date that does not exist — the 31st of February — or one outside
+`min`/`max` puts the field in its error state, the message in a tooltip on the
+alert icon, as `<kt-input>` does. The value is `null` and the form sees a
+`badInput`.
+
+## The calendar option
+
+With `calendar`, a button at the end of the field opens a
+[`<kt-calendar>`](./kt-calendar.md) on the field's date, with the
+focus in it. Choosing a day fills in the segments and closes it; `Escape`, or a
+click outside, closes it and leaves the date as it was.
+
+## In a form
+
+A form control: it submits the ISO value under `name`, and nothing while the
+date is incomplete. `required` blocks submission while it is empty, `error`
+shows a message, and `form.reset()` puts back the initial value.
+
+## API
+
+| Property   | Attribute  | Type                             | Default            |
+| ---------- | ---------- | -------------------------------- | ------------------ |
+| `value`    | `value`    | `string \| null`                 | `null`             |
+| `calendar` | `calendar` | `boolean`                        | `false`            |
+| `min`      | `min`      | `string`                         | `''`               |
+| `max`      | `max`      | `string`                         | `''`               |
+| `name`     | `name`     | `string`                         | `''`               |
+| `label`    | `label`    | `string`                         | `''`               |
+| `locale`   | `locale`   | `string`                         | page, then browser |
+| `size`     | `size`     | `'small' \| 'medium' \| 'large'` | `'medium'`         |
+| `disabled` | `disabled` | `boolean`                        | `false`            |
+| `required` | `required` | `boolean`                        | `false`            |
+| `error`    | `error`    | `string`                         | `''`               |
+
+| Event       | Detail                                           |
+| ----------- | ------------------------------------------------ |
+| `kt-change` | `{ value: string \| null }` — ISO date or `null` |
+
+| Part      | Description                          |
+| --------- | ------------------------------------ |
+| `field`   | The field                            |
+| `segment` | A day, month or year segment         |
+| `trigger` | The calendar button, with `calendar` |
+| `panel`   | The calendar popup, with `calendar`  |
+
+## Accessibility
+
+The field is a `group` named by `label`. Each segment is a `spinbutton` named
+"Day", "Month" or "Year", with its range and value, so a screen reader
+announces "Month, 09" and `↑`/`↓` work as it expects. `Tab` walks the segments,
+then the calendar button. On a phone, the segments bring up the numeric
+keypad.