@naptics/vue-collection 0.2.15 → 0.3.0

package/src/lib/utils/utils.ts

@@ -0,0 +1,90 @@
+/*
+ * ---------- Null and Undefined ----------
+ */
+
+import type { Ref } from 'vue'
+
+export type Optional<T> = T | undefined
+export type Nullable<T> = T | null
+export type Nullish<T> = T | null | undefined
+
+/**
+ * Determines if a value is not null or undefined.
+ * @param value the value to check
+ * @returns `true` if the value is anything but `null` or `undefined`.
+ */
+export function notNullish<T>(value: Nullish<T>): value is T {
+    return value !== null && value !== undefined
+}
+
+/**
+ * Determines if a value is null or undefined.
+ * @param value the value to check
+ * @returns `true` if the value is `null` or `undefined`.
+ */
+export function isNullish(value: Nullish<unknown>): value is null | undefined {
+    return value === null || value === undefined
+}
+
+/**
+ * Determines if the value of a ref is not nullish.
+ * @param ref the ref to check
+ * @returns `true` if the value of the ref is not nullish.
+ * @see notNullish
+ */
+export function notNullishRef<T>(ref: Ref<T>): ref is Ref<NonNullable<T>> {
+    return notNullish(ref.value)
+}
+
+/**
+ * Determines if the value of a ref is null or undefined.
+ * @param ref the ref to check
+ * @returns `true` if the value of the ref is `null` or `undefined`.
+ * @see isNullish
+ */
+export function isNullishRef(ref: Ref<Nullish<unknown>>): ref is Ref<null | undefined> {
+    return isNullish(ref.value)
+}
+
+/*
+ * ---------- Objects ----------
+ */
+
+export type AnyObject = Record<string | number | symbol, unknown>
+export type EmptyObject = Record<string | number | symbol, never>
+
+export function isAnyObject(object: unknown): object is AnyObject {
+    return typeof object === 'object' && !Array.isArray(object)
+}
+
+/**
+ * Marks all properties of an object (including sub-objects) as readonly.
+ */
+export type ReadonlyObject<T extends AnyObject> = {
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    readonly [P in keyof T]: T[P] extends ReadonlyObject<infer _U>
+        ? T[P]
+        : T[P] extends AnyObject
+          ? ReadonlyObject<T[P]>
+          : T[P]
+}
+
+/**
+ * Returns the same object casted to a {@link ReadonlyObject}.
+ */
+export function readonlyObject<T extends AnyObject>(object: T): ReadonlyObject<T> {
+    return object as ReadonlyObject<T>
+}
+
+/*
+ * ---------- Unique Id ----------
+ */
+
+let currentId = 1
+
+/**
+ * Generates and returns a non random but unique id.
+ */
+export function uniqueId(): number {
+    return currentId++
+}

package/src/lib/utils/vModel.ts

@@ -0,0 +1,260 @@
+import type { PropType, Ref } from 'vue'
+import type { AnyObject } from './utils'
+
+/*
+ * ---------- 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<T>(propType: PropType<T>) {
+    return {
+        /**
+         * The value of the component.
+         */
+        value: propType as PropType<T>,
+        /**
+         * This will be called, when the value of the component has changed.
+         */
+        onUpdateValue: Function as PropType<(newValue: T) => void>,
+    } as const
+}
+
+/**
+ * Creates props for a required `v-model` of the given type.
+ * @see {@link vModelProps}
+ */
+export function vModelRequiredProps<T>(propType: PropType<T>) {
+    return {
+        /**
+         * The value of the component.
+         */
+        value: {
+            type: propType as PropType<T>,
+            required: true,
+        },
+        /**
+         * This will be called, when the value of the component has changed.
+         */
+        onUpdateValue: Function as PropType<(newValue: T) => void>,
+    } as const
+}
+
+/**
+ * Creates props for a `v-model` of the given type with a default value.
+ * @see {@link vModelProps}
+ */
+export function vModelDefaultProps<T>(propType: PropType<T>, defaultValue: () => T) {
+    return {
+        /**
+         * The value of the component.
+         */
+        value: {
+            type: propType as PropType<T>,
+            default: defaultValue,
+        },
+        /**
+         * This will be called, when the value of the component has changed.
+         */
+        onUpdateValue: Function as PropType<(newValue: T) => void>,
+    } as const
+}
+
+/*
+ * ---------- VModel to pass to components ----------
+ */
+
+/**
+ * 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 function vModelForRef<T>(ref: Ref<T>): VModel<T> {
+    return {
+        value: ref.value,
+        onUpdateValue: (newValue: T) => {
+            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<T extends AnyObject, K extends keyof T>(
+    object: T,
+    key: K,
+    onUpdate?: (newValue: T) => void
+): VModel<T[K]> {
+    return {
+        value: object[key],
+        onUpdateValue: (newValue: T[K]) => {
+            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<
+    Model extends VModel<ModelValue>,
+    Key extends keyof ModelValue,
+    ModelValue extends AnyObject = Model['value'],
+>(vModel: Model, key: Key): VModel<ModelValue[Key]> {
+    return {
+        value: vModel.value[key],
+        onUpdateValue: (newValue: ModelValue[Key]) => {
+            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<
+    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> {
+    return {
+        value: vModel.value[key],
+        onUpdateValue: (newValue: UpdateValue) => {
+            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<T>(array: T[], onUpdate?: (newValue: T[]) => void): VModelForArray<T>[] {
+    return array.map((entry, index) => ({
+        value: entry,
+        onUpdateValue: (entry: T) => {
+            const newArray = [...array]
+            newArray[index] = entry
+            onUpdate?.(newArray)
+        },
+        remove: () => {
+            const newArray = [...array.slice(0, index), ...array.slice(index + 1)]
+            onUpdate?.(newArray)
+        },
+    }))
+}

package/src/lib/utils/validation.ts

@@ -0,0 +1,189 @@
+import { trsl } from '../i18n'
+
+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 function validResult(): ValidationResultValid {
+    return { isValid: true }
+}
+
+/**
+ * Creates an invalid result with the provided error message.
+ */
+export function invalidResult(errorMessage: string): ValidationResultInvalid {
+    return { isValid: false, errorMessage }
+}
+
+const TRANSLATION_KEY_BASE = 'vue-collection.validation.rules'
+function invalidResultInternal(key: string, params?: Record<string, unknown>): ValidationResultInvalid {
+    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: InputValue, rules: ValidationRule[]): ValidationResult {
+    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: ValidationRule = 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: ValidationRule = 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: number | undefined, max: number | undefined): ValidationRule {
+    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: number | undefined, max: number | undefined): ValidationRule {
+    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: ValidationRule = 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: ValidationRule = 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: string | null | undefined): ValidationRule {
+    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: string[]): ValidationRule {
+    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: RegExp): ValidationRule {
+    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: boolean, errorMessage: string): ValidationRule {
+    return input => (!input || isValid ? validResult() : invalidResult(errorMessage))
+}

package/src/lib/utils/vue.ts

@@ -0,0 +1,25 @@
+import { type Ref, watch, 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 function updateWith<T>(ref: Ref<T>, updater: () => T): void {
+    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<T>(ref: Ref<T> | ComputedRef<T>, onChange: (newValue: T) => void): void {
+    watch(() => ref.value, onChange)
+}

package/tailwind.config.js

@@ -0,0 +1,38 @@
+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}'],
+    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')],
+}

package/tsconfig.config.json

@@ -0,0 +1,9 @@
+{
+    "extends": "@vue/tsconfig/tsconfig.json",
+    "include": ["vite.config.*", "vitest.config.*", "cypress.config.*"],
+    "compilerOptions": {
+        "composite": true,
+        "types": ["node"],
+        "noEmit": false
+    }
+}

package/tsconfig.demo.json

@@ -0,0 +1,19 @@
+{
+    "extends": "@vue/tsconfig/tsconfig.dom.json",
+    // all files must be included, because demo uses lib.
+    "include": ["env.d.ts", "src/**/*", "src/**/*.json"],
+    "exclude": ["src/**/__tests__/*"],
+    "compilerOptions": {
+        "composite": true,
+        "baseUrl": ".",
+        "paths": {
+            "@/*": ["./src/*"]
+        },
+        "jsx": "preserve",
+        "jsxImportSource": "vue",
+        "noImplicitAny": false,
+        "noUncheckedIndexedAccess": false,
+        "skipLibCheck": true,
+        "noEmit": false
+    }
+}

package/tsconfig.json

@@ -0,0 +1,16 @@
+{
+    "references": [
+        {
+            "path": "./tsconfig.config.json"
+        },
+        {
+            "path": "./tsconfig.demo.json"
+        },
+        {
+            "path": "./tsconfig.lib.json"
+        },
+        {
+            "path": "./tsconfig.vitest.json"
+        }
+    ]
+}

package/tsconfig.lib.json

@@ -0,0 +1,18 @@
+{
+    "extends": "@vue/tsconfig/tsconfig.dom.json",
+    "include": ["src/lib/**/*", "src/lib/**/*.json"],
+    "exclude": ["src/**/__tests__/*"],
+    "compilerOptions": {
+        "composite": true,
+        // don't allow @ alias inside library
+        "paths": {},
+        "outDir": "lib",
+        "jsx": "preserve",
+        "jsxImportSource": "vue",
+        "noImplicitAny": false,
+        "downlevelIteration": true,
+        "skipLibCheck": true,
+        "noEmit": false,
+        "declaration": true
+    }
+}

package/tsconfig.vitest.json

@@ -0,0 +1,8 @@
+{
+    "extends": "./tsconfig.lib.json",
+    "exclude": [],
+    "compilerOptions": {
+        "composite": true,
+        "types": ["node", "jsdom"]
+    }
+}

package/utils/breakpoints.d.ts

@@ -1,7 +1,7 @@
 import { type ComputedRef } from 'vue';
 export type TWBreakpoint = 'sm' | 'md' | 'lg' | 'xl' | '2xl';
 export declare const breakpoints: Readonly<Record<TWBreakpoint, number>>;
-export declare const bodyWidth: import("vue").Ref<number>;
+export declare const bodyWidth: import("vue").Ref<number, number>;
 /**
  * This function has to be called once in the app two ensure that the breakpoint utilities actually update.
  * It sets a `window.onresize` listener.