@naptics/vue-collection 0.3.1 → 1.0.0-beta.1

package/utils/vModel.d.ts

@@ -1,182 +0,0 @@
-import type { PropType, Ref } from 'vue';
-import type { AnyObject } from './utils';
-/**
- * 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 declare function vModelProps<T>(propType: PropType<T>): {
-    /**
-     * The value of the component.
-     */
-    readonly value: PropType<T>;
-    /**
-     * This will be called, when the value of the component has changed.
-     */
-    readonly onUpdateValue: PropType<(newValue: T) => void>;
-};
-/**
- * Creates props for a required `v-model` of the given type.
- * @see {@link vModelProps}
- */
-export declare function vModelRequiredProps<T>(propType: PropType<T>): {
-    /**
-     * The value of the component.
-     */
-    readonly value: {
-        readonly type: PropType<T>;
-        readonly required: true;
-    };
-    /**
-     * This will be called, when the value of the component has changed.
-     */
-    readonly onUpdateValue: PropType<(newValue: T) => void>;
-};
-/**
- * Creates props for a `v-model` of the given type with a default value.
- * @see {@link vModelProps}
- */
-export declare function vModelDefaultProps<T>(propType: PropType<T>, defaultValue: () => T): {
-    /**
-     * The value of the component.
-     */
-    readonly value: {
-        readonly type: PropType<T>;
-        readonly default: () => T;
-    };
-    /**
-     * This will be called, when the value of the component has changed.
-     */
-    readonly onUpdateValue: PropType<(newValue: T) => void>;
-};
-/**
- * The `VModel` type contains a value and an optional update-function.
- * This object is passed to a component to create a two-way binding.
- */
-export type VModel<T, U = T> = {
-    value: T;
-    onUpdateValue?: (newValue: U) => void;
-};
-/**
- * The `VModelForArray` contains the normal `VModel` properties,
- * but aditionally a function, which removes the value from the array.
- */
-export type VModelForArray<T, U = T> = VModel<T, U> & {
-    remove(): void;
-};
-/**
- * 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 declare function vModelForRef<T>(ref: Ref<T>): VModel<T>;
-/**
- * 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 declare function vModelForObjectProperty<T extends AnyObject, K extends keyof T>(object: T, key: K, onUpdate?: (newValue: T) => void): VModel<T[K]>;
-/**
- * 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 declare function vModelForVModelProperty<Model extends VModel<ModelValue>, Key extends keyof ModelValue, ModelValue extends AnyObject = Model['value']>(vModel: Model, key: Key): VModel<ModelValue[Key]>;
-/**
- * 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 declare function vModelForVModelPropertyMapType<Model extends VModel<ModelValue>, Key extends keyof ModelValue, UpdateValue, ModelValue extends AnyObject = Model['value']>(vModel: Model, key: Key, mapType: (value: UpdateValue) => ModelValue[Key]): VModel<ModelValue[Key], UpdateValue>;
-/**
- * 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 declare function vModelsForArray<T>(array: T[], onUpdate?: (newValue: T[]) => void): VModelForArray<T>[];

package/utils/vModel.js

@@ -1,224 +0,0 @@
-/*
- * ---------- 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/utils/validation.d.ts

@@ -1,90 +0,0 @@
-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;
-/**
- * Creates a valid result.
- */
-export declare function validResult(): ValidationResultValid;
-/**
- * Creates an invalid result with the provided error message.
- */
-export declare function invalidResult(errorMessage: string): 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 somewhere 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, errorMessage: string): ValidationRule;

package/utils/validation.js

@@ -1,147 +0,0 @@
-import { trsl } from '../i18n';
-/**
- * Creates a valid result.
- */
-export function validResult() {
-  return {
-    isValid: true
-  };
-}
-/**
- * Creates an invalid result with the provided error message.
- */
-export function invalidResult(errorMessage) {
-  return {
-    isValid: false,
-    errorMessage
-  };
-}
-const TRANSLATION_KEY_BASE = 'vue-collection.validation.rules';
-function invalidResultInternal(key, params) {
-  return invalidResult(trsl(`${TRANSLATION_KEY_BASE}.${key}`, 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 invalidResultInternal('required');
-};
-/**
- * This rule expects the input to be an integer.
- */
-export const integer = input => {
-  if (!input || Number.isInteger(+input)) return validResult();else return invalidResultInternal('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 invalidResultInternal('length.min-max', {
-      min,
-      max
-    });else if (min !== undefined && !(min <= input.length)) return invalidResultInternal('length.min', {
-      min
-    });else if (max !== undefined && !(input.length <= max)) return invalidResultInternal('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 invalidResultInternal('number-range.nan');
-    if (min !== undefined && max !== undefined && !(min <= parsed && parsed <= max)) return invalidResultInternal('number-range.min-max', {
-      min,
-      max
-    });else if (min !== undefined && !(min <= parsed)) return invalidResultInternal('number-range.min', {
-      min
-    });else if (max !== undefined && !(parsed <= max)) return invalidResultInternal('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 invalidResultInternal('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 invalidResultInternal('password.to-short');else if (!/[a-z]+/.test(input)) return invalidResultInternal('password.no-lowercase');else if (!/[A-Z]+/.test(input)) return invalidResultInternal('password.no-uppercase');else if (!/\d+/.test(input)) return invalidResultInternal('password.no-digits');else if (!/[#$^+\-=!*()@%&?]+/.test(input)) return invalidResultInternal('password.no-special-chars');else return invalidResultInternal('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 invalidResultInternal('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 invalidResultInternal('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 invalidResultInternal('regex');
-  };
-}
-/**
- * This rule can be used if the validation logic happens somewhere 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, errorMessage) {
-  return input => !input || isValid ? validResult() : invalidResult(errorMessage);
-}

package/utils/vue.d.ts

@@ -1,13 +0,0 @@
-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/utils/vue.js

@@ -1,21 +0,0 @@
-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);
-}