@naptics/vue-collection 0.2.15 → 0.3.1

package/src/lib/utils/identifiable.ts

@@ -0,0 +1,87 @@
+import { isNullish, type Nullish } from './utils'
+
+export type Identifiable<Id = string> = Readonly<{ id: Id }>
+export type MaybeIdentifiable<Id = string> = Readonly<{ id?: Nullish<Id> }>
+
+/**
+ * Looks for the `id` in the given array of `Identifiables`.
+ * @param array The array to search the item in.
+ * @param id The `id` of the desired item.
+ * @returns The first item with the specified `id` or `undefined` if none exists.
+ */
+function find<Id, Item extends Identifiable<Id>>(array: Nullish<Item[]>, id: Id): Item | undefined {
+    if (isNullish(array)) return undefined
+    const filtered = array.filter(item => item.id === id)
+    if (filtered.length > 0) return filtered[0]
+    else return undefined
+}
+
+/**
+ * Checks if the given array contains an item with the `id`.
+ * @param array The array to search the item in.
+ * @param id The `id` to check the array for.
+ * @returns `true` if there is at least one item in the array with the given `id`.
+ */
+function contains<Id, Item extends Identifiable<Id>>(array: Item[], id: Id): boolean {
+    return find(array, id) !== undefined
+}
+
+function insertSingle<Id, Item extends Identifiable<Id>>(baseArray: Item[], insertItem: Item) {
+    const index = baseArray.findIndex(item => item.id === insertItem.id)
+    if (index === -1) {
+        baseArray.push(insertItem)
+    } else {
+        baseArray.splice(index, 1, insertItem)
+    }
+}
+
+/**
+ * Inserts the items into the given array, replacing items with the same `id`.
+ * If no item with the same `id` exists, the item is appended to the array.
+ * If multiple items with the same `id` exist, just the first item is replaced.
+ * @param array The array to insert the items into.
+ * @param insertItems The items to insert into the array.
+ * @returns The reference to the same array, which was passed.
+ */
+function insert<Id, Item extends Identifiable<Id>>(array: Item[], ...insertItems: Item[]): Item[] {
+    insertItems.forEach(item => insertSingle(array, item))
+    return array
+}
+
+/**
+ * Removes all items with the specified `ids` from the given array.
+ * @param array The array to remove the items from.
+ * @param ids The `ids` of the items which should be removed.
+ * @returns The reference to the same array, which was passed.
+ */
+function remove<Id, Item extends Identifiable>(array: Item[], ...ids: Id[]): Item[] {
+    ids.forEach(id => {
+        let noMatches = false
+        while (!noMatches) {
+            const index = array.findIndex(item => item.id === id)
+            if (index != -1) array.splice(index, 1)
+            else noMatches = true
+        }
+    })
+    return array
+}
+
+/**
+ * Compares the two arrays and checks if they both have
+ * items with the same `ids` in the same order.
+ * @param first The first array to compare.
+ * @param second The second array to compare.
+ * @returns `true` if the arrays contain item with the same `ids` in the same order.
+ */
+function areSameArrays<Id>(first: Identifiable<Id>[], second: Identifiable<Id>[]): boolean {
+    if (first.length != second.length) return false
+    for (let i = 0; i < first.length; i++) {
+        if (first[i]?.id !== second[i]?.id) return false
+    }
+    return true
+}
+
+/**
+ * This object contains utility functions to deal with {@link Identifiable} objects.
+ */
+export const Id = { find, contains, insert, remove, areSameArrays } as const

package/src/lib/utils/stringMaxLength.ts

@@ -0,0 +1,25 @@
+/**
+ * Returns a shortened string with '...' at the end if it is longer than the given `maxLength`.
+ * @param input the string to shorten
+ * @param maxLength the max length
+ * @see maxLengthSplitCenter
+ */
+export function maxLength(input: string | null, maxLength: number): string {
+    if (input && input.length > maxLength) return `${input.substring(0, maxLength - 3).trim()}...`
+    else return input || ''
+}
+
+/**
+ * Returns a shortened string with '...' in the center of the string if it is longer than the given `maxLength`.
+ * @param input the string to shorten
+ * @param maxLength the max length
+ * @see maxLength
+ */
+export function maxLengthSplitCenter(input: string | null, maxLength: number): string {
+    if (input && input.length > maxLength) {
+        const chars = maxLength - 3
+        const charsAtStart = Math.ceil(chars / 2)
+        const charsAtEnd = Math.floor(chars / 2)
+        return `${input.substring(0, charsAtStart).trim()}...${input.substring(input.length - charsAtEnd).trim()}`
+    } else return input || ''
+}

package/src/lib/utils/tailwind.ts

@@ -0,0 +1,41 @@
+import type { FunctionalComponent, HTMLAttributes, VNodeProps } from 'vue'
+
+export type TWTextSize =
+    | 'text-xs'
+    | 'text-sm'
+    | 'text-base'
+    | 'text-lg'
+    | 'text-xl'
+    | 'text-2xl'
+    | 'text-3xl'
+    | 'text-4xl'
+    | 'text-5xl'
+    | 'text-6xl'
+    | 'text-7xl'
+    | 'text-8xl'
+    | 'text-9xl'
+
+export type TWMaxWidth =
+    | 'max-w-xs'
+    | 'max-w-sm'
+    | 'max-w-md'
+    | 'max-w-lg'
+    | 'max-w-xl'
+    | 'max-w-2xl'
+    | 'max-w-3xl'
+    | 'max-w-4xl'
+    | 'max-w-5xl'
+    | 'max-w-6xl'
+    | 'max-w-7xl'
+    | 'max-w-full'
+    | 'max-w-min'
+    | 'max-w-max'
+    | 'max-w-fit'
+    | 'max-w-prose'
+    | 'max-w-screen-sm'
+    | 'max-w-screen-md'
+    | 'max-w-screen-lg'
+    | 'max-w-screen-xl'
+    | 'max-w-screen-2xl'
+
+export type HeroIcon = FunctionalComponent<HTMLAttributes & VNodeProps>

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))
+}