@nexdom/uimed-vue 2.0.0-beta.30 → 2.0.0-beta.32

package/AGENTS.md

@@ -26,7 +26,7 @@ Peer dependencies (`@mdi/font`, `@nexdom/shared`, `resize-observer-polyfill`, `s
 
 ### Setup
 
-Add the Vite plugin, which compiles the components' styles with the library's font and Sass settings (without it, components lose the Unimed Slab font):
+Add the Vite plugin, which compiles the components' styles with the library's font and Sass settings, and loads the icon font with `font-display`, so it doesn't block rendering while it loads. Without it, components lose the Unimed Slab font:
 
 ```ts
 // vite.config.ts
@@ -203,8 +203,9 @@ Use an existing composable (e.g. `use-toast`) as the reference, and deliver in t
   ```
 
 - Component layout: `src/components/<name>/<name>.vue`, `types.ts` for prop/option types, `__tests__/<name>.test.ts` for unit tests. Components that belong to a group live in the group's folder (e.g. the internal `src/components/dialogs/toast.vue`).
-- Composables live in a group folder: `src/composables/<group>/<name>.ts`, with `types.ts` and `__tests__/` in the group folder (e.g. `src/composables/dialogs/use-toast.ts`).
+- Composables live in a group folder: `src/composables/<group>/<name>.ts`, with `types.ts` and `__tests__/` in the group folder (e.g. `src/composables/dialogs/use-toast.ts`). A composable (`use-*.ts`) must depend on `vue` or `vue-router`, directly or through other modules (enforced by dependency-cruiser's `composables-use-vue` rule).
 - Library-wide configuration constants that aren't components or composables live in `src/consts/<name>.ts` (e.g. `src/consts/locale.ts`, the language set by `createUimed()` and `vueTestUtilsPluginUimed()`).
+- Pure helpers that don't use Vue live in `src/utils/<name>.ts`, with tests in `src/utils/__tests__/` (e.g. `src/utils/is-deep-equal.ts`).
 - 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.

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;
-  type: TextFieldType;
   clearable: boolean;
+  type: TextFieldType;
 }, {}, {}, {}, string, import("vue", { with: { "resolution-mode": "import" } }).ComponentProvideOptions, false, {}, any>;
 //#endregion
 //#region src/components/inputs/checkbox/types.d.ts

package/dist/composables.d.ts

@@ -1,4 +1,5 @@
 import { i as FeedbackColorVariant, n as ButtonVariant, r as ColorVariant } from "./types-DNT_odv7.js";
+import { ComputedRef, MaybeRefOrGetter } from "vue";
 //#region src/composables/dialogs/types.d.ts
 interface ToastOptions {
   /**
@@ -190,4 +191,89 @@ declare function useConfirm(): {
   isRunning: import("vue").ComputedRef<boolean>;
 };
 //#endregion
-export { useConfirm, useDialog, useRunOrToast, useToast };
+//#region src/composables/navigation/types.d.ts
+/**
+ * Values compared by `useUnsavedChanges`.
+ */
+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`.
+ */
+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
+//#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));
+ * }
+ * ```
+ */
+declare function useUnsavedChanges<T>(values: UnsavedChangesValues<T>, options?: UnsavedChangesOptions): {
+  hasChanges: ComputedRef<boolean>;
+};
+//#endregion
+export { useConfirm, useDialog, useRunOrToast, useToast, useUnsavedChanges };

package/dist/composables.js

@@ -1,5 +1,6 @@
 import { i as useDialog, o as useToast, t as openDialog } from "./use-dialog-Ck2_ZW7T.js";
-import { computed, ref } from "vue";
+import { computed, onActivated, onDeactivated, onMounted, onUnmounted, ref, toValue, watch } from "vue";
+import { onBeforeRouteLeave } from "vue-router";
 //#region src/composables/dialogs/use-run-or-toast.ts
 const { toast } = useToast();
 /**
@@ -114,4 +115,113 @@ function useConfirm() {
 	};
 }
 //#endregion
-export { useConfirm, useDialog, useRunOrToast, useToast };
+//#region src/utils/is-deep-equal.ts
+/**
+* Compares two values in depth, as a form would: 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. Only plain objects are compared by their keys: other objects (e.g. `File`, `Map`, `Set`
+* or class instances) and the remaining values are compared with `Object.is`, so `NaN` equals
+* `NaN`, `0` differs from `-0`, and `null`, `""` and `undefined` differ from each other.
+*/
+function isDeepEqual(a, b) {
+	if (Object.is(a, b)) return true;
+	if (a instanceof Date && b instanceof Date) return Object.is(a.getTime(), b.getTime());
+	if (Array.isArray(a) && Array.isArray(b)) return a.length === b.length && a.every((item, index) => isDeepEqual(item, b[index]));
+	if (!isPlainObject(a) || !isPlainObject(b)) return false;
+	return [.../* @__PURE__ */ new Set([...Object.keys(a), ...Object.keys(b)])].every((key) => isDeepEqual(a[key], b[key]));
+}
+/**
+* Whether the value is an object literal or an object without prototype. Checks the prototype's
+* prototype instead of comparing it to `Object.prototype`, since objects from other realms (e.g.
+* iframes, or `structuredClone` in some test environments) have their own `Object.prototype`.
+*/
+function isPlainObject(value) {
+	if (value == null) return false;
+	const prototype = Object.getPrototypeOf(value);
+	return prototype === null || Object.getPrototypeOf(prototype) === null;
+}
+//#endregion
+//#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 { useConfirm, useDialog, useRunOrToast, useToast, useUnsavedChanges };

package/dist/plugins.d.ts

@@ -1,7 +1,8 @@
 import { Plugin, UserConfig } from "vite-plus";
 //#region src/plugins.d.ts
 /**
- * Vite plugin that compiles the components' styles with the library's font and Sass settings.
+ * Vite plugin that compiles the components' styles with the library's font and Sass settings, and
+ * loads the icon font with `font-display: swap`, so it doesn't block rendering while it loads.
  * Required: without it, the components lose the Unimed Slab font. Needs `sass-embedded`, a peer
  * dependency.
  *

package/dist/plugins.js

@@ -10,8 +10,13 @@ const vuetifyStylesheets = "/node_modules/vuetify/lib/";
 * Vite doesn't compile. The URL still serves the compiled stylesheet, which Vite loads separately
 */
 const uncompiledStylesheetQuery = /[?&](?:raw|url)\b/;
+/** Matches the ids of the icon font's stylesheet, with or without a query and Windows separators */
+const iconFontStylesheet = /[\\/]node_modules[\\/]@mdi[\\/]font[\\/]css[\\/]materialdesignicons\.css(?:\?|$)/;
+/** Start of the icon font's `@font-face` rule, the only one in its stylesheet */
+const iconFontFace = "@font-face {";
 /**
-* Vite plugin that compiles the components' styles with the library's font and Sass settings.
+* Vite plugin that compiles the components' styles with the library's font and Sass settings, and
+* loads the icon font with `font-display: swap`, so it doesn't block rendering while it loads.
 * Required: without it, the components lose the Unimed Slab font. Needs `sass-embedded`, a peer
 * dependency.
 *
@@ -55,6 +60,18 @@ function vitePluginUimed() {
 			compiler = void 0;
 			await (await current)?.dispose();
 		}
+	}, {
+		name: "uimed:icon-font",
+		enforce: "pre",
+		transform: {
+			filter: { id: {
+				include: iconFontStylesheet,
+				exclude: uncompiledStylesheetQuery
+			} },
+			handler(code) {
+				return code.replace(iconFontFace, `${iconFontFace} font-display: swap;`);
+			}
+		}
 	}];
 }
 /**

package/dist/styles/fonts/fonts.css

@@ -1,4 +1,5 @@
 @font-face {
   font-family: "Unimed Slab";
   src: url("./UnimedSlab-Regular.woff2");
+  font-display: swap;
 }

package/package.json

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