@dile/ui 3.18.5 → 3.19.1

package/components/list/src/DileListItem.js

@@ -0,0 +1,499 @@
+import { LitElement, html, css } from 'lit';
+import { ifDefined } from 'lit/directives/if-defined.js';
+import '@dile/iconlib/dile-iconlib.js';
+
+const HOST_FOCUS_ROLES = ['option', 'menuitem'];
+const INTERACTIVE_TAGS = ['button', 'input', 'select', 'textarea', 'a', 'label', 'summary', 'dile-list-item'];
+const INTERACTIVE_ROLES = ['button', 'link', 'checkbox', 'switch', 'radio', 'menuitem', 'option', 'tab', 'textbox'];
+
+export class DileListItem extends LitElement {
+  static get styles() {
+    return css`
+      :host {
+        display: block;
+        box-sizing: border-box;
+        outline: none;
+        --_padding-y: var(--dile-list-item-padding-y, 0.75rem);
+        --_padding-x: var(--dile-list-item-padding-x, 1rem);
+        --_gap: var(--dile-list-item-gap, 0.75rem);
+        --_align: center;
+        --_divider-border: var(--dile-list-item-divider-width, 1px) var(--dile-list-item-divider-style, solid) var(--dile-list-item-divider-color, #e5e7eb);
+      }
+
+      * {
+        box-sizing: border-box;
+      }
+
+      :host([density="compact"]) {
+        --_padding-y: var(--dile-list-item-padding-y, 0.375rem);
+        --_padding-x: var(--dile-list-item-padding-x, 0.75rem);
+        --_gap: var(--dile-list-item-gap, 0.5rem);
+      }
+
+      :host([density="comfortable"]) {
+        --_padding-y: var(--dile-list-item-padding-y, 0.75rem);
+        --_padding-x: var(--dile-list-item-padding-x, 1rem);
+        --_gap: var(--dile-list-item-gap, 0.75rem);
+      }
+
+      :host([density="spacious"]) {
+        --_padding-y: var(--dile-list-item-padding-y, 1.25rem);
+        --_padding-x: var(--dile-list-item-padding-x, 1.25rem);
+        --_gap: var(--dile-list-item-gap, 1rem);
+      }
+
+      :host([align="start"]) {
+        --_align: flex-start;
+      }
+
+      :host([align="center"]) {
+        --_align: center;
+      }
+
+      :host([align="end"]) {
+        --_align: flex-end;
+      }
+
+      :host([divider]:not([divider="inset"]):not([divider="none"])) {
+        border-bottom: var(--_divider-border);
+      }
+
+      .item {
+        display: flex;
+        box-sizing: border-box;
+        width: 100%;
+        margin: 0;
+        text-decoration: none;
+        color: var(--dile-list-item-color, inherit);
+        background-color: var(--dile-list-item-bg, transparent);
+        border-radius: var(--dile-list-item-border-radius, 4px);
+        padding-top: var(--_padding-y);
+        padding-bottom: var(--_padding-y);
+        padding-left: var(--_padding-x);
+        padding-right: var(--_padding-x);
+        gap: var(--_gap);
+        align-items: stretch;
+        transition-property: background-color, color, border-color, box-shadow;
+        transition-duration: var(--dile-list-item-transition-duration, 0.15s);
+        transition-timing-function: ease;
+        outline: none;
+      }
+
+      .item:focus-visible,
+      :host(:focus-visible) .item {
+        outline: var(--dile-list-item-focus-ring-width, 2px) solid var(--dile-list-item-focus-ring-color, #0284c7);
+        outline-offset: var(--dile-list-item-focus-ring-offset, -2px);
+      }
+
+      :host([clickable]:not([disabled])) .item,
+      :host([href]:not([href=""]):not([disabled])) .item {
+        cursor: pointer;
+        user-select: none;
+      }
+
+      :host([clickable]:not([disabled])) .item:hover,
+      :host([href]:not([href=""]):not([disabled])) .item:hover {
+        background-color: var(--dile-list-item-bg-hover, var(--dile-surface-hover-color, #f5f5f5));
+      }
+
+      :host([clickable]:not([disabled])) .item:active,
+      :host([href]:not([href=""]):not([disabled])) .item:active {
+        background-color: var(--dile-list-item-bg-active, var(--dile-surface-active-color, #ebebeb));
+      }
+
+      :host([selected]) .item {
+        background-color: var(--dile-list-item-bg-selected, #e0f2fe);
+        color: var(--dile-list-item-selected-text-color, var(--dile-primary-dark-color, #0369a1));
+      }
+
+      :host([disabled]) {
+        opacity: var(--dile-list-item-disabled-opacity, 0.5);
+        cursor: not-allowed;
+      }
+
+      :host([disabled]) .item {
+        pointer-events: none;
+      }
+
+      .prefix {
+        display: flex;
+        align-items: center;
+        justify-content: center;
+        flex-shrink: 0;
+        align-self: var(--dile-list-item-prefix-align, var(--_align));
+      }
+
+      .prefix[hidden],
+      .suffix[hidden] {
+        display: none !important;
+      }
+
+      .prefix dile-iconlib,
+      .suffix dile-iconlib {
+        --dile-icon-size: var(--dile-list-item-icon-size, 1.25rem);
+        --dile-icon-color: var(--dile-list-item-icon-color, currentColor);
+        display: flex;
+        align-items: center;
+        justify-content: center;
+      }
+
+      :host([selected]) .prefix dile-iconlib,
+      :host([selected]) .suffix dile-iconlib {
+        --dile-icon-color: var(--dile-list-item-selected-icon-color, var(--dile-list-item-selected-text-color, currentColor));
+      }
+
+      .content {
+        display: flex;
+        flex: 1 1 auto;
+        min-width: 0;
+        align-items: stretch;
+        gap: var(--_gap);
+      }
+
+      :host([divider="inset"]) .content {
+        border-bottom: var(--_divider-border);
+      }
+
+      .body {
+        flex: 1 1 auto;
+        min-width: 0;
+        align-self: center;
+        text-align: var(--dile-list-item-text-align, left);
+      }
+
+      :host([body-align="left"]) .body {
+        text-align: left;
+      }
+
+      :host([body-align="center"]) .body {
+        text-align: center;
+      }
+
+      :host([body-align="right"]) .body {
+        text-align: right;
+      }
+
+      .body ::slotted(p),
+      .body ::slotted(h1),
+      .body ::slotted(h2),
+      .body ::slotted(h3),
+      .body ::slotted(h4),
+      .body ::slotted(h5),
+      .body ::slotted(h6) {
+        margin-top: 0;
+        margin-bottom: 0;
+      }
+
+      :host([lines="1"]) .body {
+        display: -webkit-box;
+        -webkit-line-clamp: 1;
+        -webkit-box-orient: vertical;
+        overflow: hidden;
+        text-overflow: ellipsis;
+      }
+
+      :host([lines="2"]) .body {
+        display: -webkit-box;
+        -webkit-line-clamp: 2;
+        -webkit-box-orient: vertical;
+        overflow: hidden;
+        text-overflow: ellipsis;
+      }
+
+      :host([lines]:not([lines="1"]):not([lines="2"]):not([lines="auto"]):not([lines=""])) .body {
+        display: -webkit-box;
+        -webkit-line-clamp: var(--_lines, 1);
+        -webkit-box-orient: vertical;
+        overflow: hidden;
+        text-overflow: ellipsis;
+      }
+
+      .suffix {
+        display: flex;
+        align-items: center;
+        justify-content: center;
+        flex-shrink: 0;
+        align-self: var(--dile-list-item-suffix-align, var(--_align));
+      }
+    `;
+  }
+
+  static get properties() {
+    return {
+      /** Icon identifier in "family.name" format for prefix */
+      iconPrefix: { type: String, attribute: 'icon-prefix' },
+      /** Icon identifier in "family.name" format for suffix */
+      iconSuffix: { type: String, attribute: 'icon-suffix' },
+      /** Layout density: "compact", "comfortable", or "spacious". Unset behaves as "comfortable" */
+      density: { type: String, reflect: true },
+      /** Line clamping: "1", "2", "auto", or number. Unset behaves as "auto" */
+      lines: { type: String, reflect: true },
+      /** Vertical alignment of prefix and suffix: "center", "start", or "end". Unset behaves as "center" */
+      align: { type: String, reflect: true },
+      /** Text alignment of the body content: "left", "center", or "right". Unset uses --dile-list-item-text-align */
+      bodyAlign: { type: String, attribute: 'body-align', reflect: true },
+      /** Bottom separator: boolean attribute (full), "full", "inset" or "none". Unset means no divider */
+      divider: { type: String, reflect: true },
+      /** Whether item is interactive */
+      clickable: { type: Boolean, reflect: true },
+      /** Navigation URL */
+      href: { type: String, reflect: true },
+      /** Link target */
+      target: { type: String, reflect: true },
+      /** Disabled state */
+      disabled: { type: Boolean, reflect: true },
+      /** Selected state */
+      selected: { type: Boolean, reflect: true },
+      /** Expanded state */
+      expanded: { type: Boolean, reflect: true },
+      /** Value associated with the item */
+      value: { type: String, reflect: true },
+      /** Tabindex for roving tabindex control */
+      itemTabindex: { type: Number, attribute: 'item-tabindex' },
+      /** Mirrors the host role attribute so the template reacts to role changes */
+      _hostRole: { attribute: 'role' },
+      /** Internal slot states */
+      _hasPrefixSlot: { state: true },
+      _hasSuffixSlot: { state: true },
+    };
+  }
+
+  constructor() {
+    super();
+    this.clickable = false;
+    this.disabled = false;
+    this.selected = false;
+    this.itemTabindex = 0;
+    this._hasPrefixSlot = false;
+    this._hasSuffixSlot = false;
+    this._managesHostAria = false;
+
+    this._handleKeyDown = this._handleKeyDown.bind(this);
+    this._handleKeyUp = this._handleKeyUp.bind(this);
+    this.addEventListener('keydown', this._handleKeyDown);
+    this.addEventListener('keyup', this._handleKeyUp);
+  }
+
+  connectedCallback() {
+    super.connectedCallback();
+    if (!this.hasAttribute('role')) {
+      this.setAttribute('role', 'listitem');
+    }
+    this._checkLightDomSlots();
+  }
+
+  updated(changedProperties) {
+    super.updated(changedProperties);
+    if (changedProperties.has('lines')) {
+      if (this.lines && this.lines !== 'auto' && this.lines !== '1' && this.lines !== '2') {
+        this.style.setProperty('--_lines', String(this.lines));
+      } else {
+        this.style.removeProperty('--_lines');
+      }
+    }
+    this._syncHostAria();
+  }
+
+  /** When the host acts as an option / menuitem it is the focusable, ARIA-bearing element. */
+  _isHostFocusMode() {
+    return HOST_FOCUS_ROLES.includes(this._hostRole);
+  }
+
+  _isInteractive() {
+    return Boolean(this.clickable || this.href || this._isHostFocusMode());
+  }
+
+  _computedTabindex() {
+    if (this.disabled) return -1;
+    return this.itemTabindex !== undefined && this.itemTabindex !== null ? this.itemTabindex : 0;
+  }
+
+  _expandedValue() {
+    return this.expanded !== undefined ? String(Boolean(this.expanded)) : undefined;
+  }
+
+  _syncHostAria() {
+    if (this._isHostFocusMode()) {
+      this.setAttribute('tabindex', String(this._computedTabindex()));
+      if (this._hostRole === 'option') {
+        this.setAttribute('aria-selected', this.selected ? 'true' : 'false');
+      } else {
+        this.removeAttribute('aria-selected');
+      }
+      this._toggleHostAttribute('aria-disabled', this.disabled ? 'true' : undefined);
+      this._toggleHostAttribute('aria-expanded', this._expandedValue());
+      this._managesHostAria = true;
+    } else if (this._managesHostAria) {
+      ['tabindex', 'aria-selected', 'aria-disabled', 'aria-expanded'].forEach((attr) => this.removeAttribute(attr));
+      this._managesHostAria = false;
+    }
+  }
+
+  _toggleHostAttribute(name, value) {
+    if (value === undefined) {
+      this.removeAttribute(name);
+    } else {
+      this.setAttribute(name, value);
+    }
+  }
+
+  _checkLightDomSlots() {
+    this._hasPrefixSlot = Boolean(this.querySelector(':scope > [slot="prefix"], :scope > [slot="leading"]'));
+    this._hasSuffixSlot = Boolean(this.querySelector(':scope > [slot="suffix"], :scope > [slot="trailing"]'));
+  }
+
+  _handleSlotChange() {
+    this._checkLightDomSlots();
+  }
+
+  focus(options) {
+    if (this._isHostFocusMode()) {
+      super.focus(options);
+      return;
+    }
+    const target = this.shadowRoot?.querySelector('.item');
+    if (target) {
+      target.focus(options);
+    } else {
+      super.focus(options);
+    }
+  }
+
+  render() {
+    const hasPrefix = Boolean(this._hasPrefixSlot || this.iconPrefix);
+    const hasSuffix = Boolean(this._hasSuffixSlot || this.iconSuffix);
+    const hostFocus = this._isHostFocusMode();
+    // The inner element carries focus and ARIA state unless the host is an option / menuitem.
+    const innerFocusable = this._isInteractive() && !hostFocus;
+    const tabindex = this._computedTabindex();
+    const innerDisabled = ifDefined(innerFocusable && this.disabled ? 'true' : undefined);
+    const innerCurrent = ifDefined(innerFocusable && this.selected ? 'true' : undefined);
+    const innerExpanded = ifDefined(innerFocusable ? this._expandedValue() : undefined);
+
+    const contentTemplate = html`
+      <div class="prefix" part="prefix" ?hidden="${!hasPrefix}">
+        <slot name="prefix" @slotchange="${this._handleSlotChange}"><slot name="leading" @slotchange="${this._handleSlotChange}">${this.iconPrefix ? html`<dile-iconlib icon="${this.iconPrefix}" aria-hidden="true"></dile-iconlib>` : ''}</slot></slot>
+      </div>
+      <div class="content" part="content">
+        <div class="body" part="body">
+          <slot></slot>
+        </div>
+        <div class="suffix" part="suffix" ?hidden="${!hasSuffix}">
+          <slot name="suffix" @slotchange="${this._handleSlotChange}"><slot name="trailing" @slotchange="${this._handleSlotChange}">${this.iconSuffix ? html`<dile-iconlib icon="${this.iconSuffix}" aria-hidden="true"></dile-iconlib>` : ''}</slot></slot>
+        </div>
+      </div>
+    `;
+
+    if (this.href) {
+      return html`
+        <a
+          class="item"
+          part="item"
+          href="${ifDefined(this.disabled ? undefined : this.href)}"
+          target="${ifDefined(this.target || undefined)}"
+          rel="${ifDefined(this.target === '_blank' ? 'noopener noreferrer' : undefined)}"
+          tabindex="${hostFocus ? -1 : tabindex}"
+          aria-disabled="${innerDisabled}"
+          aria-current="${innerCurrent}"
+          aria-expanded="${innerExpanded}"
+          @click="${this._handleItemClick}"
+        >${contentTemplate}</a>
+      `;
+    }
+
+    return html`
+      <div
+        class="item"
+        part="item"
+        role="${ifDefined(innerFocusable ? 'button' : undefined)}"
+        tabindex="${ifDefined(innerFocusable ? tabindex : undefined)}"
+        aria-disabled="${innerDisabled}"
+        aria-current="${innerCurrent}"
+        aria-expanded="${innerExpanded}"
+        @click="${this._handleItemClick}"
+      >${contentTemplate}</div>
+    `;
+  }
+
+  /**
+   * Returns true when the event started on an interactive control placed inside the item
+   * (slotted buttons, inputs, links, nested list items...). Those controls own their events.
+   */
+  _isFromNestedControl(e) {
+    const stop = this.shadowRoot.querySelector('.item');
+    for (const el of e.composedPath()) {
+      if (el === stop || el === this) return false;
+      if (!(el instanceof Element)) continue;
+      const tag = el.localName;
+      const role = el.getAttribute('role');
+      if (
+        INTERACTIVE_TAGS.includes(tag) ||
+        INTERACTIVE_ROLES.includes(role) ||
+        el.isContentEditable ||
+        (el.hasAttribute('tabindex') && el.tabIndex >= 0)
+      ) {
+        return true;
+      }
+    }
+    return false;
+  }
+
+  /** True when the event originated on the item's own focus target (host or inner .item). */
+  _isOwnFocusTarget(e) {
+    const origin = e.composedPath()[0];
+    return origin === this || origin === this.shadowRoot?.querySelector('.item');
+  }
+
+  _handleItemClick(e) {
+    if (!this._isInteractive()) return;
+    if (this.disabled) {
+      e.preventDefault();
+      e.stopPropagation();
+      return;
+    }
+    if (this._isFromNestedControl(e)) return;
+    this._dispatchItemClick();
+  }
+
+  _dispatchItemClick() {
+    this.dispatchEvent(new CustomEvent('dile-list-item-click', {
+      bubbles: true,
+      composed: true,
+      detail: {
+        item: this,
+        value: this.value,
+        href: this.href,
+        selected: this.selected,
+      }
+    }));
+  }
+
+  _handleKeyDown(e) {
+    if (this.disabled || !this._isInteractive() || !this._isOwnFocusTarget(e)) return;
+    if (e.key === 'Enter') {
+      if (!this.href) {
+        e.preventDefault();
+        this._dispatchItemClick();
+      } else if (e.composedPath()[0] === this) {
+        // Host has focus (option / menuitem mode): the native anchor won't receive the Enter key.
+        e.preventDefault();
+        this.shadowRoot.querySelector('a')?.click();
+      }
+    } else if (e.key === ' ') {
+      // Prevent the page from scrolling; activation happens on keyup (button behaviour).
+      e.preventDefault();
+    }
+  }
+
+  _handleKeyUp(e) {
+    if (this.disabled || !this._isInteractive() || !this._isOwnFocusTarget(e)) return;
+    if (e.key === ' ') {
+      e.preventDefault();
+      if (this.href) {
+        this.shadowRoot.querySelector('a')?.click();
+      } else {
+        this._dispatchItemClick();
+      }
+    }
+  }
+}

package/components/select/src/DileSelect.js

@@ -97,6 +97,8 @@ export class DileSelect extends DileEmmitChange(LitElement) {
   static get properties() {
     return {
       label: { type: String },
+      /** Accessible name of the slotted select when there is no visible label. With label, the label text is used */
+      accessibleLabel: { type: String },
       value: { type: String },
       name: { type: String, reflect: true },
       disabled: { type: Boolean },
@@ -114,7 +116,7 @@ export class DileSelect extends DileEmmitChange(LitElement) {
     return html`
       <div>
         ${this.label
-          ? html`<label for="${this.selectId}">${this.label}</label>`
+          ? html`<label for="${this.selectId}" @click="${this._focusSelect}">${this.label}</label>`
           : ""
         }
         <div class="select-wrapper">
@@ -159,6 +161,11 @@ export class DileSelect extends DileEmmitChange(LitElement) {
       if (!this.elselect.id) {
         this.elselect.id = this.selectId;
       }
+      // aria-label / aria-description set by the author on the slotted select always win
+      if (this._authorAriaLabel === undefined) {
+        this._authorAriaLabel = this.elselect.hasAttribute("aria-label");
+        this._authorAriaDescription = this.elselect.hasAttribute("aria-description");
+      }
       this.elselect.addEventListener("change", this.changeHandler);
       this.updateSelectA11y();
     }
@@ -194,7 +201,8 @@ export class DileSelect extends DileEmmitChange(LitElement) {
       this.elselect.classList.toggle("disabled", this.disabled);
       this.elselect.setAttribute("aria-disabled", this.disabled);
     }
-    if(changedProperties.has("errored") || changedProperties.has("message")) {
+    if(changedProperties.has("errored") || changedProperties.has("message")
+      || changedProperties.has("label") || changedProperties.has("accessibleLabel")) {
       this.updateSelectA11y();
     }
   }
@@ -205,18 +213,39 @@ export class DileSelect extends DileEmmitChange(LitElement) {
     // Set aria-invalid when errored
     this.elselect.setAttribute("aria-invalid", this.errored);
     
-    // Set aria-describedby when message exists
-    const messageId = this.message ? `${this.selectId}-message` : null;
-    if (messageId) {
-      this.elselect.setAttribute("aria-describedby", messageId);
-    } else {
-      this.elselect.removeAttribute("aria-describedby");
+    // The message lives in the shadow DOM and the select in the light DOM, so an
+    // aria-describedby id reference cannot cross the boundary: use aria-description.
+    // aria-describedby is left to the author (e.g. help text in the light DOM).
+    if (!this._authorAriaDescription) {
+      if (this.message) {
+        this.elselect.setAttribute("aria-description", this.message);
+      } else {
+        this.elselect.removeAttribute("aria-description");
+      }
     }
     
+    // Accessible name. The <label for> lives in the shadow DOM and the select in the
+    // light DOM, so "for" cannot cross the boundary: name the select via aria-label.
+    if (!this._authorAriaLabel) {
+      const accessibleName = this.label || this.accessibleLabel;
+      if (accessibleName) {
+        this.elselect.setAttribute("aria-label", accessibleName);
+      } else {
+        this.elselect.removeAttribute("aria-label");
+      }
+    }
+
     // Update visual state
     this.elselect.classList.toggle("errored", this.errored);
   }
 
+  // <label for> cannot reach the slotted select, so replicate the native label click
+  _focusSelect() {
+    if (this.elselect && !this.disabled) {
+      this.elselect.focus();
+    }
+  }
+
   firstUpdated() {
     this.quiet = this.quietOnStart;
     if(this.value) {

package/components/select/src/DileSelectOverlay.js

@@ -150,6 +150,11 @@ export class DileSelectOverlay extends DileOverlay(DileCloseDocumentClick(DileEm
       .option[aria-selected="true"] {
         font-weight: var(--dile-select-overlay-selected-font-weight, 600);
       }
+      .option-content {
+        display: block;
+        flex: 1 1 auto;
+        min-width: 0;
+      }
       @media (forced-colors: active) {
         #trigger {
           border-width: var(--dile-input-border-width, 1px);
@@ -172,6 +177,8 @@ export class DileSelectOverlay extends DileOverlay(DileCloseDocumentClick(DileEm
   static get properties() {
     return {
       label: { type: String },
+      /** Accessible name of the combobox trigger and the listbox, applied as aria-label only when there is no visible label */
+      accessibleLabel: { type: String },
       value: { type: String },
       name: { type: String, reflect: true },
       disabled: { type: Boolean },
@@ -185,6 +192,12 @@ export class DileSelectOverlay extends DileOverlay(DileCloseDocumentClick(DileEm
       /** Suppresses the visible trigger box, letting a parent component drive open()/close()
        *  and forward keyboard events via handleExternalKeydown() while supplying its own visible control. */
       hideTrigger: { type: Boolean, reflect: true },
+      /** Optional custom renderer for the content of each option in the popup:
+       *  `(option, index) => TemplateResult | string`, where `option` is `{ value, text, icon, element }`
+       *  and `element` is the native <option> (useful to read its dataset). The <li role="option">
+       *  itself (ids, aria-selected, highlight, click) is still managed by the component, and the
+       *  trigger, typeahead, accessible name and highlightedText keep using the plain option text. */
+      optionRenderer: { attribute: false },
       _activeIndex: { state: true },
       /** Display text of the currently highlighted option, readable by an external composer. */
       highlightedText: { state: true },
@@ -218,7 +231,7 @@ export class DileSelectOverlay extends DileOverlay(DileCloseDocumentClick(DileEm
 
   get options() {
     return this.elselect
-      ? Array.from(this.elselect.options).map(o => ({ value: o.value, text: o.textContent, icon: o.dataset.icon || this.elselect.dataset.icon }))
+      ? Array.from(this.elselect.options).map(o => ({ value: o.value, text: o.textContent, icon: o.dataset.icon || this.elselect.dataset.icon, element: o }))
       : [];
   }
 
@@ -325,6 +338,11 @@ export class DileSelectOverlay extends DileOverlay(DileCloseDocumentClick(DileEm
     `;
   }
 
+  /** aria-label for the trigger and the listbox: accessibleLabel, only when there is no visible label */
+  get controlAriaLabel() {
+    return !this.label && this.accessibleLabel ? this.accessibleLabel : undefined;
+  }
+
   get triggerTemplate() {
     const selected = this.selectedOption;
     return html`
@@ -332,6 +350,7 @@ export class DileSelectOverlay extends DileOverlay(DileCloseDocumentClick(DileEm
         type="button"
         id="trigger"
         role="combobox"
+        aria-label="${ifDefined(this.controlAriaLabel)}"
         aria-haspopup="listbox"
         aria-expanded="${this.opened}"
         aria-controls="overlay"
@@ -360,21 +379,36 @@ export class DileSelectOverlay extends DileOverlay(DileCloseDocumentClick(DileEm
   get overlayTemplate() {
     const options = this.options;
     return html`
-      <ul id="overlay" class="${this._overlayClass}" role="listbox">
-        ${options.map((opt, index) => html`
+      <ul id="overlay" class="${this._overlayClass}" role="listbox" aria-label="${ifDefined(this.controlAriaLabel)}">
+        ${options.map((opt, index) => {
+          const highlighted = index === this._activeIndex;
+          const selected = opt.value === (this.value ?? '');
+          const parts = ['option', highlighted ? 'option-highlighted' : '', selected ? 'option-selected' : ''].filter(Boolean).join(' ');
+          return html`
           <li
             id="${this._optionId(index)}"
             role="option"
-            class="option ${index === this._activeIndex ? 'highlighted' : ''}"
-            aria-selected="${opt.value === (this.value ?? '')}"
+            part="${parts}"
+            class="option ${highlighted ? 'highlighted' : ''}"
+            aria-selected="${selected}"
+            aria-label="${ifDefined(this.optionRenderer ? opt.text.trim() : undefined)}"
             @click="${() => this.selectOption(index)}"
             @mousemove="${() => this._setActiveIndex(index, false)}"
-          >${opt.icon ? html`<span class="option-icon">${this.renderIconlibIcon(opt.icon)}</span>` : ''}${opt.text}</li>
-        `)}
+          >${this.optionContentTemplate(opt, index)}</li>
+        `;
+        })}
       </ul>
     `;
   }
 
+  /** Content of each <li role="option">: optionRenderer's output when set, icon + text otherwise. */
+  optionContentTemplate(opt, index) {
+    if (typeof this.optionRenderer === 'function') {
+      return html`<span class="option-content" part="option-content">${this.optionRenderer(opt, index)}</span>`;
+    }
+    return html`${opt.icon ? html`<span class="option-icon">${this.renderIconlibIcon(opt.icon)}</span>` : ''}${opt.text}`;
+  }
+
   renderIconlibIcon(icon) {
     const dotIndex = icon.indexOf('.');
     if (dotIndex === -1) {