@lo-tek/interfaces 0.0.0 → 0.37.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 August Søberg-Klyver
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,130 @@
 # @lo-tek/interfaces
 
-Placeholder that reserves the name. The first real release is 0.37.0.
+A framework-agnostic design system for the web: tokens, CSS components and web components. Everything is built on things the browser already understands, so the same components work in plain HTML, React, Astro and [Datastar](https://data-star.dev).
+
+> LO-TEK is pre-1.0. A minor version can contain breaking changes, and they are listed under "Breaking" (in versions up to 0.36.0, "Brytende") in the [changelog](https://github.com/MarkusAugust/lo-tek/blob/master/interfaces/CHANGELOG.md).
+
+The full documentation, with component pages, tokens, patterns and examples for four environments, is at **[lo-tek.sobernetics.no](https://lo-tek.sobernetics.no/)**.
+
+**Coding agents** find the rules at [lo-tek.sobernetics.no/llms.txt](https://lo-tek.sobernetics.no/llms.txt), with one rulebook per environment, described under [Coding agents](https://lo-tek.sobernetics.no/coding-agents/). The same rulebooks ship in the package, in `node_modules/@lo-tek/interfaces/agent/`.
+
+## Installation
+
+```bash
+npm install @lo-tek/interfaces
+```
+
+The package has no dependencies. The web components are plain `HTMLElement` classes, and nothing is registered on import alone, so you only pay for what you actually call.
+
+## CSS components
+
+A class and a few `data-*` attributes, no JavaScript. `tokens.css` defines the variables everything else builds on, so it has to be loaded. It comes first out of habit; the order makes no difference.
+
+With a build step you import only the stylesheets you use, so a page with only buttons does not load CSS for a dialog:
+
+```js
+import "@lo-tek/interfaces/tokens.css"
+import "@lo-tek/interfaces/button.css"
+```
+
+Without a build step you link the combined file, which has everything in it:
+
+```html
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@lo-tek/interfaces/dist/lotek.css" />
+```
+
+The markup is the same whichever of the two you chose:
+
+```html
+<button class="lt-button">Submit application</button>
+<button class="lt-button" data-variant="secondary">Save draft</button>
+```
+
+## The attributes as functions
+
+`lt` gives the same classes and attributes with completion and type checking in the editor. Each component takes one object of options and returns the attributes:
+
+```js
+import { lt } from "@lo-tek/interfaces"
+
+lt.button({ variant: "secondary" })
+// { class: "lt-button", "data-variant": "secondary" }
+```
+
+In React you import from `@lo-tek/interfaces/react`, which gives `className` and `htmlFor` instead of the HTML names:
+
+```jsx
+import { lt } from "@lo-tek/interfaces/react"
+
+<button {...lt.button({ variant: "secondary" })}>Save draft</button>
+```
+
+## Web components
+
+Nothing is registered on import alone. You call `defineLt*` yourself, so you decide when the element exists:
+
+```js
+import { defineLtToast } from "@lo-tek/interfaces/toast"
+import "@lo-tek/interfaces/tokens.css"
+import "@lo-tek/interfaces/toast.css"
+
+defineLtToast()
+```
+
+```html
+<lt-toast class="lt-toast" role="status" aria-live="polite" aria-atomic="false"
+          aria-label="Notifications" data-ignore-morph></lt-toast>
+```
+
+Every `defineLt*` also takes a tag name of your choice, such as `defineLtToast("app-toast")`, and repeated calls are harmless, also alongside `defineLt()`. The stylesheets are still written for the `lt-*` names: an `<lt-field>` registered as `<my-field>` still wires the label to the field, but the `display` rule on the element name does not follow, `<lt-tabs>` and `<lt-suggestion>` do not hide their content before registration, and `<lt-dialog>` no longer positions a dialog that is open before it is modal. The four that set their class themselves, `<lt-toast>`, `<lt-session-timeout>`, `<lt-connection-status>` and `<lt-error-summary>`, look the same under another name.
+
+## The server writes the markup
+
+LO-TEK is built for apps where the HTML comes from the server, whether that is TanStack Start, React Server Components or Datastar. No web component creates nodes in markup the server has sent, because the surrounding framework would tear them out again on the next update.
+
+The builder functions in `lt` give the markup, the components give the behaviour, and the two do not overlap:
+
+```js
+import { lt } from "@lo-tek/interfaces"
+
+lt.errorSummary({ count: 2, id: "errors" })
+// { host: { class: "lt-error-summary", role: "alert", tabindex: "-1", id: "errors" },
+//   title:     { class: "lt-error-summary__title" } }
+```
+
+`id` is required in `lt.field()`, `lt.suggestion()`, `lt.tabs()` and `lt.popover()`, and `titleId` in `lt.dialog()`. `lt.tabs()` and `lt.suggestion()` also take `keys`, one key from the data per tab or option, and `lt.tabs()` requires `label`, the name of the tab list. The reason is hydration: if the function creates the id itself, the server and the browser each create their own, and the wiring between the parts is broken until React has corrected it. In React it comes from `useId()`. In `lt.errorSummary()` it is optional, since it only names the box so that something else can point to it.
+
+The full reasoning, with the tests behind it, is on [Markup and behaviour](https://lo-tek.sobernetics.no/markup-and-behaviour/).
+
+## Your own colour theme
+
+The CLI creates a complete theme from your brand colours, with the contrast requirements computed in OKLCH:
+
+```bash
+npx @lo-tek/interfaces theme --accent=#7c3aed --danger=#b3261e \
+  --success=#2b6940 --warning=#8a5a00 --neutral=#1a1a1a --out=theme.css
+```
+
+If customising through CSS is not enough, `takeover` copies the source code of one component into your project, with the imports rewritten:
+
+```bash
+npx @lo-tek/interfaces takeover button --out=src/ui
+```
+
+`npx @lo-tek/interfaces --help` shows the rest.
+
+## Customising
+
+The components are in `@layer lotek`, so your own rules win without `!important`. If you embed a component in a page you do not control, `data-lt-boundary` on the root element gives LO-TEK its styles back where the host's unlayered CSS would otherwise take them; see Customising in the documentation. Shape and size are read from `--lt-*` variables with the token value as fallback:
+
+```css
+.lt-button {
+  --lt-button-padding: var(--lt-spacing-3) var(--lt-spacing-6);
+}
+```
+
+Tailwind is optional. The theme is a plain CSS file, `@lo-tek/interfaces/tailwind.css`, so the package has no dependency on Tailwind and cannot conflict with your version.
+
+## Licence
+
+MIT

package/agent/astro.md

@@ -0,0 +1,400 @@
+# LO-TEK in Astro
+
+The rulebook for LO-TEK in an Astro project.
+
+An `.astro` file is HTML with frontmatter above it. The stylesheets are
+imported there, and the builder functions are used directly in the template,
+since Astro supports spreading like JSX. What is particular is that all of
+this runs at build time: out comes plain HTML, and `lt` is gone once the page
+is built. The only JavaScript the browser gets from the package is the
+registration of the web components you use, in a `<script>`.
+
+This is @lo-tek/interfaces 0.37.0. The file is generated by the package and
+follows its version, so it can never say anything other than the code next to
+it.
+
+## Short version
+
+1. **Import the stylesheets in the frontmatter**, `tokens.css` first. Without
+   them, the components look unstyled. The answer is then to add the import,
+   never to write your own CSS to make them look right.
+2. **Use only the classes and elements in the tables below.** `lt-modal`,
+   `lt-datepicker` and `data-variant="outlined"` exist in other design
+   systems, not in LO-TEK. If you are unsure whether something exists, it is
+   listed here or it does not exist.
+3. **No hard-coded colours or pixels.** `var(--lt-color-…)` and
+   `var(--lt-spacing-…)`.
+4. **`defineLt*()` belongs in a `<script>` in the template, never in the
+   frontmatter:** the frontmatter runs at build time, or on the server when a
+   page is rendered on demand, and `customElements` exists in neither. And a
+   boolean attribute is true as long as it is there.
+5. **Run the check on what you have written:**
+   `npx @lo-tek/interfaces check src/pages/*.astro`. It knows every class,
+   every element, every attribute and every allowed value, prints
+   `file:line:column: error: message`, or `warning:`, and exits with an error
+   code if it finds anything. It reads the file as text, so it does not see
+   what a spread such as `{...lt.button()}` writes; the check on the running
+   page below does. With the app running, also check every page you have
+   changed: `npx @lo-tek/interfaces check http://localhost:4321/page`. That
+   also requires every `for` and `aria-describedby` to point to an id that
+   exists, and every field to have a label. You are done when both answer "The
+   markup matches LO-TEK".
+
+## 1. The stylesheets
+
+`tokens.css` defines all the variables, and all the other stylesheets build on
+it. It must be loaded, and comes first out of habit: the order between it and
+the others does not matter. The imports go in the frontmatter:
+
+```astro
+---
+import "@lo-tek/interfaces/tokens.css"
+import "@lo-tek/interfaces/button.css"
+import "@lo-tek/interfaces/badge.css"
+---
+```
+
+The name of each stylesheet is in the tables below. If you have a layout
+component, `tokens.css` belongs there, once for the whole page.
+
+## 2. What exists
+
+35 CSS components and 9 web components, and this is the whole list. The
+classes are `lt-` + kebab-case. Variants are always `data-*` attributes, never
+classes of their own: `data-variant="secondary"`, not `lt-button--secondary`.
+The default variant has no attribute.
+
+### CSS components (no JavaScript)
+
+| Class | Stylesheet | Attributes |
+| --- | --- | --- |
+| `lt-accordion`<br>`lt-accordion__content` | `@lo-tek/interfaces/accordion.css` | `data-variant`: plain |
+| `lt-alert`<br>`lt-alert__title` | `@lo-tek/interfaces/alert.css` | `data-color`: info, success, warning, danger |
+| `lt-avatar`<br>`lt-avatar-stack` | `@lo-tek/interfaces/avatar.css` | `data-variant`: square<br>`data-size`: small, large |
+| `lt-badge` | `@lo-tek/interfaces/badge.css` | `data-color`: success, warning, danger, neutral |
+| `lt-breadcrumbs` | `@lo-tek/interfaces/breadcrumbs.css` | none |
+| `lt-button` | `@lo-tek/interfaces/button.css` | `data-variant`: secondary, ghost, danger |
+| `lt-card`<br>`lt-card__title` | `@lo-tek/interfaces/card.css` | `data-variant`: filled<br>`data-interactive` (flag) |
+| `lt-checkbox`<br>`lt-checkbox-row` | `@lo-tek/interfaces/checkbox.css` | `data-state`: invalid, success |
+| `lt-divider` | `@lo-tek/interfaces/divider.css` | `data-variant`: subtle, strong |
+| `lt-error-text` | `@lo-tek/interfaces/error-text.css` | `data-variant`: warning |
+| `lt-fieldset`<br>`lt-legend` | `@lo-tek/interfaces/fieldset.css` | `data-state`: invalid, success<br>`data-required`: symbol, text<br>`data-optional` (flag) |
+| `lt-file-upload`<br>`lt-file-upload-list` | `@lo-tek/interfaces/file-upload.css` | `data-state`: invalid, success |
+| `lt-heading` | `@lo-tek/interfaces/heading.css` | `data-size`: xs, s, m, xl, mega |
+| `lt-help-text` | `@lo-tek/interfaces/help-text.css` | `data-variant`: strong, success, warning |
+| `lt-icon` | `@lo-tek/interfaces/icon.css` | none |
+| `lt-input` | `@lo-tek/interfaces/input.css` | `data-state`: invalid, success<br>`data-variant`: date, datetime-local, time |
+| `lt-label` | `@lo-tek/interfaces/label.css` | `data-required`: symbol, text<br>`data-optional` (flag) |
+| `lt-link` | `@lo-tek/interfaces/link.css` | none |
+| `lt-list` | `@lo-tek/interfaces/list.css` | `data-variant`: plain, divided |
+| `lt-pagination`<br>`lt-pagination__gap` | `@lo-tek/interfaces/pagination.css` | none |
+| `lt-paragraph` | `@lo-tek/interfaces/paragraph.css` | `data-variant`: lead<br>`data-size`: small, large |
+| `lt-progress` | `@lo-tek/interfaces/progress.css` | `data-color`: success, warning, danger |
+| `lt-radio`<br>`lt-radio-row` | `@lo-tek/interfaces/radio.css` | `data-state`: invalid, success |
+| `lt-search`<br>`lt-search-row` | `@lo-tek/interfaces/search.css` | `data-state`: invalid, success |
+| `lt-select` | `@lo-tek/interfaces/select.css` | `data-state`: invalid, success<br>`data-picker`: styled |
+| `lt-skeleton` | `@lo-tek/interfaces/skeleton.css` | `data-variant`: text, circle |
+| `lt-skip-link` | `@lo-tek/interfaces/skip-link.css` | none |
+| `lt-spinner` | `@lo-tek/interfaces/spinner.css` | `data-size`: small, large |
+| `lt-sr-only` | `@lo-tek/interfaces/sr-only.css` | none |
+| `lt-switch`<br>`lt-switch-row` | `@lo-tek/interfaces/switch.css` | none |
+| `lt-table`<br>`lt-table__sort`<br>`lt-table-scroll` | `@lo-tek/interfaces/table.css` | `data-variant`: striped<br>`data-hoverable` (flag) |
+| `lt-tag` | `@lo-tek/interfaces/tag.css` | `data-variant`: filled<br>`data-selectable` (flag) |
+| `lt-textarea` | `@lo-tek/interfaces/textarea.css` | `data-state`: invalid, success |
+| `lt-toggle-group`<br>`lt-toggle-group__option` | `@lo-tek/interfaces/toggle-group.css` | none |
+| `lt-tooltip`<br>`lt-tooltip__bubble` | `@lo-tek/interfaces/tooltip.css` | none |
+
+There is also `lt-theme-control`, a class on a radio button that lets the user
+choose a theme. It is in `tokens.css`, and is described under Tokens.
+
+## 3. Tokens
+
+One layer. A colour is a cell in a matrix of **family**, that is, what it
+means, and **role**, that is, what it does, and the name is
+`--lt-color-<family>-<role>`. Every family has every role, so
+`--lt-color-danger-border` and `--lt-color-success-border` both exist. The
+roles are the same whatever the family: `surface` is a tinted surface, `fill`
+a filled one, `content` the text on top of `fill`, `border` a border, and
+`text` the family's colour as text. Border and text each have a weaker and a
+stronger step next to them.
+
+```
+Families: `accent`, `visited`, `brand1`, `brand2`, `brand3`, `neutral`, `danger`, `warning`, `success`.
+
+Roles: `surface`, `border-subtle`, `border`, `border-strong`, `fill`, `text`, `text-strong`, `text-subtle`, `content`.
+
+Outside the matrix: `--lt-color-disabled-surface`, `--lt-color-disabled-text`, `--lt-color-neutral-canvas`, `--lt-color-neutral-raised`, `--lt-color-overlay`, `--lt-focus-ring`, `--lt-icon-calendar`, `--lt-icon-check`, `--lt-icon-clock`, `--lt-icon-dash`, `--lt-icon-search`, `--lt-shadow-overlay`.
+```
+
+Spacing: `--lt-spacing-0-5`, `--lt-spacing-1`, `--lt-spacing-10`,
+`--lt-spacing-12`, `--lt-spacing-16`, `--lt-spacing-2`, `--lt-spacing-3`,
+`--lt-spacing-4`, `--lt-spacing-5`, `--lt-spacing-6`, `--lt-spacing-7`,
+`--lt-spacing-8`, `--lt-spacing-px`.
+
+Font: `--lt-font-size-l`, `--lt-font-size-m`, `--lt-font-size-mega`,
+`--lt-font-size-reference`, `--lt-font-size-s`, `--lt-font-size-xl`,
+`--lt-font-size-xs`, `--lt-font-size-xxl`, `--lt-font-size-xxs`,
+`--lt-font-weight-bold`, `--lt-font-weight-medium`,
+`--lt-font-weight-regular`, `--lt-font-weight-semibold`.
+
+Line height: `--lt-line-height-article`, `--lt-line-height-compact`,
+`--lt-line-height-default`, `--lt-line-height-heading`.
+
+`disabled` and `neutral` are not the same. `disabled` is for controls that are
+turned off, and is exempt from the contrast requirement in WCAG 1.4.3.
+`neutral` is for subdued information the user actually has to read or press,
+and holds 4.5:1. Never use the `disabled` colours to subdue something that is
+meant to be read.
+
+### Light and dark
+
+Without you doing anything, the colours follow the device's setting. A page
+that wants to decide for itself sets `data-theme="light"` or
+`data-theme="dark"` on `<html>`.
+
+The attribute is a **theme boundary** and works on any element, not only on
+the root. One theme can sit inside another, both ways.
+
+This is what an embedded component should use. When you put LO-TEK into a page
+you do not control, set the attribute on the component's own root element:
+
+```html
+<div data-theme="light">
+  <button class="lt-button">Save</button>
+</div>
+```
+
+The component is then light whatever the device is set to, and the host is
+left alone.
+
+**The host's CSS stops at the boundary.** The host often has rules without a
+layer, such as `button { background: none; border: none }` or a normalize, and
+they beat `@layer lotek`. In that case, set `data-lt-boundary` on the same
+root element:
+
+```html
+<div data-lt-boundary data-theme="light">
+  <button class="lt-button">Save</button>
+</div>
+```
+
+Below the root element the browser then ignores the host's CSS without a
+layer, unless a rule of the host's wins on specificity as described below, and
+LO-TEK's layer applies again. The rule is in `lotek.css` and in
+`@lo-tek/interfaces/boundary.css`. Fonts and other inherited properties still
+come from the host, and the `--lt-*` variables work. Three things follow from
+it:
+
+- Your own CSS inside the boundary must be in a layer after `lotek`. CSS
+  without a layer disappears there in the same way as the host's.
+- Elements without a LO-TEK class lose the host's CSS without a layer. A layer
+  the host has declared before `lotek`, such as Tailwind's Preflight in
+  `base`, still applies where LO-TEK sets nothing.
+- The boundary has the specificity (0,2,0). A rule from the host with the same
+  specificity wins if it is loaded after the boundary, and one with more
+  always wins. So do `!important` and layers the host has declared after
+  `lotek`.
+
+LO-TEK sets `color-scheme` only where someone has chosen a theme: on
+`[data-theme="light"]`, on `[data-theme="dark"]` and on the options of the
+theme picker below. Bare `:root` never gets it. The property controls the
+browser's own surfaces, that is, scrollbars, dropdowns and calendar panels,
+and it is inherited. A child can opt out with `color-scheme: normal`, but that
+is a counter-rule the host never asked to have to write: with the value on the
+root, it applied to the whole document, including where the package is only a
+guest. If the whole page should follow the system, write
+`color-scheme: light dark` on `<html>` yourself, in the same way as you set
+the layer order yourself.
+
+### Letting the user choose a theme
+
+`lt-theme-control` on a radio button makes `value` a theme choice. It is plain
+CSS, without a line of JavaScript:
+
+```html
+<fieldset class="lt-toggle-group">
+  <legend class="lt-sr-only">Theme</legend>
+  <label class="lt-toggle-group__option">
+    <input class="lt-theme-control" type="radio" name="theme"
+           value="auto" checked /> Follow the system
+  </label>
+  <label class="lt-toggle-group__option">
+    <input class="lt-theme-control" type="radio" name="theme"
+           value="light" /> Light
+  </label>
+  <label class="lt-toggle-group__option">
+    <input class="lt-theme-control" type="radio" name="theme"
+           value="dark" /> Dark
+  </label>
+</fieldset>
+```
+
+The choice controls two things. LO-TEK's colours come from the tokens, and the
+browser's **own** surfaces from `color-scheme`: `light` gives `light`, `dark`
+gives `dark`, and `auto` gives `light dark`. `light dark` is not a theme, but
+the statement that the page works in both, so the browser can choose by the
+system.
+
+"Follow the system" has no theme block, and that is on purpose: a value
+without a block matches nothing, and then the media query applies again.
+
+Do not write `color-scheme` yourself when the picker is in use. Such a rule
+outside a layer beats `@layer lotek` and locks the browser's surfaces to the
+system while the user has chosen something else.
+
+`light` and `dark` win over `data-theme` on `<html>`, so the server can send
+the stored choice while a click still takes effect before the response is
+back. `auto` does not: it means "no override from me", so if the server has
+written `data-theme`, the server's value stands. For "follow the system" to
+work at once, whatever stores the choice must also remove the attribute.
+
+Two things it does not do. It **stores nothing**: submit the group in a form
+and store the choice in a cookie the server reads, or in `localStorage`. And
+it must be in the **same tree as `<html>`**, since `:has()` does not see out
+of its own tree; a control inside a shadow root does not set the theme on the
+page.
+
+## 4. Web components
+
+Three rules apply to all of them:
+
+1. **`defineLt*()` runs once** in a `<script>` in the template. Astro bundles
+   `<script>` tags and runs them on the client. The import has no side effect
+   on its own; it is the `define` call that registers the element.
+2. **Boolean attributes are true as long as they are present.**
+   `hidden="false"`, `disabled="false"` and `open="false"` turn it *on*. To
+   turn any of them off, remove the attribute entirely.
+3. **You write the markup, the component adds the behaviour.** `<lt-field>`
+   does not create your label or your control. You write `for` on the label
+   and `id` on the control, or wrap the control in a `<label>`, so the field
+   has a name without JavaScript too. The component wires the help text and
+   the error text with `aria-describedby` and `aria-invalid`, and never writes
+   an id on the control: an id the server did not send makes an update from
+   the server replace the field, with the focus and what the user has typed.
+   The field is invalid when the error text is there without `hidden`.
+
+| Element | Category | Stylesheet | Registration | Attributes | Events | Classes inside |
+| --- | --- | --- | --- | --- | --- | --- |
+| `<lt-field>` | frame | `@lo-tek/interfaces/field.css` | `defineLtField()` from `@lo-tek/interfaces/field` | `disabled` (flag)<br>`optional` (flag)<br>`described-by` (text) | none | none |
+| `<lt-tabs>` | frame | `@lo-tek/interfaces/tabs.css` | `defineLtTabs()` from `@lo-tek/interfaces/tabs` | `server-controlled` (flag)<br>`activation`: manual, automatic | `tab-select` (index) | `lt-tabs__list`<br>`lt-tabs__panel` |
+| `<lt-error-summary>` | frame | `@lo-tek/interfaces/error-summary.css` | `defineLtErrorSummary()` from `@lo-tek/interfaces/error-summary` | `data-autofocus`: false, true<br>`hidden` (flag) | none | `lt-error-summary`<br>`lt-error-summary__title` |
+| `<lt-popover>` | frame | `@lo-tek/interfaces/popover.css` | `defineLtPopover()` from `@lo-tek/interfaces/popover` | `open` (flag)<br>`placement`: bottom-start, bottom-end, top-start, top-end<br>`server-controlled` (flag) | `popover-toggle` (open) | `lt-popover` |
+| `<lt-suggestion>` | frame | `@lo-tek/interfaces/suggestion.css` | `defineLtSuggestion()` from `@lo-tek/interfaces/suggestion` | `prefiltered` (flag)<br>`count-none` (text)<br>`count-zero` (text)<br>`count-one` (text)<br>`count-two` (text)<br>`count-few` (text)<br>`count-many` (text)<br>`count-other` (text)<br>`server-controlled` (flag) | `suggestion-select` (value, label) | `lt-suggestion__list`<br>`lt-suggestion__option`<br>`lt-suggestion__value`<br>`lt-suggestion__empty` |
+| `<lt-dialog>` | frame | `@lo-tek/interfaces/dialog.css` | `defineLtDialog()` from `@lo-tek/interfaces/dialog` | `open` (flag)<br>`server-controlled` (flag) | `dialog-toggle` (open, returnValue) | `lt-dialog` (`data-color`: brand, info, success, warning, danger)<br>`lt-dialog__body`<br>`lt-dialog__title`<br>`lt-dialog__footer`<br>`lt-dialog__header`<br>`lt-dialog__subtitle` |
+| `<lt-toast>` | standalone | `@lo-tek/interfaces/toast.css` | `defineLtToast()` from `@lo-tek/interfaces/toast` | `duration` (number)<br>`label` (text)<br>`close-label` (text) | `toast-dismiss` | `lt-toast`<br>`lt-toast__message`<br>`lt-toast__close` |
+| `<lt-session-timeout>` | frame | `@lo-tek/interfaces/session-timeout.css` | `defineLtSessionTimeout()` from `@lo-tek/interfaces/session-timeout` | `warn-at` (number)<br>`expires-at` (number)<br>`activity-interval` (number) | `session-warn`<br>`session-extend`<br>`session-logout`<br>`session-expired`<br>`session-activity` | `lt-session-timeout`<br>`lt-session-timeout__dialog`<br>`lt-session-timeout__title`<br>`lt-session-timeout__text`<br>`lt-session-timeout__count`<br>`lt-session-timeout__actions` |
+| `<lt-connection-status>` | standalone | `@lo-tek/interfaces/connection-status.css` | `defineLtConnectionStatus()` from `@lo-tek/interfaces/connection-status` | `offline-text` (text)<br>`online-text` (text) | `connection-lost`<br>`connection-restored` | `lt-connection-status`<br>`lt-connection-status__bar` |
+
+None of them uses shadow DOM. The content is in plain DOM, so `querySelector`,
+`FormData` and ordinary CSS work straight into it.
+
+## 5. The builder functions in the template
+
+```astro
+---
+import { lt } from "@lo-tek/interfaces"
+import "@lo-tek/interfaces/tokens.css"
+import "@lo-tek/interfaces/button.css"
+import "@lo-tek/interfaces/badge.css"
+---
+
+<button {...lt.button({ variant: "secondary" })}>Save draft</button>
+<span {...lt.badge({ color: "success" })}>Approved</span>
+```
+
+Runs at build time. Out comes plain HTML:
+
+```html
+<button class="lt-button" data-variant="secondary">Save draft</button>
+<span class="lt-badge" data-color="success">Approved</span>
+```
+
+`lt` is imported from the main entry, which gives `class` and `for`. The 46
+builder functions:
+
+`lt.accordion()`, `lt.alert()`, `lt.avatar()`, `lt.badge()`,
+`lt.breadcrumbs()`, `lt.button()`, `lt.card()`, `lt.checkbox()`,
+`lt.connectionStatus()`, `lt.dialog()`, `lt.divider()`, `lt.errorSummary()`,
+`lt.errorText()`, `lt.field()`, `lt.fieldset()`, `lt.fileUpload()`,
+`lt.heading()`, `lt.helpText()`, `lt.icon()`, `lt.input()`, `lt.label()`,
+`lt.legend()`, `lt.link()`, `lt.list()`, `lt.pagination()`, `lt.paragraph()`,
+`lt.popover()`, `lt.progress()`, `lt.radio()`, `lt.search()`, `lt.select()`,
+`lt.sessionTimeout()`, `lt.skeleton()`, `lt.skipLink()`, `lt.spinner()`,
+`lt.srOnly()`, `lt.suggestion()`, `lt.switch()`, `lt.table()`,
+`lt.tableSort()`, `lt.tabs()`, `lt.tag()`, `lt.textarea()`, `lt.toast()`,
+`lt.toggleGroup()`, `lt.tooltip()`
+
+## 6. Fields without JavaScript
+
+`lt.field()` works out the wiring between label, control, help text and error
+text in the frontmatter, so that too becomes static HTML:
+
+```astro
+---
+import { lt } from "@lo-tek/interfaces"
+import "@lo-tek/interfaces/tokens.css"
+import "@lo-tek/interfaces/field.css"
+
+const email = lt.field({ id: "email", required: "symbol", help: true, error: true })
+---
+
+<label {...email.label}>Email address</label>
+<input {...lt.input({ type: "email" })} {...email.control} name="email" required />
+<p {...lt.helpText()} {...email.help}>We will send the receipt here.</p>
+<p {...lt.errorText()} {...email.error}>Enter a valid address.</p>
+```
+
+No `<lt-field>`, no runtime.
+
+## 7. Web components in Astro
+
+If the field should be able to become invalid while the user is in it, the
+component has to be registered. It wires the error text to the field when it
+shows:
+
+```astro
+---
+import "@lo-tek/interfaces/tokens.css"
+import "@lo-tek/interfaces/field.css"
+---
+
+<lt-field>
+  <label class="lt-label" for="name" data-required="symbol">Full name</label>
+  <input class="lt-input" id="name" type="text" name="name" required />
+  <p class="lt-error-text" hidden>Enter your name.</p>
+</lt-field>
+
+<script>
+  import { defineLtField } from "@lo-tek/interfaces/field"
+  defineLtField()
+</script>
+```
+
+`customElements` exists only in the browser, so the registration cannot be in
+the frontmatter. A `<script>` in the template is all it takes: the components
+are ordinary web components, and need neither an Astro integration nor a
+`client:` directive.
+
+## Known pitfalls
+
+| Symptom | Cause |
+| --- | --- |
+| The styles are missing | `tokens.css` is not loaded. The order between it and the component's stylesheet does not matter |
+| An `<lt-toast>` or `<lt-connection-status>` shows nothing, an `<lt-session-timeout>` never warns, or another component does nothing | The `define` function has not run. `<lt-toast>` and `<lt-connection-status>` create their content themselves and are empty without it, and `<lt-session-timeout>` does not count the time. The markup in the others comes from you and is there regardless, with two exceptions until they are registered. `<lt-tabs>` shows one panel: of those the server left without `hidden`, the one the URL points to, otherwise the first, and under `server-controlled` always the first. `<lt-suggestion>` hides the list |
+| A component speaks English on a page in another language | The text in the markup comes from you, and is written with the app's own translation setup. The few default texts the package has are replaced with `label` and `close-label` on `<lt-toast>`, `offline-text` and `online-text` on `<lt-connection-status>`, `count-none`, `count-one` and `count-other` on `<lt-suggestion>`, and `--lt-label-required-text`, `--lt-label-optional-text` and `--lt-label-required-symbol` in CSS. Numbers and durations follow the nearest `lang`, usually the one on `<html>`. See https://lo-tek.sobernetics.no/translation/ |
+| The error text never shows, and the field counts as valid | `hidden="false"` is set on the error text, and it hides it all the same. The attribute must be removed, not set to `false` |
+| The component does nothing, and nothing says so | The registration is in the frontmatter, which never runs in the browser. It belongs in a `<script>` in the template |
+
+## When CSS is not enough
+
+The components are customised with tokens and `--lt-` variables. If that is
+not enough, `npx @lo-tek/interfaces takeover <component>` copies the source
+code of one component into `src/lotek/<component>/`, so the code is yours to
+change. The copy is TypeScript that imports from the package by name, so it
+needs a build step. It is renamed from `lt-` to `app-`, and a
+`lotek-manifest.json` next to it teaches the check the new names:
+`npx @lo-tek/interfaces check --manifest=src/lotek/<component>/lotek-manifest.json <files>`.
+A complete colour theme from your brand colours is made with
+`npx @lo-tek/interfaces theme`.
+
+All of this, with live examples: https://lo-tek.sobernetics.no/