@kubex/zinc 1.1.185 → 2.0.0

package/src/components/header/header.scss

@@ -15,6 +15,7 @@
   }
 
   &__caption {
+    font-family: var(--zn-text-h1-font-family, inherit);
     font-weight: var(--zn-text-h1-font-weight);
     font-size: var(--zn-text-h1-font-size);
     text-transform: var(--zn-text-h1-transform, none);
@@ -84,7 +85,7 @@
     }
 
     zn-icon:hover {
-      color: rgb(var(--zn-primary));
+      color: var(--zn-color-primary-fg, rgb(var(--zn-primary)));
       cursor: pointer;
     }
   }
@@ -131,8 +132,7 @@
     flex-grow: 1;
     flex-shrink: 1;
     // Chrome ignores overflow-clip-margin unless both axes clip
-    overflow: clip;
-    overflow-clip-margin: var(--zn-focus-ring-outset);
+    @include wc.clip-focus-room;
     min-width: 20px;
   }
 
@@ -159,7 +159,7 @@
     }
 
     &::slotted(a:hover) {
-      color: rgb(var(--zn-primary));
+      color: var(--zn-color-primary-fg, rgb(var(--zn-primary)));
     }
 
     &::slotted(a)::after {
@@ -190,7 +190,7 @@
       cursor: pointer;
 
       &:hover {
-        color: rgb(var(--zn-primary));
+        color: var(--zn-color-primary-fg, rgb(var(--zn-primary)));
       }
     }
   }
@@ -232,6 +232,12 @@
     flex-wrap: nowrap;
   }
 
+  // Controls in the actions row line up with the buttons beside them, without
+  // the label/help-text spacing a form field otherwise carries.
+  slot[name="actions"]::slotted(*) {
+    --zn-form-control-input-margin: 0;
+  }
+
   slot[name="actions"]::slotted(zn-button-menu) {
     flex-grow: 1;
     flex-shrink: 1;
@@ -247,3 +253,39 @@
     border-bottom: none !important;
   }
 }
+
+.header__left:has(.header__description) {
+  display: flex;
+  flex-direction: column;
+  gap: var(--zn-spacing-2x-small);
+}
+
+.header--inline-description .header__left:has(.header__description) {
+  flex-direction: row;
+  flex-wrap: wrap;
+  justify-content: flex-start;
+  align-items: baseline;
+  gap: 0 var(--zn-spacing-x-small);
+}
+
+// Narrow headers drop the actions onto their own row instead of squeezing the caption
+.header .caption {
+  flex-wrap: wrap;
+  row-gap: var(--zn-spacing-small);
+}
+
+.header__caption {
+  flex-shrink: 0;
+  min-width: min-content;
+}
+
+.header__right {
+  min-width: min-content;
+}
+
+.header__description {
+  font-size: var(--zn-header-description-font-size, var(--zn-font-size-x-small));
+  font-weight: normal;
+  line-height: var(--zn-line-height-normal, 1.45);
+  color: var(--zn-header-description-color, var(--zn-text-color-muted));
+}

package/src/components/hover-container/hover-container.component.ts

@@ -81,8 +81,9 @@ export default class ZnHoverContainer extends ZincElement {
     return triggers.includes(triggerType);
   }
 
-  private handleBlur = () => {
-    if (this.hasTrigger('focus')) {
+  // relatedTarget is retargeted to this host when focus moves into the shadow root, so contains() covers both trees
+  private handleBlur = (event: FocusEvent) => {
+    if (this.hasTrigger('focus') && !this.contains(event.relatedTarget as Node | null)) {
       this.hide();
     }
   };
@@ -204,9 +205,7 @@ export default class ZnHoverContainer extends ZincElement {
         hover-bridge>
         <slot slot="anchor"></slot>
         <div part="body" id="hover-container" class="hover-container__body"
-             role="hover-container"
-             aria-live=${this.open ? 'polite' : 'off'}
-             aria-label="hover-container">
+             aria-live=${this.open ? 'polite' : 'off'}>
           <slot name="content">${this.content}</slot>
         </div>
       </zn-popup>`;

package/src/components/icon/icon.component.ts

@@ -5,6 +5,7 @@ import {property} from 'lit/decorators.js';
 import {sha256} from '../../utilities/sha256';
 import {styleMap} from "lit/directives/style-map.js";
 import {unsafeSVG} from 'lit/directives/unsafe-svg.js';
+import lineIconStyles from './lni.scss';
 import ZincElement from '../../internal/zinc-element';
 import type {IconNode, SVGProps} from 'lucide';
 
@@ -28,9 +29,27 @@ function loadLucideIcons(): Promise<void> {
   return lucidePromise;
 }
 
+// Country flags (3:2 SVGs keyed by ISO 3166 alpha-2 code) load lazily like lucide
+let flagIcons: Record<string, string> | undefined;
+let flagPromise: Promise<void> | undefined;
+
+function loadFlagIcons(): Promise<void> {
+  flagPromise ??= import('country-flag-icons/string/3x2').then(m => {
+    flagIcons = m as unknown as Record<string, string>;
+  }).catch((error: unknown) => {
+    flagPromise = undefined;
+    console.warn('<zn-icon> failed to load the flag icon chunk', error);
+  });
+  return flagPromise;
+}
+
 export type IconLibrary = "src" | "material" | "material-outlined" | "material-round" | "material-sharp" |
   "material-two-tone" | "material-symbols-outlined" | "gravatar" | "libravatar" | "avatar" | "brands" | "line" |
-  "lucide";
+  "lucide" | "flag";
+
+export type AvatarPresence = 'online' | 'away' | 'busy' | 'meeting' | 'offline';
+
+const namedSizes: Record<string, number> = {sm: 22, md: 28, lg: 40, xl: 56};
 
 export type IconColor =
   "default"
@@ -70,14 +89,24 @@ export type IconColor =
  *
  * @cssproperty --example - An example CSS custom property.
  */
+// Lineicons' ~600 glyph rules are adopted only by icons that use them: every adopted rule is restyled per shadow
+// root, and icons are the most numerous component on a page (over 1,000 on some views, seconds of style work in Safari).
+const lineIcons = unsafeCSS(lineIconStyles);
+
 export default class ZnIcon extends ZincElement {
   static styles: CSSResultGroup = unsafeCSS(styles);
 
+  private _lineIconsAdopted = false;
+
   @property({reflect: true}) src: string;
 
   @property({reflect: true}) alt: string;
 
-  @property({type: Number, reflect: true}) size: number = 24;
+  /** Size in pixels, or one of the avatar sizes `sm` (22), `md` (28), `lg` (40) and `xl` (56). */
+  @property({
+    reflect: true,
+    converter: {fromAttribute: (value: string | null) => namedSizes[value ?? ''] ?? (value === null ? 24 : Number(value))}
+  }) size: number = 24;
 
   @property({type: Boolean, reflect: true}) round = false;
   @property({type: Boolean, reflect: true}) tile = false;
@@ -94,6 +123,12 @@ export default class ZnIcon extends ZincElement {
 
   @property({type: Boolean}) squared: boolean = false;
 
+  /** A live-status dot on an avatar: `online`, `away`, `busy`, `meeting` or `offline`. */
+  @property({reflect: true}) presence: AvatarPresence;
+
+  /** Draws an avatar as a solid circle even where the theme tints avatars. */
+  @property({type: Boolean, reflect: true}) solid = false;
+
   private static readonly presetColors = new Set([
     'default', 'primary', 'accent', 'info', 'warning', 'error', 'success',
     'white', 'disabled', 'red', 'blue', 'green', 'orange', 'yellow',
@@ -148,6 +183,8 @@ export default class ZnIcon extends ZincElement {
       case "lucide":
       case "lu":
         return "lucide";
+      case "flag":
+        return "flag";
       case 'brand':
       case 'brands':
         return "brands";
@@ -191,6 +228,13 @@ export default class ZnIcon extends ZincElement {
         await super.getUpdateComplete();
       }
     }
+    if (this.library === 'flag' && !flagIcons) {
+      await loadFlagIcons();
+      if (flagIcons) {
+        this.requestUpdate();
+        await super.getUpdateComplete();
+      }
+    }
     return result;
   }
 
@@ -273,6 +317,26 @@ export default class ZnIcon extends ZincElement {
     return email.trim().toLowerCase();
   }
 
+  protected override updated(changedProperties: PropertyValues<this>) {
+    super.updated(changedProperties);
+    if (this.library === 'line') {
+      this.adoptLineIcons();
+    }
+  }
+
+  private adoptLineIcons() {
+    const root = this.shadowRoot;
+    if (!root || this._lineIconsAdopted) return;
+    this._lineIconsAdopted = true;
+    if (lineIcons.styleSheet) {
+      root.adoptedStyleSheets = [...root.adoptedStyleSheets, lineIcons.styleSheet];
+    } else {
+      const style = document.createElement('style');
+      style.textContent = lineIcons.cssText;
+      root.appendChild(style);
+    }
+  }
+
   render() {
     return html`
       <div class="icon-wrapper">
@@ -300,6 +364,9 @@ export default class ZnIcon extends ZincElement {
           'icon--pink': this.color === "pink",
           'icon--grey': this.color === "grey",
           'icon--avatar': this.library === "avatar",
+          'icon--avatar-solid': this.library === "avatar" && this.solid,
+          'icon--flag': this.library === "flag",
+          'icon--has-color': Boolean(this.color),
           'icon--padded': this.padded,
           'icon--blink': this.blink,
           'icon--squared': this.squared,
@@ -309,7 +376,7 @@ export default class ZnIcon extends ZincElement {
           '--icon-size': this.size + "px",
           '--icon-color': (this.color && !this.isPresetColor(this.color)) ? this.color : null,
           '--icon-fill': (this.fill && !this.isPresetColor(this.fill)) ? this.fill : null,
-          '--avatar-color': this.color ? null : (this.library === 'avatar' ? this.getColorForAvatar(this.getAvatarInitials(this.src)) : null)
+          '--avatar-color': this.color ? null : (this.library === 'avatar' ? this.getColorForAvatar(this.src) : null)
         })}">
           ${this.library && this.library !== "src" ? html`
             ${choose(this.library, [
@@ -321,12 +388,14 @@ export default class ZnIcon extends ZincElement {
               ["brands", () => html`<i part="icon" class="kb">${this.src}</i>`],
               ["line", () => html`<i part="icon" class="lni lni-${this.src}"></i>`],
               ["lucide", () => this.renderLucideIcon()],
+              ["flag", () => this.renderFlagIcon()],
               ["material-symbols-outlined", () => html`<i part="icon" class="mi mi--symbol-outlined">${this.src}</i>`],
               ["gravatar", () => html`<img part="icon" alt="${this.alt}"
                                            src="https://www.gravatar.com/avatar/${this.src}?s=${this.size}${this.gravatarOptions}"/>`],
               ["libravatar", () => html`<img part="icon" alt="${this.alt}"
                                              src="https://seccdn.libravatar.org/avatar/${this.src}?s=${this.size}${this.gravatarOptions}"/>`],
-              ["avatar", () => html`<span class="avatar__text">${this.getAvatarInitials(this.src)}</span>`]
+              ["avatar", () => html`<span class="avatar__text" role="img"
+                                          aria-label="${this.alt || this.src}">${this.getAvatarInitials(this.src)}</span>`]
             ], () => html`Library not supported: ${this.library}`)}` : ''}
 
           ${(!this.library || this.library === 'src') && this.src ? html`
@@ -336,7 +405,10 @@ export default class ZnIcon extends ZincElement {
           ${!this.library && !this.src ? html`
             <slot></slot>` : ''}
         </div>
-      </div>`;
+      </div>
+      ${this.presence ? html`
+        <span part="presence" class="presence presence--${this.presence}" role="img"
+              aria-label="${this.presence}"></span>` : ''}`;
   }
 
   private getAvatarInitials(avatar: string) {
@@ -376,6 +448,21 @@ export default class ZnIcon extends ZincElement {
     return unsafeSVG(this.getLucideSvg(icon));
   }
 
+  private renderFlagIcon() {
+    if (!flagIcons) {
+      void loadFlagIcons().then(() => {
+        if (flagIcons) {
+          this.requestUpdate();
+        }
+      });
+      return html``;
+    }
+
+    const code = (this.src ?? '').toUpperCase();
+    const svg = Object.prototype.hasOwnProperty.call(flagIcons, code) ? flagIcons[code] : undefined;
+    return svg ? html`<span part="icon" class="flag" role="img" aria-label="${this.alt || code}">${unsafeSVG(svg)}</span>` : html``;
+  }
+
   private getLucideIcon(src = ''): IconNode | undefined {
     if (!src) {
       return undefined;
@@ -438,17 +525,16 @@ export default class ZnIcon extends ZincElement {
   }
 
 
-  protected getColorForAvatar(avatarInitials: string) {
+  protected getColorForAvatar(name: string) {
     const colors = [
       '#00AA55', '#0882a8', '#ed55ed', '#5eae00',
       '#09389e', '#d17300', '#5e0be2', '#5b7a13',
       '#ddb100', '#d400c2', '#DC2A2A', '#a967ff',
     ];
 
-    // Generate a hash from the initials
-    const hash = Array.from(avatarInitials).reduce((acc, char) => acc + char.charCodeAt(0), 0);
+    // Order-sensitive, so names sharing initials or letters still spread across the palette
+    const hash = Array.from(name.trim().toLowerCase()).reduce((acc, char) => (acc * 31 + char.charCodeAt(0)) >>> 0, 0);
 
-    // Use the hash to select a color
     return colors[hash % colors.length];
   }
 }

package/src/components/icon/icon.scss

@@ -1,5 +1,4 @@
 @use "../../wc";
-@use "./lni";
 
 $icon-colors: (
   default: --zn-text,
@@ -30,6 +29,40 @@ $icon-colors: (
   --icon-color: inherit;
 }
 
+:host([presence]) {
+  position: relative;
+}
+
+// A live-status dot on the avatar's corner, ringed in the surface colour so it reads against the avatar.
+.presence {
+  position: absolute;
+  right: -1px;
+  bottom: -1px;
+  width: 28%;
+  height: 28%;
+  min-width: 7px;
+  min-height: 7px;
+  border: 2px solid var(--zn-avatar-ring-color, rgb(var(--zn-panel)));
+  border-radius: 50%;
+  background: rgb(var(--zn-color-disabled));
+
+  &--online {
+    background: rgb(var(--zn-color-success));
+  }
+
+  &--away {
+    background: rgb(var(--zn-color-warning));
+  }
+
+  &--busy {
+    background: rgb(var(--zn-color-error));
+  }
+
+  &--meeting {
+    background: rgb(var(--zn-primary));
+  }
+}
+
 :host([split-pane-focus]) .icon-wrapper {
   cursor: pointer;
 }
@@ -62,6 +95,19 @@ $icon-colors: (
     font-size: var(--icon-size) !important;
   }
 
+  &--flag {
+    display: inline-flex;
+    align-items: center;
+  }
+
+  .flag svg {
+    display: block;
+    width: var(--icon-size);
+    height: calc(var(--icon-size) * 2 / 3);
+    border-radius: 2px;
+    box-shadow: 0 0 0 1px rgb(0 0 0 / 0.08);
+  }
+
   // Colors
 
   &--default {
@@ -178,20 +224,38 @@ $icon-colors: (
     animation: blink-animation 1.5s steps(5, start) infinite;
   }
 
+  // Solid by default. A theme sets --zn-avatar-tint: 1 for a tinted circle with darker initials,
+  // and --zn-avatar-default-color to replace the per-name colour.
   &--avatar {
-    background-color: var(--avatar-color, var(--icon-color));
-    color: hsl(from var(--avatar-color, var(--icon-color)) h s 95);
+    --_avatar: var(--zn-avatar-default-color, var(--avatar-color));
+    --_tint: var(--zn-avatar-tint, 0);
+    --_solid-ink: hsl(from var(--_avatar) h s 95);
+    // Mixed towards the text colour so the initials stay readable in light and dark modes
+    --_tint-ink: color-mix(in srgb, var(--_avatar) 72%, rgb(var(--zn-text)));
+
+    // Mixed with the surface, not made translucent, so overlapping avatars in a group stay opaque
+    background-color: color-mix(in srgb, var(--_avatar) calc(100% - var(--_tint) * 86%), rgb(var(--zn-panel)));
+    color: color-mix(in srgb, var(--_tint-ink) calc(var(--_tint) * 100%), var(--_solid-ink));
     display: flex;
     justify-content: center;
     align-items: center;
 
     .avatar__text {
-      font-size: calc((var(--icon-size) / 2.4));
-      color: hsl(from var(--avatar-color, var(--icon-color)) h s 95);
-      font-weight: var(--zn-font-weight-semibold);
+      font-size: calc(var(--icon-size) * var(--zn-avatar-font-scale, 0.4167));
+      font-weight: var(--zn-avatar-font-weight, var(--zn-font-weight-semibold));
+      letter-spacing: .02em;
+      color: inherit;
     }
   }
 
+  &--avatar.icon--has-color {
+    --_avatar: var(--icon-color);
+  }
+
+  &--avatar.icon--avatar-solid {
+    --_tint: 0;
+  }
+
   &--padded {
     padding: var(--zn-spacing-small);
   }

package/src/components/icon/icon.test.ts

@@ -31,6 +31,19 @@ describe('<zn-icon>', () => {
     );
   });
 
+  it('should style Lineicons glyphs only on line icons', async () => {
+    const hasLineRules = (el: Element) =>
+      el.shadowRoot!.adoptedStyleSheets.some(sheet => Array.from(sheet.cssRules).some(rule => rule.cssText.includes(".lni-home-2")));
+
+    const line = await fixture<ZnIcon>(html`<zn-icon src="home-2" library="line"></zn-icon>`);
+    const glyph = line.shadowRoot!.querySelector('.lni')!;
+    expect(getComputedStyle(glyph, '::before').content).to.not.equal('none');
+    expect(hasLineRules(line)).to.be.true;
+
+    const lucide = await fixture<ZnIcon>(html`<zn-icon src="home@lu"></zn-icon>`);
+    expect(hasLineRules(lucide)).to.be.false;
+  });
+
   it('should render Lucide icons as inline SVGs', async () => {
     const el = await fixture<ZnIcon>(html`
       <zn-icon src="cloud-upload" library="lucide" size="48"></zn-icon>
@@ -55,6 +68,19 @@ describe('<zn-icon>', () => {
     expect(svg).to.exist;
   });
 
+  it('should render country flags from the flag library', async () => {
+    const el = await fixture<ZnIcon>(html`<zn-icon src="gb@flag" size="20"></zn-icon>`);
+
+    expect(el.library).to.equal('flag');
+    expect(el.shadowRoot?.querySelector('.flag[aria-label="GB"] svg')).to.exist;
+  });
+
+  it('should render nothing for an unknown flag', async () => {
+    const el = await fixture<ZnIcon>(html`<zn-icon src="zz@flag"></zn-icon>`);
+
+    expect(el.shadowRoot?.querySelector('.flag')).to.not.exist;
+  });
+
   it('should remove a matching library indicator from the icon src', async () => {
     const el = await fixture<ZnIcon>(html`
       <zn-icon src="home@lu" library="lucide" size="48"></zn-icon>
@@ -75,4 +101,33 @@ describe('<zn-icon>', () => {
     expect(el.library).to.equal('material-symbols-outlined');
     expect(el.src).to.equal('home@lu');
   });
+
+  it('should accept the named avatar sizes', async () => {
+    const el = await fixture<ZnIcon>(html`<zn-icon src="Fiona Hart" library="avatar" size="lg"></zn-icon>`);
+    expect(el.size).to.equal(40);
+    expect(el.shadowRoot!.querySelector<HTMLElement>('.icon')!.getBoundingClientRect().width).to.equal(40);
+  });
+
+  it('should still accept a size in pixels', async () => {
+    const el = await fixture<ZnIcon>(html`<zn-icon src="home" size="18"></zn-icon>`);
+    expect(el.size).to.equal(18);
+  });
+
+  it('should show a presence dot only when presence is set', async () => {
+    const el = await fixture<ZnIcon>(html`<zn-icon src="Ben Brooks" library="avatar" round></zn-icon>`);
+    expect(el.shadowRoot!.querySelector('[part="presence"]')).to.be.null;
+
+    el.presence = 'online';
+    await el.updateComplete;
+    const dot = el.shadowRoot!.querySelector('[part="presence"]')!;
+    expect(dot.classList.contains('presence--online')).to.be.true;
+    expect(dot.getAttribute('aria-label')).to.equal('online');
+  });
+
+  it('should name an avatar for assistive technology', async () => {
+    const el = await fixture<ZnIcon>(html`<zn-icon src="BB" alt="Ben Brooks" library="avatar"></zn-icon>`);
+    const text = el.shadowRoot!.querySelector('.avatar__text')!;
+    expect(text.getAttribute('role')).to.equal('img');
+    expect(text.getAttribute('aria-label')).to.equal('Ben Brooks');
+  });
 });

package/src/components/icon-picker/icon-picker.component.ts

@@ -60,6 +60,7 @@ export default class ZnIconPicker extends ZincElement implements ZincFormControl
   @state() private _searchQuery = '';
   @state() private _iconList: string[] = [];
   @state() private _filteredIcons: string[] = [];
+  @state() private _gridFocusIcon = '';
 
   // Pending selections (not committed until confirm)
   @state() private _pendingIcon = '';
@@ -280,6 +281,35 @@ export default class ZnIconPicker extends ZincElement implements ZincFormControl
 
   private handleIconSelect(iconName: string) {
     this._pendingIcon = iconName;
+    this._gridFocusIcon = iconName;
+  }
+
+  private _gridTabStop() {
+    if (this._filteredIcons.includes(this._gridFocusIcon)) return this._gridFocusIcon;
+    if (this._filteredIcons.includes(this._pendingIcon)) return this._pendingIcon;
+    return this._filteredIcons[0];
+  }
+
+  private _handleGridKeyDown(e: KeyboardEvent) {
+    const items = [...(e.currentTarget as HTMLElement).querySelectorAll<HTMLButtonElement>('.icon-picker__grid-item')];
+    const index = items.indexOf(e.target as HTMLButtonElement);
+    if (index === -1) return;
+
+    const columns = Math.max(1, items.filter(item => item.offsetTop === items[0].offsetTop).length);
+    let next: number;
+    switch (e.key) {
+      case 'ArrowRight': next = index + 1; break;
+      case 'ArrowLeft': next = index - 1; break;
+      case 'ArrowDown': next = index + columns; break;
+      case 'ArrowUp': next = index - columns; break;
+      case 'Home': next = 0; break;
+      case 'End': next = items.length - 1; break;
+      default: return;
+    }
+    e.preventDefault();
+    next = Math.max(0, Math.min(items.length - 1, next));
+    this._gridFocusIcon = this._filteredIcons[next];
+    items[next].focus();
   }
 
   private async handleLibraryChange(e: Event) {
@@ -326,6 +356,7 @@ export default class ZnIconPicker extends ZincElement implements ZincFormControl
   }
 
   private _handleTriggerKeyDown(e: KeyboardEvent) {
+    if (e.target !== e.currentTarget) return;
     if (e.key === 'Enter' || e.key === ' ') {
       e.preventDefault();
       this._handleTriggerClick();
@@ -340,6 +371,7 @@ export default class ZnIconPicker extends ZincElement implements ZincFormControl
     // auto-detection renders an <img> instead of a font ligature.
     const triggerIcon = this._fileUrl ?? this.icon;
     const triggerLibrary = hasValue && !this.isImageValue ? this.library : nothing;
+    const gridTabStop = this._gridTabStop();
     const pendingPreviewUrl = this._pendingFileUrl ?? (this.isImageValue && !this._file ? this.icon : this._fileUrl);
 
     return html`
@@ -503,7 +535,7 @@ export default class ZnIconPicker extends ZincElement implements ZincFormControl
                     <zn-icon slot="prefix" src="search" size="18"></zn-icon>
                   </zn-input>
 
-                  <div class="icon-picker__grid">
+                  <div class="icon-picker__grid" @keydown=${this._handleGridKeyDown}>
                     ${this._filteredIcons.length === 0 ? html`
                       <div class="icon-picker__no-results">No icons found</div>
                     ` : this._filteredIcons.map(iconName => html`
@@ -514,6 +546,8 @@ export default class ZnIconPicker extends ZincElement implements ZincFormControl
                           'icon-picker__grid-item--selected': iconName === this._pendingIcon
                         })}
                         title=${iconName}
+                        aria-pressed=${iconName === this._pendingIcon ? 'true' : 'false'}
+                        tabindex=${iconName === gridTabStop ? '0' : '-1'}
                         @click=${() => this.handleIconSelect(iconName)}>
                         <zn-icon
                           src=${iconName}