@eunomia/elements 1.0.0-beta.6 → 1.0.0-beta.8

package/dist/ssr/toggle-group-ssr.css

@@ -0,0 +1,233 @@
+eun-toggle-group:not(:defined) {
+  --_toggleRadius: var(
+    --toggle-group-border-radius,
+    var(--eun-border-radius-m, 8px)
+  );
+  --_toggleFontSize: var(--eun-font-size-s, 14px);
+  --_toggleButtonPaddingBlock: var(--eun-space-s, 8px);
+  --_toggleOptionPaddingInline: calc(var(--eun-space-l, 32px) / 2);
+  --_toggleLineHeight: 1rem;
+  --_trackPaddingBlock: var(
+    --toggle-group-padding,
+    var(
+      --toggle-group-padding-block,
+      calc(var(--_toggleButtonPaddingBlock) / 2)
+    )
+  );
+  --_toggleOptionPaddingBlock: max(
+    0px,
+    calc(var(--_toggleButtonPaddingBlock) - var(--_trackPaddingBlock))
+  );
+  display: inline-flex;
+  box-sizing: border-box;
+  width: fit-content;
+  max-width: 100%;
+  gap: var(--toggle-group-gap, var(--eun-space-xs, 4px));
+  padding: var(--_trackPaddingBlock)
+    var(--toggle-group-padding, var(--toggle-group-padding-inline, 4px));
+  overflow: hidden;
+  border-radius: var(--_toggleRadius);
+  background: var(
+    --toggle-group-background,
+    var(--eun-surface-sunken, #f7f8fa)
+  );
+  border: var(--eun-border-width-s, 1px) solid
+    var(--toggle-group-border-color, var(--eun-color-grey-300, #dee0e7));
+  box-shadow: var(--toggle-group-box-shadow, none);
+  font-family: var(--eun-font-family, "Mulish", sans-serif);
+  font-size: var(--_toggleFontSize);
+}
+
+eun-toggle-group[rounded]:not(:defined) {
+  --_toggleRadius: var(
+    --toggle-group-border-radius,
+    var(--eun-border-radius-xl, 999px)
+  );
+}
+
+eun-toggle-group[size="xs"]:not(:defined) {
+  --_toggleFontSize: var(--eun-font-size-xs, 10px);
+  --_toggleButtonPaddingBlock: var(--eun-space-xxs, 1.6px);
+  --_toggleOptionPaddingInline: var(--eun-space-xs, 4px);
+  --_toggleLineHeight: 10px;
+}
+
+eun-toggle-group[size="s"]:not(:defined) {
+  --_toggleFontSize: var(--eun-font-size-xs, 10px);
+  --_toggleButtonPaddingBlock: calc(var(--eun-space-s, 8px) / 2);
+  --_toggleOptionPaddingInline: var(--eun-space-s, 8px);
+  --_toggleLineHeight: 10px;
+}
+
+eun-toggle-group[size="l"]:not(:defined) {
+  --_toggleFontSize: var(--eun-font-size-m, 16px);
+  --_toggleButtonPaddingBlock: calc(var(--eun-space-s, 8px) * 1.25);
+  --_toggleOptionPaddingInline: calc(var(--eun-space-m, 16px) * 1.25);
+  --_toggleLineHeight: 1.1rem;
+}
+
+eun-toggle-group[size="xl"]:not(:defined) {
+  --_toggleFontSize: var(--eun-font-size-l, 1.3rem);
+  --_toggleButtonPaddingBlock: calc(var(--eun-space-s, 8px) * 1.5);
+  --_toggleOptionPaddingInline: calc(var(--eun-space-m, 16px) * 1.5);
+  --_toggleLineHeight: 1.3rem;
+}
+
+eun-toggle-group:is([appearance="outline"], [appearance="flat"]):not(:defined) {
+  --_toggleOptionPaddingBlock: var(--_toggleButtonPaddingBlock);
+  padding: 0;
+  overflow: visible;
+  background: var(--toggle-group-background, transparent);
+  border: none;
+  border-radius: 0;
+}
+
+eun-toggle-group[full]:not(:defined) {
+  display: flex;
+  width: 100%;
+}
+
+eun-toggle-group[disabled]:not(:defined) {
+  opacity: 0.5;
+}
+
+eun-toggle-item:not(:defined) {
+  display: inline-flex;
+  flex-shrink: 0;
+  align-items: center;
+  gap: var(--eun-space-xs, 4px);
+  box-sizing: border-box;
+  padding: var(--_toggleOptionPaddingBlock, calc(var(--eun-space-s, 8px) / 2))
+    var(--_toggleOptionPaddingInline, calc(var(--eun-space-l, 32px) / 2));
+  border-radius: calc(
+    var(--_toggleRadius, var(--eun-border-radius-m, 8px)) - 3px
+  );
+  color: var(--toggle-group-color, var(--eun-color-grey-600, #666e8a));
+  font-family: var(--eun-font-family, "Mulish", sans-serif);
+  font-size: var(--_toggleFontSize, var(--eun-font-size-s, 14px));
+  line-height: var(--_toggleLineHeight, 1rem);
+  font-weight: var(--eun-font-weight-m, 500);
+  white-space: nowrap;
+  --_customTint: color-mix(
+    in srgb,
+    var(--toggle-group-active-background) 15%,
+    transparent
+  );
+}
+
+eun-toggle-item:not(:defined) > [slot="icon"] {
+  order: -1;
+}
+
+:is(
+  eun-toggle-group:is([appearance="outline"], [appearance="flat"])
+    > eun-toggle-item,
+  eun-toggle-item:is([appearance="outline"], [appearance="flat"])
+):not(:defined) {
+  border: var(--eun-border-width-s, 1px) solid
+    var(--toggle-group-border-color, transparent);
+  border-radius: var(--_toggleRadius, var(--eun-border-radius-m, 8px));
+}
+
+:is(
+  eun-toggle-group[appearance="outline"] > eun-toggle-item,
+  eun-toggle-item[appearance="outline"]
+):not(:defined) {
+  border-color: var(
+    --toggle-group-border-color,
+    var(--eun-color-grey-300, #dee0e7)
+  );
+}
+
+:is(eun-toggle-group[full] > eun-toggle-item, eun-toggle-item[full]):not(
+  :defined
+) {
+  flex: 1 1 0%;
+  justify-content: center;
+}
+
+:is(
+  eun-toggle-group:not(
+      [single],
+      :has(> eun-toggle-item:nth-of-type(2):last-of-type)
+    )
+    > eun-toggle-item[checked],
+  eun-toggle-group:is(
+      [single],
+      :has(> eun-toggle-item:nth-of-type(2):last-of-type)
+    )
+    > eun-toggle-item:nth-child(1 of [checked]),
+  eun-toggle-group:is(
+      [single],
+      :has(> eun-toggle-item:nth-of-type(2):last-of-type)
+    ):not([value], :has(> eun-toggle-item[checked]))
+    > eun-toggle-item:first-of-type
+):not(:defined) {
+  background: var(
+    --toggle-group-active-background,
+    var(--eun-color-primary-500, #3d6fff)
+  );
+  color: var(
+    --toggle-group-active-color,
+    var(--eun-color-on-primary-500, #ffffff)
+  );
+}
+
+:is(
+    eun-toggle-group:not(
+        [single],
+        :has(> eun-toggle-item:nth-of-type(2):last-of-type)
+      )
+      > eun-toggle-item[checked],
+    eun-toggle-group:is(
+        [single],
+        :has(> eun-toggle-item:nth-of-type(2):last-of-type)
+      )
+      > eun-toggle-item:nth-child(1 of [checked]),
+    eun-toggle-group:is(
+        [single],
+        :has(> eun-toggle-item:nth-of-type(2):last-of-type)
+      ):not([value], :has(> eun-toggle-item[checked]))
+      > eun-toggle-item:first-of-type
+  ):is(
+    eun-toggle-group:is([appearance="outline"], [appearance="flat"])
+      > eun-toggle-item,
+    eun-toggle-item:is([appearance="outline"], [appearance="flat"])
+  ):not(:defined) {
+  background: var(--_customTint, var(--eun-color-primary-alpha-20, #3d6fff33));
+  color: var(
+    --toggle-group-active-color,
+    var(--toggle-group-active-background, var(--eun-color-primary-500, #3d6fff))
+  );
+  font-weight: var(--eun-font-weight-b, 700);
+}
+
+:is(
+    eun-toggle-group:not(
+        [single],
+        :has(> eun-toggle-item:nth-of-type(2):last-of-type)
+      )
+      > eun-toggle-item[checked],
+    eun-toggle-group:is(
+        [single],
+        :has(> eun-toggle-item:nth-of-type(2):last-of-type)
+      )
+      > eun-toggle-item:nth-child(1 of [checked]),
+    eun-toggle-group:is(
+        [single],
+        :has(> eun-toggle-item:nth-of-type(2):last-of-type)
+      ):not([value], :has(> eun-toggle-item[checked]))
+      > eun-toggle-item:first-of-type
+  ):is(
+    eun-toggle-group[appearance="outline"] > eun-toggle-item,
+    eun-toggle-item[appearance="outline"]
+  ):not(:defined) {
+  border-color: var(
+    --toggle-group-active-background,
+    var(--eun-color-primary-500, #3d6fff)
+  );
+}
+
+eun-toggle-item[disabled]:not(:defined) {
+  opacity: 0.5;
+}

package/dist/ssr/toolbar-ssr.css

@@ -14,12 +14,41 @@ eun-toolbar:not(:defined) {
   height: var(--toolbar-height, 72px);
   padding: var(
     --toolbar-padding,
-    var(--toolbar-padding-block, 0)
-      var(--toolbar-padding-inline, 24px)
+    var(--toolbar-padding-block, 0) var(--toolbar-padding-inline, 24px)
   );
   position: sticky;
   top: 0;
   z-index: var(--toolbar-z-index, 100);
+  font-family: var(--eun-font-family, "Mulish", sans-serif);
+  background: var(
+    --toolbar-background,
+    var(--toolbar-background-light, var(--eun-surface-color, #ffffff))
+  );
+  color: var(
+    --toolbar-color,
+    var(--toolbar-color-light, var(--eun-text-color, #071621))
+  );
+  border-block-end: var(--eun-border-width-s, 1px) solid
+    var(--toolbar-border-color, var(--eun-border-color, #dee0e7));
+  box-shadow: var(--toolbar-shadow, none);
+}
+
+eun-toolbar[theme="dark"]:not(:defined) {
+  background: var(
+    --toolbar-background,
+    var(--toolbar-background-dark, var(--eun-surface-inverse, #0b1620))
+  );
+  color: var(
+    --toolbar-color,
+    var(--toolbar-color-dark, var(--eun-text-on-inverse, #f5f7fa))
+  );
+}
+
+/* A page loads scrolled to the top, where the upgraded bar is transparent. */
+eun-toolbar[transparent-at-top]:not(:defined) {
+  background: transparent;
+  border-color: transparent;
+  box-shadow: none;
 }
 
 eun-toolbar[position="fixed"]:not(:defined) {
@@ -77,3 +106,53 @@ eun-toolbar:not(:defined):where(
   align-items: center;
   justify-content: flex-end;
 }
+
+@media (width < 600px) {
+  eun-toolbar[mobile-breakpoint="600"][mobile-hide~="start"]:not(:defined)
+    > [slot="start"],
+  eun-toolbar[mobile-breakpoint="600"][mobile-hide~="center"]:not(:defined)
+    > [slot="center"],
+  eun-toolbar[mobile-breakpoint="600"][mobile-hide~="end"]:not(:defined)
+    > [slot="end"] {
+    display: none;
+  }
+}
+
+@media (width < 768px) {
+  eun-toolbar:not([mobile-breakpoint])[mobile-hide~="start"]:not(:defined)
+    > [slot="start"],
+  eun-toolbar:not([mobile-breakpoint])[mobile-hide~="center"]:not(:defined)
+    > [slot="center"],
+  eun-toolbar:not([mobile-breakpoint])[mobile-hide~="end"]:not(:defined)
+    > [slot="end"],
+  eun-toolbar[mobile-breakpoint="768"][mobile-hide~="start"]:not(:defined)
+    > [slot="start"],
+  eun-toolbar[mobile-breakpoint="768"][mobile-hide~="center"]:not(:defined)
+    > [slot="center"],
+  eun-toolbar[mobile-breakpoint="768"][mobile-hide~="end"]:not(:defined)
+    > [slot="end"] {
+    display: none;
+  }
+}
+
+@media (width < 1024px) {
+  eun-toolbar[mobile-breakpoint="1024"][mobile-hide~="start"]:not(:defined)
+    > [slot="start"],
+  eun-toolbar[mobile-breakpoint="1024"][mobile-hide~="center"]:not(:defined)
+    > [slot="center"],
+  eun-toolbar[mobile-breakpoint="1024"][mobile-hide~="end"]:not(:defined)
+    > [slot="end"] {
+    display: none;
+  }
+}
+
+@media (width < 1280px) {
+  eun-toolbar[mobile-breakpoint="1280"][mobile-hide~="start"]:not(:defined)
+    > [slot="start"],
+  eun-toolbar[mobile-breakpoint="1280"][mobile-hide~="center"]:not(:defined)
+    > [slot="center"],
+  eun-toolbar[mobile-breakpoint="1280"][mobile-hide~="end"]:not(:defined)
+    > [slot="end"] {
+    display: none;
+  }
+}

package/dist/types/variant.type.d.ts

@@ -55,6 +55,9 @@ export type EunomiaModalConfirmColor = Extract<EunomiaActionColor, "primary" | "
  * (elevated, drop shadow) doesn't share that constraint : it's a static
  * effect, not one gated behind interaction, so `eun-card` also exposes it
  * (see {@link EunomiaCardAppearance}) despite being a passive container.
+ * Button-family components spell that pale tinted wash `soft` instead of
+ * `default`, since their own default is `fill` : `appearance="default"`
+ * on a button would otherwise not render the default.
  * `underline` (a bottom border only) is a form field's own look, and
  * `transparent` (the pale tint, see-through instead of opaque) a scheduler
  * event chip's : each belongs to a single family, like `ghost`.
@@ -64,7 +67,7 @@ export type EunomiaModalConfirmColor = Extract<EunomiaActionColor, "primary" | "
  * (a loader's dots or bar, a skeleton's shape) is a `variant` instead,
  * with values of its own that mean nothing outside that component.
  */
-export type EunomiaAppearance = "default" | "fill" | "outline" | "flat" | "raised" | "ghost" | "underline" | "transparent";
+export type EunomiaAppearance = "default" | "soft" | "fill" | "outline" | "flat" | "raised" | "ghost" | "underline" | "transparent";
 /**
  * The four-value {@link EunomiaAppearance} subset feedback/display components
  * (alert, toast, chip, tag, tooltip) actually use — no `raised`/`ghost`,

package/dist/utils/boolean.utils.d.ts

@@ -0,0 +1,14 @@
+import type { ComplexAttributeConverter } from "lit";
+/**
+ * Converter for the boolean attributes that default to `true`. Lit's
+ * standard boolean converter only looks at the attribute's presence, the
+ * same way native HTML boolean attributes work, so `closeable="false"`
+ * would still read as `true`, and nothing declarative (HTML, SSR, JSX)
+ * could turn these off. Here the literal `"false"` really means `false`.
+ *
+ * When reflected, `true` writes an empty attribute and `false` writes
+ * `"false"`, rather than removing it : a missing attribute would read back
+ * as the `true` default on the next upgrade (SSR output, `cloneNode`), and
+ * stylesheets can target the off state with `[attr="false"]`.
+ */
+export declare const defaultTrueConverter: ComplexAttributeConverter<boolean>;

package/dist/utils/boolean.utils.js

@@ -0,0 +1,20 @@
+/**
+ * Converter for the boolean attributes that default to `true`. Lit's
+ * standard boolean converter only looks at the attribute's presence, the
+ * same way native HTML boolean attributes work, so `closeable="false"`
+ * would still read as `true`, and nothing declarative (HTML, SSR, JSX)
+ * could turn these off. Here the literal `"false"` really means `false`.
+ *
+ * When reflected, `true` writes an empty attribute and `false` writes
+ * `"false"`, rather than removing it : a missing attribute would read back
+ * as the `true` default on the next upgrade (SSR output, `cloneNode`), and
+ * stylesheets can target the off state with `[attr="false"]`.
+ */
+export const defaultTrueConverter = {
+    fromAttribute(value) {
+        return value !== null && value !== "false";
+    },
+    toAttribute(value) {
+        return value ? "" : "false";
+    },
+};

package/dist/utils/dropdown-menu.utils.d.ts

@@ -38,7 +38,7 @@ export interface DropdownMenuContainer extends HTMLElement {
  * an open submenu without knowing its concrete class.
  */
 export interface DropdownMenuEntry extends HTMLElement {
-    readonly key: string;
+    readonly value: string;
     closeSubmenu(): void;
     repositionSubmenu(): void;
 }

package/dist/utils/focusable-elements.utils.d.ts

@@ -36,6 +36,18 @@ export interface FocusableElementsOptions {
  * @returns every focusable descendant, in traversal order.
  */
 export declare function getFocusableElements(root: Element | ShadowRoot, options?: FocusableElementsOptions): HTMLElement[];
+/**
+ * The element that actually receives focus for `element` : `element`
+ * itself when it's a tab stop, otherwise its first focusable descendant
+ * (crossing slots and nested shadow roots, see {@link walkFlatTree}), e.g.
+ * the `<a>` slotted into an `eun-link` or the native control rendered
+ * inside a component's shadow root. Falls back to `element` when nothing
+ * inside it is focusable. Rendering isn't required, so a visually hidden
+ * (`sr-only`) control still counts.
+ *
+ * @param element the element to resolve.
+ */
+export declare function resolveFocusTarget(element: HTMLElement): HTMLElement;
 /**
  * Whether `root` has *any* focusable descendant (see {@link
  * walkFlatTree}), stopping at the first match rather than collecting them

package/dist/utils/focusable-elements.utils.js

@@ -106,6 +106,32 @@ export function getFocusableElements(root, options = {}) {
     });
     return results;
 }
+/**
+ * The element that actually receives focus for `element` : `element`
+ * itself when it's a tab stop, otherwise its first focusable descendant
+ * (crossing slots and nested shadow roots, see {@link walkFlatTree}), e.g.
+ * the `<a>` slotted into an `eun-link` or the native control rendered
+ * inside a component's shadow root. Falls back to `element` when nothing
+ * inside it is focusable. Rendering isn't required, so a visually hidden
+ * (`sr-only`) control still counts.
+ *
+ * @param element the element to resolve.
+ */
+export function resolveFocusTarget(element) {
+    const options = { requireRendered: false };
+    if (isFocusable(element, options)) {
+        return element;
+    }
+    let target;
+    walkFlatTree(element.shadowRoot ?? element, (descendant) => {
+        if (isFocusable(descendant, options)) {
+            target = descendant;
+            return true;
+        }
+        return false;
+    });
+    return target ?? element;
+}
 /**
  * Whether `root` has *any* focusable descendant (see {@link
  * walkFlatTree}), stopping at the first match rather than collecting them

package/dist/utils/implicit-submission.utils.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Whether a key press should trigger implicit submission: Enter, outside
+ * of an IME composition, and not already handled by something else.
+ *
+ * @param event - The keydown event to check.
+ * @returns Whether the event asks for implicit submission.
+ */
+export declare function isImplicitSubmissionKey(event: KeyboardEvent): boolean;
+/**
+ * Submits a form the way the browser does when Enter is pressed in one of
+ * its text fields, since a field whose native input lives in a shadow root
+ * never triggers it on its own. Clicks the form's default button when it
+ * has one, unless that button is disabled. Without one, submits only when
+ * the form holds a single text field.
+ *
+ * @param form - The form to submit.
+ */
+export declare function submitImplicitly(form: HTMLFormElement): void;

package/dist/utils/implicit-submission.utils.js

@@ -0,0 +1,79 @@
+/**
+ * Buttons that can submit a form, in the order the browser looks for the
+ * form's default button. `eun-button` and `eun-fab` aren't form-associated,
+ * so they're found in the form's own subtree rather than in `form.elements`.
+ */
+const SUBMIT_BUTTONS = [
+    "button:not([type])",
+    'button[type="submit"]',
+    'input[type="submit"]',
+    'input[type="image"]',
+    'eun-button[type="submit"]',
+    'eun-fab[type="submit"]',
+].join(", ");
+/**
+ * Native input types that block implicit submission, per the HTML spec.
+ */
+const BLOCKING_INPUT_TYPES = new Set([
+    "text",
+    "search",
+    "url",
+    "tel",
+    "email",
+    "password",
+    "date",
+    "month",
+    "week",
+    "time",
+    "datetime-local",
+    "number",
+]);
+/**
+ * Library fields standing in for one of the native inputs above, and so
+ * blocking implicit submission the same way it does.
+ */
+const BLOCKING_FIELDS = [
+    "eun-input",
+    "eun-search",
+    "eun-input-phone",
+    "eun-counter",
+    "eun-date-picker",
+    "eun-time-picker",
+].join(", ");
+/**
+ * Whether a key press should trigger implicit submission: Enter, outside
+ * of an IME composition, and not already handled by something else.
+ *
+ * @param event - The keydown event to check.
+ * @returns Whether the event asks for implicit submission.
+ */
+export function isImplicitSubmissionKey(event) {
+    return (event.key === "Enter" &&
+        !event.isComposing &&
+        event.keyCode !== 229 &&
+        !event.defaultPrevented);
+}
+/**
+ * Submits a form the way the browser does when Enter is pressed in one of
+ * its text fields, since a field whose native input lives in a shadow root
+ * never triggers it on its own. Clicks the form's default button when it
+ * has one, unless that button is disabled. Without one, submits only when
+ * the form holds a single text field.
+ *
+ * @param form - The form to submit.
+ */
+export function submitImplicitly(form) {
+    const defaultButton = form.querySelector(SUBMIT_BUTTONS);
+    if (defaultButton) {
+        if (!defaultButton.matches(":disabled, [disabled]")) {
+            defaultButton.click();
+        }
+        return;
+    }
+    const blockingFields = Array.from(form.elements).filter((element) => (element instanceof HTMLInputElement &&
+        BLOCKING_INPUT_TYPES.has(element.type)) ||
+        element.matches(BLOCKING_FIELDS));
+    if (blockingFields.length <= 1) {
+        form.requestSubmit();
+    }
+}

package/dist/utils/input-modality.utils.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Starts recording, once per page, whether the latest interaction came from
+ * the keyboard or a pointer. Listens in the capture phase, so a handler
+ * stopping propagation further down can't hide an interaction. Safe to call
+ * from every instance's `connectedCallback`, and a no-op outside a browser.
+ */
+export declare function trackInputModality(): void;
+/**
+ * Whether the latest interaction recorded by {@link trackInputModality}
+ * came from the keyboard. `false` before any interaction, so a surface
+ * opened by script on page load keeps its pointer behavior.
+ */
+export declare function isKeyboardModality(): boolean;

package/dist/utils/input-modality.utils.js

@@ -0,0 +1,34 @@
+/**
+ * Whether the user's latest interaction with the page came from the
+ * keyboard, as opposed to a mouse, pen, or touch.
+ */
+let keyboardModality = false;
+let tracking = false;
+const handleKeydown = () => {
+    keyboardModality = true;
+};
+const handlePointerdown = () => {
+    keyboardModality = false;
+};
+/**
+ * Starts recording, once per page, whether the latest interaction came from
+ * the keyboard or a pointer. Listens in the capture phase, so a handler
+ * stopping propagation further down can't hide an interaction. Safe to call
+ * from every instance's `connectedCallback`, and a no-op outside a browser.
+ */
+export function trackInputModality() {
+    if (tracking || typeof document === "undefined") {
+        return;
+    }
+    tracking = true;
+    document.addEventListener("keydown", handleKeydown, true);
+    document.addEventListener("pointerdown", handlePointerdown, true);
+}
+/**
+ * Whether the latest interaction recorded by {@link trackInputModality}
+ * came from the keyboard. `false` before any interaction, so a surface
+ * opened by script on page load keeps its pointer behavior.
+ */
+export function isKeyboardModality() {
+    return keyboardModality;
+}

package/dist/utils/listbox-options.utils.d.ts

@@ -31,3 +31,14 @@ export declare function parseListboxOptions(children: Iterable<Element>): Listbo
  * @returns the rendered template, or the plain `label` when nothing matches.
  */
 export declare function renderHighlightedLabel(label: string, query: string): TemplateResult | string;
+/**
+ * Renders a listbox's option rows, wrapping each run of options sharing an
+ * `optgroup` in a `role="group"` row named by that group's label, so
+ * assistive technology announces which group an option belongs to.
+ * Options outside any group are rendered as they are.
+ *
+ * @param options the options to render, in display order.
+ * @param renderOption renders one option row, given its index in `options`.
+ * @returns the rendered rows.
+ */
+export declare function renderListboxRows<T extends ListboxOption>(options: T[], renderOption: (option: T, index: number) => TemplateResult): TemplateResult[];

package/dist/utils/listbox-options.utils.js

@@ -48,7 +48,45 @@ export function renderHighlightedLabel(label, query) {
     if (index === -1) {
         return label;
     }
-    return html `${label.slice(0, index)}<mark
-      >${label.slice(index, index + query.length)}</mark
-    >${label.slice(index + query.length)}`;
+    return html `${label.slice(0, index)}<mark>${label.slice(index, index + query.length)}</mark>${label.slice(index + query.length)}`;
+}
+/**
+ * Renders a listbox's option rows, wrapping each run of options sharing an
+ * `optgroup` in a `role="group"` row named by that group's label, so
+ * assistive technology announces which group an option belongs to.
+ * Options outside any group are rendered as they are.
+ *
+ * @param options the options to render, in display order.
+ * @param renderOption renders one option row, given its index in `options`.
+ * @returns the rendered rows.
+ */
+export function renderListboxRows(options, renderOption) {
+    const rows = [];
+    let groupCount = 0;
+    let index = 0;
+    while (index < options.length) {
+        const { group } = options[index];
+        const start = index;
+        while (index < options.length && options[index].group === group) {
+            index += 1;
+        }
+        const run = options
+            .slice(start, index)
+            .map((option, offset) => renderOption(option, start + offset));
+        if (!group) {
+            rows.push(...run);
+            continue;
+        }
+        const labelId = `listbox-group-${groupCount}`;
+        groupCount += 1;
+        rows.push(html `
+      <li class="option-group" role="group" aria-labelledby=${labelId}>
+        <div id=${labelId} class="group-label">${group}</div>
+        <ul class="group-options" role="presentation">
+          ${run}
+        </ul>
+      </li>
+    `);
+    }
+    return rows;
 }