@oneonefour/rkui 0.0.0-stage → 0.0.3

package/src/shared/dial-face.js

@@ -0,0 +1,111 @@
+import { arcPath, polarToCartesian, percentOfFace, radialLine } from './dial-geometry.js'
+
+/** Degrees of travel, centred on 12 o'clock, leaving a gap at the bottom. */
+const SWEEP = 270
+export const START_ANGLE = -SWEEP / 2
+export const END_ANGLE = SWEEP / 2
+
+const TICK_COUNT = 11
+const TICK_INNER_RADIUS = 84
+const TICK_OUTER_RADIUS = 94
+export const TRACK_RADIUS = 84
+const LIMIT_RADIUS = 86
+const LIMIT_ANGLE = 158
+const RAMP_BLOCK_COUNT = 18
+/** Degrees left empty between neighbouring ramp blocks */
+const RAMP_BLOCK_GAP = 3
+const RAMP_INNER_RADIUS = 74
+const RAMP_OUTER_RADIUS = 94
+
+/**
+ * @param {number} value
+ * @param {number} min
+ * @param {number} max
+ * @returns {number} the angle that shows `value` on the dial
+ */
+export function valueToAngle(value, min, max) {
+  return START_ANGLE + ((value - min) / (max - min)) * SWEEP
+}
+
+/**
+ * @param {number} angle an angle within the dial's travel
+ * @param {number} min
+ * @param {number} max
+ * @returns {number} the value at `angle`, not yet snapped to a step
+ */
+export function angleToValue(angle, min, max) {
+  return min + ((angle - START_ANGLE) / SWEEP) * (max - min)
+}
+
+/**
+ * @param {number} index which ramp block, from 0
+ * @param {number} fraction how far round the dial the value is, from 0 to 1
+ * @returns {boolean} whether the block is lit: once the value reaches its middle
+ */
+export function isBlockLit(index, fraction) {
+  return (index + 0.5) / RAMP_BLOCK_COUNT <= fraction
+}
+
+/**
+ * @param {number} angle where the dial points
+ * @returns {string} inline CSS for the face element: the knob's angle, and the point of the track
+ *   where the arc's thumb sits
+ */
+export function faceStyle(angle) {
+  const { x, y } = percentOfFace(TRACK_RADIUS, angle)
+  return `--rkui-dial-angle: ${angle}deg; --rkui-dial-thumb-x: ${x}%; --rkui-dial-thumb-y: ${y}%`
+}
+
+/** Where the min label sits, in SVG units, left of the gap at the bottom. */
+export const MIN_LABEL = polarToCartesian(LIMIT_RADIUS, -LIMIT_ANGLE)
+/** Where the max label sits, in SVG units, right of the gap at the bottom. */
+export const MAX_LABEL = polarToCartesian(LIMIT_RADIUS, LIMIT_ANGLE)
+
+/** Evenly spaced tick marks around the dial's travel, as the ends of SVG lines. */
+export const TICKS = Array.from({ length: TICK_COUNT }, (_, index) =>
+  radialLine(
+    TICK_INNER_RADIUS,
+    TICK_OUTER_RADIUS,
+    START_ANGLE + (index * SWEEP) / (TICK_COUNT - 1),
+  ),
+)
+
+/** SVG path data for the arc's track, round the whole of the dial's travel. */
+export const TRACK = arcPath(TRACK_RADIUS, START_ANGLE, END_ANGLE)
+
+/**
+ * @param {number} fromAngle
+ * @param {number} toAngle
+ * @returns {string} SVG path data for a block of the ramp's ring, between the two angles
+ */
+function blockPath(fromAngle, toAngle) {
+  const outerStart = polarToCartesian(RAMP_OUTER_RADIUS, fromAngle)
+  const outerEnd = polarToCartesian(RAMP_OUTER_RADIUS, toAngle)
+  const innerEnd = polarToCartesian(RAMP_INNER_RADIUS, toAngle)
+  const innerStart = polarToCartesian(RAMP_INNER_RADIUS, fromAngle)
+  return [
+    `M ${outerStart.x} ${outerStart.y}`,
+    `A ${RAMP_OUTER_RADIUS} ${RAMP_OUTER_RADIUS} 0 0 1 ${outerEnd.x} ${outerEnd.y}`,
+    `L ${innerEnd.x} ${innerEnd.y}`,
+    `A ${RAMP_INNER_RADIUS} ${RAMP_INNER_RADIUS} 0 0 0 ${innerStart.x} ${innerStart.y}`,
+    'Z',
+  ].join(' ')
+}
+
+/**
+ * @param {number} stepCount how many colours the ramp has
+ * @returns {{ d: string, fill: string }[]} the ramp's blocks around the dial's travel: each one's
+ *   SVG path data, and its colour, `--rkui-dial-ramp-1` to `--rkui-dial-ramp-<stepCount>` in
+ *   equal runs
+ */
+export function rampBlocks(stepCount) {
+  const width = SWEEP / RAMP_BLOCK_COUNT
+  return Array.from({ length: RAMP_BLOCK_COUNT }, (_, index) => {
+    const from = START_ANGLE + index * width + RAMP_BLOCK_GAP / 2
+    const step = Math.floor((index * stepCount) / RAMP_BLOCK_COUNT) + 1
+    return {
+      d: blockPath(from, from + width - RAMP_BLOCK_GAP),
+      fill: `var(--rkui-dial-ramp-${step})`,
+    }
+  })
+}

package/src/shared/dial-geometry.js

@@ -0,0 +1,96 @@
+/**
+ * Geometry shared by the clock and dial faces, which Clock.vue and Dial.vue draw. No DOM: every
+ * function takes numbers and returns numbers, strings or plain objects. Angles are degrees
+ * clockwise from 12 o'clock.
+ */
+
+/** A face's SVG is drawn in a square of this many units, centred on (CENTRE, CENTRE). */
+export const VIEWBOX = 200
+export const CENTRE = VIEWBOX / 2
+
+/**
+ * @param {number} value
+ * @param {number} divisor
+ * @returns {number} `value` modulo `divisor`, never negative
+ */
+export function wrap(value, divisor) {
+  return ((value % divisor) + divisor) % divisor
+}
+
+/**
+ * @param {number} previous the angle a hand points at now, which may be past 360 or below 0
+ * @param {number} angle the way it should point next, from 0 to 360
+ * @returns {number} the angle nearest `previous` that points the same way as `angle`, so the
+ *   hand takes the short way round instead of spinning back past 12
+ */
+export function nearestTurn(previous, angle) {
+  return previous + wrap(angle - previous + 180, 360) - 180
+}
+
+/**
+ * @param {number} value
+ * @returns {number} the value to a thousandth of an SVG unit. The server and the browser can
+ *   differ in a sine's last digit; rounded, they write the same markup.
+ */
+function round(value) {
+  return Math.round(value * 1000) / 1000
+}
+
+/**
+ * @param {number} radius
+ * @param {number} angle
+ * @returns {{ x: number, y: number }} the point in the SVG at `radius` and `angle` from the centre
+ */
+export function polarToCartesian(radius, angle) {
+  const radians = (angle * Math.PI) / 180
+  return {
+    x: round(CENTRE + radius * Math.sin(radians)),
+    y: round(CENTRE - radius * Math.cos(radians)),
+  }
+}
+
+/**
+ * @param {number} radius
+ * @param {number} angle
+ * @returns {{ x: number, y: number }} the same point as a percentage of the face's width and
+ *   height, for CSS to centre an element on it
+ */
+export function percentOfFace(radius, angle) {
+  const { x, y } = polarToCartesian(radius, angle)
+  return { x: (x * 100) / VIEWBOX, y: (y * 100) / VIEWBOX }
+}
+
+/**
+ * @param {number} radius
+ * @param {number} fromAngle
+ * @param {number} toAngle
+ * @returns {string} SVG path data for a clockwise arc
+ */
+export function arcPath(radius, fromAngle, toAngle) {
+  const start = polarToCartesian(radius, fromAngle)
+  const end = polarToCartesian(radius, toAngle)
+  const largeArc = toAngle - fromAngle > 180 ? 1 : 0
+  return `M ${start.x} ${start.y} A ${radius} ${radius} 0 ${largeArc} 1 ${end.x} ${end.y}`
+}
+
+/**
+ * @param {number} innerRadius
+ * @param {number} outerRadius
+ * @param {number} angle
+ * @returns {{ x1: number, y1: number, x2: number, y2: number }} the ends of an SVG `<line>`
+ *   pointing out from the centre, between the two radii
+ */
+export function radialLine(innerRadius, outerRadius, angle) {
+  const inner = polarToCartesian(innerRadius, angle)
+  const outer = polarToCartesian(outerRadius, angle)
+  return { x1: inner.x, y1: inner.y, x2: outer.x, y2: outer.y }
+}
+
+/**
+ * @param {number} dx distance right of the centre
+ * @param {number} dy distance below the centre
+ * @returns {number} the angle of that point, from -180 to 180
+ */
+export function pointToAngle(dx, dy) {
+  return (Math.atan2(dx, -dy) * 180) / Math.PI
+}

package/src/shared/each-element.js

@@ -0,0 +1,38 @@
+// Finds elements for the enhance scripts, including ones a Vue app or a page script adds after the
+// scripts have run. One MutationObserver serves every script.
+
+/** @type {((root: Element) => void)[]} */
+const watchers = []
+/** @type {MutationObserver | undefined} */
+let observer
+
+/**
+ * Calls `setUp` once for each element that matches `selector`, now and whenever one is added to
+ * the page later. Each element it sets up gets the attribute `mark`, so none is set up twice, even
+ * by a second copy of the script.
+ * @param {string} selector
+ * @param {string} mark an attribute name, e.g. 'data-rkui-bar'
+ * @param {(element: HTMLElement) => void} setUp
+ */
+export function eachElement(selector, mark, setUp) {
+  /** @param {Element} root */
+  const watch = (root) => {
+    const found = [...(root.matches(selector) ? [root] : []), ...root.querySelectorAll(selector)]
+    for (const element of found) {
+      if (element.hasAttribute(mark)) continue
+      element.setAttribute(mark, '')
+      setUp(/** @type {HTMLElement} */ (element))
+    }
+  }
+  watch(document.documentElement)
+  watchers.push(watch)
+  if (observer) return
+  observer = new MutationObserver((records) => {
+    for (const { addedNodes } of records) {
+      for (const node of addedNodes) {
+        if (node instanceof Element) for (const each of watchers) each(node)
+      }
+    }
+  })
+  observer.observe(document.documentElement, { childList: true, subtree: true })
+}

package/src/shared/field-attrs.ts

@@ -0,0 +1,32 @@
+/** The props every control shares for its Field's message. */
+interface FieldProps {
+  hint?: string
+  error?: string
+}
+
+/** The attributes a page may already have set that a Field also writes. */
+interface LinkedAttrs {
+  'aria-describedby'?: string | null
+  'aria-invalid'?: string | boolean | null
+}
+
+/**
+ * Returns the control's attributes with its `id` and the link to its Field's message: the message's
+ * id (`${id}-message`) is joined onto any `aria-describedby` the page set, and `aria-invalid` is
+ * `true` while there is an error.
+ */
+export function fieldAttrs<T extends LinkedAttrs>(
+  id: string,
+  { hint, error }: FieldProps,
+  attrs: T,
+) {
+  const message = hint || error ? `${id}-message` : undefined
+  const describedby = [attrs['aria-describedby'], message].filter(Boolean).join(' ')
+  return {
+    ...attrs,
+    id,
+    'aria-describedby': describedby || undefined,
+    // `as const` keeps the literal type the HTML attribute types ask for.
+    'aria-invalid': error ? ('true' as const) : attrs['aria-invalid'],
+  }
+}

package/src/shared/hues.ts

@@ -0,0 +1,111 @@
+import { colors } from '../../dist/colors.js'
+
+/**
+ * The palette's hues, for every component's `hue` prop: the core hues, then the auxiliary ones.
+ * Each has a `--rkui-<hue>` fill token and `-deep` and `-tint` steps in src/tokens/colors.css. A
+ * component that supports fewer hues picks from this list.
+ */
+export const HUES = [
+  'navy',
+  'teal',
+  'coral',
+  'yellow',
+  'green',
+  'sky',
+  'grape',
+  'tangerine',
+  'lilac',
+  'apricot',
+] as const
+
+/** One of the palette's hues, e.g. 'teal'. (Read from the list above, so the two can't drift.) */
+export type Hue = (typeof HUES)[number]
+
+/** A component's `hue`: a palette hue, e.g. 'teal', or a hex code, e.g. '#ff8800'. */
+export type HueOrHex = Hue | `#${string}`
+
+/** The hues whose fill carries its own text colour (`--rkui-on-<hue>`); the rest take ink. */
+const HUES_WITH_OWN_TEXT: Hue[] = ['navy', 'coral', 'grape']
+
+/** The text token for text on a `hue` fill, e.g. `--rkui-on-navy`, or `--rkui-on-fill` (ink). */
+export function onHue(hue: Hue): string {
+  return HUES_WITH_OWN_TEXT.includes(hue) ? `--rkui-on-${hue}` : '--rkui-on-fill'
+}
+
+/** Whether `hue` is a hex code rather than a palette hue. */
+export function isHex(hue: string | undefined): hue is `#${string}` {
+  return hue?.startsWith('#') ?? false
+}
+
+/** The custom properties a component paints with, each set from its `hue`. */
+export interface HueProperties {
+  /** Takes the fill. */
+  fill?: string
+  /** Takes the colour of text and icons on the fill. */
+  text?: string
+  /** Takes the tint: a pale panel that carries `--rkui-fg` text. */
+  tint?: string
+  /** The fill carries small text, so coral takes `--rkui-coral-solid`. */
+  solid?: boolean
+}
+
+/**
+ * The style that paints a component in `hue`, for its `vars`: each of `properties` set to the
+ * hue's token, or for a hex code to the code and the colours worked out from it (DESIGN.md,
+ * "Shading"). Empty when `hue` is left out.
+ */
+export function hueVars(
+  hue: HueOrHex | undefined,
+  properties: HueProperties,
+): Record<string, string> {
+  if (!hue) return {}
+  const { fill, text, tint, solid } = properties
+  const style: Record<string, string> = {}
+  if (isHex(hue)) {
+    if (fill) style[fill] = hue
+    if (text) style[text] = `var(${textOn(hue)})`
+    if (tint) style[tint] = tintOf(hue)
+  } else {
+    if (fill) style[fill] = `var(--rkui-${solid && hue === 'coral' ? 'coral-solid' : hue})`
+    if (text) style[text] = `var(${onHue(hue)})`
+    if (tint) style[tint] = `var(--rkui-${hue}-tint)`
+  }
+  return style
+}
+
+/** A hex code's tint: 35% of it over `--rkui-raised` in light mode, 25% in dark mode. */
+function tintOf(hex: string): string {
+  const mix = (share: string) => `color-mix(in srgb, ${hex} ${share}, var(--rkui-raised))`
+  return `light-dark(${mix('35%')}, ${mix('25%')})`
+}
+
+/**
+ * The text token for a hex fill: ink (`--rkui-on-fill`), unless `--rkui-on-ink` has more contrast
+ * on it in both themes.
+ */
+function textOn(hex: string): string {
+  const fill = luminance(hex)
+  const ink = contrast(fill, luminance(colors.onFill.light))
+  const light = Math.min(
+    contrast(fill, luminance(colors.onInk.light)),
+    contrast(fill, luminance(colors.onInk.dark)),
+  )
+  return light > ink ? '--rkui-on-ink' : '--rkui-on-fill'
+}
+
+/** The WCAG contrast ratio of two relative luminances. */
+function contrast(a: number, b: number): number {
+  return (Math.max(a, b) + 0.05) / (Math.min(a, b) + 0.05)
+}
+
+/** The WCAG relative luminance of a hex code (#rgb, #rgba, #rrggbb or #rrggbbaa); alpha is ignored. */
+function luminance(hex: string): number {
+  const digits = hex.slice(1)
+  const short = digits.length <= 4
+  const channels = [0, 1, 2].map((i) => {
+    const pair = short ? digits[i] + digits[i] : digits.slice(i * 2, i * 2 + 2)
+    const value = parseInt(pair, 16) / 255
+    return value <= 0.04045 ? value / 12.92 : ((value + 0.055) / 1.055) ** 2.4
+  })
+  return 0.2126 * channels[0] + 0.7152 * channels[1] + 0.0722 * channels[2]
+}

package/src/shared/light-angle.js

@@ -0,0 +1,49 @@
+/**
+ * The maths behind LightDirection. No DOM. Angles are in degrees, clockwise from 12 o'clock, and
+ * name where the light comes from.
+ */
+
+/** Where the light comes from by default: the top left. */
+export const DEFAULT_ANGLE = 315
+
+/** At the default angle this gives --rkui-shadow-dx and --rkui-shadow-dy of exactly 1. */
+const SHADOW_LENGTH = Math.SQRT2
+
+const SUNRISE_HOUR = 6
+const SUNSET_HOUR = 18
+/** The sun rises on the left, at 9 o'clock. */
+const SUNRISE_ANGLE = 270
+
+/**
+ * @param {number} value
+ * @returns {string} `value` rounded to three decimals, so the default angle gives exactly 1
+ */
+function toToken(value) {
+  return String(Math.round(value * 1000) / 1000)
+}
+
+/**
+ * The shadow direction that points away from a light at `angle`.
+ * @param {number} angle where the light comes from
+ * @returns {{ dx: string, dy: string }} the values for --rkui-shadow-dx and --rkui-shadow-dy
+ */
+export function shadowOffsets(angle) {
+  const radians = (angle * Math.PI) / 180
+  return {
+    dx: toToken(-SHADOW_LENGTH * Math.sin(radians)),
+    dy: toToken(SHADOW_LENGTH * Math.cos(radians)),
+  }
+}
+
+/**
+ * The sun rises on the left at 6:00, is overhead at noon and sets on the right at 18:00, so 9:00
+ * gives the default angle. At night the light goes back to the default.
+ * @param {Date} time
+ * @returns {number} the light angle at `time`
+ */
+export function sunAngle(time) {
+  const hour = time.getHours() + time.getMinutes() / 60
+  const dayFraction = (hour - SUNRISE_HOUR) / (SUNSET_HOUR - SUNRISE_HOUR)
+  if (dayFraction < 0 || dayFraction > 1) return DEFAULT_ANGLE
+  return (SUNRISE_ANGLE + 180 * dayFraction) % 360
+}

package/src/shared/live-value.ts

@@ -0,0 +1,142 @@
+// A form control's value as the browser has it when its component starts, for every form control
+// with a `v-model` (inputs, textareas and selects), and a radio or checkbox's checked state. Each
+// directive goes on the control before its `v-model`: the first read must come before Vue's
+// v-model writes to it, which for a radio is as soon as it is created.
+
+import { startingIndex } from './starting-option'
+
+/** A form control that holds a value: an input, a textarea or a select. */
+type ValueControl = HTMLInputElement | HTMLTextAreaElement | HTMLSelectElement
+
+/**
+ * What each control held before Vue's `v-model` first wrote to it, when the reader or the browser
+ * had changed it: its value, or a select's chosen options.
+ */
+const changedValues = new WeakMap<ValueControl, string | HTMLOptionElement[]>()
+
+/**
+ * The value an input's markup alone gives it, as the browser cleans it up: a colour in lower case,
+ * a range's value kept within its `min`, `max` and `step`.
+ */
+function markupValue(input: HTMLInputElement): string {
+  const fresh = document.createElement('input')
+  for (const { name, value } of input.attributes) fresh.setAttribute(name, value)
+  return fresh.value
+}
+
+/** The options a select's markup alone chooses. */
+function markupOptions(select: HTMLSelectElement): HTMLOptionElement[] {
+  const options = [...select.options]
+  if (select.multiple) return options.filter((option) => option.defaultSelected)
+  const marks = options.map((option) => ({
+    selected: option.defaultSelected,
+    disabled: option.disabled,
+  }))
+  const start = options[startingIndex(marks)]
+  return start ? [start] : []
+}
+
+/** What the control holds now, if the reader or the browser changed it from its markup. */
+function changedInBrowser(control: ValueControl): string | HTMLOptionElement[] | undefined {
+  if (control instanceof HTMLSelectElement) {
+    const chosen = [...control.selectedOptions]
+    const start = markupOptions(control)
+    const same = chosen.length === start.length && chosen.every((option, i) => option === start[i])
+    return same ? undefined : chosen
+  }
+  const start = control instanceof HTMLInputElement ? markupValue(control) : control.defaultValue
+  return control.value === start ? undefined : control.value
+}
+
+/** Puts back what the control held before `v-model` wrote over it. */
+function restore(control: ValueControl, changed: string | HTMLOptionElement[]) {
+  if (typeof changed === 'string') {
+    control.value = changed
+    return
+  }
+  // A list of options comes only from a select. Choosing one unchooses the others, unless it is
+  // a multiple select.
+  const select = control as HTMLSelectElement
+  for (const option of select.options) {
+    if (changed.includes(option)) option.selected = true
+    else if (select.multiple) option.selected = false
+  }
+}
+
+/**
+ * A directive that keeps what the browser holds in an input, a textarea or a select over the
+ * model's starting value: what was typed or chosen before the component woke up
+ * (`client:visible`), or a form the browser restored on going back. A range's model also follows
+ * a starting value the browser kept within its `min`, `max` and `step`. Otherwise the model stays
+ * exactly as the parent gave it. `const vLiveValue = useLiveValue(model)`, then
+ * `<input v-live-value v-model="model">`. It hands the value on with the event `v-model` listens
+ * for, as typing would, so `v-model` casts it as usual (a number for `type="number"`).
+ */
+export function useLiveValue(model: { value: unknown }) {
+  return {
+    // Before v-model writes the model's value over it. A control already on the page came from
+    // the server; if it differs from its markup, it was changed in the browser.
+    beforeMount(control: ValueControl) {
+      if (!control.isConnected) return
+      const changed = changedInBrowser(control)
+      if (changed !== undefined) changedValues.set(control, changed)
+    },
+    // Once the mount is over, after v-model and the parent's starting value have had their say.
+    mounted(control: ValueControl) {
+      queueMicrotask(() => {
+        const changed = changedValues.get(control)
+        if (changed !== undefined) restore(control, changed)
+        const clamped = control.type === 'range' && control.value !== String(model.value)
+        if (changed === undefined && !clamped) return
+        const event = control instanceof HTMLSelectElement ? 'change' : 'input'
+        control.dispatchEvent(new Event(event, { bubbles: true }))
+      })
+    },
+  }
+}
+
+/** The radios and checkboxes changed in the browser before their component woke up: checked or not. */
+const changedChecks = new WeakMap<HTMLInputElement, boolean>()
+
+/**
+ * The radios that share `input`'s name on its page, as one group, or just `input` when it is a
+ * checkbox or has no name.
+ */
+function radioGroup(input: HTMLInputElement): HTMLInputElement[] {
+  if (input.type !== 'radio' || !input.name) return [input]
+  const root = input.getRootNode() as Document | ShadowRoot
+  return [...root.querySelectorAll<HTMLInputElement>(`input[type="radio"]`)].filter(
+    (radio) => radio.name === input.name,
+  )
+}
+
+/**
+ * A directive that keeps a radio's or checkbox's checked state from the browser: what was clicked
+ * before the component woke up (`client:visible`), or a form the browser restored on going back.
+ * Write `v-live-checked` on the input before its `v-model`. It hands the state to the `v-model` with a `change` event, so
+ * any model works: a radio group's value, a checkbox's boolean, a list of values.
+ */
+export const vLiveChecked = {
+  // Before any v-model in the group writes to it. A whole radio group is read at once, since the
+  // first radio's v-model unchecks the one the reader chose.
+  created(input: HTMLInputElement) {
+    if (!input.isConnected) return
+    for (const box of radioGroup(input)) {
+      if (box.checked !== box.defaultChecked && !changedChecks.has(box)) {
+        changedChecks.set(box, box.checked)
+      }
+    }
+  },
+  // Once the mount is over, after v-model has its list and the parent its starting value.
+  mounted(input: HTMLInputElement) {
+    const checked = changedChecks.get(input)
+    if (checked === undefined) return
+    queueMicrotask(() => {
+      input.checked = checked
+      // An unchecked radio says nothing: the radio checked in its place tells the model.
+      if (checked || input.type === 'checkbox') {
+        input.dispatchEvent(new Event('change', { bubbles: true }))
+      }
+    })
+  },
+}

package/src/shared/model-start.ts

@@ -0,0 +1,23 @@
+import { computed, onMounted, type Ref, type WritableComputedRef } from 'vue'
+
+/**
+ * A component's `v-model` that, while the model is unset, follows `start()`, a value read from its
+ * slot. On mount the starting value is handed to the parent's `v-model`. The slot is read when the
+ * template reads the model, in render. Read in setup, Vue warns that the slot is invoked outside
+ * the render function.
+ */
+export function modelWithStart<T>(
+  model: Ref<T | undefined>,
+  start: () => T,
+): WritableComputedRef<T> {
+  const selection = computed({
+    get: () => model.value ?? start(),
+    set: (value) => {
+      model.value = value
+    },
+  })
+  onMounted(() => {
+    if (model.value === undefined) model.value = selection.value
+  })
+  return selection
+}

package/src/shared/option-group.ts

@@ -0,0 +1,19 @@
+/** What an option renders as its input's `name` when the page gives it none. */
+export const NAME_PLACEHOLDER = 'rkui-option-name'
+
+/**
+ * Fills a group's `name` (and radio or checkbox type) into the options it has rendered, so the page
+ * writes them once. An option with no `name` of its own renders `NAME_PLACEHOLDER`, and an input
+ * with that name is a checkbox until the group says otherwise. An option given its own `name` is
+ * left as it is.
+ */
+export function fillOptions(html: string, name: string, multiple: boolean): string {
+  const type = multiple ? 'checkbox' : 'radio'
+  const safeName = name.replaceAll('"', '"')
+  return html
+    .replaceAll(
+      `type="checkbox" name="${NAME_PLACEHOLDER}"`,
+      () => `type="${type}" name="${safeName}"`,
+    )
+    .replaceAll(`name="${NAME_PLACEHOLDER}"`, () => `name="${safeName}"`)
+}