feat(10-03): tabs, toggles, relation fields, form lifecycle and settings pages

- FormTabs groups fields by tab (untabbed fields in the default tab) as a
  segmented tablist; a tab holding invalid fields after a 422 shows a
  count badge and the form switches to the first invalid field
- switch, checkbox and relation join the renderer registry: toggle cards
  (role=switch, 20px checkbox) keep a numeric value numeric; relation
  fields are read-only labels from meta.labels, a searchable single
  select over fields/{field}/options with emptyOption first, or ordered
  removable chips with an appending search (300 ms debounce, 20 per
  page, more on scroll or the more action)
- FormView gets the back button, record title and update subtitle, a
  sticky footer (Usuń with deleteConfirm then DELETE, Anuluj, Zapisz i
  zamknij to the mapped redirectClose, Zapisz), and asks before leaving a
  dirty form on any route change plus a beforeunload guard
- Settings: the rail pins Ustawienia to the bottom when /settings is
  non-empty; /settings lists pages by category; /settings/:code renders
  the settings schema through FormGrid and the registry, PUTs the values
  and maps a 422 like the record form
- New backend::lang keys (form.more_options, tab_default, discard,
  settings.back); form and settings smoke tests; boardwalk/dist rebuilt
This commit is contained in:
Jakub Zych
2026-09-27 17:00:18 +02:00
parent 8b5f85603f
commit 8f32416f4f
30 changed files with 1898 additions and 58 deletions

View File

@@ -0,0 +1,53 @@
<script setup lang="ts">
import { tc } from '../../app/i18n'
import { panelDomId, tabDomId, type TabItem } from './formState'
// Segmented tab control (design screen 4): track subtle with a border, 34px
// pills, the active one on surface with a shadow. A tab holding invalid
// fields after a 422 carries a count badge. Arrow keys move between tabs.
const props = defineProps<{ tabs: TabItem[]; modelValue: string; idPrefix: string }>()
const emit = defineEmits<{ 'update:modelValue': [key: string] }>()
function onKeydown(event: KeyboardEvent, index: number): void {
const step = event.key === 'ArrowRight' ? 1 : event.key === 'ArrowLeft' ? -1 : 0
if (step === 0) {
return
}
event.preventDefault()
const nextIndex = (index + step + props.tabs.length) % props.tabs.length
const next = props.tabs[nextIndex]
if (next) {
emit('update:modelValue', next.key)
document.getElementById(tabDomId(props.idPrefix, nextIndex))?.focus()
}
}
</script>
<template>
<div role="tablist" class="inline-flex gap-1 rounded-inner border border-border bg-subtle p-1">
<button
v-for="(tab, index) in tabs"
:id="tabDomId(idPrefix, index)"
:key="tab.key"
type="button"
role="tab"
:data-tab="tab.key"
:aria-selected="tab.key === modelValue ? 'true' : 'false'"
:aria-controls="panelDomId(idPrefix, index)"
:tabindex="tab.key === modelValue ? 0 : -1"
:class="tab.key === modelValue ? 'bg-surface text-text shadow-tab' : 'text-muted hover:text-text'"
class="inline-flex h-[34px] items-center gap-2 rounded-tab px-4 font-semibold transition-colors duration-150 ease-out"
@click="emit('update:modelValue', tab.key)"
@keydown="onKeydown($event, index)"
>
{{ tab.label }}
<span
v-if="tab.errors > 0"
data-tab-errors
:aria-label="tc('backend::lang.form.tab_errors', tab.errors)"
class="inline-flex h-5 min-w-5 items-center justify-center rounded-pill bg-danger px-1.5 text-[11px] font-bold text-white"
>{{ tab.errors }}</span
>
</button>
</div>
</template>

View File

@@ -0,0 +1,39 @@
<script setup lang="ts">
import { computed } from 'vue'
import { toggleOn, toggleValue, type FieldControlProps } from '../registry'
// Toggle card (design screen 4) with a 20px checkbox on the right.
const props = defineProps<FieldControlProps>()
const emit = defineEmits<{ 'update:modelValue': [value: boolean | number] }>()
const on = computed(() => toggleOn(props.modelValue))
function onChange(event: Event): void {
emit('update:modelValue', toggleValue(props.modelValue, (event.target as HTMLInputElement).checked))
}
</script>
<template>
<div
:class="invalid ? 'border-danger' : 'border-border'"
class="flex items-center justify-between gap-4 rounded-inner border px-4 py-3.5"
data-toggle-card
>
<div class="flex min-w-0 flex-col">
<label :for="controlId" class="font-semibold">
{{ field.label || field.name }}<span v-if="field.required" class="text-danger" aria-hidden="true"> *</span>
</label>
<p v-if="field.comment" :id="`${controlId}-comment`" class="text-[13px] text-muted">{{ field.comment }}</p>
</div>
<input
:id="controlId"
type="checkbox"
:name="field.name"
:checked="on"
:aria-invalid="invalid ? 'true' : undefined"
:aria-describedby="describedBy || undefined"
class="size-5 shrink-0 rounded-[6px] accent-primary"
@change="onChange"
/>
</div>
</template>

View File

@@ -0,0 +1,403 @@
<script setup lang="ts">
import { computed, onBeforeUnmount, ref, watch } from 'vue'
import { ChevronDown, X } from '@lucide/vue'
import { api } from '../../../api/client'
import type { RelationOption } from '../../../api/types'
import { t } from '../../../app/i18n'
import type { FieldControlProps } from '../registry'
// Relation field (D-17, D-18, D-26), three modes from the schema:
// readOnly the label from meta.labels only, no control
// single a searchable select over fields/{field}/options; emptyOption
// first and muted; sends the id or null
// multiple removable chips in order plus an inline search that appends
// the chosen id
// Options are searched with a 300 ms debounce, 20 per page, with more loaded
// on scroll or through the "more" action. Labels come from meta.labels and
// from every options page seen.
const props = defineProps<FieldControlProps>()
const emit = defineEmits<{ 'update:modelValue': [value: number | number[] | null] }>()
const PER_PAGE = 20
const SEARCH_DEBOUNCE = 300
const mode = computed(() => (props.field.readOnly ? 'readonly' : props.field.multiple ? 'multiple' : 'single'))
const listId = computed(() => `${props.controlId}-listbox`)
const known = ref<Record<number, string>>({})
watch(
() => props.labels,
(labels) => {
const next = { ...known.value }
for (const option of labels ?? []) {
next[option.value] = option.label
}
known.value = next
},
{ immediate: true },
)
function asId(value: unknown): number | null {
if (typeof value === 'number' && Number.isInteger(value)) {
return value
}
if (typeof value === 'string' && /^\d+$/.test(value)) {
return Number(value)
}
return null
}
const singleId = computed(() => asId(props.modelValue))
const selectedIds = computed(() =>
Array.isArray(props.modelValue) ? props.modelValue.map(asId).filter((id): id is number => id !== null) : [],
)
function labelOf(id: number): string {
return known.value[id] ?? String(id)
}
function initials(label: string): string {
return label
.split(/[\s@._-]+/)
.filter(Boolean)
.slice(0, 2)
.map((part) => part.charAt(0).toUpperCase())
.join('')
}
const readOnlyText = computed(() => {
const label = props.labels?.[0]?.label
if (label) {
return label
}
return props.field.emptyOption ?? '—'
})
// Options listbox.
const open = ref(false)
const query = ref('')
const options = ref<RelationOption[]>([])
const page = ref(0)
const lastPage = ref(0)
const loading = ref(false)
const active = ref(-1)
let generation = 0
let searchTimer: ReturnType<typeof setTimeout> | null = null
const hasMore = computed(() => page.value < lastPage.value)
async function fetchPage(nextPage: number, append: boolean): Promise<void> {
const source = props.source
if (!source) {
options.value = []
return
}
const current = ++generation
loading.value = true
try {
const search = query.value.trim()
const { data } = await api.GET('/{vendor}/{plugin}/{controller}/fields/{field}/options', {
params: {
path: { ...source, field: props.field.name },
query: { search: search === '' ? undefined : search, page: nextPage, per_page: PER_PAGE },
},
})
if (current !== generation) {
return
}
const rows = data?.data ?? []
const labels = { ...known.value }
for (const option of rows) {
labels[option.value] = option.label
}
known.value = labels
options.value = append ? [...options.value, ...rows] : rows
page.value = data?.meta.page ?? nextPage
lastPage.value = data?.meta.last_page ?? nextPage
} catch {
if (current === generation && !append) {
options.value = []
}
} finally {
if (current === generation) {
loading.value = false
}
}
}
interface Entry {
key: string
label: string
value: number | null
muted: boolean
}
const entries = computed<Entry[]>(() => {
const out: Entry[] = []
if (mode.value === 'single' && props.field.emptyOption !== undefined) {
out.push({ key: 'empty', label: props.field.emptyOption, value: null, muted: true })
}
const taken = new Set(selectedIds.value)
for (const option of options.value) {
if (mode.value === 'multiple' && taken.has(option.value)) {
continue
}
out.push({ key: `option-${option.value}`, label: option.label, value: option.value, muted: false })
}
return out
})
function optionId(index: number): string {
return `${listId.value}-${index}`
}
function openList(): void {
if (open.value) {
return
}
open.value = true
active.value = -1
void fetchPage(1, false)
}
function closeList(): void {
open.value = false
query.value = ''
active.value = -1
if (searchTimer !== null) {
clearTimeout(searchTimer)
searchTimer = null
}
}
function onQuery(event: Event): void {
query.value = (event.target as HTMLInputElement).value
open.value = true
active.value = -1
if (searchTimer !== null) {
clearTimeout(searchTimer)
}
searchTimer = setTimeout(() => {
searchTimer = null
void fetchPage(1, false)
}, SEARCH_DEBOUNCE)
}
function loadMore(): void {
if (hasMore.value && !loading.value) {
void fetchPage(page.value + 1, true)
}
}
function onScroll(event: Event): void {
const list = event.target as HTMLElement
if (list.scrollTop + list.clientHeight >= list.scrollHeight - 24) {
loadMore()
}
}
function choose(entry: Entry): void {
if (mode.value === 'multiple') {
if (entry.value !== null && !selectedIds.value.includes(entry.value)) {
emit('update:modelValue', [...selectedIds.value, entry.value])
}
} else {
emit('update:modelValue', entry.value)
}
closeList()
}
function remove(id: number): void {
emit(
'update:modelValue',
selectedIds.value.filter((item) => item !== id),
)
}
function onKeydown(event: KeyboardEvent): void {
switch (event.key) {
case 'ArrowDown':
event.preventDefault()
if (!open.value) {
openList()
} else {
active.value = Math.min(active.value + 1, entries.value.length - 1)
}
break
case 'ArrowUp':
event.preventDefault()
active.value = Math.max(active.value - 1, 0)
break
case 'Enter':
if (open.value) {
event.preventDefault()
const entry = entries.value[active.value]
if (entry) {
choose(entry)
}
}
break
case 'Escape':
if (open.value) {
event.preventDefault()
closeList()
}
break
case 'Backspace':
if (mode.value === 'multiple' && query.value === '' && selectedIds.value.length > 0) {
remove(selectedIds.value[selectedIds.value.length - 1]!)
}
break
}
}
const singleText = computed(() => {
if (singleId.value !== null) {
return labelOf(singleId.value)
}
return props.field.emptyOption ?? ''
})
onBeforeUnmount(() => {
if (searchTimer !== null) {
clearTimeout(searchTimer)
}
})
</script>
<template>
<div
v-if="mode === 'readonly'"
:id="controlId"
data-relation-readonly
:aria-describedby="describedBy || undefined"
:class="labels?.[0]?.label ? 'text-text' : 'text-muted'"
class="flex min-h-input items-center rounded-control border border-border bg-subtle px-3.5"
>
{{ readOnlyText }}
</div>
<div v-else class="relative" :data-relation="mode">
<div
v-if="mode === 'multiple'"
:class="invalid ? 'border-danger' : 'border-border-strong'"
class="flex min-h-input flex-wrap items-center gap-1.5 rounded-control border bg-surface p-1.5"
>
<span
v-for="id in selectedIds"
:key="id"
data-chip
class="inline-flex h-[30px] items-center gap-1.5 rounded-pill bg-subtle pr-1 pl-1"
>
<span
class="flex size-[22px] items-center justify-center rounded-full bg-primary text-[10px] font-bold text-on-primary"
aria-hidden="true"
>{{ initials(labelOf(id)) }}</span
>
<span class="font-semibold">{{ labelOf(id) }}</span>
<button
type="button"
:aria-label="t('backend::lang.form.remove_item', { name: labelOf(id) })"
class="flex size-6 items-center justify-center rounded-full text-muted hover:bg-hover hover:text-text"
@click="remove(id)"
>
<X :size="14" aria-hidden="true" />
</button>
</span>
<input
:id="controlId"
type="text"
role="combobox"
autocomplete="off"
:aria-expanded="open ? 'true' : 'false'"
:aria-controls="listId"
aria-autocomplete="list"
:aria-activedescendant="open && active >= 0 ? optionId(active) : undefined"
:aria-required="field.required ? 'true' : undefined"
:aria-invalid="invalid ? 'true' : undefined"
:aria-describedby="describedBy || undefined"
:value="query"
:placeholder="t('backend::lang.form.add_item')"
class="h-[30px] min-w-[120px] flex-1 border-0 bg-transparent px-2 focus-visible:shadow-none"
@click="openList"
@input="onQuery"
@keydown="onKeydown"
@blur="closeList"
/>
</div>
<div v-else class="relative">
<input
:id="controlId"
type="text"
role="combobox"
autocomplete="off"
:aria-expanded="open ? 'true' : 'false'"
:aria-controls="listId"
aria-autocomplete="list"
:aria-activedescendant="open && active >= 0 ? optionId(active) : undefined"
:aria-required="field.required ? 'true' : undefined"
:aria-invalid="invalid ? 'true' : undefined"
:aria-describedby="describedBy || undefined"
:value="open ? query : singleText"
:placeholder="open ? singleText || t('backend::lang.form.select_placeholder') : t('backend::lang.form.select_placeholder')"
:class="[
invalid ? 'border-danger' : 'border-border-strong',
!open && singleId === null ? 'text-muted' : 'text-text',
]"
class="h-input w-full rounded-control border bg-surface pr-10 pl-3.5"
@click="openList"
@input="onQuery"
@keydown="onKeydown"
@blur="closeList"
/>
<ChevronDown
:size="16"
class="pointer-events-none absolute top-1/2 right-3.5 -translate-y-1/2 text-muted"
aria-hidden="true"
/>
</div>
<ul
v-show="open"
:id="listId"
role="listbox"
class="absolute inset-x-0 top-full z-20 mt-1 max-h-64 overflow-y-auto rounded-inner border border-border bg-surface p-1 shadow-menu"
@scroll="onScroll"
>
<li
v-for="(entry, index) in entries"
:id="optionId(index)"
:key="entry.key"
role="option"
:data-value="entry.value ?? 'empty'"
:aria-selected="mode === 'single' && entry.value === singleId ? 'true' : 'false'"
:class="[entry.muted ? 'text-muted' : 'text-text', index === active ? 'bg-hover' : '']"
class="flex h-10 cursor-pointer items-center rounded-control px-3 hover:bg-hover"
@mousedown.prevent="choose(entry)"
>
{{ entry.label }}
</li>
<li v-if="loading" role="presentation" class="px-3 py-2 text-[13px] text-muted">
{{ t('backend::lang.form.loading_options') }}
</li>
<li
v-else-if="entries.filter((entry) => entry.value !== null).length === 0"
role="presentation"
class="px-3 py-2 text-[13px] text-muted"
>
{{ t('backend::lang.form.no_options') }}
</li>
<li v-if="hasMore && !loading" role="presentation" class="p-1">
<button
type="button"
data-action="more-options"
class="h-8 w-full rounded-control text-[13px] font-semibold text-muted hover:bg-hover hover:text-text"
@mousedown.prevent="loadMore"
>
{{ t('backend::lang.form.more_options') }}
</button>
</li>
</ul>
</div>
</template>

View File

@@ -0,0 +1,47 @@
<script setup lang="ts">
import { computed } from 'vue'
import { toggleOn, toggleValue, type FieldControlProps } from '../registry'
// Toggle card (design screen 4): the label as title, the comment as helper
// text and a 44x26 role="switch" control; the off track uses borderStrong.
const props = defineProps<FieldControlProps>()
const emit = defineEmits<{ 'update:modelValue': [value: boolean | number] }>()
const on = computed(() => toggleOn(props.modelValue))
function toggle(): void {
emit('update:modelValue', toggleValue(props.modelValue, !on.value))
}
</script>
<template>
<div
:class="invalid ? 'border-danger' : 'border-border'"
class="flex items-center justify-between gap-4 rounded-inner border px-4 py-3.5"
data-toggle-card
>
<div class="flex min-w-0 flex-col">
<label :for="controlId" class="font-semibold">
{{ field.label || field.name }}<span v-if="field.required" class="text-danger" aria-hidden="true"> *</span>
</label>
<p v-if="field.comment" :id="`${controlId}-comment`" class="text-[13px] text-muted">{{ field.comment }}</p>
</div>
<button
:id="controlId"
type="button"
role="switch"
:aria-checked="on ? 'true' : 'false'"
:aria-invalid="invalid ? 'true' : undefined"
:aria-describedby="describedBy || undefined"
:class="on ? 'bg-primary' : 'bg-border-strong'"
class="relative h-[26px] w-11 shrink-0 rounded-pill transition-colors duration-150 ease-out"
@click="toggle"
>
<span
:class="on ? 'translate-x-[18px] bg-on-primary' : 'translate-x-0 bg-white'"
class="absolute top-[3px] left-[3px] size-5 rounded-full shadow-tab transition-transform duration-150 ease-out"
aria-hidden="true"
/>
</button>
</div>
</template>

View File

@@ -5,6 +5,30 @@ import { isRegistered } from './registry'
export type FormMode = 'create' | 'update'
/** One form tab: the YAML tab label, or the default tab for untabbed fields. */
export interface TabItem {
key: string
label: string
errors: number
}
/** Key of the tab that holds fields without a `tab`. */
export const DEFAULT_TAB = 'default'
/** Tab key of a field: its tab label, or the default tab. */
export function tabOf(field: FormField): string {
return field.tab ? `tab:${field.tab}` : DEFAULT_TAB
}
/** DOM ids of the tab button and its panel, by tab position. */
export function tabDomId(prefix: string, index: number): string {
return `${prefix}-tab-${index}`
}
export function panelDomId(prefix: string, index: number): string {
return `${prefix}-panel-${index}`
}
/** Winter `context:` semantics: no context shows the field everywhere. */
export function contextAllows(field: FormField, mode: FormMode): boolean {
const context = field.context

View File

@@ -1,11 +1,15 @@
// Field renderer registry (D-05). A form field's `type` selects the control
// component; any type without a renderer gets UnsupportedField, the design's
// dashed box, so an unknown type never breaks the form. Phase 10.1 turns this
// seam into the plugin extension point.
// dashed box, so an unknown type never breaks the form. The relation manager
// arrives with its own component in a later plan. Phase 10.1 turns this seam
// into the plugin extension point.
import type { Component } from 'vue'
import type { ControllerParams, FormField, RelationOption } from '../../api/types'
import CheckboxField from './fields/CheckboxField.vue'
import DropdownField from './fields/DropdownField.vue'
import NumberField from './fields/NumberField.vue'
import RelationField from './fields/RelationField.vue'
import SwitchField from './fields/SwitchField.vue'
import TextField from './fields/TextField.vue'
import TextareaField from './fields/TextareaField.vue'
import UnsupportedField from './fields/UnsupportedField.vue'
@@ -30,10 +34,13 @@ const renderers = new Map<string, Component>([
['textarea', TextareaField],
['number', NumberField],
['dropdown', DropdownField],
['switch', SwitchField],
['checkbox', CheckboxField],
['relation', RelationField],
])
/** Types whose control shows the label itself (toggle cards). */
const selfLabelled = new Set<string>()
const selfLabelled = new Set<string>(['switch', 'checkbox'])
export function rendererFor(type: string): Component {
return renderers.get(type) ?? UnsupportedField
@@ -82,3 +89,16 @@ export function controlClass(invalid: boolean | undefined): string {
invalid ? 'border-danger' : 'border-border-strong',
].join(' ')
}
/** Truthiness of a stored toggle value (true, 1, "1", "true"). */
export function toggleOn(value: unknown): boolean {
if (typeof value === 'string') {
return value !== '' && value !== '0' && value.toLowerCase() !== 'false'
}
return Boolean(value)
}
/** A toggle's next value in the stored value's own type (1/0 or boolean). */
export function toggleValue(current: unknown, on: boolean): boolean | number {
return typeof current === 'number' ? (on ? 1 : 0) : on
}

View File

@@ -45,7 +45,10 @@ const initials = computed(() =>
<div class="flex min-w-0 flex-1 flex-col">
<header class="flex h-header shrink-0 items-center justify-between border-b border-border bg-surface pr-6 pl-8">
<nav :aria-label="t('backend::lang.nav.breadcrumbs')" class="flex items-center gap-2">
<template v-if="active">
<span v-if="route.name === 'settings' || route.name === 'settings-form'" class="font-semibold">
{{ t('backend::lang.nav.settings') }}
</span>
<template v-else-if="active">
<span :class="section ? 'text-muted' : 'font-semibold'">{{ active.label }}</span>
<template v-if="section">
<ChevronRight :size="14" class="text-muted" aria-hidden="true" />

View File

@@ -1,15 +1,20 @@
<script setup lang="ts">
import { computed } from 'vue'
import { RouterLink, useRoute } from 'vue-router'
import { Sun } from '@lucide/vue'
import { Settings, Sun } from '@lucide/vue'
import { t } from '../../app/i18n'
import { iconFor } from '../../app/icons'
import { activeEntry, firstControllerPath, railEntries } from '../../state/useNavigation'
import { hasSettings } from '../../state/useSettings'
const route = useRoute()
const active = computed(() => activeEntry(String(route.params.vendor ?? ''), String(route.params.plugin ?? '')))
// Ustawienia (D-21) is pinned to the bottom and shown only when the admin may
// manage at least one settings page.
const inSettings = computed(() => route.path === '/settings' || route.path.startsWith('/settings/'))
const items = computed(() =>
railEntries.value.map((entry) => ({
entry,
@@ -39,5 +44,17 @@ const items = computed(() =>
<component :is="item.icon" :size="20" aria-hidden="true" />
<span>{{ item.entry.label }}</span>
</RouterLink>
<span class="flex-1" aria-hidden="true" />
<RouterLink
v-if="hasSettings"
to="/settings"
data-rail-settings
:aria-current="inSettings ? 'page' : undefined"
:class="inSettings ? 'bg-accent-soft font-bold text-accent' : 'text-side-text hover:bg-side-hover hover:text-white'"
class="flex w-[68px] flex-col items-center gap-1 rounded-inner px-1.5 py-2 text-center text-[11px] leading-[1.2] tracking-[-0.01em] no-underline"
>
<Settings :size="20" aria-hidden="true" />
<span>{{ t('backend::lang.nav.settings') }}</span>
</RouterLink>
</nav>
</template>