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

package/lib/utils/identifiable.d.ts

@@ -0,0 +1,56 @@
+import { 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.
+ */
+declare function find<Id, Item extends Identifiable<Id>>(array: Nullish<Item[]>, id: Id): Item | 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`.
+ */
+declare function contains<Id, Item extends Identifiable<Id>>(array: Item[], id: Id): boolean;
+/**
+ * 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.
+ */
+declare function insert<Id, Item extends Identifiable<Id>>(array: Item[], ...insertItems: Item[]): Item[];
+/**
+ * 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.
+ */
+declare function remove<Id, Item extends Identifiable>(array: Item[], ...ids: Id[]): Item[];
+/**
+ * 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.
+ */
+declare function areSameArrays<Id>(first: Identifiable<Id>[], second: Identifiable<Id>[]): boolean;
+/**
+ * This object contains utility functions to deal with {@link Identifiable} objects.
+ */
+export declare const Id: {
+    readonly find: typeof find;
+    readonly contains: typeof contains;
+    readonly insert: typeof insert;
+    readonly remove: typeof remove;
+    readonly areSameArrays: typeof areSameArrays;
+};
+export {};

package/lib/utils/identifiable.js

@@ -0,0 +1,81 @@
+import { isNullish } from './utils';
+/**
+ * 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(array, id) {
+  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(array, id) {
+  return find(array, id) !== undefined;
+}
+function insertSingle(baseArray, insertItem) {
+  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(array, ...insertItems) {
+  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(array, ...ids) {
+  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(first, second) {
+  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
+};

package/lib/utils/stringMaxLength.d.ts

@@ -0,0 +1,14 @@
+/**
+ * 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 declare function maxLength(input: string | null, maxLength: number): string;
+/**
+ * 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 declare function maxLengthSplitCenter(input: string | null, maxLength: number): string;

package/lib/utils/stringMaxLength.js

@@ -0,0 +1,23 @@
+/**
+ * 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, maxLength) {
+  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, maxLength) {
+  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/lib/utils/tailwind.d.ts

@@ -0,0 +1,4 @@
+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/lib/utils/tailwind.js

@@ -0,0 +1 @@
+export {};

package/lib/utils/utils.d.ts

@@ -0,0 +1,47 @@
+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 declare function notNullish<T>(value: Nullish<T>): value is T;
+/**
+ * Determines if a value is null or undefined.
+ * @param value the value to check
+ * @returns `true` if the value is `null` or `undefined`.
+ */
+export declare function isNullish(value: Nullish<unknown>): value is null | 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 declare function notNullishRef<T>(ref: Ref<T>): ref is Ref<NonNullable<T>>;
+/**
+ * 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 declare function isNullishRef(ref: Ref<Nullish<unknown>>): ref is Ref<null | undefined>;
+export type AnyObject = Record<string | number | symbol, unknown>;
+export type EmptyObject = Record<string | number | symbol, never>;
+export declare function isAnyObject(object: unknown): object is AnyObject;
+/**
+ * Marks all properties of an object (including sub-objects) as readonly.
+ */
+export type ReadonlyObject<T extends AnyObject> = {
+    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 declare function readonlyObject<T extends AnyObject>(object: T): ReadonlyObject<T>;
+/**
+ * Generates and returns a non random but unique id.
+ */
+export declare function uniqueId(): number;

package/lib/utils/utils.js

@@ -0,0 +1,56 @@
+/*
+ * ---------- Null and 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(value) {
+  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) {
+  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(ref) {
+  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) {
+  return isNullish(ref.value);
+}
+export function isAnyObject(object) {
+  return typeof object === 'object' && !Array.isArray(object);
+}
+/**
+ * Returns the same object casted to a {@link ReadonlyObject}.
+ */
+export function readonlyObject(object) {
+  return object;
+}
+/*
+ * ---------- Unique Id ----------
+ */
+let currentId = 1;
+/**
+ * Generates and returns a non random but unique id.
+ */
+export function uniqueId() {
+  return currentId++;
+}

package/{src/lib/utils/vModel.ts → lib/utils/vModel.d.ts}

@@ -1,104 +1,76 @@
-import type { PropType, Ref } from 'vue'
-import type { AnyObject } from './utils'
-
-/*
- * ---------- VModel as Props ----------
- */
-
+import type { PropType, Ref } from 'vue';
+import type { AnyObject } from './utils';
 /**
  * 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
-}
-
+export declare function vModelProps<T>(propType: PropType<T>): {
+    /**
+     * The value of the component.
+     */
+    readonly value: PropType<T>;
+    /**
+     * This will be called, when the value of the component has changed.
+     */
+    readonly onUpdateValue: PropType<(newValue: T) => void>;
+};
 /**
  * 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
-}
-
+export declare function vModelRequiredProps<T>(propType: PropType<T>): {
+    /**
+     * The value of the component.
+     */
+    readonly value: {
+        readonly type: PropType<T>;
+        readonly required: true;
+    };
+    /**
+     * This will be called, when the value of the component has changed.
+     */
+    readonly onUpdateValue: PropType<(newValue: T) => void>;
+};
 /**
  * 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 ----------
- */
-
+export declare function vModelDefaultProps<T>(propType: PropType<T>, defaultValue: () => T): {
+    /**
+     * The value of the component.
+     */
+    readonly value: {
+        readonly type: PropType<T>;
+        readonly default: () => T;
+    };
+    /**
+     * This will be called, when the value of the component has changed.
+     */
+    readonly onUpdateValue: PropType<(newValue: T) => void>;
+};
 /**
  * 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
-}
-
+    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
-}
-
+    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
-        },
-    }
-}
-
+export declare function vModelForRef<T>(ref: Ref<T>): VModel<T>;
 /**
  * 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
@@ -121,19 +93,7 @@ export function vModelForRef<T>(ref: Ref<T>): VModel<T> {
  * )
  * ```
  */
-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 })
-        },
-    }
-}
-
+export declare function vModelForObjectProperty<T extends AnyObject, K extends keyof T>(object: T, key: K, onUpdate?: (newValue: T) => void): VModel<T[K]>;
 /**
  * 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`
@@ -163,19 +123,7 @@ export function vModelForObjectProperty<T extends AnyObject, K extends keyof T>(
  * )
  * ```
  */
-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 })
-        },
-    }
-}
-
+export declare function vModelForVModelProperty<Model extends VModel<ModelValue>, Key extends keyof ModelValue, ModelValue extends AnyObject = Model['value']>(vModel: Model, key: Key): VModel<ModelValue[Key]>;
 /**
  * This function does the same thing as {@link vModelForVModelProperty},
  * but can be provided with a mapper function for the modified property.
@@ -206,20 +154,7 @@ export function vModelForVModelProperty<
  * )
  * ```
  */
-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) })
-        },
-    }
-}
-
+export declare 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>;
 /**
  * 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.
@@ -244,17 +179,4 @@ export function vModelForVModelPropertyMapType<
  * )
  * ```
  */
-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)
-        },
-    }))
-}
+export declare function vModelsForArray<T>(array: T[], onUpdate?: (newValue: T[]) => void): VModelForArray<T>[];