@fkui/logic 6.14.0 → 6.16.0

package/LICENSE.md

@@ -1,4 +1,4 @@
-Copyright 2021 Försäkringskassan
+Copyright 2025 Försäkringskassan
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
 

package/lib/cjs/index.js

@@ -1,12 +1,5 @@
 'use strict';
 
-/**
- * @public
- */
-const configLogic = {
-    production: true,
-};
-
 /**
  * Determine if a value is empty.
  *
@@ -41,6 +34,106 @@ function isString(value) {
     return typeof value === "string" || value instanceof String;
 }
 
+/**
+ * An error indicating that a mandatory value is not set.
+ *
+ * @public
+ */
+class MissingValueError extends Error {
+    constructor(message) {
+        super(message);
+        Object.setPrototypeOf(this, MissingValueError.prototype);
+    }
+}
+/**
+ * Assert that a value is set and throw a {@link MissingValueError} if it is not,
+ * i.e., both null and undefined values will throw an error. This can be nice to
+ * use when transforming data between view model and rest api model.
+ *
+ * @public
+ * @param value - the value asserted to be set.
+ * @param message - an optional exception message to use if the check fails.
+ * @returns the value unambiguously defined.
+ * @throws {@link MissingValueError} if value is not set.
+ */
+function ensureSet(value, message = "") {
+    if (!isSet(value)) {
+        throw new MissingValueError(message);
+    }
+    return value;
+}
+
+/**
+ * [Assertion function][ts-handbook] to assert that a nullable Vue ref holds a
+ * non-null value. Typically used with template refs but any nullable ref can be
+ * used.
+ *
+ * Throws {@link MissingValueError} if the ref holds `null` or `undefined`, or
+ * the ref itself is `null` or `undefined`.
+ *
+ * [ts-handbook]: https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-7.html#assertion-functions
+ *
+ *  @example
+ *
+ * ```ts
+ * const element = useTemplateRef("my-template-ref");
+ * //    ^?   Readonly<ShallowRef<HTMLElement | null>>
+ *
+ * assertRef(element);
+ *
+ * // element is now guaranteed to be a HTMLElement ref
+ * ```
+ *
+ * @public
+ * @since v6.15.0
+ * @param ref - the value asserted to be a ref.
+ * @param message - an optional exception message to use if the check fails.
+ * @throws {@link MissingValueError} if value is not set.
+ */
+function assertRef(ref, message = "Expected ref to have a non-null value, but it did not") {
+    if (!isSet(ref?.value)) {
+        throw new MissingValueError(message);
+    }
+}
+
+/**
+ * [Assertion function][ts-handbook] to assert that a value is set.
+ * Any value that is not null or undefined is considered set including falsy values such as 0 or "".
+ *
+ * Throws {@link MissingValueError} if value is not set.
+ *
+ * [ts-handbook]: https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-7.html#assertion-functions
+ *
+ *  @example
+ *
+ * ```ts
+ * const value = getValue();
+ * //    ^?   string | null
+ *
+ * assertSet(value);
+ *
+ * // value is now guaranteed to be non-null
+ * ```
+ *
+ * @public
+ * @since v6.15.0
+ * @param value - the value asserted to be set.
+ * @param message - an optional exception message to use if the check fails.
+ * @throws {@link MissingValueError} if value is not set.
+ */
+function assertSet(value, message = "Expected value to be set, but it was not") {
+    if (!isSet(value)) {
+        throw new MissingValueError(message);
+    }
+}
+
+/**
+ * @public
+ */
+const configLogic = {
+    production: true,
+};
+
 /**
  * Implementation of Object.fromEntries() until we run a recent enough version
  * of NodeJS.
@@ -1987,35 +2080,6 @@ function deepClone(value) {
     return cloneDeep(value);
 }
 
-/**
- * An error indicating that a mandatory value is not set.
- *
- * @public
- */
-class MissingValueError extends Error {
-    constructor(message) {
-        super(message);
-        Object.setPrototypeOf(this, MissingValueError.prototype);
-    }
-}
-/**
- * Assert that a value is set and throw a {@link MissingValueError} if it is not,
- * i.e., both null and undefined values will throw an error. This can be nice to
- * use when transforming data between view model and rest api model.
- *
- * @public
- * @param value - the value asserted to be set.
- * @param message - an optional exception message to use if the check fails.
- * @returns the value unambiguously defined.
- * @throws {@link MissingValueError} if value is not set.
- */
-function ensureSet(value, message = "") {
-    if (!isSet(value)) {
-        throw new MissingValueError(message);
-    }
-    return value;
-}
-
 /**
  * Takes an optionally nested textobject structure and convert to a flat
  * structure. Nested keys are joined with a dot ".". Deep nesting is supported.
@@ -4043,7 +4107,7 @@ class ValidationServiceImpl {
     elementValidatorsReferences = {};
     validationErrorMessages = {};
     constructor() {
-        this.addValidationErrorMessages(getErrorMessages());
+        this.setErrorMessages(getErrorMessages());
     }
     getElementsAndValidators() {
         return this.elementValidatorsReferences;
@@ -4052,10 +4116,18 @@ class ValidationServiceImpl {
         return Object.values(this.validationStates).some((item) => item.touched === true);
     }
     addValidationErrorMessages(validationErrorMessages) {
-        this.validationErrorMessages = {
-            ...this.validationErrorMessages,
-            ...validationErrorMessages,
-        };
+        this.setErrorMessages(validationErrorMessages);
+    }
+    setErrorMessages(messages, options = {}) {
+        const { clear = false } = options;
+        if (clear) {
+            this.clearErrorMessages();
+        }
+        const current = this.validationErrorMessages;
+        this.validationErrorMessages = { ...current, ...messages };
+    }
+    clearErrorMessages() {
+        this.validationErrorMessages = {};
     }
     registerValidator(validator) {
         const { name } = validator;
@@ -5143,6 +5215,8 @@ exports.ValidationErrorMessageBuilder = ValidationErrorMessageBuilder;
 exports.ValidationService = ValidationService;
 exports.addFocusListener = addFocusListener;
 exports.alertScreenReader = alertScreenReader;
+exports.assertRef = assertRef;
+exports.assertSet = assertSet;
 exports.availableValidators = availableValidators;
 exports.configLogic = configLogic;
 exports.debounce = debounce;

package/lib/esm/index.js

@@ -1,10 +1,3 @@
-/**
- * @public
- */
-const configLogic = {
-    production: true,
-};
-
 /**
  * Determine if a value is empty.
  *
@@ -39,6 +32,106 @@ function isString(value) {
     return typeof value === "string" || value instanceof String;
 }
 
+/**
+ * An error indicating that a mandatory value is not set.
+ *
+ * @public
+ */
+class MissingValueError extends Error {
+    constructor(message) {
+        super(message);
+        Object.setPrototypeOf(this, MissingValueError.prototype);
+    }
+}
+/**
+ * Assert that a value is set and throw a {@link MissingValueError} if it is not,
+ * i.e., both null and undefined values will throw an error. This can be nice to
+ * use when transforming data between view model and rest api model.
+ *
+ * @public
+ * @param value - the value asserted to be set.
+ * @param message - an optional exception message to use if the check fails.
+ * @returns the value unambiguously defined.
+ * @throws {@link MissingValueError} if value is not set.
+ */
+function ensureSet(value, message = "") {
+    if (!isSet(value)) {
+        throw new MissingValueError(message);
+    }
+    return value;
+}
+
+/**
+ * [Assertion function][ts-handbook] to assert that a nullable Vue ref holds a
+ * non-null value. Typically used with template refs but any nullable ref can be
+ * used.
+ *
+ * Throws {@link MissingValueError} if the ref holds `null` or `undefined`, or
+ * the ref itself is `null` or `undefined`.
+ *
+ * [ts-handbook]: https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-7.html#assertion-functions
+ *
+ *  @example
+ *
+ * ```ts
+ * const element = useTemplateRef("my-template-ref");
+ * //    ^?   Readonly<ShallowRef<HTMLElement | null>>
+ *
+ * assertRef(element);
+ *
+ * // element is now guaranteed to be a HTMLElement ref
+ * ```
+ *
+ * @public
+ * @since v6.15.0
+ * @param ref - the value asserted to be a ref.
+ * @param message - an optional exception message to use if the check fails.
+ * @throws {@link MissingValueError} if value is not set.
+ */
+function assertRef(ref, message = "Expected ref to have a non-null value, but it did not") {
+    if (!isSet(ref?.value)) {
+        throw new MissingValueError(message);
+    }
+}
+
+/**
+ * [Assertion function][ts-handbook] to assert that a value is set.
+ * Any value that is not null or undefined is considered set including falsy values such as 0 or "".
+ *
+ * Throws {@link MissingValueError} if value is not set.
+ *
+ * [ts-handbook]: https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-7.html#assertion-functions
+ *
+ *  @example
+ *
+ * ```ts
+ * const value = getValue();
+ * //    ^?   string | null
+ *
+ * assertSet(value);
+ *
+ * // value is now guaranteed to be non-null
+ * ```
+ *
+ * @public
+ * @since v6.15.0
+ * @param value - the value asserted to be set.
+ * @param message - an optional exception message to use if the check fails.
+ * @throws {@link MissingValueError} if value is not set.
+ */
+function assertSet(value, message = "Expected value to be set, but it was not") {
+    if (!isSet(value)) {
+        throw new MissingValueError(message);
+    }
+}
+
+/**
+ * @public
+ */
+const configLogic = {
+    production: true,
+};
+
 /**
  * Implementation of Object.fromEntries() until we run a recent enough version
  * of NodeJS.
@@ -1985,35 +2078,6 @@ function deepClone(value) {
     return cloneDeep(value);
 }
 
-/**
- * An error indicating that a mandatory value is not set.
- *
- * @public
- */
-class MissingValueError extends Error {
-    constructor(message) {
-        super(message);
-        Object.setPrototypeOf(this, MissingValueError.prototype);
-    }
-}
-/**
- * Assert that a value is set and throw a {@link MissingValueError} if it is not,
- * i.e., both null and undefined values will throw an error. This can be nice to
- * use when transforming data between view model and rest api model.
- *
- * @public
- * @param value - the value asserted to be set.
- * @param message - an optional exception message to use if the check fails.
- * @returns the value unambiguously defined.
- * @throws {@link MissingValueError} if value is not set.
- */
-function ensureSet(value, message = "") {
-    if (!isSet(value)) {
-        throw new MissingValueError(message);
-    }
-    return value;
-}
-
 /**
  * Takes an optionally nested textobject structure and convert to a flat
  * structure. Nested keys are joined with a dot ".". Deep nesting is supported.
@@ -4041,7 +4105,7 @@ class ValidationServiceImpl {
     elementValidatorsReferences = {};
     validationErrorMessages = {};
     constructor() {
-        this.addValidationErrorMessages(getErrorMessages());
+        this.setErrorMessages(getErrorMessages());
     }
     getElementsAndValidators() {
         return this.elementValidatorsReferences;
@@ -4050,10 +4114,18 @@ class ValidationServiceImpl {
         return Object.values(this.validationStates).some((item) => item.touched === true);
     }
     addValidationErrorMessages(validationErrorMessages) {
-        this.validationErrorMessages = {
-            ...this.validationErrorMessages,
-            ...validationErrorMessages,
-        };
+        this.setErrorMessages(validationErrorMessages);
+    }
+    setErrorMessages(messages, options = {}) {
+        const { clear = false } = options;
+        if (clear) {
+            this.clearErrorMessages();
+        }
+        const current = this.validationErrorMessages;
+        this.validationErrorMessages = { ...current, ...messages };
+    }
+    clearErrorMessages() {
+        this.validationErrorMessages = {};
     }
     registerValidator(validator) {
         const { name } = validator;
@@ -5129,5 +5201,5 @@ if (typeof document !== "undefined") {
     createScreenReaderWrapper({ assertive: false });
 }
 
-export { DecoratedError, index as DomUtils, ElementIdService, MissingValueError, PersistenceService, SCREEN_READER_DELAY, SimplePersistenceService, TranslationService, ValidationErrorMessageBuilder, ValidationService, addFocusListener, alertScreenReader, availableValidators, configLogic, debounce, deepClone, deleteCookie, documentOrderComparator, ensureSet, findCookie, findTabbableElements, flatten, focus, focusFirst, focusLast, formatClearingNumberForBackend, formatNumber, formatPercent, formatPersonnummer, formatPersonnummerToDate, formatPostalCode, getErrorMessages, handleTab, isEmpty, isFocusable, isInvalidDatesConfig, isInvalidWeekdaysConfig, isRadiobuttonOrCheckbox, isSet, isString, isTabbable, isValidatableFormElement, isValidatableHTMLElement, isVisible, isVisibleInViewport, normalizeDateFormat, parseBankAccountNumber, parseBankgiro, parseClearingNumber, parseDate, parseNumber, parseOrganisationsnummer, parsePercent, parsePersonnummer, parsePersonnummerLuhn, parsePlusgiro, parsePostalCode, popFocus, pushFocus, removeFocusListener, restoreFocus, saveFocus, scrollTo, setCookie, stripNull, stripWhitespace, testLuhnChecksum, validChecksum, validLimit, waitForScreenReader };
+export { DecoratedError, index as DomUtils, ElementIdService, MissingValueError, PersistenceService, SCREEN_READER_DELAY, SimplePersistenceService, TranslationService, ValidationErrorMessageBuilder, ValidationService, addFocusListener, alertScreenReader, assertRef, assertSet, availableValidators, configLogic, debounce, deepClone, deleteCookie, documentOrderComparator, ensureSet, findCookie, findTabbableElements, flatten, focus, focusFirst, focusLast, formatClearingNumberForBackend, formatNumber, formatPercent, formatPersonnummer, formatPersonnummerToDate, formatPostalCode, getErrorMessages, handleTab, isEmpty, isFocusable, isInvalidDatesConfig, isInvalidWeekdaysConfig, isRadiobuttonOrCheckbox, isSet, isString, isTabbable, isValidatableFormElement, isValidatableHTMLElement, isVisible, isVisibleInViewport, normalizeDateFormat, parseBankAccountNumber, parseBankgiro, parseClearingNumber, parseDate, parseNumber, parseOrganisationsnummer, parsePercent, parsePersonnummer, parsePersonnummerLuhn, parsePlusgiro, parsePostalCode, popFocus, pushFocus, removeFocusListener, restoreFocus, saveFocus, scrollTo, setCookie, stripNull, stripWhitespace, testLuhnChecksum, validChecksum, validLimit, waitForScreenReader };
 //# sourceMappingURL=index.js.map