fn-ui-avatars 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Fábio Nascimento
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,141 @@
+[![npm version](https://img.shields.io/npm/v/fn-ui-avatars.svg)](https://www.npmjs.com/package/fn-ui-avatars)
+[![npm bundle size](https://img.shields.io/bundlephobia/minzip/fn-ui-avatars)](https://bundlephobia.com/result?p=fn-ui-avatars)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Auto-generate consistent, colorful initials avatars using the [UI-Avatars](https://ui-avatars.com/) API.
+
+Colors are **deterministic** — the same name always produces the same background color, across sessions and devices. It also features **Smart Contrast**, automatically switching the text color between black and white to ensure maximum legibility based on the generated background.
+
+---
+
+## Installation
+
+```bash
+npm install fn-ui-avatars
+```
+
+---
+
+## Usage
+
+### In the browser (vanilla JS)
+
+Add `data-name` to any `<img>` element and call `loadAvatars()` after the DOM is ready:
+
+```html
+<img class="fn-ui-avatars" data-name="Maria Silva" alt="Avatar">
+<img class="fn-ui-avatars" data-name="João Ferreira" alt="Avatar">
+
+<script type="module">
+  import { loadAvatars } from 'fn-ui-avatars';
+
+  document.addEventListener('DOMContentLoaded', () => {
+    loadAvatars(); // targets 'img.fn-ui-avatars' by default
+  });
+</script>
+```
+
+### Generate a single URL
+
+```js
+import { getAvatarUrl } from 'fn-ui-avatars';
+
+const url = getAvatarUrl('Maria Silva');
+// → https://eu.ui-avatars.com/api/?size=192&...&name=Maria+Silva&...
+
+document.querySelector('#my-avatar').src = url;
+```
+
+### With React (or any component framework)
+
+```jsx
+import { getAvatarUrl } from 'fn-ui-avatars';
+
+function Avatar({ name }) {
+  return <img src={getAvatarUrl(name)} alt={name} />;
+}
+```
+
+### CommonJS (Node / older bundlers)
+
+```js
+const { getAvatarUrl, loadAvatars } = require('fn-ui-avatars');
+```
+
+---
+
+## API
+
+### `getAvatarUrl(name, options?)`
+
+Returns a UI-Avatars URL string for the given name.
+
+| Parameter | Type | Description |
+|---|---|---|
+| `name` | `string` | Full name (e.g. `"Maria Silva"`). Required. |
+| `options` | `object` | Optional configuration (see below). |
+
+**Options:**
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `size` | `number` | `192` | Image size in pixels. |
+| `fontSize` | `number` | `0.33` | Font size ratio (`0.1`–`1`). |
+| `length` | `number` | `2` | Number of initials to display. |
+| `rounded` | `boolean` | `true` | Circular avatar. |
+| `color` | `string` | `'fff'` | Text color (hex without `#`). |
+| `format` | `string` | `'svg'` | Image format: `'svg'` or `'png'`. |
+| `baseUrl` | `string` | `'https://eu.ui-avatars.com/api/'` | Custom API base URL. |
+
+---
+
+### `loadAvatars(selector?, options?)`
+
+Scans the DOM and injects `src` attributes into matching elements that have `data-name` set and no existing `src`.
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `selector` | `string` | `'img.fn-ui-avatars'` | CSS selector for target elements. |
+| `options` | `object` | `{}` | Same options as `getAvatarUrl`. |
+
+Returns the number of avatars injected.
+
+> ⚠️ This function requires a browser environment (`document` must be defined).
+
+---
+
+### `hashCode(str)` / `intToRGB(i)`
+
+Low-level utility functions, exported for advanced use cases (e.g. generating matching border colors, custom backgrounds).
+
+```js
+import { hashCode, intToRGB } from 'fn-ui-avatars';
+
+const hex = intToRGB(hashCode('Maria Silva')); // → e.g. "4A7BCC"
+```
+
+---
+
+## How colors work
+
+Each name is hashed with a simple djb2-style algorithm, and the resulting integer is masked to produce a 6-digit hex color. This ensures:
+
+- The same name **always** gets the same color.
+- Different names get visually distinct colors.
+- No configuration or storage required.
+
+---
+
+## Running tests
+
+```bash
+npm test
+```
+
+No external test runner needed — tests use only Node's built-in assert.
+
+---
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,99 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  getAvatarUrl: () => getAvatarUrl,
+  hashCode: () => hashCode,
+  intToRGB: () => intToRGB,
+  loadAvatars: () => loadAvatars
+});
+module.exports = __toCommonJS(index_exports);
+var DEFAULT_OPTIONS = {
+  size: 192,
+  fontSize: 0.33,
+  length: 2,
+  rounded: true,
+  color: "fff",
+  format: "svg",
+  baseUrl: "https://eu.ui-avatars.com/api/"
+};
+function hashCode(str) {
+  let hash = 0;
+  for (let i = 0; i < str.length; i++) {
+    hash = str.charCodeAt(i) + ((hash << 5) - hash);
+  }
+  return hash;
+}
+function intToRGB(i) {
+  const c = (i & 16777215).toString(16).toUpperCase();
+  return "000000".substring(0, 6 - c.length) + c;
+}
+function isLightColor(hex) {
+  const r = parseInt(hex.substring(0, 2), 16);
+  const g = parseInt(hex.substring(2, 4), 16);
+  const b = parseInt(hex.substring(4, 6), 16);
+  const yiq = (r * 299 + g * 587 + b * 114) / 1e3;
+  return yiq >= 128;
+}
+function getAvatarUrl(name, options = {}) {
+  if (!name || typeof name !== "string") {
+    throw new Error('fn-ui-avatars: "name" must be a non-empty string.');
+  }
+  const opts = { ...DEFAULT_OPTIONS, ...options };
+  const encoded = name.trim().replace(/\s+/g, "+");
+  const background = intToRGB(hashCode(encoded));
+  const textColor = options.color ? opts.color : isLightColor(background) ? "000" : "fff";
+  const query = [
+    `size=${opts.size}`,
+    `font-size=${opts.fontSize}`,
+    `length=${opts.length}`,
+    `background=${background}`,
+    `color=${textColor}`,
+    `rounded=${opts.rounded}`,
+    `name=${encoded}`,
+    `format=${opts.format}`
+  ].join("&");
+  return `${opts.baseUrl}?${query}`;
+}
+function loadAvatars(selector = "img.fn-ui-avatar", options = {}) {
+  if (typeof document === "undefined") {
+    throw new Error("fn-ui-avatars: loadAvatars() requires a browser environment.");
+  }
+  const elements = document.querySelectorAll(selector);
+  let count = 0;
+  elements.forEach((el) => {
+    if (!el.getAttribute("src")) {
+      const name = el.dataset.name;
+      if (name) {
+        el.src = getAvatarUrl(name, options);
+        count++;
+      }
+    }
+  });
+  return count;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  getAvatarUrl,
+  hashCode,
+  intToRGB,
+  loadAvatars
+});

package/dist/index.d.cts

@@ -0,0 +1,33 @@
+/**
+ * fn-ui-avatars
+ * Automatically generate consistent, colorful avatars using UI-Avatars API.
+ * Colors are deterministic — the same name always produces the same color.
+ */
+interface AvatarOptions {
+    size?: number;
+    fontSize?: number;
+    length?: number;
+    rounded?: boolean;
+    color?: string;
+    format?: 'svg' | 'png';
+    baseUrl?: string;
+}
+/**
+ * Generates a numeric hash from a string.
+ */
+declare function hashCode(str: string): number;
+/**
+ * Converts an integer to a 6-character hex color string (without #).
+ */
+declare function intToRGB(i: number): string;
+/**
+ * Generates a UI-Avatars URL for a given name.
+ */
+declare function getAvatarUrl(name: string, options?: AvatarOptions): string;
+/**
+ * Scans the DOM for matching elements and injects avatar src attributes
+ * where no src is already set.
+ */
+declare function loadAvatars(selector?: string, options?: AvatarOptions): number;
+
+export { type AvatarOptions, getAvatarUrl, hashCode, intToRGB, loadAvatars };

package/dist/index.d.ts

@@ -0,0 +1,33 @@
+/**
+ * fn-ui-avatars
+ * Automatically generate consistent, colorful avatars using UI-Avatars API.
+ * Colors are deterministic — the same name always produces the same color.
+ */
+interface AvatarOptions {
+    size?: number;
+    fontSize?: number;
+    length?: number;
+    rounded?: boolean;
+    color?: string;
+    format?: 'svg' | 'png';
+    baseUrl?: string;
+}
+/**
+ * Generates a numeric hash from a string.
+ */
+declare function hashCode(str: string): number;
+/**
+ * Converts an integer to a 6-character hex color string (without #).
+ */
+declare function intToRGB(i: number): string;
+/**
+ * Generates a UI-Avatars URL for a given name.
+ */
+declare function getAvatarUrl(name: string, options?: AvatarOptions): string;
+/**
+ * Scans the DOM for matching elements and injects avatar src attributes
+ * where no src is already set.
+ */
+declare function loadAvatars(selector?: string, options?: AvatarOptions): number;
+
+export { type AvatarOptions, getAvatarUrl, hashCode, intToRGB, loadAvatars };

package/dist/index.js

@@ -0,0 +1,71 @@
+// src/index.ts
+var DEFAULT_OPTIONS = {
+  size: 192,
+  fontSize: 0.33,
+  length: 2,
+  rounded: true,
+  color: "fff",
+  format: "svg",
+  baseUrl: "https://eu.ui-avatars.com/api/"
+};
+function hashCode(str) {
+  let hash = 0;
+  for (let i = 0; i < str.length; i++) {
+    hash = str.charCodeAt(i) + ((hash << 5) - hash);
+  }
+  return hash;
+}
+function intToRGB(i) {
+  const c = (i & 16777215).toString(16).toUpperCase();
+  return "000000".substring(0, 6 - c.length) + c;
+}
+function isLightColor(hex) {
+  const r = parseInt(hex.substring(0, 2), 16);
+  const g = parseInt(hex.substring(2, 4), 16);
+  const b = parseInt(hex.substring(4, 6), 16);
+  const yiq = (r * 299 + g * 587 + b * 114) / 1e3;
+  return yiq >= 128;
+}
+function getAvatarUrl(name, options = {}) {
+  if (!name || typeof name !== "string") {
+    throw new Error('fn-ui-avatars: "name" must be a non-empty string.');
+  }
+  const opts = { ...DEFAULT_OPTIONS, ...options };
+  const encoded = name.trim().replace(/\s+/g, "+");
+  const background = intToRGB(hashCode(encoded));
+  const textColor = options.color ? opts.color : isLightColor(background) ? "000" : "fff";
+  const query = [
+    `size=${opts.size}`,
+    `font-size=${opts.fontSize}`,
+    `length=${opts.length}`,
+    `background=${background}`,
+    `color=${textColor}`,
+    `rounded=${opts.rounded}`,
+    `name=${encoded}`,
+    `format=${opts.format}`
+  ].join("&");
+  return `${opts.baseUrl}?${query}`;
+}
+function loadAvatars(selector = "img.fn-ui-avatar", options = {}) {
+  if (typeof document === "undefined") {
+    throw new Error("fn-ui-avatars: loadAvatars() requires a browser environment.");
+  }
+  const elements = document.querySelectorAll(selector);
+  let count = 0;
+  elements.forEach((el) => {
+    if (!el.getAttribute("src")) {
+      const name = el.dataset.name;
+      if (name) {
+        el.src = getAvatarUrl(name, options);
+        count++;
+      }
+    }
+  });
+  return count;
+}
+export {
+  getAvatarUrl,
+  hashCode,
+  intToRGB,
+  loadAvatars
+};

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "fn-ui-avatars",
+  "version": "1.0.0",
+  "description": "Automatically generate consistent, colorful avatars using UI-Avatars API",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts",
+    "pretest": "npm run build",
+    "test": "node test/index.test.js",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "keywords": [
+    "avatar",
+    "initials",
+    "ui-avatars",
+    "gravatar",
+    "placeholder",
+    "user-avatar"
+  ],
+  "author": "Fábio Nascimento <f_nascimento9@hotmail.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fnasciment0/fn-ui-avatars.git"
+  },
+  "bugs": {
+    "url": "https://github.com/fnasciment0/fn-ui-avatars/issues"
+  },
+  "homepage": "https://github.com/fnasciment0/fn-ui-avatars#readme",
+  "engines": {
+    "node": ">=14"
+  },
+  "devDependencies": {
+    "tsup": "^8.5.1",
+    "typescript": "^6.0.3"
+  }
+}