@oneonefour/rkui 0.0.0-stage → 0.0.3

package/src/index.css

@@ -0,0 +1,64 @@
+/* rkui: the one stylesheet a site links. Order matters: tokens first, and the shared
+   interactive states last so they win over each component's rest styles. */
+
+@import './tokens/colors.css';
+@import './tokens/palettes.css';
+@import './tokens/space.css';
+@import './tokens/motion.css';
+@import './tokens/shadows.css';
+@import './tokens/fallback.css';
+@import './base/fonts.css';
+@import './base/type.css';
+@import './base/base.css';
+@import './tokens/shadow-color.css';
+
+@import './components/icon/icon.css';
+@import './components/button/button.css';
+@import './components/field/field.css';
+@import './components/input/input.css';
+@import './components/select/select.css';
+@import './components/checkbox/checkbox.css';
+@import './components/switch/switch.css';
+@import './components/range/range.css';
+@import './components/segmented/segmented.css';
+@import './components/theme-toggle/theme-toggle.css';
+@import './components/chip/chip.css';
+@import './components/card/card.css';
+@import './components/callout/callout.css';
+@import './components/sticky-note/sticky-note.css';
+@import './components/widget-frame/widget-frame.css';
+@import './components/file/file.css';
+@import './components/date-time/date-time.css';
+@import './components/search/search.css';
+@import './components/number/number.css';
+@import './components/tiles/tiles.css';
+@import './components/color-picker/color-picker.css';
+@import './components/ballot/ballot.css';
+@import './components/range-ticks/range-ticks.css';
+@import './components/dial/dial.css';
+@import './components/clock/clock.css';
+@import './components/code/code.css';
+@import './components/drawer/drawer.css';
+@import './components/badge/badge.css';
+@import './components/spinner/spinner.css';
+@import './components/progress/progress.css';
+@import './components/water/water.css';
+@import './components/spinner-dots/spinner-dots.css';
+@import './components/loader/loader.css';
+@import './components/tooltip/tooltip.css';
+@import './components/popup/popup.css';
+@import './components/alert/alert.css';
+@import './components/breadcrumbs/breadcrumbs.css';
+@import './components/folder/folder.css';
+@import './components/pagination/pagination.css';
+@import './components/maths/maths.css';
+@import './components/figure/figure.css';
+@import './components/quote/quote.css';
+@import './components/overflow/overflow.css';
+@import './components/table/table.css';
+@import './components/sidebar/sidebar.css';
+@import './components/topbar/topbar.css';
+@import './components/header-band/header-band.css';
+@import './components/logo/logo.css';
+@import './components/motion/motion.css';
+@import './interactive.css';

package/src/interactive-enhance.js

@@ -0,0 +1,22 @@
+/* Safari drops :focus-visible from a radio that an arrow key moves focus to, so the focus band
+   on Folder, Segmented, Tiles and the other radio groups (interactive.css) disappears. This marks
+   such a radio with data-rkui-focus-visible, and the CSS shows the band for a marked radio that
+   has focus. Where the radio still matches :focus-visible, nothing is marked. */
+const MARK = 'data-rkui-focus-visible'
+
+document.addEventListener('keydown', () => {
+  const before = document.activeElement
+  // The arrow key moves focus after its keydown listeners have run.
+  requestAnimationFrame(() => {
+    const radio = document.activeElement
+    if (radio !== before && radio?.matches('input[type="radio"]:not(:focus-visible)')) {
+      radio.setAttribute(MARK, '')
+    }
+  })
+})
+
+// Each move of focus clears the mark, which the arrow key's frame then sets again. A blur
+// wouldn't do: Safari fires none when a focused radio is removed.
+document.addEventListener('focusin', () =>
+  document.querySelector(`[${MARK}]`)?.removeAttribute(MARK),
+)

package/src/interactive.css

@@ -0,0 +1,239 @@
+/* The states every interactive component shares: the pop, the flush press for unfilled buttons,
+   the pushed-in deck key and tile, the focus band and disabled. Loaded after the components, so
+   these win over their rest styles. The range slider's thumb can't join these lists
+   (pseudo-elements), so range.css repeats them. */
+
+/* Pop: hover lifts the element and grows its shadow; press sinks it into the shadow. A ballot row
+   pops its tile from anywhere on the row, and a drawer's handle its pull; :where() keeps that
+   below the tile's checked, focused and disabled states. */
+:is(
+  .rkui-button,
+  .rkui-chip,
+  .rkui-card--link,
+  .rkui-checkbox,
+  .rkui-radio,
+  .rkui-switch,
+  .rkui-tile,
+  .rkui-color-input,
+  .rkui-logo,
+  .rkui-drawer-pull
+) {
+  box-shadow: var(--rkui-shadow);
+  transition:
+    translate var(--rkui-duration-fast) ease,
+    box-shadow var(--rkui-duration-fast) ease;
+}
+
+@media (hover: hover) {
+  :is(
+    .rkui-button,
+    .rkui-chip,
+    .rkui-card--link,
+    .rkui-checkbox,
+    .rkui-radio,
+    .rkui-switch,
+    .rkui-tile,
+    .rkui-color-input,
+    .rkui-logo:where(a)
+  ):hover,
+  .rkui-segmented--deck label:hover,
+  .rkui-sidebar--deck .rkui-sidebar-link:where(:not([aria-current='page'])):hover,
+  :where(.rkui-ballot-option:hover) > .rkui-tile,
+  :where(.rkui-drawer-handle:hover) > .rkui-drawer-pull {
+    box-shadow: var(--rkui-shadow-hover);
+    translate: calc(-1 * var(--rkui-lift-offset-x)) calc(-1 * var(--rkui-lift-offset-y));
+  }
+}
+
+:is(
+  .rkui-button,
+  .rkui-chip,
+  .rkui-card--link,
+  .rkui-checkbox,
+  .rkui-radio,
+  .rkui-switch,
+  .rkui-tile,
+  .rkui-color-input,
+  .rkui-logo:where(a)
+):active,
+.rkui-segmented--deck label:active,
+.rkui-sidebar--deck .rkui-sidebar-link:where(:not([aria-current='page'])):active,
+:where(.rkui-ballot-option:active) > .rkui-tile,
+:where(.rkui-drawer-handle:active) > .rkui-drawer-pull {
+  box-shadow: var(--rkui-shadow-pressed);
+  translate: var(--rkui-press-offset-x) var(--rkui-press-offset-y);
+}
+
+/* A busy button keeps its resting shadow and doesn't pop, since it can't be used until it's done.
+   :where() keeps this below the focus band. */
+.rkui-button:where([aria-busy='true']) {
+  cursor: progress;
+}
+
+.rkui-button:where([aria-busy='true']):is(:hover, :active) {
+  box-shadow: var(--rkui-shadow);
+  translate: none;
+}
+
+/* Unfilled buttons sit flush. Pressed, the frame stays put and gets an inset shadow on the raised
+   background (so the dark inset shows in dark mode), and the label sinks: the padding shifts by
+   --rkui-press-offset, which moves the label without resizing. */
+.rkui-button--unfilled,
+.rkui-button--unfilled:hover {
+  box-shadow: none;
+  translate: none;
+}
+
+.rkui-button--unfilled:active {
+  background: var(--rkui-raised);
+  box-shadow: var(--rkui-shadow-inset);
+  translate: none;
+  padding-block: calc(var(--rkui-button-padding-block) + var(--rkui-press-offset-y))
+    calc(var(--rkui-button-padding-block) - var(--rkui-press-offset-y));
+  padding-inline: calc(var(--rkui-button-padding-inline) + var(--rkui-press-offset-x))
+    calc(var(--rkui-button-padding-inline) - var(--rkui-press-offset-x));
+}
+
+/* A checked deck key, or a sidebar deck's current page, is pushed in by the whole shadow offset,
+   flush with the page, and doesn't pop. */
+.rkui-segmented--deck label:has(:checked),
+.rkui-sidebar--deck .rkui-sidebar-link[aria-current='page'] {
+  box-shadow: none;
+  translate: var(--rkui-shadow-offset-x) var(--rkui-shadow-offset-y);
+}
+
+/* A checked tile, the current page's, or a toggle button that is on, is pushed in the same way,
+   with an inset shadow instead, at the toggles' pace. */
+.rkui-tile:is(:has(:checked), [aria-current='page']),
+.rkui-button:has(:checked) {
+  box-shadow: var(--rkui-shadow-inset);
+  translate: var(--rkui-shadow-offset-x) var(--rkui-shadow-offset-y);
+  transition-duration: var(--rkui-duration-spring);
+}
+
+/* Folder tabs pop with their position offsets instead of translate. A translate transition puts
+   the tab on its own compositor layer, which snaps to whole pixels and can open a hairline at the
+   join with the sheet. The clip at the sheet's edge (folder.css) moves with the offsets. The
+   offsets are physical, as the light is, so a tab on a strip turned on end still lifts towards it. */
+.rkui-folder-tab {
+  top: var(--rkui-folder-tab-y);
+  left: var(--rkui-folder-tab-x);
+  box-shadow: var(--rkui-shadow);
+  transition:
+    top var(--rkui-duration-fast) ease,
+    left var(--rkui-duration-fast) ease,
+    clip-path var(--rkui-duration-fast) ease,
+    box-shadow var(--rkui-duration-fast) ease;
+}
+
+@media (hover: hover) {
+  .rkui-folder-tab:hover {
+    --rkui-folder-tab-x: calc(-1 * var(--rkui-lift-offset-x));
+    --rkui-folder-tab-y: calc(-1 * var(--rkui-lift-offset-y));
+
+    box-shadow: var(--rkui-shadow-hover);
+  }
+}
+
+.rkui-folder-tab:active {
+  --rkui-folder-tab-x: var(--rkui-press-offset-x);
+  --rkui-folder-tab-y: var(--rkui-press-offset-y);
+
+  box-shadow: var(--rkui-shadow-pressed);
+}
+
+/* The selected folder tab is joined to the sheet and doesn't pop; its shadow is on ::before
+   (folder.css). It takes the selected state at once, so the press it was clicked with doesn't
+   ease back across the join. */
+.rkui-folder-tab:is(:has(:checked), [aria-current='page']) {
+  --rkui-folder-tab-x: 0px;
+  --rkui-folder-tab-y: 0px;
+
+  box-shadow: none;
+  transition: none;
+}
+
+/* Focus band. Toggle buttons, chips, cards, tiles, colour input frames, segmented groups (deck
+   keys included) and folder tabs show it for the input or link inside them, and a drawer's pull
+   for its handle; a segmented group shows it on the group, never on one option. Chips and tiles
+   can also be links, focused themselves. A radio marked data-rkui-focus-visible counts as
+   :focus-visible: Safari drops it after an arrow key (interactive-enhance.js). */
+:is(
+  .rkui-button,
+  .rkui-chip,
+  .rkui-tile,
+  .rkui-checkbox,
+  .rkui-radio,
+  .rkui-switch,
+  .rkui-input,
+  .rkui-select,
+  .rkui-logo:where(a)
+):focus-visible,
+/* :where() keeps each selector's specificity what it was, so the cascade doesn't change. */
+.rkui-radio:where([data-rkui-focus-visible]):focus,
+:is(.rkui-folder-tab, .rkui-folder-sheet):focus-visible,
+.rkui-folder-tab:has(:focus-visible, :where([data-rkui-focus-visible]):focus),
+.rkui-sidebar--deck .rkui-sidebar-link:focus-visible,
+.rkui-drawer-handle:focus-visible > .rkui-drawer-pull,
+:is(.rkui-button, .rkui-chip, .rkui-card--link, .rkui-segmented, .rkui-tile, .rkui-color-input):has(
+  :focus-visible,
+  :where([data-rkui-focus-visible]):focus
+) {
+  outline: var(--rkui-focus-width) solid var(--rkui-focus);
+  outline-offset: var(--rkui-focus-offset);
+  box-shadow: none;
+}
+
+/* The selected folder tab's band is drawn by its ::before in place of its shadow, and stops at
+   the sheet's edge like the tab's outline does. */
+.rkui-folder-tab:is(:has(:checked), [aria-current='page']):is(
+    :focus-visible,
+    :has(:focus-visible, :where([data-rkui-focus-visible]):focus)
+  ) {
+  outline: none;
+}
+
+.rkui-folder-tab:is(:has(:checked), [aria-current='page']):is(
+    :focus-visible,
+    :has(:focus-visible, :where([data-rkui-focus-visible]):focus)
+  )::before {
+  outline: var(--rkui-focus-width) solid var(--rkui-focus);
+  outline-offset: var(--rkui-focus-offset);
+  box-shadow: none;
+  --rkui-folder-cut: 0px;
+}
+
+/* A focused sheet comes in front of the tabs, so its whole focus band shows, and loses its
+   shadow, so its selected tab does too. */
+.rkui-folder-sheet:focus-visible {
+  z-index: 3;
+}
+
+.rkui-folder:has(> .rkui-folder-sheet:focus-visible) > .rkui-folder-strip .rkui-folder-tab::before {
+  box-shadow: none;
+}
+
+/* Disabled: dimmed and flat, with no pop. */
+:is(
+  .rkui-button,
+  .rkui-checkbox,
+  .rkui-radio,
+  .rkui-switch,
+  .rkui-input,
+  .rkui-select,
+  .rkui-range
+):disabled,
+:is(.rkui-button, .rkui-chip, .rkui-segmented label, .rkui-tile, .rkui-color-input):has(:disabled),
+.rkui-ballot-option:has(:disabled) > .rkui-ballot-text,
+.rkui-folder-tab.rkui-folder-tab--off {
+  opacity: 0.45;
+  cursor: not-allowed;
+  box-shadow: none;
+  translate: none;
+}
+
+/* A folder step tab with nowhere to go, at either end of the strip, doesn't pop either. */
+.rkui-folder-tab.rkui-folder-tab--off {
+  --rkui-folder-tab-x: 0px;
+  --rkui-folder-tab-y: 0px;
+}

package/src/shared/after-slide.js

@@ -0,0 +1,14 @@
+/**
+ * Runs `callback` once a segmented control's sliding pill has reached the newly checked option:
+ * after `--rkui-duration-slide`, read where the control is, so it is immediate under reduced
+ * motion. Use it when checking an option restyles the whole page (a theme or palette switch), which
+ * can otherwise cut the slide short.
+ *
+ * @param {Element} control the `.rkui-segmented` group, or any element inside it
+ * @param {() => void} callback
+ */
+export function afterSlide(control, callback) {
+  const duration = getComputedStyle(control).getPropertyValue('--rkui-duration-slide').trim()
+  const milliseconds = duration.endsWith('ms') ? parseFloat(duration) : parseFloat(duration) * 1000
+  setTimeout(callback, Number.isFinite(milliseconds) ? milliseconds : 0)
+}

package/src/shared/astro-attributes.d.ts

@@ -0,0 +1,58 @@
+// The form and link attributes an Astro page may pass to an rkui component, which hands them on
+// to its native element (an input's `name`, a button's `disabled`). Astro checks a Vue component's
+// tags against its props and the global HTML attributes only, so this adds these to that list.
+// This adds them to every tag in Astro pages, so `<div disabled>` is no longer caught. For type
+// checking only; keep it alphabetical. Each type copies Astro's own (astro-jsx.d.ts), which these
+// declarations must match.
+//
+// An Astro project that installs rkui adds this line to its `src/env.d.ts`:
+//   /// <reference types="@oneonefour/rkui/astro-attributes" />
+declare namespace astroHTML.JSX {
+  interface HTMLAttributes {
+    accept?: string | undefined | null
+    autocomplete?: string | undefined | null
+    checked?: boolean | string | undefined | null
+    closedby?: 'none' | 'closerequest' | 'any' | undefined | null
+    cols?: number | string | undefined | null
+    // `string & {}`: any other string, while editors still suggest the named commands.
+    command?:
+      | 'show-modal'
+      | 'close'
+      | 'request-close'
+      | 'show-popover'
+      | 'hide-popover'
+      | 'toggle-popover'
+      | (string & {})
+      | undefined
+      | null
+    commandfor?: string | undefined | null
+    disabled?: boolean | string | undefined | null
+    download?: string | boolean | undefined | null
+    form?: string | undefined | null
+    formaction?: string | undefined | null
+    formenctype?: string | undefined | null
+    formmethod?: string | undefined | null
+    formnovalidate?: boolean | string | undefined | null
+    formtarget?: string | undefined | null
+    list?: string | undefined | null
+    max?: number | string | undefined | null
+    maxlength?: number | string | undefined | null
+    min?: number | string | undefined | null
+    minlength?: number | string | undefined | null
+    multiple?: boolean | string | undefined | null
+    name?: string | undefined | null
+    pattern?: string | undefined | null
+    placeholder?: string | undefined | null
+    popovertarget?: string | undefined | null
+    popovertargetaction?: 'hide' | 'show' | 'toggle' | undefined | null
+    readonly?: boolean | string | undefined | null
+    rel?: string | undefined | null
+    required?: boolean | string | undefined | null
+    rows?: number | string | undefined | null
+    step?: number | string | undefined | null
+    target?: string | undefined | null
+    type?: string | undefined | null
+    value?: string | string[] | number | undefined | null
+    wrap?: string | undefined | null
+  }
+}

package/src/shared/clock-face.js

@@ -0,0 +1,148 @@
+import {
+  VIEWBOX,
+  arcPath,
+  nearestTurn,
+  percentOfFace,
+  polarToCartesian,
+  radialLine,
+  wrap,
+} from './dial-geometry.js'
+
+/** The day and night ring, where the hour hand's tag rides */
+const RING_RADIUS = 86
+const RING_WIDTH = 28
+const TICK_INNER_RADIUS = 58
+const QUARTER_TICK_INNER_RADIUS = 54
+const TICK_OUTER_RADIUS = 66
+const MINUTE_HAND_RADIUS = 40
+
+/** The hour hand goes round once a day, with noon at the top and midnight at the bottom. */
+const DEGREES_PER_HOUR = 360 / 24
+const DEGREES_PER_MINUTE = 360 / 60
+const NOON_ANGLE = 12 * DEGREES_PER_HOUR
+
+/**
+ * @param {number} value
+ * @returns {string} the value as two digits
+ */
+export function twoDigits(value) {
+  return String(value).padStart(2, '0')
+}
+
+/**
+ * @param {number} hours
+ * @param {number} minutes
+ * @param {{ hour: number, minute: number }} [previous] where the hands point now; both start at 0
+ * @returns {{ hour: number, minute: number }} the angles for the hands, each the nearest turn to
+ *   where it points now
+ */
+export function clockHandAngles(hours, minutes, previous = { hour: 0, minute: 0 }) {
+  const hourAngle = wrap((hours + minutes / 60) * DEGREES_PER_HOUR - NOON_ANGLE, 360)
+  return {
+    hour: nearestTurn(previous.hour, hourAngle),
+    minute: nearestTurn(previous.minute, minutes * DEGREES_PER_MINUTE),
+  }
+}
+
+/**
+ * @param {string} name
+ * @param {number} angle
+ * @returns {string} the properties that tell CSS where to centre the day or night icon, on the ring
+ */
+function iconPlacement(name, angle) {
+  const { x, y } = percentOfFace(RING_RADIUS, angle)
+  return `--rkui-clock-${name}-x: ${x}%; --rkui-clock-${name}-y: ${y}%`
+}
+
+/** Inline CSS for the face element: where the day and night icons sit on the ring. */
+export const FACE_STYLE = `${iconPlacement('day', 0)}; ${iconPlacement('night', 180)}`
+
+const SIX_AM = 6 * DEGREES_PER_HOUR - NOON_ANGLE
+const SIX_PM = 18 * DEGREES_PER_HOUR - NOON_ANGLE
+const RING_INNER_EDGE = RING_RADIUS - RING_WIDTH / 2
+const RING_OUTER_EDGE = RING_RADIUS + RING_WIDTH / 2
+
+/**
+ * The day and night ring: the day half over the top and the night half under it, as SVG paths
+ * `width` wide, and its edges: a circle of radius `innerEdge` and a line at each end.
+ */
+export const RING = {
+  width: RING_WIDTH,
+  day: arcPath(RING_RADIUS, SIX_AM, SIX_AM + 180),
+  night: arcPath(RING_RADIUS, SIX_PM, SIX_PM + 180),
+  innerEdge: RING_INNER_EDGE,
+  edges: [
+    radialLine(RING_INNER_EDGE, RING_OUTER_EDGE, SIX_AM),
+    radialLine(RING_INNER_EDGE, RING_OUTER_EDGE, SIX_PM),
+  ],
+}
+
+/** A tick for every five minutes, as the ends of SVG lines; the ones at the quarters are longer. */
+export const TICKS = Array.from({ length: 12 }, (_, index) => {
+  const quarter = index % 3 === 0
+  const inner = quarter ? QUARTER_TICK_INNER_RADIUS : TICK_INNER_RADIUS
+  return { quarter, line: radialLine(inner, TICK_OUTER_RADIUS, index * 5 * DEGREES_PER_MINUTE) }
+})
+
+/** How far each hand reaches from the centre, in SVG units; its tag sits at the tip. */
+const HAND_RADII = { hour: RING_RADIUS, minute: MINUTE_HAND_RADIUS }
+
+/**
+ * @param {'hour' | 'minute'} hand
+ * @returns {string} the hand's length as a percentage of the face, for `--rkui-hand-length`
+ */
+export function handLength(hand) {
+  return `${(HAND_RADII[hand] / VIEWBOX) * 100}%`
+}
+
+/**
+ * @param {string} value a time input's value, "HH:MM"
+ * @returns {{ hours: number, minutes: number }} the time; an empty value is midnight
+ */
+export function parseTime(value) {
+  const [hours = 0, minutes = 0] = value.split(':').map(Number)
+  return { hours, minutes }
+}
+
+/**
+ * @param {number} hours any whole number; it wraps round the day
+ * @param {number} minutes from 0 to 59
+ * @returns {string} the time as a time input's value, "HH:MM"
+ */
+export function formatTime(hours, minutes) {
+  return `${twoDigits(wrap(hours, 24))}:${twoDigits(minutes)}`
+}
+
+/**
+ * @param {{ x: number, y: number }} point a point on the face, in SVG units
+ * @param {{ hour: number, minute: number }} angles where the hands point
+ * @returns {'hour' | 'minute'} the hand whose tag is nearer the point
+ */
+export function nearestHand(point, angles) {
+  /** @param {'hour' | 'minute'} hand */
+  const distance = (hand) => {
+    const tag = polarToCartesian(HAND_RADII[hand], angles[hand])
+    return Math.hypot(point.x - tag.x, point.y - tag.y)
+  }
+  return distance('hour') < distance('minute') ? 'hour' : 'minute'
+}
+
+/**
+ * The time a dragged hand sets. The hour hand keeps the minutes; the minute hand snaps to `step`
+ * and, passing 12, moves the hour on or back, as on a real clock.
+ * @param {'hour' | 'minute'} hand
+ * @param {number} angle where the pointer is, clockwise from 12, 0 to 360
+ * @param {{ hours: number, minutes: number }} time the time before this move
+ * @param {number} step the minutes the minute hand snaps to
+ * @returns {{ hours: number, minutes: number }} the new time; `hours` may be outside 0 to 23
+ */
+export function draggedTime(hand, angle, { hours, minutes }, step) {
+  if (hand === 'hour') {
+    return { hours: Math.round((angle + NOON_ANGLE) / DEGREES_PER_HOUR - minutes / 60), minutes }
+  }
+  const minute = wrap(Math.round(angle / DEGREES_PER_MINUTE / step) * step, 60)
+  let hour = hours
+  if (minutes >= 45 && minute < 15) hour += 1
+  if (minutes < 15 && minute >= 45) hour -= 1
+  return { hours: hour, minutes: minute }
+}

package/src/shared/component-id.ts

@@ -0,0 +1,17 @@
+import { getCurrentInstance, useId } from 'vue'
+
+/** How many ids have been made for apps with no `idPrefix`. */
+let unprefixed = 0
+
+/**
+ * A unique id for a component's element, e.g. 'rkui-stepper-s1-0'. Call it in `<script setup>`,
+ * as for `useId()`. It is Vue's `useId()` behind the library's prefix when the app has an
+ * `idPrefix` (Astro sets one for each island that renders on the server, and `defineElement` one
+ * for each element). Without one, `useId()` would count from 0 in every app on the page, so a
+ * counter shared by the whole page is used instead: those apps (`client:only` islands) never
+ * hydrate, so the server never needs the same id.
+ */
+export function useComponentId(component: string): string {
+  const hasPrefix = Boolean(getCurrentInstance()?.appContext.config.idPrefix)
+  return `rkui-${component}-${hasPrefix ? useId() : `u${unprefixed++}`}`
+}

package/src/shared/define-element.ts

@@ -0,0 +1,51 @@
+import { defineCustomElement, h, useHost, type Component } from 'vue'
+
+/** The attributes each element had when it started, kept for when it is moved and restarts. */
+const startingAttributes = new WeakMap<HTMLElement, Record<string, string>>()
+/** How many element apps have started, for each one's id prefix. */
+let apps = 0
+
+/** Reads `host`'s attributes and takes them off it, the first time only. */
+function takeAttributes(host: HTMLElement): Record<string, string> {
+  let attrs = startingAttributes.get(host)
+  if (!attrs) {
+    attrs = {}
+    for (const { name, value } of [...host.attributes]) attrs[name] = value
+    for (const name of Object.keys(attrs)) host.removeAttribute(name)
+    startingAttributes.set(host, attrs)
+  }
+  return attrs
+}
+
+/**
+ * Registers `component` as the custom element `tag`, for plain HTML pages, which have no other way
+ * to say "put a Stepper here". The element renders the component in place, in the light DOM, so
+ * the page's CSS styles it. The element's attributes become the component's props and attributes,
+ * and move off the element, which takes no space of its own: `<rkui-stepper value="3">` renders
+ * just the Stepper. They are read once, when the element first starts: changing one later does
+ * nothing, and a moved element keeps the ones it started with.
+ */
+export function defineElement(tag: string, component: Component) {
+  const element = defineCustomElement(
+    {
+      // Vue would also hand the element's attributes on; they are read once, here, instead.
+      inheritAttrs: false,
+      setup() {
+        // Always set here: this setup only ever runs inside the element.
+        const host = useHost()!
+        const attrs = takeAttributes(host)
+        host.style.setProperty('display', 'contents')
+        return () => h(component, attrs)
+      },
+    },
+    {
+      shadowRoot: false,
+      // Each element is its own Vue app; without a prefix of its own, every app's ids would
+      // start from the same number (component-id.ts).
+      configureApp(app) {
+        app.config.idPrefix = `e${++apps}`
+      },
+    },
+  )
+  customElements.define(tag, element)
+}