@yewdiel21/motion-kit 0.9.1 → 0.14.0

package/src/core/color.ts

@@ -0,0 +1,304 @@
+/*
+ * Colour model for the colour components. HSVA is the working space (h 0–360,
+ * s and v 0–100, a 0–1): the saturation × brightness area and the hue slider
+ * map onto it directly. Parses #rgb, #rgba, #rrggbb, #rrggbbaa, rgb()/rgba()
+ * and hsl()/hsla() (comma or space syntax, optional "/ alpha"); formats hex,
+ * rgb or hsl (alpha only when below 1). A grey keeps the hue it is given, so
+ * dragging through grey never resets the hue.
+ */
+
+export interface Hsva {
+  /** 0–360. */
+  h: number;
+  /** 0–100. */
+  s: number;
+  /** 0–100. */
+  v: number;
+  /** 0–1. */
+  a: number;
+}
+
+export interface Rgba {
+  /** 0–255. */
+  r: number;
+  g: number;
+  b: number;
+  a: number;
+}
+
+export interface Hsla {
+  h: number;
+  /** 0–100. */
+  s: number;
+  l: number;
+  a: number;
+}
+
+export type ColorFormat = 'hex' | 'rgb' | 'hsl';
+export type ColorChannel = 'hue' | 'saturation' | 'brightness' | 'lightness' | 'red' | 'green' | 'blue' | 'alpha';
+
+export const CHANNEL_LABELS: Record<ColorChannel, string> = {
+  hue: 'Tono',
+  saturation: 'Saturación',
+  brightness: 'Brillo',
+  lightness: 'Luminosidad',
+  red: 'Rojo',
+  green: 'Verde',
+  blue: 'Azul',
+  alpha: 'Opacidad',
+};
+
+export const CHANNEL_RANGE: Record<ColorChannel, [number, number]> = {
+  hue: [0, 360],
+  saturation: [0, 100],
+  brightness: [0, 100],
+  lightness: [0, 100],
+  red: [0, 255],
+  green: [0, 255],
+  blue: [0, 255],
+  alpha: [0, 1],
+};
+
+const clamp = (n: number, min: number, max: number) => Math.min(max, Math.max(min, Number.isFinite(n) ? n : min));
+/** Two decimals: enough for a lossless 8-bit round trip, without float noise (31.999…). */
+const tidy = (n: number) => Math.round(n * 100) / 100;
+const wrapHue = (h: number) => {
+  const hue = ((h % 360) + 360) % 360;
+  return hue === 0 && h > 0 ? 360 : hue;
+};
+
+const hsva = (h: number, s: number, v: number, a: number): Hsva => ({
+  h: tidy(clamp(h, 0, 360)),
+  s: tidy(clamp(s, 0, 100)),
+  v: tidy(clamp(v, 0, 100)),
+  a: Math.round(clamp(a, 0, 1) * 1000) / 1000,
+});
+
+/** HSVA → RGBA (channels 0–255, unrounded). */
+export function hsvToRgb({ h, s, v, a }: Hsva): Rgba {
+  const sat = s / 100;
+  const val = v / 100;
+  const f = (n: number) => {
+    const k = (n + (h % 360) / 60) % 6;
+    return val - val * sat * Math.max(0, Math.min(k, 4 - k, 1));
+  };
+  return { r: f(5) * 255, g: f(3) * 255, b: f(1) * 255, a };
+}
+
+/** RGBA → HSVA; a grey keeps `hue` (and black keeps `saturation`) when given. */
+export function rgbToHsv({ r, g, b, a }: Rgba, hue?: number, saturation?: number): Hsva {
+  const [red, green, blue] = [r / 255, g / 255, b / 255];
+  const max = Math.max(red, green, blue);
+  const min = Math.min(red, green, blue);
+  const delta = max - min;
+  let h = hue ?? 0;
+  if (delta > 0) {
+    if (max === red) h = 60 * (((green - blue) / delta) % 6);
+    else if (max === green) h = 60 * ((blue - red) / delta + 2);
+    else h = 60 * ((red - green) / delta + 4);
+    if (h < 0) h += 360;
+  }
+  const s = max === 0 ? (saturation ?? 0) : (delta / max) * 100;
+  return hsva(h, s, max * 100, a);
+}
+
+export function hsvToHsl({ h, s, v, a }: Hsva): Hsla {
+  const sat = s / 100;
+  const val = v / 100;
+  const l = val * (1 - sat / 2);
+  const sl = l === 0 || l === 1 ? 0 : (val - l) / Math.min(l, 1 - l);
+  return { h, s: sl * 100, l: l * 100, a };
+}
+
+export function hslToHsv({ h, s, l, a }: Hsla, saturation?: number): Hsva {
+  const sat = s / 100;
+  const light = l / 100;
+  const v = light + sat * Math.min(light, 1 - light);
+  const sv = v === 0 ? (saturation ?? 0) / 100 : 2 * (1 - light / v);
+  return hsva(h, sv * 100, v * 100, a);
+}
+
+const number = (text: string, scale: number) => {
+  const value = Number.parseFloat(text);
+  if (!Number.isFinite(value)) return Number.NaN;
+  return text.trim().endsWith('%') ? (value / 100) * scale : value;
+};
+
+const alphaOf = (text: string | undefined) => (text === undefined ? 1 : clamp(number(text, 1), 0, 1));
+
+const angle = (text: string) => {
+  const value = Number.parseFloat(text);
+  if (!Number.isFinite(value)) return Number.NaN;
+  if (/turn$/i.test(text)) return value * 360;
+  if (/grad$/i.test(text)) return value * 0.9;
+  if (/rad$/i.test(text)) return (value * 180) / Math.PI;
+  return value;
+};
+
+/** "rgb(1, 2, 3)", "rgb(1 2 3 / 50%)" → its parts, or null. */
+function args(text: string, name: string): string[] | null {
+  const match = new RegExp(`^${name}a?\\(\\s*([^)]*)\\)$`, 'i').exec(text);
+  if (!match) return null;
+  const body = match[1]!.trim();
+  const [main, slash] = body.split('/');
+  const parts = main!.includes(',') ? main!.split(',').map((part) => part.trim()) : main!.trim().split(/\s+/);
+  if (slash !== undefined) {
+    if (main!.includes(',') || parts.length !== 3) return null;
+    parts.push(slash.trim());
+  }
+  if (parts.length < 3 || parts.length > 4 || parts.some((part) => !part)) return null;
+  return parts;
+}
+
+/**
+ * Any colour the components accept, as HSVA; null when the text is not one.
+ * `hue` is kept for greys (no hue of their own).
+ */
+export function parseColor(input: string | null | undefined, hue?: number): Hsva | null {
+  const text = (input ?? '').trim().toLowerCase();
+  if (!text) return null;
+  const hex = /^#?([0-9a-f]{3,4}|[0-9a-f]{6}|[0-9a-f]{8})$/.exec(text);
+  if (hex) {
+    let digits = hex[1]!;
+    if (digits.length <= 4) digits = [...digits].map((c) => c + c).join('');
+    const channel = (i: number) => Number.parseInt(digits.slice(i, i + 2), 16);
+    return rgbToHsv({ r: channel(0), g: channel(2), b: channel(4), a: digits.length === 8 ? channel(6) / 255 : 1 }, hue);
+  }
+  const rgb = args(text, 'rgb');
+  if (rgb) {
+    const [r, g, b] = rgb.slice(0, 3).map((part) => number(part, 255));
+    const a = alphaOf(rgb[3]);
+    if (![r, g, b, a].every(Number.isFinite)) return null;
+    return rgbToHsv({ r: clamp(r!, 0, 255), g: clamp(g!, 0, 255), b: clamp(b!, 0, 255), a }, hue);
+  }
+  const hsl = args(text, 'hsl');
+  if (hsl) {
+    const h = angle(hsl[0]!);
+    const s = Number.parseFloat(hsl[1]!);
+    const l = Number.parseFloat(hsl[2]!);
+    const a = alphaOf(hsl[3]);
+    if (![h, s, l, a].every(Number.isFinite)) return null;
+    const color = hslToHsv({ h: wrapHue(h), s: clamp(s, 0, 100), l: clamp(l, 0, 100), a });
+    return color.s === 0 && hue !== undefined ? { ...color, h: hue } : color;
+  }
+  return null;
+}
+
+const DEFAULT: Hsva = { h: 0, s: 100, v: 100, a: 1 };
+
+/** A colour option (text or HSVA) as HSVA; `fallback` (default red) when it cannot be read. */
+export function toHsva(input: string | Hsva | null | undefined, fallback: Hsva = DEFAULT): Hsva {
+  if (input && typeof input === 'object') return hsva(input.h, input.s, input.v, input.a ?? 1);
+  return parseColor(input, fallback.h) ?? { ...fallback };
+}
+
+const byte = (n: number) => Math.round(clamp(n, 0, 255));
+const hex2 = (n: number) => byte(n).toString(16).padStart(2, '0');
+const short = (n: number) => String(Math.round(n * 100) / 100);
+
+/** #rrggbb, or #rrggbbaa when translucent. */
+export function toHex(color: Hsva): string {
+  const { r, g, b, a } = hsvToRgb(color);
+  const alpha = byte(a * 255);
+  return `#${hex2(r)}${hex2(g)}${hex2(b)}${alpha < 255 ? hex2(alpha) : ''}`;
+}
+
+/** The colour as CSS text: hex, "rgb(255 136 0 / 0.5)" or "hsl(32 100% 50%)". */
+export function formatColor(color: Hsva, format: ColorFormat = 'hex'): string {
+  if (format === 'rgb') {
+    const { r, g, b, a } = hsvToRgb(color);
+    return `rgb(${byte(r)} ${byte(g)} ${byte(b)}${a < 1 ? ` / ${short(a)}` : ''})`;
+  }
+  if (format === 'hsl') {
+    const { h, s, l, a } = hsvToHsl(color);
+    return `hsl(${Math.round(h) % 360} ${Math.round(s)}% ${Math.round(l)}%${a < 1 ? ` / ${short(a)}` : ''})`;
+  }
+  return toHex(color);
+}
+
+/** Same colour on screen (same 8-bit hex). */
+export const sameColor = (a: Hsva, b: Hsva) => toHex(a) === toHex(b);
+
+/** Relative luminance (WCAG), 0–1, ignoring alpha. */
+export function luminance(color: Hsva): number {
+  const { r, g, b } = hsvToRgb(color);
+  const linear = (n: number) => {
+    const c = n / 255;
+    return c <= 0.03928 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;
+  };
+  return 0.2126 * linear(r) + 0.7152 * linear(g) + 0.0722 * linear(b);
+}
+
+/** One channel's value in its own range (CHANNEL_RANGE). */
+export function getChannel(color: Hsva, channel: ColorChannel): number {
+  switch (channel) {
+    case 'hue':
+      return color.h;
+    case 'saturation':
+      return color.s;
+    case 'brightness':
+      return color.v;
+    case 'alpha':
+      return color.a;
+    case 'lightness':
+      return tidy(hsvToHsl(color).l);
+    default: {
+      const rgb = hsvToRgb(color);
+      return byte(channel === 'red' ? rgb.r : channel === 'green' ? rgb.g : rgb.b);
+    }
+  }
+}
+
+/** A copy with one channel changed (clamped to its range); the hue survives greys. */
+export function setChannel(color: Hsva, channel: ColorChannel, value: number): Hsva {
+  const [min, max] = CHANNEL_RANGE[channel];
+  const next = clamp(value, min, max);
+  switch (channel) {
+    case 'hue':
+      return hsva(next, color.s, color.v, color.a);
+    case 'saturation':
+      return hsva(color.h, next, color.v, color.a);
+    case 'brightness':
+      return hsva(color.h, color.s, next, color.a);
+    case 'alpha':
+      return hsva(color.h, color.s, color.v, next);
+    case 'lightness': {
+      const hsl = hsvToHsl(color);
+      return { ...hslToHsv({ ...hsl, l: next }, color.s), h: color.h };
+    }
+    default: {
+      const rgb = hsvToRgb(color);
+      const key = channel === 'red' ? 'r' : channel === 'green' ? 'g' : 'b';
+      return rgbToHsv({ ...rgb, [key]: next }, color.h, color.s);
+    }
+  }
+}
+
+/** What a channel's value reads as: "210°", "64 %", "136". */
+export function channelText(channel: ColorChannel, value: number, format?: Intl.NumberFormat): string {
+  const shown = (n: number) => (format ? format.format(n) : String(Math.round(n)));
+  if (channel === 'hue') return `${shown(value)}°`;
+  if (channel === 'alpha') return `${shown(value * 100)} %`;
+  if (channel === 'red' || channel === 'green' || channel === 'blue') return shown(value);
+  return `${shown(value)} %`;
+}
+
+const rgbText = (color: Hsva) => formatColor(color, 'rgb');
+
+/** A slider track for `channel` at `color`: the channel's whole range, the other channels fixed. */
+export function channelGradient(color: Hsva, channel: ColorChannel, direction = 'to right'): string {
+  const opaque = { ...color, a: 1 };
+  let stops: string[];
+  if (channel === 'hue') stops = [0, 60, 120, 180, 240, 300, 360].map((h) => rgbText({ h, s: 100, v: 100, a: 1 }));
+  else if (channel === 'alpha') stops = [rgbText({ ...opaque, a: 0 }), rgbText(opaque)];
+  else if (channel === 'lightness') stops = [0, 50, 100].map((l) => rgbText(setChannel(opaque, 'lightness', l)));
+  else {
+    const [min, max] = CHANNEL_RANGE[channel];
+    stops = [setChannel(opaque, channel, min), setChannel(opaque, channel, max)].map(rgbText);
+  }
+  return `linear-gradient(${direction}, ${stops.join(', ')})`;
+}
+
+/** The saturation (x) × brightness (y) square at hue `h`. */
+export const areaBackground = (h: number) =>
+  `linear-gradient(to top, #000, transparent), linear-gradient(to right, #fff, hsl(${Math.round(h) % 360} 100% 50%))`;

package/src/core/date-range.ts

@@ -0,0 +1,67 @@
+import { addDays, dayKey, sameDay, toDate, type DateInput } from './dates';
+
+/*
+ * Date ranges on local days (range-calendar, date-range-picker): reading a
+ * {start, end} option, the day rules (min, max, unavailable days) and the
+ * two-click pick — the first click fixes an anchor, the second closes the
+ * range in either direction; crossing an unavailable day restarts at the
+ * clicked day.
+ */
+
+export interface DateRange {
+  start: Date;
+  end: Date;
+}
+
+export interface DayRules {
+  min?: Date | null;
+  max?: Date | null;
+  isUnavailable?: (day: Date) => boolean;
+}
+
+const valid = (input: DateInput | null | undefined) => {
+  if (input === null || input === undefined || input === '') return null;
+  const date = toDate(input, new Date(Number.NaN));
+  return Number.isNaN(date.getTime()) ? null : date;
+};
+
+/** An ordered range from {start, end} (Dates or 'YYYY-MM-DD'); null when either end is missing or unreadable. */
+export function toRange(value: { start?: DateInput | null; end?: DateInput | null } | null | undefined): DateRange | null {
+  if (!value) return null;
+  const start = valid(value.start);
+  const end = valid(value.end);
+  if (!start || !end) return null;
+  return start <= end ? { start, end } : { start: end, end: start };
+}
+
+export const rangeKeys = (range: DateRange) => ({ start: dayKey(range.start), end: dayKey(range.end) });
+
+export const inRange = (day: Date, range: DateRange | null | undefined) => !!range && day >= range.start && day <= range.end;
+
+/** Days from start to end, both included. */
+export const rangeLength = (range: DateRange) =>
+  Math.round((Date.UTC(range.end.getFullYear(), range.end.getMonth(), range.end.getDate()) - Date.UTC(range.start.getFullYear(), range.start.getMonth(), range.start.getDate())) / 86400000) + 1;
+
+export function isPickable(day: Date, rules: DayRules = {}): boolean {
+  if (rules.min && day < rules.min) return false;
+  if (rules.max && day > rules.max) return false;
+  return !rules.isUnavailable?.(day);
+}
+
+/** Every day of the range can be picked. */
+export function rangeIsPickable(range: DateRange, rules: DayRules = {}): boolean {
+  for (let day = range.start; day <= range.end; day = addDays(day, 1)) if (!isPickable(day, rules)) return false;
+  return true;
+}
+
+/**
+ * One click. Without an anchor, `day` becomes it. With one, the range closes
+ * (ordered); if it would cross a day that cannot be picked, `day` becomes the
+ * new anchor instead. Clicking the anchor again makes a one-day range.
+ */
+export function pickDay(anchor: Date | null, day: Date, rules: DayRules = {}): { anchor: Date | null; range: DateRange | null } {
+  if (!anchor) return { anchor: day, range: null };
+  const range = anchor <= day ? { start: anchor, end: day } : { start: day, end: anchor };
+  if (!sameDay(anchor, day) && !rangeIsPickable(range, rules)) return { anchor: day, range: null };
+  return { anchor: null, range };
+}

package/src/core/dates.ts

@@ -0,0 +1,108 @@
+/*
+ * Calendar date helpers on local dates (no time zone maths): the calendar and
+ * slot-picker components share them. Days are compared by their YYYY-MM-DD key.
+ */
+
+export type DateInput = Date | string | number;
+
+/** Local midnight of a date; "2026-10-23" is read as a local day, not UTC. */
+export function toDate(input: DateInput | null | undefined, fallback = new Date()): Date {
+  if (input instanceof Date) return Number.isNaN(input.getTime()) ? startOfDay(fallback) : startOfDay(input);
+  if (typeof input === 'string') {
+    const day = /^(\d{4})-(\d{2})-(\d{2})$/.exec(input.trim());
+    if (day) return new Date(Number(day[1]), Number(day[2]) - 1, Number(day[3]));
+  }
+  if (typeof input === 'string' || typeof input === 'number') {
+    const parsed = new Date(input);
+    if (!Number.isNaN(parsed.getTime())) return startOfDay(parsed);
+  }
+  return startOfDay(fallback);
+}
+
+/** A full date-time (events keep their hour). */
+export function toDateTime(input: DateInput): Date | null {
+  if (input instanceof Date) return Number.isNaN(input.getTime()) ? null : input;
+  if (typeof input === 'string' && /^\d{4}-\d{2}-\d{2}$/.test(input.trim())) return toDate(input);
+  const parsed = new Date(input);
+  return Number.isNaN(parsed.getTime()) ? null : parsed;
+}
+
+export const startOfDay = (date: Date) => new Date(date.getFullYear(), date.getMonth(), date.getDate());
+
+export const addDays = (date: Date, days: number) => new Date(date.getFullYear(), date.getMonth(), date.getDate() + days);
+
+/** Same day number in another month, clamped to that month's length (Jan 31 + 1 → Feb 28/29). */
+export function addMonths(date: Date, months: number): Date {
+  const target = new Date(date.getFullYear(), date.getMonth() + months, 1);
+  const last = new Date(target.getFullYear(), target.getMonth() + 1, 0).getDate();
+  return new Date(target.getFullYear(), target.getMonth(), Math.min(date.getDate(), last));
+}
+
+export const startOfMonth = (date: Date) => new Date(date.getFullYear(), date.getMonth(), 1);
+
+export function startOfWeek(date: Date, firstDay = 0): Date {
+  const shift = (date.getDay() - firstDay + 7) % 7;
+  return addDays(startOfDay(date), -shift);
+}
+
+export const sameDay = (a: Date | null | undefined, b: Date | null | undefined) =>
+  !!a && !!b && a.getFullYear() === b.getFullYear() && a.getMonth() === b.getMonth() && a.getDate() === b.getDate();
+
+export const sameMonth = (a: Date, b: Date) => a.getFullYear() === b.getFullYear() && a.getMonth() === b.getMonth();
+
+const pad = (n: number) => String(n).padStart(2, '0');
+
+/** YYYY-MM-DD of the local day. */
+export const dayKey = (date: Date) => `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}`;
+
+/** The weeks shown for a month: from the week of the 1st to the week of the last day (4–6 rows). */
+export function monthWeeks(date: Date, firstDay = 0): Date[][] {
+  const first = startOfMonth(date);
+  const last = new Date(date.getFullYear(), date.getMonth() + 1, 0);
+  const weeks: Date[][] = [];
+  for (let start = startOfWeek(first, firstDay); start <= last; start = addDays(start, 7)) {
+    weeks.push(Array.from({ length: 7 }, (_, i) => addDays(start, i)));
+  }
+  return weeks;
+}
+
+export const weekDays = (date: Date, firstDay = 0) => Array.from({ length: 7 }, (_, i) => addDays(startOfWeek(date, firstDay), i));
+
+/** Weekday names in display order, e.g. ["dom", "lun", …] for es with firstDay 0. */
+export function weekdayNames(locale: string, firstDay = 0, width: 'long' | 'short' | 'narrow' = 'short'): string[] {
+  const format = safeFormat(locale, { weekday: width });
+  // 2024-09-01 was a Sunday.
+  return Array.from({ length: 7 }, (_, i) => format.format(new Date(2024, 8, 1 + ((firstDay + i) % 7))));
+}
+
+export function safeFormat(locale: string | undefined, options: Intl.DateTimeFormatOptions): Intl.DateTimeFormat {
+  try {
+    return new Intl.DateTimeFormat(locale, options);
+  } catch {
+    return new Intl.DateTimeFormat(undefined, options);
+  }
+}
+
+/** Numbers in the language of the page around `element`: "4,6" and "1204" on a Spanish page, "4.6" and "1,204" in English. */
+export function numberFormat(element: Element, options: Intl.NumberFormatOptions = {}): Intl.NumberFormat {
+  const locale = element.closest('[lang]')?.getAttribute('lang') || undefined;
+  try {
+    return new Intl.NumberFormat(locale, options);
+  } catch {
+    return new Intl.NumberFormat(undefined, options);
+  }
+}
+
+export const capitalize =(text: string) => text.charAt(0).toLocaleUpperCase() + text.slice(1);
+
+/** Options given as JSON text (data-mk-* attributes through autoInit) become values. */
+export function fromJson<T>(value: T | string | undefined): T | undefined {
+  if (typeof value !== 'string') return value;
+  try {
+    return JSON.parse(value) as T;
+  } catch {
+    return undefined;
+  }
+}
+
+export const clampFirstDay =(n: unknown) => (Number.isInteger(n) && (n as number) >= 0 && (n as number) <= 6 ? (n as number) : 0);

package/src/core/files.ts

@@ -0,0 +1,107 @@
+import { toTime, type TimeInput } from './relative-time';
+
+/*
+ * Files (file-explorer), the pure part: what is a folder, the family an
+ * extension belongs to (its colour), sizes in KB and MB, a free name in a
+ * folder ("Nueva carpeta (2)") and the order of a folder's content (folders
+ * first, then by name, size or date; numbers in names in their natural order).
+ */
+
+export interface FileEntry {
+  id: string;
+  name: string;
+  /** 'folder' or 'file'; without it, an entry with children is a folder. */
+  kind?: 'folder' | 'file';
+  children?: FileEntry[];
+  /** Bytes. */
+  size?: number;
+  modified?: TimeInput;
+}
+
+export type FileFamily = 'folder' | 'image' | 'pdf' | 'doc' | 'sheet' | 'slides' | 'code' | 'archive' | 'media' | 'other';
+export type FileSort = 'name' | 'size' | 'modified';
+
+export const isFolder = (entry: FileEntry) => (entry.kind ? entry.kind === 'folder' : Array.isArray(entry.children));
+
+/** "pdf" for "Informe.PDF"; '' without one (".gitignore" has none). */
+export function extensionOf(name: string): string {
+  const dot = name.lastIndexOf('.');
+  return dot > 0 && dot < name.length - 1 ? name.slice(dot + 1).toLowerCase() : '';
+}
+
+const FAMILIES: Record<Exclude<FileFamily, 'folder' | 'other'>, string[]> = {
+  image: ['png', 'jpg', 'jpeg', 'gif', 'webp', 'svg', 'avif', 'heic', 'bmp', 'ico', 'fig', 'psd', 'ai', 'sketch'],
+  pdf: ['pdf'],
+  doc: ['doc', 'docx', 'txt', 'md', 'rtf', 'odt', 'pages'],
+  sheet: ['xls', 'xlsx', 'csv', 'numbers', 'ods'],
+  slides: ['ppt', 'pptx', 'key', 'odp'],
+  code: ['js', 'mjs', 'cjs', 'ts', 'tsx', 'jsx', 'json', 'css', 'scss', 'html', 'astro', 'vue', 'svelte', 'py', 'rb', 'go', 'rs', 'java', 'c', 'cpp', 'h', 'php', 'sh', 'sql', 'xml', 'yml', 'yaml', 'toml'],
+  archive: ['zip', 'rar', '7z', 'tar', 'gz', 'tgz', 'bz2'],
+  media: ['mp3', 'wav', 'ogg', 'flac', 'm4a', 'mp4', 'mov', 'avi', 'mkv', 'webm'],
+};
+
+export function fileFamily(entry: FileEntry): FileFamily {
+  if (isFolder(entry)) return 'folder';
+  const extension = extensionOf(entry.name);
+  for (const [family, extensions] of Object.entries(FAMILIES)) if (extensions.includes(extension)) return family as FileFamily;
+  return 'other';
+}
+
+/** "820 B", "12 KB", "3,4 MB" (in the given language). */
+export function formatSize(bytes: number, locale = 'es'): string {
+  const units = ['B', 'KB', 'MB', 'GB', 'TB'];
+  let value = Math.max(0, bytes);
+  let unit = 0;
+  while (value >= 1024 && unit < units.length - 1) {
+    value /= 1024;
+    unit++;
+  }
+  let format: Intl.NumberFormat;
+  try {
+    format = new Intl.NumberFormat(locale, { maximumFractionDigits: unit && value < 10 ? 1 : 0 });
+  } catch {
+    format = new Intl.NumberFormat(undefined, { maximumFractionDigits: unit && value < 10 ? 1 : 0 });
+  }
+  return `${format.format(value)} ${units[unit]}`;
+}
+
+const same = (a: string, b: string) => a.localeCompare(b, undefined, { sensitivity: 'accent' }) === 0;
+
+/** Does a sibling (other than `except`) already have this name? Case does not count ("foto" is "Foto"); accents do. */
+export const nameTaken = (name: string, siblings: FileEntry[], except?: string) => siblings.some((sibling) => sibling.id !== except && same(sibling.name, name));
+
+/** `name`, or "name (2)", "name (3)"… (before the extension for files) when a sibling has it; `except` is the entry being renamed. */
+export function uniqueName(name: string, siblings: FileEntry[], except?: string): string {
+  if (!nameTaken(name, siblings, except)) return name;
+  const extension = extensionOf(name);
+  const base = extension ? name.slice(0, -extension.length - 1) : name;
+  for (let n = 2; ; n++) {
+    const candidate = extension ? `${base} (${n}).${extension}` : `${base} (${n})`;
+    if (!nameTaken(candidate, siblings, except)) return candidate;
+  }
+}
+
+/** Folders first; then by `key` (names in natural order: "Foto 2" before "Foto 10"). */
+export function sortEntries(entries: FileEntry[], key: FileSort = 'name', direction: 1 | -1 = 1, locale = 'es'): FileEntry[] {
+  let collator: Intl.Collator;
+  try {
+    collator = new Intl.Collator(locale, { numeric: true, sensitivity: 'base' });
+  } catch {
+    collator = new Intl.Collator(undefined, { numeric: true, sensitivity: 'base' });
+  }
+  const time = (entry: FileEntry) => toTime(entry.modified)?.getTime() ?? 0;
+  return [...entries].sort((a, b) => {
+    const folderA = isFolder(a);
+    if (folderA !== isFolder(b)) return folderA ? -1 : 1;
+    let diff = 0;
+    // Folders have no size of their own: by name, as file managers do.
+    if (key === 'size' && !folderA) diff = (a.size ?? 0) - (b.size ?? 0);
+    else if (key === 'modified') diff = time(a) - time(b);
+    if (!diff) diff = collator.compare(a.name, b.name);
+    return diff * direction;
+  });
+}
+
+/** A deep copy of entries (dates and other values are kept as they are). */
+export const cloneEntries = (entries: FileEntry[]): FileEntry[] =>
+  entries.map((entry) => (entry.children ? { ...entry, children: cloneEntries(entry.children) } : { ...entry }));