@tacdaed/fragments 1.0.0-beta.0 → 1.0.0-beta.2

package/src/lib/types/base.types.ts

@@ -0,0 +1,23 @@
+export type TBaseStyle =
+  | 'default'
+  | 'primary'
+  | 'secondary'
+  | 'tertiary'
+  | 'dark'
+  | 'light'
+  | 'info'
+  | 'success'
+  | 'warning'
+  | 'danger'
+  | 'outline-primary'
+  | 'outline-secondary'
+  | 'outline-tertiary'
+  | 'outline-dark'
+  | 'outline-light'
+  | 'outline-info'
+  | 'outline-success'
+  | 'outline-warning'
+  | 'outline-danger';
+
+export type TBaseSize = 'small' | 'medium' | 'large';
+export type TBasePosition =  'top' | 'left' | 'right' | 'bottom';

package/src/lib/types/common.types.ts

@@ -0,0 +1,98 @@
+/**
+ * Represents a value that can be used in Angular's `ngClass` directive
+ * to determine whether a class should be applied.
+ * - `boolean`: apply class if true, remove if false
+ * - `number`: treated as truthy if non-zero, falsy if zero
+ * - `string`: directly represents a class name
+ * - `null` or `undefined`: no class applied
+ */
+export type NgClassValue = boolean | number | string | null | undefined;
+
+/**
+ * Describes the different formats supported by a custom implementation
+ * of Angular's `ngClass`. It allows:
+ * - A single class name as a string
+ * - An array of class names
+ * - A Set of class names
+ * - An object map where keys are class names and values determine whether they should be applied
+ * - `null` or `undefined` to apply no classes
+ */
+export type TCustomNgClass =
+  | string
+  | string[]
+  | Set<string>
+  | { [klass: string]: NgClassValue }
+  | null
+  | undefined;
+
+/**
+ * Creates a type that removes the properties of `U` from `T`
+ * by marking them as optional and setting their type to `never`.
+ * Useful for constructing mutually exclusive types.
+ */
+export type Without<T, U> = { [P in Exclude<keyof T, keyof U>]?: never };
+
+/**
+ * Constructs an exclusive OR (XOR) type between `T` and `U`.
+ * Ensures that either `T` or `U` is allowed, but not both at the same time.
+ * - If both are objects, it enforces mutual exclusivity at the property level.
+ * - If not objects, it falls back to a simple union (`T | U`).
+ */
+export type XOR<T, U> = T | U extends object
+  ? (Without<T, U> & U) | (Without<U, T> & T)
+  : T | U;
+
+/**
+ * Represents a generic function type that takes a single argument of any type
+ * and returns a value of type `T`.
+ *
+ * @template T The return type of the function.
+ */
+export type GenericFunction<T> = (arg0: unknown) => T;
+
+/**
+ * Represents a mutually exclusive type between `T` and `K`.
+ * Only one of the two types can be used at a time.
+ *
+ * @template T The first type option.
+ * @template K The second type option.
+ */
+export type TBehaviourAction<T, K> = XOR<T, K>;
+
+/**
+ * Represents an array that contains at least one element of type `T`.
+ * Ensures that the array is never empty by requiring an element at index 0.
+ *
+ * @template T The type of the elements in the array.
+ */
+export type ArrayOneOrMore<T> = { 0: T } & Array<T>;
+
+export type DateFormat =
+  | "dd/MM/yyyy"
+  | "MM/dd/yyyy"
+  | "yyyy-MM-dd"
+  | "dd-MM-yyyy"
+  | "dd.MM.yyyy"
+  | "yyyy/MM/dd"
+  | "MMM dd, yyyy"
+  | "MMMM dd, yyyy"
+  | "dd MMM yyyy"
+  | "dd MMMM yyyy"
+  | "yyyyMMdd";
+
+export type TimeFormat = "HH:mm:ss" | "HH:mm" | "hh:mm:ss a" | "hh:mm a";
+
+export type DateTimeFormat =
+  | "dd/MM/yyyy HH:mm"
+  | "dd/MM/yyyy HH:mm:ss"
+  | "MM/dd/yyyy HH:mm"
+  | "MM/dd/yyyy hh:mm a"
+  | "yyyy-MM-dd'T'HH:mm"
+  | "yyyy-MM-dd'T'HH:mm:ss"
+  | "dd MMM yyyy HH:mm"
+  | "dd MMM yyyy hh:mm a"
+  | "MMMM dd, yyyy HH:mm"
+  | "MMMM dd, yyyy hh:mm a"
+  | "yyyyMMdd HH:mm"
+  | "yyyyMMdd HH:mm:ss";
+

package/src/lib/types/form.types.ts

@@ -0,0 +1,5 @@
+import { FormControl } from '@angular/forms';
+
+export type TypeForm<T> = {
+  [K in keyof T]: FormControl<T[K]>;
+};

package/src/lib/utils/common.utils.ts

@@ -0,0 +1,53 @@
+import { ActivatedRoute } from '@angular/router';
+
+type direction = 'asc' | 'desc';
+
+export function generateId(value?: string): string {
+  const valueRandom: number = Math.floor(Math.random() * 10000000) + 1;
+  return value ? value + '-' + valueRandom : String(valueRandom);
+}
+
+export function generateNumberId(): number {
+  return Math.floor(Math.random() * 10000000) + 1;
+}
+
+export function isObjectEmpty(obj: any): boolean {
+  return Object.keys(obj).length <= 0;
+}
+
+export function paginationList<T>(
+  lista: Array<T>,
+  pageSize: number,
+  page: number
+) {
+  lista = lista.slice(+pageSize * (+page - 1), +pageSize * +page);
+  return lista;
+}
+
+export function orderList<T>(
+  lista: Array<T>,
+  orderFields: any,
+  direction: direction
+) {
+  orderFields = Array.isArray(orderFields)
+    ? orderFields.join('.')
+    : orderFields;
+  lista.sort((a: any, b: any) => {
+    if (direction === 'asc') {
+      return a[orderFields] > b[orderFields] ? 1 : -1;
+    } else {
+      return a[orderFields] < b[orderFields] ? 1 : -1;
+    }
+  });
+  return lista;
+}
+
+export function getActivatedRouteChild(
+  activatedRoute: ActivatedRoute
+): ActivatedRoute {
+  if (activatedRoute.firstChild) {
+    return getActivatedRouteChild(activatedRoute.firstChild);
+  } else {
+    return activatedRoute;
+  }
+}

package/src/lib/utils/date.utils.ts

@@ -0,0 +1,474 @@
+import { InputTimePartial } from "../components/input/input-type";
+import { DateFormat, DateTimeFormat, TimeFormat } from "../types/common.types";
+
+export function isValidDate(dateString: string, format: DateFormat = "yyyy-MM-dd"): boolean {
+  if (format !== 'yyyy-MM-dd') {
+    const isoString = convertStringToISODate(dateString, format);
+
+    if (!isoString)
+      return false;
+
+    const dateObj = new Date(isoString);
+    return !isNaN(dateObj.getTime());
+  }
+
+  const dateObject: Date = new Date(dateString);
+  return !isNaN(dateObject.getTime());
+}
+
+/**
+ * Checks if a given datetime string matches a given format and represents a valid date/time.
+ */
+export function isValidDateTime(
+  dateTimeString: string,
+  format: DateTimeFormat = "yyyy-MM-dd'T'HH:mm"
+): boolean {
+  if (!dateTimeString)
+    return false;
+
+  // If it's not the standard ISO-like format, convert it manually
+  if (format !== "yyyy-MM-dd'T'HH:mm" && format !== "yyyy-MM-dd'T'HH:mm:ss") {
+    const isoString = convertStringToISODateTime(dateTimeString, format);
+
+    if (!isoString)
+      return false;
+
+    const dateObj = new Date(isoString);
+    return !isNaN(dateObj.getTime());
+  }
+
+  // If it's already in ISO-like format, just check directly
+  const dateObject = new Date(dateTimeString);
+  return !isNaN(dateObject.getTime());
+}
+
+export function convertStringToISODate(dateString: string, format: DateFormat = "yyyy-MM-dd"): string | null {
+  const formatRegex: RegExp = buildDateFormatRegex(format);
+  const match = formatRegex.exec(dateString);
+
+  if (!match?.groups) return null;
+
+  const { day, month, year } = match.groups;
+
+  const d = parseInt(day, 10);
+  const m = parseInt(month, 10) - 1;
+  let y = parseInt(year, 10);
+
+  if (year.length === 2) {
+    y += y >= 70 ? 1900 : 2000;
+  }
+
+  const date = new Date(y, m, d);
+
+  if (date.getFullYear() !== y || date.getMonth() !== m || date.getDate() !== d) {
+    return null;
+  }
+
+  return date.toISOString();
+}
+
+/**
+ * Converts a date-time string (in a given format) to an ISO 8601 string.
+ * Returns null if invalid or if the string doesn't match the format.
+ */
+export function convertStringToISODateTime(
+  dateTimeString: string,
+  format: DateTimeFormat = "yyyy-MM-dd'T'HH:mm"
+): string | null {
+  const formatRegex: RegExp = buildDateTimeFormatRegex(format);
+  const match = formatRegex.exec(dateTimeString.trim());
+
+  if (!match?.groups) return null;
+
+  const { day, month, year, hour, minute, second, period } = match.groups;
+
+  const d = parseInt(day, 10);
+  const m = parseInt(month, 10) - 1;
+  let y = parseInt(year, 10);
+  let h = parseInt(hour ?? '0', 10);
+  const min = parseInt(minute ?? '0', 10);
+  const s = parseInt(second ?? '0', 10);
+
+  // Handle two-digit years
+  if (year.length === 2) {
+    y += y >= 70 ? 1900 : 2000;
+  }
+
+  // Handle AM/PM
+  if (period) {
+    const p = period.toUpperCase();
+    if (p === 'PM' && h < 12) h += 12;
+    if (p === 'AM' && h === 12) h = 0;
+  }
+
+  const date = new Date(y, m, d, h, min, s);
+
+  // Validation: ensure components didn’t overflow
+  if (
+    date.getFullYear() !== y ||
+    date.getMonth() !== m ||
+    date.getDate() !== d ||
+    date.getHours() !== h ||
+    date.getMinutes() !== min ||
+    date.getSeconds() !== s
+  ) {
+    return null;
+  }
+
+  return date.toISOString();
+}
+
+export function convertStringToDate(dateString: string, format: DateFormat = "yyyy-MM-dd"): Date | null {
+  const formatRegex: RegExp = buildDateFormatRegex(format);
+  const match = formatRegex.exec(dateString);
+
+  if (!match?.groups) return null;
+
+  const { day, month, year } = match.groups;
+
+  const d = parseInt(day, 10);
+  const m = parseInt(month, 10) - 1;
+  let y = parseInt(year, 10);
+
+  if (year.length === 2) {
+    y += y >= 70 ? 1900 : 2000;
+  }
+
+  return new Date(y, m, d);
+}
+
+export function convertStringToTime(
+  timeString: string,
+  format: TimeFormat = "HH:mm"
+): number | null {
+  const regex = buildTimeFormatRegex(format);
+  const match = regex.exec(timeString);
+
+  if (!match?.groups) return null;
+
+  let hours = 0;
+  const minutes = match.groups["minute"] ? parseInt(match.groups["minute"], 10) : 0;
+  const seconds = match.groups["second"] ? parseInt(match.groups["second"], 10) : 0;
+
+  if (match.groups["hour24"]) {
+    hours = parseInt(match.groups["hour24"], 10);
+  } else if (match.groups["hour12"]) {
+    hours = parseInt(match.groups["hour12"], 10);
+    const period = match.groups["period"]?.toUpperCase();
+    if (period) {
+      if (hours === 12) hours = period === "AM" ? 0 : 12;
+      else if (period === "PM") hours += 12;
+    }
+  }
+
+  return hours * 3600 + minutes * 60 + seconds;
+}
+
+/**
+ * Converts a datetime string (based on a given format) into a Date object.
+ * Returns null if parsing fails or values are invalid.
+ */
+export function convertStringToDateTime(
+  dateTimeString: string,
+  format: DateTimeFormat = "yyyy-MM-dd'T'HH:mm"
+): Date | null {
+  const regex = buildDateTimeFormatRegex(format);
+  const match = regex.exec(dateTimeString.trim());
+
+  if (!match?.groups) return null;
+
+  const separatorMatch = format.match(/( |T)/);
+  let datePart: string = format;
+  let timePart: string | null = null;
+
+  if (separatorMatch) {
+    const separator = separatorMatch[0];
+    const parts = format.split(separator);
+    datePart = parts[0];
+    timePart = parts[1] ?? null;
+  }
+
+  const dateString = timePart
+    ? dateTimeString.split(/T| /)[0]
+    : dateTimeString;
+
+  const timeString = timePart
+    ? dateTimeString.split(/T| /)[1]
+    : undefined;
+
+  const date = convertStringToDate(dateString, datePart as any);
+  if (!date) return null;
+
+  let totalSeconds = 0;
+  if (timeString && timePart) {
+    const seconds = convertStringToTime(timeString, timePart as any);
+    if (seconds == null) return null;
+    totalSeconds = seconds;
+  }
+
+  const hours = Math.floor(totalSeconds / 3600);
+  const minutes = Math.floor((totalSeconds % 3600) / 60);
+  const seconds = totalSeconds % 60;
+
+  date.setHours(hours, minutes, seconds, 0);
+
+  return date;
+}
+
+/**
+ * Builds a regex to validate date strings based on the provided format.
+ * Supports formats like "dd/MM/yyyy", "MM-dd-yyyy", "yyyy.MM.dd", etc.
+ * @param format The date format string
+ */
+export function buildDateFormatRegex(format: string): RegExp {
+  const escaped = format.replace(/[-/.]/g, m => `\\${m}`);
+
+  const pattern = escaped
+    .replace("dd", "(?<day>\\d{2})")
+    .replace("MM", "(?<month>\\d{2})")
+    .replace("yyyy", "(?<year>\\d{4})")
+    .replace("yy", "(?<year>\\d{2})");
+
+  return new RegExp(`^${pattern}$`);
+}
+
+/**
+ * Builds a regex to validate time strings based on the provided format.
+ * Supports formats like "HH:mm", "hh:mm a", "HH:mm:ss", etc.
+ * @param format The time format string
+ */
+export function buildTimeFormatRegex(format: string): RegExp {
+  const escaped = format.replace(/[-:. ]/g, m => `\\${m}`);
+  const pattern = escaped
+    .replace("HH", "(?<hour24>[01]?[0-9]|2[0-3])")
+    .replace("hh", "(?<hour12>0?[1-9]|1[0-2])")
+    .replace("mm", "(?<minute>[0-5]?[0-9])")
+    .replace("ss", "(?<second>[0-5]?[0-9])")
+    .replace("a", "(?<period>AM|PM|am|pm)");
+
+  return new RegExp(`^${pattern}$`);
+}
+/**
+ * Builds a regex to match full date-time strings.
+ * Handles both date and time tokens in a single format string (with optional AM/PM).
+ */
+export function buildDateTimeFormatRegex(format: string): RegExp {
+  // Try to find a separator between date and time parts
+  const separatorMatch = format.match(/( |T)/);
+  if (!separatorMatch) {
+    // Fallback: only date
+    return buildDateFormatRegex(format);
+  }
+
+  const separator = separatorMatch[0];
+
+  // Handle formats like "MM/dd/yyyy hh:mm a" or "dd/MM/yyyy HH:mm:ss"
+  const firstSplit = format.split(separator);
+
+  // If there's an AM/PM part, join everything after the first split back together
+  const datePart = firstSplit[0];
+  const timePart = firstSplit.slice(1).join(separator);
+
+  const dateRegexSource = buildDateFormatRegex(datePart)
+    .source.replace(/^\^|\$$/g, '');
+  const timeRegexSource = buildTimeFormatRegex(timePart)
+    .source.replace(/^\^|\$$/g, '');
+
+  const fullPattern = `^${dateRegexSource}${separator}${timeRegexSource}$`;
+  return new RegExp(fullPattern);
+}
+
+/**
+ * Converts a Date object into a string according to the specified format.
+ */
+export function formatDateToString(date: Date, format: DateFormat = 'yyyy-MM-dd'): string {
+  const day = String(date.getDate()).padStart(2, "0");
+  const month = String(date.getMonth() + 1).padStart(2, "0");
+  const year = String(date.getFullYear());
+
+  const shortMonthNames = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"];
+  const longMonthNames = ["January", "February", "March", "April", "May", "June", "July", "August", "September", "October", "November", "December"];
+
+  return format
+    .replace("dd", day)
+    .replace("MM", month)
+    .replace("yyyy", year)
+    .replace("yy", year.slice(-2))
+    .replace("MMM", shortMonthNames[date.getMonth()])
+    .replace("MMMM", longMonthNames[date.getMonth()]);
+}
+
+export function formatDateTimeToString(
+  date: Date,
+  format: DateTimeFormat = "yyyy-MM-dd'T'HH:mm"
+): string {
+  const day = String(date.getDate()).padStart(2, "0");
+  const month = String(date.getMonth() + 1).padStart(2, "0");
+  const year = String(date.getFullYear());
+
+  const hours24 = String(date.getHours()).padStart(2, "0");
+  const hours12Raw = date.getHours() % 12 || 12;
+  const hours12 = String(hours12Raw).padStart(2, "0");
+  const minutes = String(date.getMinutes()).padStart(2, "0");
+  const seconds = String(date.getSeconds()).padStart(2, "0");
+  const ampm = date.getHours() >= 12 ? "PM" : "AM";
+
+  const shortMonthNames = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"];
+  const longMonthNames = ["January", "February", "March", "April", "May", "June", "July", "August", "September", "October", "November", "December"];
+
+  return format
+    // Date replacements
+    .replace("dd", day)
+    .replace("MM", month)
+    .replace("yyyy", year)
+    .replace("yy", year.slice(-2))
+    .replace("MMM", shortMonthNames[date.getMonth()])
+    .replace("MMMM", longMonthNames[date.getMonth()])
+    // Time replacements
+    .replace("HH", hours24)
+    .replace("hh", hours12)
+    .replace("mm", minutes)
+    .replace("ss", seconds)
+    .replace("a", ampm);
+}
+
+/** Extracts AM/PM from a time string and returns the core time without it */
+export function extractMeridiem(time: string): { coreTime: string; meridiem?: 'AM' | 'PM' } {
+  const meridiemRegex = /\s?(AM|PM)$/i;
+  const match = meridiemRegex.exec(time.trim());
+  if (match) {
+    return { coreTime: time.replace(meridiemRegex, '').trim(), meridiem: match[1].toUpperCase() as 'AM' | 'PM' };
+  }
+  return { coreTime: time.trim() };
+}
+
+/** Safely parse a number and clamp it to a range, or return NaN if invalid */
+export function parseAndClamp(value?: string, min = 0, max = 59): number {
+  const num = value ? Number(value) : NaN;
+  return !isNaN(num) ? Math.min(Math.max(num, min), max) : NaN;
+}
+
+/** Pads a number with leading zero, or returns placeholder if NaN */
+export function padOrPlaceholder(num: number, placeholder: string): string {
+  return !isNaN(num) ? String(num).padStart(2, '0') : placeholder;
+}
+
+/** Determine meridiem if not explicitly provided */
+export function resolveMeridiem(meridiem?: 'AM' | 'PM', hours?: number): 'AM' | 'PM' {
+  if (meridiem) return meridiem;
+  if (hours !== undefined && !isNaN(hours)) return hours >= 12 ? 'PM' : 'AM';
+  return 'AM';
+}
+
+/** Main function refactored to use small utilities */
+export function formatTimeToString(
+  time: string,
+  format: TimeFormat = 'HH:mm',
+  partialTime?: InputTimePartial
+): string {
+  if (!time) return '';
+
+  const { coreTime, meridiem } = extractMeridiem(time);
+  const segments = coreTime.split(':');
+
+  const hours = parseAndClamp(segments[0], 0, 23);
+  const minutes = parseAndClamp(segments[1], 0, 59);
+  const seconds = parseAndClamp(segments[2], 0, 59);
+
+  const h = padOrPlaceholder(hours, 'HH');
+  const m = padOrPlaceholder(minutes, 'mm');
+  const s = padOrPlaceholder(seconds, 'ss');
+  const a = resolveMeridiem(meridiem, hours);
+
+  if (partialTime) {
+    switch (partialTime) {
+      case 'hour': return h;
+      case 'minute': return m;
+      case 'second': return s;
+      case 'meridiem': return a;
+    }
+  }
+
+  return format
+    .replace('HH', h)
+    .replace('hh', h)
+    .replace('mm', m)
+    .replace('ss', s)
+    .replace('a', a);
+}
+
+/**
+ * Converts a time string into total minutes.
+ * Supports optional seconds and AM/PM.
+ *
+ * @param time Time string ("HH:mm", "HH:mm:ss", or "hh:mm AM/PM").
+ * @returns Total minutes (including fractional for seconds), or null if invalid.
+ */
+export function parseTimeToMinutes(time: string): number | null {
+  const regex = /^(\d{1,2}):(\d{2})(?::(\d{2}))?\s*(AM|PM)?$/i;
+  const match = regex.exec(time);
+
+  if (!match) return null;
+
+  let hours = parseInt(match[1], 10);
+  const minutes = parseInt(match[2], 10);
+  const seconds = match[3] ? parseInt(match[3], 10) : 0;
+  const period = match[4]?.toUpperCase();
+
+  if (period) {
+    if (hours === 12) {
+      hours = period === "AM" ? 0 : 12;
+    } else if (period === "PM") {
+      hours += 12;
+    }
+  }
+
+  return hours * 60 + minutes + seconds / 60;
+}
+
+/**
+ * Determines if the given time format uses a 12-hour (meridiem) format.
+ * Example: "hh:mm a" → true, "HH:mm" → false
+ */
+export function isMeridiemFormat(format?: TimeFormat | null): boolean {
+  if (!format) return false;
+  return format.includes('a') || format.includes('A');
+}
+
+/**
+ * Extracts and returns the time format part of a DateTime format string.
+ * Example: "dd/MM/yyyy HH:mm" → "HH:mm"
+ */
+export function extractTimeFormat(dateTimeFormat: string): TimeFormat | null {
+  const regex = /\b[Hh]{1,2}:mm(?::ss)?(?:\s?[aA])?\b/;
+  const match = regex.exec(dateTimeFormat);
+
+  if (!match) return null;
+
+  const timePart = match[0].trim();
+
+  const allowedFormats: TimeFormat[] = ['HH:mm', 'HH:mm:ss', 'hh:mm a', 'hh:mm:ss a'];
+  return allowedFormats.includes(timePart as TimeFormat) ? (timePart as TimeFormat) : null;
+}
+
+/**
+ * Calculates the rotation angle (in degrees) for an hour hand on a 12-hour clock.
+ *
+ * @param hour - The hour value as a string (0-23 or 0-12).
+ * @returns The rotation angle in degrees, where 0 degrees is at 12 o'clock.
+ */
+export function calculateHourDegree(hour: string): number {
+  const num = Number.parseInt(hour, 10);
+  return ((num % 12) * 30 - 90);
+}
+
+/**
+ * Calculates the rotation angle (in degrees) for a minute hand on a clock.
+ *
+ * @param minute - The minute value as a string (0-59).
+ * @returns The rotation angle in degrees, where 0 degrees is at 12 o'clock.
+ */
+export function calculateMinuteDegree(minute: string): number {
+  const num = Number.parseInt(minute, 10);
+  return (num * 6 - 90);
+}

package/src/lib/utils/number.utils.ts

@@ -0,0 +1,16 @@
+/**
+ * Normalizes the value of an <input type="number">.
+ *
+ * - Returns a valid number if the input contains a numeric value
+ * - Returns null if the input is empty or not a valid number
+ *
+ * This helper ensures consistency between the raw input value
+ * and the form control value, preventing unintended NaN values.
+ *
+ * @param input The HTML input element of type "number"
+ * @returns number | null
+ */
+export function normalizeNumber(input: HTMLInputElement): number | null {
+  const num = input.valueAsNumber;
+  return isNaN(num) ? null : num;
+}