npm - @norconsult-digital-public/isypixel - Versions diffs - 2.0.2-canary.3 → 2.0.2-canary.5 - Mend

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

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 (84) hide show

package/LICENSE.md CHANGED Viewed

@@ -14,3 +14,14 @@ Norconsult Digital AS.
 The software is provided "AS IS", without warranties of any kind.
 Reverse engineering, decompilation, and disassembly are prohibited.
+---
+## Third-party attribution
+This package includes SVG icons sourced from Font Awesome Free 7.2.0.
+- Source: https://fontawesome.com
+- License: https://fontawesome.com/license/free
+- Icons under CC BY 4.0
+- Copyright © Fonticons, Inc.

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

@@ -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/docs/web-components/ip-icon-button/llm.md ADDED Viewed

@@ -0,0 +1,113 @@
+# ip-icon-button
+A circular icon-only button with a CSS ripple on click and a built-in tooltip on hover. Available in five visual variants shared with `ip-button`, plus two transparent variants (`transparentOnLight`/`transparentOnDark`) for use on surfaces that do not follow the global theme. Requires a `label` attribute for screen reader accessibility — `label` is also used as the tooltip text by default.
+## Attributes
+| Attribute            | Type    | Default     | Allowed values                                                                                                                  | Description                                                                                                                                                                    |
+| -------------------- | ------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `variant`            | string  | `"primary"` | `"primary"` \| `"secondary"` \| `"tertiary"` \| `"brand"` \| `"destructive"` \| `"transparentOnLight"` \| `"transparentOnDark"` | Visual variant of the button. The two transparent variants are interim placeholders used internally by `ip-main-menu` and may change when the dedicated token family lands.    |
+| `size`               | string  | `"medium"`  | `"small"` \| `"medium"` \| `"large"`                                                                                            | Controls the size of the button. Affects padding and icon size.                                                                                                                |
+| `disabled`           | boolean | `false`     | —                                                                                                                               | Disables the button. Also set implicitly when `loading` is `true`.                                                                                                             |
+| `loading`            | boolean | `false`     | —                                                                                                                               | Replaces the icon with a spinner and disables interaction. Renders a screen-reader-only "Loading..." text.                                                                     |
+| `type`               | string  | `"button"`  | `"button"` \| `"submit"` \| `"reset"`                                                                                           | Controls form behaviour. Defaults to `"button"` to prevent accidental form submission.                                                                                         |
+| `label`              | string  | `""`        | —                                                                                                                               | **Required.** Sets `aria-label` for screen readers and is used as the default tooltip text. When empty, the tooltip is implicitly hidden and a development warning is logged.  |
+| `disableTooltip`     | boolean | `false`     | —                                                                                                                               | Hides the built-in tooltip. Useful when the button is already described by surrounding context.                                                                                |
+| `tooltipSize`        | string  | —           | `"small"` \| `"medium"` \| `"large"`                                                                                            | Overrides the tooltip size. When unset, the tooltip inherits the button's `size`.                                                                                              |
+| `tooltipPosition`    | string  | —           | `"top"` \| `"right"` \| `"bottom"` \| `"left"`                                                                                  | Position of the tooltip relative to the button. When unset, the tooltip uses its own default (`"top"`).                                                                        |
+| `tooltipVariant`     | string  | `"default"` | `"default"` \| `"onLight"` \| `"onDark"`                                                                                        | Color variant of the tooltip. `default` adapts to the active theme. Use `"onLight"`/`"onDark"` when the button sits on a surface whose color does not follow the global theme. |
+| `tooltipHideOnClick` | boolean | `true`      | —                                                                                                                               | When `false`, clicking the button does not dismiss the tooltip. Use for toggle buttons where the tooltip text updates on click (e.g. collapse/expand, pin/unpin).              |
+| `aria-expanded`      | string  | `null`      | `"true"` \| `"false"`                                                                                                           | Property name: `expanded`. Forwards `aria-expanded` to the inner `<button>` for disclosure patterns (e.g. menu toggles). When `null` (default) the attribute is not rendered.  |
+## Slots
+| Slot      | Description                                                                                  |
+| --------- | -------------------------------------------------------------------------------------------- |
+| `icon`    | The icon element to display. Hidden when `loading` is `true`. Typically an `<i>` or `<svg>`. |
+| `tooltip` | Optional HTML override for the tooltip content. When omitted, the `label` value is used.     |
+## Size tokens
+| Size     | Padding (all sides)     | Icon size                            |
+| -------- | ----------------------- | ------------------------------------ |
+| `small`  | `$ip_spacing_space_100` | `$ip_iconography_size_small` (18px)  |
+| `medium` | `$ip_spacing_space_125` | `$ip_iconography_size_medium` (20px) |
+| `large`  | `$ip_spacing_space_150` | `$ip_iconography_size_large` (22px)  |
+## Color tokens
+| Token                                                                 | Description                                            |
+| --------------------------------------------------------------------- | ------------------------------------------------------ |
+| `$ip_color_icon_button_background_primary_default`                    | Primary background, default state                      |
+| `$ip_color_icon_button_background_primary_hover`                      | Primary background, hover state                        |
+| `$ip_color_icon_button_background_primary_active`                     | Primary background, active state                       |
+| `$ip_color_button_background_[variant]_default/hover/active/disabled` | Background for secondary, tertiary, brand, destructive |
+| `$ip_color_button_icon_[variant]_default`                             | Icon color, default state                              |
+| `$ip_color_button_icon_[variant]_disabled`                            | Icon color, disabled state                             |
+| `$ip_color_button_focus_default`                                      | Focus outline color                                    |
+## Usage examples
+### HTML
+```html
+<ip-icon-button label="Save" variant="primary">
+  <i slot="icon" class="fas fa-floppy-disk"></i>
+</ip-icon-button>
+<!-- With HTML tooltip override -->
+<ip-icon-button label="Save" variant="primary">
+  <i slot="icon" class="fas fa-floppy-disk"></i>
+  <span slot="tooltip">Save <strong>document</strong></span>
+</ip-icon-button>
+```
+### React
+```tsx
+import { IpIconButton } from '@norconsult-digital-public/isypixel/web-components/react';
+<IpIconButton label='Save' variant='primary'>
+  <i slot='icon' className='fas fa-floppy-disk' />
+</IpIconButton>;
+```
+### Vue
+```html
+<IpIconButton label="Save" variant="primary">
+  <i slot="icon" class="fas fa-floppy-disk" />
+</IpIconButton>
+```
+### Angular
+```ts
+import { IpIconButton } from '@norconsult-digital-public/isypixel/web-components/angular';
+```
+```html
+<ip-icon-button label="Save" variant="primary">
+  <i slot="icon" class="fas fa-floppy-disk"></i>
+</ip-icon-button>
+```
+### Svelte
+```html
+<script>
+  import '@norconsult-digital-public/isypixel/web-components/ip-icon-button.js';
+</script>
+<ip-icon-button label="Save" variant="primary">
+  <i slot="icon" class="fas fa-floppy-disk"></i>
+</ip-icon-button>
+```
+### Blazor
+```html
+<ip-icon-button label="Save" variant="primary">
+  <i slot="icon" class="fas fa-floppy-disk"></i>
+</ip-icon-button>
+```

package/dist/docs/web-components/ip-main-menu/llm.md ADDED Viewed

@@ -0,0 +1,219 @@
+# ip-main-menu
+Outer sidebar navigation wrapper for ISY applications. Manages three desktop display modes (expanded, auto-hide, collapsed) and a full-height mobile overlay drawer. Must be composed with `ip-main-menu-section`, `ip-main-menu-group`, and `ip-main-menu-item`.
+> **Opening the drawer on mobile:** The mobile drawer is opened by the separate `ip-main-menu-toggle` component, placed in your top bar. The two communicate through a shared store — no wiring needed. See `ip-main-menu-toggle/llm.md`.
+> **Layout requirement:** On desktop, the parent element must use `display: flex` or `display: grid` with a defined height, otherwise the sidebar will not fill the viewport. Example: `<div style="display:flex; height:100vh;"><ip-main-menu>...</ip-main-menu><main>...</main></div>`. At the mobile breakpoint the nav becomes a fixed overlay drawer and the host collapses to take no space in the layout.
+> **Breakpoint:** Mobile drawer behaviour activates at or below the `mobileBreakpoint` prop (default `1024px`). The value is shared through the store so `ip-main-menu-toggle` switches at the exact same width with no extra wiring. Below 768px the drawer spans the full viewport width (a fixed phone-size breakpoint, not configurable). No breakpoint design token is available yet; these values are hardcoded.
+> **Single-instance:** Use one `<ip-main-menu>` per page. The desktop mode and mobile drawer state are kept in a module-level store, so multiple instances on the same page will share state and stay in sync — there is no per-instance isolation.
+## Attributes
+| Attribute          | Type                                       | Default      | Allowed values                             | Description                                                                                                                                                                      |
+| ------------------ | ------------------------------------------ | ------------ | ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `heading`          | `string`                                   | —            | Any string                                 | Required. App name shown in expanded mode. Used as `aria-label` on `<nav>` and as `aria-label` on the brand element.                                                             |
+| `mode`             | `'expanded' \| 'auto-hide' \| 'collapsed'` | `'expanded'` | `'expanded'`, `'auto-hide'`, `'collapsed'` | Desktop display mode. Sets initial state; internal state tracks user interactions. Not persisted across refreshes or browser sessions — persist via `ipModeChange` (see below).  |
+| `brandHref`        | `string`                                   | —            | Any URL string                             | Optional. When set, the brand area (logo + heading) renders as an `<a>` linking to this URL. Without it, it renders as a `<button>` that emits `ipBrandClick`.                   |
+| `expandDelay`      | `number`                                   | `300`        | Any non-negative number (ms)               | Hover-intent delay before `auto-hide` expands. Increase to ignore longer drift-overs, decrease for snappier expansion. Only applies in `auto-hide` mode.                         |
+| `collapseDelay`    | `number`                                   | `300`        | Any non-negative number (ms)               | Grace period before `auto-hide` collapses after the mouse leaves. Increase to forgive accidental cursor slips, decrease for snappier collapse. Only applies in `auto-hide` mode. |
+| `mobileBreakpoint` | `string`                                   | `'1024px'`   | Any CSS length (e.g. `1024px`, `64rem`)    | Viewport width at or below which the menu becomes a mobile drawer and `ip-main-menu-toggle` appears. Shared through the store so both components switch at the same width.       |
+### Desktop modes
+| Mode        | Width | Behaviour                                 |
+| ----------- | ----- | ----------------------------------------- |
+| `expanded`  | 230px | Full labels and icons visible.            |
+| `auto-hide` | 64px  | Icons only. Expands temporarily on hover. |
+| `collapsed` | 64px  | Icons only. No hover expansion.           |
+Mode transitions:
+- **expanded → auto-hide**: click pin button
+- **expanded → collapsed**: click collapse button
+- **collapsed → expanded**: click collapse button (rotated 180°)
+- **auto-hide → expanded**: click pin/unpin button
+> The collapse button is only shown in `expanded` and `collapsed` modes. The pin button is only shown in `expanded` and `auto-hide` modes.
+## Slots
+| Slot            | Description                                                                                                                                                                                                                                                                                                                       |
+| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `logo`          | Custom logo shown in collapsed/auto-hide mode. Falls back to the built-in ISY logo if omitted.                                                                                                                                                                                                                                    |
+| `default`       | Main navigation content (`ip-main-menu-section`, `ip-main-menu-group`, `ip-main-menu-item`).                                                                                                                                                                                                                                      |
+| `bottom`        | Content pinned to the bottom of the sidebar (e.g. user profile, logout).                                                                                                                                                                                                                                                          |
+| `icon-close`    | Mobile drawer close icon. Default: Font Awesome Free `xmark` (solid). Replace by slotting your own.                                                                                                                                                                                                                               |
+| `icon-pin`      | Desktop pin button icon — shown when mode is `expanded`. Default: Font Awesome Free `thumbtack` (solid). Replace by slotting your own.                                                                                                                                                                                            |
+| `icon-unpin`    | Desktop pin button icon — shown when mode is `auto-hide`. Default: same `thumbtack` SVG as `icon-pin`, rotated 45° via CSS — identical size, no clipping. The intended design icon is FA Pro `thumbtack-angle` (sharp regular); inject it through this slot when a Pro license is available (slotted icons are not auto-rotated). |
+| `icon-collapse` | Desktop collapse/expand button icon. Rotates 180° based on mode. Default: Font Awesome Free `chevron-left` (solid). Replace by slotting your own.                                                                                                                                                                                 |
+> **Icon fallbacks:** Default SVGs are inlined from Font Awesome Free 7.2.0 (CC BY 4.0 — see LICENSE.md). Each fallback is a separate export in `icons.ts`, so any default a consumer overrides via the matching `icon-*` slot is tree-shaken from the bundle.
+## Injecting icons
+ISY applications use Font Awesome per the design system, and the bundled fallbacks are already FA Free SVGs. Slot injection is therefore only needed in two cases:
+**1. The unpin icon (recommended when an FA Pro license is available).** The intended design icon for `icon-unpin` is [`thumbtack-angle`](https://fontawesome.com/icons/sharp/regular/thumbtack-angle) (sharp regular), which is FA Pro and cannot be bundled for license reasons. The built-in fallback approximates it with the Free `thumbtack` rotated 45°. Inject the intended icon when the consuming application has a Pro license:
+```html
+<ip-main-menu heading="My Application" brand-href="/">
+  <i slot="icon-unpin" class="fa-sharp fa-regular fa-thumbtack-angle"></i>
+</ip-main-menu>
+```
+**2. A different icon library.** If the application does not use Font Awesome, replace all four control icons:
+```html
+<ip-main-menu heading="My Application" brand-href="/">
+  <span slot="icon-close">...</span>
+  <span slot="icon-pin">...</span>
+  <span slot="icon-unpin">...</span>
+  <span slot="icon-collapse">...</span>
+</ip-main-menu>
+```
+The same pattern applies in all frameworks: slot the element into the matching named slot.
+## Events
+| Event                | Payload                                                 | Description                                                                                          |
+| -------------------- | ------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
+| `ipModeChange`       | `CustomEvent<'expanded' \| 'auto-hide' \| 'collapsed'>` | Fires when the user changes desktop mode.                                                            |
+| `ipMobileOpenChange` | `CustomEvent<boolean>`                                  | Fires when the mobile drawer opens or closes. Use this to lock body scroll.                          |
+| `ipBrandClick`       | `CustomEvent<void>`                                     | Fires when the brand area is clicked and `brandHref` is not set. Use for SPA client-side navigation. |
+### Persisting mode across sessions
+The mode lives in memory only; refreshing the page resets it to the `mode` prop. Persist it yourself until a dedicated menu state persistence service is added to Pixel:
+```javascript
+const nav = document.querySelector('ip-main-menu');
+nav.mode = localStorage.getItem('nav-mode') ?? 'expanded';
+nav.addEventListener('ipModeChange', (e) => {
+  localStorage.setItem('nav-mode', e.detail);
+});
+```
+## Design tokens
+| Token                                           | Role                                                                                |
+| ----------------------------------------------- | ----------------------------------------------------------------------------------- |
+| `ip_color_menu_main_background_primary_default` | Sidebar background                                                                  |
+| `ip_color_button_focus_default`                 | Focus outline on control buttons (interim until a menu-specific focus token exists) |
+> **Token gaps (flagged to design team):**
+>
+> - Text/icon colour tokens for sidebar controls (`ip_color_menu_main_*_text`), heading, and logo
+> - Control button hover background and scrollbar colours (hardcoded with `//TODO:` comments)
+> - Width tokens (230px expanded, 64px collapsed)
+> - Mobile breakpoint token (drawer breakpoint defaults to 1024px via `mobileBreakpoint`; full-width phone breakpoint hardcoded to 768px)
+> - Mobile backdrop overlay colour token
+## Usage examples
+### HTML
+```html
+<!-- With brandHref — brand area renders as <a> -->
+<div style="display:flex; height:100vh;">
+  <ip-main-menu heading="My Application" brand-href="/">
+    <ip-main-menu-section label="Main">
+      <ip-main-menu-item label="Dashboard" active>
+        <svg slot="icon" ...></svg>
+      </ip-main-menu-item>
+    </ip-main-menu-section>
+    <ip-main-menu-item label="Settings" slot="bottom">
+      <svg slot="icon" ...></svg>
+    </ip-main-menu-item>
+  </ip-main-menu>
+  <main>...</main>
+</div>
+<!-- Without brandHref — brand area renders as <button>, handle ipBrandClick for SPA navigation -->
+<ip-main-menu heading="My Application" id="nav"></ip-main-menu>
+<script>
+  document.getElementById('nav').addEventListener('ipBrandClick', () => router.navigate('/'));
+</script>
+```
+### React
+```tsx
+import { IpMainMenu, IpMainMenuSection, IpMainMenuItem } from '@norconsult-digital-public/isypixel/web-components/react';
+// href-based navigation
+<IpMainMenu heading='My Application' brandHref='/'>
+  <IpMainMenuSection label='Main'>
+    <IpMainMenuItem label='Dashboard' active />
+  </IpMainMenuSection>
+</IpMainMenu>
+// SPA / client-side navigation
+<IpMainMenu heading='My Application' onIpBrandClick={() => navigate('/')}>
+  ...
+</IpMainMenu>
+```
+### Vue
+```vue
+<!-- href-based -->
+<IpMainMenu heading="My Application" brand-href="/">
+  <IpMainMenuSection label="Main">
+    <IpMainMenuItem label="Dashboard" :active="true" />
+  </IpMainMenuSection>
+</IpMainMenu>
+<!-- SPA -->
+<IpMainMenu heading="My Application" @ip-brand-click="router.push('/')">
+  ...
+</IpMainMenu>
+```
+### Angular
+```html
+<!-- href-based -->
+<ip-main-menu heading="My Application" brandHref="/">
+  <ip-main-menu-section label="Main">
+    <ip-main-menu-item label="Dashboard" [active]="true"></ip-main-menu-item>
+  </ip-main-menu-section>
+</ip-main-menu>
+<!-- SPA -->
+<ip-main-menu heading="My Application" (ipBrandClick)="router.navigate(['/'])"> </ip-main-menu>
+```
+### Svelte
+```svelte
+<!-- href-based -->
+<IpMainMenu heading="My Application" brandHref="/">
+  <IpMainMenuSection label="Main">
+    <IpMainMenuItem label="Dashboard" active />
+  </IpMainMenuSection>
+</IpMainMenu>
+<!-- SPA -->
+<IpMainMenu heading="My Application" on:ipBrandClick={() => goto('/')}>
+  ...
+</IpMainMenu>
+```
+### Blazor
+```razor
+<!-- href-based -->
+<ip-main-menu heading="My Application" brand-href="/">
+  <ip-main-menu-section label="Main">
+    <ip-main-menu-item label="Dashboard" active="true"></ip-main-menu-item>
+  </ip-main-menu-section>
+</ip-main-menu>
+<!-- SPA -->
+<ip-main-menu heading="My Application" @onipBrandClick="NavigateHome">
+</ip-main-menu>
+```

package/dist/docs/web-components/ip-main-menu-group/llm.md ADDED Viewed

@@ -0,0 +1,114 @@
+# ip-main-menu-group
+Collapsible group of navigation items with a label, optional icon, and an animated chevron. The chevron rotates 180° on open/close. In collapsed mode the label and chevron are hidden; a tooltip appears on hover/focus.
+> **Note:** This component must be used inside an `ip-main-menu`.
+## Attributes
+| Attribute | Type      | Default | Allowed values  | Description                                                                                                                                                                                                                                               |
+| --------- | --------- | ------- | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `label`   | `string`  | —       | Any string      | Required. Group label in expanded mode. Used as accessible name and tooltip in collapsed mode.                                                                                                                                                            |
+| `active`  | `boolean` | `false` | `true`, `false` | Whether any child item is active. Applies selected styling to the group trigger.                                                                                                                                                                          |
+| `open`    | `boolean` | `false` | `true`, `false` | Initial expanded state. Internal state takes over after first interaction (uncontrolled pattern). Not persisted across refreshes or browser sessions — listen to `ipOpenChange` to persist. A menu state persistence service may be added to Pixel later. |
+## Slots
+| Slot           | Description                                                                           |
+| -------------- | ------------------------------------------------------------------------------------- |
+| `default`      | `ip-main-menu-item` children.                                                         |
+| `icon`         | Icon displayed to the left of the label.                                              |
+| `icon-chevron` | Chevron icon. Default: inline SVG arrow. Rotates 180° via CSS transition when `open`. |
+> **Custom chevron:** Slot `icon-chevron` to replace the built-in arrow, e.g. `<i slot="icon-chevron" class="fa-solid fa-chevron-down"></i>`. The slotted icon rotates 180° on open/close just like the default.
+## Events
+| Event          | Payload                | Description                                           |
+| -------------- | ---------------------- | ----------------------------------------------------- |
+| `ipOpenChange` | `CustomEvent<boolean>` | Fires when the user toggles the group open or closed. |
+## Design tokens
+| Token                                                               | Role                                                                    |
+| ------------------------------------------------------------------- | ----------------------------------------------------------------------- |
+| `ip_color_menu_main_item_background_primary_default`                | Group trigger background (default)                                      |
+| `ip_color_menu_main_group_item_background_primary_default`          | Group trigger background (open) and child item background               |
+| `ip_color_menu_main_group_item_background_primary_hover`            | Group trigger background (hover)                                        |
+| `ip_color_menu_main_group_item_background_primary_active`           | Group trigger background (pressed)                                      |
+| `ip_color_menu_main_group_item_background_primary_selected_default` | Group trigger background when `active`                                  |
+| `ip_color_menu_main_group_item_background_primary_selected_hover`   | Active group trigger background (hover)                                 |
+| `ip_color_menu_main_group_item_background_primary_selected_active`  | Active group trigger background (pressed)                               |
+| `ip_color_menu_main_item_vertical_divider_primary_default`          | Left-border accent on active group trigger                              |
+| `ip_color_button_focus_default`                                     | Focus outline colour (interim until a menu-specific focus token exists) |
+> **Token gaps:** Text/icon colour tokens for group items are not yet available. Hardcoded values are used with `// TODO` comments.
+## Usage examples
+### HTML
+```html
+<ip-main-menu heading="My App">
+  <ip-main-menu-group label="Reports">
+    <svg slot="icon" ...></svg>
+    <ip-main-menu-item label="Monthly"></ip-main-menu-item>
+    <ip-main-menu-item label="Yearly"></ip-main-menu-item>
+  </ip-main-menu-group>
+</ip-main-menu>
+```
+### React
+```tsx
+<IpMainMenu heading='My App'>
+  <IpMainMenuGroup label='Reports' onIpOpenChange={(e) => console.log(e.detail)}>
+    <svg slot='icon' />
+    <IpMainMenuItem label='Monthly' />
+  </IpMainMenuGroup>
+</IpMainMenu>
+```
+### Vue
+```vue
+<IpMainMenu heading="My App">
+  <IpMainMenuGroup label="Reports" @ip-open-change="handleChange">
+    <svg slot="icon" />
+    <IpMainMenuItem label="Monthly" />
+  </IpMainMenuGroup>
+</IpMainMenu>
+```
+### Angular
+```html
+<ip-main-menu heading="My App">
+  <ip-main-menu-group label="Reports" (ipOpenChange)="handleChange($event)">
+    <svg slot="icon"></svg>
+    <ip-main-menu-item label="Monthly"></ip-main-menu-item>
+  </ip-main-menu-group>
+</ip-main-menu>
+```
+### Svelte
+```svelte
+<IpMainMenu heading="My App">
+  <IpMainMenuGroup label="Reports" on:ipOpenChange={handleChange}>
+    <svg slot="icon" />
+    <IpMainMenuItem label="Monthly" />
+  </IpMainMenuGroup>
+</IpMainMenu>
+```
+### Blazor
+```razor
+<ip-main-menu heading="My App">
+  <ip-main-menu-group label="Reports">
+    <svg slot="icon"></svg>
+    <ip-main-menu-item label="Monthly"></ip-main-menu-item>
+  </ip-main-menu-group>
+</ip-main-menu>
+```