@tgmc/nuxt-layer-ui
Nuxt 4 layer with PrimeVue and the Ui* component kit. It extends
@tgmc/nuxt-layer-base, so an app that extends it also gets the theme
stylesheet, Sass auto-use, @nuxt/a11y, @nuxt/icon and the a11y shell components. core/web and
@tgmc/web-layer-admin extend it; core/admin gets it through @tgmc/web-layer-admin. The wider
layer design is in nuxt-layers.md. Component rules (folders, naming, API, tests):
UI components.
What it provides
- PrimeVue:
@primevue/nuxt-modulein styled mode with the theme preset and theprimevuecascade layer. Options come fromtgmcPrimeVueConfig()(src/config/primevue.ts, export@tgmc/nuxt-layer-ui/primevue), which iscreatePrimeVueNuxtConfig()from@tgmc/theme/primevuewith its defaults; a test pins that equality. PrimeVue components are namedPrime*; the kit wraps them. PrimeVue is installed bysrc/module/tgmc-ui.ts(which stands where@primevue/nuxt-modulestood, so module and CSS order are unchanged) unlesstgmc: { primevue: false }. It needs the theme:{ primevue: true, theme: false }fails the build. Off:Prime*tags are null stubs (src/config/prime-components.ts, kept equal to the templates by a test) and the kit renders native markup. - Components: 39
Ui*components inapp/components/ui, registered without a path prefix (UiButton,UiDialog,UiToastHost…), plusUiImage.scss.UiButtontakeslabel,icon,ariaLabel,severity,variant(outlined/text/link/ghost),size(sm/md/lg),loading,to/href/external,flatandtype/disabled(reference). The tier 2 composites are listed below.UiCodeBlockstays incore/web/app/components/uibecause it uses the web syntax engine (core/web/shared/syntax). UiImageneeds the app’s @nuxt/image. It rendersNuxtImg(the layer does not depend on @nuxt/image). Itswidthsmode (aw-descriptor srcset with a nativesizesstring) also needs the URL builder as$img, which the app exposes withimage: { inject: true }; without it (core/admintoday)widthsis ignored andNuxtImgrenders the image with its own srcset (site media § Responsive sizes and format). A readysrcsetprop (url 640w, url 1280w, from the media variant resolver) is rendered as given on the same plainimgwithsizesnative; it wins overwidthsand works without$img. A failed load (or one that failed before hydration) emitserror, replaces the image with the#fallbackslot inside the same frame (ratio and dominant colour kept), names the frame withalt(role="img") or hides it when decorative, and clears on a newsrc. Without afallbackslot the frame is empty, never a broken-image icon. The optionalfallbackLabelprop makes the failed frame’s name<fallbackLabel>: <alt>(justaltwithout it; a decorative image stays unnamed). The frame isrole="img", so#fallbackcontent is presentational: it is never exposed on its own, which is why the label is a prop and not slot text.UiSvgImghas the same failure contract. It emitserror, swaps the<img>forspan.ui-svg-img--failed(keeps the caller’s class/style,data-error="",role="img"+aria-labelfromaltandfallbackLabel, oraria-hidden="true"foralt="") holding the#fallbackslot, counts a hydrated<img>with the SSRdata-errormarker as failed, and clears on a newsrc.- Composables (auto-imported):
useUiStack()/resolveUiStack()(PrimeVue, Foundation bridge or native markup, fromruntimeConfig.public.theme),useAppToast(),createAppToastApi()andnativeToasts;useForm()(form state on a Standard Schema) anduseUnsavedChangesGuard(), which returns{ open, stay, leave, dialog }for the in-page leave dialog (Forms);useUnloadGuard(dirty)(the browser’s reload / close prompt alone, also used by that guard, admin media Details and the Style Studio draft);usePagedList()(“Load more” paging),useConfirmUndo()(confirm in place, then Undo),useCrudResource()(a paged list over aCrudAdapterwith those deletes) anduseRouteQueryState()(filter state in the URL) (Lists and deletes). - Exports:
./primevue,./toast,./form-errors,./forms,./crudand./components/*../form-errors(shared/form-errors.ts) holds the form error shapes and readers (FieldErrors,ServerFormError,issuesToErrors,readServerFormError,errorSummaryHeading); it has no Vue and no DOM, so Nitro handlers import it. Web ESLint exempts this pure subpath from Nx’s static-versus-dynamic import check because component tests load other UI subpaths dynamically../forms(app/forms/form-controller.ts) holds the form types (FormController,UseFormOptions,FieldBinding,FormStatus…),createFormController(the controller without Nuxt),FORM_CONTEXTandinjectFormContext. Nuxt doesn’t scanapp/forms/, so its helpers (clone,deepEqual, the leave prompt inunsaved-changes.ts) never leak into an app’s auto-imports../crud(app/crud/) holds the pure list and delete code behind the four composables:createConfirmUndo,createPagedList,createCrudResource, the route query codec helpers and their types (CrudAdapter,ConfirmUndo,RouteQueryCodec…). It needs only Vue, so plain Vitest drives it with fake timers; Nuxt doesn’t scan it either../components/*(app/components/*) lets another project’s tests import aUi*SFC by package name (@tgmc/nuxt-layer-ui/components/ui/UiButton.vue) instead of a relative path, which@nx/enforce-module-boundariesrejects; apps keep using the auto-imports. $toast:app/feature-plugins/toast-primevue.client.ts(ToastService) ortoast-native.client.ts(the native listUiToastHostrenders), added by the ui module. The folder isn’t auto-scanned, so PrimeVue never loads when it is off. Either wayuseNuxtApp().$toast.show({ summary })anduseAppToast()work. Types:import type { AppToastApi, AppToastSeverity } from '@tgmc/nuxt-layer-ui/toast'.- Media:
app/components/media(empty until the media components land) is registered only withtgmc.media;@tgmc/media-clientand@tgmc/media-playerare optional peers. - Nitro: the layer adds
nitro.externals.inline: ['@primeuix/utils']. The base layer inlinesnuxt, and withnuxtinlined, PrimeVue pages fail with'@primeuix/utils/classnames' does not provide an export named 'mergeKeys'unless@primeuix/utilsis bundled too. It is added in every mode, becauseUiImagestill imports the theme’s JS entry, which imports@primeuix(nuxt-46-renderer-externalized-500.md).
The layer registers no imports.dirs: Nuxt scans its own app/composables, and the components entry
points at app/components/ui with pathPrefix: false. The ui module adds the toast plugin and, with
media on, the media components directory.
Tier 2 composites
| Component | Job |
|---|---|
UiForm |
The <form> for a useForm() controller: novalidate, aria-busy while saving, the context for its parts. |
UiFormField |
One labelled control: label, hint, error and the aria-* wiring, through the slot { field, invalid }. |
UiFormErrorSummary |
After a failed submit: the number of problems and a link to each invalid field. |
UiFormActions |
The action row and the visible “Saving…” / saved line. |
UiConfirmDialog |
A yes / no alertdialog on UiDialog, Cancel focused first; the leave dialog uses it. |
UiConfirmInline |
“Delete X? [Delete] [Cancel]” in place of the control that asked; Cancel focused first, Escape cancels. |
UiUndoNotice |
“Deleted X. [Undo]” per undoable delete, with a hint naming the window (“Available for 8 seconds; waits while you point at it or focus it.”, from the controller’s delayMs); the time stops on hover or focus; holdSpace keeps the space. |
The four form parts render the same native markup in both stacks. Reference: UI components § Forms and, for the two delete parts, UI components § Lists and deletes.
What the app keeps
runtimeConfig.public.theme(mode,uiStack,bridges). Without it the kit renders PrimeVue. Withtgmc: { primevue: false }the base layer’s module setsbridges.primevuetofalsefor it.- Its
tgmc:feature flags (nuxt-layers.md § 1a). - Its stylesheet entry (
#tgmc-theme-stylesheetalias) and its own icon names. - Components that need app code, such as
UiCodeBlockincore/web.
Usage
// nuxt.config.ts
export default defineNuxtConfig({ extends: ['@tgmc/nuxt-layer-ui'] });
Declare "@tgmc/nuxt-layer-ui": "*" in the app’s dependencies. primevue and
@primevue/nuxt-module (version "4", the root’s range) and @tgmc/media-client / @tgmc/media-player
are optional peers: an app declares the ones whose feature it keeps on (core/web and core/admin
list the PrimeVue pair themselves) or turns the feature off
(nuxt-layers.md § 1a). @primeuix/themes arrives through
@tgmc/theme/primevue. In @tgmc/web and @tgmc/admin, the layer is in nitro.externals.inline.
The layer depends on @standard-schema/spec (types only), so useForm() takes any Standard Schema
library. Apps add zod (or another Standard Schema library) themselves; the layer has zod only as a
devDependency for its tests. @tgmc/web-layer-admin and core/web declare zod ^4.6.7.
core/admin registers no core/web component or composable paths: the kit, useUiStack and the
toast plugin come from this layer, and the overlay helpers from the base layer.
Why the layer has a browserslist
The CSS pipeline picks the browserslist of the nearest package.json. While the kit sat inside
core/web it compiled against web’s targets; in packages/nuxt-layer-ui it would fall back to the
default query and emit older output (#0000 became transparent, :is(…) was expanded, -o-object-fit
was added). The layer’s package.json therefore carries the same browserslist as core/web, and
tests/config.spec.ts pins the two together. Admin’s own SFCs, outside the kit, still compile with the
default query as before.
Development
- Component rules (folders, naming, API, tests): UI components.
- Tests:
npx nx run @tgmc/nuxt-layer-ui:test(49 files; 458 tests pass and 7 are skipped). Three Vitest projects:nuxt-layer-ui: jsdom unit tests with@vue/test-utils(config,primevue,app-toast,ui-control-id,use-ui-stack,ui-button-outlined,ui-button-focus-ring,focus-control,control-attrs,colors-scss,prime-components, the pure form code:form-errors,form-values,form-controller,unsaved-changes, and the pure list and delete code:confirm-undo,paged-list,crud-resource,route-query-state), plusui-module, which boots the layer withloadNuxtto check what each flag installs and registers.nuxt-layer-ui:nuxt:@nuxt/test-utilswithenvironment: 'nuxt'. It mounts fixtures intests/nuxt/fixtures/withmountSuspendedagainst the layer running as a Nuxt app (harness,primevue, the component matrix:ui-buttonplus the six form controls,ui-icon-off/ui-toast-hostfor icons off and the native toast list, andui-form,ui-dialog,ui-confirm-dialogandunsaved-changes-guardfor the forms template and the dialogs;ui-messagefor its live region;ui-confirm-inlineanduse-confirm-undo,use-paged-list,use-crud-resourceanduse-route-query-statefor lists and deletes). New mounted specs go intests/nuxt/ui-<component>.spec.tsand follow UI components § Tests. Specs that mount a native<dialog>install the jsdom shim fromtests/nuxt/support/dialog-shim.ts.nuxt-layer-ui:nuxt-off: the same setup with every flag off (tgmc: { theme: false, icon: false, primevue: false, media: false }) and its own build dir undernode_modules/.cache/nuxt-off, so the two test apps never share generated files.tests/nuxt-off/a11y-floor.spec.tschecks the accessibility floor: no Vue warning, native controls with visible names, the skip link, the announcer and the native toast regions.ui-form-offandui-confirm-dialog-offmount the forms template andUiConfirmDialogthere;ui-confirm-inline-offandui-undo-notice-offdo the same for the delete parts.
- Build matrix:
npx nx run @tgmc/nuxt-layer-ui:test:build-matrix(2 files, 8 tests, about 45 s;vitest.build-matrix.config.ts). It runs a realnuxt buildof two fixture apps intests/build-matrix/fixtures/(all-onandall-off, both extendingshared/, one page using the a11y shell and the kit) and serves each with@nuxt/test-utils/e2e. A probe module (fixtures/shared/probe.ts) records the installed modules, registered components and component directories, and whether any PrimeVue, icon or media module was bundled; the specs then check those, the emitted CSS (theme or system-colour fallback, focus rings) and the server-rendered HTML. CI runs it in the “Affected build matrix” step;npm testand the pre-push hook don’t. A new feature flag gets a probe marker and a check in both specs.- Colour guard:
tests/colors-scss.spec.tsallows theme roles only inapp/;UiColorPicker’s#000000is the one data literal.
- Colour guard:
- The Nuxt project needs a small plugin in
vitest.config.ts: Nuxt’s builder runs on Vite 8 (rolldown) while Vitest runs on the root’s Vite 7, which cannot run the rolldown-onlynuxt:replaceplugin, so the config drops it and applies theimport.meta.*defines itself. - The harness boots the layer as its own Nuxt root and writes
components.d.ts(by@primevue/nuxt-module) and.nuxtrc.packages/nuxt-layer-ui/.gitignoreignores the generatedcomponents.d.ts, and the one each build-matrix fixture writes;.nuxtrcis committed. - Lint:
npx nx run @tgmc/nuxt-layer-ui:lint. Typecheck (src/**,shared/**andapp/forms/**; not the.vuefiles orapp/composables):npx nx run @tgmc/nuxt-layer-ui:typecheck --skip-sync --excludeTaskDependencies(same caveat as the base layer). - Guards:
core/web/tests/{components-scss,colors-scss,ui-floors,icons}.spec.tswalkpackages/nuxt-layer-ui/app(core/web/tests/support/ui-source-roots.ts), so later moves into the layer need no guard edits.layer-dependency-ranges.spec.tschecks the manifest against the root ranges, andapps-extend-base.spec.tschecks that the apps extend the layer and that admin has nocore/webkit paths. - Open follow-ups: interaction-redesign.md § Nuxt layers, § PR 2 Task 5, § PR 2 Task 5b and § PR 3 Task 7.