@nexdom/uimed-vue 2.0.0-beta.8 → 2.0.0

package/dist/composables/navigation/types.d.ts

@@ -0,0 +1,54 @@
+import { ColorVariant } from "../colors/types.js";
+import { MaybeRefOrGetter } from "vue";
+//#region src/composables/navigation/types.d.ts
+/**
+ * Values compared by `useUnsavedChanges`.
+ */
+export interface UnsavedChangesValues<T> {
+  /**
+   * Original (last saved) value. To mark the form as saved, assign it a copy of the current value.
+   */
+  previous: MaybeRefOrGetter<T>;
+  /**
+   * Current value of the form.
+   */
+  current: MaybeRefOrGetter<T>;
+}
+/**
+ * Options of `useUnsavedChanges`.
+ */
+export interface UnsavedChangesOptions {
+  /**
+   * Plain text displayed as the confirmation dialog's title. HTML isn't interpreted.
+   * @default "Alterações não salvas"
+   */
+  title?: string;
+  /**
+   * Plain text displayed as the confirmation dialog's message. HTML isn't interpreted.
+   * @default "Existem alterações que ainda não foram salvas. Deseja sair sem salvar?"
+   */
+  message?: string;
+  /**
+   * Text displayed on the button which leaves the page.
+   * @default "Sair sem salvar"
+   */
+  confirmText?: string;
+  /**
+   * Text displayed on the button which cancels the navigation.
+   * @default "Continuar editando"
+   */
+  cancelText?: string;
+  /**
+   * Applies a color to the button which leaves the page.
+   * One of `primary`, `secondary`, `positive`, `informative`, `caution`, or `danger`.
+   * @default "danger"
+   */
+  color?: ColorVariant;
+  /**
+   * Also asks for the browser's native confirmation on reload (F5), tab close or leaving the app
+   * through an external link.
+   * @default true
+   */
+  beforeUnload?: boolean;
+}
+//#endregion

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

@@ -0,0 +1,96 @@
+import { computed, nextTick, onMounted, onUnmounted, ref, toValue, watch } from "vue";
+//#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 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;
+	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)) {
+			event.preventDefault();
+			openSearch(document.activeElement);
+		} else if (event.key === "Escape" && origin) open.value = false;
+	}
+	async function openSearch(from) {
+		if (!open.value) origin = from;
+		open.value = true;
+		await nextTick();
+		const input = findInput();
+		input.focus({ preventScroll: true });
+		input.select();
+	}
+	function findInput() {
+		return toValue(field).$el.querySelector("input");
+	}
+	return {
+		...useNavigationShortcutKeys(),
+		openSearch
+	};
+}
+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
+export { owners, useNavigationSearchShortcut, useNavigationShortcutKeys };

package/dist/composables/navigation/use-route-props.js

@@ -0,0 +1,21 @@
+import { computed, toValue } from "vue";
+//#region src/composables/navigation/use-route-props.ts
+function useRouteProps(route) {
+	return computed(() => routeToProps(route));
+}
+function routeToProps(route) {
+	const location = toValue(route);
+	return isExternalRoute(location) ? { href: location } : { to: location };
+}
+/**
+* Maps a menu item's route to its list item's props. An item without a route only runs its action,
+* so it's a button: Vuetify would make it a list item, which the menus' groups of links don't allow.
+*/
+function routeToListItemProps(route) {
+	return route ? routeToProps(route) : { role: "button" };
+}
+function isExternalRoute(route) {
+	return typeof route === "string" && route.startsWith("http");
+}
+//#endregion
+export { useRouteProps as default, isExternalRoute, routeToListItemProps, routeToProps };

package/dist/composables/navigation/use-unsaved-changes.d.ts

@@ -0,0 +1,35 @@
+import { UnsavedChangesOptions, UnsavedChangesValues } from "./types.js";
+import { ComputedRef } from "vue";
+//#region src/composables/navigation/use-unsaved-changes.d.ts
+/**
+ * Composable which compares the original and the current values of a form, and asks the user to
+ * confirm before leaving the page while they differ.
+ *
+ * Must be called in the `setup` of a component. Leaving through vue-router is only guarded in
+ * components rendered by a `<RouterView>`, and the confirmation dialog is displayed by `UMain`.
+ *
+ * @param values - The original (`previous`) and current (`current`) values, as refs, getters or
+ * reactive objects. They're compared in depth: key order doesn't matter, a key holding `undefined`
+ * equals a missing key, dates are compared by their time and arrays item by item, in order.
+ * @param options - Texts and color of the confirmation dialog, and whether to ask for the
+ * browser's native confirmation before unloading the page.
+ * @returns `hasChanges`, a computed property which is `true` while the values differ
+ *
+ * @example
+ * ```ts
+ * const saved = ref({ name: "Maria" });
+ * const form = ref(structuredClone(toRaw(saved.value)));
+ *
+ * const { hasChanges } = useUnsavedChanges({ previous: saved, current: form });
+ *
+ * async function save() {
+ *   await api.save(form.value);
+ *   // Marks the form as saved
+ *   saved.value = structuredClone(toRaw(form.value));
+ * }
+ * ```
+ */
+export default function useUnsavedChanges<T>(values: UnsavedChangesValues<T>, options?: UnsavedChangesOptions): {
+  hasChanges: ComputedRef<boolean>;
+};
+//#endregion

package/dist/composables/navigation/use-unsaved-changes.js

@@ -0,0 +1,88 @@
+import useConfirm from "../dialogs/use-confirm.js";
+import { computed, onActivated, onDeactivated, onMounted, onUnmounted, toValue, watch } from "vue";
+import { isDeepEqual } from "@nexdom/shared/utils";
+import { onBeforeRouteLeave } from "vue-router";
+//#region src/composables/navigation/use-unsaved-changes.ts
+/**
+* Calls whose page is on display with unsaved changes. The `beforeunload` listener is registered
+* while at least one of them exists, so a call that stops guarding doesn't remove the guard of the
+* others.
+*/
+const unloadGuards = /* @__PURE__ */ new Set();
+function preventUnload(event) {
+	event.preventDefault();
+}
+function updateUnloadListener() {
+	if (unloadGuards.size > 0) globalThis.addEventListener("beforeunload", preventUnload);
+	else globalThis.removeEventListener("beforeunload", preventUnload);
+}
+/**
+* Composable which compares the original and the current values of a form, and asks the user to
+* confirm before leaving the page while they differ.
+*
+* Must be called in the `setup` of a component. Leaving through vue-router is only guarded in
+* components rendered by a `<RouterView>`, and the confirmation dialog is displayed by `UMain`.
+*
+* @param values - The original (`previous`) and current (`current`) values, as refs, getters or
+* reactive objects. They're compared in depth: key order doesn't matter, a key holding `undefined`
+* equals a missing key, dates are compared by their time and arrays item by item, in order.
+* @param options - Texts and color of the confirmation dialog, and whether to ask for the
+* browser's native confirmation before unloading the page.
+* @returns `hasChanges`, a computed property which is `true` while the values differ
+*
+* @example
+* ```ts
+* const saved = ref({ name: "Maria" });
+* const form = ref(structuredClone(toRaw(saved.value)));
+*
+* const { hasChanges } = useUnsavedChanges({ previous: saved, current: form });
+*
+* async function save() {
+*   await api.save(form.value);
+*   // Marks the form as saved
+*   saved.value = structuredClone(toRaw(form.value));
+* }
+* ```
+*/
+function useUnsavedChanges(values, options = {}) {
+	const hasChanges = computed(() => !isDeepEqual(toValue(values.previous), toValue(values.current)));
+	const { confirm } = useConfirm();
+	/** Answer of the dialog on display, shared by every navigation made while it's open. */
+	let pending;
+	onBeforeRouteLeave(() => {
+		if (!hasChanges.value) return true;
+		pending ??= confirm({
+			title: options.title ?? "Alterações não salvas",
+			message: options.message ?? "Existem alterações que ainda não foram salvas. Deseja sair sem salvar?",
+			confirmText: options.confirmText ?? "Sair sem salvar",
+			cancelText: options.cancelText ?? "Continuar editando",
+			color: options.color ?? "danger"
+		}, async () => {}).then((answer) => answer !== false).finally(() => pending = void 0);
+		return pending;
+	});
+	/** Whether the component is on display, which is false while `<KeepAlive>` keeps it deactivated. */
+	let isActive = true;
+	if (options.beforeUnload ?? true) {
+		onMounted(() => watch(hasChanges, updateBeforeUnload, { immediate: true }));
+		onUnmounted(deactivate);
+		onDeactivated(deactivate);
+		onActivated(() => {
+			isActive = true;
+			updateBeforeUnload();
+		});
+	}
+	/** Identifies this call in `unloadGuards`. */
+	const unloadGuard = {};
+	function updateBeforeUnload() {
+		if (hasChanges.value && isActive) unloadGuards.add(unloadGuard);
+		else unloadGuards.delete(unloadGuard);
+		updateUnloadListener();
+	}
+	function deactivate() {
+		isActive = false;
+		updateBeforeUnload();
+	}
+	return { hasChanges };
+}
+//#endregion
+export { useUnsavedChanges as default };

package/dist/composables/section/section.js

@@ -0,0 +1,34 @@
+import { computed, toValue } from "vue";
+//#region src/composables/section/section.ts
+const sectionVariantToVuetifyVariant = {
+	primary: "elevated",
+	secondary: "outlined"
+};
+function useSectionVariant(variant) {
+	return computed(() => {
+		const variantValue = toValue(variant);
+		return variantValue ? sectionVariantToVuetifyVariant[variantValue] : sectionVariantToVuetifyVariant.primary;
+	});
+}
+const sectionTextAlignToClasses = {
+	start: {
+		content: "text-start",
+		actions: "justify-end"
+	},
+	center: {
+		content: "text-center",
+		actions: "justify-center"
+	},
+	end: {
+		content: "text-end",
+		actions: "justify-end"
+	}
+};
+function useSectionTextAlign(textAlign) {
+	return computed(() => {
+		const textAlignValue = toValue(textAlign);
+		return textAlignValue ? sectionTextAlignToClasses[textAlignValue] : sectionTextAlignToClasses.start;
+	});
+}
+//#endregion
+export { useSectionTextAlign, useSectionVariant };

package/dist/composables.d.ts

@@ -1,67 +1,6 @@
-import { n as FeedbackColorVariant } from "./types-BPXXtbmW.js";
-//#region src/composables/dialogs/types.d.ts
-interface ToastOptions {
-  /**
-   * Text to be presented in the toast.
-   */
-  message: string;
-  /**
-   * Applies a color to the button.
-   * One of `positive`, `informative`, `caution`, or `danger`.
-   * @default "informative"
-   */
-  color?: FeedbackColorVariant;
-}
-//#endregion
-//#region src/composables/dialogs/use-toast.d.ts
-/**
- * Composable which returns a function to display toast messages.
- *
- * @example
- * ```ts
- * const { toast } = useToast();
- * toast({ message: "Hello, World!" });
- * ```
- */
-declare function useToast(): {
-  toast: typeof toast;
-};
-/**
- * Displays a toast message.
- * @param {ToastOptions} options - Options for the toast message.
- *
- * @example
- * ```ts
- * toast({ message: "Hello, World!" });
- * ```
- */
-declare function toast(options: ToastOptions): void;
-//#endregion
-//#region src/composables/dialogs/use-run-or-toast..d.ts
-/**
- * Generate `run` method and a computed property `isRunning`.
- * Calling `run` will  reactively update `isRunning`.
- *
- * @example
- * ```ts
- * const { run, isRunning } = useRunOrToast();
- *
- * // Logs: false
- * console.log(isRunning.value);
- *
- * const promise = run(() => someFunction(param1, param2));
- *
- * // Logs: true
- * console.log(isRunning.value);
- *
- * await promise;
- * // Logs: false
- * console.log(isRunning.value);
- * ```
- */
-declare function useRunOrToast(): {
-  run: <T extends (...args: Parameters<T>) => PromiseLike<Awaited<ReturnType<T>>>>(toRun: T, ...params: Parameters<T>) => Promise<Awaited<ReturnType<T>> | false>;
-  isRunning: import("vue").ComputedRef<boolean>;
-};
-//#endregion
-export { useRunOrToast, useToast };
+import useToast from "./composables/dialogs/use-toast.js";
+import useRunOrToast from "./composables/dialogs/use-run-or-toast.js";
+import useDialog from "./composables/dialogs/use-dialog.js";
+import useConfirm from "./composables/dialogs/use-confirm.js";
+import useUnsavedChanges from "./composables/navigation/use-unsaved-changes.js";
+export { useConfirm, useDialog, useRunOrToast, useToast, useUnsavedChanges };

package/dist/composables.js

@@ -1,65 +1,6 @@
-import { n as useToast } from "./use-toast-CACuYhK_.js";
-import { computed, ref } from "vue";
-//#region src/composables/dialogs/use-run-or-toast..ts
-const { toast } = useToast();
-/**
-* Generate `run` method and a computed property `isRunning`.
-* Calling `run` will  reactively update `isRunning`.
-*
-* @example
-* ```ts
-* const { run, isRunning } = useRunOrToast();
-*
-* // Logs: false
-* console.log(isRunning.value);
-*
-* const promise = run(() => someFunction(param1, param2));
-*
-* // Logs: true
-* console.log(isRunning.value);
-*
-* await promise;
-* // Logs: false
-* console.log(isRunning.value);
-* ```
-*/
-function useRunOrToast() {
-	const running = ref(false);
-	const isRunning = computed(() => running.value);
-	/**
-	* Receives a function and its parameters, runs it, and if it throws an error, shows a toast with the error message.
-	* @returns the function returned value or `false` on error
-	*
-	* @example
-	* ```ts
-	* const { run, isRunning } = useRunOrToast();
-	*
-	* // Call like this:
-	* const someFunctionResult1 = await run(() => someFunction(param1, param2));
-	*
-	* // Or this:
-	* const someFunctionResult2 = await run(someFunction, param1, param2);
-	* ```
-	*/
-	async function run(toRun, ...params) {
-		try {
-			running.value = true;
-			return await toRun(...params);
-		} catch (error) {
-			if (error instanceof Error) toast({
-				message: error.message,
-				color: "danger"
-			});
-			else console.error(error);
-			return false;
-		} finally {
-			running.value = false;
-		}
-	}
-	return {
-		run,
-		isRunning
-	};
-}
-//#endregion
-export { useRunOrToast, useToast };
+import useToast from "./composables/dialogs/use-toast.js";
+import useDialog from "./composables/dialogs/use-dialog.js";
+import useRunOrToast from "./composables/dialogs/use-run-or-toast.js";
+import useConfirm from "./composables/dialogs/use-confirm.js";
+import useUnsavedChanges from "./composables/navigation/use-unsaved-changes.js";
+export { useConfirm, useDialog, useRunOrToast, useToast, useUnsavedChanges };