Skip to the content.

UI components

The standard for every Vue component in the apps and layers: where it lives, how it is named, its API and how it is tested. The blueprint behind it is nuxt-layers.md § 2; the kit itself is documented in nuxt-layer-ui.md.

Where components live

Tier What Where Native fallback
0 Accessibility primitives UiSkipLink, UiAnnouncer packages/nuxt-layer-base/app/components/a11y/ native only
1 Primitives one control or element: UiButton, UiInputText, UiSelect, UiIcon packages/nuxt-layer-ui/app/components/ui/UiX.vue required
2 Composites a few primitives with one job: UiForm, UiFormField, UiFormErrorSummary, UiFormActions, UiConfirmDialog, UiConfirmInline, UiUndoNotice packages/nuxt-layer-ui/app/components/ui/UiX.vue required
3 Complex data-heavy widgets: UiDataTable, UiChart, UiRichTextEditor packages/nuxt-layer-ui/app/components/ui/UiX/ the simplest semantic equivalent
App portfolio views: AppStyleStudio, AppPrimaryNav, AppMediaFile / AppMediaFallback / AppPlaceholderMedia (media fallbacks) core/web/app/components/ —
Admin admin views: AdminMediaDrawer, AdminNav core/admin/app/components/, packages/web-layer-admin/app/components/ —

Logic lives in composables and utils; components are views. A component that both apps need goes into a layer, never into one app for the other to reach.

The four form parts (UiForm, UiFormField, UiFormErrorSummary, UiFormActions) render the same native markup in both stacks; only the controls slotted into them differ. UiConfirmDialog renders through UiDialog, so it is PrimeVue’s Dialog when PrimeVue is on and a native <dialog> when it is off. See Forms.

Folders

Naming

API conventions

Styling

When a component may drop the native fallback

Tiers 0–2 always keep a native branch with the same props, v-model, accessible name and keyboard behaviour. A tier 3 component may replace the PrimeVue look-alike with the simplest semantic equivalent when all of these hold:

A component never falls back to nothing, and the fallback is recorded in the component’s JSDoc header and its docs page.

With features off

An app can turn the theme, the icons, PrimeVue and the media components off with tgmc: flags (nuxt-layers.md § 1a). The accessibility floor stays in every mode:

Media that fails to load

Media slots and case studies show a labelled stand-in for a failed file; other kit images show an empty frame named by alt, never a broken-image icon. The gallery video has no fallback yet (TODO).

Details, names per kind and tests: site media § Fallbacks.

Lists and deletes

Four composables and two tier 2 components cover a list that pages, filters and deletes. The pure code is in packages/nuxt-layer-ui/app/crud/ (export ./crud, Vue reactivity only, so plain Vitest drives it with fake timers); the composables in app/composables/ add the announcer, focus and the route. The composables and both components are auto-imported; the types come from @tgmc/nuxt-layer-ui/crud (CrudAdapter, ConfirmUndo, RouteQueryCodec …).

useConfirmUndo(options)

Confirm in place, then 8 s to Undo before the real delete. Options:

It returns confirmingId, pending (one { id, item, label, message, deadline, paused, buttonId, messageId } per delete that can still be undone), committing (commit requests in flight), settling (something pending or committing), isPending(id), undoButtonId(id), request(item), cancel(), confirm(item), undo(id), pause(id, source?) / resume(id, source?) (source is 'pointer' or 'focus'; the window runs again once neither holds it) and flush().

UiConfirmInline and UiUndoNotice

UiConfirmInline is the question that takes the place of the control that asked (“Delete X? [Delete] [Cancel]”). Props: question (required), confirmLabel (default “Delete”), cancelLabel (default “Cancel”), initialFocus ('cancel', the default, or 'confirm'). Events: confirm and cancel. It is a role="group" named by the question; Escape emits cancel and goes no further.

UiUndoNotice lists the deletes that can still be undone (“Deleted X. [Undo]”), one line each, and renders nothing when there are none. Props: undoable (the useConfirmUndo / useCrudResource().undoable controller; required), label (the list’s name, default “Recently deleted”), undoLabel (default “Undo”) and holdSpace (default off). It is not a live region: the controller announces through the page’s announcer, so the text is spoken once. Undo is described by its line (aria-describedby).

UiConfirmInline(
  v-if="undoable.confirmingId.value === post.id",
  :question="`Delete ${post.title}?`",
  @confirm="undoable.confirm(post)",
  @cancel="undoable.cancel()"
)
UiButton(v-else, label="Delete…", severity="danger", variant="text", @click="undoable.request(post)")
UiUndoNotice(:undoable="undoable")

usePagedList(options)

“Load more” paging. Options: fetchPage({ offset, limit, signal }) returning { items, total? }, pageSize (default 24), getId (drops rows a page repeats, so rows added elsewhere don’t show twice), announce(result) (the Load more wording), onError(error, 'first' | 'more'), enabled(), key (a new value reloads from the first page), immediate (load on mount; default on) and announcer (default on). It returns items, total (number | null), loading, loadingMore, loaded, error, hasMore, status, load(), loadMore(), reset() and abort().

useCrudResource(adapter, options)

A paged list over a CrudAdapter with confirm + Undo deletes and create / update.

useRouteQueryState(codec, defaults)

Filter state kept in the URL. codec has keys (the query keys it owns), read(query, defaults), write(state, defaults) (only values that differ from the defaults), and optional isFiltered (default: write returns a key) and cleared (default: defaults); firstQueryValue() reads the first value of a repeated key. It returns a ref per state key plus filtered and clear().

Differences from the blueprint

The kit follows nuxt-layers.md § 4 except where the pages needed more (the blueprint is read-only for this change; the owner updates it from this list):

Tests

Every kit component gets a mounted spec, packages/nuxt-layer-ui/tests/nuxt/ui-<component>.spec.ts, run by the nuxt-layer-ui:nuxt Vitest project (mountSuspended against the layer running as a Nuxt app). Each spec covers:

The lists and deletes code has a mounted spec for UiConfirmInline (ui-confirm-inline.spec.ts) and for each composable (use-confirm-undo, use-paged-list, use-crud-resource, use-route-query-state), plus features-off specs for UiConfirmInline and UiUndoNotice (tests/nuxt-off/ui-confirm-inline-off.spec.ts, ui-undo-notice-off.spec.ts). Pure helpers get plain Vitest specs in packages/nuxt-layer-ui/tests/ (for the crud code: confirm-undo, paged-list, crud-resource and route-query-state). Run everything with npx nx run @tgmc/nuxt-layer-ui:test.

Helpers

UiButton

packages/nuxt-layer-ui/app/components/ui/UiButton.vue. The same props work in both stacks: the PrimeVue stack renders Button, the native stack a <button> / <a> with the same classes.

Prop Type Notes
label string Visible text.
icon Lucide name Decorative; an icon-only button needs ariaLabel.
ariaLabel string The accessible name of an icon-only button.
severity secondary, success, info, warn, danger, contrast, help Primary when unset.
variant outlined, text, link, ghost ghost is text plus the hover wash.
size sm, md (default), lg Padding only. PrimeVue’s small / large are not valid values.
loading boolean See the rules below.
to route location Renders a NuxtLink.
href string Renders an <a>.
external boolean With href or to: opens a new tab.
flat boolean Flat solid fill; automatic inside forms, search and field groups.
type button (default), submit, reset Never rendered on a link.
disabled boolean Never rendered as the disabled attribute on a link.

Rules:

//- Button
UiButton(label="Save", @click="save")

//- Icon-only: the name goes on the button
UiButton(icon="x", variant="text", aria-label="Close details", @click="close")

//- Loading: stays focusable, and a submit button won't submit twice
UiButton(type="submit", label="Save", :loading="saving")

//- Internal link (client-side navigation)
UiButton(to="/admin/blog", label="Back", variant="outlined")

//- External link (new tab, announced)
UiButton(href="https://example.com/deck.pdf", label="Download deck", icon="file-text", external, download)

UiTabs

packages/nuxt-layer-ui/app/components/ui/UiTabs.vue: PrimeVue Tabs when PrimeVue is on, otherwise a native role="tablist" with the same p-tabs / p-tab classes. Used by the evidence-examples dialog (AppEvidenceExamplesDialog) and /product; core/admin has none. The theme styles both stacks as plain tabs (ink-muted labels, the selected one ink, bold and underlined in --theme-link-color, 44px, focus ring, forced-colors Highlight): see theme.md § Tabs.

UiDialog

packages/nuxt-layer-ui/app/components/ui/UiDialog.vue. PrimeVue’s Dialog when PrimeVue is on, otherwise a native <dialog class="p-dialog p-component"> with the same props: visible (v-model:visible), header, ariaLabel, role (dialog by default, or alertdialog), modal (default true), closable (default true) and dismissableMask (default true). It has a default slot and a footer slot. Other attributes, such as aria-describedby, go on the dialog root.

Forms

The forms template is four tier 2 parts and one composable. UiForm, UiFormField, UiFormErrorSummary and UiFormActions read the controller that useForm() returns. The schema can be any Standard Schema; the apps use zod 4. The admin blog editor (packages/web-layer-admin/app/pages/admin/blog/[id].vue) is the reference page. The design, and why the layer doesn’t use @primevue/forms, are in nuxt-layers.md § 3.

UiForm(:form="form", aria-labelledby="post-form-title")
  UiFormErrorSummary
  UiFormField(name="title", label="Title", required, v-slot="{ field, invalid }")
    UiInputText(v-bind="field", :invalid="invalid")
  UiFormField(name="body", label="Body", hint="Markdown", required, v-slot="{ field, invalid }")
    UiTextarea(v-bind="field", :invalid="invalid", :rows="16")
  UiFormActions
    UiButton(type="submit", label="Save", :loading="form.pending.value")
UiConfirmDialog(v-bind="leavePrompt.dialog.value")
const form = useForm({
  id: 'post',
  schema: blogPostCreateSchema,
  initialValues: { title: '', slug: '', excerpt: '', body: '', status: 'draft' },
  async onSubmit(values, { signal }) {
    const saved = await adminFetch<BlogPost>(`/api/admin/posts/${id}`, { method: 'PUT', body: values, signal });
    for (const name of FIELDS) form.rebase(name, saved[name]);
  },
});

const leavePrompt = useUnsavedChangesGuard(form.dirty, {
  allow: (to) => deleted.value || isAdminSignInPath(to.path),
  focusOnStay: () => document.getElementById('post-title'),
});

The parts

All four throw “<Component> must be used inside UiForm” when they are rendered outside a UiForm.

useForm(options)

Auto-imported from the ui layer. The types and createFormController (the same controller without Nuxt) come from @tgmc/nuxt-layer-ui/forms. Options:

It returns the controller: id, values, errors, formError, touched, dirty, pending, status (idle, invalid, pending, saved or failed), statusMessage, submitCount, errorCount (fields with an error, plus one for a form-level error), fieldId(name), error(name) (the first message), field(name), handleSubmit(event?), validate(name?), setErrors(errors), reset(values?), rebase(name, value), focusFirstInvalid() and abort().

What a submit does:

“Saved” needs a clean form. statusMessage shows the saved text only while the form isn’t dirty, and the announcer skips “Saved” when the form is still dirty after onSubmit returns. So after a successful save the page adopts what the server saved: form.rebase(name, savedValue) for each field (the server may normalise a value, as it does the slug), or form.reset(saved). A page that does neither never shows or announces “Saved”. The next edit hides the line again.

Server errors (422 and 409)

@tgmc/nuxt-layer-ui/form-errors (packages/nuxt-layer-ui/shared/form-errors.ts) holds what client and server share. It has no Vue and no DOM, so Nitro handlers import it too:

A write handler throws createError({ statusCode: 422, statusMessage, data: { fieldErrors, formError } }). Nitro puts data inside its JSON error body, and ofetch puts that body at error.data, so readServerFormError reads error.data.data. Without that payload it falls back to the response’s status message, then the error’s, then fallback. Keep statusMessage ASCII, because h3 strips any other character from it; the full text travels in data. The admin blog API’s contract (422 for invalid fields, 409 on fieldErrors.slug, 404 and 400 on formError) is in admin.md § Write errors.

Unsaved changes: the leave dialog

const leavePrompt = useUnsavedChangesGuard(form.dirty, { allow, focusOnStay });

Then render UiConfirmDialog(v-bind="leavePrompt.dialog.value") once in the page template. The guard returns { open, stay, leave, dialog }; dialog carries visible, the texts and the onConfirm / onCancel listeners.

UiConfirmDialog

A yes / no question in a modal alertdialog, rendered through UiDialog. Props: visible (required; the parent owns it), header, message, confirmLabel (default “Confirm”), cancelLabel (default “Cancel”) and confirmSeverity (danger, the default, or contrast). Events: confirm and cancel.

UiConfirmDialog(
  :visible="asking",
  header="Discard this draft?",
  message="The draft is deleted for good.",
  confirm-label="Discard",
  @confirm="discard",
  @cancel="asking = false"
)

Responsive, keyboard, screen reader and touch