@nxgt/material-vue 0.40.1 → 0.42.0

package/docs/guides/app-shell.md

@@ -17,10 +17,7 @@ const items: MenuItem[] = [
 </script>
 
 <template>
-  <ActivityLayout :items="items" avatar-src="/me.png">
-    <template #brand>
-      <strong>Acme</strong>
-    </template>
+  <ActivityLayout :items="items" logo="/logo.svg" name="Acme" avatar-src="/me.png">
     <RouterView />
   </ActivityLayout>
 </template>
@@ -179,7 +176,11 @@ partitionMenu(items);                              // { content, footer }
 | `content-as` | `'main' \| 'div'` | `'main'` | The content region's element: the page's `<main>` landmark, or a `div` when your app renders its own `<main>` |
 | `scroll` | `'document' \| 'container'` | `'document'` | Who scrolls: the page (header and sidebar sticky), or the content region inside a shell one screen high |
 | `class` | `string` | — | Classes for the outer element (`[data-slot=activity-layout]`), which takes the other attributes too |
-| `#brand` | slot | an atom icon | Replaces the sidebar header: a logo, a product name. Always fill it; the default is a placeholder |
+| `logo` | `string \| { src, alt? }` | an atom badge | The app's logo, an image URL: alone in the collapsed rail, beside `name` in the phone's menu sheet (see [The brand](#the-brand-logo-and-name)) |
+| `#logo` | slot | — | The logo as a node (an inline SVG), in place of `logo`; it wins when both are given |
+| `name` | `string` | — | The app's name, already translated: the logo's accessible name and tooltip in the rail, shown beside it in the sheet |
+| `#brand` | slot | — | Replaces the sidebar header entirely, in the rail and in the menu sheet; wins over `logo` and `name` |
+| `#header-title` | slot | — | The header's leading title: the context the app is in (the active organisation's name), right after the phone's menu button, truncated when long |
 | `#header-actions` | slot | — | In the header, before the avatar: notifications, help, `LanguageSwitcher`, `ThemeToggle` |
 | `#avatar` | slot | the `avatar-src` image | Replaces the avatar entirely |
 | default | slot | — | The routed content, usually `<RouterView />` |
@@ -214,32 +215,26 @@ the slots.
 ```vue
 <script setup lang="ts">
 import {
+  AccountMenu,
   ActivityLayout,
-  Avatar,
-  AvatarFallback,
-  AvatarImage,
   LanguageSwitcher,
   type MenuItem,
   ThemeToggle,
 } from '@nxgt/material-vue/components';
 
-defineProps<{ items: MenuItem[]; user: { name: string; picture?: string } }>();
+defineProps<{ items: MenuItem[]; user: { name: string; email: string; picture?: string } }>();
+const emit = defineEmits<{ 'sign-out': [] }>();
 </script>
 
 <template>
-  <ActivityLayout :items="items">
-    <template #brand>
-      <img src="/logo.svg" alt="Acme" class="h-8" />
-    </template>
+  <ActivityLayout :items="items" logo="/logo.svg" name="Acme">
+    <template #header-title>Northwind school</template>
     <template #header-actions>
       <LanguageSwitcher />
       <ThemeToggle />
     </template>
     <template #avatar>
-      <Avatar>
-        <AvatarImage :src="user.picture ?? ''" :alt="user.name" />
-        <AvatarFallback>{{ user.name.slice(0, 2) }}</AvatarFallback>
-      </Avatar>
+      <AccountMenu :name="user.name" :secondary="user.email" :src="user.picture" @sign-out="emit('sign-out')" />
     </template>
     <RouterView />
   </ActivityLayout>
@@ -254,7 +249,92 @@ entry closes it — so does any route change, Back included — and focus goes t
 the page's `<main>`, unless the new screen already focused an element inside it
 (an error page's `h1`), which keeps it; closed with Escape, the close button or the overlay,
 focus returns to the menu button. Its entries show their labels, so they have
-no tooltip: none opens over the first entry as focus moves in.
+no tooltip: none opens over the first entry as focus moves in. It shows the
+app's `logo` and `name` (or `#brand`) above the entries, as the expanded
+sidebar does.
+
+### The app bar: a title, the actions, the account
+
+The header reads, from the start: the phone's menu button, `#header-title`
+(the context the app is in, the active school or organisation), then
+`#header-actions` (language, notifications) and `#avatar` at the end. The
+title takes the room left and ends in an ellipsis when it does not fit, so
+the avatar always stays on screen. It is not a heading: the screen's `h1` is
+`ActivityContent`'s title.
+
+`AccountMenu` is the `#avatar` most apps want: an avatar button named
+"Account menu, Ada Lovelace" (`material.account-menu.trigger`) that opens a
+menu aligned to its end, headed by the avatar, the name and `secondary`, then
+the app's `items` and a destructive Sign out
+(`material.account-menu.sign-out`). Choosing Sign out emits `sign-out` and
+keeps the menu open: pass `signing-out` while the request runs, and the item
+shows a spinner and ignores a second selection. Without `src`, or until it
+loads, the avatar shows the initials on `bg-primary`.
+
+```vue
+<AccountMenu
+  :name="user.name"
+  :secondary="user.email"
+  :src="user.picture"
+  :items="[
+    { label: t('menu.profile'), url: '/profile', icon: 'user' },
+    { label: t('menu.settings'), url: '/settings', icon: 'gear' },
+  ]"
+  :signing-out="pending"
+  @sign-out="signOut"
+/>
+```
+
+Each entry is an `AccountMenuItem`, exported with it:
+
+```ts
+type AccountMenuItem = {
+  label: string; // already translated
+  url: string; // rendered as a real link through `link-component`
+  icon?: IconName; // optional, decorative: the label names the entry
+};
+```
+
+`icon` is an `IconName`, a symbol id of the Font Awesome duotone sprite you serve (`user`, `gear`, `arrow-right-from-bracket`; browse the names at <https://fontawesome.com/icons>, and see [getting started](../getting-started.md#icons) for serving the sprite).
+
+### The brand: logo and name
+
+`logo` (or the `#logo` slot) and `name` put the app's brand in the sidebar
+header, in the shape each place has room for. `logo` is typed `AppLogo`
+(`string | AppLogoImage`, where `AppLogoImage` is `{ src: string; alt?: string }`
+and a string is the image URL), both exported from
+`@nxgt/material-vue/components`:
+
+- **The collapsed rail** (desktop, about 70 px wide) shows the **logo alone**.
+  `name` is its accessible name (an `<img alt>`, or `role="img"` with an
+  `aria-label` around the `#logo` node) and shows as a tooltip on hover, to
+  its right.
+- **The expanded sidebar and the phone's menu sheet** show the **logo and the
+  name side by side**. The name is on screen there, so the logo is decorative
+  (`alt=""` or `aria-hidden`), and no tooltip repeats it.
+
+```vue
+<ActivityLayout :items="items" logo="/logo.svg" :name="t('app.name')">…</ActivityLayout>
+<!-- An image with its own alt, used when there is no name: -->
+<ActivityLayout :items="items" :logo="{ src: '/logo.svg', alt: 'Acme' }">…</ActivityLayout>
+<!-- A node, an inline SVG for instance: -->
+<ActivityLayout :items="items" name="Acme">
+  <template #logo><AcmeMark class="size-8" /></template>
+  …
+</ActivityLayout>
+```
+
+Without a logo the header keeps its placeholder atom badge (named by `name`
+in the rail when there is one); fill `logo` in a real app. `#brand` is the
+full override: one node rendered as given, collapsed or expanded alike, in the
+rail and in the menu sheet. `AppSidebar` takes the same props and slots, and
+`AppHeader` takes them for its menu sheet.
+
+`#brand` is rendered twice, once in the rail and once in the menu sheet (the
+rail stays in the page on a phone, hidden): an `id` inside it appears twice
+while the sheet is open, so leave ids out of it. A link in `#brand` (a home
+link around the logo) is the sheet's first focusable element, so it takes
+the focus when the sheet opens.
 
 ## Landmarks, headings and scrolling
 
@@ -375,7 +455,7 @@ home included, is a `RouterLink`, so it goes through the router's base: under
 `AppSidebar`, `AppHeader` and `AppBreadcrumb` are exported for a layout of your
 own. `AppSidebar` and `AppHeader` take the same `items`; `AppSidebar` also
 takes `expanded` (`v-model:expanded`) and `with-toggle-icon`, and has the
-`#brand` slot; `AppHeader` takes `avatar-src` and `show-menu-icon` (default
+`#brand` slot, `logo`, `name` and `#logo`; `AppHeader` takes `avatar-src`, `logo`, `name` and `show-menu-icon` (default
 `true`), with `#actions`, `#avatar` and a default slot for the middle of the
 bar. The lower-level `Sidebar`, `TopAppBar`, `NavigationRail` and `Breadcrumb`
 primitives are on the

package/docs/guides/forms.md

@@ -315,10 +315,16 @@ shows them right under its fields.
   `form-actions` gets the same sticky footer.
 - A focused control or link is scrolled into view clear of the actions and
   a line of helper text below it (`scroll-margin-bottom` on the fields'
-  controls: 6rem, plus a dialog's bottom padding, 7.5rem above a
-  `ConfirmationDialog`'s stacked footer), so a field you tab to is never
-  hidden behind them (WCAG 2.4.11). It is set on the controls, so it holds
-  in a scroll box of your own too.
+  controls: 6rem, 8rem on a phone, plus a dialog's bottom padding, plus the
+  safe-area inset beyond 1rem, 7.5rem above a `ConfirmationDialog`'s stacked
+  footer), so a field you tab to is never hidden behind them (WCAG 2.4.11).
+  It is set on the controls, so it holds in a scroll box of your own too.
+- The actions pad their bottom for the safe area
+  (`max(1rem, env(safe-area-inset-bottom))`): in an installed app with
+  `viewport-fit=cover`, they clear the home indicator. The phone default
+  (below `sm`, where the buttons share the row) comes from
+  `--form-actions-clearance-default`, which is internal: override
+  `--form-actions-clearance` instead.
 - Taller actions (a third button, labels that wrap) or helper text on
   several lines need more room: raise `--form-actions-clearance` on the
   form. A dialog whose bottom padding is not the default 1.5rem (`p-0` and

package/docs/guides/i18n.md

@@ -292,7 +292,7 @@ the `LocationPreview` trigger (`material.map.preview` / `preview-named`),
 (`material['duration-field']['hours-label']` / `minutes-label`), and
 the delete button of the deprecated `ContactItem` / `OpeningHoursItem`
 (`material.contacts.buttons.remove`,
-`material['opening-hours'].buttons.remove`). `FacetGroup`'s toggle is named "Level, 2 selected" / "Level, 2 sélectionnés" (`material.facet-group.name`, an ICU plural over `{title}` and `{count}`) and its Clear button "Clear Level" / "Effacer Level" (`material.facet-group.clear-label`, with the visible `material.facet-group.clear`). When the form of a
+`material['opening-hours'].buttons.remove`). `FacetGroup`'s toggle is named "Level, 2 selected" / "Level, 2 sélectionnés" (`material.facet-group.name`, an ICU plural over `{title}` and `{count}`) and its Clear button "Clear Level" / "Effacer Level" (`material.facet-group.clear-label`, with the visible `material.facet-group.clear`). `AccountMenu`'s avatar button is named "Account menu, {name}" / "Menu du compte, {name}" (`material.account-menu.trigger`, over `{name}`) and its last item reads "Sign out" / "Se déconnecter" (`material.account-menu.sign-out`), unless you pass `sign-out-label`. When the form of a
 `ConfirmationDialog` with `form-options` cannot be loaded, it says so in the
 form's place: "The form could not be loaded." / "Le formulaire n’a pas pu être
 chargé." (`material.confirm-dialog.form-failed`). The keys and the French are the

package/docs/roadmap.md

@@ -167,6 +167,15 @@ version they shipped in, and planned entries may name the major they target.
 
 ## Shipped
 
+- **The app's brand, a header title and an account menu** — the app shell
+  takes the app's `logo` and `name`: the logo alone in the collapsed rail,
+  named by the app's name and shown as its tooltip, the logo and the name side
+  by side expanded and in the phone's menu sheet, which now shows `brand` too;
+  `#header-title`, the context the app is in, right after the phone's menu
+  button and truncated when long; and `AccountMenu`, the avatar button named
+  "Account menu, <name>" that opens the account's name and e-mail, the app's
+  links and a busy-aware Sign out (`sign-out`).
+
 - **Rows a user adds, removes and reorders** — `RepeatableGroup` and
   `RepeatableGroupFormField` over the form library's field array: rows from
   the `row` slot, a list for assistive tech, Remove and move buttons named after

package/docs/troubleshooting.md

@@ -28,6 +28,7 @@ words in your error.
 - [A Button's label overflows a card on a phone](#a-buttons-label-overflows-a-card-on-a-phone)
 - [A dialog or sheet scrolls, or clips a child, after upgrading](#a-dialog-or-sheet-scrolls-or-clips-a-child-after-upgrading)
 - [A form's fields no longer scroll in their own box after upgrading](#a-forms-fields-no-longer-scroll-in-their-own-box-after-upgrading)
+- [axe reports `target-size` on a control under a form's sticky actions](#axe-reports-target-size-on-a-control-under-a-forms-sticky-actions)
 - [`JsBarcode is not a function`](#jsbarcode-is-not-a-function)
 - [A `LinkButton` selected as a `button` stops matching](#a-linkbutton-selected-as-a-button-stops-matching)
 - [A `Toc`, `Pager`, `SeeAlso` or `ScrollProgress` inside `Doc` selected by `data-slot` stops matching](#a-toc-pager-seealso-or-scrollprogress-inside-doc-selected-by-data-slot-stops-matching)
@@ -190,6 +191,7 @@ words in your error.
 - [A test's `getByRole('region')` finds more than one region](#a-tests-getbyroleregion-finds-more-than-one-region)
 - [A `DataTable` toolbar is gone](#a-datatable-toolbar-is-gone)
 - [axe reports `target-size` on a `DataTable`'s "Select all"](#axe-reports-target-size-on-a-datatables-select-all)
+- [A French test no longer finds the sort menu's "Asc" or "Desc"](#a-french-test-no-longer-finds-the-sort-menus-asc-or-desc)
 
 **PDF reader**
 
@@ -1311,6 +1313,26 @@ actions where they are, make them static:
 An app's own fixed bottom bar or floating action button now sits under the
 sticky actions (`z-index: 10`): give it a z-index above 10 (`class="z-20"`).
 
+### axe reports `target-size` on a control under a form's sticky actions
+
+**When:** since the form's actions stick to the bottom (see above), axe's
+`target-size` (WCAG 2.5.8) flags a field's control, a link or a button
+that sits half under the sticky `[data-slot="form-actions"]` bar, wherever
+the page happens to stop scrolling when the scan runs. The same control passes once scrolled into view.
+**Why:** axe measures what is visible of a target: the sticky bar covers part
+of the control, so axe sees a target smaller than 24 by 24 px, or one whose
+circle meets Cancel or Save. A user scrolls the control out from under the
+bar; a scan does not.
+**Fix:** scan with the actions put back in the flow, so nothing covers the
+fields, and keep the bar's own buttons in the scan:
+
+```ts
+await page.addStyleTag({
+  content: '[data-slot="form-actions"] { position: static !important; }',
+});
+await expectAccessible(page);
+```
+
 ## Feedback
 
 ### A toast with an action never goes away
@@ -3580,6 +3602,15 @@ page.getByRole('region', { name: 'Invoices' });
 **Why:** axe measures the 16px box itself, not its 24px `::before`, so it asks for a 24px circle around the box clear of every other control. The sort button reaches 12px back into its cell's padding (`-ml-3`), and the `select` cell had no padding after its checkbox: the circle met the button.
 **Fix:** upgrade: the `select` column's checkboxes now keep a 12px margin after them. Drop any axe `exclude` of `thead [data-slot="checkbox-field"]` you kept for it. A `select` column of your own (not `predefinedColumns().select`) needs the same: `me-3` on its checkboxes.
 
+### A French test no longer finds the sort menu's "Asc" or "Desc"
+
+**When:** after upgrading, a test running in French clicks the
+`DataTableColumnHeader` menu item "Asc" or "Desc" and finds nothing.
+**Why:** `material.table.labels.asc` / `desc` are now translated in French,
+"Croissant" / "Décroissant" (#612); English keeps "Asc" / "Desc".
+**Fix:** look for `getByRole('menuitem', { name: 'Croissant' })` (or
+`'Décroissant'`) in French.
+
 ---
 
 ---

package/lib/components/base-content.css

@@ -139,13 +139,23 @@
 				[contenteditable]
 			) {
 			scroll-margin-bottom: calc(
-				var(--form-actions-clearance, 6rem) +
-				var(--form-actions-fill, 0px)
+				var(
+					--form-actions-clearance,
+					var(--form-actions-clearance-default, 6rem)
+				) +
+				var(--form-actions-fill, 0px) +
+				max(0px, calc(env(safe-area-inset-bottom, 0px) - 1rem))
 			);
 		}
-		/* Sticky at the bottom of whatever scrolls the form: in reach. */
+		/* A phone's actions wrap their labels over two lines and a field has an
+		   error line: 8rem covers both (`--form-actions-clearance` still wins). */
+		@variant max-sm {
+			--form-actions-clearance-default: 8rem;
+		}
+		/* Sticky at the bottom of whatever scrolls the form: in reach. Padded
+		   for the safe area (`viewport-fit=cover`: the home indicator). */
 		[data-slot="form-actions"] {
-			@apply sticky bottom-0 z-10 flex w-full justify-end gap-2 bg-background/90 p-4 backdrop-blur-sm max-sm:*:flex-1;
+			@apply sticky bottom-0 z-10 flex w-full justify-end gap-2 bg-background/90 p-4 pb-[max(1rem,env(safe-area-inset-bottom))] backdrop-blur-sm max-sm:*:flex-1;
 		}
 	}
 

package/lib/nuxt/component-names.ts

@@ -4,6 +4,7 @@ export const COMPONENT_NAMES = [
 	'AccordionContent',
 	'AccordionItem',
 	'AccordionTrigger',
+	'AccountMenu',
 	'ActionCard',
 	'Activity',
 	'ActivityContent',

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@nxgt/material-vue",
-	"version": "0.40.1",
+	"version": "0.42.0",
 	"license": "MIT",
 	"bugs": {
 		"email": "stevegires@gmail.com"
@@ -124,7 +124,7 @@
 		"docs:previews": "vitest run --project previews"
 	},
 	"dependencies": {
-		"@nxgt/material-core": "^0.11.1",
+		"@nxgt/material-core": "^0.12.0",
 		"@floating-ui/dom": "^1.8.0",
 		"@fortawesome/fontawesome-common-types": "7.3.1",
 		"@lucide/vue": "^1.45.0",