@cleen/ui-core 0.1.0

package/src/utils/audio.ts

@@ -0,0 +1,69 @@
+/** Minimal synchronous PCM WAV encoder – no extra deps needed =w= */
+export const encodeWav = (buffer: AudioBuffer): Blob => {
+  const { numberOfChannels: channels, sampleRate, length } = buffer;
+  const bitsPerSample = 16;
+  const blockAlign = (channels * bitsPerSample) / 8;
+  const byteRate = sampleRate * blockAlign;
+  const dataSize = length * blockAlign;
+  const wavBuffer = new ArrayBuffer(44 + dataSize);
+  const v = new DataView(wavBuffer);
+
+  const str = (offset: number, s: string) => {
+    for (let i = 0; i < s.length; i++) v.setUint8(offset + i, s.charCodeAt(i));
+  };
+
+  str(0, 'RIFF');
+  v.setUint32(4, 36 + dataSize, true);
+  str(8, 'WAVE');
+  str(12, 'fmt ');
+  v.setUint32(16, 16, true);
+  v.setUint16(20, 1, true); // PCM
+  v.setUint16(22, channels, true);
+  v.setUint32(24, sampleRate, true);
+  v.setUint32(28, byteRate, true);
+  v.setUint16(32, blockAlign, true);
+  v.setUint16(34, bitsPerSample, true);
+  str(36, 'data');
+  v.setUint32(40, dataSize, true);
+
+  let offset = 44;
+  for (let i = 0; i < length; i++) {
+    for (let ch = 0; ch < channels; ch++) {
+      const s = Math.max(-1, Math.min(1, buffer.getChannelData(ch)[i]));
+      v.setInt16(offset, s < 0 ? s * 0x8000 : s * 0x7fff, true);
+      offset += 2;
+    }
+  }
+
+  return new Blob([wavBuffer], { type: 'audio/wav' });
+};
+
+export const trimBlob = async (
+  blob: Blob,
+  startSec: number,
+  endSec: number
+): Promise<Blob> => {
+  const ctx = new AudioContext();
+  const decoded = await ctx.decodeAudioData(await blob.arrayBuffer());
+  await ctx.close();
+
+  const { sampleRate, numberOfChannels } = decoded;
+  const startSample = Math.round(startSec * sampleRate);
+  const endSample = Math.round(endSec * sampleRate);
+  const trimLength = endSample - startSample;
+
+  // OfflineAudioContext would add latency; just slice the buffers directly
+  const trimmedBuffer = new AudioContext().createBuffer(
+    numberOfChannels,
+    trimLength,
+    sampleRate
+  );
+  for (let ch = 0; ch < numberOfChannels; ch++) {
+    trimmedBuffer.copyToChannel(
+      decoded.getChannelData(ch).subarray(startSample, endSample),
+      ch
+    );
+  }
+
+  return encodeWav(trimmedBuffer);
+};

package/src/utils/cn.ts

@@ -0,0 +1,13 @@
+import clsx, { type ClassValue } from 'clsx';
+import { createTailwindMerge, getDefaultConfig } from 'tailwind-merge';
+
+const twConfig = () => ({
+  ...getDefaultConfig(),
+  prefix: 'cleen-',
+});
+
+const twMerge = createTailwindMerge(twConfig);
+
+export const cn = (...inputs: ClassValue[]) => {
+  return twMerge(clsx(inputs));
+};

package/src/utils/colors.ts

@@ -0,0 +1,159 @@
+import {
+  darken,
+  getLuminance,
+  lighten,
+  parseToRgba,
+  toHex,
+  toRgba,
+} from 'color2k';
+
+type RGBA = [number, number, number, number];
+
+export class ColorHelpers {
+  /**
+   * Calculates the Delta E (CIE94) between two RGB colors.
+   *
+   * Delta E is a metric for color difference. Based on the value, we can describe how different the colors are:
+   *
+   * Perception Levels:
+   * - Delta E <= 1.0: Not perceptible by human eyes.
+   * - Delta E between 1-2: Perceptible through close observation.
+   * - Delta E between 2-10: Perceptible at a glance.
+   * - Delta E between 11-49: Colors are more similar than opposite.
+   * - Delta E = 100: Colors are exact opposites.
+   *
+   * @param {Array<number>} rgb1 - The first RGB color as an array [R, G, B].
+   * @param {Array<number>} rgb2 - The second RGB color as an array [R, G, B].
+   * @returns {number} The Delta E value representing the difference between the two colors.
+   *
+   * @example
+   * deltaE([128, 0, 255], [128, 0, 255]); // 0
+   * deltaE([128, 0, 255], [128, 0, 230]); // 3.175
+   * deltaE([128, 0, 255], [255, 0, 0]);   // 61.24
+   */
+  static deltaE(rgbA: RGBA, rgbB: RGBA) {
+    const labA = ColorHelpers.rgb2lab(rgbA);
+    const labB = ColorHelpers.rgb2lab(rgbB);
+
+    const deltaL = labA[0] - labB[0];
+    const deltaA = labA[1] - labB[1];
+    const deltaB = labA[2] - labB[2];
+    const c1 = Math.sqrt(labA[1] * labA[1] + labA[2] * labA[2]);
+    const c2 = Math.sqrt(labB[1] * labB[1] + labB[2] * labB[2]);
+    const deltaC = c1 - c2;
+    let deltaH = deltaA * deltaA + deltaB * deltaB - deltaC * deltaC;
+    deltaH = deltaH < 0 ? 0 : Math.sqrt(deltaH);
+    const sc = 1.0 + 0.045 * c1;
+    const sh = 1.0 + 0.015 * c1;
+    const deltaLKlsl = deltaL / 1.0;
+    const deltaCkcsc = deltaC / sc;
+    const deltaHkhsh = deltaH / sh;
+    const i =
+      deltaLKlsl * deltaLKlsl +
+      deltaCkcsc * deltaCkcsc +
+      deltaHkhsh * deltaHkhsh;
+    return i < 0 ? 0 : Math.sqrt(i);
+  }
+
+  static rgb2lab(rgb: RGBA) {
+    let r = rgb[0] / 255,
+      g = rgb[1] / 255,
+      b = rgb[2] / 255,
+      x,
+      y,
+      z;
+    r = r > 0.04045 ? Math.pow((r + 0.055) / 1.055, 2.4) : r / 12.92;
+    g = g > 0.04045 ? Math.pow((g + 0.055) / 1.055, 2.4) : g / 12.92;
+    b = b > 0.04045 ? Math.pow((b + 0.055) / 1.055, 2.4) : b / 12.92;
+    x = (r * 0.4124 + g * 0.3576 + b * 0.1805) / 0.95047;
+    y = (r * 0.2126 + g * 0.7152 + b * 0.0722) / 1.0;
+    z = (r * 0.0193 + g * 0.1192 + b * 0.9505) / 1.08883;
+    x = x > 0.008856 ? Math.pow(x, 1 / 3) : 7.787 * x + 16 / 116;
+    y = y > 0.008856 ? Math.pow(y, 1 / 3) : 7.787 * y + 16 / 116;
+    z = z > 0.008856 ? Math.pow(z, 1 / 3) : 7.787 * z + 16 / 116;
+    return [116 * y - 16, 500 * (x - y), 200 * (y - z)];
+  }
+
+  static isSimilar(color1: string, color2: string, defaultDeltaE = 24) {
+    const e = ColorHelpers.deltaE(parseToRgba(color1), parseToRgba(color2));
+    return e < defaultDeltaE;
+  }
+
+  static adjustColorForContrast(hexColor: string, amount = 0.25) {
+    // Always convert to hex for polished
+    let _colorAsHex = toHex(hexColor);
+    let result = hexColor;
+
+    try {
+      // If color is almost white, force to pure white to avoid hue bias
+      if (
+        _colorAsHex.match(/^#f{2,}e{0,2}$/i) ||
+        getLuminance(_colorAsHex) > 0.98
+      ) {
+        _colorAsHex = '#ffffff';
+      }
+
+      if (getLuminance(_colorAsHex) > 0.6) {
+        const darkenedColorHSLA = darken(_colorAsHex, amount);
+        const darkenedColorRGBA = toRgba(darkenedColorHSLA);
+        result = darkenedColorRGBA;
+      } else {
+        const lightenedColorHSLA = lighten(_colorAsHex, amount);
+        const lightenedColorRGBA = toRgba(lightenedColorHSLA);
+        result = lightenedColorRGBA;
+      }
+
+      return result;
+    } catch {
+      return 'rgba(var(--cleen-white)';
+    }
+  }
+
+  // Util functions to get color based on pass string (CSS variables can be parsed as well)
+  static getComputedColor(color?: string) {
+    if (!color?.includes('var(')) {
+      return color;
+    }
+
+    // Extract variable name from var(--variable-name)
+    const varName = color.match(/var\((--[^,)]+)/)?.[1];
+
+    if (varName && typeof window !== 'undefined') {
+      // Get the computed style value from the document
+      const color = getComputedStyle(document.documentElement)
+        .getPropertyValue(varName)
+        .trim();
+
+      return color ? `rgb(${color})` : undefined;
+    }
+
+    return undefined;
+  }
+
+  static getComputedRgb(color?: string) {
+    if (!color) {
+      return undefined;
+    }
+
+    if (!color?.includes('var(')) {
+      const [r, g, b] = parseToRgba(color);
+      return `${r}, ${g}, ${b}`;
+    }
+
+    // Extract variable name from var(--variable-name)
+    const varName = color.match(/var\((--[^,)]+)/)?.[1];
+
+    if (varName && typeof window !== 'undefined') {
+      // Get the computed style value from the document
+      return getComputedStyle(document.documentElement)
+        .getPropertyValue(varName)
+        .trim();
+    }
+
+    return undefined;
+  }
+
+  static trasparentize(color?: string, value = 0) {
+    return `color-mix(in srgb, ${color} ${(1 - value) * 100}%, transparent)`;
+  }
+}

package/src/utils/images.ts

@@ -0,0 +1,42 @@
+const PICSUM_BASE_URL = 'https://picsum.photos';
+
+interface PicsumOptions {
+  width: number;
+  height?: number;
+  grayscale?: boolean;
+  blur?: number; // 1 to 10
+  seed?: string; // for consistent images
+}
+
+export const getRandomImageUrl = (options: PicsumOptions): string => {
+  const { width, height, grayscale, blur, seed } = options;
+
+  let url = PICSUM_BASE_URL;
+
+  if (seed) {
+    url += `/seed/${encodeURIComponent(seed)}`;
+  }
+
+  url += `/${width}/${height || width}`;
+
+  const params = new URLSearchParams();
+
+  if (grayscale) {
+    params.append('grayscale', '');
+  }
+
+  if (blur) {
+    params.append('blur', blur.toString());
+  }
+
+  if (seed) {
+    params.append('seed', seed);
+  }
+
+  const queryString = params.toString();
+  if (queryString) {
+    url += `?${queryString}`;
+  }
+
+  return url;
+};

package/src/utils/object.ts

@@ -0,0 +1,86 @@
+/**
+ * Deep partial type — makes all properties optional recursively.
+ */
+export type PartialDeep<T> = T extends (...args: unknown[]) => unknown
+  ? T
+  : T extends Array<infer U>
+    ? Array<PartialDeep<U>>
+    : T extends object
+      ? { [K in keyof T]?: PartialDeep<T[K]> }
+      : T | undefined;
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    !Array.isArray(value) &&
+    Object.prototype.toString.call(value) === '[object Object]'
+  );
+}
+
+/**
+ * Recursively apply values on top of default values.
+ *
+ * Rules / assumptions:
+ * - Plain objects are merged recursively.
+ * - Arrays are replaced entirely by provided values (not concatenated).
+ * - If a provided value is `undefined`, the default is kept.
+ * - If a provided value is `null`, it overrides the default.
+ * - Non-plain objects (Date, RegExp, Map, Set, class instances) are replaced by the provided value when present.
+ *
+ * Example:
+ *   const defaults = { a: 1, b: { c: 2, d: [1] } };
+ *   const vals = { b: { c: 3 } };
+ *   applyDefaults(defaults, vals) // => { a: 1, b: { c: 3, d: [1] } }
+ */
+export function applyDefaults<T>(defaults: T, values?: PartialDeep<T>): T {
+  // Internal recursive merge
+  const merge = (d: unknown, v: unknown): unknown => {
+    // If v is explicitly undefined, keep default
+    if (v === undefined) {
+      return cloneValue(d);
+    }
+
+    // If both are plain objects, merge recursively
+    if (isPlainObject(d) && isPlainObject(v)) {
+      const result: Record<string, unknown> = {};
+      const keys = new Set<string>([...Object.keys(d), ...Object.keys(v)]);
+      keys.forEach(key => {
+        const dv = (d as Record<string, unknown>)[key];
+        const vv = (v as Record<string, unknown>)[key];
+        result[key] = merge(dv, vv);
+      });
+      return result;
+    }
+
+    // Arrays: prefer provided value (replace), or clone default if v is undefined handled above
+    if (Array.isArray(d) || Array.isArray(v)) {
+      if (v === undefined) return cloneValue(d);
+      // If provided a value for array, return clone of that array
+      return cloneValue(v);
+    }
+
+    // For all other cases, if v is provided (including null), use it; otherwise clone default
+    return v !== undefined ? cloneValue(v) : cloneValue(d);
+  };
+
+  // Shallow/deep clone helper for primitives, arrays and plain objects
+  const cloneValue = (x: unknown): unknown => {
+    if (x === undefined) return undefined;
+    if (x === null) return null;
+    if (Array.isArray(x)) return (x as unknown[]).map(item => cloneValue(item));
+    if (isPlainObject(x)) {
+      const o: Record<string, unknown> = {};
+      Object.keys(x as Record<string, unknown>).forEach(k => {
+        o[k] = cloneValue((x as Record<string, unknown>)[k]);
+      });
+      return o;
+    }
+    // For non-plain objects (Date, RegExp, Map, Set, etc.) and primitives, return as is
+    return x;
+  };
+
+  return merge(defaults, values) as T;
+}
+
+export default applyDefaults;

package/src/utils/position.ts

@@ -0,0 +1,140 @@
+import type { Position } from '@/types/position';
+
+// Neat lil' helper to calculate the optimal position based on viewport
+export const calculateOptimalPosition = (
+  overlayRect: DOMRect,
+  triggerRect: DOMRect,
+  preferredPosition: Position
+): Position => {
+  const viewport = {
+    width: window.innerWidth,
+    height: window.innerHeight,
+  };
+
+  let newPosition = preferredPosition;
+
+  // Handle side positions (left/right)
+  if (preferredPosition === 'left' || preferredPosition === 'right') {
+    const isLeft = preferredPosition === 'left';
+    const spaceLeft = triggerRect.left;
+    const spaceRight = viewport.width - triggerRect.right;
+
+    if (
+      isLeft &&
+      spaceLeft < overlayRect.width &&
+      spaceRight > overlayRect.width
+    ) {
+      return 'right';
+    } else if (
+      !isLeft &&
+      spaceRight < overlayRect.width &&
+      spaceLeft > overlayRect.width
+    ) {
+      return 'left';
+    }
+    return newPosition;
+  }
+
+  // Check vertical bounds for top/bottom positions
+  const isBottom = preferredPosition.startsWith('bottom');
+  const spaceBelow = viewport.height - triggerRect.bottom;
+  const spaceAbove = triggerRect.top;
+
+  if (
+    isBottom &&
+    spaceBelow < overlayRect.height &&
+    spaceAbove > overlayRect.height
+  ) {
+    newPosition = preferredPosition.replace('bottom', 'top') as Position;
+  } else if (
+    !isBottom &&
+    preferredPosition.startsWith('top') &&
+    spaceAbove < overlayRect.height &&
+    spaceBelow > overlayRect.height
+  ) {
+    newPosition = preferredPosition.replace('top', 'bottom') as Position;
+  }
+
+  // Check horizontal bounds for corner positions
+  if (preferredPosition.includes('-')) {
+    const isLeft = preferredPosition.endsWith('left');
+    const spaceRight = viewport.width - triggerRect.right;
+    const spaceLeft = triggerRect.left;
+
+    if (
+      isLeft &&
+      spaceRight < overlayRect.width &&
+      spaceLeft > overlayRect.width
+    ) {
+      newPosition = newPosition.replace('left', 'right') as Position;
+    } else if (
+      !isLeft &&
+      spaceRight < overlayRect.width &&
+      spaceLeft > overlayRect.width
+    ) {
+      newPosition = newPosition.replace('right', 'left') as Position;
+    }
+  }
+
+  return newPosition;
+};
+
+// Calculate the top/left values based on the final position
+export const calculatePositionValues = (
+  overlayRect: DOMRect,
+  triggerRect: DOMRect,
+  position: Position,
+  offset?: number
+) => {
+  if (!triggerRect) {
+    return { top: 0, left: 0 };
+  }
+
+  const scrollY = window.scrollY;
+  const scrollX = window.scrollX;
+  const gap = offset || 0;
+
+  // Handle vertical positioning (top/bottom)
+  let top = 0;
+  if (position.startsWith('bottom')) {
+    top = triggerRect.bottom + scrollY + gap;
+  } else if (position.startsWith('top')) {
+    top = triggerRect.top + scrollY - (overlayRect?.height || 0) - gap;
+  } else {
+    // left/right positions - vertically center
+    top =
+      triggerRect.top +
+      scrollY +
+      triggerRect.height / 2 -
+      (overlayRect?.height || 0) / 2;
+  }
+
+  // Handle horizontal positioning (left/right)
+  let left = 0;
+  if (position === 'left') {
+    // Pure "left" - place overlay outside to the left of trigger
+    left = triggerRect.left + scrollX - (overlayRect?.width || 0) - gap;
+  } else if (position === 'right') {
+    // Pure "right" - place overlay outside to the right of trigger
+    left = triggerRect.right + scrollX + gap;
+  } else if (
+    position.endsWith('left') ||
+    position === 'bottom' ||
+    position === 'top'
+  ) {
+    left = triggerRect.left + scrollX;
+  } else if (position.endsWith('right')) {
+    left = triggerRect.right + scrollX - (overlayRect?.width || 0);
+  }
+
+  // Special handling for centered positions
+  if (position === 'bottom' || position === 'top') {
+    left =
+      triggerRect.left +
+      scrollX +
+      triggerRect.width / 2 -
+      (overlayRect?.width || 0) / 2;
+  }
+
+  return { top, left };
+};

package/src/utils/string.ts

@@ -0,0 +1,27 @@
+export const formatFileSize = (bytes?: number) => {
+  if (bytes === 0 || !bytes) {
+    return '0 B';
+  }
+
+  const k = 1024;
+  const sizes = ['B', 'KB', 'MB', 'GB', 'TB'];
+  const i = Math.floor(Math.log(bytes) / Math.log(k));
+  return Math.round(bytes / Math.pow(k, i)) + ' ' + sizes[i];
+};
+
+// Calculate "mm:ss" from seconds
+export const formatAudioTime = (seconds: number): string => {
+  const mins = Math.floor(seconds / 60);
+  const secs = Math.floor(seconds % 60);
+  return `${String(mins).padStart(2, '0')}:${String(secs).padStart(2, '0')}`;
+};
+
+// Calculate "created X days ago"
+export const getCreatedDate = (date: string) => {
+  const created = new Date(date);
+  const now = new Date();
+
+  const diffTime = Math.abs(now.getTime() - created.getTime());
+  const diffDays = Math.ceil(diffTime / (1000 * 60 * 60 * 24));
+  return `Created ${diffDays} days ago`;
+};