@kinetis/vector-ui 0.0.0-stage → 0.9.0

package/app/components/Vx/Input/Markdown.vue

@@ -0,0 +1,120 @@
+<script setup lang="ts">
+import { EditorContent, useEditor } from '@tiptap/vue-3'
+import type { Editor } from '@tiptap/core'
+import StarterKit from '@tiptap/starter-kit'
+import { Markdown } from '@tiptap/markdown'
+import type { VectorField } from '#vector/app/types/vector'
+
+// A Markdown field, for technical content: edited WYSIWYG, stored as the
+// Markdown source (the editor reads and writes it through @tiptap/markdown).
+// "Source" shows the text itself, to edit what the toolbar does not offer.
+const props = defineProps<{ field: VectorField, rules: ((v: unknown) => true | string)[], errorMessages: string[], record?: Record<string, unknown>, resource?: string }>()
+const model = defineModel<string | null>()
+
+const { t } = useVectorT()
+const toolbar = computed(() => props.field.markdown?.toolbar ?? ['bold', 'italic', 'strike', 'code', 'heading', 'list', 'blockquote', 'codeBlock', 'horizontalRule', 'link'])
+const on = (button: string) => toolbar.value.includes(button)
+const source = ref(false)
+let emitting = false
+
+const editor = useEditor({
+    extensions: [
+        StarterKit.configure({
+            link: { openOnClick: false, autolink: true, protocols: [], isAllowedUri: (url: string) => allowedHref(url) },
+            heading: { levels: [1, 2, 3, 4] },
+        }),
+        Markdown,
+    ],
+    injectNonce: import.meta.client ? (window.__VECTOR__?.cspNonce ?? undefined) : undefined,
+    editorProps: { attributes: { 'class': 'vx-richtext-content', 'aria-label': props.field.label, 'role': 'textbox', 'aria-multiline': 'true' } },
+    onCreate: ({ editor: current }) => {
+        current.commands.setContent(model.value ?? '', { contentType: 'markdown', emitUpdate: false })
+    },
+    onUpdate: ({ editor: current }) => {
+        const text = current.getMarkdown().trim()
+        emitting = true
+        model.value = text === '' ? null : text
+    },
+})
+
+watch(model, (value) => {
+    if (emitting) {
+        emitting = false
+        return
+    }
+    if (!source.value) editor.value?.commands.setContent(value ?? '', { contentType: 'markdown', emitUpdate: false })
+})
+
+// leaving the source view reads the text back into the editor
+watch(source, (showing) => {
+    if (!showing) editor.value?.commands.setContent(model.value ?? '', { contentType: 'markdown', emitUpdate: false })
+})
+
+onBeforeUnmount(() => editor.value?.destroy())
+
+const active = (name: string, attrs?: Record<string, unknown>) => editor.value?.isActive(name, attrs) ?? false
+const run = (command: (e: Editor) => void) => {
+    if (editor.value) command(editor.value)
+}
+
+const linkMenu = ref(false)
+const linkHref = ref('')
+const linkError = computed(() => linkHref.value.trim() !== '' && !allowedHref(linkHref.value.trim()) ? t('fields.richtext.linkRefused') : null)
+function openLink() {
+    linkHref.value = String(editor.value?.getAttributes('link').href ?? '')
+    linkMenu.value = true
+}
+function applyLink() {
+    const href = linkHref.value.trim()
+    if (linkError.value) return
+    run(e => href === '' ? e.chain().focus().unsetLink().run() : e.chain().focus().extendMarkRange('link').setLink({ href }).run())
+    linkMenu.value = false
+}
+</script>
+
+<template>
+    <v-input :model-value="model" :rules="rules" :error-messages="errorMessages" :hint="field.help ?? undefined" :persistent-hint="!!field.help" class="vx-richtext">
+        <div class="vx-richtext-frame" :class="{ 'vx-richtext-frame--error': errorMessages.length > 0 }">
+            <div class="text-caption text-medium-emphasis px-3 pt-2">{{ field.label }}</div>
+            <div class="vx-richtext-toolbar d-flex flex-wrap align-center ga-1 px-2 py-1" role="toolbar" :aria-label="t('fields.richtext.toolbar', { label: field.label })">
+                <template v-if="!source">
+                    <v-btn v-if="on('bold')" icon="mdi-format-bold" size="small" variant="text" :active="active('bold')" :aria-label="t('fields.richtext.bold')" @click="run(e => e.chain().focus().toggleBold().run())" />
+                    <v-btn v-if="on('italic')" icon="mdi-format-italic" size="small" variant="text" :active="active('italic')" :aria-label="t('fields.richtext.italic')" @click="run(e => e.chain().focus().toggleItalic().run())" />
+                    <v-btn v-if="on('strike')" icon="mdi-format-strikethrough" size="small" variant="text" :active="active('strike')" :aria-label="t('fields.richtext.strike')" @click="run(e => e.chain().focus().toggleStrike().run())" />
+                    <v-btn v-if="on('code')" icon="mdi-code-tags" size="small" variant="text" :active="active('code')" :aria-label="t('fields.richtext.code')" @click="run(e => e.chain().focus().toggleCode().run())" />
+                    <template v-if="on('heading')">
+                        <v-divider vertical class="mx-1" />
+                        <v-btn v-for="level in ([1, 2, 3] as const)" :key="level" :icon="`mdi-format-header-${level}`" size="small" variant="text" :active="active('heading', { level })" :aria-label="t('fields.richtext.heading', { level })" @click="run(e => e.chain().focus().toggleHeading({ level }).run())" />
+                    </template>
+                    <template v-if="on('list')">
+                        <v-divider vertical class="mx-1" />
+                        <v-btn icon="mdi-format-list-bulleted" size="small" variant="text" :active="active('bulletList')" :aria-label="t('fields.richtext.bulletList')" @click="run(e => e.chain().focus().toggleBulletList().run())" />
+                        <v-btn icon="mdi-format-list-numbered" size="small" variant="text" :active="active('orderedList')" :aria-label="t('fields.richtext.orderedList')" @click="run(e => e.chain().focus().toggleOrderedList().run())" />
+                    </template>
+                    <v-btn v-if="on('blockquote')" icon="mdi-format-quote-close" size="small" variant="text" :active="active('blockquote')" :aria-label="t('fields.richtext.blockquote')" @click="run(e => e.chain().focus().toggleBlockquote().run())" />
+                    <v-btn v-if="on('codeBlock')" icon="mdi-code-braces" size="small" variant="text" :active="active('codeBlock')" :aria-label="t('fields.richtext.codeBlock')" @click="run(e => e.chain().focus().toggleCodeBlock().run())" />
+                    <v-btn v-if="on('horizontalRule')" icon="mdi-minus" size="small" variant="text" :aria-label="t('fields.richtext.horizontalRule')" @click="run(e => e.chain().focus().setHorizontalRule().run())" />
+                    <v-menu v-if="on('link')" v-model="linkMenu" :close-on-content-click="false" location="bottom">
+                        <template #activator="{ props: activator }">
+                            <v-btn v-bind="activator" icon="mdi-link-variant" size="small" variant="text" :active="active('link')" :aria-label="t('fields.richtext.link')" @click="openLink" />
+                        </template>
+                        <v-card min-width="320" class="pa-3">
+                            <v-text-field v-model="linkHref" :label="t('fields.richtext.linkUrl')" :error-messages="linkError ? [linkError] : []" autofocus @keydown.enter.prevent="applyLink" />
+                            <div class="d-flex justify-end ga-2">
+                                <v-btn variant="text" @click="linkHref = ''; applyLink()">{{ t('common.remove') }}</v-btn>
+                                <v-btn color="primary" :disabled="!!linkError" @click="applyLink">{{ t('common.apply') }}</v-btn>
+                            </div>
+                        </v-card>
+                    </v-menu>
+                </template>
+                <v-spacer />
+                <v-btn size="small" variant="text" :prepend-icon="source ? 'mdi-eye-outline' : 'mdi-language-markdown-outline'" :aria-pressed="source" @click="source = !source">
+                    {{ source ? t('fields.richtext.visual') : t('fields.richtext.source') }}
+                </v-btn>
+            </div>
+            <v-divider />
+            <v-textarea v-if="source" v-model="model" :aria-label="t('fields.richtext.sourceOf', { label: field.label })" variant="plain" auto-grow rows="6" hide-details class="px-3 font-monospace" />
+            <EditorContent v-show="!source" :editor="editor" class="vx-richtext-editor" />
+        </div>
+    </v-input>
+</template>

package/app/components/Vx/Input/Money.vue

@@ -0,0 +1,47 @@
+<script setup lang="ts">
+import type { VectorField } from '#vector/app/types/vector'
+
+// Edited as a decimal amount, held as minor units — the wire value, in as
+// many decimals as the currency has (none for yen, three for dinars). The
+// text is what was typed until the field is left; only then, when the
+// value changes from outside, or when the currency changes, is it written
+// out in full.
+const props = defineProps<{ field: VectorField, rules: ((v: unknown) => true | string)[], errorMessages: string[], record: Record<string, unknown> }>()
+const model = defineModel<number | null>()
+
+const currency = computed(() => currencyOf(props.field, props.record))
+
+const digits = computed(() => minorDigits(currency.value))
+const format = (value: number | null | undefined) => (typeof value === 'number' ? (value / 10 ** digits.value).toFixed(digits.value) : '')
+const text = ref(format(model.value))
+let typed: number | null | undefined = model.value
+
+watch(model, (value) => {
+    if (value !== typed) text.value = format(value)
+    typed = value
+})
+// the same minor units read in another currency's decimals
+watch(digits, () => { text.value = format(model.value) })
+
+function input(value: string) {
+    text.value = value
+    const parsed = Number.parseFloat(String(value ?? '').replace(',', '.'))
+    typed = Number.isFinite(parsed) ? Math.round(parsed * 10 ** digits.value) : null
+    model.value = typed
+}
+</script>
+
+<template>
+    <v-text-field
+        :model-value="text"
+        :label="field.label"
+        :rules="rules"
+        :error-messages="errorMessages"
+        :suffix="currency ?? undefined"
+        :inputmode="digits > 0 ? 'decimal' : 'numeric'"
+        :hint="field.help ?? undefined"
+        :persistent-hint="!!field.help"
+        @update:model-value="input"
+        @blur="text = format(model)"
+    />
+</template>

package/app/components/Vx/Input/Number.vue

@@ -0,0 +1,24 @@
+<script setup lang="ts">
+import { fieldProps, type VectorField } from '#vector/app/types/vector'
+
+const props = defineProps<{ field: VectorField, rules: ((v: unknown) => true | string)[], errorMessages: string[], record?: Record<string, unknown>, resource?: string }>()
+const model = defineModel<number | null>()
+const decimals = computed(() => {
+    const d = fieldProps(props.field).decimals
+    return typeof d === 'number' ? d : (props.field.valueType === 'float' ? 2 : 0)
+})
+</script>
+
+<template>
+    <v-number-input
+        v-model="model"
+        :label="field.label"
+        :rules="rules"
+        :error-messages="errorMessages"
+        :precision="decimals"
+        :step="decimals > 0 ? 1 / 10 ** decimals : 1"
+        :hint="field.help ?? undefined"
+        :persistent-hint="!!field.help"
+        control-variant="stacked"
+    />
+</template>

package/app/components/Vx/Input/Relation.vue

@@ -0,0 +1,127 @@
+<script setup lang="ts">
+import type { VectorField, VectorRelationValue } from '#vector/app/types/vector'
+
+// belongsTo edits one identifier, manyToMany a list; both search the
+// target's title on the server, debounced, dropping stale answers. A
+// dependent choice list searches with the form's value of the field it
+// depends on, waits for one, and drops its choice when that value changes.
+// An option shows the target's subtitle and thumbnail when it has them;
+// thumbnails come through the API client as data URLs, like image cells.
+const props = defineProps<{ field: VectorField, rules: ((v: unknown) => true | string)[], errorMessages: string[], resource: string, record?: Record<string, unknown>, disabled?: boolean }>()
+const model = defineModel<number | string | (number | string)[] | null>()
+const multiple = computed(() => props.field.type === 'manyToMany')
+const client = useVectorResource(() => props.resource)
+const { t, noun } = useVectorT()
+
+const items = ref<VectorRelationValue[]>([])
+const target = useVectorResource(() => props.field.relation?.resource ?? props.resource)
+const thumbs = reactive<Record<string, string>>({})
+const requested = new Set<string>()
+
+function loadThumbs(options: VectorRelationValue[]) {
+    for (const option of options) {
+        const key = String(option.id)
+        if (!option.image || requested.has(key)) continue
+        requested.add(key)
+        target.fileBlob(option.id, option.image).then(dataUrl).then((url) => { thumbs[key] = url }).catch(() => {})
+    }
+}
+
+const search = ref('')
+const loading = ref(false)
+let requestId = 0
+
+const dependsOn = computed(() => props.field.relation?.dependsOn ?? null)
+const dependency = computed<string | number | null>(() => {
+    if (!dependsOn.value) return null
+    const value = props.record?.[dependsOn.value.field]
+    const key = value && typeof value === 'object' && 'id' in value ? (value as { id: unknown }).id : value
+    return typeof key === 'number' || (typeof key === 'string' && key !== '') ? key : typeof key === 'boolean' ? Number(key) : null
+})
+const waiting = computed(() => dependsOn.value !== null && dependency.value === null)
+
+async function fetchOptions(query: string, ids: (number | string)[] = []) {
+    if (waiting.value && !ids.length) {
+        items.value = items.value.filter(i => isSelected(i.id))
+        return
+    }
+    const id = ++requestId
+    loading.value = true
+    try {
+        const depends = dependsOn.value && dependency.value !== null ? { [dependsOn.value.field]: dependency.value } : {}
+        const result = await client.options(props.field.name, query, ids, depends)
+        if (id === requestId) {
+            // keep the selected entries visible while the list changes
+            const selected = items.value.filter(i => isSelected(i.id))
+            const merged = [...selected, ...result.data.filter(r => !selected.some(s => s.id === r.id))]
+            items.value = merged
+            loadThumbs(result.data)
+        }
+    } finally {
+        if (id === requestId) loading.value = false
+    }
+}
+
+function isSelected(id: number | string) {
+    return multiple.value ? Array.isArray(model.value) && model.value.includes(id) : model.value === id
+}
+
+const debounced = useDebounceFn((q: string) => fetchOptions(q), 250)
+watch(search, (q) => { if (typeof q === 'string') debounced(q) })
+
+// Another team, other agents: a choice made for the old value no longer holds.
+watch(dependency, (now, before) => {
+    if (now === before) return
+    if (!multiple.value && model.value !== null && model.value !== undefined) model.value = null
+    items.value = []
+    fetchOptions('')
+})
+
+// Resolve the labels of an initial value once.
+onMounted(async () => {
+    const initial: (number | string)[] = multiple.value
+        ? (Array.isArray(model.value) ? model.value : [])
+        : (model.value === null || model.value === undefined || Array.isArray(model.value) ? [] : [model.value])
+    await fetchOptions('', initial.length ? initial : [])
+    if (initial.length) await fetchOptions('')
+})
+</script>
+
+<template>
+    <v-autocomplete
+        v-model="model"
+        v-model:search="search"
+        :label="field.label"
+        :items="items"
+        item-title="label"
+        item-value="id"
+        :multiple="multiple"
+        :chips="multiple"
+        :closable-chips="multiple"
+        :loading="loading"
+        :rules="rules"
+        :error-messages="errorMessages"
+        :clearable="field.nullable === true || multiple"
+        :disabled="disabled || waiting"
+        no-filter
+        :hint="waiting ? t('fields.relation.dependsFirst', { label: noun(dependsOn!.label) }) : (field.help ?? undefined)"
+        :persistent-hint="waiting || !!field.help"
+        :placeholder="t('fields.relation.placeholder')"
+    >
+        <template #item="{ props: itemProps, item }">
+            <v-list-item v-bind="itemProps" :subtitle="(item as VectorRelationValue).subtitle ?? undefined">
+                <template v-if="thumbs[String((item as VectorRelationValue).id)]" #prepend>
+                    <v-avatar rounded size="32"><v-img :src="thumbs[String((item as VectorRelationValue).id)]" alt="" cover /></v-avatar>
+                </template>
+            </v-list-item>
+        </template>
+        <template v-if="multiple" #chip="{ props: chipProps, item }">
+            <v-chip v-bind="chipProps" :prepend-avatar="thumbs[String((item as VectorRelationValue).id)]" :title="(item as VectorRelationValue).subtitle ?? undefined" />
+        </template>
+        <template v-else #selection="{ item }">
+            <v-avatar v-if="thumbs[String((item as VectorRelationValue).id)]" rounded size="24" class="me-2"><v-img :src="thumbs[String((item as VectorRelationValue).id)]" alt="" cover /></v-avatar>
+            <span>{{ (item as VectorRelationValue).label }}</span>
+            <span v-if="(item as VectorRelationValue).subtitle" class="text-medium-emphasis ms-2 vx-relation-subtitle">{{ (item as VectorRelationValue).subtitle }}</span>
+        </template>
+    </v-autocomplete>
+</template>

package/app/components/Vx/Input/Repeater.vue

@@ -0,0 +1,134 @@
+<script setup lang="ts">
+import type { VectorField } from '#vector/app/types/vector'
+
+// An owned relation's rows edited inside the parent's form: one line of
+// the child's inputs per row, added and removed within the repeater's
+// bounds. The form sends the whole list; a row keeps its `id`, so the
+// server updates that child, and a row without one is created.
+const props = defineProps<{
+    field: VectorField
+    /** the form's rules for the field itself; a row's inputs carry their own */
+    rules?: unknown[]
+    errorMessages: string[]
+    resource: string
+    record?: Record<string, unknown>
+    /** the form's server errors, keyed `field.row.column` for a row's own */
+    serverErrors?: Record<string, string[]>
+    disabled?: boolean
+}>()
+const model = defineModel<Record<string, unknown>[] | null>()
+
+const { t, noun } = useVectorT()
+const { resource: resourceOf } = useVectorSchema()
+const { inputFor } = useVectorInputs()
+
+const child = computed(() => props.field.relation ? resourceOf(props.field.relation.resource) : undefined)
+const columns = computed<VectorField[]>(() => (props.field.repeater?.fields ?? [])
+    .map(name => child.value?.fields.find(f => f.name === name))
+    .filter((f): f is VectorField => f !== undefined))
+const min = computed(() => props.field.repeater?.min ?? 0)
+const max = computed(() => props.field.repeater?.max ?? 100)
+const rows = computed(() => (Array.isArray(model.value) ? model.value : []))
+const width = computed(() => Math.max(3, Math.floor(12 / Math.max(1, Math.min(columns.value.length, 4)))))
+
+// Stable keys, so removing a row keeps every other row's inputs (and a
+// relation input's loaded label) with the row it belongs to.
+let next = 0
+const keys = ref<number[]>([])
+watch(() => rows.value.length, (length) => {
+    if (keys.value.length !== length) keys.value = Array.from({ length }, () => next++)
+}, { immediate: true })
+
+function blank(): Record<string, unknown> {
+    return Object.fromEntries(columns.value.map(f => [f.name, f.hasDefault ? f.default : f.type === 'boolean' ? false : null]))
+}
+
+function add() {
+    keys.value = [...keys.value, next++]
+    model.value = [...rows.value, blank()]
+}
+
+function remove(index: number) {
+    keys.value = keys.value.filter((_, i) => i !== index)
+    model.value = rows.value.filter((_, i) => i !== index)
+    clearRowErrors()
+}
+
+function set(index: number, name: string, value: unknown) {
+    model.value = rows.value.map((row, i) => (i === index ? { ...row, [name]: value } : row))
+    // The form owns the server errors and lets each input clear its own.
+    // eslint-disable-next-line vue/no-mutating-props
+    if (props.serverErrors) delete props.serverErrors[`${props.field.name}.${index}.${name}`]
+}
+
+/** Row errors are keyed by position, which a removal shifts: they go with it. */
+function clearRowErrors() {
+    for (const key of Object.keys(props.serverErrors ?? {})) {
+        if (key.startsWith(`${props.field.name}.`)) delete props.serverErrors![key]
+    }
+}
+
+// A row's inputs read the record they belong to through the relation back
+// to it: a line priced in `order.currency` sees the order being edited.
+const inverse = computed(() => props.field.relation?.inverse)
+const rowRecord = (row: Record<string, unknown>) => (inverse.value ? { ...row, [inverse.value]: props.record ?? {} } : row)
+
+const rowErrors = (index: number, name: string) => props.serverErrors?.[`${props.field.name}.${index}.${name}`] ?? []
+
+// A new record starts with the rows it must hold.
+onMounted(() => {
+    if (child.value && rows.value.length < min.value && !props.record?.id) {
+        model.value = [...rows.value, ...Array.from({ length: min.value - rows.value.length }, blank)]
+    }
+})
+</script>
+
+<template>
+    <v-card variant="outlined" class="pa-3" role="group" :aria-label="field.label">
+        <div class="d-flex align-center mb-2">
+            <span class="text-subtitle-2">{{ field.label }}</span>
+            <v-spacer />
+            <span class="text-caption text-medium-emphasis">{{ t('fields.repeater.count', { count: rows.length, max }) }}</span>
+        </div>
+        <v-alert v-for="message in errorMessages" :key="message" type="error" variant="tonal" density="compact" class="mb-2" :text="message" />
+        <p v-if="!child" class="text-medium-emphasis text-body-2">{{ t('fields.repeater.unavailable') }}</p>
+        <template v-else>
+            <div
+                v-for="(row, index) in rows"
+                :key="keys[index]"
+                class="d-flex ga-2 align-start mb-1"
+                role="group"
+                :aria-label="t('fields.repeater.row', { label: child.labelSingular, n: index + 1 })"
+            >
+                <v-row density="compact" class="flex-grow-1">
+                    <v-col v-for="column in columns" :key="column.name" cols="12" :md="width">
+                        <component
+                            :is="inputFor(column)"
+                            :model-value="row[column.name]"
+                            :field="column"
+                            :rules="rulesFor(column, row.id ? 'update' : 'create')"
+                            :error-messages="rowErrors(index, column.name)"
+                            :record="rowRecord(row)"
+                            :resource="child.slug"
+                            :disabled="disabled"
+                            density="compact"
+                            @update:model-value="(value: unknown) => set(index, column.name, value)"
+                        />
+                    </v-col>
+                </v-row>
+                <v-btn
+                    icon="mdi-close"
+                    variant="text"
+                    size="small"
+                    class="mt-2"
+                    :disabled="disabled || rows.length <= min"
+                    :aria-label="t('fields.repeater.remove', { label: noun(child.labelSingular), n: index + 1 })"
+                    @click="remove(index)"
+                />
+            </div>
+            <v-btn variant="tonal" size="small" prepend-icon="mdi-plus" :disabled="disabled || rows.length >= max" @click="add">
+                {{ t('fields.repeater.add', { label: noun(child.labelSingular) }) }}
+            </v-btn>
+        </template>
+    </v-card>
+</template>

package/app/components/Vx/Input/RichText.vue

@@ -0,0 +1,182 @@
+<script setup lang="ts">
+import { EditorContent, useEditor } from '@tiptap/vue-3'
+import type { Editor } from '@tiptap/core'
+import type { VectorField } from '#vector/app/types/vector'
+
+// A rich-text field: a Tiptap editor over exactly the field's schema. Its
+// value is the document as JSON text — null when empty — which the server
+// validates against the same schema. Pasted content outside the schema is
+// dropped by construction: ProseMirror keeps only what the schema holds.
+// An image is uploaded through the field's image field and stored by its
+// key; a mention picks a record of the field's `mentions` relation.
+const props = defineProps<{ field: VectorField, rules: ((v: unknown) => true | string)[], errorMessages: string[], record?: Record<string, unknown>, resource?: string }>()
+const model = defineModel<string | null>()
+
+const { t } = useVectorT()
+const client = useVectorResource(() => props.resource ?? '')
+const { richText: custom } = useVectorExtensions()
+const rich = computed(() => props.field.richtext ?? { features: [], imageField: null, mentions: null, storesHtml: false, maxBytes: 262_144 })
+const on = (feature: string) => rich.value.features.includes(feature)
+
+// images uploaded in this form, shown from the picked file until the record is saved
+const uploaded = new Map<string, string>()
+
+async function imageSource(key: string): Promise<string | null> {
+    if (uploaded.has(key)) return uploaded.get(key)!
+    const id = props.record?.id
+    if (id === undefined || id === null || !rich.value.imageField) return null
+    return await dataUrl(await client.fileBlob(id as string | number, rich.value.imageField, key))
+}
+
+async function mentionItems(query: string) {
+    if (!rich.value.mentions) return []
+    return (await client.options(rich.value.mentions, query)).data.slice(0, 8).map(o => ({ id: o.id, label: o.label }))
+}
+
+const extensions = richTextExtensions({ features: rich.value.features, placeholder: props.field.help ?? undefined, imageSource, mentionItems, custom })
+let emitting = false
+
+const editor = useEditor({
+    content: model.value ? toDocument(model.value, extensions) : null,
+    extensions,
+    // Tiptap's own style element carries the hosted shell's nonce, so a strict style-src admits it
+    injectNonce: import.meta.client ? (window.__VECTOR__?.cspNonce ?? undefined) : undefined,
+    editorProps: { attributes: { 'class': 'vx-richtext-content', 'aria-label': props.field.label, 'role': 'textbox', 'aria-multiline': 'true' } },
+    onUpdate: ({ editor: current }) => {
+        const doc = current.getJSON()
+        emitting = true
+        model.value = isEmptyDocument(doc) ? null : JSON.stringify(doc)
+    },
+})
+
+// a value set from outside (a reset, a repeater row) replaces the content
+watch(model, (value) => {
+    if (emitting) {
+        emitting = false
+        return
+    }
+    editor.value?.commands.setContent(value ? toDocument(value, extensions) : null, { emitUpdate: false })
+})
+
+onBeforeUnmount(() => editor.value?.destroy())
+
+const active = (name: string, attrs?: Record<string, unknown>) => editor.value?.isActive(name, attrs) ?? false
+const run = (command: (e: Editor) => void) => {
+    if (editor.value) command(editor.value)
+}
+
+// links: http(s), mailto or relative only, as the server requires
+const linkMenu = ref(false)
+const linkHref = ref('')
+const linkError = computed(() => linkHref.value.trim() !== '' && !allowedHref(linkHref.value.trim()) ? t('fields.richtext.linkRefused') : null)
+function openLink() {
+    linkHref.value = String(editor.value?.getAttributes('link').href ?? '')
+    linkMenu.value = true
+}
+function applyLink() {
+    const href = linkHref.value.trim()
+    if (linkError.value) return
+    run(e => href === '' ? e.chain().focus().unsetLink().run() : e.chain().focus().extendMarkRange('link').setLink({ href }).run())
+    linkMenu.value = false
+}
+
+// images: uploaded at once through the image field, stored by key
+const picker = ref<HTMLInputElement | null>(null)
+const uploading = ref(false)
+const uploadError = ref<string | null>(null)
+async function insertImage(event: Event) {
+    const file = (event.target as HTMLInputElement).files?.[0]
+    ;(event.target as HTMLInputElement).value = ''
+    if (!file || !rich.value.imageField) return
+    uploading.value = true
+    uploadError.value = null
+    try {
+        const { key } = await client.upload(rich.value.imageField, file)
+        uploaded.set(key, await dataUrl(file))
+        run(e => e.chain().focus().setImage({ src: key, alt: file.name }).run())
+    } catch (error) {
+        uploadError.value = vectorErrorMessage(error)
+    } finally {
+        uploading.value = false
+    }
+}
+
+const inTable = computed(() => active('table'))
+</script>
+
+<template>
+    <v-input :model-value="model" :rules="rules" :error-messages="uploadError ? [uploadError, ...errorMessages] : errorMessages" :hint="field.help ?? undefined" :persistent-hint="!!field.help" class="vx-richtext">
+        <div class="vx-richtext-frame" :class="{ 'vx-richtext-frame--error': errorMessages.length > 0 }">
+            <div class="text-caption text-medium-emphasis px-3 pt-2">{{ field.label }}</div>
+            <div class="vx-richtext-toolbar d-flex flex-wrap align-center ga-1 px-2 py-1" role="toolbar" :aria-label="t('fields.richtext.toolbar', { label: field.label })">
+                <v-btn v-if="on('bold')" icon="mdi-format-bold" size="small" variant="text" :active="active('bold')" :aria-label="t('fields.richtext.bold')" @click="run(e => e.chain().focus().toggleBold().run())" />
+                <v-btn v-if="on('italic')" icon="mdi-format-italic" size="small" variant="text" :active="active('italic')" :aria-label="t('fields.richtext.italic')" @click="run(e => e.chain().focus().toggleItalic().run())" />
+                <v-btn v-if="on('underline')" icon="mdi-format-underline" size="small" variant="text" :active="active('underline')" :aria-label="t('fields.richtext.underline')" @click="run(e => e.chain().focus().toggleUnderline().run())" />
+                <v-btn v-if="on('strike')" icon="mdi-format-strikethrough" size="small" variant="text" :active="active('strike')" :aria-label="t('fields.richtext.strike')" @click="run(e => e.chain().focus().toggleStrike().run())" />
+                <v-btn v-if="on('code')" icon="mdi-code-tags" size="small" variant="text" :active="active('code')" :aria-label="t('fields.richtext.code')" @click="run(e => e.chain().focus().toggleCode().run())" />
+                <template v-if="on('heading')">
+                    <v-divider vertical class="mx-1" />
+                    <v-btn v-for="level in ([1, 2, 3] as const)" :key="level" :icon="`mdi-format-header-${level}`" size="small" variant="text" :active="active('heading', { level })" :aria-label="t('fields.richtext.heading', { level })" @click="run(e => e.chain().focus().toggleHeading({ level }).run())" />
+                </template>
+                <template v-if="on('list')">
+                    <v-divider vertical class="mx-1" />
+                    <v-btn icon="mdi-format-list-bulleted" size="small" variant="text" :active="active('bulletList')" :aria-label="t('fields.richtext.bulletList')" @click="run(e => e.chain().focus().toggleBulletList().run())" />
+                    <v-btn icon="mdi-format-list-numbered" size="small" variant="text" :active="active('orderedList')" :aria-label="t('fields.richtext.orderedList')" @click="run(e => e.chain().focus().toggleOrderedList().run())" />
+                </template>
+                <v-btn v-if="on('blockquote')" icon="mdi-format-quote-close" size="small" variant="text" :active="active('blockquote')" :aria-label="t('fields.richtext.blockquote')" @click="run(e => e.chain().focus().toggleBlockquote().run())" />
+                <v-btn v-if="on('codeBlock')" icon="mdi-code-braces" size="small" variant="text" :active="active('codeBlock')" :aria-label="t('fields.richtext.codeBlock')" @click="run(e => e.chain().focus().toggleCodeBlock().run())" />
+                <v-btn v-if="on('horizontalRule')" icon="mdi-minus" size="small" variant="text" :aria-label="t('fields.richtext.horizontalRule')" @click="run(e => e.chain().focus().setHorizontalRule().run())" />
+                <v-menu v-if="on('link')" v-model="linkMenu" :close-on-content-click="false" location="bottom">
+                    <template #activator="{ props: activator }">
+                        <v-btn v-bind="activator" icon="mdi-link-variant" size="small" variant="text" :active="active('link')" :aria-label="t('fields.richtext.link')" @click="openLink" />
+                    </template>
+                    <v-card min-width="320" class="pa-3">
+                        <v-text-field v-model="linkHref" :label="t('fields.richtext.linkUrl')" :error-messages="linkError ? [linkError] : []" autofocus @keydown.enter.prevent="applyLink" />
+                        <div class="d-flex justify-end ga-2">
+                            <v-btn variant="text" @click="linkHref = ''; applyLink()">{{ t('common.remove') }}</v-btn>
+                            <v-btn color="primary" :disabled="!!linkError" @click="applyLink">{{ t('common.apply') }}</v-btn>
+                        </div>
+                    </v-card>
+                </v-menu>
+                <template v-if="on('table')">
+                    <v-divider vertical class="mx-1" />
+                    <v-btn icon="mdi-table-plus" size="small" variant="text" :aria-label="t('fields.richtext.insertTable')" @click="run(e => e.chain().focus().insertTable({ rows: 3, cols: 3, withHeaderRow: true }).run())" />
+                    <template v-if="inTable">
+                        <v-btn icon="mdi-table-row-plus-after" size="small" variant="text" :aria-label="t('fields.richtext.addRow')" @click="run(e => e.chain().focus().addRowAfter().run())" />
+                        <v-btn icon="mdi-table-column-plus-after" size="small" variant="text" :aria-label="t('fields.richtext.addColumn')" @click="run(e => e.chain().focus().addColumnAfter().run())" />
+                        <v-btn icon="mdi-table-row-remove" size="small" variant="text" :aria-label="t('fields.richtext.deleteRow')" @click="run(e => e.chain().focus().deleteRow().run())" />
+                        <v-btn icon="mdi-table-column-remove" size="small" variant="text" :aria-label="t('fields.richtext.deleteColumn')" @click="run(e => e.chain().focus().deleteColumn().run())" />
+                        <v-btn icon="mdi-table-remove" size="small" variant="text" :aria-label="t('fields.richtext.deleteTable')" @click="run(e => e.chain().focus().deleteTable().run())" />
+                    </template>
+                </template>
+                <template v-if="on('image') && rich.imageField">
+                    <v-btn icon="mdi-image-plus" size="small" variant="text" :loading="uploading" :aria-label="t('fields.richtext.image')" @click="picker?.click()" />
+                    <input ref="picker" type="file" accept="image/png,image/jpeg,image/webp,image/gif" class="d-none" @change="insertImage">
+                </template>
+                <v-spacer />
+                <v-btn icon="mdi-undo" size="small" variant="text" :aria-label="t('fields.richtext.undo')" @click="run(e => e.chain().focus().undo().run())" />
+                <v-btn icon="mdi-redo" size="small" variant="text" :aria-label="t('fields.richtext.redo')" @click="run(e => e.chain().focus().redo().run())" />
+            </div>
+            <v-divider />
+            <EditorContent :editor="editor" class="vx-richtext-editor" />
+        </div>
+    </v-input>
+</template>
+
+<style>
+.vx-richtext .v-input__control { display: block; }
+.vx-richtext-frame { border: 1px solid rgba(var(--v-border-color), var(--v-border-opacity)); border-radius: 4px; width: 100%; }
+.vx-richtext-frame--error { border-color: rgb(var(--v-theme-error)); }
+.vx-richtext-editor .vx-richtext-content { min-height: 8rem; padding: 0.75rem 1rem; outline: none; }
+.vx-richtext-content p.is-editor-empty:first-child::before { content: attr(data-placeholder); float: inline-start; height: 0; pointer-events: none; opacity: 0.5; }
+.vx-richtext-content table, .vx-richtext-view table { border-collapse: collapse; margin: 0.5rem 0; }
+.vx-richtext-content td, .vx-richtext-content th, .vx-richtext-view td, .vx-richtext-view th { border: 1px solid rgba(var(--v-border-color), 0.3); padding: 0.25rem 0.5rem; min-width: 4rem; vertical-align: top; }
+.vx-richtext-content img, .vx-richtext-view img { max-width: 100%; height: auto; }
+.vx-richtext-content blockquote, .vx-richtext-view blockquote { border-inline-start: 3px solid rgba(var(--v-border-color), 0.4); padding-inline-start: 0.75rem; margin: 0.5rem 0; }
+.vx-richtext-content pre, .vx-richtext-view pre { background: rgba(var(--v-theme-on-surface), 0.06); padding: 0.5rem 0.75rem; border-radius: 4px; overflow-x: auto; }
+.vx-richtext-content ul, .vx-richtext-content ol, .vx-richtext-view ul, .vx-richtext-view ol { padding-inline-start: 1.5rem; }
+.vx-mention { color: rgb(var(--v-theme-primary)); font-weight: 500; }
+.vx-mention-menu { position: absolute; z-index: 3000; background: rgb(var(--v-theme-surface)); border: 1px solid rgba(var(--v-border-color), 0.3); border-radius: 4px; box-shadow: 0 4px 12px rgba(0, 0, 0, 0.15); display: flex; flex-direction: column; min-width: 12rem; }
+.vx-mention-choice { text-align: start; padding: 0.35rem 0.75rem; background: none; border: 0; cursor: pointer; }
+.vx-mention-choice--active, .vx-mention-choice:hover { background: rgba(var(--v-theme-primary), 0.12); }
+</style>