ng-hub-ui-avatar 21.0.0 → 22.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (10) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +258 -90
  3. package/fesm2022/ng-hub-ui-avatar.mjs +166 -81
  4. package/fesm2022/ng-hub-ui-avatar.mjs.map +1 -1
  5. package/ng-hub-ui-avatar-22.1.1.tgz +0 -0
  6. package/ng-hub-ui-avatar-22.2.0.tgz +0 -0
  7. package/package.json +5 -7
  8. package/src/lib/styles/mixins/_avatar-theme.scss +119 -0
  9. package/types/ng-hub-ui-avatar.d.ts +45 -4
  10. package/index.d.ts +0 -238
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Carlos Morcillo
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,93 +1,164 @@
1
- ## <ng-hub-ui-avatar>
1
+ # ng-hub-ui-avatar
2
2
 
3
- [![npm version](https://badge.fury.io/js/ng-hub-ui-avatar.svg)](https://badge.fury.io/js/ng-hub-ui-avatar.svg)
3
+ [Español](./README.es.md) | **English**
4
+
5
+ [![NPM Version](https://img.shields.io/npm/v/ng-hub-ui-avatar.svg)](https://www.npmjs.com/package/ng-hub-ui-avatar)
4
6
  [![npm](https://img.shields.io/npm/dt/ng-hub-ui-avatar.svg)](https://www.npmjs.com/package/ng-hub-ui-avatar)
5
- ![size](https://img.shields.io/bundlephobia/minzip/ng-hub-ui-avatar.svg)
7
+ [![license](https://img.shields.io/npm/l/ng-hub-ui-avatar.svg)](https://github.com/carlos-morcillo/ng-hub-ui-avatar/blob/main/LICENSE)
6
8
 
7
- > **⚠️ CRITICAL (MAJOR RELEASE):** Version 21.0.0 introduces architectural breaking changes by dropping several unsupported avatar sources and migrating outputs/inputs to Angular Signals. Please read the [BREAKING_CHANGES.md](./BREAKING_CHANGES.md) file before upgrading.
9
+ A universal avatar component for Angular applications that renders avatars from multiple sources (Gravatar, GitHub, Facebook, custom images, initials or plain text) and applies an automatic fallback strategy when a source fails.
8
10
 
9
- ## NPM Project
11
+ > **⚠️ BREAKING CHANGES:** Version 21.1.0 removes the need for public stylesheet imports. Styles are now encapsulated within the component. Please read the [BREAKING_CHANGES.md](./BREAKING_CHANGES.md) file before upgrading.
10
12
 
11
- [ng-hub-ui-avatar](https://www.npmjs.com/package/ng-hub-ui-avatar)
13
+ ## Documentation and Live Examples
12
14
 
13
- ## Inspiration
15
+ This package is part of [Hub UI](https://hubui.dev/), a collection of Angular component libraries for standalone apps.
14
16
 
15
- This project is a fork of [ngx-avatars](https://github.com/Heatmanofurioso/ngx-avatars), which itself continued the original avatar work. This package adapts and maintains the component for modern Angular applications.
17
+ - Docs: https://hubui.dev/avatar/overview/
18
+ - Live examples: https://hubui.dev/avatar/examples/
19
+ - Hub UI: https://hubui.dev/
16
20
 
17
- ## Part of ng-hub-ui Family
21
+ ## 🧩 Library Family `ng-hub-ui`
18
22
 
19
- This component is part of the ng-hub-ui ecosystem, which includes:
23
+ This library is part of the **Hub UI** ecosystem:
20
24
 
21
- - [ng-hub-ui-paginable](https://www.npmjs.com/package/ng-hub-ui-paginable)
22
- - [ng-hub-ui-modal](https://www.npmjs.com/package/ng-hub-ui-modal)
23
- - [ng-hub-ui-stepper](https://www.npmjs.com/package/ng-hub-ui-stepper)
25
+ - [ng-hub-ui-accordion](https://www.npmjs.com/package/ng-hub-ui-accordion) (deprecated — use ng-hub-ui-panels)
26
+ - [ng-hub-ui-action-sheet](https://www.npmjs.com/package/ng-hub-ui-action-sheet)
27
+ - [ng-hub-ui-avatar](https://www.npmjs.com/package/ng-hub-ui-avatar) ← You are here
28
+ - [ng-hub-ui-board](https://www.npmjs.com/package/ng-hub-ui-board)
24
29
  - [ng-hub-ui-breadcrumbs](https://www.npmjs.com/package/ng-hub-ui-breadcrumbs)
30
+ - [ng-hub-ui-calendar](https://www.npmjs.com/package/ng-hub-ui-calendar)
31
+ - [ng-hub-ui-dropdown](https://www.npmjs.com/package/ng-hub-ui-dropdown)
32
+ - [ng-hub-ui-ds](https://www.npmjs.com/package/ng-hub-ui-ds)
33
+ - [ng-hub-ui-forms](https://www.npmjs.com/package/ng-hub-ui-forms)
34
+ - [ng-hub-ui-history](https://www.npmjs.com/package/ng-hub-ui-history)
35
+ - [ng-hub-ui-milestones](https://www.npmjs.com/package/ng-hub-ui-milestones)
36
+ - [ng-hub-ui-modal](https://www.npmjs.com/package/ng-hub-ui-modal)
37
+ - [ng-hub-ui-nav](https://www.npmjs.com/package/ng-hub-ui-nav)
38
+ - [ng-hub-ui-paginable](https://www.npmjs.com/package/ng-hub-ui-paginable)
39
+ - [ng-hub-ui-panels](https://www.npmjs.com/package/ng-hub-ui-panels)
25
40
  - [ng-hub-ui-portal](https://www.npmjs.com/package/ng-hub-ui-portal)
41
+ - [ng-hub-ui-skeleton](https://www.npmjs.com/package/ng-hub-ui-skeleton)
42
+ - [ng-hub-ui-sortable](https://www.npmjs.com/package/ng-hub-ui-sortable)
43
+ - [ng-hub-ui-stepper](https://www.npmjs.com/package/ng-hub-ui-stepper)
44
+ - [ng-hub-ui-utils](https://www.npmjs.com/package/ng-hub-ui-utils)
45
+
46
+ ## 📑 Table of Contents
47
+
48
+ - [Documentation and Live Examples](#documentation-and-live-examples)
49
+ - [🧩 Library Family `ng-hub-ui`](#-library-family-ng-hub-ui)
50
+ - [Description](#description)
51
+ - [Features](#features)
52
+ - [Installation](#installation)
53
+ - [Quick Start](#quick-start)
54
+ - [Usage](#usage)
55
+ - [API Reference](#api-reference)
56
+ - [Styling](#styling)
57
+ - [Changelog](#changelog)
58
+ - [Contributing](#contributing)
59
+ - [Support](#support)
60
+ - [License](#license)
26
61
 
27
62
  ## Description
28
63
 
29
- `ng-hub-ui-avatar` is a universal avatar component for Angular applications.
30
- It can render avatars from multiple sources and apply an automatic fallback strategy when a source fails.
64
+ `ng-hub-ui-avatar` is a universal avatar component for Angular applications. It can render avatars from multiple sources and apply an automatic fallback strategy when a source fails.
31
65
 
32
66
  Supported avatar sources:
33
67
 
34
- - Facebook
35
68
  - Gravatar
36
69
  - GitHub
70
+ - Facebook
37
71
  - Custom image (`src`)
38
72
  - Initials (`name`)
39
73
  - Text value (`value`)
40
74
 
41
- Fallback uses source priority order. By default, the component tries supported sources in its configured order until one succeeds.
75
+ Fallback uses a source priority order. By default, the component tries the supported sources in their configured order until one succeeds.
42
76
 
43
- ## Installation
77
+ > This project is a fork of [ngx-avatars](https://github.com/Heatmanofurioso/ngx-avatars), which itself continued the original avatar work. This package adapts and maintains the component for modern Angular applications.
44
78
 
45
- Install avatar component using [Yarn](https://yarnpkg.com/):
79
+ ## Features
46
80
 
47
- ```bash
48
- yarn add ng-hub-ui-avatar
49
- ```
81
+ - **Multiple Sources**: Gravatar, GitHub, Facebook, custom images, initials and plain text.
82
+ - **Projected Custom Content**: Drop any icon (FontAwesome, Material…), inline SVG, image or emoji inside `<hub-avatar>` and it is sized, centered and padded agnostically.
83
+ - **Automatic Fallback**: Configurable source priority order with graceful fallback when a source fails.
84
+ - **Initials Generation**: Builds initials avatars from a name with auto-generated background colors.
85
+ - **Async Remote Sources**: Resolves remote avatars (for example Gravatar) over HTTP with caching support.
86
+ - **Flexible Shape**: Round or square avatars with configurable corner radius and border.
87
+ - **CSS Variables**: Full theming via canonical `--hub-avatar-*` custom properties.
88
+ - **Signals API**: Modern Angular inputs/outputs built on signals.
89
+ - **Module Configuration**: Customize colors, source priority order and cache behavior via `AvatarModule.forRoot()`.
50
90
 
51
- or
91
+ ## Installation
52
92
 
53
93
  ```bash
54
- npm install ng-hub-ui-avatar --save
94
+ npm install ng-hub-ui-avatar
55
95
  ```
56
96
 
57
- ## Usage
58
-
59
- ### 1. Import `AvatarModule`
97
+ ## Quick Start
60
98
 
61
99
  ```typescript
62
- import { BrowserModule } from '@angular/platform-browser';
63
100
  import { NgModule } from '@angular/core';
64
- import { HttpClientModule } from '@angular/common/http';
65
- import { AppComponent } from './app.component';
101
+ import { BrowserModule } from '@angular/platform-browser';
102
+ import { provideHttpClient } from '@angular/common/http';
66
103
  import { AvatarModule } from 'ng-hub-ui-avatar';
104
+ import { AppComponent } from './app.component';
67
105
 
68
106
  @NgModule({
69
107
  declarations: [AppComponent],
70
- imports: [BrowserModule, HttpClientModule, AvatarModule],
108
+ imports: [BrowserModule, AvatarModule],
109
+ providers: [provideHttpClient()],
71
110
  bootstrap: [AppComponent]
72
111
  })
73
112
  export class AppModule {}
74
113
  ```
75
114
 
76
- - `HttpClientModule` is required for async remote sources (for example Gravatar, Google, GitHub).
115
+ > `HttpClient` is required for async remote sources (for example Gravatar or GitHub). For standalone bootstrap apps, add `provideHttpClient()` to your application providers and import `AvatarModule` in the components that use `<hub-avatar>`.
77
116
 
78
- ### 2. Start using the component
117
+ Then use the component in any template:
79
118
 
80
119
  ```html
81
- <hub-avatar></hub-avatar>
120
+ <hub-avatar name="John Doe"></hub-avatar>
121
+ ```
122
+
123
+ ## Usage
124
+
125
+ `ng-hub-ui-avatar` is distributed as an Angular module. The `<hub-avatar>` component is declared and exported by `AvatarModule`.
126
+
127
+ ### Module-based apps
128
+
129
+ ```typescript
130
+ import { AvatarModule } from 'ng-hub-ui-avatar';
131
+
132
+ @NgModule({
133
+ imports: [AvatarModule]
134
+ })
135
+ export class FeatureModule {}
136
+ ```
137
+
138
+ ### Standalone components
139
+
140
+ Because the component is provided by a module, import `AvatarModule` directly in the `imports` array of your standalone component:
141
+
142
+ ```typescript
143
+ import { Component } from '@angular/core';
144
+ import { AvatarModule } from 'ng-hub-ui-avatar';
145
+
146
+ @Component({
147
+ selector: 'app-profile',
148
+ standalone: true,
149
+ imports: [AvatarModule],
150
+ template: `<hub-avatar name="John Doe" [round]="true" size="64"></hub-avatar>`
151
+ })
152
+ export class ProfileComponent {}
82
153
  ```
83
154
 
84
- ## Examples
155
+ ### Examples
85
156
 
86
157
  ```html
87
- <hub-avatar facebookId="nasa"></hub-avatar>
88
158
  <hub-avatar gravatarId="adde9b2b981a8083cf084c63ad86f753"></hub-avatar>
89
159
  <hub-avatar gravatarId="user@gmail.com"></hub-avatar>
90
160
  <hub-avatar githubId="angular"></hub-avatar>
161
+ <hub-avatar facebookId="nasa"></hub-avatar>
91
162
  <hub-avatar src="assets/avatar.jpg"></hub-avatar>
92
163
  <hub-avatar name="John Doe"></hub-avatar>
93
164
  <hub-avatar value="75%"></hub-avatar>
@@ -103,44 +174,29 @@ export class AppModule {}
103
174
  ></hub-avatar>
104
175
  ```
105
176
 
106
- ## Component API
177
+ ### Custom content (icons, SVG, images)
107
178
 
108
- ### Inputs
179
+ Project any content directly inside `<hub-avatar>` — an icon from any library, an inline `<svg>`, an `<img>` or even an emoji — and the avatar handles it agnostically: it centers the content, applies decent padding and clips it to the avatar shape (round or square). Font icons inherit a size and colour; inline SVG/images fill the avatar. Everything scales with `size`.
109
180
 
110
- | Input | Type | Default | Description |
111
- | ---------------- | ------------------------------- | ----------- | ---------------------------------------------- |
112
- | `facebookId` | `string \| null` | `undefined` | Facebook user id |
113
- | `gravatarId` | `string \| null` | `undefined` | Gravatar email/hash |
114
- | `githubId` | `string \| null` | `undefined` | GitHub user id |
115
- | `src` | `string \| SafeUrl \| null` | `undefined` | Custom image source |
116
- | `alt` | `string \| null` | `undefined` | Custom image alt text |
117
- | `name` | `string \| null` | `undefined` | Text source used to generate initials |
118
- | `value` | `string \| null` | `undefined` | Direct text avatar value |
119
- | `size` | `number \| string` | `50` | Avatar size in px |
120
- | `textSizeRatio` | `number` | `3` | Text size ratio (`size / textSizeRatio`) |
121
- | `initialsSize` | `number \| string` | `0` | Max initials length (`0` means no limit) |
122
- | `round` | `boolean` | `true` | Enables circular shape |
123
- | `cornerRadius` | `number \| string` | `0` | Radius in px when `round` is `false` |
124
- | `bgColor` | `string` | `undefined` | Background color override |
125
- | `fgColor` | `string` | `#FFF` | Foreground/text color |
126
- | `borderColor` | `string` | `undefined` | Border color (applies 1px solid border) |
127
- | `style` | `Record<string, any> \| string` | `{}` | Custom inline styles merged into avatar styles |
128
- | `placeholder` | `string` | `undefined` | Reserved placeholder input |
129
- | `referrerpolicy` | `string \| null` | `undefined` | Referrer policy for avatar image requests |
181
+ ```html
182
+ <!-- FontAwesome (or any icon font) -->
183
+ <hub-avatar><i class="fa-solid fa-user"></i></hub-avatar>
130
184
 
131
- ### Outputs
185
+ <!-- Material Symbols -->
186
+ <hub-avatar size="72"><span class="material-symbols-outlined">rocket_launch</span></hub-avatar>
132
187
 
133
- | Output | Type | Description |
134
- | --------------- | ---------------------- | ----------------------------------------------------------------------- |
135
- | `clickOnAvatar` | `EventEmitter<Source>` | Fired on avatar click with the source used to render the current avatar |
188
+ <!-- Inline SVG -->
189
+ <hub-avatar size="64">
190
+ <svg viewBox="0 0 24 24" fill="currentColor"><path d="M12 2 2 7l10 5 10-5-10-5Z" /></svg>
191
+ </hub-avatar>
136
192
 
137
- ### Source payload (`clickOnAvatar`)
193
+ <!-- Emoji -->
194
+ <hub-avatar>🚀</hub-avatar>
195
+ ```
138
196
 
139
- - `sourceType`: source type (`facebook`, `twitter`, etc.)
140
- - `sourceId`: identifier used by that source
141
- - `getAvatar(size)`: function that resolves avatar URL/value
197
+ It activates automatically whenever content is projected and takes precedence over the image/initials sources. The circle uses the avatar's own background (`--hub-avatar-bg-color`, the design-system accent by default) with a white foreground, so it reads as a coloured circle out of the box. Theme it with the regular `bgColor` / `fgColor` / `borderColor` inputs, and tune the sizing with the `--hub-avatar-content-*` tokens (see [Styling](#styling)).
142
198
 
143
- ## Module Configuration (`forRoot`)
199
+ ### Module configuration (`forRoot`)
144
200
 
145
201
  `AvatarModule.forRoot()` allows overriding module-level behavior.
146
202
 
@@ -164,32 +220,74 @@ export class AppModule {}
164
220
 
165
221
  `AvatarConfig` fields:
166
222
 
167
- - `colors?: string[]` -> custom color palette for generated text avatars.
168
- - `sourcePriorityOrder?: AvatarSource[]` -> custom fallback order.
169
- - `disableSrcCache?: boolean` -> disables cache for custom source requests.
223
+ | Field | Type | Description |
224
+ | --------------------- | ---------------- | -------------------------------------------------------- |
225
+ | `colors` | `string[]` | Custom color palette for generated text avatars. |
226
+ | `sourcePriorityOrder` | `AvatarSource[]` | Custom fallback order across avatar sources. |
227
+ | `disableSrcCache` | `boolean` | Disables the cache for custom (image) source requests. |
170
228
 
171
- Note: `facebookId` is kept as best-effort compatibility source and may fail depending on external API/privacy restrictions.
229
+ `AvatarSource` enum values: `FACEBOOK`, `GRAVATAR`, `GITHUB`, `CUSTOM`, `INITIALS`, `VALUE`.
230
+
231
+ > Note: `facebookId` is kept as a best-effort compatibility source and may fail depending on external API/privacy restrictions.
232
+
233
+ ## API Reference
234
+
235
+ ### Inputs
236
+
237
+ | Input | Type | Default | Description |
238
+ | ---------------- | ------------------------------- | ----------- | ---------------------------------------------- |
239
+ | `facebookId` | `string \| null` | `undefined` | Facebook user id |
240
+ | `gravatarId` | `string \| null` | `undefined` | Gravatar email/hash |
241
+ | `githubId` | `string \| null` | `undefined` | GitHub user id |
242
+ | `src` | `string \| SafeUrl \| null` | `undefined` | Custom image source |
243
+ | `alt` | `string \| null` | `undefined` | Custom image alt text |
244
+ | `name` | `string \| null` | `undefined` | Text source used to generate initials |
245
+ | `value` | `string \| null` | `undefined` | Direct text avatar value |
246
+ | `size` | `number \| string` | `50` | Avatar size in px |
247
+ | `textSizeRatio` | `number` | `3` | Text size ratio (`size / textSizeRatio`) |
248
+ | `initialsSize` | `number \| string` | `0` | Max initials length (`0` means no limit) |
249
+ | `round` | `boolean` | `true` | Enables circular shape |
250
+ | `cornerRadius` | `number \| string` | `0` | Radius in px when `round` is `false` |
251
+ | `bgColor` | `string` | `undefined` | Background color override |
252
+ | `fgColor` | `string` | `#FFF` | Foreground/text color |
253
+ | `borderColor` | `string` | `undefined` | Border color (applies a 1px solid border) |
254
+ | `style` | `Record<string, any> \| string` | `{}` | Custom inline styles merged into avatar styles |
255
+ | `placeholder` | `string` | `undefined` | Reserved placeholder input |
256
+ | `referrerpolicy` | `string \| null` | `undefined` | Referrer policy for avatar image requests |
257
+ | `status` | `HubAvatarStatus \| string \| null` | `null` | Presence indicator dot at the bottom-end corner. Built-ins: `online` (success), `away` (warning), `busy` (danger), `offline` (neutral). Any custom string is accepted — set `--hub-avatar-status-color` to colour it. When `null` (default) no dot is rendered. |
258
+
259
+ `HubAvatarStatus` is an exported type covering the built-in statuses: `'online' | 'away' | 'busy' | 'offline'`.
260
+
261
+ ### Outputs
262
+
263
+ | Output | Type | Description |
264
+ | --------------- | ---------------------- | ----------------------------------------------------------------------- |
265
+ | `clickOnAvatar` | `EventEmitter<Source>` | Fired on avatar click with the source used to render the current avatar |
266
+
267
+ The emitted `Source` payload exposes:
268
+
269
+ - `sourceType`: source type (`facebook`, `gravatar`, `github`, `custom`, `initials`, `value`).
270
+ - `sourceId`: identifier used by that source.
271
+ - `getAvatar(size)`: function that resolves the avatar URL/value.
172
272
 
173
273
  ## Styling
174
274
 
275
+ Styles are encapsulated within the component using canonical `--hub-avatar-*` tokens. Since version 21.1.0 you no longer need to import a global stylesheet.
276
+
175
277
  Full CSS variable catalog:
176
278
 
177
279
  - [`./docs/css-variables-reference.md`](./docs/css-variables-reference.md)
178
280
 
179
- Import the library stylesheet once in your global styles:
180
-
181
- ```scss
182
- @use 'ng-hub-ui-avatar/src/lib/styles/avatar.scss';
183
- ```
184
-
185
281
  Framework-agnostic customization example:
186
282
 
187
283
  ```scss
188
284
  hub-avatar {
189
- --hub-avatar-size: 56px;
190
- --hub-avatar-border-radius: 12px;
285
+ --hub-avatar-size: 64px;
286
+ --hub-avatar-border-radius: 16px;
191
287
  --hub-avatar-fg-color: #ffffff;
192
288
  --hub-avatar-bg-color: #0d6efd;
289
+ --hub-avatar-border-width: 2px;
290
+ --hub-avatar-border-color: #0a58ca;
193
291
  }
194
292
  ```
195
293
 
@@ -203,23 +301,92 @@ hub-avatar {
203
301
  }
204
302
  ```
205
303
 
206
- ## Build and Test
304
+ ### Custom content
207
305
 
208
- Build library package:
306
+ When you project content into `<hub-avatar>` (see [Custom content](#custom-content-icons-svg-images)), the **background is the avatar's own** (`--hub-avatar-bg-color`, the **accent colour by default**) and the icon uses the **avatar foreground** (`--hub-avatar-fg-color`, white) — so it reads as a coloured circle out of the box. Theme it with the regular `bgColor` / `fgColor` inputs (or `--hub-avatar-bg-color` / `--hub-avatar-fg-color`) just like any other avatar. Two extra tokens control the projected content's **sizing**, both relative to `--hub-avatar-size`:
209
307
 
210
- ```bash
211
- npm run build avatar -- --configuration production
308
+ | Token | Default | Description |
309
+ | -------------------------------- | ------------------------------------- | ------------------------------------------------------------------- |
310
+ | `--hub-avatar-content-padding` | `calc(var(--hub-avatar-size) * 0.2)` | Breathing room between the projected content and the avatar edge. |
311
+ | `--hub-avatar-content-icon-size` | `calc(var(--hub-avatar-size) * 0.55)` | Font size for icon fonts / emoji (inherited by the projected glyph). |
312
+
313
+ ```scss
314
+ hub-avatar {
315
+ --hub-avatar-bg-color: #e7f1ff; // the avatar's own background — also the content circle
316
+ --hub-avatar-fg-color: #0d6efd; // icon colour (or set the `fgColor` input)
317
+ --hub-avatar-content-icon-size: calc(var(--hub-avatar-size) * 0.6);
318
+ }
212
319
  ```
213
320
 
214
- Run avatar tests:
321
+ ### Presence status
215
322
 
216
- ```bash
217
- npm test -- avatar
323
+ Set the `status` input to render a small dot at the bottom-end corner. The dot scales with the avatar (the component exposes the live size on the host as `--hub-avatar-size`).
324
+
325
+ ```html
326
+ <hub-avatar name="John Doe" status="online"></hub-avatar>
327
+ <hub-avatar name="Jane Doe" status="busy"></hub-avatar>
328
+ <hub-avatar name="Custom" status="dnd"></hub-avatar>
329
+ ```
330
+
331
+ Built-ins map to the design-system colours: `online` → success, `away` → warning, `busy` → danger, `offline` → neutral. Any custom string is accepted; colour it with `--hub-avatar-status-color`:
332
+
333
+ ```scss
334
+ hub-avatar[data-status='dnd'] {
335
+ --hub-avatar-status-color: #9333ea;
336
+ }
337
+ ```
338
+
339
+ Status tokens:
340
+
341
+ | Variable | Default | Usage |
342
+ | ------------------------------- | ------------------------------------------------------------- | -------------------------------------- |
343
+ | `--hub-avatar-status-size` | `calc(var(--hub-avatar-size, 50px) * 0.28)` | Diameter of the status dot |
344
+ | `--hub-avatar-status-offset` | `0px` | Inset of the dot from the corner |
345
+ | `--hub-avatar-status-ring-width`| `max(2px, calc(var(--hub-avatar-size, 50px) * 0.05))` | Width of the ring around the dot |
346
+ | `--hub-avatar-status-ring-color`| `var(--hub-sys-surface-page, #fff)` | Colour of the ring around the dot |
347
+ | `--hub-avatar-status-color` | `var(--hub-sys-text-muted, #6c757d)` | Dot colour (re-based per built-in status) |
348
+
349
+ ### Avatar group
350
+
351
+ Wrap several `<hub-avatar>` in a `.hub-avatar-group` to overlap them into a stacked group; each avatar gets a ring so the edges read cleanly.
352
+
353
+ ```html
354
+ <div class="hub-avatar-group">
355
+ <hub-avatar name="John Doe"></hub-avatar>
356
+ <hub-avatar name="Jane Doe"></hub-avatar>
357
+ <hub-avatar name="Sam Smith"></hub-avatar>
358
+ </div>
359
+ ```
360
+
361
+ Group tokens:
362
+
363
+ | Variable | Default | Usage |
364
+ | ------------------------------ | -------------------------------------------------------- | ---------------------------------- |
365
+ | `--hub-avatar-group-overlap` | `calc(var(--hub-avatar-size, 50px) * 0.3)` | Horizontal overlap between avatars |
366
+ | `--hub-avatar-group-ring-width`| `max(2px, calc(var(--hub-avatar-size, 50px) * 0.04))` | Ring width around each avatar |
367
+ | `--hub-avatar-group-ring-color`| `var(--hub-sys-surface-page, #fff)` | Ring colour around each avatar |
368
+
369
+ ### Sass theming mixin
370
+
371
+ The `hub-avatar-theme()` mixin themes an avatar in a single include — shape/surface, initials typography, the status dot and the group ring. Every parameter is optional and defaults to `null`, so only the ones you pass are emitted as `--hub-avatar-*` overrides. It is token-based, with no Bootstrap dependency.
372
+
373
+ ```scss
374
+ @use 'ng-hub-ui-avatar/styles/mixins/avatar-theme' as *;
375
+
376
+ hub-avatar.brand {
377
+ @include hub-avatar-theme(
378
+ $size: 64px,
379
+ $border-radius: 1rem,
380
+ $bg: #ede9fe,
381
+ $fg: #5b21b6,
382
+ $status-ring-color: #ede9fe
383
+ );
384
+ }
218
385
  ```
219
386
 
220
- ## Release Notes & History
387
+ ## Changelog
221
388
 
222
- - `1.0.0`: Initial fork and package publication.
389
+ See [CHANGELOG.md](./CHANGELOG.md) for the full version history.
223
390
 
224
391
  ## Contributing
225
392
 
@@ -230,13 +397,14 @@ Contributions and collaboration are welcome.
230
397
  - Commit and push your changes.
231
398
  - Open a pull request.
232
399
 
233
- ## Support the Project
400
+ ## Support
234
401
 
235
402
  If you find this project helpful and would like to support its development, you can buy me a coffee:
236
403
 
237
404
  [!["Buy Me A Coffee"](https://www.buymeacoffee.com/assets/img/custom_images/orange_img.png)](https://buymeacoffee.com/carlosmorcillo)
238
405
 
239
- Your support helps maintain and improve this project.
406
+ - **Issues**: [GitHub Issues](https://github.com/carlos-morcillo/ng-hub-ui-avatar/issues)
407
+ - **Author**: [Carlos Morcillo](https://www.carlosmorcillo.com)
240
408
 
241
409
  ## License
242
410