@oscarpalmer/atoms 0.82.1 → 0.84.0

package/dist/color/hex.js

@@ -1,7 +1,7 @@
 var __defProp = Object.defineProperty;
 var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
 var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
-import { anyPattern, getNormalisedHex, hexToRgb } from "./functions.js";
+import { getNormalisedHex, anyPattern, hexToRgb } from "./functions.js";
 class HexColor {
   constructor(value) {
     __publicField(this, "state");

package/dist/i18n.cjs

@@ -0,0 +1,120 @@
+"use strict";
+var _a, _b, _c;
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const defaults = {
+  delimiter: "",
+  languages: {
+    fallback: null,
+    preferred: null
+  }
+};
+function getKey(value, languages) {
+  if ((languages == null ? void 0 : languages.fallback) == null && (languages == null ? void 0 : languages.preferred) == null) {
+    return;
+  }
+  const { fallback, preferred } = languages;
+  switch (true) {
+    case (preferred != null && preferred.full in value):
+      return preferred.full;
+    case (preferred != null && preferred.region != null && preferred.base in value):
+      return preferred.base;
+    case (fallback != null && fallback.full in value):
+      return fallback.full;
+    case (fallback != null && fallback.region != null && fallback.base in value):
+      return fallback.base;
+  }
+}
+function getLanguage(value) {
+  if (typeof value !== "string") {
+    return;
+  }
+  const [full, base, region] = /^([a-z]{2,3})(?:-([A-Z]{2}))?$/.exec(value) ?? [];
+  if (full != null) {
+    return { base, full, region };
+  }
+}
+function getTranslation(value, key, delimiter, languages) {
+  if (key != null) {
+    return translateValue(value[key], delimiter, languages);
+  }
+  const asString = value.toString();
+  return asString === "[object Object]" ? "" : asString;
+}
+function setLanguage(key, value) {
+  const language = getLanguage(value);
+  if (language != null) {
+    defaults.languages[key] = language;
+  }
+}
+function translate(value, options) {
+  let delimiter = defaults.delimiter;
+  let languages = defaults.languages;
+  if (options != null) {
+    delimiter = typeof options.delimiter === "string" ? options.delimiter : defaults.delimiter;
+    languages = {
+      fallback: getLanguage(options.fallback),
+      preferred: getLanguage(options.language)
+    };
+  }
+  return translateUnknown(value, delimiter, languages);
+}
+translate.configure = (configuration) => {
+  if (typeof configuration.delimiter === "string") {
+    defaults.delimiter = configuration.delimiter;
+  }
+  if (typeof configuration.fallback === "string") {
+    setLanguage("fallback", configuration.fallback);
+  }
+  if (typeof configuration.language === "string") {
+    setLanguage("preferred", configuration.language);
+  }
+};
+translate.configuration = () => {
+  return {
+    delimiter: String(defaults.delimiter),
+    fallback: String(defaults.languages.fallback.full),
+    language: String(defaults.languages.preferred.full)
+  };
+};
+function translatePrimitive(value) {
+  return value == null ? "" : typeof value === "string" ? value : String(value);
+}
+function translateTranslatable(value, delimiter, languages) {
+  if (Array.isArray(value)) {
+    return value.map((item) => translateValue(item, delimiter, languages)).filter((translated) => translated.trim().length > 0).join(delimiter);
+  }
+  return getTranslation(
+    value,
+    getKey(value, languages) ?? getKey(value, defaults.languages),
+    delimiter,
+    languages
+  );
+}
+function translateUnknown(value, delimiter, languages) {
+  return typeof value !== "object" || value == null ? translateValue(value, delimiter, languages) : translateTranslatable(
+    value,
+    delimiter,
+    languages
+  );
+}
+function translateValue(value, delimiter, languages) {
+  let actual = value;
+  if (typeof value === "function") {
+    actual = value();
+    if (typeof actual === "function") {
+      return "";
+    }
+  }
+  if (Array.isArray(actual)) {
+    return translateTranslatable(actual, delimiter, languages);
+  }
+  if (typeof actual === "object" && actual != null) {
+    const asString = actual.toString();
+    return asString === "[object Object]" ? translateTranslatable(actual, delimiter, languages) : asString;
+  }
+  return translatePrimitive(actual);
+}
+const defaultLanguage = (((_c = (_b = (_a = document == null ? void 0 : document.documentElement) == null ? void 0 : _a.lang) == null ? void 0 : _b.trim()) == null ? void 0 : _c.length) ?? 0) > 0 ? document.documentElement.lang : (navigator == null ? void 0 : navigator.language) ?? "en";
+setLanguage("fallback", defaultLanguage);
+setLanguage("preferred", defaultLanguage);
+exports.translate = translate;

package/dist/i18n.js

@@ -0,0 +1,120 @@
+var _a, _b, _c;
+const defaults = {
+  delimiter: "",
+  languages: {
+    fallback: null,
+    preferred: null
+  }
+};
+function getKey(value, languages) {
+  if ((languages == null ? void 0 : languages.fallback) == null && (languages == null ? void 0 : languages.preferred) == null) {
+    return;
+  }
+  const { fallback, preferred } = languages;
+  switch (true) {
+    case (preferred != null && preferred.full in value):
+      return preferred.full;
+    case (preferred != null && preferred.region != null && preferred.base in value):
+      return preferred.base;
+    case (fallback != null && fallback.full in value):
+      return fallback.full;
+    case (fallback != null && fallback.region != null && fallback.base in value):
+      return fallback.base;
+  }
+}
+function getLanguage(value) {
+  if (typeof value !== "string") {
+    return;
+  }
+  const [full, base, region] = /^([a-z]{2,3})(?:-([A-Z]{2}))?$/.exec(value) ?? [];
+  if (full != null) {
+    return { base, full, region };
+  }
+}
+function getTranslation(value, key, delimiter, languages) {
+  if (key != null) {
+    return translateValue(value[key], delimiter, languages);
+  }
+  const asString = value.toString();
+  return asString === "[object Object]" ? "" : asString;
+}
+function setLanguage(key, value) {
+  const language = getLanguage(value);
+  if (language != null) {
+    defaults.languages[key] = language;
+  }
+}
+function translate(value, options) {
+  let delimiter = defaults.delimiter;
+  let languages = defaults.languages;
+  if (options != null) {
+    delimiter = typeof options.delimiter === "string" ? options.delimiter : defaults.delimiter;
+    languages = {
+      fallback: getLanguage(options.fallback),
+      preferred: getLanguage(options.language)
+    };
+  }
+  return translateUnknown(value, delimiter, languages);
+}
+translate.configure = (configuration) => {
+  if (typeof configuration.delimiter === "string") {
+    defaults.delimiter = configuration.delimiter;
+  }
+  if (typeof configuration.fallback === "string") {
+    setLanguage("fallback", configuration.fallback);
+  }
+  if (typeof configuration.language === "string") {
+    setLanguage("preferred", configuration.language);
+  }
+};
+translate.configuration = () => {
+  return {
+    delimiter: String(defaults.delimiter),
+    fallback: String(defaults.languages.fallback.full),
+    language: String(defaults.languages.preferred.full)
+  };
+};
+function translatePrimitive(value) {
+  return value == null ? "" : typeof value === "string" ? value : String(value);
+}
+function translateTranslatable(value, delimiter, languages) {
+  if (Array.isArray(value)) {
+    return value.map((item) => translateValue(item, delimiter, languages)).filter((translated) => translated.trim().length > 0).join(delimiter);
+  }
+  return getTranslation(
+    value,
+    getKey(value, languages) ?? getKey(value, defaults.languages),
+    delimiter,
+    languages
+  );
+}
+function translateUnknown(value, delimiter, languages) {
+  return typeof value !== "object" || value == null ? translateValue(value, delimiter, languages) : translateTranslatable(
+    value,
+    delimiter,
+    languages
+  );
+}
+function translateValue(value, delimiter, languages) {
+  let actual = value;
+  if (typeof value === "function") {
+    actual = value();
+    if (typeof actual === "function") {
+      return "";
+    }
+  }
+  if (Array.isArray(actual)) {
+    return translateTranslatable(actual, delimiter, languages);
+  }
+  if (typeof actual === "object" && actual != null) {
+    const asString = actual.toString();
+    return asString === "[object Object]" ? translateTranslatable(actual, delimiter, languages) : asString;
+  }
+  return translatePrimitive(actual);
+}
+const defaultLanguage = (((_c = (_b = (_a = document == null ? void 0 : document.documentElement) == null ? void 0 : _a.lang) == null ? void 0 : _b.trim()) == null ? void 0 : _c.length) ?? 0) > 0 ? document.documentElement.lang : (navigator == null ? void 0 : navigator.language) ?? "en";
+setLanguage("fallback", defaultLanguage);
+setLanguage("preferred", defaultLanguage);
+export {
+  translate
+};

package/dist/index.cjs

@@ -4,6 +4,7 @@ const array_index = require("./array/index.cjs");
 const color_index = require("./color/index.cjs");
 const emitter = require("./emitter.cjs");
 const _function = require("./function.cjs");
+const i18n = require("./i18n.cjs");
 const is = require("./is.cjs");
 const logger = require("./logger.cjs");
 const math = require("./math.cjs");
@@ -54,6 +55,7 @@ exports.debounce = _function.debounce;
 exports.memoise = _function.memoise;
 exports.noop = _function.noop;
 exports.throttle = _function.throttle;
+exports.translate = i18n.translate;
 exports.isArrayOrPlainObject = is.isArrayOrPlainObject;
 exports.isEmpty = is.isEmpty;
 exports.isKey = is.isKey;

package/dist/index.js

@@ -2,6 +2,7 @@ import { flatten, push } from "./array/index.js";
 import { getForegroundColor } from "./color/index.js";
 import { emitter } from "./emitter.js";
 import { debounce, memoise, noop, throttle } from "./function.js";
+import { translate } from "./i18n.js";
 import { isArrayOrPlainObject, isEmpty, isKey, isNullable, isNullableOrEmpty, isNullableOrWhitespace, isNumber, isNumerical, isObject, isPlainObject, isPrimitive } from "./is.js";
 import { logger } from "./logger.js";
 import { average, max, min, round, sum } from "./math.js";
@@ -134,6 +135,7 @@ export {
   toMap,
   toQuery,
   toRecord,
+  translate,
   truncate,
   unique,
   unsmush,

package/package.json

@@ -9,13 +9,13 @@
 	"description": "Atomic utilities for making your JavaScript better.",
 	"devDependencies": {
 		"@biomejs/biome": "^1.9",
-		"@types/node": "^22.12",
+		"@types/node": "^22.13",
 		"@vitest/coverage-istanbul": "^3",
 		"dts-bundle-generator": "^9.5",
 		"glob": "^11",
-		"happy-dom": "^16.7",
+		"happy-dom": "^17",
 		"typescript": "^5.7",
-		"vite": "^6",
+		"vite": "^6.1",
 		"vitest": "^3"
 	},
 	"exports": {
@@ -70,6 +70,16 @@
 				"default": "./dist/function.cjs"
 			}
 		},
+		"./i18n": {
+			"import": {
+				"types": "./types/i18n.d.ts",
+				"default": "./dist/i18n.js"
+			},
+			"require": {
+				"types": "./types/i18n.d.cts",
+				"default": "./dist/i18n.cjs"
+			}
+		},
 		"./is": {
 			"import": {
 				"types": "./types/is.d.ts",
@@ -179,15 +189,8 @@
 			}
 		}
 	},
-	"files": [
-		"dist",
-		"src",
-		"types"
-	],
-	"keywords": [
-		"helper",
-		"utility"
-	],
+	"files": ["dist", "src", "types"],
+	"keywords": ["helper", "utility"],
 	"license": "MIT",
 	"main": "./dist/index.cjs",
 	"module": "./dist/index.js",
@@ -205,5 +208,5 @@
 	},
 	"type": "module",
 	"types": "./types/index.d.cts",
-	"version": "0.82.1"
+	"version": "0.84.0"
 }

package/src/i18n.ts

@@ -0,0 +1,300 @@
+import {isPlainObject} from './is';
+import type {PlainObject, Primitive} from './models';
+
+type Defaults = {
+	/**
+	 * Delimiter to use when translating an array of translatable values
+	 */
+	delimiter: string;
+	/**
+	 * Languages to use when translating
+	 */
+	languages: Languages;
+};
+
+type Language = {
+	/**
+	 * Language code _(e.g. `en`, `es`, `fr`, `ja`, `zh`)_
+	 */
+	readonly base: string;
+	/**
+	 * Language code with region _(e.g. `en-US`, `es-ES`, `fr-FR`, `ja-JP`, `zh-CN`)_
+	 */
+	readonly full: string;
+	/**
+	 * Region code _(e.g. `US`, `ES`, `FR`, `JP`, `CN`)_
+	 */
+	readonly region?: string;
+};
+
+type Languages = {
+	/**
+	 * Language to use when no translation is found
+	 */
+	fallback: Language;
+	/**
+	 * Language to use when translating
+	 */
+	preferred: Language;
+};
+
+type TranslateConfiguration = TranslateOptions;
+
+export type TranslateOptions = {
+	/**
+	 * Delimiter to use when translating an array of translatable values
+	 */
+	delimiter: string;
+	/**
+	 * Language to use when no translation is found
+	 */
+	fallback: string;
+	/**
+	 * Language to use when translating
+	 */
+	language: string;
+};
+
+/**
+ * A translatable object
+ */
+export type Translatable = Record<string, unknown>;
+
+const defaults: Defaults = {
+	delimiter: '',
+	languages: {
+		fallback: null as never,
+		preferred: null as never,
+	},
+};
+
+/**
+ * Get translation key for a translatable object
+ */
+function getKey(
+	value: PlainObject,
+	languages: Partial<Languages>,
+): string | undefined {
+	if (languages?.fallback == null && languages?.preferred == null) {
+		return;
+	}
+
+	const {fallback, preferred} = languages;
+
+	switch (true) {
+		case preferred != null && preferred.full in value:
+			return preferred.full;
+
+		case preferred != null &&
+			preferred.region != null &&
+			preferred.base in value:
+			return preferred.base;
+
+		case fallback != null && fallback.full in value:
+			return fallback.full;
+
+		case fallback != null && fallback.region != null && fallback.base in value:
+			return fallback.base;
+	}
+}
+
+/**
+ * Get a _Language_ from a value
+ */
+function getLanguage(value: unknown): Language | undefined {
+	if (typeof value !== 'string') {
+		return;
+	}
+
+	const [full, base, region] =
+		/^([a-z]{2,3})(?:-([A-Z]{2}))?$/.exec(value) ?? [];
+
+	if (full != null) {
+		return {base, full, region};
+	}
+}
+
+/**
+ * Get translation for a key from a translatable object
+ */
+function getTranslation(
+	value: PlainObject,
+	key: string | undefined,
+	delimiter: string,
+	languages: Partial<Languages>,
+): string {
+	if (key != null) {
+		return translateValue((value as PlainObject)[key], delimiter, languages);
+	}
+
+	const asString = value.toString();
+
+	return asString === '[object Object]' ? '' : asString;
+}
+
+/**
+ * Set a _Language_ for a key
+ */
+function setLanguage(key: keyof Languages, value: string): void {
+	const language = getLanguage(value);
+
+	if (language != null) {
+		defaults.languages[key] = language;
+	}
+}
+
+/**
+ * Translates a value _(with optional options, but defaulting to configuration)_
+ */
+export function translate(
+	value: unknown,
+	options?: Partial<TranslateOptions>,
+): string;
+
+/**
+ * Translates an array of values _(with optional options, but defaulting to configuration)_
+ */
+export function translate(
+	value: unknown[],
+	options?: Partial<TranslateOptions>,
+): string;
+
+export function translate(
+	value: unknown | unknown[],
+	options?: Partial<TranslateOptions>,
+): string {
+	let delimiter = defaults.delimiter;
+	let languages: Partial<Languages> = defaults.languages;
+
+	if (options != null) {
+		delimiter =
+			typeof options.delimiter === 'string'
+				? options.delimiter
+				: defaults.delimiter;
+
+		languages = {
+			fallback: getLanguage(options.fallback),
+			preferred: getLanguage(options.language),
+		};
+	}
+
+	return translateUnknown(value, delimiter, languages);
+}
+
+/**
+ * Configures the translation options _(used as defaults when translating)_
+ */
+translate.configure = (
+	configuration: Partial<TranslateConfiguration>,
+): void => {
+	if (typeof configuration.delimiter === 'string') {
+		defaults.delimiter = configuration.delimiter;
+	}
+
+	if (typeof configuration.fallback === 'string') {
+		setLanguage('fallback', configuration.fallback);
+	}
+
+	if (typeof configuration.language === 'string') {
+		setLanguage('preferred', configuration.language);
+	}
+};
+
+/**
+ * Gets the current translation configuration
+ */
+translate.configuration = (): TranslateConfiguration => {
+	return {
+		delimiter: String(defaults.delimiter),
+		fallback: String(defaults.languages.fallback.full),
+		language: String(defaults.languages.preferred.full),
+	};
+};
+
+/**
+ * Translates a primitive value into a string
+ */
+function translatePrimitive(value: Primitive): string {
+	return value == null ? '' : typeof value === 'string' ? value : String(value);
+}
+
+/**
+ * Translates a translatable object _(or array of translatable objects)_ into a string
+ */
+function translateTranslatable(
+	value: PlainObject | PlainObject[],
+	delimiter: string,
+	languages: Partial<Languages>,
+): string {
+	if (Array.isArray(value)) {
+		return value
+			.map(item => translateValue(item, delimiter, languages))
+			.filter(translated => translated.trim().length > 0)
+			.join(delimiter);
+	}
+
+	return getTranslation(
+		value,
+		getKey(value, languages) ?? getKey(value, defaults.languages),
+		delimiter,
+		languages,
+	);
+}
+
+/**
+ * Translates a value _(into a string)_
+ */
+function translateUnknown(
+	value: unknown,
+	delimiter: string,
+	languages: Partial<Languages>,
+): string {
+	return typeof value !== 'object' || value == null
+		? translateValue(value, delimiter, languages)
+		: translateTranslatable(
+				value as PlainObject | PlainObject[],
+				delimiter,
+				languages,
+			);
+}
+
+/**
+ * Translates a value _(into a string)_
+ */
+function translateValue(
+	value: unknown,
+	delimiter: string,
+	languages: Partial<Languages>,
+): string {
+	let actual = value;
+
+	if (typeof value === 'function') {
+		actual = value();
+
+		if (typeof actual === 'function') {
+			return '';
+		}
+	}
+
+	if (Array.isArray(actual)) {
+		return translateTranslatable(actual, delimiter, languages);
+	}
+
+	if (typeof actual === 'object' && actual != null) {
+		const asString = actual.toString();
+
+		return asString === '[object Object]'
+			? translateTranslatable(actual as PlainObject, delimiter, languages)
+			: asString;
+	}
+
+	return translatePrimitive(actual as Primitive);
+}
+
+const defaultLanguage =
+	(document?.documentElement?.lang?.trim()?.length ?? 0) > 0
+		? document.documentElement.lang
+		: (navigator?.language ?? 'en');
+
+setLanguage('fallback', defaultLanguage);
+setLanguage('preferred', defaultLanguage);

package/src/index.ts

@@ -2,6 +2,7 @@ export * from './array/index';
 export * from './color/index';
 export * from './emitter';
 export * from './function';
+export * from './i18n';
 export * from './is';
 export * from './logger';
 export * from './math';

package/types/i18n.d.cts

@@ -0,0 +1,35 @@
+// Generated by dts-bundle-generator v9.5.1
+
+export type TranslateConfiguration = TranslateOptions;
+export type TranslateOptions = {
+	/**
+	 * Delimiter to use when translating an array of translatable values
+	 */
+	delimiter: string;
+	/**
+	 * Language to use when no translation is found
+	 */
+	fallback: string;
+	/**
+	 * Language to use when translating
+	 */
+	language: string;
+};
+/**
+ * A translatable object
+ */
+export type Translatable = Record<string, unknown>;
+/**
+ * Translates a value _(with optional options, but defaulting to configuration)_
+ */
+export declare function translate(value: unknown, options?: Partial<TranslateOptions>): string;
+/**
+ * Translates an array of values _(with optional options, but defaulting to configuration)_
+ */
+export declare function translate(value: unknown[], options?: Partial<TranslateOptions>): string;
+export declare namespace translate {
+	var configure: (configuration: Partial<TranslateConfiguration>) => void;
+	var configuration: () => TranslateConfiguration;
+}
+
+export {};