@nexdom/uimed-vue 2.5.0 → 2.6.0

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/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.0",
   "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`.