@jskit-ai/users-web 0.2.20 → 0.2.22

package/CHANGELOG.md

@@ -2,6 +2,11 @@
 
 ## Unreleased
 
+- Account settings sections are pages in Material 3's list-detail layout (shell-web's `ShellListDetail`): `/account` lists the sections and `/account/<section>` opens one, instead of `?section=` on one page. `AccountSettingsClientElement` reads the route's `section` param and links each section to its path, keeping `returnTo`; on compact and medium windows it shows the list or one section, whose Up returns to the list, and on expanded and large windows the list beside the open section (or the first section on the list's own page), where Done replaces Up as the way out. The `users/account-settings` pattern adds `src/pages/account/[section].vue`, with parent `"/"`. Upgrading: add that page beside `src/pages/account/index.vue`, and change links to `/account?section=<value>` into `/account/<value>`.
+- Account settings have one way out: on a page with the shell's Up arrow (one that declares a parent) there is no Done action beside it, which read as a second back control. Done shows only where Up can't go back: a page without a parent, or a `returnTo` on another of the app's origins.
+- Account settings use Material 3's label type and single-column form: the section list's labels are label-large (14px/500) instead of Vuetify's 13px nav title, and `ProfileClientElement`'s and the pattern's display name and email each take the form's full width, so a long email no longer truncates in a half-width column.
+- The profile form's Save button, and the account-settings pattern's Save buttons, keep 16dp from the last field in every section; they touched it, as fields hide their empty details. The pattern's Avatar size select takes the same column width as the fields beside it.
+- The account settings section list marks the selected section with Material 3's pill indicator in `secondary-container`, as the shell's navigation does, instead of a grey rectangle; its hover and pressed state layers are pills too.
 - The account-settings pattern ships the account surface's layout, `src/pages/account.vue` (`ShellLayout` around `<RouterView />`, `meta.jskit.surface: "account"`), so the settings page's title, Up arrow and Done action show in the top app bar, with no navigation bar, rail or drawer on a surface that has no navigation. An app whose account page renders under no layout copies it; until then `jskit check` reports `nav/missing-shell-layout` on the page.
 - The account settings page and the account-settings pattern's sections sit directly on the page, without bordered sheets, and the section list has no extra border or tint.
 - The account settings page has no in-page title or Back button: it gives the shell's top app bar its title (`useShellPageTitle`) and a Done action (`ShellPageAction`) that returns to `returnTo`, another of the app's origins included, as Back did. Message keys: `jskit.users.accountSettings.back` is removed and `jskit.users.accountSettings.done` ("Done") is new. The pattern's section buttons no longer set a fixed height; they are Material 3's 40dp buttons inside material-web's 48dp touch target.

package/fixtures/account-settings/main.js

@@ -1,4 +1,5 @@
 import { createApp, h, reactive, ref, shallowReactive } from "vue";
+import { createPinia } from "pinia";
 import { createRouter, createWebHistory, RouterView } from "vue-router";
 import { QueryClient, VueQueryPlugin } from "@tanstack/vue-query";
 import "vuetify/styles";
@@ -7,8 +8,15 @@ import { createMaterialVuetifyOptions } from "@jskit-ai/material-web/client";
 import { createVuetify } from "vuetify";
 import * as components from "vuetify/components";
 import * as directives from "vuetify/directives";
+import { silentLogger } from "@jskit-ai/kernel/shared/support/silentLogger";
+import ShellLayout from "@jskit-ai/shell-web/client/components/ShellLayout";
 import { SHELL_WEB_ERROR_RUNTIME_KEY } from "@jskit-ai/shell-web/client/error";
 import { SHELL_WEB_PLACEMENT_RUNTIME_KEY } from "@jskit-ai/shell-web/client/placement";
+import { createWebPlacementRuntime } from "../../../shell-web/src/client/placement/runtime.js";
+import {
+  SHELL_NAVIGATION_RUNTIME_KEY,
+  createShellNavigationRuntime
+} from "../../../shell-web/src/client/navigation/shellNavigationRuntime.js";
 import AccountSettingsClientElement from "../../src/client/components/AccountSettingsClientElement.vue";
 import ProfileClientElement from "../../src/client/components/ProfileClientElement.vue";
 import { useAccountLocale } from "../../src/client/lib/accountLocale.js";
@@ -17,12 +25,27 @@ import PreferencesSection from "../../patterns/account-settings/example/src/comp
 import ProfileSection from "../../patterns/account-settings/example/src/components/account/settings/AccountSettingsProfileSection.vue";
 import SignInMethodsSection from "../../patterns/account-settings/example/src/components/account/settings/AccountSettingsSignInMethodsSection.vue";
 
+// The real shell (its layout, placements and navigation) around the real account settings code; the error runtime is
+// a double that records reports. The account surface is laid out as the account-settings pattern lays it out: /account
+// lists the sections and /account/<section> opens one, whose parent is the list.
+const sectionComponents = new Map();
 function section(value, title, component, order) {
-  return { order, component, props: { value, title, usesSharedRuntime: true } };
+  sectionComponents.set(`fixture.section.${value}`, component);
+  return {
+    id: `fixture.section.${value}`,
+    // The section outlet itself, as the app's topology resolves users-web's sections to it.
+    target: "account-settings:sections",
+    internal: true,
+    kind: "component",
+    surfaces: ["account"],
+    order,
+    componentToken: `fixture.section.${value}`,
+    props: { value, title, usesSharedRuntime: true }
+  };
 }
 
-// The shell's two runtimes as doubles; everything below them is the real account settings code.
-const context = {
+const placement = createWebPlacementRuntime({ components: sectionComponents, logger: silentLogger });
+placement.setContext({
   surfaceConfig: {
     tenancyMode: "none",
     defaultSurfaceId: "home",
@@ -32,9 +55,7 @@ const context = {
       account: { id: "account", enabled: true, pagesRoot: "account", routeBase: "/account", requiresWorkspace: false }
     }
   }
-};
-const listeners = new Set();
-let revision = 1;
+});
 let placements = new URLSearchParams(window.location.search).has("empty")
   ? []
   : [
@@ -43,16 +64,7 @@ let placements = new URLSearchParams(window.location.search).has("empty")
       section("notifications", "Notifications", NotificationsSection, 300),
       section("sign-in-methods", "Sign-in methods", SignInMethodsSection, 400)
     ];
-const placement = {
-  getContext: () => context,
-  setContext: () => context,
-  getPlacements: () => placements,
-  getRevision: () => revision,
-  subscribe(listener) {
-    listeners.add(listener);
-    return () => listeners.delete(listener);
-  }
-};
+placement.replacePlacements(placements);
 const errorRuntime = {
   report(event) {
     window.accountFixture.reports.push(event);
@@ -93,8 +105,7 @@ window.accountFixture = {
   profileState,
   placeSection() {
     placements = [...placements, section("extra", "Extra", { render: () => h("p", "Extra section") }, 150)];
-    revision += 1;
-    listeners.forEach((listener) => listener({ revision }));
+    placement.replacePlacements(placements);
   }
 };
 
@@ -126,14 +137,32 @@ const ProfileElementPage = {
 const router = createRouter({
   history: createWebHistory(),
   routes: [
-    { path: "/home", component: { render: () => h("p", { "data-testid": "home" }, "Home") } },
-    { path: "/account", component: AccountPage },
+    { path: "/home", component: { render: () => h("p", { "data-testid": "home" }, "Home") }, meta: { jskit: { surface: "home" } } },
+    {
+      path: "/account",
+      component: RouterView,
+      meta: { jskit: { surface: "account" } },
+      children: [
+        // src/pages/account/index.vue: the section list, an inner page of home.
+        { path: "", component: AccountPage, meta: { jskit: { parent: { surface: "home", path: "/" } } } },
+        // src/pages/account/[section].vue: one section, whose parent is the list.
+        { path: ":section", component: AccountPage, meta: { jskit: { parent: "/" } } }
+      ]
+    },
     { path: "/profile-element", component: ProfileElementPage }
   ]
 });
-const app = createApp({ render: () => h(components.VApp, null, { default: () => h(components.VMain, null, { default: () => h(RouterView) }) }) });
+const navigation = createShellNavigationRuntime({ router });
+navigation.install();
+const app = createApp({
+  render: () => h(components.VApp, null, {
+    default: () => h(ShellLayout, { surfaceLabel: "Fixture" }, { default: () => h(RouterView) })
+  })
+});
 app.provide(SHELL_WEB_PLACEMENT_RUNTIME_KEY, placement);
+app.provide(SHELL_NAVIGATION_RUNTIME_KEY, navigation);
 app.provide(SHELL_WEB_ERROR_RUNTIME_KEY, errorRuntime);
+app.use(createPinia());
 app.use(router);
 app.use(VueQueryPlugin, { queryClient: new QueryClient({ defaultOptions: { queries: { retry: false } } }) });
 app.use(createVuetify({ components, directives, ...createMaterialVuetifyOptions() }));

package/fixtures/translated-app/main.js

@@ -143,6 +143,7 @@ const router = createRouter({
     { path: "/home", component: HomePage },
     { path: "/errors", component: ErrorsPage },
     { path: "/account", component: AccountSettingsClientElement },
+    { path: "/account/:section", component: AccountSettingsClientElement },
     { path: "/auth/login", component: DefaultLoginView },
     { path: "/auth/reset-password", component: DefaultResetPasswordView },
     { path: "/auth/signout", component: DefaultSignOutView }

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@jskit-ai/users-web",
-  "version": "0.2.20",
+  "version": "0.2.22",
   "type": "module",
   "scripts": {
-    "test": "node --test --test-concurrency=1"
+    "test": "jskit test"
   },
   "exports": {
     "./client": "./src/client/index.js",
@@ -13,15 +13,15 @@
     "./locales/en.json": "./locales/en.json"
   },
   "dependencies": {
-    "@jskit-ai/uploads-image-web": "0.2.10",
-    "@jskit-ai/users-core": "0.2.12"
+    "@jskit-ai/uploads-image-web": "0.2.12",
+    "@jskit-ai/users-core": "0.2.14"
   },
   "peerDependencies": {
-    "@jskit-ai/auth-web": "0.2.15",
-    "@jskit-ai/http-runtime": "0.2.10",
-    "@jskit-ai/http-web": "0.2.18",
-    "@jskit-ai/kernel": "0.2.10",
-    "@jskit-ai/shell-web": "0.2.13",
+    "@jskit-ai/auth-web": "0.2.17",
+    "@jskit-ai/http-runtime": "0.2.12",
+    "@jskit-ai/http-web": "0.2.20",
+    "@jskit-ai/kernel": "0.2.12",
+    "@jskit-ai/shell-web": "0.2.15",
     "@tanstack/vue-query": "^5.90.5",
     "vue": "^3.5.13",
     "vue-router": "^5.0.4",
@@ -230,6 +230,6 @@
     }
   },
   "devDependencies": {
-    "@jskit-ai/material-web": "0.1.2"
+    "@jskit-ai/material-web": "0.1.3"
   }
 }

package/patterns/account-settings/PATTERN.md

@@ -38,6 +38,18 @@ app's language; the app does, for example
 `watch(useAccountLocale(), (code) => { if (code) i18n.global.locale.value = code; }, { immediate: true })`.
 Section titles may be plain text, a message key or `{ key, fallback }`.
 
+Sections are pages of the account surface, in Material 3's list-detail layout
+(shell-web's `ShellListDetail`): `/account` is the section list
+(`src/pages/account/index.vue`) and `/account/<section>` one section
+(`src/pages/account/[section].vue`, its `value`, such as
+`/account/preferences`), both rendering `AccountSettingsClientElement`, which
+reads the section from the route's `section` param. The section page's parent
+is the list, the surface's `"/"`. A phone or medium window shows the list or one
+section, and Up returns from the section to the list; an expanded or large
+window shows the list beside the open section, or beside the first section on
+the list's own page. A link to a section is its path, `/account/invites`, with
+`returnTo` in the query for Done.
+
 `runtime.signInMethods.methods` lists the auth provider's OAuth sign-in
 methods as `{ provider, label, linked, canLink, canUnlink }`, read from the
 settings security status. `link(provider)` leaves for the provider through
@@ -59,12 +71,19 @@ provider offers provider linking (`providerLinking` in its capabilities).
 - The route and placement owner agree.
 - The account surface renders in its own layout, `src/pages/account.vue`
   (`ShellLayout` around `<RouterView />`, `meta.jskit.surface: "account"`), so
-  the settings page's title, Up arrow and Done action are in the top app bar.
+  the settings page's title and Up arrow are in the top app bar. Up is the
+  page's only way out; `AccountSettingsClientElement` adds a Done action only
+  where Up can't go back (no parent, a section beside the list on a wide
+  window, or a returnTo on another origin).
   With no navigation items, the surface shows no navigation bar, rail or drawer.
+- Each section has its own address, `/account/<section>`, served by
+  `src/pages/account/[section].vue` with parent `"/"`; nothing selects a
+  section through the query.
 
 ## Example files
 
-`example/` contains the account surface's layout, an account route and four
+`example/` contains the account surface's layout, the section list's route
+(`account/index.vue`), a section's route (`account/[section].vue`) and four
 concrete settings sections.
 Adapt their fields and copy while retaining the shared account runtime.
 
@@ -77,7 +96,9 @@ notification vocabulary while keeping server-owned validation authoritative.
 
 Navigate away and back with warm cache, exercise browser back/forward, save and
 clear fields, verify toast errors, inspect skeleton geometry, and test keyboard
-operation at compact and expanded widths.
+operation at compact and expanded widths. At 390 px check that the list and a
+section show one at a time and Up returns from the section to the list; at
+1280 px that the list shows beside the open section, with no Up.
 
 ## Avoid
 

package/patterns/account-settings/example/src/components/account/settings/AccountSettingsNotificationsSection.vue

@@ -35,11 +35,11 @@ const notifications = props.runtime.notifications;
           color="primary"
           hide-details
           disabled
-          class="mb-4"
         />
         <v-btn
           type="submit"
           color="primary"
+          class="mt-4"
           :loading="notifications.isSaving.value"
           :disabled="notifications.isRefreshing.value"
         >

package/patterns/account-settings/example/src/components/account/settings/AccountSettingsPreferencesSection.vue

@@ -94,7 +94,7 @@ const preferences = props.runtime.preferences;
             />
           </v-col>
 
-          <v-col cols="12" md="3">
+          <v-col cols="12" md="4">
             <v-select
               v-model.number="preferences.form.avatarSize"
               label="Avatar size"
@@ -110,6 +110,7 @@ const preferences = props.runtime.preferences;
         <v-btn
           type="submit"
           color="primary"
+          class="mt-4"
           :loading="preferences.isSaving.value"
           :disabled="preferences.isRefreshing.value"
         >

package/patterns/account-settings/example/src/components/account/settings/AccountSettingsProfileSection.vue

@@ -51,7 +51,7 @@ const profile = props.runtime.profile;
         </v-row>
 
         <v-row>
-          <v-col cols="12" md="6">
+          <v-col cols="12">
             <v-text-field
               v-model="profile.form.displayName"
               label="Display name"
@@ -63,7 +63,7 @@ const profile = props.runtime.profile;
             />
           </v-col>
 
-          <v-col cols="12" md="6">
+          <v-col cols="12">
             <v-text-field
               v-model="profile.form.email"
               label="Email"
@@ -79,6 +79,7 @@ const profile = props.runtime.profile;
         <v-btn
           type="submit"
           color="primary"
+          class="mt-4"
           :loading="profile.isSaving.value"
           :disabled="profile.isDeletingAvatar.value || profile.isRefreshing.value"
         >

package/patterns/account-settings/example/src/pages/account/[section].vue

@@ -0,0 +1,23 @@
+<route lang="json">
+{
+  "meta": {
+    "guard": {
+      "policy": "authenticated"
+    },
+    "jskit": {
+      "title": "Account settings",
+      "parent": "/"
+    }
+  }
+}
+</route>
+
+<template>
+  <AccountSettingsClientElement />
+</template>
+
+<script setup>
+// One section of account settings (/account/preferences). Its parent is the section list, the surface's "/", so on a
+// phone Up returns to the list; a wide window shows the list beside the section.
+import AccountSettingsClientElement from "@jskit-ai/users-web/client/components/AccountSettingsClientElement";
+</script>

package/patterns/account-settings/example/src/pages/account.vue

@@ -9,14 +9,15 @@
 </route>
 
 <script setup>
-// The account surface's layout: the shell's top app bar carries the settings page's title, its Up arrow back to home
-// and its Done action. The surface has no navigation items, so the shell draws no navigation bar, rail or drawer.
+// The account surface's layout: the shell's top app bar carries the settings page's title and its Up arrow back to
+// home, the page's only way out (a Done action shows only where Up can't go back, such as a returnTo on another of
+// the app's origins). The surface has no navigation items, so the shell draws no navigation bar, rail or drawer.
 import ShellLayout from "@/components/ShellLayout.vue";
 import { RouterView } from "vue-router";
 </script>
 
 <template>
-  <ShellLayout title="" subtitle="">
+  <ShellLayout>
     <RouterView />
   </ShellLayout>
 </template>

package/src/client/components/AccountSettingsClientElement.vue

@@ -1,10 +1,13 @@
 <script setup>
 import { computed } from "vue";
-import { useRoute, useRouter } from "vue-router";
-import { normalizeOneOf } from "@jskit-ai/kernel/shared/support/normalize";
+import { useRoute } from "vue-router";
+import ShellListDetail from "@jskit-ai/shell-web/client/components/ShellListDetail";
 import ShellPageAction from "@jskit-ai/shell-web/client/components/ShellPageAction";
 import ShellPageActions from "@jskit-ai/shell-web/client/components/ShellPageActions";
 import { useShellPageTitle } from "@jskit-ai/shell-web/client/composables/useShellPageTitle";
+import { useShellWindowSizeClass } from "@jskit-ai/shell-web/client/composables/useShellWindowSizeClass";
+import { usePaths } from "@jskit-ai/shell-web/client/navigation/usePaths";
+import { useShellNavigation } from "@jskit-ai/shell-web/client/navigation/useShellNavigation";
 import { useAccountSettingsRuntime } from "../composables/useAccountSettingsRuntime.js";
 import { useAccountSettingsSections } from "../account-settings/sections.js";
 import { useJskitText } from "../i18n.js";
@@ -12,12 +15,16 @@ import { useJskitText } from "../i18n.js";
 const { t, text } = useJskitText();
 const runtime = useAccountSettingsRuntime();
 const route = useRoute();
-const router = useRouter();
+const paths = usePaths();
 const sections = useAccountSettingsSections();
-// The app bar carries the page's title and its Done action, which returns to where the person came from (returnTo,
-// which may be another of the app's origins).
+// The app bar carries the page's title. Its Up arrow, on a page that declares a parent, is the way out; a Done action
+// beside it would be a second back control. Done shows only where Up can't take the person back: a page without a
+// parent, an open section beside the list on a wide window (the list is the parent, already in view), or a returnTo
+// on another of the app's origins.
 useShellPageTitle(() => t("jskit.users.accountSettings.title"));
+const { canGoUp } = useShellNavigation();
 const doneTarget = computed(() => runtime.backNavigationTarget.value);
+const showsDone = computed(() => !canGoUp.value || !doneTarget.value.sameOrigin);
 const sectionValues = computed(() => Object.freeze(sections.value.map((section) => section.value)));
 const defaultSection = computed(() => {
   if (sectionValues.value.includes("profile")) {
@@ -27,45 +34,31 @@ const defaultSection = computed(() => {
   return sectionValues.value[0] || "";
 });
 
-function normalizeSection(value) {
-  const source = Array.isArray(value) ? value[0] : value;
-  return normalizeOneOf(source, sectionValues.value, defaultSection.value);
-}
+// Sections are pages: the surface's "/" is the list (/account) and "/<section>" one section (/account/preferences),
+// the app's src/pages/account/[section].vue, whose parent is the list. Compact and medium windows show one pane at a
+// time, so the list leads to a section and Up returns to it; wide windows show the list beside the open section, or
+// beside the first section on the list's own page.
+const openSection = computed(() => {
+  const value = route.params?.section;
+  const section = String(Array.isArray(value) ? value[0] : value || "").trim().toLowerCase();
+  return sectionValues.value.includes(section) ? section : "";
+});
+const { isExpanded, isLarge } = useShellWindowSizeClass();
+const shownSection = computed(() => {
+  const value = openSection.value || (isExpanded.value || isLarge.value ? defaultSection.value : "");
+  return sections.value.find((section) => section.value === value) || null;
+});
 
-function readRouteSection() {
-  return normalizeSection(route?.query?.section);
+// A section's page keeps the address's returnTo, where Done leads.
+function sectionTarget(value) {
+  const returnTo = route.query?.returnTo;
+  return { path: paths.page(`/${value}`), query: returnTo ? { returnTo } : {} };
 }
-
-const activeTab = computed({
-  get() {
-    return readRouteSection();
-  },
-  set(nextValue) {
-    const normalizedSection = normalizeSection(nextValue);
-    const currentSection = readRouteSection();
-    if (!normalizedSection || normalizedSection === currentSection) {
-      return;
-    }
-
-    const nextQuery = {
-      ...route.query
-    };
-    if (normalizedSection === defaultSection.value) {
-      delete nextQuery.section;
-    } else {
-      nextQuery.section = normalizedSection;
-    }
-
-    void router.replace({
-      query: nextQuery
-    });
-  }
-});
 </script>
 
 <template>
   <section class="settings-view py-2 py-md-4">
-    <ShellPageActions>
+    <ShellPageActions v-if="showsDone">
       <ShellPageAction
         :label="t('jskit.users.accountSettings.done')"
         :to="doneTarget.sameOrigin ? doneTarget.href : undefined"
@@ -99,36 +92,28 @@ const activeTab = computed({
         </template>
         <template v-else>
           <v-progress-linear v-if="runtime.refreshingSettings.value" indeterminate class="mb-4" />
-          <v-row class="settings-layout" no-gutters>
-            <v-col cols="12" md="3" lg="2" class="pr-md-4 mb-4 mb-md-0">
+          <ShellListDetail :detail-open="Boolean(openSection)">
+            <template #list>
               <v-list nav class="settings-section-list">
                 <v-list-item
                   v-for="section in sections"
                   :key="section.value"
+                  class="settings-section-list__item"
                   :title="text(section.title)"
-                  :active="activeTab === section.value"
-                  @click="activeTab = section.value"
+                  :to="sectionTarget(section.value)"
+                  :active="shownSection?.value === section.value"
                 />
               </v-list>
-            </v-col>
-
-            <v-col cols="12" md="9" lg="10">
-              <v-window v-model="activeTab" :touch="false" class="settings-sections-window">
-                <v-window-item
-                  v-for="section in sections"
-                  :key="section.value"
-                  :value="section.value"
-                  :transition="false"
-                  :reverse-transition="false"
-                >
-                  <component
-                    :is="section.component"
-                    v-bind="section.usesSharedRuntime ? { runtime } : undefined"
-                  />
-                </v-window-item>
-              </v-window>
-            </v-col>
-          </v-row>
+            </template>
+            <template #detail>
+              <div v-if="shownSection" :key="shownSection.value" class="settings-section-detail">
+                <component
+                  :is="shownSection.component"
+                  v-bind="shownSection.usesSharedRuntime ? { runtime } : undefined"
+                />
+              </div>
+            </template>
+          </ShellListDetail>
         </template>
       </div>
     </div>
@@ -149,6 +134,28 @@ const activeTab = computed({
   padding: 1rem;
 }
 
+/* The selected section is Material 3's pill indicator in secondary-container, as the shell's navigation draws it, and
+   its hover and pressed state layers take the same pill. */
+.settings-section-list__item {
+  --v-activated-opacity: 0;
+  border-radius: 9999px;
+  min-height: 56px;
+  color: rgb(var(--v-theme-on-surface-variant));
+}
+
+.settings-section-list__item.v-list-item--active {
+  background: rgb(var(--v-theme-secondary-container));
+  color: rgb(var(--v-theme-on-secondary-container));
+}
+
+/* Material 3's navigation item label (label-large), not Vuetify's 13px nav list title. */
+.settings-section-list__item :deep(.v-list-item-title) {
+  font-size: 0.875rem;
+  font-weight: 500;
+  letter-spacing: 0.00625rem;
+  line-height: 1.25rem;
+}
+
 .settings-panel__state {
   margin-inline: auto;
   max-width: 30rem;

package/src/client/components/ProfileClientElement.vue

@@ -50,7 +50,7 @@
           </v-row>
 
           <v-row>
-            <v-col cols="12" md="6">
+            <v-col cols="12">
               <v-text-field
                 v-model="state.profileForm.displayName"
                 :label="copyText.displayName"
@@ -60,7 +60,7 @@
                 :error-messages="state.profileFieldErrors.displayName"
               />
             </v-col>
-            <v-col cols="12" md="6">
+            <v-col cols="12">
               <v-text-field
                 v-model="state.profileForm.email"
                 :label="copyText.email"
@@ -72,7 +72,13 @@
               />
             </v-col>
           </v-row>
-          <v-btn type="submit" color="primary" :loading="state.profileMutation.isPending.value" :data-testid="uiTestIds.submitButton">
+          <v-btn
+            type="submit"
+            color="primary"
+            class="mt-4"
+            :loading="state.profileMutation.isPending.value"
+            :data-testid="uiTestIds.submitButton"
+          >
             {{ copyText.saveProfile }}
           </v-btn>
 

package/test/accountSettings.browser.test.js

@@ -55,8 +55,8 @@ function document(attributes, type = "user-settings") {
 }
 
 /** One page with the settings API behind it; `routes` answers "METHOD /path", anything else is a test failure. */
-async function openApp({ routes = {} } = {}) {
-  const page = await browser.newPage({ baseURL: runtime.baseURL, viewport: { width: 1280, height: 900 } });
+async function openApp({ routes = {}, viewport = { width: 1280, height: 900 } } = {}) {
+  const page = await browser.newPage({ baseURL: runtime.baseURL, viewport, reducedMotion: "reduce" });
   page.setDefaultTimeout(15_000);
   page.setDefaultNavigationTimeout(60_000);
   const api = { requests: [], unexpected: [], errors: [], page };
@@ -123,13 +123,15 @@ test("the profile section loads, saves, shows a refused field and removes the av
     }
   });
   const { page } = api;
-  await page.goto("/account?returnTo=/home");
+  // A section open beside the list: the list, its parent, is in view, so there is no Up, and Done returns to returnTo.
+  await page.goto("/account/profile?returnTo=/home");
   const name = page.getByLabel("Display name");
   await expect(name).toHaveValue("Ada");
   await expect(page.getByLabel("Email", { exact: true })).toHaveValue("ada@example.com");
-  // The page's Done action (in the shell's app bar, or in place without one) returns to returnTo; there is no in-page h1.
   await expect(page.getByRole("link", { name: "Done" })).toHaveAttribute("href", "/home");
-  await expect(page.getByRole("heading", { level: 1 })).toHaveCount(0);
+  await expect(page.getByTestId("jskit-shell-back")).toHaveCount(0);
+  // The app bar's title is the page's one h1.
+  await expect(page.getByRole("heading", { level: 1 })).toHaveText("Account settings");
 
   await name.fill("  Ada Lovelace ");
   await page.getByRole("button", { name: "Save profile" }).click();
@@ -151,7 +153,58 @@ test("the profile section loads, saves, shows a refused field and removes the av
 
   await page.getByRole("link", { name: "Done" }).click();
   await expect(page.getByTestId("home")).toBeVisible();
+
+  // The list's own page is an inner page of home: Up is its only way out, with no Done beside it.
+  await page.goto("/account?returnTo=/home");
+  await expect(page.getByLabel("Display name")).toHaveValue("Ada");
+  await expect(page.getByTestId("jskit-shell-back")).toBeVisible();
+  await expect(page.getByRole("link", { name: "Done" })).toHaveCount(0);
+  await finish(api);
+});
+
+// Material 3's list-detail layout: a phone shows the section list or one section, and Up returns from the section to
+// the list and from the list to home; a wide window shows the list beside the open section, with no Up to the list.
+test("a phone shows the section list and one section at a time, and Up returns to the list", options, async () => {
+  const api = await openApp({ viewport: { width: 390, height: 844 } });
+  const { page } = api;
+  const up = page.getByTestId("jskit-shell-back");
+  const sectionLinks = page.getByRole("link", { name: /^(Profile|Preferences|Notifications|Sign-in methods)$/u });
+  await page.goto("/account");
+  await expect(sectionLinks).toHaveCount(4);
+  await expect(page.getByLabel("Display name")).toHaveCount(0);
+  await expect(page.locator(".settings-section-list__item.v-list-item--active")).toHaveCount(0);
+
+  await page.getByRole("link", { name: "Preferences" }).click();
+  await page.waitForURL("**/account/preferences");
+  await expect(page.getByRole("button", { name: /Save preferences/u })).toBeVisible();
+  await expect(sectionLinks.first()).toBeHidden();
+  await expect(page.getByRole("link", { name: "Done" })).toHaveCount(0);
+
+  await up.click();
+  await page.waitForURL((url) => url.pathname === "/account");
+  await expect(sectionLinks.first()).toBeVisible();
+  await expect(page.getByRole("button", { name: /Save preferences/u })).toHaveCount(0);
+
+  // A section opened from a pasted link has the list as its parent too.
+  await page.goto("/account/notifications");
+  await expect(page.getByRole("button", { name: /Save notification settings/u })).toBeVisible();
+  await up.click();
+  await page.waitForURL((url) => url.pathname === "/account");
+  await up.click();
+  await expect(page.getByTestId("home")).toBeVisible();
   await finish(api);
+
+  const wide = await openApp();
+  await wide.page.goto("/account");
+  await expect(wide.page.getByRole("link", { name: "Preferences" })).toBeVisible();
+  await expect(wide.page.getByLabel("Display name")).toBeVisible();
+  await expect(wide.page.locator(".settings-section-list__item.v-list-item--active")).toHaveText("Profile");
+  await wide.page.getByRole("link", { name: "Preferences" }).click();
+  await wide.page.waitForURL("**/account/preferences");
+  await expect(wide.page.getByRole("link", { name: "Profile" })).toBeVisible();
+  await expect(wide.page.getByRole("button", { name: /Save preferences/u })).toBeVisible();
+  await expect(wide.page.getByTestId("jskit-shell-back")).toHaveCount(0);
+  await finish(wide);
 });
 
 test("saved preferences follow into the theme, the stored preference and the account locale", options, async () => {
@@ -168,8 +221,8 @@ test("saved preferences follow into the theme, the stored preference and the acc
   await expect(page.getByTestId("account-locale")).toHaveText("it-IT");
   assert.equal(await page.evaluate(() => localStorage.getItem("jskit.themePreference")), "dark");
 
-  await page.getByRole("listitem").filter({ hasText: "Preferences" }).click();
-  await page.waitForURL("**/account?section=preferences");
+  await page.getByRole("link", { name: "Preferences" }).click();
+  await page.waitForURL("**/account/preferences");
   await page.getByRole("button", { name: /Save preferences/u }).click();
   await expect.poll(() => lastReport(page)).toBe("Preferences updated.");
   const saved = api.requests.find((request) => request.key === "PATCH /api/settings/preferences");
@@ -191,7 +244,7 @@ test("a refused preference shows its message", options, async () => {
     }
   });
   const { page } = api;
-  await page.goto("/account?section=preferences");
+  await page.goto("/account/preferences");
   await page.getByRole("button", { name: /Save preferences/u }).click();
   await expect(page.getByText("Theme is not allowed.")).toBeVisible();
   // The old error array looped here for seconds before Vue gave up, so the page must also stay idle.
@@ -211,19 +264,61 @@ test("notifications save, and sign-in methods link through the provider and unli
     }
   });
   const { page } = api;
-  await page.goto("/account?section=notifications");
+  await page.goto("/account/notifications");
   await page.getByRole("button", { name: /Save notification settings/u }).click();
   await expect.poll(() => lastReport(page)).toBe("Notification settings updated.");
   const saved = api.requests.find((request) => request.key === "PATCH /api/settings/notifications");
   assert.deepEqual(saved.body.data.attributes, { productUpdates: true, accountActivity: false, securityAlerts: true });
 
-  await page.getByRole("listitem").filter({ hasText: "Sign-in methods" }).click();
+  await page.getByRole("link", { name: "Sign-in methods" }).click();
   await page.getByRole("button", { name: "Unlink" }).click();
   await expect.poll(() => lastReport(page)).toBe("Sign-in method removed.");
   await expect(page.getByRole("button", { name: "Unlink" })).toHaveCount(0);
   await page.getByRole("button", { name: "Link" }).click();
   await page.getByText("Provider").waitFor();
-  assert.equal(api.requests.at(-1).search, "?returnTo=%2Faccount%3Fsection%3Dsign-in-methods");
+  assert.equal(api.requests.at(-1).search, "?returnTo=%2Faccount%2Fsign-in-methods");
+  await finish(api);
+});
+
+// Material 3 type and layout: the section list's labels and the buttons are label-large (14px/500), a switch sits
+// after its label at the row's end, and each field has the form's full width, so a long email shows whole.
+test("account settings use Material 3 label type, trailing switches and full-width fields", options, async () => {
+  const email = "ada.lovelace.analytical.engine@difference-engine.example.com";
+  const api = await openApp({
+    routes: { "GET /api/settings": document(settings({ profile: { ...settings().profile, email } })) }
+  });
+  const { page } = api;
+  await page.goto("/account");
+  await expect(page.getByLabel("Email", { exact: true })).toHaveValue(email);
+  const type = (locator) => locator.evaluate((element) => {
+    const style = window.getComputedStyle(element);
+    return [style.fontSize, style.fontWeight];
+  });
+  assert.deepEqual(await type(page.locator(".settings-section-list__item .v-list-item-title").first()), ["14px", "500"]);
+  assert.deepEqual(await type(page.getByRole("button", { name: "Save profile" })), ["14px", "500"]);
+  const fields = await page.evaluate(() => {
+    const form = document.querySelector(".settings-section-detail form");
+    const width = (element) => Math.round(element.getBoundingClientRect().width);
+    return [...form.querySelectorAll(".v-text-field")].map((field) => {
+      const input = field.querySelector("input");
+      return { width: width(field), form: width(form), whole: input.scrollWidth <= input.clientWidth };
+    });
+  });
+  assert.ok(fields.length >= 2, "the profile form has its fields");
+  for (const field of fields) {
+    assert.ok(field.width >= field.form - 48, `a field has the form's width: ${JSON.stringify(field)}`);
+    assert.equal(field.whole, true, `a field shows its value whole: ${JSON.stringify(field)}`);
+  }
+
+  await page.goto("/account/notifications");
+  const switches = await page.locator(".v-switch").evaluateAll((elements) => elements.map((element) => {
+    const label = element.querySelector(".v-label").getBoundingClientRect();
+    const control = element.querySelector(".v-selection-control__wrapper").getBoundingClientRect();
+    const row = element.getBoundingClientRect();
+    return { after: control.left >= label.right, atEnd: Math.abs(row.right - control.right) <= 1, labelAtStart: Math.abs(label.left - row.left) <= 1 };
+  }));
+  assert.ok(switches.length >= 3, "the notification switches render");
+  for (const position of switches) assert.deepEqual(position, { after: true, atEnd: true, labelAtStart: true });
   await finish(api);
 });
 
@@ -265,7 +360,7 @@ test("each section stays busy until its save or removal answers", options, async
   await expect(removeAvatar).not.toHaveClass(loading);
   await expect(saveProfile).toBeEnabled();
 
-  await page.getByRole("listitem").filter({ hasText: "Preferences" }).click();
+  await page.getByRole("link", { name: "Preferences" }).click();
   const savePreferences = page.getByRole("button", { name: /Save preferences/u });
   const disabledFields = page.locator(".v-input--disabled");
   await savePreferences.click();
@@ -275,7 +370,7 @@ test("each section stays busy until its save or removal answers", options, async
   await expect(savePreferences).not.toHaveClass(loading);
   await expect(disabledFields).toHaveCount(0);
 
-  await page.getByRole("listitem").filter({ hasText: "Notifications" }).click();
+  await page.getByRole("link", { name: "Notifications" }).click();
   const saveNotifications = page.getByRole("button", { name: /Save notification settings/u });
   const productUpdates = page.getByLabel("Product updates");
   await saveNotifications.click();
@@ -290,16 +385,17 @@ test("each section stays busy until its save or removal answers", options, async
 test("the section list follows the address and the placements, and says when there is nothing to show", options, async () => {
   const api = await openApp();
   const { page } = api;
-  await page.goto("/account?section=unknown");
+  // A section no placement names opens none: the list, with the first section beside it on a wide window.
+  await page.goto("/account/unknown");
   await expect(page.getByLabel("Display name")).toBeVisible();
 
   await page.evaluate(() => window.accountFixture.placeSection());
-  await page.getByRole("listitem").filter({ hasText: "Extra" }).click();
+  await page.getByRole("link", { name: "Extra" }).click();
   await page.getByText("Extra section").waitFor();
-  await page.waitForURL("**/account?section=extra");
-  await page.getByRole("listitem").filter({ hasText: "Profile" }).click();
+  await page.waitForURL("**/account/extra");
+  await page.getByRole("link", { name: "Profile" }).click();
   await expect(page.getByLabel("Display name")).toBeVisible();
-  await page.waitForURL((url) => url.search === "");
+  await page.waitForURL("**/account/profile");
   await finish(api);
 
   const empty = await openApp();

package/test/accountSettingsPattern.test.js

@@ -0,0 +1,24 @@
+import assert from "node:assert/strict";
+import { readFile } from "node:fs/promises";
+import test from "node:test";
+
+// The users/account-settings pattern lays its sections out as pages: the section list at the account surface's "/",
+// an inner page of home, and one section at "/<section>", whose parent is the list, both rendering the element.
+const PAGES = new URL("../patterns/account-settings/example/src/pages/", import.meta.url);
+
+async function routeMeta(file) {
+  const source = await readFile(new URL(file, PAGES), "utf8");
+  const block = /<route lang="json">([\s\S]*?)<\/route>/u.exec(source);
+  assert.ok(block, `${file} declares its route meta`);
+  assert.match(source, /<AccountSettingsClientElement \/>/u, `${file} renders AccountSettingsClientElement`);
+  return JSON.parse(block[1]).meta;
+}
+
+test("the account-settings pattern's list and section pages declare their parents", async () => {
+  const list = await routeMeta("account/index.vue");
+  assert.deepEqual(list.jskit.parent, { surface: "home", path: "/" });
+  const section = await routeMeta("account/[section].vue");
+  assert.equal(section.jskit.parent, "/");
+  assert.deepEqual(section.guard, list.guard);
+  assert.equal(section.jskit.title, list.jskit.title);
+});

package/test/settingsPlacementContract.test.js

@@ -90,7 +90,9 @@ test("package-owned account settings host is placement-backed rather than scaffo
   );
 
   assert.match(source, /useAccountSettingsSections/);
-  // The app bar carries the title and the Done action; the page keeps only its intro.
+  // The app bar carries the title, and Done only where Up can't go back; the page keeps only its intro.
+  assert.match(source, /<ShellPageActions v-if="showsDone">/u);
+  assert.match(source, /const showsDone = computed\(\(\) => !canGoUp\.value \|\| !doneTarget\.value\.sameOrigin\);/u);
   assert.match(source, /settings-panel__intro/);
   assert.match(source, /useShellPageTitle/);
   assert.doesNotMatch(source, /<h1/u);

package/test/translatedApp.browser.test.js

@@ -295,6 +295,15 @@ test("the profile menu and a refused, then retried, sign-out show only the pseud
   });
   const { page } = api;
   await api.open("/home");
+  // On a phone, where the name is hidden, the activator is a round icon button around the avatar.
+  await page.setViewportSize({ width: 390, height: 844 });
+  const activator = await page.locator(".auth-profile-widget__activator").evaluate((element) => {
+    const box = element.getBoundingClientRect();
+    return { width: box.width, height: box.height, radius: Number.parseFloat(window.getComputedStyle(element).borderTopLeftRadius) };
+  });
+  assert.equal(Math.round(activator.width), Math.round(activator.height), "The phone activator is as wide as it is tall.");
+  assert.ok(activator.radius >= activator.height / 2, `The phone activator's corner radius was ${activator.radius}px.`);
+  await page.setViewportSize({ width: 1280, height: 900 });
   await page.locator(".auth-profile-widget__activator").click();
   const signOut = page.getByRole("link", { name: shown("app.menu.signOut") });
   await expect(signOut).toBeVisible();
@@ -371,9 +380,28 @@ test("account settings, their feedback and a refused field show only the pseudo-
   await api.open("/account?returnTo=/home");
   await expect(page.getByText(shown("jskit.users.accountSettings.profile.save"))).toBeVisible();
   await assertTranslated(page, "account settings");
+  // The selected section carries Material 3's pill indicator in secondary-container, not a grey rectangle.
+  const selected = await page.locator(".settings-section-list .v-list-item--active").evaluate((element) => {
+    const probe = document.createElement("div");
+    probe.style.background = "rgb(var(--v-theme-secondary-container))";
+    document.body.append(probe);
+    const indicator = window.getComputedStyle(probe).backgroundColor;
+    probe.remove();
+    const style = window.getComputedStyle(element);
+    return { background: style.backgroundColor, indicator, radius: Number.parseFloat(style.borderTopLeftRadius), height: element.getBoundingClientRect().height };
+  });
+  assert.equal(selected.background, selected.indicator);
+  assert.ok(selected.radius >= selected.height / 2, `The selected section's corner radius was ${selected.radius}px.`);
+  // Save keeps 16dp from the last field above it.
+  const saveGap = await page.getByTestId("profile-submit-button").evaluate((button) => {
+    const row = button.previousElementSibling;
+    const fields = [...row.querySelectorAll(".v-input")].map((field) => field.getBoundingClientRect().bottom);
+    return button.getBoundingClientRect().top - Math.max(...fields);
+  });
+  assert.ok(saveGap >= 15.5, `Save sat ${saveGap}px below the last field.`);
 
-  await page.getByRole("listitem").filter({ hasText: shown("app.settings.preferences") }).click();
-  await page.waitForURL("**section=preferences**");
+  await page.getByRole("link", { name: shown("app.settings.preferences") }).click();
+  await page.waitForURL((url) => url.pathname === "/account/preferences");
   await page.getByTestId("theme-select").click();
   await expect(page.getByRole("option", { name: shown("jskit.users.accountSettings.preferences.theme.light") })).toBeVisible();
   await assertTranslated(page, "the theme choices");