@imaginario27/air-ui-utils 1.0.0

package/eslint.config.mjs

@@ -0,0 +1,14 @@
+// https://eslint.nuxt.com/packages/module
+
+// @ts-check
+import withNuxt from './.nuxt/eslint.config.mjs'
+
+export default withNuxt({
+    rules: {
+        'vue/attribute-hyphenation': 'off',
+        'vue/no-multiple-template-root': 'off',
+        'vue/require-default-prop': 'off',
+        'vue/multi-word-component-names': 'off',
+        '@typescript-eslint/no-explicit-any': 'warn',
+    }
+})

package/models/constants/app.ts

@@ -0,0 +1,8 @@
+export const App = {
+    NAME: 'AirUI',
+}
+
+export const AppSlug = {
+    DOCS: 'docs',
+    COMPONENTS: 'components',
+}

package/models/constants/form.ts

@@ -0,0 +1,22 @@
+
+export const FieldMaxLength = {
+    FULLNAME: 80,
+    LASTNAME: 80,         
+    EMAIL: 254,  
+    PHONE: 15,       
+    SUBJECT: 100,       
+    MESSAGE: 500,
+    PASSWORD: 64, 
+    SEARCH: 80,  
+    DESCRIPTION: 400,     
+}
+
+export const FieldError = {
+    REQUIRED_FIELD: 'This field is required.',
+    REQUIRED_EMAIL: 'Email is required.',
+    INVALID_EMAIL: 'Invalid email address.',
+    REQUIRED_OPTION: 'Please select an option.',
+    INVALID_DATE_RANGE: 'Start date must be before or equal to end date',
+    PASSWORDS_DO_NOT_MATCH: 'Passwords do not match.',
+    INVALID_URL: 'Invalid URL.',
+}

package/models/constants/notifications.ts

@@ -0,0 +1,4 @@
+export const AppNotification = {
+    COPIED_TO_CLIPBOARD: 'Copied to clipboard',
+    COPIED_TO_CLIPBOARD_ERROR: 'Error copying to clipboard',
+}

package/models/types/pdfExportTable.ts

@@ -0,0 +1,6 @@
+export interface HeaderConfig {
+    field: string
+    callback?: (value: any) => string
+}
+
+export type Headers = Record<string, string | HeaderConfig>

package/nuxt.config.ts

@@ -0,0 +1,11 @@
+// https://nuxt.com/docs/api/configuration/nuxt-config
+
+export default defineNuxtConfig({
+    compatibilityDate: "2024-11-01",
+    devtools: { enabled: false },
+    ssr: false,
+
+    eslint: {
+        // options here
+    },
+})

package/package.json

@@ -0,0 +1,43 @@
+{
+    "name": "@imaginario27/air-ui-utils",
+    "version": "1.0.0",
+    "author": "imaginario27",
+    "type": "module",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/imaginario27/air-ui.git"
+    },
+    "publishConfig": {
+        "access": "public"
+    },
+    "scripts": {
+        "build": "nuxt build",
+        "dev": "nuxt dev",
+        "generate": "nuxt generate",
+        "preview": "nuxt preview",
+        "postinstall": "nuxt prepare",
+        "test": "vitest",
+        "publish:patch": "npm version patch --no-git-tag-version && npm publish",
+        "publish:minor": "npm version minor --no-git-tag-version && npm publish",
+        "publish:major": "npm version major --no-git-tag-version && npm publish"
+    },
+    "dependencies": {
+        "eslint": "^9.36.0",
+        "jspdf": "^3.0.3",
+        "jspdf-autotable": "^5.0.2",
+        "nuxt": "^4.1.2",
+        "vue": "^3.5.22",
+        "vue-router": "^4.5.1"
+    },
+    "devDependencies": {
+        "@nuxt/test-utils": "^3.19.2",
+        "@vitest/coverage-v8": "^3.2.4",
+        "@vue/test-utils": "^2.4.6",
+        "happy-dom": "^18.0.1",
+        "playwright-core": "^1.55.1",
+        "prettier": "^3.6.2",
+        "ts-node": "^10.9.2",
+        "typescript": "^5.9.2",
+        "vitest": "^3.2.4"
+    }
+}

package/tsconfig.json

@@ -0,0 +1,7 @@
+{
+    // https://nuxt.com/docs/guide/concepts/typescript
+    "extends": "./.nuxt/tsconfig.json",
+    "compilerOptions": {
+        "types": ["vitest/globals"],
+    }
+}

package/utils/counters.ts

@@ -0,0 +1,30 @@
+/**
+ * Returns the counter content for a stack display based on the number of items, counter type, and item limit.
+ *
+ * @param items - Array of items to evaluate
+ * @param counterType - Type of counter display (ellipsis or numeric)
+ * @param itemsLimit - Optional maximum number of items before showing a counter
+ *
+ * @returns A string representing the counter content
+ */
+
+export const getStackCounterContent = (
+    items: unknown[],
+    counterType: StackCounterType,
+    itemsLimit?: number | null,
+) => {
+    const ellipsis = '...'
+
+    if (!items.length && (itemsLimit === null || itemsLimit === undefined) || counterType === StackCounterType.ELLIPSIS) {
+        return ellipsis
+    }
+
+
+    if (counterType === StackCounterType.COUNTER) {
+        const additionalItems = items.length - (itemsLimit ?? 0)
+
+        return additionalItems > 9 ? '+9' : `+${additionalItems}`
+    }
+
+    return ellipsis
+}

package/utils/data.ts

@@ -0,0 +1,94 @@
+/**
+ * Creates a delay for a specified number of milliseconds.
+ *
+ * @param {number} ms - The duration of the delay in milliseconds.
+ * @returns {Promise<void>} A promise that resolves after the specified delay.
+ *
+ * @example
+ * ```ts
+ * await delay(2000) // Delays execution for 2 seconds
+ * ```
+ */
+export const delay = (ms: number): Promise<void> => {
+    return new Promise((resolve) => setTimeout(resolve, ms))
+}
+
+/**
+ * Returns a paginated subset of an array.
+ *
+ * @template T - The type of items in the array.
+ * @param {T[]} data - The full array of data items.
+ * @param {number} currentPage - The current page number (1-based).
+ * @param {number} itemsPerPage - The number of items per page.
+ * @param {number} [itemsLimit] - Optional maximum number of items to consider before pagination.
+ * @returns {T[]} The paginated array of items.
+ */
+export function getPaginatedData<T>(
+    data: T[],
+    currentPage: number,
+    itemsPerPage: number,
+    itemsLimit?: number
+): T[] {
+    let result = data
+
+    // Apply items limit if provided
+    if (itemsLimit !== undefined && itemsLimit !== null) {
+        result = result.slice(0, itemsLimit)
+    }
+
+    const start = (currentPage - 1) * itemsPerPage
+    const end = start + itemsPerPage
+
+    return result.slice(start, end)
+}
+
+
+/**
+ * Converts an array of objects into SelectOption[] by mapping specified keys or transformation functions.
+ *
+ * @param originArray - The array of items to convert.
+ * @param keyMap - A partial map where each key is a SelectOption field ('text', 'value', etc.)
+ *                 and the value is either a string key to pick from the item, or a function that returns the desired value.
+ *
+ * @example
+ * convertToSelectOptions(users, {
+ *   text: user => capitalize(user.name),
+ *   value: user => slugify(user.name),
+ * })
+ */
+export const convertToSelectOptions = <T = Record<string, any>>(
+    originArray: T[],
+    keyMap: Partial<Record<keyof SelectOption, keyof T | ((item: T) => any)>>
+): SelectOption[] => {
+    if (!Array.isArray(originArray)) {
+        return []
+    }
+
+    return originArray
+        .map((item) => {
+            const option: Partial<SelectOption> = {}
+
+            for (const [optionKey, source] of Object.entries(keyMap)) {
+                const value =
+                    typeof source === 'function'
+                        ? source(item)
+                        : item[source as keyof T]
+
+                if (value !== undefined) {
+                    option[optionKey as keyof SelectOption] = value
+                }
+            }
+
+            // Require at least a `value` and one of `text` or `userDisplayName`
+            if (option.value === undefined) {
+                return null
+            }
+
+            if (!option.text && !option.userDisplayName) {
+                return null
+            }
+
+            return option as SelectOption
+        })
+        .filter(Boolean) as SelectOption[]
+}

package/utils/dates.ts

@@ -0,0 +1,186 @@
+/**
+ * Formats an ISO date string to 'dd/mm/yyyy'.
+ *
+ * @param {string} isoDate - The ISO date string.
+ * @returns {string} The formatted date or 'Invalid date' if the input is invalid.
+ */
+export const formatISODateToDDMMYYYY = (isoDate: string): string => {
+    const date = new Date(isoDate)
+    return isNaN(date.getTime())
+        ? 'Invalid date'
+        : date.toLocaleDateString('en-GB') // Formats to dd/mm/yyyy
+}
+
+/**
+ * Converts a date string from `YYYY-MM-DD` format to `DD/MM/YYYY` format.
+ *
+ * @param {string} dateString - The date string in `YYYY-MM-DD` format.
+ * @returns {string} The formatted date string in `DD/MM/YYYY` format, or an empty string if the input is invalid.
+ */
+export const formatDateToDDMMYYYY = (dateString: string): string => {
+    if (!dateString) return ''
+
+    const [year, month, day] = dateString.split('-').map(Number)
+
+    // Ensure all values are valid before formatting
+    if (!year || !month || !day) return ''
+
+    return `${day.toString().padStart(2, '0')}/${month.toString().padStart(2, '0')}/${year}`
+}
+
+
+/**
+ * Returns a human-readable relative date string (e.g., "Today", "Yesterday", "2 days ago").
+ * If the date is older than 6 days, it formats as 'dd/mm/yyyy'.
+ *
+ * @param {string} isoDate - The ISO date string.
+ * @returns {string} The formatted relative date or standard date format.
+ */
+export const formatRelativeDate = (isoDate: string): string => {
+    const date = new Date(isoDate)
+    if (isNaN(date.getTime())) return 'Invalid date'
+
+    const now = new Date()
+    const nowMidnight = new Date(now.getFullYear(), now.getMonth(), now.getDate()) // Strip time from today
+    const dateMidnight = new Date(date.getFullYear(), date.getMonth(), date.getDate()) // Strip time from input
+
+    const diffInMs = nowMidnight.getTime() - dateMidnight.getTime()
+    const diffInDays = Math.floor(diffInMs / (1000 * 60 * 60 * 24)) // Convert ms to days
+
+    if (diffInDays === 0) return 'Today'
+    if (diffInDays === 1) return 'Yesterday'
+    if (diffInDays >= 2 && diffInDays <= 6) return `${diffInDays} days ago`
+
+    return formatISODateToDDMMYYYY(isoDate) // Fallback to dd/mm/yyyy
+}
+
+/**
+ * Formats a date string (YYYY-MM) into an object containing the full month name and year.
+ *
+ * @param {string} dateString - The date string in "YYYY-MM" format.
+ * @returns {{ month: string; year: number } | null} 
+ *          An object containing the full month name and year, or `null` if the input is invalid.
+ *
+ * @example
+ * formatDateToMonthYear("2025-03")
+ * // Returns: { month: "March", year: 2025 }
+ *
+ * formatDateToMonthYear("")
+ * // Returns: null
+ */
+export const formatDateToMonthYear = (
+    dateString: string
+): { month: string; year: number } | null => {
+    if (!dateString) return null
+
+    const [year, month] = dateString.split('-')
+    const date = new Date(Number(year), Number(month) - 1)
+
+    return {
+        month: date.toLocaleString('en-GB', { month: 'long' }),
+        year: date.getFullYear()
+    }
+}
+
+/**
+ * Adds a month to a given ISO date string.
+ * 
+ * @param isoDate - The ISO date string (e.g., '2025-03-15T00:00:00.000Z').
+ * @returns A new ISO date string with one month added.
+ */
+export const getNextMonthISODate = (isoDate: string): string => {
+    const date = new Date(isoDate)
+
+    // Set the new month while handling month overflow
+    date.setMonth(date.getMonth() + 1)
+
+    return date.toISOString()
+}
+
+/**
+ * Adds a year to a given ISO date string.
+ * 
+ * @param isoDate - The ISO date string (e.g., '2025-03-15T00:00:00.000Z').
+ * @returns A new ISO date string with one year added.
+ */
+export const getNextYearToISODate = (isoDate: string): string => {
+    const date = new Date(isoDate)
+
+    // Set the new year while maintaining the month/day
+    date.setFullYear(date.getFullYear() + 1)
+
+    return date.toISOString()
+}
+
+/**
+ * Formats a date (ISO string or timestamp) into a localized full date with optional time.
+ * Example: 
+ * - formatLocalizedDateTime('2025-09-20T10:15:22', 'en') → "September 20, 2025 (10:15:22)"
+ * - formatLocalizedDateTime(1761724212863, 'en', false) → "October 29, 2025"
+ * 
+ * @param dateInput - ISO date string or timestamp
+ * @param locale - The locale code (e.g. 'en', 'es', 'fr', 'de')
+ * @param showTime - Whether to include the time in the output
+ * @returns Formatted localized date string
+ */
+export function formatLocalizedDateTime(
+    dateInput: string | number, 
+    locale: string = 'en',
+    showTime: boolean = true
+): string {
+    if (!dateInput) return ''
+
+    const date = new Date(dateInput)
+    if (isNaN(date.getTime())) return ''
+
+    const dateFormatter = new Intl.DateTimeFormat(locale, {
+        year: 'numeric',
+        month: 'long',
+        day: 'numeric',
+    })
+
+    const formattedDate = dateFormatter.format(date)
+
+    if (!showTime) {
+        return formattedDate
+    }
+
+    const timeFormatter = new Intl.DateTimeFormat(locale, {
+        hour: '2-digit',
+        minute: '2-digit',
+        second: '2-digit',
+        hour12: false,
+    })
+
+    const formattedTime = timeFormatter.format(date)
+    return `${formattedDate} (${formattedTime})`
+}
+
+/**
+ * Formats a YYYY-MM-DD date string into a localized full date.
+ * Example:
+ * - formatLocalizedDate('2025-09-24', 'en') → "September 24, 2025"
+ * - formatLocalizedDate('2025-09-24', 'es') → "24 de septiembre de 2025"
+ *
+ * @param dateString - The date string in "YYYY-MM-DD" format
+ * @param locale - The locale code (e.g. 'en', 'es', 'fr', 'de')
+ * @returns Formatted localized date string
+ */
+export const formatLocalizedDate = (
+    dateString: string,
+    locale: string = 'en'
+): string => {
+    if (!dateString) return ''
+
+    const date = new Date(dateString)
+
+    if (isNaN(date.getTime())) return ''
+
+    const formatter = new Intl.DateTimeFormat(locale, {
+        year: 'numeric',
+        month: 'long',
+        day: 'numeric',
+    })
+
+    return formatter.format(date)
+}

package/utils/encoding.ts

@@ -0,0 +1,15 @@
+
+/**
+ * Encodes an SVG string to a Data URI.
+ *
+ * @param {string} svg - The SVG string.
+ * @returns {string} The encoded Data URI.
+ */
+export const encodeSvgToDataURI = (svg: string): string => {
+    return `data:image/svg+xml;charset=utf8,${encodeURIComponent(
+        svg.replace(
+            '<svg',
+            svg.includes('xmlns') ? '<svg' : '<svg xmlns="http://www.w3.org/2000/svg"'
+        )
+    )}`
+}

package/utils/errors.ts

@@ -0,0 +1,21 @@
+/**
+ * Returns an error message depending on the environment.
+ *
+ * @param devErrorMessage - Error message shown in development mode
+ * (usually raw details).
+ * @param prodErrorMessage - Error message shown in production mode
+ * (user-friendly localized message).
+ * @returns A string with the appropriate message.
+ *
+ */
+export const getEnvErrorMessage = (
+    devErrorMessage: string | Error,
+    prodErrorMessage: string
+): string => {
+    const devMessage =
+        typeof devErrorMessage === 'string'
+            ? devErrorMessage
+            : devErrorMessage.message
+
+    return process.dev ? devMessage : prodErrorMessage
+}

package/utils/events.ts

@@ -0,0 +1,64 @@
+import { AppNotification } from "../models/constants/notifications"
+
+/**
+ * A composable to handle clicks outside a specified element.
+ *
+ * @param elementRef - A reference to the target DOM element.
+ * @param callback - A function to call when a click outside the element is detected.
+ */
+export const useClickOutside = (
+    elementRef: Ref<HTMLElement | null>, 
+    callback: () => void
+): void => {
+    const handleClick = (event: MouseEvent): void => {
+        const element = elementRef.value
+
+        if (!(element instanceof HTMLElement)) return
+
+        if (!element.contains(event.target as Node)) {
+            callback()
+        }
+    }
+
+    watchEffect((cleanup) => {
+        document.addEventListener('mousedown', handleClick) 
+
+        cleanup(() => {
+            document.removeEventListener('mousedown', handleClick) 
+        })
+    })
+}
+
+
+/**
+ * Copies text to the clipboard and shows success or error notifications.
+ * @param text - The text to copy to the clipboard.
+ * @param successMessage - The success message to display.
+ * @param errorMessage - The error message to display.
+ */
+export const copyToClipboard = async (
+    text: string, 
+    successMessage: string = 'Copied to clipboard', 
+    errorMessage: string = 'Failed to copy to clipboard'
+): Promise<void> => {
+    if (!text) return
+
+    const { $toast } = useNuxtApp()
+
+    try {
+        await navigator.clipboard.writeText(text)
+        $toast.success(successMessage, { toastId: 'clipboard-success' })
+    } catch {
+        $toast.error(errorMessage, { toastId: 'clipboard-error' })
+    }
+}
+
+
+/**
+ * Opens the default email app with the given email address pre-filled.
+ * @param email - The email address to open in the default email client.
+ */
+export const openEmailApp = (email: string): void => {
+    if (!email) return
+    window.location.href = `mailto:${email}`
+}

package/utils/formFilters.ts

@@ -0,0 +1,10 @@
+/**
+ * Filters out non-alphabetic characters from a given string.
+ *
+ * @param {string} value - The input string to be filtered.
+ * @returns {string} The filtered string containing only alphabetic characters and spaces.
+ */
+export const filterAlphabetic = (value: string): string => {
+    return value.replace(/[^a-zA-ZÀ-ÿ\s]/g, '') // Removes non-alphabetic characters
+}
+

package/utils/formValidation.ts

@@ -0,0 +1,201 @@
+
+import { FieldError } from '@/models/constants/form'
+
+/**
+ * Validates a field value to ensure it is not empty, null, or undefined.
+ *
+ * @param value - The value to validate. Can be of any type.
+ * @param requiredFieldMessage - Optional custom error message to return if the value is invalid.
+ * @returns A string containing the error message if invalid, or null if the value is valid.
+ */
+export const validateField = (
+    value: unknown,
+    requiredFieldMessage?: string,
+): string | null => {
+    if (typeof value === 'string' && value.trim() === '') {
+        return requiredFieldMessage ?? FieldError.REQUIRED_FIELD
+    }
+
+    if (value === null || value === undefined) {
+        return requiredFieldMessage ?? FieldError.REQUIRED_FIELD
+    }
+
+    return null
+}
+
+/**
+ * Validates whether a given value is a valid email address.
+ *
+ * @param value - The value to validate as an email. Must be a non-empty string.
+ * @param requiredFieldMessage - Optional custom error message to return if the email is empty or missing.
+ * @param invalidEmailMessage - Optional custom error message to return if the email format is invalid.
+ * @returns A string containing the validation error message if invalid, or null if valid.
+ */
+export const validateEmail = (
+    value: unknown,
+    requiredFieldMessage?: string,
+    invalidEmailMessage?: string,
+): string | null => {
+    if (typeof value !== 'string' || !value.trim()) {
+        return requiredFieldMessage ?? FieldError.REQUIRED_EMAIL
+    }
+
+    const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/
+    if (!emailRegex.test(value)) {
+        return invalidEmailMessage ?? FieldError.INVALID_EMAIL
+    }
+
+    return null
+}
+
+/**
+ * Validates that two password values match.
+ *
+ * @param password - The original password.
+ * @param confirmPassword - The repeated password to compare.
+ * @param requiredFieldMessage - Optional custom error message to return if the value is invalid.
+ * @param mismatchMessage - Optional custom error message if the passwords do not match.
+ * @returns A string containing the error message if invalid, or null if the passwords match.
+ */
+export const validatePasswordMatch = (
+    password: unknown,
+    confirmPassword: unknown,
+    requiredFieldMessage?: string,
+    mismatchMessage?: string,
+): string | null => {
+    if (
+        typeof password !== 'string' ||
+        !password.trim() ||
+        typeof confirmPassword !== 'string' ||
+        !confirmPassword.trim()
+    ) {
+        return requiredFieldMessage ?? FieldError.REQUIRED_FIELD
+    }
+
+    if (password !== confirmPassword) {
+        return mismatchMessage ?? FieldError.PASSWORDS_DO_NOT_MATCH
+    }
+
+    return null
+}
+
+/**
+ * Validates that an end date is not before a start date.
+ *
+ * @param startDate - The start date to compare from.
+ * @param endDate - The end date to compare against.
+ * @param requiredFieldMessage - Optional custom message if either date is missing or invalid.
+ * @param invalidRangeMessage - Optional custom message if the end date is before the start date.
+ * @returns A string containing the error message if invalid, or null if the range is valid.
+ */
+export const validateDateRange = (
+    startDate: unknown,
+    endDate: unknown,
+    requiredFieldMessage = FieldError.REQUIRED_FIELD,
+    invalidRangeMessage = FieldError.INVALID_DATE_RANGE,
+): string | null => {
+    if (
+        typeof startDate !== 'string' || !startDate ||
+        typeof endDate !== 'string' || !endDate
+    ) {
+        return requiredFieldMessage
+    }
+
+    const start = new Date(startDate)
+    const end = new Date(endDate)
+
+    if (isNaN(start.getTime()) || isNaN(end.getTime()) || start > end) {
+        return invalidRangeMessage
+    }
+
+    return null
+}
+
+/**
+ * Validates whether a given value is a valid URL.
+ *
+ * @param value - The value to validate as a URL.
+ * @param requiredFieldMessage - Optional custom message if the value is empty.
+ * @param invalidUrlMessage - Optional custom message if the URL format is invalid.
+ * @returns A string containing the error message if invalid, or null if valid.
+ */
+export const validateUrl = (
+    value: unknown,
+    requiredFieldMessage = FieldError.REQUIRED_FIELD,
+    invalidUrlMessage = FieldError.INVALID_URL,
+): string | null => {
+    if (typeof value !== 'string' || !value.trim()) {
+        return requiredFieldMessage
+    }
+
+    try {
+        new URL(value)
+        return null
+    } catch {
+        return invalidUrlMessage
+    }
+}
+
+/**
+ * Validates a checkbox/switch field to ensure it is checked (true).
+ *
+ * @param value - The value to validate. Should be a boolean.
+ * @param requiredFieldMessage - Optional custom error message to return if the checkbox is not checked.
+ * @returns A string containing the error message if unchecked, or null if valid.
+ */
+export const validateBooleanField = (
+    value: unknown,
+    requiredFieldMessage = FieldError.REQUIRED_FIELD,
+): string | null => {
+    if (typeof value !== 'boolean' || value === false) {
+        return requiredFieldMessage
+    }
+
+    return null
+}
+
+/**
+ * Validates that a given value is a non-empty array (or meets min/max length criteria).
+ *
+ * @param value - The value to validate. Should be an array.
+ * @param requiredFieldMessage - Custom error message if value is not a valid array or empty.
+ * @param minLength - Optional minimum number of items required in the array.
+ * @param maxLength - Optional maximum number of items allowed in the array.
+ * @param lengthErrorMessage - Optional custom error message if min/max length is violated.
+ * @returns A string containing the error message if invalid, or null if valid.
+ */
+export const validateArrayField = (
+    value: unknown,
+    requiredFieldMessage = FieldError.REQUIRED_FIELD,
+    minLength?: number,
+    maxLength?: number,
+    lengthErrorMessage?: string,
+): string | null => {
+    // Must be an array
+    if (!Array.isArray(value)) {
+        return requiredFieldMessage
+    }
+
+    // Must not be empty
+    if (value.length === 0) {
+        return requiredFieldMessage
+    }
+
+    // Check minimum length
+    if (typeof minLength === 'number' && value.length < minLength) {
+        return (
+            lengthErrorMessage ??
+            `At least ${minLength} item${minLength > 1 ? 's' : ''} required`
+        )
+    }
+
+    // Check maximum length
+    if (typeof maxLength === 'number' && value.length > maxLength) {
+        return (
+            lengthErrorMessage ??
+            `No more than ${maxLength} item${maxLength > 1 ? 's' : ''} allowed`
+        )
+    }
+
+    return null
+}

package/utils/grids.ts

@@ -0,0 +1,47 @@
+/**
+ * Generates Tailwind CSS grid class string based on column settings for mobile and desktop breakpoints.
+ *
+ * @param cols - Number of columns for large screens (typically 2, 3, or 4).
+ * @param tabletCols - Number of columns for mobile screens (typically 2).
+ * @param mobileCols - Number of columns for mobile screens (typically 1 or 2).
+ * @param gapClass - Tailwind gap utility class to control spacing between grid items (default is 'gap-6').
+ * @returns A string of Tailwind utility classes to control the grid layout responsively.
+ *
+ */
+export const getGridClasses = (
+    cols: number, 
+    tabletCols: number, 
+    mobileCols: number,
+    gapClass = 'gap-6'
+): string => {
+    const baseClasses = 'grid w-full'
+
+    const mobileColsMapping: Record<number, string> = {
+        1: 'grid-cols-1',
+        2: 'grid-cols-2',
+        3: 'grid-cols-3',
+        4: 'grid-cols-4',
+    }
+
+    const tabletColsMapping: Record<number, string> = {
+        1: 'sm:grid-cols-1',
+        2: 'sm:grid-cols-2',
+        3: 'sm:grid-cols-3',
+        4: 'sm:grid-cols-4',
+    }
+
+    const colsMapping: Record<number, string> = {
+        1: 'lg:grid-cols-1',
+        2: 'lg:grid-cols-2',
+        3: 'lg:grid-cols-3',
+        4: 'lg:grid-cols-4',
+        5: 'lg:grid-cols-5',
+        6: 'lg:grid-cols-6',
+    }
+
+    const mobileClass = mobileColsMapping[mobileCols] ?? 'grid-cols-1'
+    const tabletClass = tabletColsMapping[tabletCols] ?? 'sm:grid-cols-2'
+    const desktopClass = colsMapping[cols] ?? 'lg:grid-cols-3'
+
+    return `${baseClasses} ${gapClass} ${mobileClass} ${tabletClass} ${desktopClass}`
+}

package/utils/navigation.ts

@@ -0,0 +1,15 @@
+/**
+ * Navigates to the previous URL using the router's back method.
+ * If no history exists, it redirects to a specified fallback URL.
+ * 
+ * @param fallback - The URL to navigate to if no history is available.
+ */
+export const goBack = (fallback = '/') => {
+    const router = useRouter()
+
+    if (window.history.length > 1) {
+        router.back()
+    } else {
+        router.push(fallback) 
+    }
+}

package/utils/pages.ts

@@ -0,0 +1,18 @@
+
+/**
+ * Generates a formatted page title based on the specified format.
+ *
+ * @param {string} pageTitle - The main title of the page.
+ * @param {string} appName - The name of the app.
+ * @param {PageTitleFormat} [format=PageTitleFormat.FULL] - The format of the title, defaulting to FULL.
+ * @returns {string} The formatted page title.
+ */
+export const pageTitle = (
+    pageTitle = 'Page title', 
+    appName = 'App name', 
+    format: PageTitleFormat = PageTitleFormat.FULL
+) => {
+    return format === PageTitleFormat.FULL 
+        ? `${pageTitle} | ${appName}` 
+        : pageTitle
+}

package/utils/passwords.ts

@@ -0,0 +1,74 @@
+
+/**
+ * Evaluates secure password conditions.
+ * @param password - The password string to evaluate.
+ * @returns An object indicating whether each condition is satisfied.
+ */
+export const evaluateSecurePasswordConditions = (password: string) => {
+    return {
+        isLongEnough: password.length >= 12,
+        hasMixedCase: /[a-z]/.test(password) && /[A-Z]/.test(password),
+        hasNumbersAndSpecialChars: /[0-9]/.test(password) && /[^a-zA-Z0-9]/.test(password),
+    }
+}
+
+/**
+ * Checks if all secure password conditions are fulfilled.
+ * @param password - The password string to validate.
+ * @returns `true` if all conditions are met, otherwise `false`.
+ */
+export const isSecurePassword = (password: string): boolean => {
+    const conditions = evaluateSecurePasswordConditions(password)
+    for (const key in conditions) {
+        if (!conditions[key as keyof typeof conditions]) return false
+    }
+    return true
+}
+
+/**
+ * Generates a secure password that meets specified security requirements.
+ *
+ * @param length - The desired length of the password (default is 12 characters).
+ * @returns A randomly generated, secure password string.
+ *
+ * The generated password will:
+ * 1. Be at least 12 characters long (or the specified length).
+ * 2. Include at least one lowercase letter, one uppercase letter, one number, and one special character.
+ * 3. Be shuffled to prevent predictable patterns.
+ */
+export const generateSecurePassword = (length: number = 12): string => {
+    const getRandomChar = (charset: string): string => {
+        return charset[Math.floor(Math.random() * charset.length)]!
+    }
+
+    const lowerCaseChars = 'abcdefghijklmnopqrstuvwxyz'
+    const upperCaseChars = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ'
+    const numericChars = '0123456789'
+    const specialChars = '!@#$%^&*()-_=+[]{}|;:,.<>?'
+
+    let password = ''
+
+    // Ensure the password contains at least one character from each required set
+    password += getRandomChar(lowerCaseChars)
+    password += getRandomChar(upperCaseChars)
+    password += getRandomChar(numericChars)
+    password += getRandomChar(specialChars)
+
+    // Fill the rest of the password with random characters from all sets
+    const allChars = lowerCaseChars + upperCaseChars + numericChars + specialChars
+    while (password.length < length) {
+        password += getRandomChar(allChars)
+    }
+
+    // Shuffle the password to make it less predictable
+    password = password.split('').sort(() => Math.random() - 0.5).join('')
+
+    // Ensure the password meets all conditions
+    const conditions = evaluateSecurePasswordConditions(password)
+    if (!conditions.isLongEnough || !conditions.hasMixedCase || !conditions.hasNumbersAndSpecialChars) {
+        // Recursively generate a new password if conditions are not met
+        return generateSecurePassword(length)
+    }
+
+    return password
+}

package/utils/pdfExport.ts

@@ -0,0 +1,52 @@
+import jsPDF from "jspdf"
+import autoTable from "jspdf-autotable"
+import type { Headers } from "@/models/types/pdfExportTable"
+
+/**
+ * Exports data to a PDF file.
+ * @param {Array<Record<string, any>>} data - The data to export.
+ * @param {string} title - The title of the PDF.
+ * @param {string} fileName - The name of the exported file.
+ * @param {Headers} headers - Custom headers structured like the Excel headers.
+ */
+export function exportDataToPDF(
+    data: Array<Record<string, any>>,
+    title: string,
+    fileName: string,
+    headers: Headers
+): void {
+    const doc = new jsPDF()
+
+    // Transform headers object into an array of formatted headers
+    const formattedHeaders = Object.entries(headers).map(([label, config]) => ({
+        label,
+        field: typeof config === "string" ? config : config.field,
+        callback:
+            typeof config === "object" && config.callback
+                ? config.callback
+                : null,
+    }))
+
+    // Map data rows to match headers
+    const tableData = data.map((row) =>
+        formattedHeaders.map(({ field, callback }) => {
+            const value = field
+                .split(".")
+                .reduce((obj, key) => obj && obj[key], row)
+            return callback ? callback(value) : value
+        })
+    )
+
+    doc.text(title, 14, 15)
+
+    // Use only the header keys for the `head` property in autoTable
+    autoTable(doc, {
+        head: [formattedHeaders.map(({ label }) => label)],
+        body: tableData,
+        startY: 20,
+        styles: { font: "helvetica", fontSize: 10, overflow: "linebreak" },
+        headStyles: { fillColor: [22, 160, 133] },
+    })
+
+    doc.save(fileName)
+}

package/utils/rating.ts

@@ -0,0 +1,31 @@
+/**
+ * Returns an array of MDI icon names representing a indicator rating.
+ *
+ * @param value - A number from 0 to 5 (can include 0.5 steps). Will be clamped between 0 and 5.
+ * @returns An array of 5 icon strings representing full, half, or empty indicator.
+ *
+ */
+export const getRatingIndicator = (
+    value: number,
+    emptyIndicator: string = 'mdiStarOutline',
+    halfIndicator: string = 'mdiStarHalfFull',
+    fullIndicator: string = 'mdiStar'
+): string[] => {
+    const clamped = Math.min(5, Math.max(0, Math.round(value * 2) / 2))
+    const icons: string[] = []
+    let remaining = clamped
+
+    for (let i = 0; i < 5; i++) {
+        if (remaining >= 1) {
+            icons.push(fullIndicator)
+        } else if (remaining >= 0.5) {
+            icons.push(halfIndicator)
+        } else {
+            icons.push(emptyIndicator)
+        }
+        remaining -= 1
+    }
+
+    return icons
+}
+

package/utils/strings.ts

@@ -0,0 +1,148 @@
+/**
+ * Trims a string to the specified maximum length and appends "..." if it exceeds the limit.
+ * Optionally, appends a "Read more" link if `readMoreLink` is provided.
+ *
+ * @param {string} inputString - The text string to be trimmed.
+ * @param {number} maxLength - The maximum allowed length of the string.
+ * @param {string} [readMoreText='Read more'] - Optional text for the "Read more" link.
+ * @param {string} [readMoreLink] - Optional URL for the "Read more" link. If omitted, only "..." is appended.
+ * @returns {string} The trimmed string, with "..." or a "Read more" link if truncated.
+ * @throws {Error} If `inputString` is not a string.
+ * @throws {Error} If `maxLength` is not a number or negative.
+ */
+export const trimText = (
+    inputString: string, 
+    maxLength: number, 
+    readMoreText: string = 'Read more', 
+    readMoreLink?: string
+): string => {
+    if (typeof inputString !== 'string') {
+        throw new Error('The inputString parameter must be a text string')
+    }
+    if (typeof maxLength !== 'number' || maxLength < 0) {
+        throw new Error('The maxLength parameter must be a non-negative number')
+    }
+
+    // Return the original text if it's within the max length
+    if (inputString.length <= maxLength) {
+        return inputString
+    }
+
+    // Trim text
+    const trimmedText = inputString.substring(0, maxLength) + '...'
+
+    // Append "Read more" link only if readMoreLink is provided
+    return readMoreLink 
+        ? `${trimmedText} <a href="${readMoreLink}" target="_blank" rel="noopener noreferrer" class="text-text-primary hover:text-text-hover">(${readMoreText})</a>` 
+        : trimmedText
+
+}
+
+/**
+ * Highlights a keyword inside a given text by wrapping matches in a span with a highlight class.
+ *
+ * @param {string} text - The full text where the keyword should be highlighted.
+ * @param {string} keyword - The word to highlight.
+ * @param {string} highlightClass - Optional Tailwind or custom CSS class for styling the highlight.
+ * @returns {string} The modified text with highlighted words wrapped in a span.
+ */
+export const highlightKeywordInText = (
+    text: string = '', 
+    keyword: string = '', 
+    highlightClass = 'text-text-active font-semibold'
+): string => {
+    if (!text.trim()) return text 
+    if (!keyword.trim()) return text
+
+    // Escape special characters in the keyword to prevent regex errors
+    const escapedKeyword = keyword.replace(/[-\/\\^$*+?.()|[\]{}]/g, '\\$&')
+
+    // Create a case-insensitive regular expression for the keyword
+    const regex = new RegExp(`(${escapedKeyword})`, 'gi')
+
+    // Replace matching words with a highlighted <span>
+    return text.replace(regex, `<span class="${highlightClass}">$1</span>`)
+}
+
+/**
+ * Converts a string into a slug format.
+ * - Converts to lowercase
+ * - Removes special characters
+ * - Replaces spaces with hyphens
+ *
+ * @param {string} text - The input string to slugify
+ * @returns {string} - The slugified string
+ */
+export const convertStringIntoSlugFormat = (text: string): string => {
+    return text
+        .toLowerCase()
+        .replace(/[^a-z0-9\s]/g, '') // Remove special characters
+        .replace(/\s+/g, '-') // Replace spaces with dashes
+        .trim()
+}
+
+/**
+ * Converts the first letter of a string to lowercase while keeping the rest unchanged.
+ * 
+ * @param {string} str - The input string.
+ * @returns {string} The transformed string with the first letter in lowercase.
+ */
+export const lowercaseFirstLetter = (str: string): string => {
+    if (!str) return str
+    return str.charAt(0).toLowerCase() + str.slice(1)
+}
+
+/**
+ * Converts the first letter of a string to upperrcase while keeping the rest unchanged.
+ * 
+ * @param {string} str - The input string.
+ * @returns {string} The transformed string with the first letter in uppercase.
+ */
+export const capitalizeFirstLetter = (str: string): string => {
+    if (!str) return str
+    return str.charAt(0).toUpperCase() + str.slice(1)
+}
+
+/**
+ * Extracts the last four digits from a given credit card number.
+ *
+ * @param {string} pan - The full credit card number (PAN).
+ * @returns {string} The last four digits of the card number, or an empty string if the input is invalid.
+ */
+export const getCreditCardLastFourNumbers = (pan: string): string => {
+    if (!pan) return ''
+    return pan.slice(-4)
+}
+
+/**
+ * Returns the full name of a user by combining first and last names.
+ *
+ * @param firstName - The user's first name.
+ * @param lastName - The user's last name.
+ * @returns The concatenated full name in the format "FirstName LastName".
+ */
+export const getUserFullName = (firstName: string, lastName: string): string => {
+    return `${firstName} ${lastName}`
+}
+
+/**
+ * Extracts the initials from a given input.
+ *
+ * - If the name is empty or invalid, returns "TU" by default.
+ * - Takes the first character of up to two words to form the initials.
+ *
+ * @param input - The input string to generate initials from
+ * @returns A string with the initials in uppercase (e.g., "John Doe" -> "JD")
+ * 
+ */
+export const getInitials = (input: string): string => {
+    const words = input?.split(' ').filter(Boolean)
+  
+    if (!words?.length) return 'TU'
+  
+    const initials = words.slice(0, 2).map(word => word[0]?.toUpperCase()).join('')
+  
+    return initials || 'TU'
+}
+  
+  

package/utils/users.ts

@@ -0,0 +1,31 @@
+/**
+ * Generates a unique username based on the user's first name and last names.
+ * The username follows the format: `{firstName}.{lastNames}{randomNumber}`.
+ *
+ * @param {string} firstName - The user's first name.
+ * @param {string} lastNames - The user's last names (can include spaces).
+ * @returns {string} A generated username in lowercase with a random 4-digit number.
+ */
+export const generateUsername = (firstName: string, lastNames: string): string => {
+    const normalizedFirstName = firstName.trim().toLowerCase()
+    const normalizedLastNames = lastNames.trim().toLowerCase().replace(/\s+/g, '')
+    
+    const randomNumber = Math.floor(1000 + Math.random() * 9000)
+    
+    return `${normalizedFirstName}.${normalizedLastNames}${randomNumber}`
+}
+
+/**
+ * Generates a display name using the first name and only the first last name.
+ * Returns 'Test User' if either parameter is null or undefined.
+ * 
+ * @param {string | null | undefined} firstName - The user's first name.
+ * @param {string | null | undefined} lastNames - The user's full last names (may contain multiple words).
+ * @returns {string} The formatted display name or 'Test User' if inputs are missing.
+ */
+export const getUserDisplayName = (firstName?: string | null, lastNames?: string | null): string => {
+    if (!firstName || !lastNames) return 'Test User'
+
+    const firstLastName = lastNames.split(' ')[0] // Get only the first last name
+    return `${firstName} ${firstLastName}`
+}