@norconsult-digital-public/isypixel 2.0.2-canary.4 → 2.0.2-canary.6

package/dist/docs/web-components/ip-avatar/llm.md

@@ -0,0 +1,171 @@
+# ip-avatar
+
+A theme-aware user avatar. It shows a profile image with a fallback chain (primary image → fallback image → initials → silhouette), an optional one- or two-line label (name + caption), a configurable ring, a forced or automatic loading state, and four positional corner slots. It is domain-agnostic: status, signing, and responsibility semantics are not baked in — consumers place and style their own markers via the corner slots.
+
+**Storybook:** https://pixel.isy.no/storybook/?path=/docs/core-ui-ip-avatar-usage--docs
+
+> This component requires ISY Pixel global styles to render correctly. Always remind the user to verify that styles are imported in their global stylesheet. See `llm.md` in the package root for style import options.
+
+## Attributes
+
+| Attribute               | Type    | Default      | Values                                                                                | Description                                                                                                |
+| ----------------------- | ------- | ------------ | ------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
+| `name`                  | string  | `""`         | Any string                                                                            | Full name. Used as the image `alt`, the source for initials/abbreviation, and the tooltip text.            |
+| `alt-name`              | string  | `undefined`  | Any string                                                                            | Explicit short/alternative name shown when `mode="alt-name"`. When unset, the name is abbreviated.         |
+| `caption`               | string  | `undefined`  | Any string                                                                            | Secondary line shown beneath the name, e.g. a role or title.                                               |
+| `placeholder`           | string  | `undefined`  | Any string                                                                            | Text shown beside the avatar when there is no name, e.g. an unselected-resource hint.                      |
+| `src`                   | string  | `undefined`  | Any image URL                                                                         | Primary profile image URL, tried first in the fallback chain.                                              |
+| `fallback-src`          | string  | `undefined`  | Any image URL                                                                         | Fallback image URL, used when `src` is missing or fails to load.                                           |
+| `mode`                  | string  | `"fullname"` | `"fullname"`, `"alt-name"`, `"firstname"`, `"lastname"`, `"initials"`, `"image-only"` | Which name representation is shown as visible text beside the avatar.                                      |
+| `fallback`              | string  | `"auto"`     | `"auto"`, `"initials"`, `"silhouette"`                                                | Circle content when there is no image. `auto` shows initials when a name is set, silhouette when nameless. |
+| `label-position`        | string  | `"right"`    | `"top"`, `"right"`, `"bottom"`, `"left"`                                              | Placement of the text label relative to the circle.                                                        |
+| `gap`                   | string  | `undefined`  | Any CSS length                                                                        | Overrides the gap between the avatar and the label. Defaults scale with `size`.                            |
+| `size`                  | string  | `"medium"`   | `"small"`, `"medium"`, `"large"`, `"custom"`                                          | Avatar size: `small` 40px, `medium` 50px (42px image), `large` 64px. Use `custom` with `custom-size`.      |
+| `custom-size`           | string  | `undefined`  | Any CSS length                                                                        | Diameter when `size="custom"`, applied to both width and height so the avatar stays circular.              |
+| `image-loading`         | string  | `"lazy"`     | `"lazy"`, `"eager"`                                                                   | Native image loading strategy forwarded to the inner `<img>`.                                              |
+| `loading`               | boolean | `false`      | `true`, `false`                                                                       | Forces the loading indicator regardless of image state, e.g. before `src` is known.                        |
+| `ring-variant`          | string  | `"default"`  | `"default"`, `"brand"`, `"success"`, `"warning"`, `"error"`, `"custom"`               | Predefined, theme-aware ring colour. Use `custom` together with `ring-color` for a raw colour.             |
+| `ring-color`            | string  | `undefined`  | Any CSS colour                                                                        | Raw ring colour, applied only when `ring-variant="custom"`. Does not adapt to light/dark.                  |
+| `ring-style`            | string  | `"solid"`    | `"solid"`, `"dashed"`, `"dotted"`                                                     | Line style of the ring.                                                                                    |
+| `ring-gap`              | string  | `undefined`  | Any CSS length                                                                        | Gap between the ring and the content. Defaults to a small constant (2px).                                  |
+| `striped`               | boolean | `false`      | `true`, `false`                                                                       | Overlays subtle diagonal stripes on the no-image background (initials / silhouette).                       |
+| `clickable`             | boolean | `false`      | `true`, `false`                                                                       | Makes the avatar interactive: focusable, keyboard-activatable, and emits `ipClick`.                        |
+| `selected`              | boolean | `false`      | `true`, `false`                                                                       | Applies the selected (active) container styling, e.g. for the chosen item in a list.                       |
+| `disabled`              | boolean | `false`      | `true`, `false`                                                                       | Greys out the avatar and, when `clickable`, prevents activation.                                           |
+| `full-width`            | boolean | `false`      | `true`, `false`                                                                       | Stretches the avatar to fill the row, so stacked avatars span the full width.                              |
+| `maintain-label-height` | boolean | `false`      | `true`, `false`                                                                       | Keeps both label lines at a constant height even when empty, so avatars in a row stay aligned.             |
+| `disable-tooltip`       | boolean | `false`      | `true`, `false`                                                                       | Disables the built-in tooltip entirely.                                                                    |
+| `tooltip-position`      | string  | `"top"`      | `"top"`, `"right"`, `"bottom"`, `"left"`                                              | Placement of the tooltip, forwarded to `ip-tooltip`.                                                       |
+| `tooltip-size`          | string  | `"medium"`   | `"small"`, `"medium"`, `"large"`                                                      | Size of the tooltip, forwarded to `ip-tooltip`.                                                            |
+| `tooltip-variant`       | string  | `"default"`  | `"default"`, `"onLight"`, `"onDark"`                                                  | Colour variant of the tooltip, forwarded to `ip-tooltip`.                                                  |
+
+**Fallback chain** — `src` is tried first. When it fails to load, `fallback-src` is tried next. When both are missing or fail, the avatar shows the user's initials (when a name is set) or a silhouette glyph. `fallback` can force `initials` or `silhouette`. Each image failure emits `ipImageError` with the failed URL.
+
+**Tooltip content** — The tooltip surfaces the full `name` whenever the visible text differs from it (e.g. `firstname`, `lastname`, `initials`, or an abbreviated `alt-name`). When the visible text already equals the full name — in `mode="fullname"`, or in `mode="alt-name"` for a name short enough that abbreviation leaves it unchanged — the tooltip is auto-disabled unless custom `tooltip` slot content is provided.
+
+## Slots
+
+| Slot           | Description                                                                                   |
+| -------------- | --------------------------------------------------------------------------------------------- |
+| `top-left`     | Adornment anchored to the top-left corner of the circle. The consumer supplies and styles it. |
+| `top-right`    | Adornment anchored to the top-right corner.                                                   |
+| `bottom-left`  | Adornment anchored to the bottom-left corner.                                                 |
+| `bottom-right` | Adornment anchored to the bottom-right corner, e.g. a status badge.                           |
+| `tooltip`      | Optional override of the tooltip content. Defaults to the derived name when not provided.     |
+
+## Events
+
+| Event          | Payload               | When                                                                                 |
+| -------------- | --------------------- | ------------------------------------------------------------------------------------ |
+| `ipImageError` | `string` (failed src) | An image fails to load and the component advances down the fallback chain.           |
+| `ipClick`      | `void`                | A `clickable` avatar is activated by mouse or keyboard. Not emitted when `disabled`. |
+
+## Accessibility
+
+- The image uses `name` as its `alt`. When the initials fallback is shown, `name` is exposed to assistive technology via visually hidden text and the initials/silhouette are marked `aria-hidden`.
+- While an image loads or `loading` is set, the media sets `aria-busy="true"` and renders visually hidden loading text. Initials/silhouette are the final state, never a stuck spinner.
+- When `clickable`, the avatar exposes `role="button"`, is focusable (`tabindex="0"`), shows a `:focus-visible` ring, and is activated with Enter or Space.
+- When `disabled`, a clickable avatar sets `aria-disabled="true"`, drops out of the tab order, and blocks `ipClick`.
+- A `clickable` avatar with no visible label derives its accessible name from `name` (falling back to `placeholder`). When using `mode="image-only"` (or no name/placeholder) on a clickable avatar, supply an accessible name yourself via the `tooltip` slot or a wrapping label, or the button is announced unnamed.
+
+## Design tokens
+
+> The avatar reuses generic semantic tokens as theme-aware stand-ins; a dedicated avatar token family (background, foreground, ring, container hover/selected) does not exist yet. Avatar sizes are literal pixel values for the same reason. These are marked `//TODO` in the SCSS and will be replaced once design adds the avatar tokens.
+
+| SCSS variable                                                | Role                                                                     |
+| ------------------------------------------------------------ | ------------------------------------------------------------------------ |
+| `$ip_color_surface_primary_default`                          | Ring layer background behind the ring gap                                |
+| `$ip_color_text_primary_blue`                                | Foreground colour: initials, silhouette, loader, and default ring        |
+| `$ip_color_border_opaque_15`                                 | No-image background behind initials / silhouette                         |
+| `$ip_color_border_opaque_10`                                 | Clickable container hover background and the stripe overlay              |
+| `$ip_color_border_opaque_20`                                 | Selected container background                                            |
+| `$ip_color_button_focus_default`                             | Focus ring when `clickable`                                              |
+| `$ip_color_brand_accent_primary_default`                     | Ring colour for `ring-variant="brand"`                                   |
+| `$ip_color_extended_green-500`                               | Ring colour for `ring-variant="success"`                                 |
+| `$ip_color_extended_yellow-500`                              | Ring colour for `ring-variant="warning"`                                 |
+| `$ip_color_extended_red-500`                                 | Ring colour for `ring-variant="error"`                                   |
+| `$ip_color_text_primary_black`                               | Default label (name) text colour; override with `--ip-avatar-text-color` |
+| `$ip_radius_size_small`                                      | Framed container and focus-ring radius                                   |
+| `$ip_spacing_space_050` / `$ip_spacing_space_200`            | Framed container padding                                                 |
+| `$ip_spacing_space_100` / `_200` / `_300`                    | Avatar↔label gap defaults for small / medium / large                     |
+| `$ip_typography_body_font_size_small` / `_medium` / `_large` | Initials and label font size per size                                    |
+| `$ip_typography_body_line_height_compact`                    | Line height for the name and caption lines                               |
+| `$ip_typography_font_family_primary`                         | Font family for initials and label                                       |
+| `$ip_typography_font_weight_bold_700`                        | Initials font weight                                                     |
+| `$ip_typography_font_weight_light_300`                       | Caption and placeholder font weight (italic)                             |
+
+## CSS custom properties
+
+| Property                 | Default                        | Role                                                                                                                                                  |
+| ------------------------ | ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--ip-avatar-text-color` | `$ip_color_text_primary_black` | Label (name and caption) text colour. Set to `currentColor` so the label inherits its surroundings — e.g. on a dark surface such as inside a tooltip. |
+
+## Usage
+
+### HTML
+
+> Attribute names must be **kebab-case** in HTML: use `fallback-src`, not `fallbackSrc`.
+
+```js
+import '@norconsult-digital-public/isypixel/web-components/ip-avatar.js';
+```
+
+```html
+<ip-avatar name="Alexander Wangsvik" caption="Elkraft, ingeniør" src="/users/alexander.jpg" fallback-src="/users/default.png">
+  <span slot="bottom-right" class="badge">✓</span>
+</ip-avatar>
+```
+
+### React
+
+```tsx
+import { IpAvatar } from '@norconsult-digital-public/isypixel/web-components/react';
+
+<IpAvatar name='Alexander Wangsvik' caption='Elkraft, ingeniør' src='/users/alexander.jpg' fallbackSrc='/users/default.png' onIpClick={() => {}} />;
+```
+
+### Vue
+
+```vue
+<script setup lang="ts">
+import { IpAvatar } from '@norconsult-digital-public/isypixel/web-components/vue';
+</script>
+
+<template>
+  <IpAvatar name="Alexander Wangsvik" caption="Elkraft, ingeniør" src="/users/alexander.jpg" fallback-src="/users/default.png" />
+</template>
+```
+
+### Angular
+
+```ts
+import { IpAvatar } from '@norconsult-digital-public/isypixel/web-components/angular';
+```
+
+```html
+<ip-avatar name="Alexander Wangsvik" caption="Elkraft, ingeniør" [src]="imageUrl" ring-variant="brand" (ipClick)="onSelect()"></ip-avatar>
+```
+
+### Svelte
+
+```svelte
+<script lang="ts">
+  import '@norconsult-digital-public/isypixel/web-components/ip-avatar.js';
+</script>
+
+<ip-avatar name="Alexander Wangsvik" caption="Elkraft, ingeniør" src="/users/alexander.jpg" fallback-src="/users/default.png"></ip-avatar>
+```
+
+### Blazor
+
+> Attribute names must be **kebab-case** in Blazor HTML.
+
+Copy `ip-avatar.js` to `wwwroot/lib/isypixel/components/` at build time. See `llm.md` in the package root for the MSBuild target.
+
+```html
+<script type="module" src="lib/isypixel/components/ip-avatar.js"></script>
+
+<ip-avatar name="Alexander Wangsvik" caption="Elkraft, ingeniør" src="/users/alexander.jpg" fallback-src="/users/default.png"></ip-avatar>
+```
+
+- Boolean attributes such as `clickable`, `disabled`, `striped`, and `disable-tooltip` must be set as `clickable="true"` (string value) — Blazor does not reliably render bare boolean attributes on custom elements.

package/dist/docs/web-components/ip-avatar-stack/llm.md

@@ -0,0 +1,169 @@
+# ip-avatar-stack
+
+A stacked-avatar component that overlaps multiple `ip-avatar` instances and shows a combined names label (the first person's name plus a `+N` count for the rest). Consumers place `ip-avatar` elements in the default slot; the stack manages the overlap, the overflow collapse into a `+N` counter, and the label. It reuses each avatar's own ring to keep the overlapping circles visually distinct.
+
+**Storybook:** https://pixel.isy.no/storybook/?path=/docs/core-ui-ip-avatar-stack-usage--docs
+
+> This component requires ISY Pixel global styles to render correctly. Always remind the user to verify that styles are imported in their global stylesheet. See `llm.md` in the package root for style import options.
+
+> Place `ip-avatar` elements in the default slot. The stack forces each slotted avatar to `image-only`, so you do not need to set `mode` yourself. In `label-mode="name"` the stack reads the first avatar's `name` for the text label, so set `name` on at least the first avatar. Match each avatar's `size` to the stack's `size` so the circles align.
+
+## Attributes
+
+| Attribute         | Type    | Default     | Values                                       | Description                                                                                                                                                                                           |
+| ----------------- | ------- | ----------- | -------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `max`             | number  | `3`         | Any integer ≥ 1                              | Maximum number of avatars rendered (the hard cap). Surplus avatars are hidden; in `label-mode="counter"` they collapse into a `+N` counter circle (N = total − visible).                              |
+| `auto-fit`        | boolean | `true`      | `true`, `false`                              | Reduces the visible avatars to fit the container width, collapsing the rest like `max` does (`max` stays the cap). Set `false` for a fixed stack that always shows up to `max`.                       |
+| `size`            | string  | `"medium"`  | `"small"`, `"medium"`, `"large"`, `"custom"` | Stack size: drives the overflow counter size (small 40px, medium 50px, large 64px) and the default overlap.                                                                                           |
+| `custom-size`     | string  | `undefined` | Any CSS length                               | Diameter of the overflow counter when `size="custom"`, applied to both width and height.                                                                                                              |
+| `overlap`         | string  | `undefined` | Any CSS length                               | Overrides the overlap offset between circles. Defaults scale with `size` (small 20px, medium 24px, large 30px).                                                                                       |
+| `label-mode`      | string  | `"name"`    | `"name"`, `"counter"`, `"none"`              | How the group is summarised. `name`: first name + `+N` rest text label. `counter`: a `+N` counter circle in the stack. `none`: nothing. The counter circle and the text label are mutually exclusive. |
+| `gap`             | string  | `undefined` | Any CSS length                               | Overrides the gap between the stack and the label. Defaults scale with `size`.                                                                                                                        |
+| `preview-avatars` | boolean | `true`      | `true`, `false`                              | Whether the tooltip previews (the counter preview and the names-label tooltip) show a small avatar beside each person. Set `false` for a compact, name-only list.                                     |
+| `clickable`       | boolean | `false`     | `true`, `false`                              | Makes the `+N` overflow counter (in `label-mode="counter"`) focusable, keyboard-activatable, and emits `ipOverflowClick`.                                                                             |
+| `disabled`        | boolean | `false`     | `true`, `false`                              | Greys out the stack and, when `clickable`, prevents activation of the overflow counter.                                                                                                               |
+
+**Counter mode** — In `label-mode="counter"`, when more avatars are slotted than are shown, the visible avatars are shown (up to `max`, or fewer with `auto-fit`) and the remainder collapse into a single `+N` counter circle appended to the stack, where N = total − visible. No text label is shown. The collapsed avatars are hidden from the layout and the accessibility tree. Hovering or focusing the counter opens a tooltip previewing the collapsed people. The preview reads `name`, `src`, and `caption` from the collapsed `ip-avatar` elements; by default each row shows a small `ip-avatar` with its name and caption, or just the name and caption when `preview-avatars="false"`.
+
+**Auto-fit** — On by default. The stack measures its container width and shows as many avatars as fit, collapsing the rest into the `+N` counter (counter mode) or reflecting them in the `+N` text (name mode). `max` remains the upper cap, so the visible count is never more than `max` and adapts down as the container narrows. It needs a width-constrained ancestor to measure against; place the stack in its own container for best results. Set `auto-fit="false"` for a fixed stack that always shows up to `max`.
+
+**Names label** — In `label-mode="name"` the text label reads the first slotted avatar's `name` and appends `+N`, where N is the number of remaining avatars (total − 1), e.g. `Markus Halvorsen +2` for three avatars. This mode shows no counter circle. When more than one avatar is slotted, hovering the label opens a tooltip listing every slotted person (not just the overflow), using the same preview rows as counter mode and honouring `preview-avatars`.
+
+## Slots
+
+| Slot       | Description                                                                        |
+| ---------- | ---------------------------------------------------------------------------------- |
+| `default`  | The `ip-avatar` elements to stack. Non-`ip-avatar` nodes are ignored.              |
+| `label`    | Overrides the auto-generated text label. Shown in `label-mode="name"`.             |
+| `overflow` | Overrides the content of the `+N` counter circle. Shown in `label-mode="counter"`. |
+
+## Events
+
+| Event             | Payload | When                                                                                           |
+| ----------------- | ------- | ---------------------------------------------------------------------------------------------- |
+| `ipOverflowClick` | `void`  | A `clickable` overflow counter is activated by mouse or keyboard. Not emitted when `disabled`. |
+
+## Accessibility
+
+- The overlap and paint order are presentational only; each slotted `ip-avatar` keeps its own accessible name and tooltip.
+- Avatars collapsed into the `+N` counter are hidden from the accessibility tree; their names are surfaced through the counter's tooltip preview instead.
+- When `clickable`, the overflow counter exposes `role="button"`, is focusable (`tabindex="0"`), shows a `:focus-visible` ring, is activated with Enter or Space, and carries an `aria-label` describing how many more there are.
+- When `disabled`, a clickable counter sets `aria-disabled="true"` and blocks `ipOverflowClick`.
+
+## Design tokens
+
+> The stack reuses generic semantic tokens as theme-aware stand-ins; a dedicated avatar token family (background, foreground, ring, sizes, overlap) does not exist yet. Counter sizes and overlap offsets are literal pixel values for the same reason. These are marked `//TODO` in the SCSS and will be replaced once design adds the avatar tokens.
+
+| SCSS variable                                                | Role                                                       |
+| ------------------------------------------------------------ | ---------------------------------------------------------- |
+| `$ip_color_surface_primary_default`                          | Overflow counter ring layer background behind the ring gap |
+| `$ip_color_text_primary_blue`                                | Overflow counter ring colour and `+N` text colour          |
+| `$ip_color_border_opaque_15`                                 | Overflow counter inner background behind the `+N` text     |
+| `$ip_color_button_focus_default`                             | Focus ring of the overflow counter when `clickable`        |
+| `$ip_color_text_tertiary_default`                            | Names label text colour                                    |
+| `$ip_spacing_space_100` / `_200` / `_300`                    | Stack↔label gap defaults for small / medium / large        |
+| `$ip_typography_body_font_size_small` / `_medium` / `_large` | Counter and label font size per size                       |
+| `$ip_typography_body_line_height_compact`                    | Label line height                                          |
+| `$ip_typography_font_family_primary`                         | Font family for the counter and label                      |
+| `$ip_typography_font_weight_bold_700`                        | `+N` counter font weight                                   |
+
+## Usage
+
+### HTML
+
+> Attribute names must be **kebab-case** in HTML: use `label-mode`, not `labelMode`.
+
+```js
+import '@norconsult-digital-public/isypixel/web-components/ip-avatar-stack.js';
+import '@norconsult-digital-public/isypixel/web-components/ip-avatar.js';
+```
+
+```html
+<ip-avatar-stack max="3" size="medium" label-mode="name">
+  <ip-avatar name="Markus Halvorsen" src="/users/markus.jpg"></ip-avatar>
+  <ip-avatar name="Mia Berg" src="/users/mia.jpg"></ip-avatar>
+  <ip-avatar name="Jonas Lie" src="/users/jonas.jpg"></ip-avatar>
+  <ip-avatar name="Sara Nilsen"></ip-avatar>
+</ip-avatar-stack>
+```
+
+### React
+
+```tsx
+import { IpAvatarStack, IpAvatar } from '@norconsult-digital-public/isypixel/web-components/react';
+
+<IpAvatarStack max={3} size='medium' labelMode='name' clickable onIpOverflowClick={() => {}}>
+  <IpAvatar name='Markus Halvorsen' src='/users/markus.jpg' />
+  <IpAvatar name='Mia Berg' src='/users/mia.jpg' />
+  <IpAvatar name='Jonas Lie' src='/users/jonas.jpg' />
+  <IpAvatar name='Sara Nilsen' />
+</IpAvatarStack>;
+```
+
+### Vue
+
+```vue
+<script setup lang="ts">
+import { IpAvatarStack, IpAvatar } from '@norconsult-digital-public/isypixel/web-components/vue';
+</script>
+
+<template>
+  <IpAvatarStack :max="3" size="medium" label-mode="name">
+    <IpAvatar name="Markus Halvorsen" src="/users/markus.jpg" />
+    <IpAvatar name="Mia Berg" src="/users/mia.jpg" />
+    <IpAvatar name="Jonas Lie" src="/users/jonas.jpg" />
+    <IpAvatar name="Sara Nilsen" />
+  </IpAvatarStack>
+</template>
+```
+
+### Angular
+
+```ts
+import { IpAvatarStack, IpAvatar } from '@norconsult-digital-public/isypixel/web-components/angular';
+```
+
+```html
+<ip-avatar-stack [max]="3" size="medium" label-mode="name" clickable (ipOverflowClick)="onShowAll()">
+  <ip-avatar name="Markus Halvorsen" [src]="markusUrl"></ip-avatar>
+  <ip-avatar name="Mia Berg" [src]="miaUrl"></ip-avatar>
+  <ip-avatar name="Jonas Lie" [src]="jonasUrl"></ip-avatar>
+  <ip-avatar name="Sara Nilsen"></ip-avatar>
+</ip-avatar-stack>
+```
+
+### Svelte
+
+```svelte
+<script lang="ts">
+  import '@norconsult-digital-public/isypixel/web-components/ip-avatar-stack.js';
+  import '@norconsult-digital-public/isypixel/web-components/ip-avatar.js';
+</script>
+
+<ip-avatar-stack max="3" size="medium" label-mode="name">
+  <ip-avatar name="Markus Halvorsen" src="/users/markus.jpg"></ip-avatar>
+  <ip-avatar name="Mia Berg" src="/users/mia.jpg"></ip-avatar>
+  <ip-avatar name="Jonas Lie" src="/users/jonas.jpg"></ip-avatar>
+  <ip-avatar name="Sara Nilsen"></ip-avatar>
+</ip-avatar-stack>
+```
+
+### Blazor
+
+> Attribute names must be **kebab-case** in Blazor HTML.
+
+Copy `ip-avatar-stack.js` and `ip-avatar.js` to `wwwroot/lib/isypixel/components/` at build time. See `llm.md` in the package root for the MSBuild target.
+
+```html
+<script type="module" src="lib/isypixel/components/ip-avatar-stack.js"></script>
+<script type="module" src="lib/isypixel/components/ip-avatar.js"></script>
+
+<ip-avatar-stack max="3" size="medium" label-mode="name">
+  <ip-avatar name="Markus Halvorsen" src="/users/markus.jpg"></ip-avatar>
+  <ip-avatar name="Mia Berg" src="/users/mia.jpg"></ip-avatar>
+  <ip-avatar name="Jonas Lie" src="/users/jonas.jpg"></ip-avatar>
+  <ip-avatar name="Sara Nilsen"></ip-avatar>
+</ip-avatar-stack>
+```
+
+- Boolean attributes such as `clickable` and `disabled` must be set as `clickable="true"` (string value) — Blazor does not reliably render bare boolean attributes on custom elements.

package/dist/llm.md

@@ -169,16 +169,18 @@ In `index.html` `<body>`:
 
 ## Components
 
-| Component              | Description                                                                                     | Docs                                              |
-| ---------------------- | ----------------------------------------------------------------------------------------------- | ------------------------------------------------- |
-| `ip-button`            | Clickable button with visual variants, loading state, and icon slot                             | `docs/web-components/ip-button/llm.md`            |
-| `ip-icon-button`       | Circular icon-only button with CSS ripple, visual variants, and loading state                   | `docs/web-components/ip-icon-button/llm.md`       |
-| `ip-tooltip`           | Tooltip that wraps a trigger and shows non-interactive content on hover, focus, and Escape      | `docs/web-components/ip-tooltip/llm.md`           |
-| `ip-main-menu`         | Sidebar navigation wrapper with expanded/auto-hide/collapsed desktop modes and mobile drawer    | `docs/web-components/ip-main-menu/llm.md`         |
-| `ip-main-menu-toggle`  | Hamburger button for the top bar that opens the `ip-main-menu` mobile drawer via a shared store | `docs/web-components/ip-main-menu-toggle/llm.md`  |
-| `ip-main-menu-section` | Semantic section wrapper that groups navigation items with an optional visible label            | `docs/web-components/ip-main-menu-section/llm.md` |
-| `ip-main-menu-group`   | Collapsible group of navigation items with label, icon, and animated chevron                    | `docs/web-components/ip-main-menu-group/llm.md`   |
-| `ip-main-menu-item`    | Individual navigation item; renders as `<a>` when `href` is provided, otherwise as `<button>`   | `docs/web-components/ip-main-menu-item/llm.md`    |
+| Component              | Description                                                                                                      | Docs                                              |
+| ---------------------- | ---------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- |
+| `ip-button`            | Clickable button with visual variants, loading state, and icon slot                                              | `docs/web-components/ip-button/llm.md`            |
+| `ip-icon-button`       | Circular icon-only button with CSS ripple, visual variants, and loading state                                    | `docs/web-components/ip-icon-button/llm.md`       |
+| `ip-tooltip`           | Tooltip that wraps a trigger and shows non-interactive content on hover, focus, and Escape                       | `docs/web-components/ip-tooltip/llm.md`           |
+| `ip-avatar`            | Theme-aware avatar with image/fallback/initials/silhouette chain, label, ring, loader, corner slots, and tooltip | `docs/web-components/ip-avatar/llm.md`            |
+| `ip-avatar-stack`      | Overlapping stack of `ip-avatar` elements with overflow collapse into a `+N` counter and a combined names label  | `docs/web-components/ip-avatar-stack/llm.md`      |
+| `ip-main-menu`         | Sidebar navigation wrapper with expanded/auto-hide/collapsed desktop modes and mobile drawer                     | `docs/web-components/ip-main-menu/llm.md`         |
+| `ip-main-menu-toggle`  | Hamburger button for the top bar that opens the `ip-main-menu` mobile drawer via a shared store                  | `docs/web-components/ip-main-menu-toggle/llm.md`  |
+| `ip-main-menu-section` | Semantic section wrapper that groups navigation items with an optional visible label                             | `docs/web-components/ip-main-menu-section/llm.md` |
+| `ip-main-menu-group`   | Collapsible group of navigation items with label, icon, and animated chevron                                     | `docs/web-components/ip-main-menu-group/llm.md`   |
+| `ip-main-menu-item`    | Individual navigation item; renders as `<a>` when `href` is provided, otherwise as `<button>`                    | `docs/web-components/ip-main-menu-item/llm.md`    |
 
 ## Services
 

package/dist/types/components/ip-avatar/ip-avatar.d.ts

@@ -0,0 +1,97 @@
+import { EventEmitter, JSX } from '../../stencil-public-runtime';
+export declare class IpAvatar {
+    /** User's full name. Used as the image `alt`, the source for every name representation, and the tooltip text. */
+    name: string;
+    /** Alternative (typically shortened) name shown when `mode="alt-name"`. When unset, the name is abbreviated automatically. */
+    altName: string | undefined;
+    /** Caption line shown beneath the name, e.g. a role or title. */
+    caption: string | undefined;
+    /** Text shown beside the avatar when there is no name, e.g. an unselected-resource hint. */
+    placeholder: string | undefined;
+    /** Primary profile image URL, tried first in the fallback chain. */
+    src: string | undefined;
+    /** Fallback image URL, used when `src` is missing or fails to load. */
+    fallbackSrc: string | undefined;
+    /** Which name representation, if any, is displayed as visible text beside the avatar. */
+    mode: 'fullname' | 'alt-name' | 'firstname' | 'lastname' | 'initials' | 'image-only';
+    /** What to show inside the circle when there is no image: `auto` derives initials from the name (silhouette when nameless), `initials` forces initials, `silhouette` forces the person glyph. */
+    fallback: 'auto' | 'initials' | 'silhouette';
+    /** Position of the text label relative to the avatar circle. */
+    labelPosition: 'top' | 'right' | 'bottom' | 'left';
+    /** Overrides the gap between the avatar and the label. Any CSS length; defaults scale with `size`. */
+    gap: string | undefined;
+    /** Avatar size. Use `custom` together with `customSize` for an arbitrary size. */
+    size: 'small' | 'medium' | 'large' | 'custom';
+    /** Diameter of the avatar when `size="custom"`. Any CSS length, e.g. `64px` or `4rem`. Applied to both width and height so the avatar stays circular. */
+    customSize: string | undefined;
+    /** Native image loading strategy forwarded to the inner `<img>`. */
+    imageLoading: 'lazy' | 'eager';
+    /** Forces the loading spinner regardless of image state — for showing a pending avatar before `src` is known. */
+    loading: boolean;
+    /** Predefined, theme-aware ring colour. Use `custom` together with `ringColor` for a raw colour. */
+    ringVariant: 'default' | 'brand' | 'success' | 'warning' | 'error' | 'custom';
+    /** Raw CSS colour for the ring, applied only when `ringVariant="custom"`. Does not adapt to light/dark. */
+    ringColor: string | undefined;
+    /** Line style of the ring around the circle. */
+    ringStyle: 'solid' | 'dashed' | 'dotted';
+    /** Gap between the ring and the content (image/initials). Any CSS length; defaults to a small constant. */
+    ringGap: string | undefined;
+    /** Makes the avatar interactive: focusable, keyboard-activatable, and emits `ipClick`. */
+    clickable: boolean;
+    /** Applies the selected (active) container styling, e.g. for the chosen item in a list. */
+    selected: boolean;
+    /** Stretches the avatar to fill the available width, so stacked avatars span the full row. */
+    fullWidth: boolean;
+    /** Keeps the name and caption lines at a constant height even when empty, so avatars in a row stay aligned regardless of which carry a name/caption. */
+    maintainLabelHeight: boolean;
+    /** Overlays subtle diagonal stripes on the no-image background (initials / silhouette). */
+    striped: boolean;
+    /** Greys out the avatar and, when `clickable`, prevents activation. */
+    disabled: boolean;
+    /** Disables the built-in tooltip entirely. */
+    disableTooltip: boolean;
+    /** Placement of the tooltip, forwarded to `ip-tooltip`. */
+    tooltipPosition: 'top' | 'right' | 'bottom' | 'left';
+    /** Size of the tooltip, forwarded to `ip-tooltip`. */
+    tooltipSize: 'small' | 'medium' | 'large';
+    /** Colour variant of the tooltip, forwarded to `ip-tooltip`. */
+    tooltipVariant: 'default' | 'onLight' | 'onDark';
+    /** Index into the resolved source chain — advances when an image fails to load. */
+    private srcIndex;
+    /** Tracks whether the current image is still loading, to show the spinner. */
+    private isLoading;
+    /** Tracks whether the consumer slotted custom tooltip content, so the tooltip stays enabled even without a derived name. */
+    private hasTooltipSlot;
+    /** Emitted with the failed src each time an image fails to load and the fallback chain advances. */
+    imageError: EventEmitter<string>;
+    /** Emitted when a clickable, non-disabled avatar is activated by mouse or keyboard. */
+    clickEvent: EventEmitter<void>;
+    /** Whitespace-separated words of the name, with empty entries removed. */
+    private get nameWords();
+    /** Resolved image source chain in priority order, skipping any that are not set and de-duplicating so an identical URL is never retried (which would never fire a second load error). */
+    private get sources();
+    /** The image source currently being displayed, or an empty string once the chain is exhausted. */
+    private get currentSrc();
+    /** The name representation displayed as visible text beside the avatar, per the active mode. */
+    private get visibleName();
+    /** The full name surfaced by the tooltip — shown only when the visible text is not already the full name. */
+    private get tooltipName();
+    componentWillLoad(): void;
+    /** Restarts the fallback chain from the primary source — runs on load and whenever a source prop changes. */
+    resetImageState(): void;
+    /** Marks the image as loaded so the spinner is removed. */
+    private handleImageLoad;
+    /** Advances down the fallback chain on load failure, emitting the failed src; falls back to initials or silhouette once exhausted. */
+    private handleImageError;
+    /** Emits ipClick when the avatar is clickable and not disabled. */
+    private handleActivate;
+    /** Activates the avatar on Enter or Space, mirroring native button keyboard behaviour. */
+    private handleKeyDown;
+    /** Tracks custom tooltip slot content so the tooltip is not auto-disabled when the consumer provides their own. */
+    private handleTooltipSlotChange;
+    /** Whether the initials fallback should render: forced by `fallback`, or chosen automatically when a name is present. */
+    private get showsInitials();
+    /** Renders the image, the initials fallback, or the silhouette placeholder depending on what is available. */
+    private renderMediaContent;
+    render(): JSX.Element;
+}

package/dist/types/components/ip-avatar-stack/ip-avatar-stack.d.ts

@@ -0,0 +1,96 @@
+import { EventEmitter, JSX } from '../../stencil-public-runtime';
+export declare class IpAvatarStack {
+    /** Host element, used to keep the stacking layout in sync when layout props change. */
+    private host;
+    /** Maximum number of avatars shown before the rest collapse into a `+N` counter. Acts as the hard cap; with `auto-fit` on, fewer may show. */
+    max: number;
+    /** Reduces the visible avatars to fit the container width, collapsing the rest like `max` does (`max` stays the cap). Set `auto-fit="false"` for a fixed stack that always shows up to `max`. */
+    autoFit: boolean;
+    /** Stack size. Drives the overflow counter size and the default overlap; slotted avatars should match. */
+    size: 'small' | 'medium' | 'large' | 'custom';
+    /** Diameter of the overflow counter when `size="custom"`. Any CSS length, applied to both width and height. */
+    customSize: string | undefined;
+    /** Overrides the overlap offset between circles. Any CSS length; defaults scale with `size`. */
+    overlap: string | undefined;
+    /** How the group is summarised: the first name with a `+N` rest count, a `+N` overflow counter circle in the stack, or nothing. The counter circle and the text label are mutually exclusive. */
+    labelMode: 'name' | 'counter' | 'none';
+    /** Overrides the gap between the stack and the label. Any CSS length; defaults scale with `size`. */
+    gap: string | undefined;
+    /** Whether the tooltip previews (the counter and the names label) show a small avatar beside each person, or just the name and caption. */
+    previewAvatars: boolean;
+    /** Makes the `+N` overflow counter focusable, keyboard-activatable, and emits `ipOverflowClick`. */
+    clickable: boolean;
+    /** Greys out the stack and, when `clickable`, prevents activation of the overflow counter. */
+    disabled: boolean;
+    /** Identity of every slotted avatar, in order. Drives the count, the names label, the counter, and both tooltip previews. */
+    private people;
+    /** Width-fitted cap computed by the width observer when `autoFit` is on; `null` until first measured (then `effectiveMax` falls back to `max`). */
+    private fittedMax;
+    /** Emitted when a clickable, non-disabled overflow counter is activated by mouse or keyboard. */
+    overflowClick: EventEmitter<void>;
+    /** Active width observer driving auto-fit; null when auto-fit is off or the element is detached. */
+    private resizeObserver;
+    /** True once the first render has measured; gates restart-on-reconnect so the very first connect defers to `componentDidLoad`. */
+    private hasLoaded;
+    /** Re-reads the slot and re-applies the layout when the collapse threshold changes. */
+    relayout(): void;
+    /** Re-fits when a dimension-affecting prop changes — the count that fits depends on avatar size and overlap. */
+    onDimensionChange(): void;
+    /** Starts or stops width observation when auto-fit is toggled, resetting the fitted cap. */
+    onAutoFitChange(): void;
+    /** Restarts width observation when the element is re-attached after a move; the first connect defers to `componentDidLoad`. */
+    connectedCallback(): void;
+    /** Begins observing the container width once the element and its slotted avatars exist. */
+    componentDidLoad(): void;
+    /** Tears down the width observer when the element leaves the DOM. */
+    disconnectedCallback(): void;
+    /** The `ip-avatar` elements currently assigned to the default slot. */
+    private assignedAvatars;
+    /** Reads the first avatar's name from the `name` property, falling back to the attribute for plain-HTML consumers. */
+    private nameOf;
+    /** Reads an avatar's image source from the `src` property, falling back to the attribute for plain-HTML consumers. */
+    private srcOf;
+    /** Reads an avatar's caption from the `caption` property, falling back to the attribute for plain-HTML consumers. */
+    private captionOf;
+    /** Records every slotted avatar's identity, then applies the stacking layout. */
+    private syncFromSlot;
+    /** Re-reads the slotted avatars whenever the assigned set changes. */
+    private handleSlotChange;
+    /** Forces each avatar to image-only, paints each above the one before it (last on top), and collapses avatars beyond `effectiveMax` into the overflow counter. */
+    private applyStacking;
+    /** Avatars to show before collapsing: the width-fitted cap (never above `max`) in auto-fit mode, otherwise `max`. */
+    private get effectiveMax();
+    /** Observes the parent's width (container resize) and the window (ambient resize) so the fitted cap stays in sync. */
+    private startObserving;
+    /** Disconnects the width observer and the window listener. */
+    private stopObserving;
+    /** Measures the container and updates the fitted cap, re-applying the stacking layout when it changes. */
+    private recomputeFit;
+    /** Content-box width available to the stack, measured from its parent. */
+    private availableWidth;
+    /** Current overlap offset in px, read from the computed custom property (set per size or via the `overlap` prop). */
+    private measuredOverlap;
+    /** Current stack↔label gap in px, read from the computed custom property (set per size or via the `gap` prop). */
+    private measuredGap;
+    /** Natural width of the rendered names label, reserved so it is not clipped before avatars collapse in name mode. */
+    private measuredLabelWidth;
+    /** Pixel width the `+N` counter occupies, matching the per-size circle in the SCSS. */
+    private counterWidth;
+    /** Largest avatar count that fits the available width, reserving room for the counter when one will show. At least 1. */
+    private computeFittedMax;
+    /** Emits ipOverflowClick when the counter is clickable and not disabled. */
+    private handleOverflowActivate;
+    /** Activates the overflow counter on Enter or Space, mirroring native button keyboard behaviour. */
+    private handleOverflowKeyDown;
+    /** Auto-generated names label: the first name plus a `+N` count of the remaining avatars. */
+    private get labelText();
+    /** Renders the people preview: ip-avatar's built-in label per row, or a compact name-only list when `previewAvatars` is off. Shared by the counter preview and the names-label tooltip. */
+    private renderPeopleList;
+    /** A preview row using ip-avatar's own circle, name, and caption. The class makes its label inherit the tooltip bubble's colour. */
+    private renderPersonRow;
+    /** A compact, avatar-less preview row — the name with an optional caption beneath. Used when `previewAvatars` is off, where ip-avatar's circle-bound label cannot apply. */
+    private renderPersonName;
+    /** Inline custom properties for the overlap and label gap, set only when the consumer overrides the defaults. */
+    private get hostStyle();
+    render(): JSX.Element;
+}