@nexdom/uimed-vue 2.0.0-beta.24 → 2.0.0-beta.26

package/AGENTS.md

@@ -151,7 +151,7 @@ Use an existing component (e.g. `button`) as the reference, and deliver all of t
 
 1. `src/components/<name>/<name>.vue` (following the pattern in [Code conventions](#code-conventions)), `types.ts` and `__tests__/<name>.test.ts`.
 2. The `U`-prefixed export in `src/components/index.ts`.
-3. A usage guide at `docs/guide/components/<name>.md`, with `<demo>` examples (and a `<playground>` section when the component has configurable props), and an API reference at `docs/api/components/<name>.md` (props, events and slots tables). Both in Portuguese.
+3. A usage guide at `docs/guide/components/<name>.md`, with `<demo>` examples (and a `<playground>` section when the component has configurable props), and an API reference at `docs/api/components/<name>.md` (props, events and slots tables). Both in Portuguese. In a demo's template inside a `.md` file, don't put an attribute with a template literal after one with an arrow function in the same tag: the Markdown type-check (`vue-tsc`) reads the `>` of `=>` as the end of the tag and fails with `TS1003`. Order the attributes so the template literal comes first.
 4. Both pages registered in the sidebar at `docs/.vitepress/config.ts`.
 5. `e2e/components/<name>.spec.ts` covering the guide's interactive examples and a "UI consistency" screenshot check (plus accessible snapshots where relevant). Commit the generated files under `__snapshots__`/`__screenshot__`.
 6. The full CI sequence passing locally.
@@ -173,7 +173,7 @@ Use an existing composable (e.g. `use-toast`) as the reference, and deliver in t
   - A new component/composable must be listed in its guide page (`docs/guide/…`), its API page (`docs/api/…`), both sidebars in `docs/.vitepress/config.ts`, the guide index table (`docs/guide/index.md`) and the API index list (`docs/api/index.md`).
 - Never write CSS or `<style>` blocks, and expose styling to consumers only through props.
 - Adjustments that Vuetify exposes as Sass variables (e.g. a font family or a line height) go in `src/styles/settings.scss`, which `vitePluginUimed()` compiles into Vuetify's stylesheets in the apps. That file only configures variables: still no CSS rules.
-- Don't add spacing to Vuetify components: no padding or margin utility classes (`pa-*`, `pt-6`, `px-4`, `ma-2`, ...) and no spacing props overriding the defaults. Vuetify already applies Material Design 3 spacing, and overriding it breaks what it handles on its own, such as button paddings and the scrollbar of scrollable content. If the default spacing looks wrong, stop and ask instead of adjusting it.
+- Don't add spacing to Vuetify components: no padding or margin utility classes (`pa-*`, `pt-6`, `px-4`, `ma-2`, ...) and no spacing props overriding the defaults. Vuetify already applies Material Design 3 spacing, and overriding it breaks what it handles on its own, such as button paddings and the scrollbar of scrollable content. If the default spacing looks wrong, stop and ask instead of adjusting it. The one accepted layout margin is `mt-auto` on `v-card-actions` (as in `USection`), which pushes the actions to the bottom of a full-height card without setting any spacing value.
 - Prefer a Vuetify component's own props to building its parts by hand (e.g. `title`/`text` on `v-card` instead of `v-card-item` > `v-card-title` > `v-card-text`). A non-spacing utility class is acceptable only when no prop covers the need (e.g. `text-wrap` on a card title), with a comment saying why.
 - Keep components thin: a component wires props, slots and events to Vuetify. Logic beyond that (focus management, queues, DOM lookups, comparisons) goes into an internal composable with its own unit tests.
 - Path aliases: `@/*` → `src/*`, `@e2e/*` → `e2e/*`.

package/dist/components.d.ts

@@ -433,8 +433,8 @@ declare const __VLS_export$14: import("vue", { with: { "resolution-mode": "impor
   "onUpdate:modelValue"?: ((value: string) => any) | undefined;
 }>, {
   variant: TextFieldVariant;
-  clearable: boolean;
   type: TextFieldType;
+  clearable: boolean;
 }, {}, {}, {}, string, import("vue", { with: { "resolution-mode": "import" } }).ComponentProvideOptions, false, {}, any>;
 //#endregion
 //#region src/components/inputs/checkbox/types.d.ts
@@ -1289,6 +1289,12 @@ type DataSetItemProps = {
    * @default "primary"
    */
   variant?: SectionVariant;
+  /**
+   * Actions of the record, like "Editar" and "Excluir", displayed at the
+   * bottom of its card, just like on `USection`. When undefined or empty, no
+   * actions area is rendered.
+   */
+  actions?: SectionAction[];
   /**
    * Component id to use on automated tests.
    */
@@ -1316,7 +1322,11 @@ type DataSetItemSlots = {
  * <template>
  *   <u-data-set :items="patients">
  *     <template #default="{ item }">
- *       <u-data-set-item :title="item.name" subtitle="Beneficiário">
+ *       <u-data-set-item
+ *         :title="item.name"
+ *         subtitle="Beneficiário"
+ *         :actions="[{ label: 'Editar', variant: 'secondary', onClick: () => edit(item) }]"
+ *       >
  *         <u-table :headers="['Plano', 'Idade']" :items="[[item.plan, item.age]]" vertical />
  *       </u-data-set-item>
  *     </template>

package/dist/components.js

@@ -1,5 +1,5 @@
-import { a as messages, n as owners, r as requests, s as useVuetifyColor } from "./use-dialog-Ck2_ZW7T.js";
-import { Fragment, computed, createBlock, createCommentVNode, createElementBlock, createElementVNode, createSlots, createTextVNode, createVNode, defineComponent, guardReactiveProps, inject, isRef, mergeModels, mergeProps, normalizeClass, normalizeProps, onMounted, onScopeDispose, onUnmounted, openBlock, provide, ref, renderList, renderSlot, resolveDynamicComponent, shallowRef, toDisplayString, toValue, unref, useId, useModel, useSlots, useTemplateRef, watch, withCtx, withModifiers } from "vue";
+import { a as messages, n as owners$1, r as requests, s as useVuetifyColor } from "./use-dialog-Ck2_ZW7T.js";
+import { Fragment, computed, createBlock, createCommentVNode, createElementBlock, createElementVNode, createSlots, createTextVNode, createVNode, defineComponent, guardReactiveProps, inject, isRef, mergeModels, mergeProps, nextTick, normalizeClass, normalizeProps, onMounted, onScopeDispose, onUnmounted, openBlock, provide, ref, renderList, renderSlot, resolveDynamicComponent, shallowRef, toDisplayString, toValue, unref, useId, useModel, useSlots, useTemplateRef, watch, withCtx, withKeys, withModifiers } from "vue";
 import { pt } from "vuetify/locale";
 import { VApp, VAppBar, VAppBarNavIcon, VAppBarTitle, VAutocomplete, VAvatar, VBadge, VBtn, VCard, VCardActions, VCardText, VCheckboxBtn, VCol, VCombobox, VContainer, VDataIterator, VDatePicker, VDialog, VDivider, VEmptyState, VExpansionPanel, VExpansionPanelText, VExpansionPanelTitle, VExpansionPanels, VForm, VIcon, VIconBtn, VImg, VList, VListGroup, VListItem, VListItemAction, VListSubheader, VLocaleProvider, VMain, VMenu, VNavigationDrawer, VPagination, VProgressLinear, VRow, VSkeletonLoader, VSnackbarQueue, VTable, VTextField, VTimePicker } from "vuetify/components";
 import { formatDateTime, isEmail, isEmpty, isPhone, isUrl } from "@nexdom/shared/utils";
@@ -15,6 +15,101 @@ function isExternalRoute(route) {
 	return typeof route === "string" && route.startsWith("http");
 }
 //#endregion
+//#region src/composables/navigation/use-navigation-search-shortcut.ts
+/**
+* Mounted navigation menus, in mounting order. Only the first one answers the shortcut, so pages
+* with more than one `UMain` (like the docs) don't open every menu at once.
+*/
+const owners = ref([]);
+/**
+* Focus targets where the shortcut is left to the page: overlays (dialogs, confirmations and
+* menus) and other modals, the activators of open menus (which keep the focus when opened by a
+* click, and would pull it back from the navigation menu) and rich text editors, which usually
+* take Ctrl+K to insert links.
+*/
+const IGNORED_TARGETS = [
+	".v-overlay",
+	"dialog",
+	"[aria-modal='true']",
+	"[aria-haspopup][aria-expanded='true']",
+	"[contenteditable]:not([contenteditable='false'])"
+].join(", ");
+/** Accessible name of the search field, whose placeholder also shows the shortcut. */
+const SEARCH_NAME = "Buscar";
+/**
+* Shortcut keys for the current platform. Starts with the non-macOS keys and switches on mount,
+* so server-rendered pages (the docs) hydrate without mismatches.
+*/
+function useNavigationShortcutKeys() {
+	const isMac = ref(false);
+	onMounted(() => isMac.value = isMacOS());
+	return {
+		label: computed(() => isMac.value ? "⌘K" : "Ctrl+K"),
+		ariaKeyshortcuts: computed(() => isMac.value ? "Meta+K" : "Control+K")
+	};
+}
+/**
+* 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.
+*/
+function useNavigationSearchShortcut(options) {
+	const { open, field } = options;
+	const owner = Symbol("navigation-search-shortcut");
+	/** Element focused before the shortcut opened the menu, which gets the focus back on close. */
+	let origin = null;
+	onMounted(() => {
+		owners.value.push(owner);
+		globalThis.addEventListener("keydown", onKeydown, { capture: true });
+		findInput().setAttribute("aria-label", SEARCH_NAME);
+	});
+	onUnmounted(() => {
+		owners.value = owners.value.filter((item) => item !== owner);
+		globalThis.removeEventListener("keydown", onKeydown, { capture: true });
+	});
+	watch(open, (isOpen) => {
+		if (isOpen) return;
+		const target = origin;
+		origin = null;
+		if (!findInput().closest(".v-navigation-drawer").contains(document.activeElement)) return;
+		if (target instanceof HTMLElement || target instanceof SVGElement) target.focus();
+	});
+	function onKeydown(event) {
+		if (owners.value[0] !== owner || isIgnoredTarget(event)) return;
+		if (isShortcut(event)) openAndFocus(event);
+		else if (event.key === "Escape" && origin) close();
+	}
+	async function openAndFocus(event) {
+		event.preventDefault();
+		if (!open.value) origin = document.activeElement;
+		open.value = true;
+		await nextTick();
+		const input = findInput();
+		input.focus({ preventScroll: true });
+		input.select();
+	}
+	function findInput() {
+		return field.value.$el.querySelector("input");
+	}
+	function close() {
+		open.value = false;
+	}
+	return {
+		...useNavigationShortcutKeys(),
+		close
+	};
+}
+function isMacOS() {
+	return navigator.userAgent.includes("Macintosh");
+}
+function isShortcut(event) {
+	return (isMacOS() ? event.metaKey : event.ctrlKey) && !event.shiftKey && !event.altKey && !event.isComposing && event.key.toLowerCase() === "k";
+}
+function isIgnoredTarget(event) {
+	return event.target instanceof Element && event.target.closest(IGNORED_TARGETS) !== null;
+}
+//#endregion
 //#region src/components/app-bar/app-bar.vue?vue&type=script&setup=true&lang.ts
 const _hoisted_1$3 = { class: "opacity-60" };
 //#endregion
@@ -69,6 +164,7 @@ var app_bar_default = /* @__PURE__ */ defineComponent({
 		const props = __props;
 		const notificationsOpen = useModel(__props, "notificationsOpen");
 		const navigationOpen = useModel(__props, "navigationOpen");
+		const { ariaKeyshortcuts: navigationKeyshortcuts } = useNavigationShortcutKeys();
 		const helpBtnDataTestid = computed(() => `${props.dataTestid}-help`);
 		const notificationsBtnDataTestid = computed(() => `${props.dataTestid}-notifications`);
 		const navigationBtnDataTestid = computed(() => `${props.dataTestid}-navigation`);
@@ -221,8 +317,13 @@ var app_bar_default = /* @__PURE__ */ defineComponent({
 						"data-testid": navigationBtnDataTestid.value,
 						"aria-expanded": navigationOpen.value,
 						"aria-label": "Menu de navegação",
+						"aria-keyshortcuts": unref(navigationKeyshortcuts),
 						onClick: _cache[0] || (_cache[0] = ($event) => navigationOpen.value = !navigationOpen.value)
-					}, null, 8, ["data-testid", "aria-expanded"])) : createCommentVNode("v-if", true),
+					}, null, 8, [
+						"data-testid",
+						"aria-expanded",
+						"aria-keyshortcuts"
+					])) : createCommentVNode("v-if", true),
 					__props.logo ? (openBlock(), createBlock(unref(VImg), {
 						key: 1,
 						src: props.logo,
@@ -488,6 +589,10 @@ var navigation_menu_default = /* @__PURE__ */ defineComponent({
 		const props = __props;
 		const open = useModel(__props, "modelValue");
 		const search = ref("");
+		const { label: shortcutLabel, close } = useNavigationSearchShortcut({
+			open,
+			field: useTemplateRef("searchField")
+		});
 		const filteredItems = computed(() => filterItems());
 		const searchDataTestid = computed(() => `${props.dataTestid}-search`);
 		const query = computed(() => search.value.toLowerCase());
@@ -518,17 +623,20 @@ var navigation_menu_default = /* @__PURE__ */ defineComponent({
 				"data-testid": props.dataTestid,
 				"aria-busy": props.loading || void 0,
 				absolute: "",
-				temporary: ""
+				temporary: "",
+				onKeydown: withKeys(unref(close), ["esc"])
 			}, {
 				prepend: withCtx(() => [createElementVNode("div", _hoisted_1$2, [createVNode(text_field_default, {
+					ref: "searchField",
 					modelValue: search.value,
 					"onUpdate:modelValue": _cache[0] || (_cache[0] = ($event) => search.value = $event),
 					type: "search",
-					label: "Buscar",
+					placeholder: `Buscar (${unref(shortcutLabel)})`,
 					"data-testid": searchDataTestid.value,
 					disabled: props.loading
 				}, null, 8, [
 					"modelValue",
+					"placeholder",
 					"data-testid",
 					"disabled"
 				])])]),
@@ -561,7 +669,8 @@ var navigation_menu_default = /* @__PURE__ */ defineComponent({
 			}, 8, [
 				"modelValue",
 				"data-testid",
-				"aria-busy"
+				"aria-busy",
+				"onKeydown"
 			]);
 		};
 	}
@@ -892,7 +1001,7 @@ var dialog_host_default = /* @__PURE__ */ defineComponent({
 	__name: "dialog-host",
 	setup(__props) {
 		const owner = Symbol("dialog");
-		const isOwner = computed(() => owners.value[0] === owner);
+		const isOwner = computed(() => owners$1.value[0] === owner);
 		const next = computed(() => isOwner.value ? requests.value[0] : void 0);
 		/** Dialog on display, kept until its leave transition ends. */
 		const request = shallowRef();
@@ -921,8 +1030,8 @@ var dialog_host_default = /* @__PURE__ */ defineComponent({
 			persistent: () => isRunning.value,
 			afterLeave: showNext
 		});
-		onMounted(() => owners.value.push(owner));
-		onUnmounted(() => owners.value = owners.value.filter((item) => item !== owner));
+		onMounted(() => owners$1.value.push(owner));
+		onUnmounted(() => owners$1.value = owners$1.value.filter((item) => item !== owner));
 		watch(next, show);
 		function show() {
 			if (request.value) return;
@@ -2253,6 +2362,10 @@ var data_set_item_default = /* @__PURE__ */ defineComponent({
 			type: String,
 			required: false
 		},
+		actions: {
+			type: Array,
+			required: false
+		},
 		dataTestid: {
 			type: String,
 			required: false
@@ -2266,6 +2379,7 @@ var data_set_item_default = /* @__PURE__ */ defineComponent({
 				title: props.title,
 				subtitle: props.subtitle,
 				variant: props.variant,
+				actions: props.actions,
 				"data-testid": props.dataTestid,
 				"full-height": ""
 			}, {
@@ -2278,6 +2392,7 @@ var data_set_item_default = /* @__PURE__ */ defineComponent({
 				"title",
 				"subtitle",
 				"variant",
+				"actions",
 				"data-testid"
 			]);
 		};

package/package.json

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