@naptics/vue-collection 0.2.14 → 0.3.0

package/src/lib/i18n/index.ts

@@ -0,0 +1,54 @@
+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
+}
+
+let provider: TranslationProvider | undefined = 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: TranslationProvider): void {
+    provider = newProvider
+}
+
+/**
+ * Translates the specified key with the according message.
+ * @param key the key to translate.
+ * @param params formatting parameters for the message.
+ * @returns the translated message.
+ */
+export function trsl(key: string, params?: Record<string, unknown>): string {
+    return provider?.trsl(key, params) ?? key
+}
+
+/**
+ * Translates the specified key using pluralization.
+ * The provided `count`is automatically passed as the parameter `n` to the translation library.
+ * @param key the key to translate.
+ * @param count the count used for the pluralization.
+ * @param params formatting parameters for the message.
+ * @returns the translated message.
+ * @see trsl
+ */
+export function trslc(key: string, count: Nullish<number>, params?: Record<string, unknown>): string {
+    return provider?.trslc(key, count, params) ?? key
+}

package/src/lib/index.ts

@@ -0,0 +1,2 @@
+import { createComponent, createView } from './utils/component'
+export { createComponent, createView }

package/src/lib/jsx.d.ts

@@ -0,0 +1,13 @@
+import type { VNode } from 'vue'
+
+declare global {
+    namespace JSX {
+        interface IntrinsicElements {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            [elem: string]: any
+        }
+        type Element = VNode
+    }
+}
+
+export {}

package/src/lib/utils/__tests__/identifiable.spec.ts

@@ -0,0 +1,72 @@
+import { describe, expect, test } from 'vitest'
+import { Id } from '../identifiable'
+
+const one = { id: 'id1', label: 'one' }
+const two = { id: 'id2', label: 'two' }
+const three = { id: 'id3', label: 'three' }
+const four = { id: 'id4', label: 'four' }
+const all = [one, two, three, four]
+
+describe('identifiable', () => {
+    test('find', () => {
+        expect(Id.find(all, 'id1')).toMatchObject(one)
+        expect(Id.find(all, 'id3')).toMatchObject(three)
+        // check if the first is picked if multiple
+        expect(Id.find([...all, { id: 'id2', label: 'new' }], 'id2')).toMatchObject(two)
+        // check if undefined is returned if not found
+        expect(Id.find(all, 'id')).toBeUndefined()
+    })
+
+    test('contains', () => {
+        expect(Id.contains(all, 'id1')).toBe(true)
+        expect(Id.contains(all, 'id3')).toBe(true)
+        expect(Id.contains(all, 'id5')).toBe(false)
+        expect(Id.contains(all, 'id')).toBe(false)
+    })
+
+    test('insert', () => {
+        const before = [one, two, three]
+        let modify = [...before]
+
+        let after = Id.insert(modify, two, one)
+        // Check if array is still the same
+        expect(after).toMatchObject(before)
+        // Check if the reference is the same
+        expect(after).toBe(modify)
+
+        modify = [...before]
+        after = Id.insert(modify, four, three)
+        expect(after).toMatchObject([one, two, three, four])
+
+        modify = [...before]
+        const twoModified = { id: 'id2', label: 'twoooo' }
+        after = Id.insert(modify, twoModified)
+        expect(after).toMatchObject([one, twoModified, three])
+    })
+
+    test('remove', () => {
+        const before = [one, two, three]
+        let modify = [...before]
+
+        let after = Id.remove(modify, 'id')
+        // Check if array is still the same
+        expect(after).toMatchObject(before)
+        // Check if the reference is the same
+        expect(after).toBe(modify)
+
+        modify = [...before]
+        after = Id.remove(modify, 'id2')
+        expect(after).toMatchObject([one, three])
+
+        modify = [one, two, three, four]
+        after = Id.remove(modify, 'id1', 'id3')
+        expect(after).toMatchObject([two, four])
+    })
+
+    test('areSameArrays', () => {
+        const allDifferent = all.map(item => ({ ...item, label: 'different' }))
+        expect(Id.areSameArrays(all, allDifferent)).toBe(true)
+        expect(Id.areSameArrays(all, allDifferent.slice(1))).toBe(false)
+        expect(Id.areSameArrays(all, allDifferent.reverse())).toBe(false)
+    })
+})

package/src/lib/utils/__tests__/validation.spec.ts

@@ -0,0 +1,92 @@
+import { trsl } from '../../i18n'
+import { describe, expect, test } from 'vitest'
+import { email, external, matches, option, password, regex, required } from '../validation'
+
+const expectValid = (test: unknown) => expect(test).toMatchObject({ isValid: true })
+const expectInvalid = (test: unknown, errKey: string) =>
+    expect(test).toMatchObject({ isValid: false, errorMessage: trsl(`vue-collection.validation.rules.${errKey}`) })
+
+describe('validation', () => {
+    test('required', () => {
+        expectValid(required('_'))
+        expectValid(required(' i '))
+        expectValid(required('hellooh'))
+        expectValid(required('`'))
+
+        expectInvalid(required(undefined), 'required')
+        expectInvalid(required(null), 'required')
+        expectInvalid(required(''), 'required')
+        expectInvalid(required(' '), 'required')
+    })
+
+    test('email', () => {
+        expectValid(email(''))
+        expectValid(email('_@_.ch'))
+        expectValid(email('dfadfasd.dfad.fdak@_.ch'))
+        expectValid(email('dfadfasd.dfad.fdak@dfdaf.chdl.ch'))
+        expectValid(email('deslek-djsl@dfdaf-cas.ch'))
+
+        expectInvalid(email('a'), 'email')
+        expectInvalid(email('a@'), 'email')
+        expectInvalid(email('a@d'), 'email')
+        expectInvalid(email('a@d.c'), 'email')
+        expectInvalid(email('a.ch'), 'email')
+    })
+
+    test('password', () => {
+        expectValid(password(''))
+        expectValid(password('Password1+'))
+        expectValid(password('+Password1'))
+        expectValid(password('1+Password'))
+        expectValid(password('assword1+P'))
+        expectValid(password('12p+D678'))
+
+        expectInvalid(password('p'), 'password.to-short')
+        expectInvalid(password('Pword1+'), 'password.to-short')
+        expectInvalid(password('PASSWORD1+'), 'password.no-lowercase')
+        expectInvalid(password('password1+'), 'password.no-uppercase')
+        expectInvalid(password('Password+'), 'password.no-digits')
+        expectInvalid(password('Password1'), 'password.no-special-chars')
+    })
+
+    test('matches', () => {
+        const testValid = [undefined, null, '', '1', 'hello', 'So cooool']
+        testValid.forEach(value => {
+            expectValid(matches(value)(value))
+        })
+
+        // This rule does not allow the input to be falsy, always has to match.
+        const testInvalid = ['', '1', 'hi', 'noice', 'not-null', 'not-null', 'not-null']
+        const checkInvalid = ['ho', '11', 'HI', 'noices', '', null, undefined]
+
+        testInvalid.forEach((value, index) => {
+            expectInvalid(matches(value)(checkInvalid[index]), 'matches')
+        })
+    })
+
+    test('regex', () => {
+        expectValid(regex(/\d+/)('123'))
+        expectValid(regex(/\d*/)(null))
+        expectValid(regex(/\d+/)(null))
+
+        expectInvalid(regex(/\d+/)('abc'), 'regex')
+    })
+
+    test('option', () => {
+        const options1 = ['a', 'b', 'ab', 'ac', 'a']
+        expectValid(option(options1)(null))
+        expectValid(option(options1)('a'))
+        expectValid(option(options1)('b'))
+        expectValid(option(options1)('ab'))
+
+        expectInvalid(option(options1)('c'), 'option')
+        expectInvalid(option(options1)('A'), 'option')
+        expectInvalid(option(options1)('aB'), 'option')
+    })
+
+    test('external', () => {
+        expectValid(external(true, trsl('vue-collection.validation.rules.phone'))('hi'))
+        expectValid(external(false, trsl('vue-collection.validation.rules.phone'))(null))
+        expectInvalid(external(false, trsl('vue-collection.validation.rules.phone'))('hi'), 'phone')
+    })
+})

package/src/lib/utils/breakpoints.ts

@@ -0,0 +1,47 @@
+import { computed, ref, type ComputedRef } from 'vue'
+
+export type TWBreakpoint = 'sm' | 'md' | 'lg' | 'xl' | '2xl'
+
+export const breakpoints: Readonly<Record<TWBreakpoint, number>> = {
+    sm: 640,
+    md: 768,
+    lg: 1024,
+    xl: 1280,
+    '2xl': 1536,
+}
+
+export const bodyWidth = ref(document.body.clientWidth)
+
+/**
+ * This function has to be called once in the app two ensure that the breakpoint utilities actually update.
+ * It sets a `window.onresize` listener.
+ */
+export function addDocumentResizeEventListener(): void {
+    window.onresize = () => {
+        bodyWidth.value = document.body.clientWidth
+    }
+}
+
+/**
+ * Returns a ref whose value is `true` as long as the `document.body.clientWitdh` is above the specified breakpoint.
+ */
+export function isWidthBreakpoint(breakpoint: TWBreakpoint): ComputedRef<boolean> {
+    switch (breakpoint) {
+        case 'sm':
+            return isWidthSm
+        case 'md':
+            return isWidthMd
+        case 'lg':
+            return isWidthLg
+        case 'xl':
+            return isWidthXl
+        case '2xl':
+            return isWidth2xl
+    }
+}
+
+export const isWidth2xl = computed(() => bodyWidth.value > breakpoints['2xl'])
+export const isWidthXl = computed(() => bodyWidth.value > breakpoints.xl)
+export const isWidthLg = computed(() => bodyWidth.value > breakpoints.lg)
+export const isWidthMd = computed(() => bodyWidth.value > breakpoints.md)
+export const isWidthSm = computed(() => bodyWidth.value > breakpoints.sm)

package/src/lib/utils/component.tsx

@@ -0,0 +1,131 @@
+// eslint-disable @typescript-eslint/explicit-module-boundary-types
+// eslint-disable-next-line vue/prefer-import-from-vue
+import type { LooseRequired } from '@vue/shared'
+import {
+    defineComponent,
+    reactive,
+    toRef,
+    type ComponentObjectPropsOptions,
+    type ExtractPropTypes,
+    type RenderFunction,
+    type SetupContext,
+    type ToRefs,
+    type UnwrapNestedRefs,
+    type Slots,
+    toRefs,
+    ref,
+} from 'vue'
+import type { AnyObject } from './utils'
+
+type Data = Record<string, unknown>
+export type Props<T extends Data = Data> = ComponentObjectPropsOptions<T>
+
+/**
+ * `ExtractedProps` maps a prop object to the props, which are received in the `setup` function of a components.
+ */
+export type ExtractedProps<T extends Props> = Readonly<LooseRequired<Readonly<ExtractPropTypes<T>>>>
+
+/**
+ * Components should be created using this helper function.
+ * It only takes three arguments, the name and the props of the component and the setup function.
+ * All other arguments which the {@link defineComponent} method of vue may provide,
+ * should not be used for a better consistency across all components.
+ * @param name the name of the component, should be more than one word.
+ * @param props the props of the component.
+ * @param setup the setup function, which will be called when the component is mounted.
+ * @returns the created vue-component.
+ */
+export function createComponent<T extends Props>(
+    name: string,
+    props: T,
+    setup: (props: ExtractedProps<T>, context: SetupContext<never[]>) => RenderFunction | Promise<RenderFunction>
+) {
+    // Vue 3.5's defineComponent has strict type requirements that don't align with our simplified API.
+    // The type assertion is necessary because the generic setup function signature doesn't match
+    // Vue's complex overloaded defineComponent types, even though the runtime behavior is correct.
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    return defineComponent({ name, props, emits: [], setup } as any)
+}
+
+/**
+ * When using this function, the created component will make available all props
+ * specifiedin `slotPropKeys` as slot. In this way, they can be used by either setting
+ * the prop directly or by using a slot with the same name. This is useful for older
+ * components (in `.vue` files), because they are dependent on slots.
+ * @see {@link createComponent}
+ */
+export function createComponentWithSlots<T extends Props>(
+    name: string,
+    props: T,
+    slotPropKeys: SlotPropsKeys<ExtractedProps<T>>,
+    setup: (props: ExtractedProps<T>, context: SetupContext<never[]>) => RenderFunction | Promise<RenderFunction>
+) {
+    const newSetup: typeof setup = (props, context) => {
+        const slottedProps = createSlotProps(props, context.slots, ...slotPropKeys)
+        return setup(slottedProps, context)
+    }
+    return createComponent(name, props, newSetup)
+}
+
+/**
+ * Views should be created using this helper function. Views are special components, which don't have props.
+ * They are often the parent objects in a view hierarchy and contain many components.
+ * This function is syntactic sugar to create views and just calls {@link createComponent}.
+ * @param name the name of the component, should be more than one word.
+ * @param setup the setup function, which will be called when the component is mounted.
+ * @returns the created vue-component.
+ */
+export function createView(
+    name: string,
+    setup: (context: SetupContext<never[]>) => RenderFunction | Promise<RenderFunction>
+) {
+    return defineComponent({ name, emits: [], setup: (props, context) => setup(context) })
+}
+
+/**
+ * Extracts props from another prop object and returns a reactive object with the specified props.
+ * @param props the props to extract from
+ * @param keys the keys to extract from the props
+ * @returns the new object with the specified props
+ * @example
+ * const parentProps = { title: 'hi', text: 'ho' }
+ * const childProps = extractProps(parentProps, 'title')
+ * console.log(childProps) // { title: 'hi' }
+ */
+export function extractProps<T extends Record<string, unknown>>(
+    props: T,
+    ...keys: (keyof T)[]
+): UnwrapNestedRefs<Partial<ToRefs<T>>> {
+    const partial: Partial<ToRefs<T>> = {}
+    for (const key of keys) partial[key] = toRef(props, key)
+    return reactive(partial)
+}
+
+/*
+ * ---------- Slot Helpers ----------
+ */
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type SlotFunction<Args extends any[] = any[]> = (...args: Args) => JSX.Element
+
+/**
+ * Filters object T to only have properties of type K.
+ */
+type FilterObject<T, K> = {
+    [P in keyof T as T[P] extends K ? P : never]: T[P]
+}
+
+type SlotPropsKeys<T extends AnyObject> = (keyof FilterObject<T, SlotFunction | undefined>)[]
+
+function createSlotProps<T extends AnyObject, U extends SlotPropsKeys<T>>(props: T, slots: Slots, ...keys: U): T {
+    // create refs, don't touch all props which are not slots
+    const newProps = toRefs(props)
+    keys.forEach(key => {
+        // if a slot is set once, it is basically always set. The changing content is not a problem as it is inside the function.
+        const slot = slots[key as string]
+        // if the slot is set, overwrite the props
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        if (slot) newProps[key] = ((...args: any) => <>{slot?.(...args)}</>) as any
+    })
+    return ref(newProps).value
+}

package/src/lib/utils/deferred.ts

@@ -0,0 +1,28 @@
+type PromiseResolve<T> = (value: T | PromiseLike<T>) => void
+type PromiseReject = (reason?: unknown) => void
+
+export type DeferredPromise<T> = {
+    promise: Promise<T>
+    resolve: PromiseResolve<T>
+    reject: PromiseReject
+}
+
+/**
+ * Utlitity to return a deferred promise, which can be resolved from outside.
+ * @returns promise, resolve and reject
+ */
+export function deferred<T>(): DeferredPromise<T> {
+    let resolve!: PromiseResolve<T>
+    let reject!: PromiseReject
+
+    const promise = new Promise<T>((_resolve, _reject) => {
+        resolve = _resolve
+        reject = _reject
+    })
+
+    return {
+        promise,
+        resolve,
+        reject,
+    }
+}

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>