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

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

@@ -0,0 +1,165 @@
+# 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`                               | Label (name) text colour                                          |
+| `$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)                      |
+
+## 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/llm.md

@@ -169,16 +169,17 @@ 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-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;
+}