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

package/lib/utils/vModel.js

@@ -0,0 +1,224 @@
+/*
+ * ---------- 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,90 @@
+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/lib/utils/validation.js

@@ -0,0 +1,147 @@
+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/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,21 @@
+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

@@ -2,13 +2,17 @@
     "name": "@naptics/vue-collection",
     "author": "Timo Siegenthaler and Jonas Schoch",
     "description": "Vue Collection is a collection of styled and fully functional Vue components which can easily be integrated into our projects.",
-    "version": "1.0.0-beta.1",
-    "main": "./index.js",
+    "version": "1.0.0-beta.2",
+    "main": "./lib/index.js",
+    "files": [
+        "lib/"
+    ],
     "repository": {
         "type": "git",
         "url": "https://github.com/naptics/vue-collection"
     },
     "scripts": {
+        "prepack": "npm run build-lib",
         "dev": "vite",
         "lint": "eslint . --fix --ignore-pattern=.gitignore",
         "type-check": "run-p type-check-lib type-check-demo",

package/.github/workflows/build.yml

@@ -1,26 +0,0 @@
-name: Lint, Type-Check, Build & Test
-
-on: 
-  push: 
-    branches: 
-      - '**' 
-
-jobs:
-  build:
-    name: Lint, Type-Check, Build & Test
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout repository
-        uses: actions/checkout@v4
-      - name: Read .nvmrc
-        run: echo "NVMRC=$(cat .nvmrc)" >> $GITHUB_OUTPUT
-        id: nvm
-      - name: Setup node environment
-        uses: actions/setup-node@v4
-        with:
-          node-version: ${{ steps.nvm.outputs.NVMRC }}
-      - run: npm ci
-      - run: npm run lint
-      - run: npm run build-lib
-      - run: npm run build-demo
-      - run: npm run test

package/.github/workflows/deploy-demo.yml

@@ -1,46 +0,0 @@
-name: Deploy Demo App to Github Pages
-
-on:
-  push:
-    branches: 
-      - main
-    
-permissions:
-  contents: read
-  pages: write
-  id-token: write
-
-env:
-  VITE_BASE_PATH: vue-collection/
-
-jobs:
-  build:
-    name: Lint, Type-Check, Build & Test
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout repository
-        uses: actions/checkout@v4
-      - name: Setup Pages
-        uses: actions/configure-pages@v5
-      - name: Read .nvmrc
-        run: echo "NVMRC=$(cat .nvmrc)" >> $GITHUB_OUTPUT
-        id: nvm
-      - name: Setup node environment
-        uses: actions/setup-node@v4
-        with:
-          node-version: ${{ steps.nvm.outputs.NVMRC }}
-      - run: npm ci
-      - run: npm run lint
-      - run: npm run build-demo
-      - run: npm run test
-      - name: Upload demo as artifact
-        uses: actions/upload-pages-artifact@v3
-        with:
-          path: 'dist'
-  deploy:
-    name: Deploy Demo App To Github Pages
-    needs: build
-    runs-on: ubuntu-latest
-    steps:
-      - name: Deploy to GitHub Pages
-        uses: actions/deploy-pages@v4

package/.github/workflows/deploy-lib.yml

@@ -1,59 +0,0 @@
-name: Deploy Library to npm
-
-on:
-  push:
-    tags:
-      - v*
-
-jobs:
-  build:
-    name: Lint, Type-Check, Build & Test
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout repository
-        uses: actions/checkout@v4
-      - name: Read .nvmrc
-        run: echo "NVMRC=$(cat .nvmrc)" >> $GITHUB_OUTPUT
-        id: nvm
-      - name: Setup node environment
-        uses: actions/setup-node@v4
-        with:
-          node-version: ${{ steps.nvm.outputs.NVMRC }}
-      - run: npm ci
-      - run: npm run lint
-      - run: npm run build-lib
-      - run: npm run test
-      - name: Upload library as artifact
-        uses: actions/upload-artifact@v4
-        with:
-          name: vue-collection-lib
-          path: |
-            lib
-            .npmrc
-            package.json
-            README.md
-  deploy:
-    name: Deploy Library to npm
-    needs: build
-    runs-on: ubuntu-latest
-    permissions:
-      id-token: write  # Required for OIDC
-      contents: read
-    steps:
-      - name: Checkout repository
-        uses: actions/checkout@v4
-      - name: Read .nvmrc
-        run: echo "NVMRC=$(cat .nvmrc)" >> $GITHUB_OUTPUT
-        id: nvm
-      - name: Setup node environment
-        uses: actions/setup-node@v4
-        with:
-          node-version: ${{ steps.nvm.outputs.NVMRC }}
-          registry-url: https://registry.npmjs.org/
-      - name: Download library artifact
-        uses: actions/download-artifact@v4
-        with:
-          name: vue-collection-lib
-      - name: Prepare folder structure
-        run: mv ./lib/* .
-      - run: npm publish --access=public