@nexdom/uimed-vue 2.0.0-beta.31 → 2.0.0-beta.33

package/AGENTS.md

@@ -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__/`. Generic helpers that any TypeScript project could use (e.g. `isDeepEqual`) belong in `@nexdom/shared` instead.
 - 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.js

@@ -333,7 +333,11 @@ var app_bar_default = /* @__PURE__ */ defineComponent({
 						class: "py-2 ml-5 mr-n3",
 						cover: ""
 					}, null, 8, ["src"])) : createCommentVNode("v-if", true),
-					props.title ? (openBlock(), createBlock(unref(VAppBarTitle), { key: 2 }, {
+					props.title ? (openBlock(), createBlock(unref(VAppBarTitle), {
+						key: 2,
+						role: "heading",
+						"aria-level": "1"
+					}, {
 						default: withCtx(() => [createTextVNode(toDisplayString(props.title), 1)]),
 						_: 1
 					})) : createCommentVNode("v-if", true)

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,7 @@
 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 { isDeepEqual } from "@nexdom/shared/utils";
+import { onBeforeRouteLeave } from "vue-router";
 //#region src/composables/dialogs/use-run-or-toast.ts
 const { toast } = useToast();
 /**
@@ -114,4 +116,87 @@ function useConfirm() {
 	};
 }
 //#endregion
-export { useConfirm, useDialog, useRunOrToast, useToast };
+//#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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nexdom/uimed-vue",
-  "version": "2.0.0-beta.31",
+  "version": "2.0.0-beta.33",
   "description": "A ui framework for NEXDOM applications.",
   "keywords": [
     "lib",
@@ -55,7 +55,7 @@
     "@commitlint/cli": "^21.2.1",
     "@commitlint/config-conventional": "^21.2.0",
     "@mdi/font": "^7.4.47",
-    "@nexdom/shared": "^2.1.1",
+    "@nexdom/shared": "^2.3.0",
     "@playwright/test": "^1.62.1",
     "@sonar/scan": "^5.0.0",
     "@stryker-mutator/core": "^10.0.0",
@@ -87,7 +87,7 @@
   },
   "peerDependencies": {
     "@mdi/font": "^7.4.47",
-    "@nexdom/shared": "^2.1.1",
+    "@nexdom/shared": "^2.3.0",
     "resize-observer-polyfill": "^1.5.1",
     "sass-embedded": "^1.103.1",
     "vite-plus": "^1.0.0",