@greendrake/ui 0.1.0

package/src/TextField.vue

@@ -0,0 +1,116 @@
+<script setup lang="ts">
+import { computed, ref, watch, onMounted, inject, type Component } from 'vue'
+import { hasFinePointer } from '@greendrake/util'
+import FieldTip from './FieldTip'
+import FixAndroidTyping from './FixAndroidTyping'
+import { validationScopeKey } from './validationScope'
+
+const input = ref<HTMLInputElement | HTMLTextAreaElement | null>(null)
+const error = ref<string | false>(false)
+// Blank input yields '' — the model is always a string, never undefined.
+// When a validator is set, the model likewise falls back to '' while the
+// typed value is invalid.
+const model = defineModel<string>({ default: '' })
+const props = withDefaults(
+    defineProps<{
+        autofocus?: boolean
+        // Lands on the input so focusIn(id) / <label for> can target it.
+        id?: string
+        type?: string
+        placeholder?: string
+        // Accessible name when no visible label is associated; defaults to the
+        // placeholder so a placeholder-only field always names itself.
+        ariaLabel?: string
+        validator?: (v: string) => true | string
+        validateOnBlur?: boolean
+        // The rich-text editor component rendered when type === 'rich'. It must
+        // speak the same string v-model contract as this field. Supplied by the
+        // consumer (see @greendrake/ui-rich) so tiptap is bundled only where
+        // rich editing is actually used. Init-time contract: read once below.
+        richEditor?: Component
+    }>(),
+    {
+        type: 'text',
+        validateOnBlur: true
+    }
+)
+if (props.type === 'rich' && !props.richEditor) {
+    throw new Error('TextField: type="rich" requires the richEditor prop')
+}
+const richEditor = props.richEditor
+const inputValue = ref(model.value)
+const isInputHere = computed(() => input.value && input.value.isConnected)
+const validationScope = inject(validationScopeKey, null)
+const onLeave = (e: FocusEvent) => {
+    const validator = props.validator
+    if (!validator || !props.validateOnBlur) return
+    // When a form provides a validation scope, suppress validation if focus
+    // is leaving that scope entirely (clicked outside the form, or onto
+    // unfocusable content). Validate only when focus stays within the form.
+    const scopeEl = validationScope?.value
+    if (scopeEl) {
+        const next = e.relatedTarget as Node | null
+        if (!next || !scopeEl.contains(next)) return
+    }
+    // this event may be triggered by destroying the housing component, in which case
+    // there is no need to validate/set tips.
+    // Verify that the element is still part of DOM after a small delay:
+    const valueAtBlur = inputValue.value
+    setTimeout(() => {
+        // Skip validation if the value changed since blur (e.g. form reset due
+        // to navigation) or the field is empty (an untouched/emptied field
+        // should not nag on its way out).
+        if (isInputHere.value && inputValue.value === valueAtBlur && inputValue.value !== '') {
+            const validationResult = validator(inputValue.value)
+            if (true !== validationResult) {
+                error.value = validationResult
+            }
+        }
+    }, 200)
+}
+let ignoreModelChange = false
+watch(inputValue, () => {
+    if (error.value !== false) {
+        error.value = false
+    }
+    const modelValue = !props.validator || props.validator(inputValue.value) === true ? inputValue.value : ''
+    if (modelValue !== model.value) {
+        ignoreModelChange = true
+        model.value = modelValue
+    }
+})
+watch(model, m => {
+    if (ignoreModelChange) {
+        ignoreModelChange = false
+    } else if (inputValue.value !== m) {
+        inputValue.value = m
+    }
+})
+FieldTip(error, input)
+// Pointer devices only: there, landing in the field is a free head start and the
+// whole surface stays visible. On touch it would summon the on-screen keyboard
+// over the content the user came to read, before they asked to type.
+if (props.autofocus && hasFinePointer()) {
+    onMounted(() => {
+        setTimeout(() => {
+            // Only claim focus when nothing else has it. Otherwise a delayed
+            // autofocus can race against a modal that opened after this field
+            // mounted and steal focus mid-interaction (e.g. between Playwright's
+            // .fill focus step and its keyboard.insertText step).
+            if (isInputHere.value && input.value && document.activeElement === document.body) {
+                input.value.focus()
+            }
+        }, 300)
+    })
+}
+const onInput = () => FixAndroidTyping(input, inputValue)
+const focus = () => {
+    if (isInputHere.value && input.value) input.value.focus()
+}
+defineExpose({ focus })
+</script>
+<template>
+    <textarea v-if="type === 'textarea'" :id="id" ref="input" v-model="inputValue" :placeholder="placeholder" :aria-label="ariaLabel ?? placeholder" spellcheck="false" @blur="onLeave" @input="onInput" />
+    <component :is="richEditor!" v-else-if="type === 'rich'" v-model="inputValue" :aria-label="ariaLabel" />
+    <input v-else :id="id" ref="input" v-model="inputValue" :type="type" :placeholder="placeholder" :aria-label="ariaLabel ?? placeholder" spellcheck="false" @blur="onLeave" @input="onInput" />
+</template>

package/src/TheWrap.vue

@@ -0,0 +1,30 @@
+<template>
+    <div class="TheWrap">
+        <div class="TheWrap__content">
+            <slot name="top" />
+            <slot />
+        </div>
+        <slot name="bottom" />
+    </div>
+</template>
+<style lang="scss" scoped>
+// Page layout shell: `top` slot + routed content stretch, the `bottom` slot
+// (footer) is pushed to the viewport bottom on short pages. When only a single
+// child renders (e.g. a splash), it is centered vertically instead.
+// CSS contract: --max-content-width (optional) caps the shell's width; without
+// it the shell spans its container.
+.TheWrap {
+    width: 100%;
+    max-width: var(--max-content-width, none);
+    min-height: 100%;
+    display: flex;
+    flex-direction: column;
+    justify-content: space-between;
+    &__content {
+        flex: 1 0 auto;
+    }
+    &:has(> :only-child) {
+        justify-content: center;
+    }
+}
+</style>

package/src/ThumbnailGrid.vue

@@ -0,0 +1,166 @@
+<script lang="ts">
+import type { Ref } from 'vue'
+
+export type ThumbnailGridItem = Record<string, unknown>
+
+export interface ThumbnailGridLoaderParams {
+    offset: number
+    limit: number
+    [key: string]: unknown
+}
+
+export type ThumbnailGridLoader = (params: ThumbnailGridLoaderParams, loading: Ref<boolean>) => Promise<{ data: ThumbnailGridItem[]; total: number }>
+</script>
+<script setup lang="ts">
+// Paged, multi-select thumbnail grid. Backed by the same loader contract as
+// the data table ((params, loading) => { data, total }) so a host can feed
+// both views from one closure. Selection is a v-model array of id values. Reloads
+// whenever `filters` changes (host puts its filter signature there).
+import { ref, watch, onMounted } from 'vue'
+import { messages } from './messages'
+
+const props = withDefaults(
+    defineProps<{
+        loader: ThumbnailGridLoader
+        filters?: Record<string, unknown>
+        thumbnailField?: string
+        titleField?: string
+        idField?: string
+        pageSize?: number
+    }>(),
+    {
+        filters: () => ({}),
+        thumbnailField: 'thumbnail',
+        titleField: 'title',
+        idField: 'node_id',
+        pageSize: 24
+    }
+)
+
+const selected = defineModel<Array<string | number>>('selected', { default: () => [] })
+
+const items = ref<ThumbnailGridItem[]>([])
+const total = ref(0)
+const offset = ref(0)
+const loading = ref(false)
+
+// The item fields are addressed by configurable names, so their types are the
+// grid's contract rather than the item type's: id is a string/number key,
+// thumbnail a URL string, title display text.
+const idOf = (item: ThumbnailGridItem) => item[props.idField] as string | number
+const thumbnailOf = (item: ThumbnailGridItem) => item[props.thumbnailField] as string
+const titleOf = (item: ThumbnailGridItem) => item[props.titleField] as string
+
+async function load() {
+    const res = await props.loader(
+        {
+            offset: offset.value,
+            limit: props.pageSize,
+            ...props.filters
+        },
+        loading
+    )
+    items.value = res.data
+    total.value = res.total
+}
+
+function refresh() {
+    offset.value = 0
+    load()
+}
+
+watch(
+    () => props.filters,
+    () => {
+        offset.value = 0
+        load()
+    },
+    { deep: true }
+)
+watch(offset, load)
+onMounted(load)
+
+function toggle(id: string | number) {
+    selected.value = selected.value.includes(id) ? selected.value.filter(x => x !== id) : [...selected.value, id]
+}
+
+function end() {
+    return Math.min(offset.value + props.pageSize, total.value)
+}
+function prev() {
+    if (offset.value > 0) offset.value = Math.max(0, offset.value - props.pageSize)
+}
+function next() {
+    if (end() < total.value) offset.value += props.pageSize
+}
+
+defineExpose({ refresh })
+</script>
+<template>
+    <div class="ThumbnailGrid" :class="{ spinner: loading }">
+        <div class="ThumbnailGrid__tiles">
+            <div v-for="item in items" :key="idOf(item)" class="ThumbnailGrid__tile" :class="{ selected: selected.includes(idOf(item)) }" @click="toggle(idOf(item))">
+                <img class="ThumbnailGrid__img" :src="thumbnailOf(item)" :alt="titleOf(item)" />
+                <div class="ThumbnailGrid__title">{{ titleOf(item) }}</div>
+            </div>
+            <div v-if="!items.length" class="ThumbnailGrid__empty">{{ messages.nothingFound }}</div>
+        </div>
+        <div class="ThumbnailGrid__pager">
+            <button type="button" :disabled="offset === 0" @click="prev">‹</button>
+            <span class="ThumbnailGrid__range">{{ total ? offset + 1 : 0 }}–{{ end() }} / {{ total }}</span>
+            <button type="button" :disabled="end() >= total" @click="next">›</button>
+        </div>
+    </div>
+</template>
+<style lang="scss">
+.ThumbnailGrid {
+    display: flex;
+    flex-direction: column;
+    min-height: 0;
+    &__tiles {
+        flex-grow: 1;
+        overflow-y: auto;
+        display: grid;
+        grid-template-columns: repeat(auto-fill, minmax(120px, 1fr));
+        gap: var(--space-2);
+        padding: var(--space-2);
+        align-content: start;
+    }
+    &__tile {
+        border: 1px solid var(--border-color-light);
+        border-radius: var(--border-radius);
+        overflow: hidden;
+        cursor: default;
+        &.selected {
+            border-color: var(--border-color-hover);
+            outline: 2px solid var(--border-color-hover);
+        }
+    }
+    &__img {
+        display: block;
+        width: 100%;
+        aspect-ratio: 1;
+        object-fit: cover;
+        background: var(--form-background);
+    }
+    &__title {
+        padding: var(--space-1);
+        font-size: var(--font-xs);
+        white-space: nowrap;
+        overflow: hidden;
+        text-overflow: ellipsis;
+    }
+    &__empty {
+        padding: var(--space-4);
+        opacity: 0.6;
+    }
+    &__pager {
+        display: flex;
+        align-items: center;
+        justify-content: center;
+        gap: var(--space-2);
+        padding: var(--space-1);
+        border-top: 1px solid var(--border-color-light);
+    }
+}
+</style>

package/src/TreeView.vue

@@ -0,0 +1,308 @@
+<script lang="ts">
+// Node shape (whatever the loader returns) must carry at least:
+//   - [idField]    (default 'key')   — unique string/number id
+//   - [labelField] (default 'title') — display text
+//   - expandable                     — whether it has children to load
+export interface TreeNode {
+    expandable: boolean
+    [key: string]: unknown
+}
+
+export type TreeNodeId = string | number
+
+// loader(parentId | null) => Promise<TreeNode[]>  (null → root level)
+export type TreeLoader = (parentId: TreeNodeId | null) => Promise<TreeNode[]>
+
+type Guide = 'through' | 'blank' | 'elbow' | 'elbow-last'
+
+type VisibleEntry = {
+    id: TreeNodeId
+    node: TreeNode
+    depth: number
+    expandable: boolean
+    guides: Guide[]
+}
+</script>
+<script setup lang="ts">
+// Generic lazy tree. Children are loaded on demand via `loader` and cached per
+// node; expanding/collapsing only re-walks the cache. The whole tree is rendered
+// as one flat list of the currently-visible nodes (each carrying its depth), so
+// selection is a flat, index-addressable problem handled by the shared
+// useSelection composable — the same one the data table uses. Selection is
+// mouse-driven (click = single, shift = range, ctrl/cmd = toggle); there are no
+// checkboxes. The selected node ids are exposed as a v-model array.
+import { ref, computed, reactive, watch, onMounted } from 'vue'
+import useSelection from './useSelection'
+
+const props = withDefaults(
+    defineProps<{
+        loader: TreeLoader
+        idField?: string
+        labelField?: string
+        multiSelect?: boolean
+    }>(),
+    {
+        idField: 'key',
+        labelField: 'title',
+        multiSelect: true
+    }
+)
+
+const selected = defineModel<TreeNodeId[]>('selected', { default: () => [] })
+
+const roots = ref<TreeNode[]>([])
+const loading = ref(false)
+// id -> child node[]; presence means "already loaded".
+const childrenCache = reactive(new Map<TreeNodeId, TreeNode[]>())
+const expanded = reactive(new Set<TreeNodeId>())
+const childLoading = reactive(new Set<TreeNodeId>())
+
+// Depth-first flatten of every currently-visible node. This ordered list is both
+// what the template renders and the index space useSelection operates on (range
+// selection walks contiguous entries here).
+//
+// Each entry also carries the `guides` it needs to draw the connector lines: one
+// cell per indentation column. `ancestorVerticals[i]` (threaded down the walk)
+// says whether the ancestor sitting in column i still has a sibling below — i.e.
+// whether a vertical line passes through this row at that column. The node's own
+// (rightmost) column is the elbow: '├' when more siblings follow, '└' when last.
+const visibleNodes = computed(() => {
+    const out: VisibleEntry[] = []
+    const walk = (nodes: TreeNode[], depth: number, ancestorVerticals: boolean[]) => {
+        nodes.forEach((node, idx) => {
+            const id = node[props.idField] as TreeNodeId
+            const isLast = idx === nodes.length - 1
+            const guides: Guide[] = ancestorVerticals.map(v => (v ? 'through' : 'blank'))
+            if (depth > 0) guides.push(isLast ? 'elbow-last' : 'elbow')
+            out.push({
+                id,
+                node,
+                depth,
+                expandable: node.expandable,
+                guides
+            })
+            const children = childrenCache.get(id)
+            if (expanded.has(id) && children) {
+                walk(children, depth + 1, depth === 0 ? [] : [...ancestorVerticals, !isLast])
+            }
+        })
+    }
+    walk(roots.value, 0, [])
+    return out
+})
+
+const selection = useSelection<TreeNodeId>(visibleNodes, 'id')
+
+// Selection is owned by useSelection's Set; the v-model array is a mirror. Seed
+// the Set from any initial model value, then keep both in sync. Each watcher
+// no-ops when the two already agree, so the round-trip terminates.
+for (const id of selected.value) selection.selected.add(id)
+
+watch(
+    () => [...selection.selected],
+    arr => {
+        if (arr.length !== selected.value.length || arr.some(id => !selected.value.includes(id))) {
+            selected.value = arr
+        }
+    }
+)
+
+watch(selected, val => {
+    const set = selection.selected
+    if (set.size === val.length && val.every(id => set.has(id))) return
+    set.clear()
+    for (const id of val) set.add(id)
+})
+
+async function toggleExpand(entry: VisibleEntry) {
+    if (!entry.expandable) return
+    if (expanded.has(entry.id)) {
+        expanded.delete(entry.id)
+        return
+    }
+    if (!childrenCache.has(entry.id)) {
+        childLoading.add(entry.id)
+        try {
+            childrenCache.set(entry.id, await props.loader(entry.id))
+        } finally {
+            childLoading.delete(entry.id)
+        }
+    }
+    expanded.add(entry.id)
+}
+
+function onRowClick(entry: VisibleEntry, e: MouseEvent) {
+    if (props.multiSelect && e.shiftKey) selection.rangeTo(entry.id)
+    else if (props.multiSelect && (e.ctrlKey || e.metaKey)) selection.toggle(entry.id)
+    else selection.replace(entry.id)
+}
+
+onMounted(async () => {
+    loading.value = true
+    try {
+        roots.value = await props.loader(null)
+    } finally {
+        loading.value = false
+    }
+})
+</script>
+<template>
+    <ul class="TreeView" :class="{ spinner: loading }">
+        <li
+            v-for="entry in visibleNodes"
+            :key="entry.id"
+            class="TreeView__node"
+            :class="{
+                'TreeView__node--selected': selection.selected.has(entry.id),
+                'TreeView__node--leaf': !entry.expandable
+            }"
+            @click="onRowClick(entry, $event)"
+        >
+            <span v-for="(guide, i) in entry.guides" :key="i" class="TreeView__guide" :class="`TreeView__guide--${guide}`" />
+            <button v-if="entry.expandable" type="button" class="TreeView__toggle" :class="{ spinner: childLoading.has(entry.id) }" @click.stop="toggleExpand(entry)">
+                <svg v-if="!childLoading.has(entry.id)" class="TreeView__icon" viewBox="0 0 16 16" aria-hidden="true">
+                    <line x1="4" y1="8" x2="12" y2="8" />
+                    <line v-if="!expanded.has(entry.id)" x1="8" y1="4" x2="8" y2="12" />
+                </svg>
+            </button>
+            <span v-else class="TreeView__spacer" />
+            <span class="TreeView__label">{{ entry.node[labelField] }}</span>
+        </li>
+    </ul>
+</template>
+<style lang="scss">
+// One column width, shared by guide cells, the toggle box, and the leaf spacer so
+// connectors line up under their parent's box exactly.
+$indent: 16px;
+$line-color: var(--tree-line-color, var(--border-color-light));
+
+.TreeView {
+    list-style: none;
+    margin: 0;
+    padding: 0;
+    user-select: none;
+
+    &.spinner {
+        min-height: 40px;
+    }
+
+    &__node {
+        display: flex;
+        align-items: stretch;
+        // Reset the site's global list-item margin; the rows must abut so the
+        // connector lines run continuously from one to the next.
+        margin: 0;
+        cursor: default;
+        white-space: nowrap;
+
+        &:hover {
+            background-color: var(--form-background-hover);
+        }
+        &--selected,
+        &--selected:hover {
+            // Neutral gray band (classic tree look); themeable via the shared token.
+            background-color: var(--row-select-color, rgba(127, 127, 127, 0.32));
+        }
+    }
+
+    // One indentation column. Lines are centered on the column (left/top 50%, a
+    // 1px line pulled back half its width) so they sit exactly on the box centre
+    // and the box's glyph strokes: a vertical (::before) and, for elbows, a
+    // horizontal stub (::after) reaching the node's box.
+    &__guide {
+        position: relative;
+        flex-shrink: 0;
+        width: $indent;
+
+        &--through::before,
+        &--elbow::before,
+        &--elbow-last::before {
+            content: '';
+            position: absolute;
+            top: 0;
+            left: 50%;
+            width: 1px;
+            margin-left: -0.5px;
+            background: $line-color;
+        }
+        // Sibling line passing through, and the ├ elbow: full height.
+        &--through::before,
+        &--elbow::before {
+            bottom: 0;
+        }
+        // The └ elbow (last child): vertical stops at the connector.
+        &--elbow-last::before {
+            height: 50%;
+        }
+        &--elbow::after,
+        &--elbow-last::after {
+            content: '';
+            position: absolute;
+            top: 50%;
+            margin-top: -0.5px;
+            left: 50%;
+            right: 0;
+            height: 1px;
+            background: $line-color;
+        }
+    }
+
+    // A leaf has no box, just an aligning spacer in the box slot. Extend the
+    // elbow's horizontal across that slot so the line reaches the label rather
+    // than stopping short where a box would have been.
+    &__node--leaf &__guide--elbow::after,
+    &__node--leaf &__guide--elbow-last::after {
+        right: -$indent;
+    }
+
+    // +/- box: a sharp square centered on the node's vertical spine. box-sizing is
+    // border-box (global), so width/height include the 1px border → a true 16×16
+    // square; padding:0 overrides the app's global button padding.
+    &__toggle {
+        align-self: center;
+        flex-shrink: 0;
+        width: $indent;
+        height: $indent;
+        padding: 0;
+        display: inline-flex;
+        align-items: center;
+        justify-content: center;
+        border: 1px solid var(--border-color-light);
+        background: var(--form-background);
+        color: var(--font-color);
+        cursor: default;
+
+        &.spinner::before {
+            width: 12px;
+            height: 12px;
+            margin-top: -6px;
+            margin-left: -6px;
+        }
+    }
+    // Plus/minus as centered strokes: the '+' vertical sits on the box centre
+    // (= the connector spine), its horizontal on the row centre.
+    &__icon {
+        display: block;
+        width: 100%;
+        height: 100%;
+        stroke: currentColor;
+        stroke-width: 1.5;
+    }
+    // Keeps leaf labels aligned with their expandable siblings'.
+    &__spacer {
+        flex-shrink: 0;
+        width: $indent;
+    }
+    &__label {
+        align-self: center;
+        flex-grow: 1;
+        overflow: hidden;
+        text-overflow: ellipsis;
+        // Row height lives here (not in node padding) so the guide cells stretch
+        // the full row and the connector lines run gaplessly between rows.
+        line-height: 20px;
+        padding-inline-start: var(--space-1);
+        padding-inline-end: var(--space-2);
+    }
+}
+</style>

package/src/_shared.scss

@@ -0,0 +1,22 @@
+// Package-internal SCSS shared between components (app themes never import this).
+
+// Repositions the theme's base `.spinner::before` pseudo-element as a small
+// indicator vertically centered at the element's right edge.
+// top/bottom both 0 + auto block-margin centers a fixed-height absolutely
+// positioned element vertically without depending on the container's height.
+// Can't use `transform: translateY(-50%)` here — the base spinner rule
+// animates `transform: rotate` and the two would clash.
+@mixin spinner-inline-right($right) {
+    position: absolute;
+    width: 22px;
+    height: 22px;
+    top: 0;
+    bottom: 0;
+    // Reset the base spinner's centring margins: block:auto centres vertically
+    // against top/bottom:0; inline:0 clears the base's negative margin-left so
+    // right-edge anchoring lands where $right places it.
+    margin-block: auto;
+    margin-inline: 0;
+    right: $right;
+    left: unset;
+}

package/src/copyTextToClipboard.ts

@@ -0,0 +1,3 @@
+// Requires a secure context (https/localhost), which every deployment target
+// provides. Rejects when the document is not focused or permission is denied.
+export const copyTextToClipboard = (text: string): Promise<void> => navigator.clipboard.writeText(text)