@greendrake/ui 0.1.0

package/src/downsizeImage.ts

@@ -0,0 +1,78 @@
+interface Options {
+    maxDimension?: number
+    maxSizeKB?: number
+    minQuality?: number
+}
+
+const DEFAULTS = {
+    maxDimension: 2000,
+    maxSizeKB: 1024,
+    minQuality: 0.2
+}
+
+const canvasToBlob = (canvas: HTMLCanvasElement, type: string, quality: number): Promise<Blob> =>
+    new Promise((resolve, reject) => {
+        canvas.toBlob(blob => (blob ? resolve(blob) : reject(new Error('toBlob returned null'))), type, quality)
+    })
+
+const loadImage = (file: File): Promise<HTMLImageElement> =>
+    new Promise((resolve, reject) => {
+        const url = URL.createObjectURL(file)
+        const img = new Image()
+        img.onload = () => {
+            URL.revokeObjectURL(url)
+            resolve(img)
+        }
+        img.onerror = () => {
+            URL.revokeObjectURL(url)
+            reject(new Error('Failed to load image'))
+        }
+        img.src = url
+    })
+
+// Re-encodes an oversized image as JPEG, scaling it to fit maxDimension and
+// stepping quality down until it fits maxSizeKB (or minQuality is reached).
+// Non-images and files already within both limits pass through untouched, as
+// do files the browser cannot decode.
+export default async function downsizeImage(file: File, opts?: Options): Promise<File> {
+    if (!file.type.startsWith('image/')) return file
+
+    const { maxDimension, maxSizeKB, minQuality } = { ...DEFAULTS, ...opts }
+    const maxSizeBytes = maxSizeKB * 1024
+
+    let img: HTMLImageElement
+    try {
+        img = await loadImage(file)
+    } catch {
+        return file
+    }
+    let { width, height } = img
+    if (file.size <= maxSizeBytes && width <= maxDimension && height <= maxDimension) {
+        return file
+    }
+
+    if (width > maxDimension || height > maxDimension) {
+        const ratio = Math.min(maxDimension / width, maxDimension / height)
+        width = Math.round(width * ratio)
+        height = Math.round(height * ratio)
+    }
+
+    const canvas = document.createElement('canvas')
+    canvas.width = width
+    canvas.height = height
+    const ctx = canvas.getContext('2d')!
+    ctx.drawImage(img, 0, 0, width, height)
+
+    let quality = 0.92
+    let blob = await canvasToBlob(canvas, 'image/jpeg', quality)
+
+    while (blob.size > maxSizeBytes && quality > minQuality) {
+        quality -= 0.05
+        blob = await canvasToBlob(canvas, 'image/jpeg', quality)
+    }
+
+    canvas.remove()
+
+    const name = file.name.replace(/\.[^.]+$/, '.jpg')
+    return new File([blob], name, { type: 'image/jpeg' })
+}

package/src/inModal.ts

@@ -0,0 +1,8 @@
+import type { InjectionKey } from 'vue'
+
+// Modal provides this so descendants can tell they render inside a modal
+// window rather than the page. Surfaces that pin themselves to the viewport
+// (e.g. AsyncSearch's narrow-viewport results takeover) are wrong inside one:
+// the sheet already owns the screen, sits above them in the stacking order,
+// and leaves them no room when it is pinned to the bottom edge.
+export const inModalKey: InjectionKey<true> = Symbol('inModal')

package/src/main.ts

@@ -0,0 +1,78 @@
+export { showToast, type ToastHandle, type ToastOptions, type ToastVariant } from './toast/showToast'
+export { messages, configureUiMessages, type UiMessages } from './messages'
+export { default as Loading } from './Loading.vue'
+export { default as TabBar } from './TabBar.vue'
+export type { TabDef } from './TabBar.vue'
+export { default as Splash } from './Splash.vue'
+
+// Form controls
+export { default as TextField } from './TextField.vue'
+export { default as Password } from './Password.vue'
+export { default as Email } from './Email.vue'
+export { default as Checkbox } from './Checkbox.vue'
+export { default as CurrencyInput } from './CurrencyInput.vue'
+export { default as Field } from './Field.vue'
+export { default as FieldTip } from './FieldTip'
+export { validationScopeKey } from './validationScope'
+
+// Form submission state machine
+export { default as FormC } from './Form.vue'
+export { default as AsyncAction } from './AsyncAction.vue'
+export { default as OptionSwitch } from './OptionSwitch.vue'
+export type { OptionValue, OptionsArray, OptionsMap } from './OptionSwitch.vue'
+export { default as SegmentedControl } from './SegmentedControl.vue'
+export type { SegmentedOption } from './SegmentedControl.vue'
+
+// Search
+export { default as SearchField } from './SearchField.vue'
+export { default as AsyncSearch } from './AsyncSearch.vue'
+export type { SearchFunction } from './AsyncSearch.vue'
+export type { SearchResultItem } from './AsyncSearchResults.vue'
+
+// Overlay / navigation
+export { default as Modal } from './Modal.vue'
+export { default as ModalOnClick } from './ModalOnClick.vue'
+export { default as MenuButton } from './MenuButton.vue'
+export { default as SelectBox } from './SelectBox.vue'
+export type { SelectBoxOption } from './SelectBox.vue'
+
+// Media / collections
+export { default as Gallery } from './Gallery.vue'
+export type { GalleryItem } from './Gallery.vue'
+export { default as ThumbnailGrid } from './ThumbnailGrid.vue'
+export type { ThumbnailGridItem, ThumbnailGridLoader, ThumbnailGridLoaderParams } from './ThumbnailGrid.vue'
+export { default as TreeView } from './TreeView.vue'
+export type { TreeNode, TreeNodeId, TreeLoader } from './TreeView.vue'
+export { default as Accordion } from './Accordion.vue'
+export type { AccordionSection } from './Accordion.vue'
+export { default as useSelection } from './useSelection'
+export { default as RowSelect } from './RowSelect'
+export { default as CircularProgress } from './CircularProgress.vue'
+export { default as downsizeImage } from './downsizeImage'
+export { default as Copy } from './Copy.vue'
+export { copyTextToClipboard } from './copyTextToClipboard'
+
+// Layout shell
+export { default as TheWrap } from './TheWrap.vue'
+export { default as BottomNav } from './BottomNav.vue'
+export type { BottomNavTab } from './BottomNav.vue'
+
+// Gestures
+export { TOUCH_PAN_SLOP_PX } from './touchSlop'
+
+// Small DOM conveniences
+export const scrollToTop = (): void => window.scroll({ top: 0 })
+
+export const focusIn = (el: string | HTMLElement | null, selector?: string): void => {
+    if (el) {
+        let input: Element | null = null
+        if (typeof el === 'string') {
+            input = document.getElementById(el)
+        } else if (selector) {
+            input = el.querySelector(selector)
+        }
+        if (input instanceof HTMLElement && document.activeElement !== input) {
+            input.focus()
+        }
+    }
+}

package/src/messages.ts

@@ -0,0 +1,39 @@
+import { reactive } from 'vue'
+
+// Every user-facing string in this package, overridable in one place. Apps
+// with i18n call configureUiMessages at boot (and again on locale change).
+const defaults = {
+    loading: 'Loading',
+    ok: 'OK',
+    cancel: 'Cancel',
+    close: 'Close',
+    clear: 'Clear',
+    tryAgain: 'Try again',
+    trying: 'Trying...',
+    // {seconds} is replaced with the countdown value at render time.
+    retryCountdown: 'Error. Retrying in {seconds}',
+    toHomePage: 'To the home page',
+    nothingFound: 'Nothing found',
+    searchResults: 'Search results',
+    search: 'Search',
+    create: 'Create',
+    refresh: 'Refresh',
+    delete: 'Delete',
+    deleting: 'Deleting...',
+    newTab: 'New tab',
+    copied: 'Copied',
+    clickToCopy: 'Click to copy',
+    invalidEmail: 'Not a valid email address',
+    selectOption: 'Select an option',
+    errorOther: 'Oops.. Sorry, something went wrong',
+    errorNetwork: 'Looks like a network connectivity issue',
+    errorNotFound: 'The requested page not found'
+}
+
+export type UiMessages = typeof defaults
+
+export const messages: UiMessages = reactive({ ...defaults })
+
+export const configureUiMessages = (overrides: Partial<UiMessages>): void => {
+    Object.assign(messages, overrides)
+}

package/src/modalStack.ts

@@ -0,0 +1,181 @@
+// Module-level modal stack: with nested modals open, Escape and browser
+// history navigation (popstate) must close only the top-most modal, not all of
+// them at once. Modals register their close handler on mount; the shared
+// document/window listeners exist only while at least one modal is open and
+// always act on the top of the stack.
+//
+// The stack also owns modal FOCUS CONFINEMENT (WCAG 2.4.3): while a modal is
+// open, everything outside the top-most modal's root is `inert` (unfocusable,
+// hidden from AT), stray focus is redirected back inside (defence-in-depth for
+// engines with partial inert support, with first/last Tab wrapping), initial
+// focus moves into the modal, and closing restores focus to the invoker.
+// Centralised here — not per-modal — so only the top-most modal ever traps.
+import { hasFinePointer } from '@greendrake/util'
+
+type CloseHandler = () => void
+
+// Where a modal wants focus when it opens: on the field it exists to fill, or
+// on the dialog itself when its fields serve options within it rather than the
+// modal's purpose. This states the modal's INTENT only — whether a field is
+// actually worth focusing also depends on the device (see focusInitial).
+export type InitialFocus = 'field' | 'dialog'
+
+type ModalEntry = {
+    close: CloseHandler
+    root: HTMLElement | null
+    invoker: HTMLElement | null
+}
+
+const stack: ModalEntry[] = []
+const top = (): ModalEntry | undefined => stack[stack.length - 1]
+
+const closeTop = (): void => {
+    top()?.close()
+}
+
+const onKeyUp = (e: KeyboardEvent): void => {
+    if (e.key === 'Escape') {
+        closeTop()
+    }
+}
+
+// In an SPA the router drives route changes off popstate, so a modal left open
+// by stale parent state would otherwise overlay the new page.
+const onPopState = (): void => closeTop()
+
+const FOCUSABLE = 'a[href], button:not([disabled]), input:not([disabled]):not([type="hidden"]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex="-1"])'
+
+const focusables = (root: HTMLElement): HTMLElement[] => [...root.querySelectorAll<HTMLElement>(FOCUSABLE)].filter(n => n.getClientRects().length > 0)
+
+// Fallback focus target when a modal holds no focusable content: its dialog
+// container (carries tabindex="-1").
+const container = (root: HTMLElement): HTMLElement | null => root.querySelector<HTMLElement>('[tabindex="-1"]')
+
+// Initial focus prefers a form field (the reason most modals open) over
+// chrome like the close button, which is first in DOM order. Two things veto
+// that and hand focus to the dialog itself instead: the modal declaring its
+// fields incidental (`initialFocus: 'dialog'`), and a device with no fine
+// pointer. On touch, focusing a field summons the on-screen keyboard — half
+// the viewport gone before the user has asked to type — which is a cost no
+// modal's intent can be worth, so it is decided here rather than at each of
+// them. Focus still moves INTO the modal either way: the trap, the dialog's
+// announcement to assistive tech and the restore-on-close all depend on it
+// (see registerModal), so the touch case redirects focus, never skips it.
+//
+// preventScroll on the open/close focus moves: they are structural, not
+// navigation, and scrolling the page to reveal what the code just focused
+// moves content the reader did not ask to move. The trap's Tab wrap
+// (onFocusIn) deliberately does NOT prevent scroll — that move answers a
+// keypress, and in a sheet with internal overflow the wrapped-to control may
+// sit outside the visible part, where suppressing the reveal would land
+// keyboard focus on something invisible.
+const focusInitial = (root: HTMLElement, initialFocus: InitialFocus): void => {
+    if (initialFocus === 'dialog' || !hasFinePointer()) {
+        container(root)?.focus({ preventScroll: true })
+        return
+    }
+    const all = focusables(root)
+    const target = all.find(n => /^(input|textarea|select)$/i.test(n.tagName)) ?? all[0] ?? container(root)
+    target?.focus({ preventScroll: true })
+}
+
+// Background scroll lock, held while any modal is open. The page behind a
+// modal has no business moving, and on iOS it otherwise does: focusing a field
+// inside the sheet makes WebKit scroll the document to clear the keyboard, and
+// since the sheet is fixed, all that moves is the page under it. Pinning the
+// body is what actually leaves the document unscrollable — `overflow: hidden`
+// propagates between html and body and stops nothing — so the keyboard scrolls
+// the sheet's own overflow instead, which is the thing that should move.
+let lockedAt: number | null = null
+let lockedHref = ''
+const lockScroll = (): void => {
+    lockedAt = window.scrollY
+    lockedHref = location.href
+    // Classic (space-taking) scrollbars: pinning the body leaves the document
+    // unscrollable, which drops its scrollbar and shifts the whole background
+    // by the gutter width. Hold that width as extra body padding for the
+    // lock's duration; overlay scrollbars measure 0 and change nothing.
+    const gutter = window.innerWidth - document.documentElement.clientWidth
+    Object.assign(document.body.style, {
+        position: 'fixed',
+        top: `-${lockedAt}px`,
+        left: '0',
+        right: '0',
+        ...(gutter > 0 && { paddingRight: `${parseFloat(getComputedStyle(document.body).paddingRight) + gutter}px` })
+    })
+}
+const unlockScroll = (): void => {
+    if (lockedAt === null) return
+    Object.assign(document.body.style, {
+        position: '',
+        top: '',
+        left: '',
+        right: '',
+        paddingRight: ''
+    })
+    // Restore the offset only where it still applies: a popstate can navigate
+    // and close the modal in one stroke (unregistration then runs after the
+    // route has changed), and the old page's offset imposed on the new page
+    // would override the browser's own scroll restoration.
+    if (location.href === lockedHref) window.scrollTo(0, lockedAt)
+    lockedAt = null
+}
+
+// Everything outside the top-most modal's root goes inert — including the
+// roots of modals lower in the stack. Only attributes this module set are
+// removed on recompute, so independently-inert content is left alone.
+let inerted: Element[] = []
+const applyInert = (): void => {
+    for (const n of inerted) n.removeAttribute('inert')
+    inerted = []
+    const root = top()?.root
+    if (!root) return
+    for (const child of document.body.children) {
+        if (child !== root && !child.contains(root) && !child.hasAttribute('inert')) {
+            child.setAttribute('inert', '')
+            inerted.push(child)
+        }
+    }
+}
+
+const onFocusIn = (e: FocusEvent): void => {
+    const root = top()?.root
+    if (!root || root.contains(e.target as Node)) return
+    const all = focusables(root)
+    if (!all.length) {
+        container(root)?.focus()
+        return
+    }
+    // Focus escaped: Shift-Tab off the first element wraps to the last;
+    // anything else (Tab off the last, programmatic strays) lands on the first.
+    const target = e.relatedTarget === all[0] ? all[all.length - 1] : all[0]
+    target.focus()
+}
+
+export const registerModal = (close: CloseHandler, root: HTMLElement | null = null, initialFocus: InitialFocus = 'field'): (() => void) => {
+    if (stack.length === 0) {
+        document.addEventListener('keyup', onKeyUp)
+        document.addEventListener('focusin', onFocusIn)
+        window.addEventListener('popstate', onPopState)
+        lockScroll()
+    }
+    const entry: ModalEntry = {
+        close,
+        root,
+        invoker: document.activeElement instanceof HTMLElement ? document.activeElement : null
+    }
+    stack.push(entry)
+    applyInert()
+    if (root) focusInitial(root, initialFocus)
+    return () => {
+        stack.splice(stack.indexOf(entry), 1)
+        if (stack.length === 0) {
+            document.removeEventListener('keyup', onKeyUp)
+            document.removeEventListener('focusin', onFocusIn)
+            window.removeEventListener('popstate', onPopState)
+            unlockScroll()
+        }
+        applyInert()
+        if (entry.invoker?.isConnected) entry.invoker.focus({ preventScroll: true })
+    }
+}

package/src/styles.d.ts

@@ -0,0 +1,6 @@
+// A stylesheet imported for effect resolves to nothing at the type level, and
+// TypeScript 6 checks that it resolves at all (noUncheckedSideEffectImports).
+// Declared here rather than left to the consumer's vite/client: this package
+// ships source, so whatever compiles it — an app, another package, an outside
+// project — must be told what the import means by the package that makes it.
+declare module '*.scss'

package/src/toast/ToastShell.vue

@@ -0,0 +1,70 @@
+<script setup lang="ts">
+import type { ToastVariant } from './showToast'
+
+withDefaults(
+    defineProps<{
+        // Rendered as plain text; rich content arrives as a VNode via showToast.
+        text?: string
+        variant?: ToastVariant
+    }>(),
+    { text: undefined, variant: 'accent' }
+)
+</script>
+<template>
+    <div class="Toast" :class="`Toast--${variant}`">
+        <template v-if="text">{{ text }}</template>
+        <slot v-else />
+    </div>
+</template>
+<style lang="scss">
+@use '@greendrake/scss-kit' as *;
+
+// The shared layer showToast mounts every toast into — one per document, the
+// toasts stacked down from the top in the order they were raised.
+.ToastLayer {
+    position: fixed;
+    // Below the status bar and cutout, not over them. The layer is fixed, so
+    // it sits outside the padding body spends on the same inset — without this
+    // it would render across the clock and battery on a native shell. The
+    // token is 0 in browsers, leaving the gap as it was.
+    top: calc(var(--safe-area-inset-top, 0px) + 10px);
+    left: 0;
+    right: 0;
+    display: flex;
+    flex-direction: column;
+    align-items: center;
+    gap: var(--space-2);
+    pointer-events: none;
+    z-index: z('toast');
+}
+
+.Toast {
+    pointer-events: auto;
+    max-width: min(92vw, 480px);
+    padding: var(--space-3) var(--space-4);
+    border-radius: 8px;
+    color: var(--toast-color, #fff);
+    box-shadow: 0 4px 14px rgb(0 0 0 / 35%);
+    a {
+        color: var(--toast-color, #fff);
+    }
+}
+
+// An ordinary toast reports something that worked; the warning variant is the
+// failure surface, and reads as one at a glance rather than only in its words.
+// `--toast-background` still overrides both, for an app that wants its own.
+.Toast--accent {
+    background-color: var(--toast-background, var(--accent-color));
+}
+
+.Toast--warning {
+    background-color: var(--toast-background, var(--warning-color));
+}
+
+.BlockingOverlay {
+    position: fixed;
+    inset: 0;
+    z-index: z('modal');
+    background-color: rgb(0 0 0 / 25%);
+}
+</style>

package/src/toast/showToast.ts

@@ -0,0 +1,81 @@
+import { h, render, type VNode } from 'vue'
+import ToastShell from './ToastShell.vue'
+
+export interface ToastHandle {
+    destroy: () => void
+}
+
+// What the toast is saying, which decides its colour: `accent` for the ordinary
+// "that worked" report, `warning` for a failure.
+export type ToastVariant = 'accent' | 'warning'
+
+export interface ToastOptions {
+    content: string | VNode
+    // Auto-dismiss on the next user interaction (key press / pointer down)
+    // after the toast appears. Default true; blocking error toasts opt out.
+    hideOnClick?: boolean
+    // Defaults to `accent`: most toasts confirm something, and a failure says
+    // so explicitly rather than every caller restating the ordinary case.
+    variant?: ToastVariant
+    onHidden?: () => void
+}
+
+// The one fixed top-center layer every toast renders into, so toasts raised
+// together stack in the order shown rather than each sitting over the last.
+// Created on first use and kept: it is pointer-transparent, and empty it
+// costs nothing.
+let layer: HTMLElement | null = null
+const toastLayer = (): HTMLElement => {
+    if (!layer) {
+        layer = document.createElement('div')
+        layer.className = 'ToastLayer'
+        document.body.appendChild(layer)
+    }
+    return layer
+}
+
+// Imperative top-center toast. Renders without an app context, so it is
+// callable from stores and plain modules; interactive content arrives as a
+// VNode with its handlers already bound.
+export const showToast = (options: ToastOptions): ToastHandle => {
+    const host = document.createElement('div')
+    toastLayer().appendChild(host)
+    const isText = typeof options.content === 'string'
+    const shellProps = { variant: options.variant ?? 'accent' }
+    const vnode = isText ? h(ToastShell, { ...shellProps, text: options.content as string }) : h(ToastShell, shellProps, { default: () => options.content as VNode })
+    render(vnode, host)
+
+    const destroy = (): void => {
+        detachDismiss()
+        render(null, host)
+        host.remove()
+        options.onHidden?.()
+    }
+
+    let detachDismiss = (): void => {}
+    if (options.hideOnClick !== false) {
+        // Pointer-downs inside ANY toast don't dismiss: destroying at
+        // pointerdown would unmount interactive content (e.g. a link) before
+        // the browser ever synthesizes its click — and destroying a toast
+        // stacked above the one being pressed would shift that one out from
+        // under the pointer, so the click lands elsewhere. Interacting with a
+        // toast is not the interaction that clears the stack.
+        const onInteraction = (e: Event): void => {
+            if (e.target instanceof Node && toastLayer().contains(e.target)) return
+            destroy()
+        }
+        // Attach on the next frame so the interaction that triggered the toast
+        // cannot dismiss it in the same event cycle.
+        const raf = requestAnimationFrame(() => {
+            document.addEventListener('keydown', onInteraction)
+            document.addEventListener('pointerdown', onInteraction)
+        })
+        detachDismiss = () => {
+            cancelAnimationFrame(raf)
+            document.removeEventListener('keydown', onInteraction)
+            document.removeEventListener('pointerdown', onInteraction)
+        }
+    }
+
+    return { destroy }
+}

package/src/touchSlop.ts

@@ -0,0 +1,6 @@
+// Distance a touch/pen pointer must travel before the gesture counts as a
+// deliberate directional move rather than a tap or start-of-gesture jitter —
+// mirrors typical platform touch slop. Its own module so the components that
+// arbitrate gestures (the sheet drag in Modal, the pan in InfiniteScrollTable)
+// share one value without importing each other.
+export const TOUCH_PAN_SLOP_PX = 10

package/src/useSelection.ts

@@ -0,0 +1,99 @@
+import { shallowReactive, type Ref, type ComputedRef } from 'vue'
+
+// Flat, index-addressable multi-selection over an ordered item list: single
+// (replace), ctrl-toggle, shift-range from an anchor, keyboard cursor moves,
+// select-all. The selected Set holds item ids read from items[i][idField].
+export default function useSelection<Id extends string | number>(items: Ref<Record<string, unknown>[]> | ComputedRef<Record<string, unknown>[]>, idField: string) {
+    const selected: Set<Id> = shallowReactive(new Set())
+    let anchor: Id | null = null
+    let cursor: Id | null = null
+
+    function getId(index: number): Id {
+        return items.value[index][idField] as Id
+    }
+
+    function indexOf(id: Id): number {
+        return items.value.findIndex(item => (item[idField] as Id) === id)
+    }
+
+    function addRange(fromId: Id, toId: Id): void {
+        const a = indexOf(fromId)
+        const b = indexOf(toId)
+        if (a === -1 || b === -1) return
+        const [lo, hi] = a <= b ? [a, b] : [b, a]
+        for (let i = lo; i <= hi; i++) selected.add(getId(i))
+    }
+
+    function toggle(id: Id): void {
+        if (selected.has(id)) selected.delete(id)
+        else selected.add(id)
+        anchor = id
+        cursor = id
+    }
+
+    function replace(id: Id): void {
+        selected.clear()
+        selected.add(id)
+        anchor = id
+        cursor = id
+    }
+
+    function rangeTo(id: Id): void {
+        if (anchor === null) {
+            toggle(id)
+            return
+        }
+        selected.clear()
+        addRange(anchor, id)
+        cursor = id
+    }
+
+    /**
+     * Move cursor up or down.
+     * If extend is true (shift held), add to selection.
+     * If extend is false, replace selection with single item.
+     * Returns the new cursor index (useful for scrolling into view), or -1 if no items.
+     */
+    function moveCursor(direction: 'up' | 'down', extend: boolean): number {
+        if (!items.value.length) return -1
+        const max = items.value.length - 1
+        const curIdx = cursor !== null ? indexOf(cursor) : -1
+        const next = direction === 'up' ? Math.max(0, curIdx <= 0 ? 0 : curIdx - 1) : Math.min(max, curIdx === -1 ? 0 : curIdx + 1)
+        const nextId = getId(next)
+
+        if (extend) {
+            selected.add(nextId)
+            cursor = nextId
+            if (anchor === null) anchor = nextId
+        } else {
+            selected.clear()
+            selected.add(nextId)
+            anchor = nextId
+            cursor = nextId
+        }
+        return next
+    }
+
+    function selectAll(): void {
+        for (let i = 0; i < items.value.length; i++) selected.add(getId(i))
+    }
+
+    function clear(): void {
+        selected.clear()
+        anchor = null
+        cursor = null
+    }
+
+    return {
+        selected,
+        getId,
+        indexOf,
+        addRange,
+        toggle,
+        replace,
+        rangeTo,
+        moveCursor,
+        selectAll,
+        clear
+    }
+}

package/src/validationScope.ts

@@ -0,0 +1,6 @@
+import type { InjectionKey, Ref } from 'vue'
+
+// Form components provide a template ref to their root element under this key
+// so descendant TextFields can suppress blur-time validation when focus leaves
+// the form (e.g. user clicks Sign In in the header without completing the form).
+export const validationScopeKey: InjectionKey<Ref<HTMLElement | null>> = Symbol('validationScope')