@studiocubics/utils 0.0.1

package/.turbo/turbo-build.log

@@ -0,0 +1,17 @@
+
+> @studiocubics/utils@0.0.1 build /home/runner/work/StudioCubics/StudioCubics/packages/utils
+> tsup
+
+CLI Building entry: src/index.ts
+CLI Using tsconfig: tsconfig.json
+CLI tsup v8.5.1
+CLI Using tsup config: /home/runner/work/StudioCubics/StudioCubics/packages/utils/tsup.config.ts
+CLI Target: es2022
+CLI Cleaning output folder
+CJS Build start
+CJS dist/index.js     9.75 KB
+CJS dist/index.js.map 19.24 KB
+CJS ⚡️ Build success in 343ms
+DTS Build start
+DTS ⚡️ Build success in 2850ms
+DTS dist/index.d.ts 5.81 KB

package/CHANGELOG.md

@@ -0,0 +1,7 @@
+# @studiocubics/utils
+
+## 0.0.1
+
+### Patch Changes
+
+- First publish inshallah!

package/dist/index.d.ts

@@ -0,0 +1,164 @@
+import { Ref } from 'react';
+
+type ActionResponse<K extends string = string, E extends K[] = K[]> = {
+    success: boolean;
+    payload?: unknown;
+    error?: string;
+    fieldErrors?: Record<K, E>;
+};
+declare const apiRes: {
+    actionFail: <K extends string = string>(error: ActionResponse<K>["error"], fieldErrors?: Record<string, string[]>) => ActionResponse<K>;
+    actionSuccess: <K extends string = string>(payload?: unknown) => ActionResponse<K>;
+    /**
+     * "Failed to fetch data!"
+     */
+    apiError: (message?: string) => string;
+    /**
+     * "You are not authenticated to access this resource."
+     */
+    unauthorised: string;
+    /**
+     * "You do not have the necessary permissions to access this resource."
+     */
+    forbidden: string;
+    /**
+     * "${item} is of wrong type, expected type: ${expectedType}"
+     */
+    wrongType: (item: string, expectedType?: string) => string;
+    /**
+     * "An error occured trying to read the formdata in these fields:
+     * ${fields}."
+     */
+    formdataError: (fields: string | string[]) => string;
+    /**
+     * "Missing parameter: ${param}."
+     */
+    missingParams: (param: string | string[]) => string;
+    /**
+     * "${item} not found!"
+     */
+    notFound: (item: string) => string;
+    /**
+     * "${item} already exists!"
+     */
+    alreadyExists: (item: string) => string;
+    /**
+     * "${contentName} size exceeded the maximum of ${maxSize}"
+     */
+    contentTooLarge: (contentName: string, maxSize?: string) => string;
+    /**
+     * An API Error has occurred:
+     * Check here => ${location}
+     * More Info: ${errorMessage}
+     */
+    generalError: (location: string, errorMessage?: string) => string;
+};
+
+interface SafePositionOptions {
+    anchorOrigin?: string;
+    transformOrigin?: string;
+    margin?: number;
+}
+interface Position {
+    x: number;
+    y: number;
+}
+/**
+ * Calculates safe position of an element within viewport relative to an anchor element
+ * Works like Material UI Popover positioning:
+ * - anchorOrigin: point on the anchor element (e.g., "top center" = top-center of anchor)
+ * - transformOrigin: point on the positioned element that attaches to anchor (e.g., "bottom center" = bottom-center of popup attaches to anchor point)
+ *
+ * Example: anchorOrigin "top center" + transformOrigin "bottom center" positions popup above and centered
+ *
+ * @param element - The element to position
+ * @param anchorElement - The anchor element to position relative to
+ * @param options - Configuration options
+ * @returns Safe x, y coordinates
+ */
+declare function calculateSafePosition(element: HTMLElement | null, anchorElement: HTMLElement | null, options?: SafePositionOptions): Position;
+
+/**
+ * Delays the program loop for the given amount of milliseconds
+ */
+declare const delay: (ms: number) => Promise<unknown>;
+
+/**
+ * Returns a human-readable relative time string vs Date.now().
+ * Accepts Date | number (ms) | date-string.
+ * Fast, allocation-light, no Intl.
+ */
+declare function relativeTime(input: Date | number | string): string;
+
+/**
+ * Formats a date according to the provided format string.
+ *
+ * @param dateInput - The date to format (as Date object, timestamp, or date string)
+ * @param format - The format string using tokens (default: "day D MMM, YYYY")
+ *
+ * @returns The formatted date string
+ *
+ * @example
+ * formatDate(new Date(), "Day, DD MMMM YYYY")
+ * // => "Thursday, 02 January 2026"
+ *
+ * @example
+ * formatDate(new Date(), "DD/MM/YYYY HH:mm:ss")
+ * // => "02/01/2026 14:30:45"
+ *
+ * @example
+ * formatDate(new Date(), "h:mm A")
+ * // => "2:30 PM"
+ *
+ * Available tokens:
+ * - Day: Full day name (e.g., "Monday")
+ * - day: Short day name (e.g., "Mon")
+ * - DD: Day of month, zero-padded (e.g., "05")
+ * - D: Day of month (e.g., "5")
+ * - MMMM: Full month name (e.g., "January")
+ * - MMM: Short month name (e.g., "Jan")
+ * - MM: Month number, zero-padded (e.g., "01")
+ * - YYYY: Full year (e.g., "2026")
+ * - YY: Two-digit year (e.g., "26")
+ * - HH: Hours (24-hour), zero-padded (e.g., "14")
+ * - H: Hours (24-hour) (e.g., "14")
+ * - hh: Hours (12-hour), zero-padded (e.g., "02")
+ * - h: Hours (12-hour) (e.g., "2")
+ * - mm: Minutes, zero-padded (e.g., "05")
+ * - m: Minutes (e.g., "5")
+ * - ss: Seconds, zero-padded (e.g., "09")
+ * - s: Seconds (e.g., "9")
+ * - A: AM/PM uppercase (e.g., "PM")
+ * - a: am/pm lowercase (e.g., "pm")
+ */
+declare function formatDate(dateInput: number | string | Date, format?: string): string;
+
+declare function initialiseForm<T extends string = string>(...fieldNames: T[]): ActionResponse<T, T[]>;
+
+/**
+ * This function returns the rounded corresponding value in the target range using linear interpolation.
+ *
+ * @param value - The input value to remap.
+ * @param from - The source range as a tuple [min, max].
+ * @param to - The target range as a tuple [min, max].
+ * @returns The remapped value in the target range.
+ *
+ * @example
+ * remap(3, [1, 10], [1, 5]); // 2
+ */
+declare function remap(value: number, from: [number, number], to: [number, number], roundTo?: "floor" | "ceil"): number;
+
+declare function mergeRefs<T>(...refs: (Ref<T> | undefined)[]): (instance: T | null) => void;
+
+declare function cn(...classNames: (string | undefined)[]): string;
+
+declare function toCapitalCase(str: string | undefined): string;
+declare function toCamelCase(str: string | undefined): string;
+declare function toKebabCase(str: string | undefined): string;
+declare function toSnakeCase(str: string | undefined): string;
+declare function toConstantCase(str: string | undefined): string;
+declare function toCapitalised(str: string | undefined): string;
+
+declare function cssSafeString(str: string): string;
+
+export { type ActionResponse, type Position, type SafePositionOptions, apiRes, calculateSafePosition, cn, cssSafeString, delay, formatDate, initialiseForm, mergeRefs, relativeTime, remap, toCamelCase, toCapitalCase, toCapitalised, toConstantCase, toKebabCase, toSnakeCase };

package/dist/index.js

@@ -0,0 +1,347 @@
+"use strict";Object.defineProperty(exports, "__esModule", {value: true});// src/API/apiRes.ts
+var apiRes = {
+  actionFail: (error, fieldErrors) => ({
+    success: false,
+    error,
+    fieldErrors
+  }),
+  actionSuccess: (payload) => ({
+    success: true,
+    payload
+  }),
+  /**
+   * "Failed to fetch data!"
+   */
+  apiError: (message) => message ? message : "Failed to fetch data!",
+  /**
+   * "You are not authenticated to access this resource."
+   */
+  unauthorised: "You are not authenticated to access this resource.",
+  /**
+   * "You do not have the necessary permissions to access this resource."
+   */
+  forbidden: "You do not have the necessary permissions to access this resource.",
+  /**
+   * "${item} is of wrong type, expected type: ${expectedType}"
+   */
+  wrongType: (item, expectedType) => `${item} is of wrong type${expectedType ? `, expected type: ${expectedType}` : ""}.`,
+  /**
+   * "An error occured trying to read the formdata in these fields:
+   * ${fields}."
+   */
+  formdataError: (fields) => `An error occured trying to read the formdata in these fields:
+${JSON.stringify(fields)}.`,
+  /**
+   * "Missing parameter: ${param}."
+   */
+  missingParams: (param) => `Missing parameter: ${JSON.stringify(param)}.`,
+  /**
+   * "${item} not found!"
+   */
+  notFound: (item) => `${item} not found!`,
+  /**
+   * "${item} already exists!"
+   */
+  alreadyExists: (item) => `${item} already exists!`,
+  /**
+   * "${contentName} size exceeded the maximum of ${maxSize}"
+   */
+  contentTooLarge: (contentName, maxSize) => `${contentName} size exceeded${maxSize ? ` the maximum of ${maxSize}` : ""}.`,
+  /**
+   * An API Error has occurred:
+   * Check here => ${location}
+   * More Info: ${errorMessage}
+   */
+  generalError: (location, errorMessage = "") => `An API Error has occurred:
+Check here => ${location}
+More Info: ${errorMessage}`
+};
+
+// src/Calculations/calculateSafePosition.ts
+function calculateSafePosition(element, anchorElement, options = {}) {
+  const {
+    anchorOrigin = "top left",
+    transformOrigin = "top left",
+    margin = 0
+  } = options;
+  if (!element || !anchorElement) return { x: 0, y: 0 };
+  const parseOrigin = (origin) => {
+    const parts = origin.toLowerCase().trim().split(/\s+/);
+    let vertical = "top";
+    let horizontal = "left";
+    for (const part of parts) {
+      if (["top", "bottom"].includes(part)) vertical = part;
+      else if (["left", "right"].includes(part))
+        horizontal = part;
+      else if (part === "center") {
+        if (parts.length === 1) {
+          vertical = "center";
+          horizontal = "center";
+        } else if (["top", "bottom"].includes(parts[0])) horizontal = "center";
+        else vertical = "center";
+      }
+    }
+    return { vertical, horizontal };
+  };
+  const getAnchorOffset = (size, origin) => {
+    if (origin === "center") return size / 2;
+    if (origin === "bottom" || origin === "right") return size;
+    return 0;
+  };
+  const getTransformOffset = (size, origin) => {
+    if (origin === "center") return size / 2;
+    if (origin === "bottom" || origin === "right") return size;
+    return 0;
+  };
+  const elementRect = element.getBoundingClientRect();
+  const anchorRect = anchorElement.getBoundingClientRect();
+  const viewportWidth = window.innerWidth;
+  const viewportHeight = window.innerHeight;
+  const anchor = parseOrigin(anchorOrigin);
+  const transform = parseOrigin(transformOrigin);
+  const anchorX = anchorRect.left + getAnchorOffset(anchorRect.width, anchor.horizontal);
+  const anchorY = anchorRect.top + getAnchorOffset(anchorRect.height, anchor.vertical);
+  const elementOriginX = getTransformOffset(
+    elementRect.width,
+    transform.horizontal
+  );
+  const elementOriginY = getTransformOffset(
+    elementRect.height,
+    transform.vertical
+  );
+  let x = anchorX - elementOriginX;
+  let y = anchorY - elementOriginY;
+  if (x + elementRect.width > viewportWidth - margin) {
+    x = viewportWidth - elementRect.width - margin;
+  }
+  if (x < margin) {
+    x = margin;
+  }
+  if (y + elementRect.height > viewportHeight - margin) {
+    y = viewportHeight - elementRect.height - margin;
+  }
+  if (y < margin) {
+    y = margin;
+  }
+  return {
+    x: Math.max(margin, x),
+    y: Math.max(margin, y)
+  };
+}
+
+// src/Code/delay.ts
+var delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+// src/Dates/relativeTime.ts
+function relativeTime(input) {
+  const t = input instanceof Date ? input.getTime() : typeof input === "number" ? input : Date.parse(input);
+  if (!Number.isFinite(t)) return "invalid date";
+  const now = Date.now();
+  const diffMs = t - now;
+  const absMs = Math.abs(diffMs);
+  const isFuture = diffMs > 0;
+  const MIN = 6e4;
+  const HOUR = 36e5;
+  const DAY = 864e5;
+  const WEEK = 6048e5;
+  const YEAR = 31536e6;
+  if (absMs > 5 * YEAR) {
+    return isFuture ? "a long time from now" : "a long time ago";
+  }
+  if (absMs < MIN) {
+    return "just now";
+  }
+  let value;
+  let unit;
+  if (absMs < HOUR) {
+    value = Math.round(absMs / MIN);
+    unit = "minute";
+  } else if (absMs < DAY) {
+    value = Math.round(absMs / HOUR);
+    unit = "hour";
+  } else if (absMs < WEEK) {
+    value = Math.round(absMs / DAY);
+    unit = "day";
+  } else if (absMs < YEAR) {
+    value = Math.round(absMs / WEEK);
+    unit = "week";
+  } else {
+    value = Math.round(absMs / YEAR);
+    unit = "year";
+  }
+  if (value !== 1) unit += "s";
+  return isFuture ? `in ${value} ${unit}` : `${value} ${unit} ago`;
+}
+
+// src/Dates/formateDate.ts
+function formatDate(dateInput, format = "HH:mm:ss day D MMM, YYYY") {
+  const date = new Date(dateInput);
+  const pad = (n) => String(n).padStart(2, "0");
+  const daysFull = [
+    "Sunday",
+    "Monday",
+    "Tuesday",
+    "Wednesday",
+    "Thursday",
+    "Friday",
+    "Saturday"
+  ];
+  const daysShort = ["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"];
+  const monthsFull = [
+    "January",
+    "February",
+    "March",
+    "April",
+    "May",
+    "June",
+    "July",
+    "August",
+    "September",
+    "October",
+    "November",
+    "December"
+  ];
+  const monthsShort = monthsFull.map((m) => m.slice(0, 3));
+  const dayIndex = date.getDay();
+  const dateNum = date.getDate();
+  const monthIndex = date.getMonth();
+  const year = date.getFullYear();
+  const hours24 = date.getHours();
+  const minutes = date.getMinutes();
+  const seconds = date.getSeconds();
+  const hours12 = hours24 % 12 || 12;
+  const isPM = hours24 >= 12;
+  const yearStr = String(year);
+  const replacements = {
+    Day: daysFull[dayIndex],
+    day: daysShort[dayIndex],
+    DD: pad(dateNum),
+    D: String(dateNum),
+    MMMM: monthsFull[monthIndex],
+    MMM: monthsShort[monthIndex],
+    MM: pad(monthIndex + 1),
+    YYYY: yearStr,
+    YY: yearStr.slice(-2),
+    HH: pad(hours24),
+    H: String(hours24),
+    hh: pad(hours12),
+    h: String(hours12),
+    mm: pad(minutes),
+    m: String(minutes),
+    ss: pad(seconds),
+    s: String(seconds),
+    A: isPM ? "PM" : "AM",
+    a: isPM ? "pm" : "am"
+  };
+  const tokens = Object.keys(replacements).sort(
+    (a, b) => b.length - a.length
+  );
+  const pattern = new RegExp(tokens.join("|"), "g");
+  return format.replace(pattern, (match) => replacements[match]);
+}
+
+// src/Forms/initialiseForm.ts
+function initialiseForm(...fieldNames) {
+  let fieldErrors = {};
+  for (const fieldName of fieldNames) {
+    fieldErrors[fieldName] = [];
+  }
+  return {
+    success: false,
+    fieldErrors
+  };
+}
+
+// src/Numbers/remap.ts
+function remap(value, from, to, roundTo = "floor") {
+  const [fromMin, fromMax] = from;
+  const [toMin, toMax] = to;
+  if (roundTo == "ceil")
+    return Math.ceil(
+      toMin + (value - fromMin) * (toMax - toMin) / (fromMax - fromMin)
+    );
+  return Math.floor(
+    toMin + (value - fromMin) * (toMax - toMin) / (fromMax - fromMin)
+  );
+}
+
+// src/React/mergeRefs.ts
+function mergeRefs(...refs) {
+  return (instance) => {
+    for (const ref of refs) {
+      if (!ref) continue;
+      if (typeof ref === "function") {
+        ref(instance);
+      } else {
+        ref.current = instance;
+      }
+    }
+  };
+}
+
+// src/Strings/cn.ts
+function cn(...classNames) {
+  return classNames.filter((c) => c).join(" ");
+}
+
+// src/Strings/stringCases.ts
+function toWords(str) {
+  return str.replace(/([a-z])([A-Z])/g, "$1 $2").replace(/[_\-]+/g, " ").trim().split(/\s+/).filter(Boolean).map((w) => w.toLowerCase());
+}
+function toCapitalCase(str) {
+  if (!str) return "";
+  const words = toWords(str);
+  return words.map((w) => w[0].toUpperCase() + w.slice(1)).join("");
+}
+function toCamelCase(str) {
+  if (!str) return "";
+  const words = toWords(str);
+  return words.map((w, i) => i === 0 ? w : w[0].toUpperCase() + w.slice(1)).join("");
+}
+function toKebabCase(str) {
+  if (!str) return "";
+  return toWords(str).join("-");
+}
+function toSnakeCase(str) {
+  if (!str) return "";
+  return toWords(str).join("_");
+}
+function toConstantCase(str) {
+  if (!str) return "";
+  return toWords(str).join("_").toUpperCase();
+}
+function toCapitalised(str) {
+  if (!str) return "";
+  const words = toWords(str);
+  if (words.length === 0) return "";
+  return words.map((w) => w[0].toUpperCase() + w.slice(1)).join(" ");
+}
+
+// src/Strings/cssSafeString.ts
+function cssSafeString(str) {
+  const encoded = encodeURIComponent(str).toLowerCase().replace(/\.|%[0-9a-z]{2}/gi, "");
+  const firstChar = encoded.charAt(0);
+  if (firstChar.match(/^[0-9-]/)) {
+    return "_" + encoded;
+  }
+  return encoded;
+}
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+exports.apiRes = apiRes; exports.calculateSafePosition = calculateSafePosition; exports.cn = cn; exports.cssSafeString = cssSafeString; exports.delay = delay; exports.formatDate = formatDate; exports.initialiseForm = initialiseForm; exports.mergeRefs = mergeRefs; exports.relativeTime = relativeTime; exports.remap = remap; exports.toCamelCase = toCamelCase; exports.toCapitalCase = toCapitalCase; exports.toCapitalised = toCapitalised; exports.toConstantCase = toConstantCase; exports.toKebabCase = toKebabCase; exports.toSnakeCase = toSnakeCase;
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["/home/runner/work/StudioCubics/StudioCubics/packages/utils/dist/index.js","../src/API/apiRes.ts","../src/Calculations/calculateSafePosition.ts","../src/Code/delay.ts","../src/Dates/relativeTime.ts","../src/Dates/formateDate.ts","../src/Forms/initialiseForm.ts","../src/Numbers/remap.ts","../src/React/mergeRefs.ts","../src/Strings/cn.ts","../src/Strings/stringCases.ts","../src/Strings/cssSafeString.ts"],"names":[],"mappings":"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","file":"/home/runner/work/StudioCubics/StudioCubics/packages/utils/dist/index.js","sourcesContent":[null,"export type ActionResponse<K extends string = string, E extends K[] = K[]> = {\n  success: boolean;\n  payload?: unknown;\n  error?: string;\n  fieldErrors?: Record<K, E>;\n};\n\nexport const apiRes = {\n  actionFail: <K extends string = string>(\n    error: ActionResponse<K>[\"error\"],\n    fieldErrors?: Record<string, string[]>\n  ): ActionResponse<K> => ({\n    success: false,\n    error,\n    fieldErrors: fieldErrors as ActionResponse<K>[\"fieldErrors\"],\n  }),\n  actionSuccess: <K extends string = string>(\n    payload?: unknown\n  ): ActionResponse<K> => ({\n    success: true,\n    payload,\n  }),\n  /**\n   * \"Failed to fetch data!\"\n   */\n  apiError: (message?: string) => (message ? message : \"Failed to fetch data!\"),\n  /**\n   * \"You are not authenticated to access this resource.\"\n   */\n  unauthorised: \"You are not authenticated to access this resource.\",\n  /**\n   * \"You do not have the necessary permissions to access this resource.\"\n   */\n  forbidden:\n    \"You do not have the necessary permissions to access this resource.\",\n  /**\n   * \"${item} is of wrong type, expected type: ${expectedType}\"\n   */\n  wrongType: (item: string, expectedType?: string) =>\n    `${item} is of wrong type${expectedType ? `, expected type: ${expectedType}` : \"\"}.`,\n  /**\n   * \"An error occured trying to read the formdata in these fields:\n   * ${fields}.\"\n   */\n  formdataError: (fields: string | string[]) =>\n    `An error occured trying to read the formdata in these fields:\\n${JSON.stringify(fields)}.`,\n  /**\n   * \"Missing parameter: ${param}.\"\n   */\n  missingParams: (param: string | string[]) =>\n    `Missing parameter: ${JSON.stringify(param)}.`,\n  /**\n   * \"${item} not found!\"\n   */\n  notFound: (item: string) => `${item} not found!`,\n  /**\n   * \"${item} already exists!\"\n   */\n  alreadyExists: (item: string) => `${item} already exists!`,\n  /**\n   * \"${contentName} size exceeded the maximum of ${maxSize}\"\n   */\n  contentTooLarge: (contentName: string, maxSize?: string) =>\n    `${contentName} size exceeded${\n      maxSize ? ` the maximum of ${maxSize}` : \"\"\n    }.`,\n  /**\n   * An API Error has occurred:\n   * Check here => ${location}\n   * More Info: ${errorMessage}\n   */\n  generalError: (location: string, errorMessage: string = \"\") =>\n    `An API Error has occurred:\\nCheck here => ${location}\\nMore Info: ${errorMessage}`,\n};\n","type VerticalOrigin = \"top\" | \"center\" | \"bottom\";\ntype HorizontalOrigin = \"left\" | \"center\" | \"right\";\n\ninterface ParsedOrigin {\n  vertical: VerticalOrigin;\n  horizontal: HorizontalOrigin;\n}\n\nexport interface SafePositionOptions {\n  anchorOrigin?: string;\n  transformOrigin?: string;\n  margin?: number;\n}\n\nexport interface Position {\n  x: number;\n  y: number;\n}\n\n/**\n * Calculates safe position of an element within viewport relative to an anchor element\n * Works like Material UI Popover positioning:\n * - anchorOrigin: point on the anchor element (e.g., \"top center\" = top-center of anchor)\n * - transformOrigin: point on the positioned element that attaches to anchor (e.g., \"bottom center\" = bottom-center of popup attaches to anchor point)\n *\n * Example: anchorOrigin \"top center\" + transformOrigin \"bottom center\" positions popup above and centered\n *\n * @param element - The element to position\n * @param anchorElement - The anchor element to position relative to\n * @param options - Configuration options\n * @returns Safe x, y coordinates\n */\nexport function calculateSafePosition(\n  element: HTMLElement | null,\n  anchorElement: HTMLElement | null,\n  options: SafePositionOptions = {}\n): Position {\n  const {\n    anchorOrigin = \"top left\",\n    transformOrigin = \"top left\",\n    margin = 0,\n  } = options;\n\n  if (!element || !anchorElement) return { x: 0, y: 0 };\n\n  const parseOrigin = (origin: string): ParsedOrigin => {\n    const parts = origin.toLowerCase().trim().split(/\\s+/);\n    let vertical: VerticalOrigin = \"top\";\n    let horizontal: HorizontalOrigin = \"left\";\n\n    for (const part of parts) {\n      if ([\"top\", \"bottom\"].includes(part)) vertical = part as VerticalOrigin;\n      else if ([\"left\", \"right\"].includes(part))\n        horizontal = part as HorizontalOrigin;\n      else if (part === \"center\") {\n        // Assign center depending on position in string\n        if (parts.length === 1) {\n          vertical = \"center\";\n          horizontal = \"center\";\n        } else if ([\"top\", \"bottom\"].includes(parts[0])) horizontal = \"center\";\n        else vertical = \"center\";\n      }\n    }\n\n    return { vertical, horizontal };\n  };\n\n  const getAnchorOffset = (\n    size: number,\n    origin: VerticalOrigin | HorizontalOrigin\n  ): number => {\n    if (origin === \"center\") return size / 2;\n    if (origin === \"bottom\" || origin === \"right\") return size;\n    return 0; // top or left\n  };\n\n  const getTransformOffset = (\n    size: number,\n    origin: VerticalOrigin | HorizontalOrigin\n  ): number => {\n    if (origin === \"center\") return size / 2;\n    if (origin === \"bottom\" || origin === \"right\") return size;\n    return 0; // top or left\n  };\n\n  const elementRect = element.getBoundingClientRect();\n  const anchorRect = anchorElement.getBoundingClientRect();\n  const viewportWidth = window.innerWidth;\n  const viewportHeight = window.innerHeight;\n\n  const anchor = parseOrigin(anchorOrigin);\n  const transform = parseOrigin(transformOrigin);\n\n  // Calculate anchor point on the anchor element\n  const anchorX =\n    anchorRect.left + getAnchorOffset(anchorRect.width, anchor.horizontal);\n  const anchorY =\n    anchorRect.top + getAnchorOffset(anchorRect.height, anchor.vertical);\n\n  // Calculate where on the element we're attaching (transform origin point)\n  const elementOriginX = getTransformOffset(\n    elementRect.width,\n    transform.horizontal\n  );\n  const elementOriginY = getTransformOffset(\n    elementRect.height,\n    transform.vertical\n  );\n\n  // Position the element so its transform origin aligns with the anchor point\n  let x = anchorX - elementOriginX;\n  let y = anchorY - elementOriginY;\n\n  // Check and adjust for viewport boundaries with margin\n  // Right boundary\n  if (x + elementRect.width > viewportWidth - margin) {\n    x = viewportWidth - elementRect.width - margin;\n  }\n  // Left boundary\n  if (x < margin) {\n    x = margin;\n  }\n\n  // Bottom boundary\n  if (y + elementRect.height > viewportHeight - margin) {\n    y = viewportHeight - elementRect.height - margin;\n  }\n  // Top boundary\n  if (y < margin) {\n    y = margin;\n  }\n\n  return {\n    x: Math.max(margin, x),\n    y: Math.max(margin, y),\n  };\n}\n","/**\n * Delays the program loop for the given amount of milliseconds\n */\nexport const delay = (ms: number) =>\n  new Promise((resolve) => setTimeout(resolve, ms));\n","/**\n * Returns a human-readable relative time string vs Date.now().\n * Accepts Date | number (ms) | date-string.\n * Fast, allocation-light, no Intl.\n */\nexport function relativeTime(\n  input: Date | number | string\n): string {\n  const t: number =\n    input instanceof Date\n      ? input.getTime()\n      : typeof input === \"number\"\n      ? input\n      : Date.parse(input);\n\n  if (!Number.isFinite(t)) return \"invalid date\";\n\n  const now = Date.now();\n  const diffMs = t - now;\n  const absMs = Math.abs(diffMs);\n  const isFuture = diffMs > 0;\n\n  // time constants (ms)\n  const MIN = 60_000;\n  const HOUR = 3_600_000;\n  const DAY = 86_400_000;\n  const WEEK = 604_800_000;\n  const YEAR = 31_536_000_000;\n\n  // very far away → coarse wording\n  if (absMs > 5 * YEAR) {\n    return isFuture ? \"a long time from now\" : \"a long time ago\";\n  }\n\n  if (absMs < MIN) {\n    return \"just now\";\n  }\n\n  let value: number;\n  let unit: \"minute\" | \"hour\" | \"day\" | \"week\" | \"year\";\n\n  if (absMs < HOUR) {\n    value = Math.round(absMs / MIN);\n    unit = \"minute\";\n  } else if (absMs < DAY) {\n    value = Math.round(absMs / HOUR);\n    unit = \"hour\";\n  } else if (absMs < WEEK) {\n    value = Math.round(absMs / DAY);\n    unit = \"day\";\n  } else if (absMs < YEAR) {\n    value = Math.round(absMs / WEEK);\n    unit = \"week\";\n  } else {\n    value = Math.round(absMs / YEAR);\n    unit = \"year\";\n  }\n\n  if (value !== 1) unit += \"s\";\n\n  return isFuture\n    ? `in ${value} ${unit}`\n    : `${value} ${unit} ago`;\n}\n","type DateToken =\n  | \"Day\"\n  | \"day\"\n  | \"DD\"\n  | \"D\"\n  | \"MMMM\"\n  | \"MMM\"\n  | \"MM\"\n  | \"YYYY\"\n  | \"YY\"\n  | \"HH\"\n  | \"H\"\n  | \"hh\"\n  | \"h\"\n  | \"mm\"\n  | \"m\"\n  | \"ss\"\n  | \"s\"\n  | \"A\"\n  | \"a\";\n\n/**\n * Formats a date according to the provided format string.\n *\n * @param dateInput - The date to format (as Date object, timestamp, or date string)\n * @param format - The format string using tokens (default: \"day D MMM, YYYY\")\n *\n * @returns The formatted date string\n *\n * @example\n * formatDate(new Date(), \"Day, DD MMMM YYYY\")\n * // => \"Thursday, 02 January 2026\"\n *\n * @example\n * formatDate(new Date(), \"DD/MM/YYYY HH:mm:ss\")\n * // => \"02/01/2026 14:30:45\"\n *\n * @example\n * formatDate(new Date(), \"h:mm A\")\n * // => \"2:30 PM\"\n *\n * Available tokens:\n * - Day: Full day name (e.g., \"Monday\")\n * - day: Short day name (e.g., \"Mon\")\n * - DD: Day of month, zero-padded (e.g., \"05\")\n * - D: Day of month (e.g., \"5\")\n * - MMMM: Full month name (e.g., \"January\")\n * - MMM: Short month name (e.g., \"Jan\")\n * - MM: Month number, zero-padded (e.g., \"01\")\n * - YYYY: Full year (e.g., \"2026\")\n * - YY: Two-digit year (e.g., \"26\")\n * - HH: Hours (24-hour), zero-padded (e.g., \"14\")\n * - H: Hours (24-hour) (e.g., \"14\")\n * - hh: Hours (12-hour), zero-padded (e.g., \"02\")\n * - h: Hours (12-hour) (e.g., \"2\")\n * - mm: Minutes, zero-padded (e.g., \"05\")\n * - m: Minutes (e.g., \"5\")\n * - ss: Seconds, zero-padded (e.g., \"09\")\n * - s: Seconds (e.g., \"9\")\n * - A: AM/PM uppercase (e.g., \"PM\")\n * - a: am/pm lowercase (e.g., \"pm\")\n */\nexport function formatDate(\n  dateInput: number | string | Date,\n  format: string = \"HH:mm:ss day D MMM, YYYY\"\n) {\n  const date = new Date(dateInput);\n\n  const pad = (n: number) => String(n).padStart(2, \"0\");\n\n  const daysFull = [\n    \"Sunday\",\n    \"Monday\",\n    \"Tuesday\",\n    \"Wednesday\",\n    \"Thursday\",\n    \"Friday\",\n    \"Saturday\",\n  ];\n  const daysShort = [\"Sun\", \"Mon\", \"Tue\", \"Wed\", \"Thu\", \"Fri\", \"Sat\"];\n  const monthsFull = [\n    \"January\",\n    \"February\",\n    \"March\",\n    \"April\",\n    \"May\",\n    \"June\",\n    \"July\",\n    \"August\",\n    \"September\",\n    \"October\",\n    \"November\",\n    \"December\",\n  ];\n  const monthsShort = monthsFull.map((m) => m.slice(0, 3));\n\n  // Extract all values once\n  const dayIndex = date.getDay();\n  const dateNum = date.getDate();\n  const monthIndex = date.getMonth();\n  const year = date.getFullYear();\n  const hours24 = date.getHours();\n  const minutes = date.getMinutes();\n  const seconds = date.getSeconds();\n\n  const hours12 = hours24 % 12 || 12;\n  const isPM = hours24 >= 12;\n  const yearStr = String(year);\n\n  const replacements: Record<DateToken, string> = {\n    Day: daysFull[dayIndex],\n    day: daysShort[dayIndex],\n    DD: pad(dateNum),\n    D: String(dateNum),\n    MMMM: monthsFull[monthIndex],\n    MMM: monthsShort[monthIndex],\n    MM: pad(monthIndex + 1),\n    YYYY: yearStr,\n    YY: yearStr.slice(-2),\n    HH: pad(hours24),\n    H: String(hours24),\n    hh: pad(hours12),\n    h: String(hours12),\n    mm: pad(minutes),\n    m: String(minutes),\n    ss: pad(seconds),\n    s: String(seconds),\n    A: isPM ? \"PM\" : \"AM\",\n    a: isPM ? \"pm\" : \"am\",\n  };\n\n  // Sort tokens by length (longest first) to avoid partial replacements\n  const tokens = (Object.keys(replacements) as DateToken[]).sort(\n    (a, b) => b.length - a.length\n  );\n\n  // Use a single regex replacement to avoid overlapping matches\n  const pattern = new RegExp(tokens.join(\"|\"), \"g\");\n  return format.replace(pattern, (match) => replacements[match as DateToken]);\n}\n","import type { ActionResponse } from \"../API/apiRes\";\n\nexport function initialiseForm<T extends string = string>(\n  ...fieldNames: T[]\n): ActionResponse<T, T[]> {\n  let fieldErrors = {} as Record<T, T[]>;\n  for (const fieldName of fieldNames) {\n    fieldErrors[fieldName] = [] as T[];\n  }\n  return {\n    success: false,\n    fieldErrors,\n  };\n}\n","/**\n * This function returns the rounded corresponding value in the target range using linear interpolation.\n *\n * @param value - The input value to remap.\n * @param from - The source range as a tuple [min, max].\n * @param to - The target range as a tuple [min, max].\n * @returns The remapped value in the target range.\n *\n * @example\n * remap(3, [1, 10], [1, 5]); // 2\n */\nexport function remap(\n  value: number,\n  from: [number, number],\n  to: [number, number],\n  roundTo: \"floor\" | \"ceil\" = \"floor\",\n): number {\n  const [fromMin, fromMax] = from;\n  const [toMin, toMax] = to;\n\n  if (roundTo == \"ceil\")\n    return Math.ceil(\n      toMin + ((value - fromMin) * (toMax - toMin)) / (fromMax - fromMin),\n    );\n  return Math.floor(\n    toMin + ((value - fromMin) * (toMax - toMin)) / (fromMax - fromMin),\n  );\n}\n","import type { RefObject, Ref } from \"react\";\n\nexport function mergeRefs<T>(\n  ...refs: (Ref<T> | undefined)[]\n): (instance: T | null) => void {\n  return (instance) => {\n    for (const ref of refs) {\n      if (!ref) continue;\n      if (typeof ref === \"function\") {\n        ref(instance);\n      } else {\n        (ref as RefObject<T | null>).current = instance;\n      }\n    }\n  };\n}\n","export function cn(...classNames: (string | undefined)[]) {\n  return classNames.filter((c) => c).join(\" \");\n}\n","function toWords(str: string): string[] {\n  return str\n    .replace(/([a-z])([A-Z])/g, \"$1 $2\") // camelCase → camel Case\n    .replace(/[_\\-]+/g, \" \") // snake_case, kebab-case → spaces\n    .trim()\n    .split(/\\s+/)\n    .filter(Boolean)\n    .map((w) => w.toLowerCase());\n}\n\nexport function toCapitalCase(str: string | undefined): string {\n  if (!str) return \"\";\n  const words = toWords(str);\n  return words.map((w) => w[0].toUpperCase() + w.slice(1)).join(\"\");\n}\n\nexport function toCamelCase(str: string | undefined): string {\n  if (!str) return \"\";\n\n  const words = toWords(str);\n  return words\n    .map((w, i) => (i === 0 ? w : w[0].toUpperCase() + w.slice(1)))\n    .join(\"\");\n}\n\nexport function toKebabCase(str: string | undefined): string {\n  if (!str) return \"\";\n\n  return toWords(str).join(\"-\");\n}\n\nexport function toSnakeCase(str: string | undefined): string {\n  if (!str) return \"\";\n\n  return toWords(str).join(\"_\");\n}\n\nexport function toConstantCase(str: string | undefined): string {\n  if (!str) return \"\";\n\n  return toWords(str).join(\"_\").toUpperCase();\n}\n\nexport function toCapitalised(str: string | undefined): string {\n  if (!str) return \"\";\n\n  const words = toWords(str);\n  if (words.length === 0) return \"\";\n  return words.map((w) => w[0].toUpperCase() + w.slice(1)).join(\" \");\n}\n","export function cssSafeString(str: string) {\n  const encoded = encodeURIComponent(str)\n    .toLowerCase()\n    .replace(/\\.|%[0-9a-z]{2}/gi, \"\");\n\n  const firstChar = encoded.charAt(0);\n  if (firstChar.match(/^[0-9-]/)) {\n    // Check if the first character is a number or hyphen\n    return \"_\" + encoded;\n  }\n\n  return encoded;\n}\n"]}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@studiocubics/utils",
+  "description": "Package containing utility functions by Studio Cubics",
+  "publishConfig": {
+    "access": "public"
+  },
+  "private": false,
+  "version": "0.0.1",
+  "main": "./dist/index.js",
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "types": "./dist/index.d.ts",
+  "peerDependencies": {
+    "react": "19",
+    "@types/react": "19"
+  },
+  "devDependencies": {
+    "tsup": "^8.5.1"
+  },
+  "keywords": [
+    "@studiocubics",
+    "cubics",
+    "studio",
+    "utils",
+    "functions",
+    "utilities"
+  ],
+  "author": {
+    "name": "Studio Cubics",
+    "email": "studiocubics7@gmail.com",
+    "url": "https://studio-cubics.vercel.app"
+  },
+  "license": "MIT",
+  "scripts": {
+    "build": "tsup",
+    "clean": "rimraf dist node_modules"
+  }
+}

package/src/API/_index.ts

@@ -0,0 +1 @@
+export * from "./apiRes";

package/src/API/apiRes.ts

@@ -0,0 +1,74 @@
+export type ActionResponse<K extends string = string, E extends K[] = K[]> = {
+  success: boolean;
+  payload?: unknown;
+  error?: string;
+  fieldErrors?: Record<K, E>;
+};
+
+export const apiRes = {
+  actionFail: <K extends string = string>(
+    error: ActionResponse<K>["error"],
+    fieldErrors?: Record<string, string[]>
+  ): ActionResponse<K> => ({
+    success: false,
+    error,
+    fieldErrors: fieldErrors as ActionResponse<K>["fieldErrors"],
+  }),
+  actionSuccess: <K extends string = string>(
+    payload?: unknown
+  ): ActionResponse<K> => ({
+    success: true,
+    payload,
+  }),
+  /**
+   * "Failed to fetch data!"
+   */
+  apiError: (message?: string) => (message ? message : "Failed to fetch data!"),
+  /**
+   * "You are not authenticated to access this resource."
+   */
+  unauthorised: "You are not authenticated to access this resource.",
+  /**
+   * "You do not have the necessary permissions to access this resource."
+   */
+  forbidden:
+    "You do not have the necessary permissions to access this resource.",
+  /**
+   * "${item} is of wrong type, expected type: ${expectedType}"
+   */
+  wrongType: (item: string, expectedType?: string) =>
+    `${item} is of wrong type${expectedType ? `, expected type: ${expectedType}` : ""}.`,
+  /**
+   * "An error occured trying to read the formdata in these fields:
+   * ${fields}."
+   */
+  formdataError: (fields: string | string[]) =>
+    `An error occured trying to read the formdata in these fields:\n${JSON.stringify(fields)}.`,
+  /**
+   * "Missing parameter: ${param}."
+   */
+  missingParams: (param: string | string[]) =>
+    `Missing parameter: ${JSON.stringify(param)}.`,
+  /**
+   * "${item} not found!"
+   */
+  notFound: (item: string) => `${item} not found!`,
+  /**
+   * "${item} already exists!"
+   */
+  alreadyExists: (item: string) => `${item} already exists!`,
+  /**
+   * "${contentName} size exceeded the maximum of ${maxSize}"
+   */
+  contentTooLarge: (contentName: string, maxSize?: string) =>
+    `${contentName} size exceeded${
+      maxSize ? ` the maximum of ${maxSize}` : ""
+    }.`,
+  /**
+   * An API Error has occurred:
+   * Check here => ${location}
+   * More Info: ${errorMessage}
+   */
+  generalError: (location: string, errorMessage: string = "") =>
+    `An API Error has occurred:\nCheck here => ${location}\nMore Info: ${errorMessage}`,
+};

package/src/Calculations/_index.ts

@@ -0,0 +1 @@
+export * from "./calculateSafePosition";

package/src/Calculations/calculateSafePosition.ts

@@ -0,0 +1,137 @@
+type VerticalOrigin = "top" | "center" | "bottom";
+type HorizontalOrigin = "left" | "center" | "right";
+
+interface ParsedOrigin {
+  vertical: VerticalOrigin;
+  horizontal: HorizontalOrigin;
+}
+
+export interface SafePositionOptions {
+  anchorOrigin?: string;
+  transformOrigin?: string;
+  margin?: number;
+}
+
+export interface Position {
+  x: number;
+  y: number;
+}
+
+/**
+ * Calculates safe position of an element within viewport relative to an anchor element
+ * Works like Material UI Popover positioning:
+ * - anchorOrigin: point on the anchor element (e.g., "top center" = top-center of anchor)
+ * - transformOrigin: point on the positioned element that attaches to anchor (e.g., "bottom center" = bottom-center of popup attaches to anchor point)
+ *
+ * Example: anchorOrigin "top center" + transformOrigin "bottom center" positions popup above and centered
+ *
+ * @param element - The element to position
+ * @param anchorElement - The anchor element to position relative to
+ * @param options - Configuration options
+ * @returns Safe x, y coordinates
+ */
+export function calculateSafePosition(
+  element: HTMLElement | null,
+  anchorElement: HTMLElement | null,
+  options: SafePositionOptions = {}
+): Position {
+  const {
+    anchorOrigin = "top left",
+    transformOrigin = "top left",
+    margin = 0,
+  } = options;
+
+  if (!element || !anchorElement) return { x: 0, y: 0 };
+
+  const parseOrigin = (origin: string): ParsedOrigin => {
+    const parts = origin.toLowerCase().trim().split(/\s+/);
+    let vertical: VerticalOrigin = "top";
+    let horizontal: HorizontalOrigin = "left";
+
+    for (const part of parts) {
+      if (["top", "bottom"].includes(part)) vertical = part as VerticalOrigin;
+      else if (["left", "right"].includes(part))
+        horizontal = part as HorizontalOrigin;
+      else if (part === "center") {
+        // Assign center depending on position in string
+        if (parts.length === 1) {
+          vertical = "center";
+          horizontal = "center";
+        } else if (["top", "bottom"].includes(parts[0])) horizontal = "center";
+        else vertical = "center";
+      }
+    }
+
+    return { vertical, horizontal };
+  };
+
+  const getAnchorOffset = (
+    size: number,
+    origin: VerticalOrigin | HorizontalOrigin
+  ): number => {
+    if (origin === "center") return size / 2;
+    if (origin === "bottom" || origin === "right") return size;
+    return 0; // top or left
+  };
+
+  const getTransformOffset = (
+    size: number,
+    origin: VerticalOrigin | HorizontalOrigin
+  ): number => {
+    if (origin === "center") return size / 2;
+    if (origin === "bottom" || origin === "right") return size;
+    return 0; // top or left
+  };
+
+  const elementRect = element.getBoundingClientRect();
+  const anchorRect = anchorElement.getBoundingClientRect();
+  const viewportWidth = window.innerWidth;
+  const viewportHeight = window.innerHeight;
+
+  const anchor = parseOrigin(anchorOrigin);
+  const transform = parseOrigin(transformOrigin);
+
+  // Calculate anchor point on the anchor element
+  const anchorX =
+    anchorRect.left + getAnchorOffset(anchorRect.width, anchor.horizontal);
+  const anchorY =
+    anchorRect.top + getAnchorOffset(anchorRect.height, anchor.vertical);
+
+  // Calculate where on the element we're attaching (transform origin point)
+  const elementOriginX = getTransformOffset(
+    elementRect.width,
+    transform.horizontal
+  );
+  const elementOriginY = getTransformOffset(
+    elementRect.height,
+    transform.vertical
+  );
+
+  // Position the element so its transform origin aligns with the anchor point
+  let x = anchorX - elementOriginX;
+  let y = anchorY - elementOriginY;
+
+  // Check and adjust for viewport boundaries with margin
+  // Right boundary
+  if (x + elementRect.width > viewportWidth - margin) {
+    x = viewportWidth - elementRect.width - margin;
+  }
+  // Left boundary
+  if (x < margin) {
+    x = margin;
+  }
+
+  // Bottom boundary
+  if (y + elementRect.height > viewportHeight - margin) {
+    y = viewportHeight - elementRect.height - margin;
+  }
+  // Top boundary
+  if (y < margin) {
+    y = margin;
+  }
+
+  return {
+    x: Math.max(margin, x),
+    y: Math.max(margin, y),
+  };
+}

package/src/Code/_index.ts

@@ -0,0 +1 @@
+export * from "./delay";

package/src/Code/delay.ts

@@ -0,0 +1,5 @@
+/**
+ * Delays the program loop for the given amount of milliseconds
+ */
+export const delay = (ms: number) =>
+  new Promise((resolve) => setTimeout(resolve, ms));

package/src/Dates/_index.ts

@@ -0,0 +1,2 @@
+export * from "./relativeTime";
+export * from "./formateDate";

package/src/Dates/formateDate.ts

@@ -0,0 +1,140 @@
+type DateToken =
+  | "Day"
+  | "day"
+  | "DD"
+  | "D"
+  | "MMMM"
+  | "MMM"
+  | "MM"
+  | "YYYY"
+  | "YY"
+  | "HH"
+  | "H"
+  | "hh"
+  | "h"
+  | "mm"
+  | "m"
+  | "ss"
+  | "s"
+  | "A"
+  | "a";
+
+/**
+ * Formats a date according to the provided format string.
+ *
+ * @param dateInput - The date to format (as Date object, timestamp, or date string)
+ * @param format - The format string using tokens (default: "day D MMM, YYYY")
+ *
+ * @returns The formatted date string
+ *
+ * @example
+ * formatDate(new Date(), "Day, DD MMMM YYYY")
+ * // => "Thursday, 02 January 2026"
+ *
+ * @example
+ * formatDate(new Date(), "DD/MM/YYYY HH:mm:ss")
+ * // => "02/01/2026 14:30:45"
+ *
+ * @example
+ * formatDate(new Date(), "h:mm A")
+ * // => "2:30 PM"
+ *
+ * Available tokens:
+ * - Day: Full day name (e.g., "Monday")
+ * - day: Short day name (e.g., "Mon")
+ * - DD: Day of month, zero-padded (e.g., "05")
+ * - D: Day of month (e.g., "5")
+ * - MMMM: Full month name (e.g., "January")
+ * - MMM: Short month name (e.g., "Jan")
+ * - MM: Month number, zero-padded (e.g., "01")
+ * - YYYY: Full year (e.g., "2026")
+ * - YY: Two-digit year (e.g., "26")
+ * - HH: Hours (24-hour), zero-padded (e.g., "14")
+ * - H: Hours (24-hour) (e.g., "14")
+ * - hh: Hours (12-hour), zero-padded (e.g., "02")
+ * - h: Hours (12-hour) (e.g., "2")
+ * - mm: Minutes, zero-padded (e.g., "05")
+ * - m: Minutes (e.g., "5")
+ * - ss: Seconds, zero-padded (e.g., "09")
+ * - s: Seconds (e.g., "9")
+ * - A: AM/PM uppercase (e.g., "PM")
+ * - a: am/pm lowercase (e.g., "pm")
+ */
+export function formatDate(
+  dateInput: number | string | Date,
+  format: string = "HH:mm:ss day D MMM, YYYY"
+) {
+  const date = new Date(dateInput);
+
+  const pad = (n: number) => String(n).padStart(2, "0");
+
+  const daysFull = [
+    "Sunday",
+    "Monday",
+    "Tuesday",
+    "Wednesday",
+    "Thursday",
+    "Friday",
+    "Saturday",
+  ];
+  const daysShort = ["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"];
+  const monthsFull = [
+    "January",
+    "February",
+    "March",
+    "April",
+    "May",
+    "June",
+    "July",
+    "August",
+    "September",
+    "October",
+    "November",
+    "December",
+  ];
+  const monthsShort = monthsFull.map((m) => m.slice(0, 3));
+
+  // Extract all values once
+  const dayIndex = date.getDay();
+  const dateNum = date.getDate();
+  const monthIndex = date.getMonth();
+  const year = date.getFullYear();
+  const hours24 = date.getHours();
+  const minutes = date.getMinutes();
+  const seconds = date.getSeconds();
+
+  const hours12 = hours24 % 12 || 12;
+  const isPM = hours24 >= 12;
+  const yearStr = String(year);
+
+  const replacements: Record<DateToken, string> = {
+    Day: daysFull[dayIndex],
+    day: daysShort[dayIndex],
+    DD: pad(dateNum),
+    D: String(dateNum),
+    MMMM: monthsFull[monthIndex],
+    MMM: monthsShort[monthIndex],
+    MM: pad(monthIndex + 1),
+    YYYY: yearStr,
+    YY: yearStr.slice(-2),
+    HH: pad(hours24),
+    H: String(hours24),
+    hh: pad(hours12),
+    h: String(hours12),
+    mm: pad(minutes),
+    m: String(minutes),
+    ss: pad(seconds),
+    s: String(seconds),
+    A: isPM ? "PM" : "AM",
+    a: isPM ? "pm" : "am",
+  };
+
+  // Sort tokens by length (longest first) to avoid partial replacements
+  const tokens = (Object.keys(replacements) as DateToken[]).sort(
+    (a, b) => b.length - a.length
+  );
+
+  // Use a single regex replacement to avoid overlapping matches
+  const pattern = new RegExp(tokens.join("|"), "g");
+  return format.replace(pattern, (match) => replacements[match as DateToken]);
+}

package/src/Dates/relativeTime.ts

@@ -0,0 +1,64 @@
+/**
+ * Returns a human-readable relative time string vs Date.now().
+ * Accepts Date | number (ms) | date-string.
+ * Fast, allocation-light, no Intl.
+ */
+export function relativeTime(
+  input: Date | number | string
+): string {
+  const t: number =
+    input instanceof Date
+      ? input.getTime()
+      : typeof input === "number"
+      ? input
+      : Date.parse(input);
+
+  if (!Number.isFinite(t)) return "invalid date";
+
+  const now = Date.now();
+  const diffMs = t - now;
+  const absMs = Math.abs(diffMs);
+  const isFuture = diffMs > 0;
+
+  // time constants (ms)
+  const MIN = 60_000;
+  const HOUR = 3_600_000;
+  const DAY = 86_400_000;
+  const WEEK = 604_800_000;
+  const YEAR = 31_536_000_000;
+
+  // very far away → coarse wording
+  if (absMs > 5 * YEAR) {
+    return isFuture ? "a long time from now" : "a long time ago";
+  }
+
+  if (absMs < MIN) {
+    return "just now";
+  }
+
+  let value: number;
+  let unit: "minute" | "hour" | "day" | "week" | "year";
+
+  if (absMs < HOUR) {
+    value = Math.round(absMs / MIN);
+    unit = "minute";
+  } else if (absMs < DAY) {
+    value = Math.round(absMs / HOUR);
+    unit = "hour";
+  } else if (absMs < WEEK) {
+    value = Math.round(absMs / DAY);
+    unit = "day";
+  } else if (absMs < YEAR) {
+    value = Math.round(absMs / WEEK);
+    unit = "week";
+  } else {
+    value = Math.round(absMs / YEAR);
+    unit = "year";
+  }
+
+  if (value !== 1) unit += "s";
+
+  return isFuture
+    ? `in ${value} ${unit}`
+    : `${value} ${unit} ago`;
+}

package/src/Forms/_index.ts

@@ -0,0 +1 @@
+export * from "./initialiseForm";

package/src/Forms/initialiseForm.ts

@@ -0,0 +1,14 @@
+import type { ActionResponse } from "../API/apiRes";
+
+export function initialiseForm<T extends string = string>(
+  ...fieldNames: T[]
+): ActionResponse<T, T[]> {
+  let fieldErrors = {} as Record<T, T[]>;
+  for (const fieldName of fieldNames) {
+    fieldErrors[fieldName] = [] as T[];
+  }
+  return {
+    success: false,
+    fieldErrors,
+  };
+}

package/src/Numbers/_index.ts

@@ -0,0 +1 @@
+export * from "./remap";

package/src/Numbers/remap.ts

@@ -0,0 +1,28 @@
+/**
+ * This function returns the rounded corresponding value in the target range using linear interpolation.
+ *
+ * @param value - The input value to remap.
+ * @param from - The source range as a tuple [min, max].
+ * @param to - The target range as a tuple [min, max].
+ * @returns The remapped value in the target range.
+ *
+ * @example
+ * remap(3, [1, 10], [1, 5]); // 2
+ */
+export function remap(
+  value: number,
+  from: [number, number],
+  to: [number, number],
+  roundTo: "floor" | "ceil" = "floor",
+): number {
+  const [fromMin, fromMax] = from;
+  const [toMin, toMax] = to;
+
+  if (roundTo == "ceil")
+    return Math.ceil(
+      toMin + ((value - fromMin) * (toMax - toMin)) / (fromMax - fromMin),
+    );
+  return Math.floor(
+    toMin + ((value - fromMin) * (toMax - toMin)) / (fromMax - fromMin),
+  );
+}

package/src/React/_index.ts

@@ -0,0 +1 @@
+export * from "./mergeRefs";

package/src/React/mergeRefs.ts

@@ -0,0 +1,16 @@
+import type { RefObject, Ref } from "react";
+
+export function mergeRefs<T>(
+  ...refs: (Ref<T> | undefined)[]
+): (instance: T | null) => void {
+  return (instance) => {
+    for (const ref of refs) {
+      if (!ref) continue;
+      if (typeof ref === "function") {
+        ref(instance);
+      } else {
+        (ref as RefObject<T | null>).current = instance;
+      }
+    }
+  };
+}

package/src/Strings/_index.ts

@@ -0,0 +1,3 @@
+export * from "./cn";
+export * from "./stringCases";
+export * from "./cssSafeString";

package/src/Strings/cn.ts

@@ -0,0 +1,3 @@
+export function cn(...classNames: (string | undefined)[]) {
+  return classNames.filter((c) => c).join(" ");
+}

package/src/Strings/cssSafeString.ts

@@ -0,0 +1,13 @@
+export function cssSafeString(str: string) {
+  const encoded = encodeURIComponent(str)
+    .toLowerCase()
+    .replace(/\.|%[0-9a-z]{2}/gi, "");
+
+  const firstChar = encoded.charAt(0);
+  if (firstChar.match(/^[0-9-]/)) {
+    // Check if the first character is a number or hyphen
+    return "_" + encoded;
+  }
+
+  return encoded;
+}

package/src/Strings/stringCases.ts

@@ -0,0 +1,50 @@
+function toWords(str: string): string[] {
+  return str
+    .replace(/([a-z])([A-Z])/g, "$1 $2") // camelCase → camel Case
+    .replace(/[_\-]+/g, " ") // snake_case, kebab-case → spaces
+    .trim()
+    .split(/\s+/)
+    .filter(Boolean)
+    .map((w) => w.toLowerCase());
+}
+
+export function toCapitalCase(str: string | undefined): string {
+  if (!str) return "";
+  const words = toWords(str);
+  return words.map((w) => w[0].toUpperCase() + w.slice(1)).join("");
+}
+
+export function toCamelCase(str: string | undefined): string {
+  if (!str) return "";
+
+  const words = toWords(str);
+  return words
+    .map((w, i) => (i === 0 ? w : w[0].toUpperCase() + w.slice(1)))
+    .join("");
+}
+
+export function toKebabCase(str: string | undefined): string {
+  if (!str) return "";
+
+  return toWords(str).join("-");
+}
+
+export function toSnakeCase(str: string | undefined): string {
+  if (!str) return "";
+
+  return toWords(str).join("_");
+}
+
+export function toConstantCase(str: string | undefined): string {
+  if (!str) return "";
+
+  return toWords(str).join("_").toUpperCase();
+}
+
+export function toCapitalised(str: string | undefined): string {
+  if (!str) return "";
+
+  const words = toWords(str);
+  if (words.length === 0) return "";
+  return words.map((w) => w[0].toUpperCase() + w.slice(1)).join(" ");
+}

package/src/index.ts

@@ -0,0 +1,8 @@
+export * from "./API/_index";
+export * from "./Calculations/_index";
+export * from "./Code/_index";
+export * from "./Dates/_index";
+export * from "./Forms/_index";
+export * from "./Numbers/_index";
+export * from "./React/_index";
+export * from "./Strings/_index";

package/tsconfig.json

@@ -0,0 +1,32 @@
+{
+  "compilerOptions": {
+    "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.app.tsbuildinfo",
+    "target": "ES2022",
+    "useDefineForClassFields": true,
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "resolveJsonModule": true,
+    "allowJs": true,
+    "skipLibCheck": true,
+
+    /* Bundler mode */
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "moduleDetection": "force",
+    "noEmit": true,
+    "jsx": "react-jsx",
+    // Output
+    "declaration": true,
+    "outDir": "./dist",
+
+    /* Linting */
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "erasableSyntaxOnly": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedSideEffectImports": true
+  },
+  "include": ["src"]
+}

package/tsup.config.ts

@@ -0,0 +1,9 @@
+import { defineConfig } from "tsup";
+
+export default defineConfig({
+  entry: ["src/index.ts"],
+  splitting: true,
+  sourcemap: true,
+  clean: true,
+  dts: true,
+});