@studiocubics/utils 0.0.1 → 0.0.2

package/package.json

@@ -5,17 +5,17 @@
     "access": "public"
   },
   "private": false,
-  "version": "0.0.1",
+  "version": "0.0.2",
   "main": "./dist/index.js",
   "exports": {
     ".": "./dist/index.js"
   },
   "types": "./dist/index.d.ts",
   "peerDependencies": {
-    "react": "19",
-    "@types/react": "19"
+    "react": ">= 19"
   },
   "devDependencies": {
+    "@types/react": "^19",
     "tsup": "^8.5.1"
   },
   "keywords": [

package/.turbo/turbo-build.log

@@ -1,17 +0,0 @@
-
-> @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

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

package/src/API/_index.ts

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

package/src/API/apiRes.ts

@@ -1,74 +0,0 @@
-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

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

package/src/Calculations/calculateSafePosition.ts

@@ -1,137 +0,0 @@
-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

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

package/src/Code/delay.ts

@@ -1,5 +0,0 @@
-/**
- * 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

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

package/src/Dates/formateDate.ts

@@ -1,140 +0,0 @@
-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

@@ -1,64 +0,0 @@
-/**
- * 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

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

package/src/Forms/initialiseForm.ts

@@ -1,14 +0,0 @@
-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

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

package/src/Numbers/remap.ts

@@ -1,28 +0,0 @@
-/**
- * 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

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

package/src/React/mergeRefs.ts

@@ -1,16 +0,0 @@
-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

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

package/src/Strings/cn.ts

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

package/src/Strings/cssSafeString.ts

@@ -1,13 +0,0 @@
-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

@@ -1,50 +0,0 @@
-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

@@ -1,8 +0,0 @@
-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

@@ -1,32 +0,0 @@
-{
-  "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"]
-}