@naptics/vue-collection 0.0.2 → 0.0.3

package/README.md

@@ -2,11 +2,13 @@
 
 Vue Collection is a collection of styled and fully functional Vue components which can easily be integrated into our projects.
 
-## Showroom 🎆
+## Demo Page 🎆
 
-You can take a look at all components on [Gitlab Pages](https://naptx.gitlab.io/libraries/vue-collection/).
+You can take a look at all components on [GitHub Pages](https://naptics.github.io/vue-collection/).
 
-## Integrate Vue Collection into a new project 🔨
+## Project Setup 🚧
+
+This section shows how to create a new Vue project with the recommended tech-stack to be ready to install Vue Collection afterwards.
 
 1. Create a new vue-project with `npm init vue@latest`. Add at least typescript, jsx, vue-router, eslint and prettier.
 2. Remove boilerplate code.
@@ -14,14 +16,116 @@ You can take a look at all components on [Gitlab Pages](https://naptx.gitlab.io/
     - `npm install -D tailwindcss postcss autoprefixer`
     - `npx tailwindcss init`
     - ... follow the further instructions
-    - When creating the App.css add contents of this repo's `App.css`
-4. Add tailwind forms with `npm install -D @tailwindcss/forms`
-5. Copy the tailwind configuration `tailwind.config.js` to your project.
-6. Add other dependencies with `npm install @headlessui/vue @heroicons/vue vue-i18n awesome-phonenumber @popperjs/core`
-7. Copy files from `.vscode` to your project. Remove `.vscode/settings.json` file from `.gitignore`. Copy `.prettierrc` to your project.
-8. Make sure typescript config is correct. Double check with this repo.
-9. Copy the contents of `src/components/base` (without the tests), `src/i18n` and `src/utils/vue-collection` to your project.
-10. Create your `App.tsx` file (you probably deleted earlier) and add a router view to the app. Link the `App.css` to it. Then you're ready to add a `HomeView` and link it to the router. Make sure to always use the `createView` and `createComponent` functions defined in the `src/utils/vue` file.
-11. Close your project and reopen it again. Now all weird warnings should go away.
-12. You're ready to go: Run your app with `npm run dev`.
-13. Don't forget to configure primary, secondary and default color in `tailwind.config.js`. Also choose which classes are white-listed.
+4. Add tailwind forms with `npm install -D @tailwindcss/forms`.
+5. Add other dependencies with `npm install @heroicons/vue vue-i18n`
+6. Copy files from `.vscode` to your project. Remove `.vscode/settings.json` file from `.gitignore`. Copy `.prettierrc` to your project.
+7. Make sure typescript config is correct. Double check with this repo.
+
+## Installation Guide 🔨
+
+These are the steps to add Vue Collection to an existing project. You may have to go through the steps of `Project Setup` and check if you have the neccesary (peer-)dependencies installed.
+
+1. Go to [npmjs.com](https://npmjs.com), sign in with naptics and create a new read-only classic access token.
+2. Save your access token under `~/.npmrc` with the following content, replacing `YOUR_TOKEN` with the access token.
+
+```
+//registry.npmjs.org/:_authToken=YOUR_TOKEN
+```
+
+3. Install Vue Collection with `npm i @naptics/vue-collection`.
+4. Add tailwind config -> See below
+5. Register i18n provider -> See below
+
+## Tailwind Config
+
+With this tailwind config file, Vue Collection works as expected. Feel free to change the `default`, `primary` and `secondary` colors and add whatever is needed in your project.
+
+```js
+// tailwind.config.js
+
+/* eslint-disable no-undef */
+const colors = require('tailwindcss/colors')
+
+const unresolvedConfig = require('tailwindcss/defaultConfig')
+const resolveConfig = require('tailwindcss/resolveConfig')
+const config = resolveConfig(unresolvedConfig)
+
+const allShades = '50|100|200|300|400|500|600|700|800|900'
+const usedColors = 'default|primary|secondary|green|red|yellow|blue'
+const smallSizes = '1|2|3|4|5|6|7|8|9|10|11|12|14|16|18|20'
+
+/** @type {import('tailwindcss').Config} */
+module.exports = {
+    content: ['./src/**/*.{tsx,ts}', './node_modules/@naptics/vue-collection/**/*.{jsx,js}'],
+    safelist: [
+        {
+            pattern: new RegExp(`^(bg|text)-(${usedColors})-(${allShades})$`),
+            variants: ['hover'],
+        },
+        {
+            pattern: new RegExp(`^ring-(${usedColors})-(${allShades})$`),
+            variants: ['focus-visible'],
+        },
+        {
+            pattern: new RegExp(`^(w|h)-(${smallSizes})$`),
+        },
+    ],
+    theme: {
+        extend: {
+            colors: {
+                default: colors.slate,
+                primary: colors.violet,
+                secondary: colors.fuchsia,
+            },
+            minHeight: config.theme.spacing,
+        },
+    },
+    plugins: [require('@tailwindcss/forms')],
+}
+```
+
+## Register i18n Provider
+
+These are two sample files, how the i18n provider can be registered by using `vue-i18n`. The translation files of Vue Collection have to be added to the i18n provider in order for the Vue Collection components to work properly.
+
+```ts
+// src/i18n/index.ts
+
+import en from './en'
+import de from './de'
+import { createI18n } from 'vue-i18n'
+import { registerTranslationProvider } from '@naptics/vue-collection/i18n'
+
+const i18n = createI18n({
+    legacy: false,
+    locale: 'de',
+    messages: {
+        en,
+        de,
+    },
+})
+
+registerTranslationProvider({
+    trsl(key, params) {
+        return i18n.global.t(key, params == null ? {} : params)
+    },
+    trslc(key, count, params) {
+        const newCount = count ?? 0
+        const newParams = { n: newCount, ...params }
+        return i18n.global.t(key, newParams, { plural: newCount })
+    },
+})
+```
+
+```ts
+// src/i18n/de.ts
+
+import vueCollection from '@naptics/vue-collection/i18n/de/vue-collection.json'
+
+const de = {
+    ['vue-collection']: vueCollection,
+    // other translation files
+}
+
+export default de
+```

package/components/NInputPhone.d.ts

@@ -140,10 +140,10 @@ declare const _default: import("vue").DefineComponent<{
     tooltipMaxWidth: import("../utils/tailwind").TWMaxWidth;
     disabled: boolean;
     error: boolean;
-    rules: import("../utils/validation").ValidationRule | import("../utils/validation").ValidationRule[];
     autocomplete: string;
     hideLabel: boolean;
     optional: boolean;
+    rules: import("../utils/validation").ValidationRule | import("../utils/validation").ValidationRule[];
     hideErrorMessage: boolean;
     disableBlurValidation: boolean;
 }>;

package/components/NInputPhone.jsx

@@ -2,6 +2,7 @@ import { createComponent, createProps } from '../utils/component';
 import { external } from '../utils/validation';
 import { computed, Suspense } from 'vue';
 import NValInput, { nValInputProps } from './NValInput';
+import { trsl } from '../i18n';
 export const nInputPhoneProps = createProps(nValInputProps);
 /**
  * The `NInputPhone` autoformats phone numbers and checks if they are valid.
@@ -27,5 +28,5 @@ const NPhoneInput = createComponent('NInputPhone', nInputPhoneProps, async (prop
         return formatted || props.value;
     });
     const isValid = computed(() => parsePhoneNumber(props.value || '').valid);
-    return () => (<NValInput {...{ ...props, onUpdateValue }} value={value.value} rules={external(isValid.value, 'phone')} type="tel"/>);
+    return () => (<NValInput {...{ ...props, onUpdateValue }} value={value.value} rules={external(isValid.value, trsl('vue-collection.validation.rules.phone'))} type="tel"/>);
 });

package/components/NInputSuggestion.d.ts

@@ -199,10 +199,10 @@ declare const _default: import("vue").DefineComponent<{
     tooltipMaxWidth: import("../utils/tailwind").TWMaxWidth;
     disabled: boolean;
     error: boolean;
-    rules: import("../utils/validation").ValidationRule | import("../utils/validation").ValidationRule[];
     autocomplete: string;
     hideLabel: boolean;
     optional: boolean;
+    rules: import("../utils/validation").ValidationRule | import("../utils/validation").ValidationRule[];
     hideErrorMessage: boolean;
     disableBlurValidation: boolean;
     maxItems: number;

package/components/NTextArea.d.ts

@@ -241,10 +241,10 @@ declare const _default: import("vue").DefineComponent<{
     tooltipMaxWidth: import("../utils/tailwind").TWMaxWidth;
     disabled: boolean;
     error: boolean;
-    rules: import("../utils/validation").ValidationRule | import("../utils/validation").ValidationRule[];
     autocomplete: string;
     hideLabel: boolean;
     optional: boolean;
+    rules: import("../utils/validation").ValidationRule | import("../utils/validation").ValidationRule[];
     hideErrorMessage: boolean;
     disableBlurValidation: boolean;
     resizable: boolean;

package/components/NValInput.d.ts

@@ -287,10 +287,10 @@ declare const _default: import("vue").DefineComponent<{
     tooltipMaxWidth: import("../utils/tailwind").TWMaxWidth;
     disabled: boolean;
     error: boolean;
-    rules: ValidationRule | ValidationRule[];
     autocomplete: string;
     hideLabel: boolean;
     optional: boolean;
+    rules: ValidationRule | ValidationRule[];
     hideErrorMessage: boolean;
     disableBlurValidation: boolean;
 }>;

package/i18n/index.d.ts

@@ -1,3 +1,26 @@
+import type { Nullish } from '../utils/utils';
+/**
+ * @see {@link trsl}
+ */
+export type TranslationFunction = typeof trsl;
+/**
+ * @see {@link trslc}
+ */
+export type TranslationCountFunction = typeof trslc;
+/**
+ * A `TranslationProvider` has to implement the two functions `trsl` and `trslc`.
+ */
+export type TranslationProvider = {
+    trsl: TranslationFunction;
+    trslc: TranslationCountFunction;
+};
+/**
+ * Registeres a new translation provider for vue-collection.
+ * The translation provider should contain all vue-collection
+ * texts located under `i18n/<lang>/vue-collection.json`.
+ * @param newProvider
+ */
+export declare function registerTranslationProvider(newProvider: TranslationProvider): void;
 /**
  * Translates the specified key with the according message.
  * @param key the key to translate.
@@ -14,4 +37,4 @@ export declare function trsl(key: string, params?: Record<string, unknown>): str
  * @returns the translated message.
  * @see trsl
  */
-export declare function trslc(key: string, count: number | null | undefined, params?: Record<string, unknown>): string;
+export declare function trslc(key: string, count: Nullish<number>, params?: Record<string, unknown>): string;

package/i18n/index.js

@@ -1,14 +1,13 @@
-import en from './en';
-import de from './de';
-import { createI18n } from 'vue-i18n';
-const i18n = createI18n({
-    legacy: false,
-    locale: 'en',
-    messages: {
-        en,
-        de,
-    },
-});
+let provider = undefined;
+/**
+ * Registeres a new translation provider for vue-collection.
+ * The translation provider should contain all vue-collection
+ * texts located under `i18n/<lang>/vue-collection.json`.
+ * @param newProvider
+ */
+export function registerTranslationProvider(newProvider) {
+    provider = newProvider;
+}
 /**
  * Translates the specified key with the according message.
  * @param key the key to translate.
@@ -16,7 +15,9 @@ const i18n = createI18n({
  * @returns the translated message.
  */
 export function trsl(key, params) {
-    return i18n.global.t(key, params == null ? {} : params);
+    if (!provider)
+        console.warn('Vue Collection: No translation provider has been registered!');
+    return provider?.trsl(key, params) ?? key;
 }
 /**
  * Translates the specified key using pluralization.
@@ -28,7 +29,7 @@ export function trsl(key, params) {
  * @see trsl
  */
 export function trslc(key, count, params) {
-    const newCount = count ?? 0;
-    const newParams = { n: newCount, ...params };
-    return i18n.global.t(key, newParams, { plural: newCount });
+    if (!provider)
+        console.warn('Vue Collection: No translation provider has been registered!');
+    return provider?.trslc(key, count, params) ?? key;
 }

package/index.d.ts

@@ -62,3 +62,5 @@ import NValInput from './components/NValInput';
 export { NValInput };
 import { type ValidatedForm, createValidatedForm } from './components/ValidatedForm';
 export { ValidatedForm, createValidatedForm };
+import { createComponent, createView, createProps } from './utils/component';
+export { createComponent, createView, createProps };

package/index.js

@@ -63,3 +63,5 @@ import NValInput from './components/NValInput';
 export { NValInput };
 import { createValidatedForm } from './components/ValidatedForm';
 export { createValidatedForm };
+import { createComponent, createView, createProps } from './utils/component';
+export { createComponent, createView, createProps };

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@naptics/vue-collection",
-    "version": "0.0.2",
+    "version": "0.0.3",
     "main": "./index.js",
     "scripts": {
         "dev": "vite",
@@ -21,8 +21,7 @@
     },
     "peerDependencies": {
         "@heroicons/vue": "^2.0.16",
-        "vue": "^3.2.36",
-        "vue-i18n": "^9.2.2"
+        "vue": "^3.2.36"
     },
     "devDependencies": {
         "@intlify/unplugin-vue-i18n": "^0.8.2",
@@ -47,6 +46,7 @@
         "typescript": "^4.9.5",
         "vite": "^4.1.3",
         "vitest": "^0.28.5",
+        "vue-i18n": "^9.2.2",
         "vue-router": "^4.1.6",
         "vue-tsc": "^1.1.5"
     }

package/utils/validation.d.ts

@@ -15,8 +15,14 @@ export type ValidationResult = ValidationResultValid | ValidationResultInvalid;
  * with the {@link required} rule.
  */
 export type ValidationRule = (input: InputValue) => ValidationResult;
+/**
+ * Creates a valid result.
+ */
 export declare function validResult(): ValidationResultValid;
-export declare function invalidResult(ruleKey: string, params?: Record<string, unknown>): ValidationResultInvalid;
+/**
+ * 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.
@@ -76,9 +82,9 @@ export declare function option(options: string[]): ValidationRule;
  */
 export declare function regex(pattern: RegExp): ValidationRule;
 /**
- * This rule can be used if the validation logic happens somwhere else.
+ * 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, errorKey: string): ValidationRule;
+export declare function external(isValid: boolean, errorMessage: string): ValidationRule;

package/utils/validation.js

@@ -1,9 +1,19 @@
 import { trsl } from '../i18n';
+/**
+ * Creates a valid result.
+ */
 export function validResult() {
     return { isValid: true };
 }
-export function invalidResult(ruleKey, params) {
-    return { isValid: false, errorMessage: trsl(`vue-collection.validation.rules.${ruleKey}`, params) };
+/**
+ * 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.
@@ -33,7 +43,7 @@ export const required = input => {
     if (trimmed)
         return validResult();
     else
-        return invalidResult('required');
+        return invalidResultInternal('required');
 };
 /**
  * This rule expects the input to be an integer.
@@ -42,7 +52,7 @@ export const integer = input => {
     if (!input || Number.isInteger(+input))
         return validResult();
     else
-        return invalidResult('integer');
+        return invalidResultInternal('integer');
 };
 /**
  * This rule expects the input to be in the specified length range. An empty input
@@ -55,11 +65,11 @@ export function length(min, max) {
         if (!input)
             return validResult();
         if (min !== undefined && max !== undefined && !(min <= input.length && input.length <= max))
-            return invalidResult('length.min-max', { min, max });
+            return invalidResultInternal('length.min-max', { min, max });
         else if (min !== undefined && !(min <= input.length))
-            return invalidResult('length.min', { min });
+            return invalidResultInternal('length.min', { min });
         else if (max !== undefined && !(input.length <= max))
-            return invalidResult('length.max', { max });
+            return invalidResultInternal('length.max', { max });
         return validResult();
     };
 }
@@ -74,13 +84,13 @@ export function numberRange(min, max) {
             return validResult();
         const parsed = Number.parseFloat(input);
         if (Number.isNaN(parsed))
-            return invalidResult('number-range.nan');
+            return invalidResultInternal('number-range.nan');
         if (min !== undefined && max !== undefined && !(min <= parsed && parsed <= max))
-            return invalidResult('number-range.min-max', { min, max });
+            return invalidResultInternal('number-range.min-max', { min, max });
         else if (min !== undefined && !(min <= parsed))
-            return invalidResult('number-range.min', { min });
+            return invalidResultInternal('number-range.min', { min });
         else if (max !== undefined && !(parsed <= max))
-            return invalidResult('number-range.max', { max });
+            return invalidResultInternal('number-range.max', { max });
         return validResult();
     };
 }
@@ -92,7 +102,7 @@ export const email = input => {
     if (!input || VALIDATION_FORMAT_EMAIL.test(input))
         return validResult();
     else
-        return invalidResult('email');
+        return invalidResultInternal('email');
 };
 export const VALIDATION_FORMAT_PASSWORD = /^(?=.*[a-z])(?=.*[A-Z])(?=.*\d)(?=.*[#$^+\-=!*()@%&?]).{8,}$/;
 /**
@@ -102,17 +112,17 @@ export const password = input => {
     if (!input || VALIDATION_FORMAT_PASSWORD.test(input))
         return validResult();
     else if (input.length < 8)
-        return invalidResult('password.to-short');
+        return invalidResultInternal('password.to-short');
     else if (!/[a-z]+/.test(input))
-        return invalidResult('password.no-lowercase');
+        return invalidResultInternal('password.no-lowercase');
     else if (!/[A-Z]+/.test(input))
-        return invalidResult('password.no-uppercase');
+        return invalidResultInternal('password.no-uppercase');
     else if (!/\d+/.test(input))
-        return invalidResult('password.no-digits');
+        return invalidResultInternal('password.no-digits');
     else if (!/[#$^+\-=!*()@%&?]+/.test(input))
-        return invalidResult('password.no-special-chars');
+        return invalidResultInternal('password.no-special-chars');
     else
-        return invalidResult('password.unknown');
+        return invalidResultInternal('password.unknown');
 };
 /**
  * This rule expects the input-value to match another (input-) value.
@@ -125,7 +135,7 @@ export function matches(other) {
         if (input === other)
             return validResult();
         else
-            return invalidResult('matches');
+            return invalidResultInternal('matches');
     };
 }
 /**
@@ -137,7 +147,7 @@ export function option(options) {
         if (!input || options.includes(input || ''))
             return validResult();
         else
-            return invalidResult('option');
+            return invalidResultInternal('option');
     };
 }
 /**
@@ -149,15 +159,15 @@ export function regex(pattern) {
         if (!input || pattern.test(input || ''))
             return validResult();
         else
-            return invalidResult('regex');
+            return invalidResultInternal('regex');
     };
 }
 /**
- * This rule can be used if the validation logic happens somwhere else.
+ * 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, errorKey) {
-    return input => (!input || isValid ? validResult() : invalidResult(errorKey));
+export function external(isValid, errorMessage) {
+    return input => (!input || isValid ? validResult() : invalidResult(errorMessage));
 }

package/i18n/de/template.json

@@ -1,10 +0,0 @@
-{
-    "title": {},
-    "subtitle": {},
-    "text": {},
-    "property": {},
-    "term": {},
-    "action": {},
-    "enum": {},
-    "error": {}
-}

package/i18n/de.d.ts

@@ -1,61 +0,0 @@
-declare const de: {
-    "vue-collection": {
-        title: {};
-        subtitle: {};
-        text: {
-            "loading-search-results": string;
-            "no-search-results": string;
-            "drag-n-drop-files": string;
-            "files-selected": string;
-        };
-        property: {};
-        term: {};
-        action: {
-            search: string;
-            select: string;
-            remove: string;
-            cancel: string;
-            "all-right": string;
-            proceed: string;
-            save: string;
-            "clear-files": string;
-        };
-        enum: {};
-        error: {
-            "file-type": string;
-            "file-size": string;
-            "too-many-files": string;
-        };
-        validation: {
-            rules: {
-                email: string;
-                integer: string;
-                length: {
-                    min: string;
-                    max: string;
-                    "min-max": string;
-                };
-                matches: string;
-                "number-range": {
-                    nan: string;
-                    min: string;
-                    max: string;
-                    "min-max": string;
-                };
-                option: string;
-                password: {
-                    "to-short": string;
-                    "no-lowercase": string;
-                    "no-uppercase": string;
-                    "no-digits": string;
-                    "no-special-chars": string;
-                    unknown: string;
-                };
-                phone: string;
-                required: string;
-                regex: string;
-            };
-        };
-    };
-};
-export default de;

package/i18n/de.js

@@ -1,5 +0,0 @@
-import vueCollection from './de/vue-collection.json';
-const de = {
-    ['vue-collection']: vueCollection,
-};
-export default de;

package/i18n/en/template.json

@@ -1,10 +0,0 @@
-{
-    "title": {},
-    "subtitle": {},
-    "text": {},
-    "property": {},
-    "term": {},
-    "action": {},
-    "enum": {},
-    "error": {}
-}

package/i18n/en.d.ts

@@ -1,61 +0,0 @@
-declare const en: {
-    "vue-collection": {
-        title: {};
-        subtitle: {};
-        text: {
-            "loading-search-results": string;
-            "no-search-results": string;
-            "drag-n-drop-files": string;
-            "files-selected": string;
-        };
-        property: {};
-        term: {};
-        action: {
-            search: string;
-            select: string;
-            remove: string;
-            cancel: string;
-            "all-right": string;
-            proceed: string;
-            save: string;
-            "clear-files": string;
-        };
-        enum: {};
-        error: {
-            "file-type": string;
-            "file-size": string;
-            "too-many-files": string;
-        };
-        validation: {
-            rules: {
-                email: string;
-                integer: string;
-                length: {
-                    min: string;
-                    max: string;
-                    "min-max": string;
-                };
-                matches: string;
-                "number-range": {
-                    nan: string;
-                    min: string;
-                    max: string;
-                    "min-max": string;
-                };
-                option: string;
-                password: {
-                    "to-short": string;
-                    "no-lowercase": string;
-                    "no-uppercase": string;
-                    "no-digits": string;
-                    "no-special-chars": string;
-                    unknown: string;
-                };
-                phone: string;
-                required: string;
-                regex: string;
-            };
-        };
-    };
-};
-export default en;

package/i18n/en.js

@@ -1,5 +0,0 @@
-import vueCollection from './en/vue-collection.json';
-const en = {
-    ['vue-collection']: vueCollection,
-};
-export default en;