@nexdom/uimed-vue 2.0.0-beta.61 → 2.0.0-beta.62

package/AGENTS.md

@@ -216,7 +216,7 @@ Use an existing composable (e.g. `use-toast`) as the reference, and deliver in t
 - Public components/composables are re-exported from `src/components/index.ts` and `src/composables/index.ts`. Prop types stay internal (`types.ts` is not re-exported); consumers derive them with `ComponentProps` (see [Usage](#usage)).
 - Every publicly exported component must use the `U` prefix on its export identifier (e.g., `UButton`, `UMain`), while internal file names and component names remain unprefixed.
 - Use [JSDoc](https://jsdoc.app/about-getting-started) on every method/prop/type intended to be part of the public API — it's the primary documentation surface and supports markdown/code examples.
-- Known workarounds (see CONTRIBUTING.md before touching related config): `stryker-vue-ignorer` patches a Stryker/Vue macro-hoisting issue; `vue-tsc` is used for type-check instead of Vite+'s built-in one due to an oxlint/Vue support gap; the internal `SkeletonLoader` wraps Vuetify's skeleton loader so its loading announcement gets valid ARIA attributes in server rendering. All are meant to be removed once fixed upstream — don't build further on top of them without checking if they're still needed.
+- Known workarounds (see CONTRIBUTING.md before touching related config): `stryker-vue-ignorer` patches a Stryker/Vue macro-hoisting issue; `vue-tsc` is used for type-check instead of Vite+'s built-in one due to an oxlint/Vue support gap; the internal `SkeletonLoader` wraps Vuetify's skeleton loader so its loading announcement gets valid ARIA attributes in server rendering; the navigation menu's rail (`useNavigationRail`) dispatches synthetic `mouseenter`/`mouseleave` events on Vuetify's navigation drawer, which only expands its rail on mouse events, to expand it on keyboard focus and keep it expanded when the mouse leaves with the focus inside. All are meant to be removed once fixed upstream — don't build further on top of them without checking if they're still needed.
 
 ## Testing conventions
 

package/dist/components/inputs/text-field/text-field.vue.d.ts

@@ -23,8 +23,8 @@ declare const __VLS_export: import("vue", { with: { "resolution-mode": "import"
   "onUpdate:modelValue"?: ((value: string) => any) | undefined;
 }>, {
   variant: TextFieldVariant;
-  type: TextFieldType;
   clearable: boolean;
+  type: TextFieldType;
 }, {}, {}, {}, string, import("vue", { with: { "resolution-mode": "import" } }).ComponentProvideOptions, false, {}, any>;
 //#endregion
 export { _default as default };

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

@@ -1,4 +1,5 @@
 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 container_default from "../grid/container/container.js";
@@ -50,10 +51,11 @@ var main_vue_vue_type_script_setup_true_lang_default = /*@__PURE__*/ defineCompo
 	setup(__props) {
 		const props = __props;
 		const slots = useSlots();
+		const mobile = useMobileNavigation();
 		const appBarProps = computed(() => props.appBar ? {
 			...props.appBar,
 			logo: props.logo,
-			navigation: props.navigationMenu !== void 0,
+			navigation: props.navigationMenu !== void 0 && mobile.value,
 			loading: props.loading
 		} : void 0);
 		const backgroundClass = useVuetifyBackgroundColor(() => props.background);

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

@@ -3,7 +3,8 @@ import { routeToListItemProps } from "../../composables/navigation/use-route-pro
 import { useNavigationSearchShortcut } from "../../composables/navigation/use-navigation-search-shortcut.js";
 import skeleton_loader_default from "../skeleton-loader/skeleton-loader.js";
 import text_field_default from "../inputs/text-field/text-field.js";
-import { Fragment, computed, createBlock, createCommentVNode, createElementBlock, createElementVNode, createVNode, defineComponent, mergeModels, mergeProps, openBlock, ref, renderList, unref, useModel, useTemplateRef, withCtx, withKeys } from "vue";
+import { isParentItem, useNavigationRail } from "../../composables/navigation/use-navigation-rail.js";
+import { Fragment, computed, createBlock, createCommentVNode, createElementBlock, createElementVNode, createVNode, defineComponent, isRef, mergeModels, mergeProps, openBlock, ref, renderList, unref, useModel, useTemplateRef, vShow, withCtx, withDirectives, withKeys } from "vue";
 import { VDivider, VList, VListGroup, VListItem, VNavigationDrawer } from "vuetify/components";
 //#region src/components/navigation-menu/navigation-menu.vue?vue&type=script&setup=true&lang.ts
 const _hoisted_1 = { class: "px-4 pt-2" };
@@ -35,11 +36,22 @@ var navigation_menu_vue_vue_type_script_setup_true_lang_default = /*@__PURE__*/
 		const props = __props;
 		const open = useModel(__props, "modelValue");
 		const search = ref("");
-		const { label: shortcutLabel, close } = useNavigationSearchShortcut({
+		const field = useTemplateRef("searchField");
+		const { mobile, collapsed, drawerOpen, menuOpen, opened, isActiveGroup, dismiss, isRestoringFocus, onFocusin, onFocusout, onMouseenter, onMouseleave } = useNavigationRail({
 			open,
-			field: useTemplateRef("searchField")
+			field,
+			searchItem: useTemplateRef("searchItem"),
+			items: () => props.items,
+			search
+		});
+		const { label: shortcutLabel, ariaKeyshortcuts, openSearch } = useNavigationSearchShortcut({
+			open: menuOpen,
+			field
 		});
 		const filteredItems = computed(() => filterItems());
+		function onSearchItemFocus(event) {
+			if (!isRestoringFocus()) openSearch(event.relatedTarget);
+		}
 		const searchDataTestid = computed(() => `${props.dataTestid}-search`);
 		const query = computed(() => search.value.toLowerCase());
 		function filterItems() {
@@ -58,49 +70,91 @@ var navigation_menu_vue_vue_type_script_setup_true_lang_default = /*@__PURE__*/
 		function matches(item) {
 			return item.description.toLowerCase().includes(query.value);
 		}
-		function isParentItem(item) {
-			return "items" in item;
-		}
 		return (_ctx, _cache) => {
 			return openBlock(), createBlock(unref(VNavigationDrawer), {
-				modelValue: open.value,
-				"onUpdate:modelValue": _cache[1] || (_cache[1] = ($event) => open.value = $event),
+				modelValue: unref(drawerOpen),
+				"onUpdate:modelValue": _cache[2] || (_cache[2] = ($event) => isRef(drawerOpen) ? drawerOpen.value = $event : null),
 				color: "primary",
 				"data-testid": props.dataTestid,
 				"aria-busy": props.loading || void 0,
+				mobile: unref(mobile),
+				permanent: !unref(mobile),
+				rail: !unref(mobile),
+				"expand-on-hover": "",
 				absolute: "",
 				temporary: "",
-				onKeydown: withKeys(unref(close), ["esc"])
+				onFocusin: unref(onFocusin),
+				onFocusout: unref(onFocusout),
+				onMouseenter: unref(onMouseenter),
+				onMouseleave: unref(onMouseleave),
+				onKeydown: withKeys(unref(dismiss), ["esc"])
 			}, {
-				prepend: withCtx(() => [createElementVNode("div", _hoisted_1, [createVNode(text_field_default, {
-					ref: "searchField",
-					modelValue: search.value,
-					"onUpdate:modelValue": _cache[0] || (_cache[0] = ($event) => search.value = $event),
-					type: "search",
-					placeholder: `Buscar (${unref(shortcutLabel)})`,
-					"data-testid": searchDataTestid.value,
-					disabled: props.loading
-				}, null, 8, [
-					"modelValue",
-					"placeholder",
-					"data-testid",
-					"disabled"
-				])])]),
+				prepend: withCtx(() => [
+					withDirectives(createElementVNode("div", _hoisted_1, [createVNode(text_field_default, {
+						ref: "searchField",
+						modelValue: search.value,
+						"onUpdate:modelValue": _cache[0] || (_cache[0] = ($event) => search.value = $event),
+						type: "search",
+						placeholder: `Buscar (${unref(shortcutLabel)})`,
+						"data-testid": searchDataTestid.value,
+						disabled: props.loading
+					}, null, 8, [
+						"modelValue",
+						"placeholder",
+						"data-testid",
+						"disabled"
+					])], 512), [[vShow, !unref(collapsed)]]),
+					createCommentVNode(" Vuetify's list is focusable and passes the focus on to its first item: out of the tab\n      order, the item gets the focus straight from the page, which then gets it back on `Esc` "),
+					withDirectives(createVNode(unref(VList), {
+						nav: "",
+						role: "group",
+						tabindex: "-1"
+					}, {
+						default: withCtx(() => [createCommentVNode(" Rendered as a native button, as the groups' headers (see below). Vuetify only styles\n        a disabled item, and its button would still take the focus "), createVNode(unref(VListItem), {
+							ref: "searchItem",
+							title: "Buscar",
+							"prepend-icon": unref(icons).search,
+							disabled: props.loading,
+							tabindex: props.loading ? -1 : void 0,
+							"aria-disabled": props.loading || void 0,
+							"aria-keyshortcuts": unref(ariaKeyshortcuts),
+							role: void 0,
+							tag: "button",
+							type: "button",
+							class: "w-100 text-start",
+							onFocus: onSearchItemFocus
+						}, null, 8, [
+							"prepend-icon",
+							"disabled",
+							"tabindex",
+							"aria-disabled",
+							"aria-keyshortcuts"
+						])]),
+						_: 1
+					}, 512), [[vShow, unref(collapsed)]])
+				]),
 				default: withCtx(() => [createVNode(unref(VDivider)), createVNode(skeleton_loader_default, {
 					loading: props.loading,
 					type: "list-item@6",
 					color: "primary"
 				}, {
 					default: withCtx(() => [createCommentVNode(" Vuetify's `list` role only allows list items, but the items are links "), createVNode(unref(VList), {
+						opened: unref(opened),
+						"onUpdate:opened": _cache[1] || (_cache[1] = ($event) => isRef(opened) ? opened.value = $event : null),
 						nav: "",
 						role: "group"
 					}, {
 						default: withCtx(() => [(openBlock(true), createElementBlock(Fragment, null, renderList(filteredItems.value, (item, index) => {
-							return openBlock(), createElementBlock(Fragment, { key: index }, [isParentItem(item) ? (openBlock(), createBlock(unref(VListGroup), { key: 0 }, {
+							return openBlock(), createElementBlock(Fragment, { key: index }, [unref(isParentItem)(item) ? (openBlock(), createBlock(unref(VListGroup), {
+								key: 0,
+								value: item.description
+							}, {
 								activator: withCtx(({ props: activatorProps, isOpen }) => [createVNode(unref(VListItem), mergeProps({ ref_for: true }, activatorProps, {
 									title: item.description,
-									"prepend-icon": item.icon && unref(icons)[item.icon],
+									"prepend-icon": unref(icons)[item.icon],
+									active: unref(isActiveGroup)(item),
 									"aria-expanded": isOpen,
+									"aria-selected": void 0,
 									role: void 0,
 									tag: "button",
 									type: "button",
@@ -108,6 +162,7 @@ var navigation_menu_vue_vue_type_script_setup_true_lang_default = /*@__PURE__*/
 								}), null, 16, [
 									"title",
 									"prepend-icon",
+									"active",
 									"aria-expanded"
 								])]),
 								default: withCtx(() => [(openBlock(true), createElementBlock(Fragment, null, renderList(item.items, (childItem, childIndex) => {
@@ -117,10 +172,10 @@ var navigation_menu_vue_vue_type_script_setup_true_lang_default = /*@__PURE__*/
 									}), null, 16, ["title", "onClick"]);
 								}), 128))]),
 								_: 2
-							}, 1024)) : (openBlock(), createBlock(unref(VListItem), mergeProps({
+							}, 1032, ["value"])) : (openBlock(), createBlock(unref(VListItem), mergeProps({
 								key: 1,
 								title: item.description,
-								"prepend-icon": item.icon && unref(icons)[item.icon]
+								"prepend-icon": unref(icons)[item.icon]
 							}, { ref_for: true }, unref(routeToListItemProps)(item.route), { onClick: item.action }), null, 16, [
 								"title",
 								"prepend-icon",
@@ -128,7 +183,7 @@ var navigation_menu_vue_vue_type_script_setup_true_lang_default = /*@__PURE__*/
 							]))], 64);
 						}), 128))]),
 						_: 1
-					})]),
+					}, 8, ["opened"])]),
 					_: 1
 				}, 8, ["loading"])]),
 				_: 1
@@ -136,6 +191,13 @@ var navigation_menu_vue_vue_type_script_setup_true_lang_default = /*@__PURE__*/
 				"modelValue",
 				"data-testid",
 				"aria-busy",
+				"mobile",
+				"permanent",
+				"rail",
+				"onFocusin",
+				"onFocusout",
+				"onMouseenter",
+				"onMouseleave",
 				"onKeydown"
 			]);
 		};

package/dist/components/navigation-menu/types.d.ts

@@ -22,12 +22,12 @@ export type NavigationMenuParentItem = {
    */
   description: string;
   /**
-   * Icon shown before the group's description. One of the names listed on the "Ícones" guide
-   * page.
+   * Icon shown before the group's description, and alone while the menu is collapsed to a rail.
+   * One of the names listed on the "Ícones" guide page.
    *
    * @see {@link https://nexdom-healthtech.github.io/uimed-vue/guide/icons | Icons Guide}
    */
-  icon?: Icon;
+  icon: Icon;
   /**
    * Child {@link NavigationMenuChildItem} list. Unlike the first level items, they show no icon.
    */
@@ -44,12 +44,12 @@ export interface NavigationMenuItem {
    */
   description: string;
   /**
-   * Icon shown before the item's description. One of the names listed on the "Ícones" guide
-   * page.
+   * Icon shown before the item's description, and alone while the menu is collapsed to a rail.
+   * One of the names listed on the "Ícones" guide page.
    *
    * @see {@link https://nexdom-healthtech.github.io/uimed-vue/guide/icons | Icons Guide}
    */
-  icon?: Icon;
+  icon: Icon;
   /**
    * Route to navigate when item is clicked.
    */

package/dist/composables/navigation/use-navigation-rail.js

@@ -0,0 +1,163 @@
+import { isExternalRoute } from "./use-route-props.js";
+import { useDisplay } from "vuetify";
+import { computed, inject, nextTick, onMounted, ref, toValue, watch } from "vue";
+import { isDeepEqual } from "@nexdom/shared/utils";
+import { routerKey } from "vue-router";
+//#region src/composables/navigation/use-navigation-rail.ts
+/**
+* Mouse events the rail dispatches on the drawer to expand or collapse it, which its own listeners
+* ignore.
+*/
+const syntheticEvents = /* @__PURE__ */ new WeakSet();
+/**
+* Whether the navigation menu is a temporary drawer, opened by the app bar's button, instead of a
+* rail. Starts as the drawer and switches on mount, so server-rendered pages (the docs), rendered
+* without a window width, hydrate without mismatches.
+*/
+function useMobileNavigation() {
+	const { mobile } = useDisplay();
+	const mounted = ref(false);
+	onMounted(() => mounted.value = true);
+	return computed(() => !mounted.value || mobile.value);
+}
+/**
+* State of the navigation menu as a rail, above the mobile breakpoint: collapsed to its icons, and
+* expanded over the page while the mouse is over it, the keyboard focus is in it or the user is
+* searching. `Esc` collapses it until the mouse enters it, the focus leaves and enters it again
+* or the user searches.
+*
+* The drawer only expands its rail on its own mouse events, so the rail dispatches them itself to
+* expand on focus, and to stay expanded when the mouse leaves with the focus inside.
+*/
+function useNavigationRail(options) {
+	const { open, field, searchItem, items, search } = options;
+	const mobile = useMobileNavigation();
+	const router = inject(routerKey, null);
+	const pointerInside = ref(false);
+	const focusInside = ref(false);
+	const searching = ref(false);
+	/** Collapsed by `Esc`: the focus doesn't expand it again until it leaves the rail. */
+	const dismissed = ref(false);
+	let restoringFocus = false;
+	const expandedGroups = ref([]);
+	const collapsed = computed(() => !mobile.value && !(pointerInside.value || focusInside.value || searching.value));
+	const drawerOpen = computed({
+		get: () => !mobile.value || open.value,
+		set: (value) => {
+			if (mobile.value) open.value = value;
+		}
+	});
+	/** The drawer's model below the mobile breakpoint, and the rail's search state above it. */
+	const menuState = computed(() => mobile.value ? open : searching);
+	const menuOpen = computed({
+		get: () => menuState.value.value,
+		set: (value) => {
+			menuState.value.value = value;
+			dismissed.value = false;
+		}
+	});
+	const opened = computed({
+		get: () => collapsed.value ? [] : expandedGroups.value,
+		set: (value) => expandedGroups.value = value
+	});
+	watch(collapsed, (isCollapsed) => {
+		syncHover();
+		if (isCollapsed) search.value = "";
+		else expandedGroups.value = currentGroups();
+	});
+	watch(() => router?.currentRoute.value, () => searching.value = false);
+	function onFocusin(event) {
+		focusInside.value = !dismissed.value && event.target.matches(":focus-visible");
+	}
+	function onFocusout(event) {
+		if (isInside(event, event.relatedTarget)) return;
+		focusInside.value = false;
+		searching.value = false;
+		dismissed.value = false;
+	}
+	function onMouseenter(event) {
+		if (syntheticEvents.has(event)) return;
+		pointerInside.value = true;
+		dismissed.value = false;
+	}
+	function onMouseleave(event) {
+		if (syntheticEvents.has(event)) return;
+		pointerInside.value = false;
+		syncHover();
+	}
+	async function dismiss() {
+		menuOpen.value = false;
+		pointerInside.value = false;
+		focusInside.value = false;
+		dismissed.value = true;
+		await nextTick();
+		if (collapsed.value && isHidingFocus()) {
+			restoringFocus = true;
+			toValue(searchItem).$el.focus();
+			restoringFocus = false;
+		}
+	}
+	/**
+	* Whether the focus is on an element the collapsed rail hides: the search field or an item of a
+	* group, which would leave the focus on the page's body.
+	*/
+	function isHidingFocus() {
+		const { activeElement } = document;
+		const groupsItems = [...findDrawer().querySelectorAll(".v-list-group__items")];
+		return toValue(field).$el.contains(activeElement) || groupsItems.some((items) => items.contains(activeElement));
+	}
+	function isRestoringFocus() {
+		return restoringFocus;
+	}
+	/** Expands or collapses the drawer's rail, through the mouse events it listens to. */
+	function syncHover() {
+		const event = new MouseEvent(collapsed.value ? "mouseleave" : "mouseenter");
+		syntheticEvents.add(event);
+		findDrawer().dispatchEvent(event);
+	}
+	function findDrawer() {
+		return toValue(field).$el.closest(".v-navigation-drawer");
+	}
+	function currentGroups() {
+		return (toValue(items) ?? []).filter((item) => isParentItem(item) && hasCurrentRoute(item)).map(({ description }) => description);
+	}
+	function isActiveGroup(item) {
+		return collapsed.value && hasCurrentRoute(item);
+	}
+	function hasCurrentRoute(item) {
+		return item.items.some(({ route }) => isCurrentRoute(route));
+	}
+	/**
+	* Whether the route is the current page, or one of its parents, as the links highlight
+	* themselves: by the matched route record and the params the route sets.
+	*/
+	function isCurrentRoute(route) {
+		if (!router || route === void 0 || isExternalRoute(route)) return false;
+		const { matched, params } = router.resolve(route);
+		const current = router.currentRoute.value;
+		const record = matched.at(-1);
+		return current.matched.includes(record) && Object.entries(params).every(([key, value]) => isDeepEqual(value, current.params[key]));
+	}
+	return {
+		mobile,
+		collapsed,
+		drawerOpen,
+		menuOpen,
+		opened,
+		isActiveGroup,
+		dismiss,
+		isRestoringFocus,
+		onFocusin,
+		onFocusout,
+		onMouseenter,
+		onMouseleave
+	};
+}
+function isParentItem(item) {
+	return "items" in item;
+}
+function isInside(event, target) {
+	return target instanceof Node && event.currentTarget.contains(target);
+}
+//#endregion
+export { isParentItem, useMobileNavigation, useNavigationRail };

package/dist/composables/navigation/use-navigation-search-shortcut.js

@@ -34,9 +34,10 @@ function useNavigationShortcutKeys() {
 }
 /**
 * Listens to Ctrl+K (⌘K on macOS) on `window` while mounted: opens the menu, waits for it to
-* render (the drawer is `inert` while closed) and focuses the search field (a disabled field, as
-* while loading, can't take the focus). When the menu opened by the shortcut closes with the focus
-* inside it, the focus goes back to where it was.
+* render (the drawer is `inert` while closed, and the rail only shows the field while expanded)
+* and focuses the search field (a disabled field, as while loading, can't take the focus). When
+* the menu opened by the shortcut closes with the focus inside it, the focus goes back to where it
+* was.
 */
 function useNavigationSearchShortcut(options) {
 	const { open, field } = options;
@@ -61,12 +62,13 @@ function useNavigationSearchShortcut(options) {
 	});
 	function onKeydown(event) {
 		if (owners.value[0] !== owner || isIgnoredTarget(event)) return;
-		if (isShortcut(event)) openAndFocus(event);
-		else if (event.key === "Escape" && origin) close();
+		if (isShortcut(event)) {
+			event.preventDefault();
+			openSearch(document.activeElement);
+		} else if (event.key === "Escape" && origin) open.value = false;
 	}
-	async function openAndFocus(event) {
-		event.preventDefault();
-		if (!open.value) origin = document.activeElement;
+	async function openSearch(from) {
+		if (!open.value) origin = from;
 		open.value = true;
 		await nextTick();
 		const input = findInput();
@@ -76,12 +78,9 @@ function useNavigationSearchShortcut(options) {
 	function findInput() {
 		return toValue(field).$el.querySelector("input");
 	}
-	function close() {
-		open.value = false;
-	}
 	return {
 		...useNavigationShortcutKeys(),
-		close
+		openSearch
 	};
 }
 function isMacOS() {

package/package.json

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