@greendrake/ui 0.1.0

package/src/AsyncSearch.vue

@@ -0,0 +1,262 @@
+<script lang="ts">
+import type { Ref } from 'vue'
+import type { SearchResultItem } from './AsyncSearchResults.vue'
+
+// isSearching is handed to the search function so it can drive the spinner
+// for exactly the duration of its backend call (e.g. via an api pendingRef).
+export type SearchFunction = (query: string, isSearching: Ref<boolean>) => Promise<SearchResultItem[]>
+</script>
+<script setup lang="ts">
+import { h, inject, ref, watch, onBeforeUnmount, useSlots, type Component } from 'vue'
+import { useTippy } from 'vue-tippy'
+import { randomString } from '@greendrake/util'
+import SearchField from './SearchField.vue'
+import AsyncSearchResults from './AsyncSearchResults.vue'
+import { inModalKey } from './inModal'
+
+const slots = useSlots()
+const query = ref('')
+const emit = defineEmits<{
+    result: [data: SearchResultItem]
+}>()
+const props = withDefaults(
+    defineProps<{
+        search: SearchFunction
+        placeholder?: string
+        autofocus?: boolean
+        itemComponent?: Component | null
+        searchKey?: unknown
+        // Minimum query length before a search fires. Lower it for vocabularies
+        // with legitimately short entries (e.g. two-letter brand names).
+        minQueryLength?: number
+    }>(),
+    {
+        itemComponent: undefined,
+        searchKey: undefined,
+        minQueryLength: 3
+    }
+)
+let searchID: string | undefined
+const isSearching = ref(false)
+// Combobox state for AT: expanded while the results surface is up, with
+// aria-controls tying the input to the (teleported) listbox.
+const expanded = ref(false)
+const listboxId = `async-search-${randomString()}`
+const cmp = ref<InstanceType<typeof SearchField> | null>(null)
+
+// Narrow viewports swap the anchored popper (which clips against small
+// screens and on-screen keyboards) for a full-width results panel. Tracked
+// live so a viewport change mid-session picks the right surface on the NEXT
+// search (the open one is torn down on any change anyway).
+const narrowQuery = window.matchMedia('(max-width: 600px)')
+const isNarrow = ref(narrowQuery.matches)
+const onNarrowChange = (e: MediaQueryListEvent): void => {
+    isNarrow.value = e.matches
+}
+narrowQuery.addEventListener('change', onNarrowChange)
+onBeforeUnmount(() => narrowQuery.removeEventListener('change', onNarrowChange))
+
+// In the page the panel takes the viewport over, pinned under the input. In a
+// modal it stays in flow: the sheet is already the narrow-viewport takeover
+// surface, it paints over anything pinned to the viewport, and when it sits on
+// the bottom edge there is no room under the input to pin to.
+const inModal = inject(inModalKey, false)
+
+// The panel's dataset (null = closed) and, when pinned, its measured top edge.
+const panelResults = ref<SearchResultItem[] | null>(null)
+const panelTop = ref(0)
+
+let destroyTippy: (() => void) | null = null
+let hideTippy: (() => void) | null = null
+const closeResults = () => {
+    if (destroyTippy) {
+        destroyTippy()
+        destroyTippy = null
+        hideTippy = null
+    }
+    panelResults.value = null
+    expanded.value = false
+}
+const clear = () => {
+    query.value = ''
+    closeResults()
+}
+onBeforeUnmount(closeResults)
+const isValidQuery = (q: string): boolean => !!q && q.length >= props.minQueryLength
+
+const onPick = (data: SearchResultItem) => {
+    emit('result', data)
+}
+
+const executeSearch = async () => {
+    closeResults()
+    if (!isValidQuery(query.value)) {
+        return
+    }
+    searchID = randomString()
+    const currentSearchId = searchID
+    const data = await props.search(query.value, isSearching)
+    // Race guard: if a new search started while this one was in flight, its
+    // results are stale — drop them and let the newer search present its own.
+    closeResults()
+    if (currentSearchId === searchID && !!query.value) {
+        if (isNarrow.value) {
+            // Full-width panel under the input (F9/F14) — rendered in this
+            // component's template, so the footer slot and pick handling are
+            // shared with the popper path.
+            if (!inModal) {
+                panelTop.value = (cmp.value?.$el as HTMLElement | undefined)?.getBoundingClientRect().bottom ?? 0
+            }
+            panelResults.value = data
+            expanded.value = true
+            return
+        }
+        const { destroy, hide: tippyHide } = useTippy(cmp, {
+            theme: 'asyncSearchResults',
+            trigger: 'manual',
+            // The popper is a listbox surface, not a tooltip; keep tippy from
+            // stamping tooltip semantics/aria onto it or the input.
+            role: 'presentation',
+            aria: { content: null, expanded: false },
+            maxWidth: 'none',
+            placement: 'bottom-start',
+            offset: [0, -1],
+            arrow: false,
+            showOnCreate: true,
+            interactive: true,
+            content: h(
+                AsyncSearchResults,
+                {
+                    data,
+                    listboxId,
+                    itemComponent: props.itemComponent,
+                    // Only surface the pick — don't clear here. What happens next is the
+                    // consumer's call (navigate, close, or clear via the exposed clear());
+                    // the results stay put until the query changes or this component
+                    // unmounts (e.g. when a navigation the pick triggered finally commits).
+                    onPick
+                },
+                // The popper renders outside the app's render tree, so the host's
+                // slots are handed to the vnode explicitly: default = the footer
+                // strip, empty = the host's own zero-result surface.
+                {
+                    ...(slots['resultsFooter'] ? { default: slots['resultsFooter'] } : {}),
+                    ...(slots['empty'] ? { empty: slots['empty'] } : {})
+                }
+            )
+        })
+        destroyTippy = destroy
+        hideTippy = tippyHide
+        expanded.value = true
+    }
+}
+
+// Enter forces an immediate search on the current input. flush() commits the
+// un-debounced value and cancels any pending debounced update; if that changed the
+// query, the watcher below runs the search — so only re-trigger here when it did
+// not (the re-summon-after-dismissal case), avoiding a double search.
+const onEnter = () => {
+    if (!cmp.value?.flush()) {
+        executeSearch()
+    }
+}
+
+watch(query, async v => {
+    closeResults()
+    if (isValidQuery(v)) {
+        await executeSearch()
+    }
+})
+
+// Re-run search when searchKey changes (if there's a valid query)
+watch(
+    () => props.searchKey,
+    async () => {
+        if (isValidQuery(query.value)) {
+            await executeSearch()
+        }
+    }
+)
+// Dismiss the results popper WITHOUT clearing the query (unlike clear) — keeps the
+// query intact so a footer action that reads it (e.g. "Save this search") still works,
+// and stops the popper from covering any modal that action opens.
+const hide = () => hideTippy?.()
+defineExpose({
+    clear,
+    hide
+})
+</script>
+<template>
+    <div class="AsyncSearch" @keydown.enter.prevent="onEnter">
+        <!-- Enter searches the current input immediately and can re-summon the results
+             box after it was dismissed (e.g. by refocusing the field), which otherwise
+             needs editing the query. See onEnter; .prevent stops a stray form submit.
+             Listener on the root div (not the SearchField component) so it fires once,
+             free of attribute fallthrough. A root-level comment would make this a
+             fragment in dev builds (breaking $el consumers), hence it sits inside. -->
+        <SearchField v-bind="{ ...$attrs, role: 'combobox', 'aria-autocomplete': 'list', 'aria-expanded': expanded ? 'true' : 'false', 'aria-controls': listboxId }" ref="cmp" v-model="query" :placeholder="placeholder" :autofocus="autofocus" :class="{ spinner: isSearching }" :debounce="true" />
+        <!-- Teleported only when pinned to the viewport; in a modal the panel is
+             left in flow, inside the sheet (and inside its focus/inert scope). -->
+        <Teleport to="body" :disabled="inModal">
+            <div v-if="panelResults" class="AsyncSearch__panel" :class="{ 'AsyncSearch__panel--pinned': !inModal }" :style="inModal ? undefined : { top: `${panelTop}px` }" @keydown.esc="closeResults">
+                <AsyncSearchResults :data="panelResults" :listbox-id="listboxId" :item-component="itemComponent" @pick="onPick">
+                    <!-- Forwarded only when the host actually supplies it, so an
+                         empty pass-through can't shadow the default message. -->
+                    <template v-if="$slots.empty" #empty><slot name="empty" /></template>
+                    <slot name="resultsFooter" />
+                </AsyncSearchResults>
+            </div>
+        </Teleport>
+    </div>
+</template>
+<style lang="scss">
+@use './shared' as *;
+@use '@greendrake/scss-kit' as *;
+.AsyncSearch {
+    position: relative;
+
+    &__panel {
+        background: var(--background-color);
+        border-top: 1px solid var(--border-color);
+
+        // Pinned variant: takes the viewport over from the input's bottom edge
+        // down to the bottom nav, so the whole remaining screen is results.
+        &--pinned {
+            position: fixed;
+            left: 0;
+            right: 0;
+            bottom: calc(var(--bottomnav-height, 0px) + var(--safe-area-inset-bottom, 0px));
+            z-index: z('sticky');
+            overflow-y: auto;
+            .AsyncSearchResults {
+                max-height: none;
+            }
+        }
+    }
+    .SearchField {
+        position: relative;
+        &.spinner::before {
+            @include spinner-inline-right(28px);
+        }
+    }
+    div[data-tippy-root] {
+        width: 100%;
+        cursor: default;
+    }
+    .tippy-box[data-theme~='asyncSearchResults'] {
+        background-color: var(--background-color);
+        border: 1px solid var(--border-color);
+        color: var(--font-color);
+        // The popper reads as the field's continuation, so it takes the field's
+        // corner — and clips to it: the result rows and the host's footer paint
+        // their own opaque backgrounds out to the edge and would square the
+        // corners off again. Nothing to lose by clipping (this theme has no
+        // arrow, and the result list scrolls inside its own box).
+        border-radius: var(--border-radius);
+        overflow: hidden;
+        .tippy-content {
+            padding: 0;
+        }
+    }
+}
+</style>

package/src/AsyncSearchResults.vue

@@ -0,0 +1,74 @@
+<script lang="ts">
+export interface SearchResultItem {
+    id: string
+    // Rendered via v-html by the default item renderer — hence the explicit
+    // name; build it only from trusted/escaped content. A custom itemComponent
+    // may render whatever fields the item carries instead.
+    // Required by the default renderer (rendered via v-html — supply
+    // trusted/escaped markup); irrelevant when the host passes itemComponent.
+    htmlTitle?: string
+    [key: string]: unknown
+}
+</script>
+<script setup lang="ts">
+import type { Component } from 'vue'
+import { messages } from './messages'
+
+withDefaults(
+    defineProps<{
+        data: SearchResultItem[]
+        itemComponent?: Component | null
+        // The listbox element id the host input's aria-controls points at.
+        listboxId?: string
+    }>(),
+    {
+        itemComponent: null,
+        listboxId: undefined
+    }
+)
+const emit = defineEmits<{
+    pick: [data: SearchResultItem]
+}>()
+const onClick = (data: SearchResultItem) => emit('pick', data)
+</script>
+<template>
+    <div class="AsyncSearchResults">
+        <div v-if="data.length" :id="listboxId" role="listbox" tabindex="0" :aria-label="messages.searchResults">
+            <div v-for="d in data" :key="d.id" class="AsyncSearchResults__Result" role="option" :aria-selected="false" @click="onClick(d)">
+                <component :is="itemComponent" v-if="itemComponent" :data="d" />
+                <span v-else v-html="d.htmlTitle ?? ''" />
+            </div>
+        </div>
+        <!-- Hosts that can do better than "nothing found" — offer near-misses,
+             an alert, a way to create what is missing — fill the empty slot. -->
+        <slot v-else name="empty">
+            <div class="AsyncSearchResults__Result nothingFound">{{ messages.nothingFound }}</div>
+        </slot>
+        <slot />
+    </div>
+</template>
+<style lang="scss">
+.AsyncSearchResults {
+    max-height: 200px;
+    display: flex;
+    border-radius: var(--border-radius);
+    flex-direction: column;
+    > div:first-child {
+        overflow-y: auto;
+    }
+    &__Result {
+        padding: var(--space-2);
+        background-color: var(--form-background);
+        &:not(:last-child) {
+            border-bottom: 1px solid var(--border-color-light);
+        }
+        cursor: default;
+        &:hover {
+            background-color: var(--form-background-hover);
+        }
+        &.nothingFound {
+            padding: var(--space-2);
+        }
+    }
+}
+</style>

package/src/BottomNav.vue

@@ -0,0 +1,125 @@
+<script lang="ts">
+export interface BottomNavTab {
+    id: string
+    label: string
+    // The route this tab navigates to. Omit for a tab that acts on the app
+    // shell instead of navigating — an overlay whose existence is a property of
+    // the viewport, not of the URL. Such a tab renders as a button and reports
+    // its state through `select` + aria-expanded rather than aria-current.
+    to?: string
+    // Marks this tab active. The app owns the mapping (a tab usually covers a
+    // family of routes, not one path), so it is a plain flag, not a matcher.
+    active: boolean
+    // Optional attention count rendered as a badge on the tab icon.
+    badge?: number
+}
+</script>
+<script setup lang="ts">
+import { RouterLink } from 'vue-router'
+defineProps<{ tabs: BottomNavTab[] }>()
+const emit = defineEmits<{ select: [id: string] }>()
+</script>
+<template>
+    <!-- Fixed bottom tab bar for narrow viewports. Apps style the per-tab icon
+         via the .BottomNav__icon--<id> class hook (mask-image pattern) and hide
+         the bar on wide viewports; the safe-area inset is honoured here so the
+         bar clears the home indicator in native shells. The badge is a sibling
+         of the masked icon, not a child — a mask clips its descendants. -->
+    <nav class="BottomNav">
+        <component
+            :is="tab.to ? RouterLink : 'button'"
+            v-for="tab in tabs"
+            :key="tab.id"
+            :to="tab.to"
+            :type="tab.to ? undefined : 'button'"
+            class="BottomNav__tab"
+            :class="{ 'BottomNav__tab--active': tab.active }"
+            :aria-current="tab.to && tab.active ? 'page' : undefined"
+            :aria-expanded="tab.to ? undefined : tab.active"
+            @click="tab.to || emit('select', tab.id)"
+        >
+            <span class="BottomNav__glyph" aria-hidden="true">
+                <span class="BottomNav__icon" :class="`BottomNav__icon--${tab.id}`"></span>
+                <span v-if="tab.badge" class="BottomNav__badge">{{ tab.badge }}</span>
+            </span>
+            <span class="BottomNav__label">{{ tab.label }}</span>
+        </component>
+        <!-- Trailing cell for something that is not navigation: a page's own
+             actions, which on a narrow viewport have nowhere else persistent to
+             live. Empty on every page that offers none, and the tabs take the
+             whole bar then — so a page with actions narrows them, which is the
+             cost of not reserving a cell nothing usually fills. -->
+        <slot />
+    </nav>
+</template>
+<style lang="scss">
+@use '@greendrake/scss-kit' as *;
+.BottomNav {
+    position: fixed;
+    left: 0;
+    right: 0;
+    bottom: 0;
+    z-index: z('sticky');
+    display: flex;
+    height: calc(var(--bottomnav-height) + var(--safe-area-inset-bottom, 0px));
+    padding-bottom: var(--safe-area-inset-bottom, 0px);
+    background: var(--form-background);
+    border-top: 1px solid var(--border-color-light);
+    &__tab {
+        flex: 1 1 0;
+        display: flex;
+        flex-direction: column;
+        align-items: center;
+        justify-content: center;
+        gap: 2px;
+        color: var(--font-color-muted, var(--font-color));
+        text-decoration: none;
+        // A tab is a link or, when it opens a shell overlay, a button — which
+        // arrives with a UA background, border and font of its own.
+        background: none;
+        border: none;
+        font: inherit;
+        cursor: pointer;
+        &--active {
+            color: var(--accent-color);
+            .BottomNav__icon {
+                background-color: var(--accent-color);
+            }
+        }
+    }
+    &__glyph {
+        position: relative;
+        width: 24px;
+        height: 24px;
+    }
+    &__icon {
+        @include icon-base;
+        display: block;
+        width: 100%;
+        height: 100%;
+        mask-position: center center;
+        background-color: var(--font-color-muted, var(--font-color));
+    }
+    &__badge {
+        position: absolute;
+        top: -6px;
+        right: -10px;
+        background: var(--color-attention-fill, var(--accent-color));
+        color: var(--color-attention-contrast, #fff);
+        border-radius: 999px;
+        padding: 0 5px;
+        font-size: 11px;
+        line-height: 16px;
+        min-width: 16px;
+        text-align: center;
+    }
+    &__label {
+        font-size: var(--font-xs);
+        line-height: 1;
+        // Follow the tab's own colour (muted when inactive, accent when active).
+        // Without this the theme's global `a span` link tint paints every label
+        // violet, so the active/inactive distinction collapses to just the icon.
+        color: inherit;
+    }
+}
+</style>

package/src/Checkbox.vue

@@ -0,0 +1,112 @@
+<script setup lang="ts">
+import { computed } from 'vue'
+import { randomString } from '@greendrake/util'
+
+const props = defineProps<{
+    label?: string
+    // Render as an iOS-style sliding switch instead of the default tick box.
+    switch?: boolean
+    disabled?: boolean
+}>()
+
+const value = defineModel<boolean>()
+const id = randomString('checkbox')
+const cls = computed(() => ['Checkbox', { 'Checkbox--switch': props.switch }])
+</script>
+<template>
+    <div :class="cls">
+        <input :id="id" v-model="value" type="checkbox" :disabled="props.disabled" />
+        <label v-if="props.label" :for="id">{{ props.label }}</label>
+    </div>
+</template>
+<style lang="scss">
+.Checkbox {
+    display: flex;
+    align-items: center;
+    gap: var(--space-2);
+    // 24px minimum: WCAG 2.5.8 target size (the box itself is the target).
+    --checkbox-size: 24px;
+
+    &:not(.Checkbox--switch) {
+        input[type='checkbox'] {
+            padding: 0;
+            appearance: none;
+            -webkit-appearance: none;
+            // Grid-centre the tick glyph — fixed margins would drift off
+            // centre the moment the size token changes.
+            display: grid;
+            place-content: center;
+            width: var(--checkbox-size);
+            height: var(--checkbox-size);
+            max-width: var(--checkbox-size);
+            max-height: var(--checkbox-size);
+            min-width: var(--checkbox-size);
+            min-height: var(--checkbox-size);
+            border: 1px solid var(--border-color);
+            border-radius: var(--border-radius);
+            background: var(--input-background);
+            cursor: default;
+        }
+
+        input[type='checkbox']:checked::after {
+            content: '';
+            width: 6px;
+            height: 10px;
+            border: solid var(--font-color);
+            border-width: 0 2px 2px 0;
+            // The ink is the glyph box's right+bottom strokes, so the rotated
+            // tick reads below/right of the geometric centre; the margin
+            // biases the box up to optical centre.
+            margin-bottom: 3px;
+            transform: rotate(45deg);
+        }
+    }
+
+    // iOS-style sliding switch: a pill track with a knob that slides to the right
+    // and the track turns accent-coloured when checked.
+    &.Checkbox--switch {
+        --switch-width: 40px;
+        --switch-height: 24px;
+        --switch-knob: calc(var(--switch-height) - 4px);
+
+        input[type='checkbox'] {
+            position: relative;
+            padding: 0;
+            appearance: none;
+            -webkit-appearance: none;
+            width: var(--switch-width);
+            min-width: var(--switch-width);
+            height: var(--switch-height);
+            border: none;
+            border-radius: var(--switch-height);
+            background: var(--border-color);
+            transition: background 0.2s ease;
+        }
+
+        input[type='checkbox']::after {
+            content: '';
+            position: absolute;
+            top: 2px;
+            left: 2px;
+            width: var(--switch-knob);
+            height: var(--switch-knob);
+            border-radius: 50%;
+            background: #fff;
+            transition: transform 0.2s ease;
+        }
+
+        input[type='checkbox']:checked {
+            background: var(--accent-color);
+        }
+
+        input[type='checkbox']:checked::after {
+            transform: translateX(calc(var(--switch-width) - var(--switch-height)));
+        }
+    }
+
+    input[type='checkbox']:disabled {
+        opacity: 0.5;
+        cursor: not-allowed;
+    }
+}
+</style>

package/src/CircularProgress.vue

@@ -0,0 +1,57 @@
+<script lang="ts">
+// Geometry is static: r=16 inside a 36×36 viewBox leaves headroom for the 3px
+// stroke (16 + 1.5 = 17.5 < 18). Kept at module scope so it isn't rebuilt per
+// instance.
+const RADIUS = 16
+const CIRCUMFERENCE = 2 * Math.PI * RADIUS
+</script>
+<script setup lang="ts">
+import { computed } from 'vue'
+
+const props = defineProps<{ progress: number }>()
+
+const clamped = computed(() => Math.max(0, Math.min(100, props.progress)))
+// Full circumference at 0%, zero at 100% — the dash grows clockwise from the
+// top (the arc circle is rotated -90deg in CSS).
+const dashOffset = computed(() => CIRCUMFERENCE * (1 - clamped.value / 100))
+</script>
+<template>
+    <svg class="CircularProgress" viewBox="0 0 36 36" role="progressbar" :aria-valuenow="Math.round(clamped)" aria-valuemin="0" aria-valuemax="100">
+        <circle class="CircularProgress__track" cx="18" cy="18" :r="RADIUS" />
+        <circle class="CircularProgress__arc" cx="18" cy="18" :r="RADIUS" :stroke-dasharray="CIRCUMFERENCE" :stroke-dashoffset="dashOffset" />
+        <text class="CircularProgress__label" x="18" y="18">{{ Math.round(clamped) }}%</text>
+    </svg>
+</template>
+<style lang="scss">
+.CircularProgress {
+    width: 100%;
+    height: 100%;
+    display: block;
+
+    &__track,
+    &__arc {
+        fill: none;
+        stroke-width: 3;
+    }
+
+    &__track {
+        stroke: var(--circular-progress-track, #c2c6cc);
+    }
+
+    &__arc {
+        stroke: var(--circular-progress-arc, #2ea043);
+        stroke-linecap: round;
+        transform: rotate(-90deg);
+        transform-origin: 50% 50%;
+        transition: stroke-dashoffset 0.15s linear;
+    }
+
+    &__label {
+        fill: var(--circular-progress-label, #fff);
+        font-size: 9px;
+        font-weight: 600;
+        text-anchor: middle;
+        dominant-baseline: central;
+    }
+}
+</style>

package/src/Copy.vue

@@ -0,0 +1,51 @@
+<script setup lang="ts">
+import { copyTextToClipboard } from './copyTextToClipboard'
+import { messages } from './messages'
+
+const props = withDefaults(
+    defineProps<{
+        value: string
+        showValue?: boolean
+    }>(),
+    {
+        showValue: false
+    }
+)
+
+const onClick = async (e: MouseEvent) => {
+    e.preventDefault()
+    const target = e.currentTarget as HTMLElement
+    await copyTextToClipboard(props.value)
+    target.classList.add('copied')
+    setTimeout(() => {
+        if (document.body.contains(target)) {
+            target.classList.remove('copied')
+        }
+    }, 2000)
+}
+</script>
+<template>
+    <div class="Copy2Clipboard" :title="messages.clickToCopy" @click="onClick">
+        <span v-if="showValue" class="Copy2Clipboard__value">{{ value }}</span>
+    </div>
+</template>
+<style lang="scss">
+@use '@greendrake/scss-kit' as *;
+.Copy2Clipboard {
+    cursor: default;
+    display: inline-flex;
+    align-items: center;
+    gap: 4px;
+    &::before {
+        content: '';
+        @include icon;
+        @include i('copy');
+    }
+    &:hover::before {
+        background-color: orange;
+    }
+    &.copied::before {
+        background-color: green;
+    }
+}
+</style>