@naptics/vue-collection 0.0.1

package/lib/utils/vModel.js

@@ -0,0 +1,215 @@
+/*
+ * ---------- VModel as Props ----------
+ */
+/**
+ * Creates props for a `v-model` of the given type.
+ * A `v-model` consits of a value-property and a update-function.
+ * @param propType The propType of the `v-model`.
+ * @returns An object containing the value-property and the update-function.
+ */
+export function vModelProps(propType) {
+    return {
+        /**
+         * The value of the component.
+         */
+        value: propType,
+        /**
+         * This will be called, when the value of the component has changed.
+         */
+        onUpdateValue: Function,
+    };
+}
+/**
+ * Creates props for a required `v-model` of the given type.
+ * @see {@link vModelProps}
+ */
+export function vModelRequiredProps(propType) {
+    return {
+        /**
+         * The value of the component.
+         */
+        value: {
+            type: propType,
+            required: true,
+        },
+        /**
+         * This will be called, when the value of the component has changed.
+         */
+        onUpdateValue: Function,
+    };
+}
+/**
+ * Creates props for a `v-model` of the given type with a default value.
+ * @see {@link vModelProps}
+ */
+export function vModelDefaultProps(propType, defaultValue) {
+    return {
+        /**
+         * The value of the component.
+         */
+        value: {
+            type: propType,
+            default: defaultValue,
+        },
+        /**
+         * This will be called, when the value of the component has changed.
+         */
+        onUpdateValue: Function,
+    };
+}
+/**
+ * Uses the given `ref` as a `v-model`, to create a two-way binding with the `ref`.
+ * @param ref The `ref` which should be used as the `v-model`.
+ * @returns An object of type {@link VModel}, which connects the `ref` to the `v-model`.
+ */
+export function vModelForRef(ref) {
+    return {
+        value: ref.value,
+        onUpdateValue: (newValue) => {
+            ref.value = newValue;
+        },
+    };
+}
+/**
+ * This creates a `v-model` for a property of an object. The property of the object is taken as the
+ * value of the `v-model`, the `onUpdate` function, is called every time when the property is updated
+ * with the whole object and its updated property.
+ * @param object The object which contains the relevant property.
+ * @param key The key of the property which should be used as the v-model.
+ * @param onUpdate The updater function which is called with the entire object when the property has changed.
+ * @returns An object containing of type {@link VModel}.
+ * @example
+ * ```tsx
+ * // inside setup function
+ * const customer = ref({ firstName: 'Hansi', lastName: 'Halunk' })
+ *
+ * // This input needs a v-model for the `firstName` property.
+ * return () => (
+ *     <NInput
+ *         name="First Name"
+ *         {...vModelForObjectProperty(customer.value, 'firstName', newVal => (customer.value = newValue))}
+ *     />
+ * )
+ * ```
+ */
+export function vModelForObjectProperty(object, key, onUpdate) {
+    return {
+        value: object[key],
+        onUpdateValue: (newValue) => {
+            onUpdate?.({ ...object, [key]: newValue });
+        },
+    };
+}
+/**
+ * This creates a `v-model` which operates on one property of a parent `v-model`. It takes the value of
+ * the property as the value of the `v-model` and calls the function `onUpdateValue` of the parent `v-model`
+ * whenever the property changes. This function can be seen as a kind of mapper for a `v-model`.
+ * @param vModel The parent `v-model`, which this function extracts a single property from.
+ * @param key The key of the relevant property.
+ * @returns An object of type {@link VModel}.
+ * @example
+ * ```tsx
+ * type Customer = { firstName: string, lastName: String }
+ *
+ * // inside setup function,
+ * // This vModel would normally be inside the props of a component e.g., `CustomerEditor`.
+ * const parentVModel = {
+ *     value: { firstName: 'Hansi', lastName: 'Halunk' },
+ *     onUpdateValue: (newValue: Customer) => {
+ *         // update something
+ *     }
+ * }
+ *
+ * // This input needs a v-model for the `firstName` property.
+ * return () => (
+ *     <NInput
+ *         name="First Name"
+ *         {...vModelForVModelProperty(parentVModel, 'firstName'))}
+ *      />
+ * )
+ * ```
+ */
+export function vModelForVModelProperty(vModel, key) {
+    return {
+        value: vModel.value[key],
+        onUpdateValue: (newValue) => {
+            vModel.onUpdateValue?.({ ...vModel.value, [key]: newValue });
+        },
+    };
+}
+/**
+ * This function does the same thing as {@link vModelForVModelProperty},
+ * but can be provided with a mapper function for the modified property.
+ * @see {@link vModelForVModelProperty}
+ * @example
+ * ```tsx
+ * type Customer = { firstName: string, lastName: String, type: 'admin' | 'user' }
+ *
+ * // inside setup function,
+ * // This vModel would normally be inside the props of a component e.g., `CustomerEditor`.
+ * const parentVModel = {
+ *     value: { firstName: 'Hansi', lastName: 'Halunk', type: 'user' },
+ *     onUpdateValue: (newValue: Customer) => {
+ *         // update something
+ *     }
+ * }
+ *
+ * // This input needs a v-model for the `type` property.
+ * // Unfortunately the NSelect input expects an `onUpdateValue` with a
+ * // parameter of type `string`, not type `admin | user`.
+ * // So we have to provide a mapper function from `string` to `admin | user`.
+ * // In this example, we just cast the value.
+ * return () => (
+ *     <NSelect
+ *         name="Type"
+ *         {...vModelForVModelPropertyMapType(parentVModel, 'type', newVal => newVal as 'admin' | 'user'))}
+ *      />
+ * )
+ * ```
+ */
+export function vModelForVModelPropertyMapType(vModel, key, mapType) {
+    return {
+        value: vModel.value[key],
+        onUpdateValue: (newValue) => {
+            vModel.onUpdateValue?.({ ...vModel.value, [key]: mapType(newValue) });
+        },
+    };
+}
+/**
+ * Creates an array of `v-models`, one for every element of an array. All changes in
+ * a `v-model` of any element, will call the `onUpdate` function, with the updated array.
+ * @param array The array to create `v-models` for.
+ * @param onUpdate The updater function, which is called whenever an element has changed.
+ * @returns An object of type {@link VModelForArray}.
+ * @example
+ * ```tsx
+ * // inside setup function
+ * const todos = ref([
+ *     'Create v-model helper functions.',
+ *     'Document them!'
+ * ])
+ *
+ * // For every todo, there should be an input to modifiy it.
+ * return () => (
+ *     <div>
+ *         {vModelsForArray(todos.value, newValue => (todos.value = newValue)).map(todoVModel => (
+ *            <NInput name="Todo" {...todoVModel} />
+ *         ))}
+ *     </div>
+ * )
+ * ```
+ */
+export function vModelsForArray(array, onUpdate) {
+    return array.map((entry, index) => ({
+        value: entry,
+        onUpdateValue: (entry) => {
+            const newArray = [...array];
+            newArray[index] = entry;
+            onUpdate?.(newArray);
+        },
+        remove: () => {
+            const newArray = [...array.slice(0, index), ...array.slice(index + 1)];
+            onUpdate?.(newArray);
+        },
+    }));
+}

package/lib/utils/validation.d.ts

@@ -0,0 +1,84 @@
+export type ValidationResultValid = {
+    isValid: true;
+    errorMessage?: undefined;
+};
+export type ValidationResultInvalid = {
+    isValid: false;
+    errorMessage: string;
+};
+export type InputValue = string | null | undefined;
+export type ValidationResult = ValidationResultValid | ValidationResultInvalid;
+/**
+ * A `ValidationRule` checks an input for a criteria and returns either
+ * a {@link ValidationResultValid} or a {@link ValidationResultInvalid}.
+ * A falsy input-value should always return a valid result to not interfere
+ * with the {@link required} rule.
+ */
+export type ValidationRule = (input: InputValue) => ValidationResult;
+export declare function validResult(): ValidationResultValid;
+export declare function invalidResult(ruleKey: string, params?: Record<string, unknown>): ValidationResultInvalid;
+/**
+ * Validates a given input with the specified rules.
+ * The rules are evaluated in the order they're in the array.
+ * The {@link ValidationResult} will either contain the errorMessage of the failed rule
+ * or a valid result if all rules passed.
+ * @param input the input to validate.
+ * @param rules the rules which should be vaildated, in the order of priority.
+ * @returns an object containing the result of the validation.
+ */
+export declare function validate(input: InputValue, rules: ValidationRule[]): ValidationResult;
+/**
+ * This rule expects the trimmed input-value to be truthy.
+ */
+export declare const required: ValidationRule;
+/**
+ * This rule expects the input to be an integer.
+ */
+export declare const integer: ValidationRule;
+/**
+ * This rule expects the input to be in the specified length range. An empty input
+ * will always be allowed by this rule to not interefere with the {@link required} rule.
+ * @param min The minimum length of the string.
+ * @param max The maximum length of the string.
+ */
+export declare function length(min: number | undefined, max: number | undefined): ValidationRule;
+/**
+ * This rule expects the input to be a number in the specified range.
+ * @param min the lower bound, if `undefined` there is no lower bound.
+ * @param max the upper bound, if `undefined` there is no upper bound.
+ */
+export declare function numberRange(min: number | undefined, max: number | undefined): ValidationRule;
+export declare const VALIDATION_FORMAT_EMAIL: RegExp;
+/**
+ * This rule expects the input-value to be a valid email adress matching {@link VALIDATION_FORMAT_EMAIL}.
+ */
+export declare const email: ValidationRule;
+export declare const VALIDATION_FORMAT_PASSWORD: RegExp;
+/**
+ * This rule expects the input-value to be a password matching {@link VALIDATION_FORMAT_PASSWORD}.
+ */
+export declare const password: ValidationRule;
+/**
+ * This rule expects the input-value to match another (input-) value.
+ * In difference to most other rules, this rule does not always return a valid result,
+ * when the input is falsy. The input is always required to match the other value.
+ * @param other the other value to match
+ */
+export declare function matches(other: string | null | undefined): ValidationRule;
+/**
+ * This rule expects the input-value to match one option in an array.
+ * @param options the options which the input can match
+ */
+export declare function option(options: string[]): ValidationRule;
+/**
+ * This rule expects the input-value to match the regex pattern
+ * @param pattern the pattern the input should match.
+ */
+export declare function regex(pattern: RegExp): ValidationRule;
+/**
+ * This rule can be used if the validation logic happens somwhere else.
+ * When `isValid = true` is passed, the function will return a valid result,
+ * otherwise it will return the invalid result with the passed `errorKey`.
+ * Like always, a falsy input is always valid to not interefere with the {@link required} rule.
+ */
+export declare function external(isValid: boolean, errorKey: string): ValidationRule;

package/lib/utils/validation.js

@@ -0,0 +1,163 @@
+import { trsl } from '../i18n';
+export function validResult() {
+    return { isValid: true };
+}
+export function invalidResult(ruleKey, params) {
+    return { isValid: false, errorMessage: trsl(`vue-collection.validation.rules.${ruleKey}`, params) };
+}
+/**
+ * Validates a given input with the specified rules.
+ * The rules are evaluated in the order they're in the array.
+ * The {@link ValidationResult} will either contain the errorMessage of the failed rule
+ * or a valid result if all rules passed.
+ * @param input the input to validate.
+ * @param rules the rules which should be vaildated, in the order of priority.
+ * @returns an object containing the result of the validation.
+ */
+export function validate(input, rules) {
+    for (const rule of rules) {
+        const validationResult = rule(input);
+        if (!validationResult.isValid)
+            return validationResult;
+    }
+    return validResult();
+}
+/*
+ * ---------- Validation Rules ----------
+ */
+/**
+ * This rule expects the trimmed input-value to be truthy.
+ */
+export const required = input => {
+    const trimmed = input?.trim();
+    if (trimmed)
+        return validResult();
+    else
+        return invalidResult('required');
+};
+/**
+ * This rule expects the input to be an integer.
+ */
+export const integer = input => {
+    if (!input || Number.isInteger(+input))
+        return validResult();
+    else
+        return invalidResult('integer');
+};
+/**
+ * This rule expects the input to be in the specified length range. An empty input
+ * will always be allowed by this rule to not interefere with the {@link required} rule.
+ * @param min The minimum length of the string.
+ * @param max The maximum length of the string.
+ */
+export function length(min, max) {
+    return input => {
+        if (!input)
+            return validResult();
+        if (min !== undefined && max !== undefined && !(min <= input.length && input.length <= max))
+            return invalidResult('length.min-max', { min, max });
+        else if (min !== undefined && !(min <= input.length))
+            return invalidResult('length.min', { min });
+        else if (max !== undefined && !(input.length <= max))
+            return invalidResult('length.max', { max });
+        return validResult();
+    };
+}
+/**
+ * This rule expects the input to be a number in the specified range.
+ * @param min the lower bound, if `undefined` there is no lower bound.
+ * @param max the upper bound, if `undefined` there is no upper bound.
+ */
+export function numberRange(min, max) {
+    return input => {
+        if (!input)
+            return validResult();
+        const parsed = Number.parseFloat(input);
+        if (Number.isNaN(parsed))
+            return invalidResult('number-range.nan');
+        if (min !== undefined && max !== undefined && !(min <= parsed && parsed <= max))
+            return invalidResult('number-range.min-max', { min, max });
+        else if (min !== undefined && !(min <= parsed))
+            return invalidResult('number-range.min', { min });
+        else if (max !== undefined && !(parsed <= max))
+            return invalidResult('number-range.max', { max });
+        return validResult();
+    };
+}
+export const VALIDATION_FORMAT_EMAIL = /^\w+([.-]?\w+)*@\w+([.-]?\w+)*(\.\w{2,3})+$/;
+/**
+ * This rule expects the input-value to be a valid email adress matching {@link VALIDATION_FORMAT_EMAIL}.
+ */
+export const email = input => {
+    if (!input || VALIDATION_FORMAT_EMAIL.test(input))
+        return validResult();
+    else
+        return invalidResult('email');
+};
+export const VALIDATION_FORMAT_PASSWORD = /^(?=.*[a-z])(?=.*[A-Z])(?=.*\d)(?=.*[#$^+\-=!*()@%&?]).{8,}$/;
+/**
+ * This rule expects the input-value to be a password matching {@link VALIDATION_FORMAT_PASSWORD}.
+ */
+export const password = input => {
+    if (!input || VALIDATION_FORMAT_PASSWORD.test(input))
+        return validResult();
+    else if (input.length < 8)
+        return invalidResult('password.to-short');
+    else if (!/[a-z]+/.test(input))
+        return invalidResult('password.no-lowercase');
+    else if (!/[A-Z]+/.test(input))
+        return invalidResult('password.no-uppercase');
+    else if (!/\d+/.test(input))
+        return invalidResult('password.no-digits');
+    else if (!/[#$^+\-=!*()@%&?]+/.test(input))
+        return invalidResult('password.no-special-chars');
+    else
+        return invalidResult('password.unknown');
+};
+/**
+ * This rule expects the input-value to match another (input-) value.
+ * In difference to most other rules, this rule does not always return a valid result,
+ * when the input is falsy. The input is always required to match the other value.
+ * @param other the other value to match
+ */
+export function matches(other) {
+    return input => {
+        if (input === other)
+            return validResult();
+        else
+            return invalidResult('matches');
+    };
+}
+/**
+ * This rule expects the input-value to match one option in an array.
+ * @param options the options which the input can match
+ */
+export function option(options) {
+    return input => {
+        if (!input || options.includes(input || ''))
+            return validResult();
+        else
+            return invalidResult('option');
+    };
+}
+/**
+ * This rule expects the input-value to match the regex pattern
+ * @param pattern the pattern the input should match.
+ */
+export function regex(pattern) {
+    return input => {
+        if (!input || pattern.test(input || ''))
+            return validResult();
+        else
+            return invalidResult('regex');
+    };
+}
+/**
+ * This rule can be used if the validation logic happens somwhere else.
+ * When `isValid = true` is passed, the function will return a valid result,
+ * otherwise it will return the invalid result with the passed `errorKey`.
+ * Like always, a falsy input is always valid to not interefere with the {@link required} rule.
+ */
+export function external(isValid, errorKey) {
+    return input => (!input || isValid ? validResult() : invalidResult(errorKey));
+}

package/lib/utils/vue.d.ts

@@ -0,0 +1,13 @@
+import { type Ref, type ComputedRef } from 'vue';
+/**
+ * Creates a watcher on the updater function, which sets the value of the ref on every change.
+ * @param ref the ref to update
+ * @param updater the updater funtion which provides the updates
+ */
+export declare function updateWith<T>(ref: Ref<T>, updater: () => T): void;
+/**
+ * Conveience function to create a watcher for a ref
+ * @param ref the ref to watch
+ * @param onChange the function, which is executed on change of a value
+ */
+export declare function watchRef<T>(ref: Ref<T> | ComputedRef<T>, onChange: (newValue: T) => void): void;

package/lib/utils/vue.js

@@ -0,0 +1,19 @@
+import { watch } from 'vue';
+/**
+ * Creates a watcher on the updater function, which sets the value of the ref on every change.
+ * @param ref the ref to update
+ * @param updater the updater funtion which provides the updates
+ */
+export function updateWith(ref, updater) {
+    watch(updater, newValue => {
+        ref.value = newValue;
+    }, { immediate: true });
+}
+/**
+ * Conveience function to create a watcher for a ref
+ * @param ref the ref to watch
+ * @param onChange the function, which is executed on change of a value
+ */
+export function watchRef(ref, onChange) {
+    watch(() => ref.value, onChange);
+}

package/package.json

@@ -0,0 +1,56 @@
+{
+    "name": "@naptics/vue-collection",
+    "version": "0.0.1",
+    "main": "./lib/index.js",
+    "files": [
+        "lib"
+    ],
+    "scripts": {
+        "dev": "vite",
+        "lint": "eslint . --ext .vue,.js,.jsx,.cjs,.mjs,.ts,.tsx,.cts,.mts --fix --ignore-path .gitignore",
+        "type-check": "run-p type-check-lib type-check-demo",
+        "type-check-demo": "vue-tsc --noEmit -p tsconfig.demo.json --composite false",
+        "type-check-lib": "vue-tsc --noEmit -p tsconfig.lib.json --composite false",
+        "test": "vitest --environment jsdom",
+        "build-demo": "run-p type-check-demo build-only-demo",
+        "build-lib": "run-p type-check-lib build-only-lib",
+        "build-only-demo": "vite build",
+        "build-only-lib": "rm -rf ./lib && tsc --project tsconfig.lib.json && mv ./lib/src/lib/* ./lib && rm -rf ./lib/src && rm ./lib/tsconfig.lib.tsbuildinfo && cp ./src/lib/components/*.css ./lib/components"
+    },
+    "dependencies": {
+        "@headlessui/vue": "^1.7.10",
+        "@popperjs/core": "^2.11.6",
+        "awesome-phonenumber": "^5.1.0"
+    },
+    "peerDependencies": {
+        "@heroicons/vue": "^2.0.16",
+        "vue": "^3.2.36",
+        "vue-i18n": "^9.2.2"
+    },
+    "devDependencies": {
+        "@intlify/unplugin-vue-i18n": "^0.8.2",
+        "@rushstack/eslint-patch": "^1.2.0",
+        "@tailwindcss/forms": "^0.5.3",
+        "@types/jsdom": "^21.1.0",
+        "@types/node": "^18.14.0",
+        "@vitejs/plugin-vue": "^4.0.0",
+        "@vitejs/plugin-vue-jsx": "^3.0.0",
+        "@vue/eslint-config-prettier": "^7.1.0",
+        "@vue/eslint-config-typescript": "^11.0.2",
+        "@vue/test-utils": "^2.3.0",
+        "@vue/tsconfig": "^0.1.3",
+        "autoprefixer": "^10.4.13",
+        "eslint": "^8.34.0",
+        "eslint-plugin-vue": "^9.9.0",
+        "jsdom": "^21.1.0",
+        "npm-run-all": "^4.1.5",
+        "postcss": "^8.4.21",
+        "prettier": "^2.8.4",
+        "tailwindcss": "^3.2.7",
+        "typescript": "^4.9.5",
+        "vite": "^4.1.3",
+        "vitest": "^0.28.5",
+        "vue-router": "^4.1.6",
+        "vue-tsc": "^1.1.5"
+    }
+}