@nexdom/uimed-vue 2.5.0 → 2.6.1

package/dist/components/main/back-to-top.js

@@ -0,0 +1,5 @@
+import back_to_top_vue_vue_type_script_setup_true_lang_default from "./back-to-top.vue_vue_type_script_setup_true_lang.js";
+//#region src/components/main/back-to-top.vue
+var back_to_top_default = back_to_top_vue_vue_type_script_setup_true_lang_default;
+//#endregion
+export { back_to_top_default as default };

package/dist/components/main/back-to-top.vue_vue_type_script_setup_true_lang.js

@@ -0,0 +1,35 @@
+import { icons } from "../../consts/icons.js";
+import { createBlock, createCommentVNode, createElementVNode, createVNode, defineComponent, openBlock, unref, withCtx } from "vue";
+import { VFab, VIcon } from "vuetify/components";
+var back_to_top_vue_vue_type_script_setup_true_lang_default = /*@__PURE__*/ defineComponent({
+	inheritAttrs: false,
+	__name: "back-to-top",
+	props: { active: {
+		type: Boolean,
+		required: true
+	} },
+	emits: ["click"],
+	setup(__props, { emit: __emit }) {
+		const props = __props;
+		const emit = __emit;
+		return (_ctx, _cache) => {
+			return openBlock(), createBlock(unref(VFab), {
+				active: props.active,
+				icon: unref(icons).backToTop,
+				color: "tertiary",
+				location: "bottom end",
+				app: "",
+				onClick: _cache[0] || (_cache[0] = ($event) => emit("click"))
+			}, {
+				default: withCtx(() => [
+					createVNode(unref(VIcon), { icon: unref(icons).backToTop }, null, 8, ["icon"]),
+					createCommentVNode(" The FAB gives its attributes to its wrapper instead of its button, so the button can't take\n    an aria-label: its name is a text that only screen readers read, which no prop provides "),
+					_cache[1] || (_cache[1] = createElementVNode("span", { class: "d-sr-only" }, "Retornar ao topo", -1))
+				]),
+				_: 1
+			}, 8, ["active", "icon"]);
+		};
+	}
+});
+//#endregion
+export { back_to_top_vue_vue_type_script_setup_true_lang_default as default };

package/dist/components/main/main.vue_vue_type_script_setup_true_lang.js

@@ -2,12 +2,15 @@ import app_bar_default from "../app-bar/app-bar.js";
 import { useMobileNavigation } from "../../composables/navigation/use-navigation-rail.js";
 import navigation_menu_default from "../navigation-menu/navigation-menu.js";
 import footer_default from "../footer/footer.js";
+import back_to_top_default from "./back-to-top.js";
 import container_default from "../grid/container/container.js";
 import toast_default from "../dialogs/toast.js";
 import dialog_host_default from "../dialogs/dialog-host.js";
 import useVuetifyBackgroundColor from "../../composables/colors/use-vuetify-background-color.js";
-import { computed, createBlock, createCommentVNode, createSlots, createVNode, defineComponent, mergeModels, mergeProps, normalizeClass, normalizeProps, openBlock, ref, renderSlot, unref, useModel, useSlots, withCtx } from "vue";
+import useBackToTop from "../../composables/navigation/use-back-to-top.js";
+import { computed, createBlock, createCommentVNode, createSlots, createVNode, defineComponent, mergeModels, mergeProps, normalizeClass, normalizeProps, openBlock, ref, renderSlot, unref, useModel, useSlots, useTemplateRef, withCtx, withDirectives } from "vue";
 import { VApp, VMain } from "vuetify/components";
+import { Scroll } from "vuetify/directives";
 var main_vue_vue_type_script_setup_true_lang_default = /*@__PURE__*/ defineComponent({
 	inheritAttrs: false,
 	__name: "main",
@@ -61,6 +64,7 @@ var main_vue_vue_type_script_setup_true_lang_default = /*@__PURE__*/ defineCompo
 		const backgroundClass = useVuetifyBackgroundColor(() => props.background);
 		const notificationsOpen = useModel(__props, "notificationsOpen");
 		const navigationMenuOpen = ref(false);
+		const { visible, onScroll, backToTop } = useBackToTop(useTemplateRef("main"));
 		return (_ctx, _cache) => {
 			return openBlock(), createBlock(unref(VApp), {
 				class: normalizeClass(unref(backgroundClass)),
@@ -82,7 +86,11 @@ var main_vue_vue_type_script_setup_true_lang_default = /*@__PURE__*/ defineCompo
 						"onUpdate:modelValue": _cache[2] || (_cache[2] = ($event) => navigationMenuOpen.value = $event),
 						loading: props.loading
 					}), null, 16, ["modelValue", "loading"])) : createCommentVNode("v-if", true),
-					createVNode(unref(VMain), null, {
+					createCommentVNode(" Focusable, so the back-to-top button can move the focus to the start of the content "),
+					createVNode(unref(VMain), {
+						ref: "main",
+						tabindex: "-1"
+					}, {
 						default: withCtx(() => [createCommentVNode(" Full height, so the page's rows and containers with `fullHeight` have a height to fill "), createVNode(container_default, { "full-height": "" }, {
 							default: withCtx(() => [
 								renderSlot(_ctx.$slots, "default"),
@@ -92,8 +100,13 @@ var main_vue_vue_type_script_setup_true_lang_default = /*@__PURE__*/ defineCompo
 							_: 3
 						})]),
 						_: 3
-					}),
-					props.footer?.description ? (openBlock(), createBlock(footer_default, normalizeProps(mergeProps({ key: 2 }, props.footer)), null, 16)) : createCommentVNode("v-if", true)
+					}, 512),
+					props.footer?.description ? (openBlock(), createBlock(footer_default, normalizeProps(mergeProps({ key: 2 }, props.footer)), null, 16)) : createCommentVNode("v-if", true),
+					createCommentVNode(" After the footer, so the layout places it above the footer "),
+					withDirectives(createVNode(back_to_top_default, {
+						active: unref(visible),
+						onClick: unref(backToTop)
+					}, null, 8, ["active", "onClick"]), [[unref(Scroll), unref(onScroll)]])
 				]),
 				_: 3
 			}, 8, ["class", "data-testid"]);

package/dist/components/navigation-menu/navigation-menu.vue_vue_type_script_setup_true_lang.js

@@ -149,11 +149,12 @@ var navigation_menu_vue_vue_type_script_setup_true_lang_default = /*@__PURE__*/
 					type: "list-item@6",
 					color: "tertiary"
 				}, {
-					default: withCtx(() => [createCommentVNode(" Vuetify's `list` role only allows list items, but the items are links.\n      `indent` aligns the items of a group with its title, which the 24px between the icons and\n      the titles (`settings.scss`) move 8px to the left of Vuetify's default indentation. It\n      replaces the group's prepend width too, so it's the icon (24px) plus that gap (24px) "), createVNode(unref(VList), {
+					default: withCtx(() => [createCommentVNode(" Vuetify's `list` role only allows list items, but the items are links.\n      Vuetify makes the list the only tab stop and takes its items out of the tab order, for the arrow\n      keys: the items are links and buttons, so each one is a tab stop instead (the arrow keys still\n      move between them), and the list stays out of the tab order.\n      `indent` aligns the items of a group with its title, which the 24px between the icons and\n      the titles (`settings.scss`) move 8px to the left of Vuetify's default indentation. It\n      replaces the group's prepend width too, so it's the icon (24px) plus that gap (24px) "), createVNode(unref(VList), {
 						opened: unref(opened),
 						"onUpdate:opened": _cache[1] || (_cache[1] = ($event) => isRef(opened) ? opened.value = $event : null),
 						nav: "",
 						role: "group",
+						tabindex: "-1",
 						indent: 48
 					}, {
 						default: withCtx(() => [(openBlock(true), createElementBlock(Fragment, null, renderList(filteredItems.value, (item, index) => {
@@ -168,6 +169,7 @@ var navigation_menu_vue_vue_type_script_setup_true_lang_default = /*@__PURE__*/
 									"aria-expanded": isOpen,
 									"aria-selected": void 0,
 									role: void 0,
+									tabindex: "0",
 									tag: "button",
 									type: "button",
 									class: "w-100 text-start v-treeview-item--activatable-group-activator"
@@ -180,6 +182,7 @@ var navigation_menu_vue_vue_type_script_setup_true_lang_default = /*@__PURE__*/
 								default: withCtx(() => [(openBlock(true), createElementBlock(Fragment, null, renderList(item.items, (childItem, childIndex) => {
 									return openBlock(), createBlock(unref(VListItem), mergeProps({ key: childIndex }, { ref_for: true }, unref(routeToListItemProps)(childItem.route), {
 										title: childItem.description,
+										tabindex: "0",
 										onClick: childItem.action
 									}), null, 16, ["title", "onClick"]);
 								}), 128))]),
@@ -188,7 +191,10 @@ var navigation_menu_vue_vue_type_script_setup_true_lang_default = /*@__PURE__*/
 								key: 1,
 								title: item.description,
 								"prepend-icon": unref(icons)[item.icon]
-							}, { ref_for: true }, unref(routeToListItemProps)(item.route), { onClick: item.action }), null, 16, [
+							}, { ref_for: true }, unref(routeToListItemProps)(item.route), {
+								tabindex: "0",
+								onClick: item.action
+							}), null, 16, [
 								"title",
 								"prepend-icon",
 								"onClick"

package/dist/composables/navigation/use-back-to-top.js

@@ -0,0 +1,36 @@
+import { onMounted, ref, toValue } from "vue";
+//#region src/composables/navigation/use-back-to-top.ts
+/**
+* Back-to-top button's state for `content`, the template ref of the component whose element the
+* button brings into view and focuses (which must be focusable, e.g. with `tabindex="-1"`). The
+* button shows once the top of the content is a screen above the viewport, instead of after the page
+* scrolls a screen: in apps both are the same, but on pages with more than one `UMain` (like the
+* docs) only the one scrolled past shows it.
+*/
+function useBackToTop(content) {
+	const visible = ref(false);
+	function onScroll() {
+		const element = toValue(content)?.$el;
+		visible.value = element ? -element.getBoundingClientRect().top > globalThis.innerHeight : false;
+	}
+	function backToTop() {
+		const element = toValue(content)?.$el;
+		if (!element) return;
+		globalThis.scrollTo({
+			top: globalThis.scrollY + element.getBoundingClientRect().top,
+			behavior: prefersReducedMotion() ? "instant" : "smooth"
+		});
+		element.focus({ preventScroll: true });
+	}
+	onMounted(onScroll);
+	return {
+		visible,
+		onScroll,
+		backToTop
+	};
+}
+function prefersReducedMotion() {
+	return globalThis.matchMedia("(prefers-reduced-motion: reduce)").matches;
+}
+//#endregion
+export { useBackToTop as default };

package/dist/consts/icons.d.ts

@@ -50,6 +50,7 @@ export declare const icons: {
   showPassword: string;
   hidePassword: string;
   close: string;
+  backToTop: string;
   clear: string;
   dropdown: string;
   subgroup: string;

package/dist/consts/icons.js

@@ -1,4 +1,4 @@
-import { mdiAccount, mdiAccountGroup, mdiAccountGroupOutline, mdiAccountOutline, mdiAlertCircle, mdiBellOutline, mdiCalendar, mdiCalendarOutline, mdiChartBox, mdiChartBoxOutline, mdiCheckCircle, mdiCheckboxBlankOutline, mdiCheckboxMarked, mdiChevronDown, mdiChevronLeft, mdiChevronRight, mdiChevronUp, mdiClipboardText, mdiClipboardTextOutline, mdiClose, mdiCloseCircle, mdiCog, mdiCogOutline, mdiEye, mdiEyeOff, mdiFileDocument, mdiFileDocumentOutline, mdiFlask, mdiFlaskOutline, mdiFolder, mdiFolderOutline, mdiHelpCircleOutline, mdiHome, mdiHomeOutline, mdiHospitalBuilding, mdiInformation, mdiMagnify, mdiMenu, mdiMenuDown, mdiPill, mdiStethoscope, mdiWallet, mdiWalletOutline } from "@mdi/js";
+import { mdiAccount, mdiAccountGroup, mdiAccountGroupOutline, mdiAccountOutline, mdiAlertCircle, mdiArrowUp, mdiBellOutline, mdiCalendar, mdiCalendarOutline, mdiChartBox, mdiChartBoxOutline, mdiCheckCircle, mdiCheckboxBlankOutline, mdiCheckboxMarked, mdiChevronDown, mdiChevronLeft, mdiChevronRight, mdiChevronUp, mdiClipboardText, mdiClipboardTextOutline, mdiClose, mdiCloseCircle, mdiCog, mdiCogOutline, mdiEye, mdiEyeOff, mdiFileDocument, mdiFileDocumentOutline, mdiFlask, mdiFlaskOutline, mdiFolder, mdiFolderOutline, mdiHelpCircleOutline, mdiHome, mdiHomeOutline, mdiHospitalBuilding, mdiInformation, mdiMagnify, mdiMenu, mdiMenuDown, mdiPill, mdiStethoscope, mdiWallet, mdiWalletOutline } from "@mdi/js";
 //#region src/consts/icons.ts
 /**
 * SVG path of each icon, by its name, in the order the "Ícones" guide page lists them. The paths
@@ -51,6 +51,7 @@ const icons = {
 	showPassword: mdiEye,
 	hidePassword: mdiEyeOff,
 	close: mdiClose,
+	backToTop: mdiArrowUp,
 	clear: mdiCloseCircle,
 	dropdown: mdiMenuDown,
 	subgroup: mdiMenuDown,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nexdom/uimed-vue",
-  "version": "2.5.0",
+  "version": "2.6.1",
   "description": "A ui framework for NEXDOM applications.",
   "keywords": [
     "lib",

package/skills/uimed-vue/SKILL.md

@@ -83,6 +83,7 @@ createApp(App).use(createUimed()).mount("#app");
   type SectionAction = NonNullable<ComponentProps<typeof USection>["actions"]>[number];
   ```
 
+- `UMain` shows a "back to top" floating button on its own once the page scrolls past a screen, so don't add one to the screens.
 - Icons are passed by name (e.g. `icon="cog"`), from the list in [`references/guide/icons.md`](references/guide/icons.md).
 - The components' internal texts, such as their messages and the names read by screen readers, are in Portuguese (pt-BR).
 

package/skills/uimed-vue/references/api/components/main.md

@@ -105,6 +105,10 @@ Item dentro de um [grupo](#navigationmenuparent). Tem as mesmas propriedades do
 | `dataTestid`  | `string` |        | Aplica atributo `data-testid` para testes sobre o rodapé.                                                                          |
 | `description` | `string` |        | Texto exibido no rodapé, por exemplo a versão da aplicação (`"Versão 1.4.2"`). **O rodapé será ocultado quando omitido ou vazio.** |
 
+## Retornar ao topo
+
+O componente exibe um botão flutuante "Retornar ao topo" no canto inferior direito quando o usuário rola a página por mais de uma tela, sem props para configurá-lo. Veja [Retornar ao topo](../../guide/components/main.md#retornar-ao-topo) no guia.
+
 ## Eventos
 
 | Event                      | Retorno   | Descrição                                                      |

package/skills/uimed-vue/references/guide/components/main.md

@@ -391,6 +391,41 @@ const appBar: NonNullable<MainProps["appBar"]> = {
 </script>
 ```
 
+## Retornar ao topo
+
+Em páginas longas, como listagens e formulários extensos, o `UMain` exibe um botão flutuante no canto inferior direito para voltar ao início do conteúdo. Ele aparece quando o usuário rola a página por mais de uma tela e some ao voltar ao topo, sem nenhuma prop: páginas curtas nunca o exibem.
+
+O botão fica acima do rodapé, quando exibido, e abaixo dos diálogos e dos toasts. Ao ser acionado, ele rola a página até o início do conteúdo de forma suave, ou imediata quando o usuário prefere reduzir os movimentos nas configurações do sistema, e move o foco para o início do conteúdo, para que quem navega pelo teclado continue a partir dali. Os leitores de tela o anunciam como "Retornar ao topo".
+
+Role a demonstração abaixo para ver o botão:
+
+```vue
+<template>
+  <u-main :appBar :footer>
+    <h2>Manual do usuário</h2>
+    <p v-for="step in 12" :key="step">{{ step }}. {{ manualText }}</p>
+  </u-main>
+</template>
+
+<script lang="ts" setup>
+import type { ComponentProps } from "vue-component-type-helpers";
+import { UMain } from "@nexdom/uimed-vue/components";
+
+type MainProps = ComponentProps<typeof UMain>;
+
+const manualText =
+  "Este manual descreve cada etapa do atendimento, do agendamento da consulta à emissão do relatório final, com as orientações para preencher os formulários, conferir os dados do paciente antes de salvar e resolver as pendências mais comuns. Siga as etapas na ordem em que aparecem e, em caso de dúvida, procure a equipe de suporte da sua unidade.";
+
+const appBar: NonNullable<MainProps["appBar"]> = {
+  title: "Menu superior",
+};
+
+const footer: NonNullable<MainProps["footer"]> = {
+  description: "Versão 1.4.2",
+};
+</script>
+```
+
 ## Eventos
 
 ### Notificações

package/skills/uimed-vue/references/guide/icons.md

@@ -57,7 +57,7 @@ A lista começa pelos ícones de conteúdo, como `home` e `calendar`, cujos nome
 
 Em seguida vêm os ícones que os próprios componentes exibem, cujos nomes descrevem a função com que os componentes os usam:
 
-- Ações, como `help`, `search`, `showPassword` e `close`.
+- Ações, como `help`, `search`, `showPassword`, `close` e `backToTop`.
 - Expansão de menus e grupos, como `dropdown`, `expand` e `collapse`, e navegação entre páginas, com `prev` e `next`.
 - Marcações da caixa de seleção: `checkboxOn` e `checkboxOff`.
 - Retorno ao usuário, nas cores das mensagens: `success`, `info`, `warning` e `error`.