@gtivr4/a1-design-system-react 0.14.0 → 0.18.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gtivr4/a1-design-system-react",
-  "version": "0.14.0",
+  "version": "0.18.0",
   "description": "React components for the A1 token-driven design system.",
   "type": "module",
   "main": "./src/index.js",
@@ -40,5 +40,6 @@
   },
   "peerDependencies": {
     "react": ">=18"
-  }
+  },
+  "types": "./src/index.d.ts"
 }

package/src/color-scheme.css

@@ -443,8 +443,10 @@ html.a1-theme-dark .a1-theme-light .a1-notification--default {
 html.a1-theme-light {
   color-scheme: light;
   --semantic-color-surface-page:   var(--base-color-neutral-0);
+  --semantic-color-surface-card:   var(--base-color-neutral-0);
   --semantic-color-surface-panel:  var(--base-color-neutral-50);
   --semantic-color-surface-raised: var(--base-color-neutral-100);
+  --semantic-color-surface-inverse: var(--base-color-neutral-900);
   --semantic-color-text-default: var(--base-color-neutral-900);
   --semantic-color-text-muted:   var(--base-color-neutral-600);
   --semantic-color-text-inverse: var(--base-color-neutral-0);

package/src/components/accordion/Accordion.d.ts

@@ -3,6 +3,12 @@ import * as React from "react";
 export interface AccordionProps {
   /** Trigger label text */
   label: string;
+  /**
+   * Secondary information shown in the trigger, **below** the label. It only
+   * shows while the accordion is collapsed (a glanceable summary, e.g. the
+   * applied settings) and is hidden when open. Truncates with an ellipsis.
+   */
+  subtext?: React.ReactNode;
   /** Controlled open state */
   open?: boolean;
   /** Initial open state (uncontrolled). Default: false */
@@ -11,6 +17,8 @@ export interface AccordionProps {
   onChange?: (open: boolean) => void;
   /** Size — affects trigger text size and padding. Default: "md" */
   size?: "sm" | "md" | "lg";
+  /** Show a divider under the trigger/header (it stays attached to the header, not the bottom of the open panel). Default: false */
+  divider?: boolean;
   /** Prevent the accordion from being toggled. Default: false */
   disabled?: boolean;
   className?: string;

package/src/components/accordion/Accordion.jsx

@@ -6,11 +6,13 @@ const SIZES = ["sm", "md", "lg"];
 
 export function Accordion({
   label,
+  subtext,
   children,
   open: controlledOpen,
   defaultOpen = false,
   onChange,
   size = "md",
+  divider = false,
   disabled = false,
   className = "",
   ...rest
@@ -46,6 +48,7 @@ export function Accordion({
         "a1-accordion",
         `a1-accordion--${resolvedSize}`,
         open && "a1-accordion--open",
+        divider && "a1-accordion--divider",
         disabled && "a1-accordion--disabled",
         className,
       ].filter(Boolean).join(" ")}
@@ -63,7 +66,12 @@ export function Accordion({
         <span className="a1-accordion__chevron" aria-hidden="true">
           <Icon name="expand_more" />
         </span>
-        <span className="a1-accordion__label">{label}</span>
+        <span className="a1-accordion__text">
+          <span className="a1-accordion__label">{label}</span>
+          {subtext != null && subtext !== "" && (
+            <span className="a1-accordion__subtext">{subtext}</span>
+          )}
+        </span>
       </button>
 
       <div

package/src/components/accordion/accordion.css

@@ -3,31 +3,34 @@
 .a1-accordion {
   /* Size tokens — default (md) */
   --a1-ac-height:      var(--component-accordion-trigger-height-md);
-  --a1-ac-px:          var(--component-accordion-padding-inline-md);
+  --a1-ac-px:          var(--base-spacing-8);
   --a1-ac-py:          var(--base-spacing-8);
   --a1-ac-icon-size:   var(--component-accordion-icon-size-md);
   --a1-ac-font-size:   var(--semantic-font-size-body-md);
   --a1-ac-font-weight: var(--base-font-weight-medium);
+  --a1-ac-subtext-size: var(--semantic-font-size-body-sm);
 }
 
 /* ─── Sizes ─────────────────────────────────────────────────────────────────── */
 
 .a1-accordion--sm {
   --a1-ac-height:      var(--component-accordion-trigger-height-sm);
-  --a1-ac-px:          var(--component-accordion-padding-inline-sm);
+  --a1-ac-px:          var(--base-spacing-4);
   --a1-ac-py:          var(--base-spacing-6);
   --a1-ac-icon-size:   var(--component-accordion-icon-size-sm);
   --a1-ac-font-size:   var(--semantic-font-size-body-sm);
   --a1-ac-font-weight: var(--base-font-weight-medium);
+  --a1-ac-subtext-size: var(--semantic-font-size-body-xs);
 }
 
 .a1-accordion--lg {
   --a1-ac-height:      var(--component-accordion-trigger-height-lg);
-  --a1-ac-px:          var(--component-accordion-padding-inline-lg);
+  --a1-ac-px:          var(--base-spacing-12);
   --a1-ac-py:          var(--base-spacing-12);
   --a1-ac-icon-size:   var(--component-accordion-icon-size-lg);
   --a1-ac-font-size:   var(--semantic-font-size-body-lg);
   --a1-ac-font-weight: var(--base-font-weight-bold);
+  --a1-ac-subtext-size: var(--semantic-font-size-body-md);
 }
 
 /* ─── Trigger ───────────────────────────────────────────────────────────────── */
@@ -41,7 +44,6 @@
   padding-inline: var(--a1-ac-px);
   padding-block: var(--a1-ac-py);
   border: none;
-  border-radius: var(--component-accordion-border-radius);
   background: transparent;
   cursor: pointer;
   color: var(--semantic-color-text-default);
@@ -85,13 +87,36 @@
   transform: rotate(0deg);
 }
 
-/* ─── Label ─────────────────────────────────────────────────────────────────── */
+/* ─── Label + subtext ───────────────────────────────────────────────────────── */
+
+/* Label and subtext stack vertically (subtext below the title). */
+.a1-accordion__text {
+  display: flex;
+  flex: 1 1 auto;
+  flex-direction: column;
+  min-width: 0;
+}
 
 .a1-accordion__label {
-  flex: 1;
   min-width: 0;
 }
 
+/* Secondary info below the title, shown only while collapsed (e.g. a summary of
+   applied settings). Truncates with an ellipsis. */
+.a1-accordion__subtext {
+  min-width: 0;
+  color: var(--semantic-color-text-muted);
+  font-size: var(--a1-ac-subtext-size);
+  font-weight: var(--semantic-font-weight-body);
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+.a1-accordion--open .a1-accordion__subtext {
+  display: none;
+}
+
 /* ─── Body — CSS grid height animation ──────────────────────────────────────── */
 
 .a1-accordion__body {
@@ -109,6 +134,21 @@
   min-height: 0;
 }
 
+/* ─── Divider (optional) ────────────────────────────────────────────────────── */
+/* Attached to the trigger (the expanding header), so it stays put under the
+   header whether collapsed or expanded — never drops to the bottom of the open
+   panel. */
+
+.a1-accordion--divider .a1-accordion__trigger {
+  border-block-end: var(--component-divider-size-xs) solid var(--semantic-color-border-subtle);
+}
+
+/* With a divider, give the open panel breathing room so its first item does not
+   sit directly against the divider line. Scales with the accordion size. */
+.a1-accordion--divider .a1-accordion__body-inner {
+  padding-block-start: var(--a1-ac-py);
+}
+
 /* ─── Disabled ──────────────────────────────────────────────────────────────── */
 
 .a1-accordion--disabled .a1-accordion__trigger {

package/src/components/autocomplete/Autocomplete.d.ts

@@ -0,0 +1,53 @@
+import * as React from "react";
+
+export interface AutocompleteOption {
+  value: string;
+  label?: string;
+  /** A CSS colour rendered as a swatch beside the option (and on the selected value / chip). In `variant="color"` the swatch defaults to `value` when omitted. */
+  swatch?: string;
+  /** A Material Symbols glyph name rendered beside the option / chip / selected value. */
+  icon?: string;
+  /** Group name. When any option has a `group`, the listbox renders a sticky heading before each group's options. Options are ordered by each group's first appearance. */
+  group?: string;
+}
+
+export interface AutocompleteProps {
+  /** Suggestion list. Pass strings or `{ value, label }` objects. */
+  options?: (string | AutocompleteOption)[];
+  /** Selected value — a string in single mode, a string[] in multi mode. */
+  value?: string | string[];
+  /** Called with the new value (string, or string[] when `multiple`). */
+  onChange?: (value: string | string[]) => void;
+  /** Allow selecting more than one option (renders removable chips). Default: false */
+  multiple?: boolean;
+  /** Allow creating a value not in `options` ("Add …"). Default: false */
+  allowCreate?: boolean;
+  /** Called with the created value when an `allowCreate` option is chosen. */
+  onCreate?: (value: string) => void;
+  /** Visual variant. "color" renders a colour swatch beside each option / chip / the selected value (swatch defaults to the option `value`). Default: "default" */
+  variant?: "default" | "color";
+  /** Field label. */
+  label?: React.ReactNode;
+  /** Helper text shown below the control. */
+  hint?: React.ReactNode;
+  /** Error message; styles the control and replaces the hint. */
+  error?: React.ReactNode;
+  /** Size scale, matching the field family. Default: "default" */
+  size?: "compact" | "default" | "comfortable";
+  required?: boolean;
+  disabled?: boolean;
+  id?: string;
+  name?: string;
+  className?: string;
+  /** Text shown when no options match. Default: "No matches" */
+  emptyText?: React.ReactNode;
+  /** Label for the create option, given the current query. */
+  createLabel?: (query: string) => React.ReactNode;
+  /** Cap the number of options rendered in the listbox (for very large lists like an icon picker). Excess options are hidden behind a "keep typing" footer. */
+  maxVisible?: number;
+  /** Footer text shown when the list is capped by `maxVisible`, given the shown count. */
+  moreText?: (shown: number) => React.ReactNode;
+  "aria-label"?: string;
+}
+
+export declare function Autocomplete(props: AutocompleteProps): React.ReactElement;

package/src/components/autocomplete/Autocomplete.jsx

@@ -0,0 +1,380 @@
+import { useEffect, useId, useLayoutEffect, useMemo, useRef, useState } from "react";
+import { createPortal } from "react-dom";
+import { Icon } from "../icon/Icon.jsx";
+import { MessageBadge } from "../message/Message.jsx";
+import { useLabel } from "../labels/Labels.jsx";
+import "./autocomplete.css";
+
+const SIZES = ["compact", "default", "comfortable"];
+
+function normalizeOption(o) {
+  return typeof o === "string" ? { value: o, label: o } : o;
+}
+
+/**
+ * Autocomplete — a combobox that filters a list of options as you type, in
+ * single- or multi-select mode. Optionally lets the user create a value that
+ * isn't in the list (`allowCreate`). Built on the ARIA combobox/listbox pattern
+ * and styled to match the A1 field family.
+ */
+const VARIANTS = ["default", "color"];
+
+export function Autocomplete({
+  options = [],
+  value,
+  onChange,
+  multiple = false,
+  allowCreate = false,
+  onCreate,
+  variant = "default",
+  label,
+  hint,
+  error,
+  size,
+  required = false,
+  disabled = false,
+  id: providedId,
+  name,
+  className = "",
+  emptyText = "No matches",
+  createLabel = (q) => `Add “${q}”`,
+  maxVisible,
+  moreText = (shown) => `Showing the first ${shown} — keep typing to narrow.`,
+  "aria-label": ariaLabel,
+  ...props
+}) {
+  const autoId = useId();
+  const id = providedId ?? autoId;
+  const listId = `${id}-listbox`;
+  const hintId = `${id}-hint`;
+  const errorId = `${id}-error`;
+  const resolvedSize = SIZES.includes(size) ? size : "default";
+  const resolvedVariant = VARIANTS.includes(variant) ? variant : "default";
+  const requiredText = useLabel("field.required", "Required");
+
+  const items = useMemo(() => options.map(normalizeOption), [options]);
+  // Grouping: when any option carries a `group`, the listbox renders a heading
+  // before each group. `groupRank` records each group's first-appearance order
+  // so results can be ordered to keep groups contiguous.
+  const hasGroups = useMemo(() => items.some((i) => i.group != null), [items]);
+  const groupRank = useMemo(() => {
+    const order = new Map();
+    for (const i of items) if (i.group != null && !order.has(i.group)) order.set(i.group, order.size);
+    return order;
+  }, [items]);
+  const selectedValues = multiple
+    ? (Array.isArray(value) ? value : [])
+    : (value != null && value !== "" ? [value] : []);
+
+  const [query, setQuery] = useState("");
+  const [open, setOpen] = useState(false);
+  const [activeIndex, setActiveIndex] = useState(-1);
+  const inputRef = useRef(null);
+  const rootRef = useRef(null);
+  const controlRef = useRef(null);
+  const listRef = useRef(null);
+  // The listbox is portaled to <body> so it escapes any clipping ancestor
+  // (e.g. an Accordion's overflow:hidden panel); position it under the control.
+  const [menuPos, setMenuPos] = useState(null);
+
+  const labelFor = (v) => items.find((i) => i.value === v)?.label ?? v;
+  // A swatch colour for a value: an explicit option `swatch`, or the value
+  // itself when it's a CSS colour (the common case for a colour picker).
+  const swatchFor = (v) => {
+    const opt = items.find((i) => i.value === v);
+    if (opt && opt.swatch) return opt.swatch;
+    return resolvedVariant === "color" ? v : undefined;
+  };
+  // A Material Symbols glyph for a value (option `icon`) — used by icon pickers.
+  const iconFor = (v) => items.find((i) => i.value === v)?.icon;
+  const selectedLabel = !multiple && selectedValues.length ? labelFor(selectedValues[0]) : "";
+  const selectedSwatch = !multiple && selectedValues.length ? swatchFor(selectedValues[0]) : undefined;
+  const selectedIcon = !multiple && selectedValues.length ? iconFor(selectedValues[0]) : undefined;
+
+  const q = query.trim().toLowerCase();
+  // In multi mode, keep selected options in the list (shown checked) so they can
+  // be toggled off; in single mode the list is just the filter results.
+  const filtered = items.filter((i) => !q || i.label.toLowerCase().includes(q));
+  // Order grouped results by each group's first appearance so the headings stay
+  // contiguous and keyboard navigation order matches the visual order.
+  const ordered = hasGroups
+    ? [...filtered].sort((a, b) => (groupRank.get(a.group) ?? Infinity) - (groupRank.get(b.group) ?? Infinity))
+    : filtered;
+  // Cap how many options render (large lists, e.g. the icon picker). The create
+  // row and the "refine" footer sit outside the cap.
+  const truncated = maxVisible != null && ordered.length > maxVisible;
+  const limited = truncated ? ordered.slice(0, maxVisible) : ordered;
+  const exactExists = items.some((i) => i.label.toLowerCase() === q || String(i.value).toLowerCase() === q);
+  const showCreate = allowCreate && q.length > 0 && !exactExists
+    && !(multiple && selectedValues.includes(query.trim()));
+  const visible = showCreate
+    ? [...limited, { __create: true, value: query.trim(), label: createLabel(query.trim()) }]
+    : limited;
+
+  // Precompute render rows: a group heading is inserted before the first option
+  // of each group. Headings are not part of `visible`, so keyboard navigation
+  // (which indexes `visible`) naturally skips them.
+  const rows = [];
+  let prevGroup;
+  visible.forEach((opt, idx) => {
+    if (hasGroups && !opt.__create && opt.group != null && opt.group !== prevGroup) {
+      rows.push({ kind: "group", label: opt.group, key: `__group-${opt.group}` });
+    }
+    if (!opt.__create) prevGroup = opt.group;
+    rows.push({ kind: "option", opt, idx });
+  });
+
+  // Close on outside interaction. The portaled listbox lives outside rootRef, so
+  // ignore clicks within it too.
+  useEffect(() => {
+    if (!open) return;
+    const onDoc = (e) => {
+      if (rootRef.current?.contains(e.target)) return;
+      if (listRef.current?.contains(e.target)) return;
+      setOpen(false);
+    };
+    document.addEventListener("mousedown", onDoc);
+    return () => document.removeEventListener("mousedown", onDoc);
+  }, [open]);
+
+  // Track the control's viewport rect while open so the fixed-position listbox
+  // follows it through scrolling/resizing of any ancestor.
+  useLayoutEffect(() => {
+    if (!open || disabled) return undefined;
+    const update = () => {
+      const el = controlRef.current;
+      if (!el) return;
+      const r = el.getBoundingClientRect();
+      setMenuPos({ top: r.bottom, left: r.left, width: r.width });
+    };
+    update();
+    window.addEventListener("scroll", update, true);
+    window.addEventListener("resize", update);
+    return () => {
+      window.removeEventListener("scroll", update, true);
+      window.removeEventListener("resize", update);
+    };
+  }, [open, disabled]);
+
+  // On open, highlight the currently-selected option so the menu opens focused
+  // on it (single-select; in multi mode the first selected value).
+  useEffect(() => {
+    if (!open) return;
+    if (selectedValues.length === 0) { setActiveIndex(-1); return; }
+    const idx = visible.findIndex((o) => !o.__create && o.value === selectedValues[0]);
+    if (idx >= 0) setActiveIndex(idx);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [open]);
+
+  // Keep the active option scrolled into view (on open + arrow navigation).
+  useEffect(() => {
+    if (!open || activeIndex < 0) return;
+    const el = listRef.current?.querySelector(".a1-autocomplete__option--active");
+    el?.scrollIntoView({ block: "nearest" });
+  }, [open, activeIndex, menuPos]);
+
+  function commit(option) {
+    if (!option) return;
+    if (option.__create) onCreate?.(option.value);
+    const v = option.value;
+    if (multiple) {
+      // Toggle: re-selecting a checked option removes it. The menu stays open
+      // until the user dismisses it (outside click / Escape).
+      if (selectedValues.includes(v)) onChange?.(selectedValues.filter((x) => x !== v));
+      else onChange?.([...selectedValues, v]);
+      setQuery("");
+      setActiveIndex(-1);
+      setOpen(true);
+      inputRef.current?.focus();
+    } else {
+      onChange?.(v);
+      setQuery("");
+      setOpen(false);
+    }
+  }
+
+  function removeValue(v) {
+    if (multiple) onChange?.(selectedValues.filter((x) => x !== v));
+    else onChange?.("");
+  }
+
+  function handleKeyDown(e) {
+    if (e.key === "ArrowDown") {
+      e.preventDefault();
+      setOpen(true);
+      setActiveIndex((i) => Math.min(i + 1, visible.length - 1));
+    } else if (e.key === "ArrowUp") {
+      e.preventDefault();
+      setActiveIndex((i) => Math.max(i - 1, 0));
+    } else if (e.key === "Enter") {
+      if (open && activeIndex >= 0 && visible[activeIndex]) { e.preventDefault(); commit(visible[activeIndex]); }
+      else if (open && visible.length === 1) { e.preventDefault(); commit(visible[0]); }
+    } else if (e.key === "Escape") {
+      setOpen(false);
+    } else if (e.key === "Backspace" && multiple && query === "" && selectedValues.length) {
+      removeValue(selectedValues[selectedValues.length - 1]);
+    }
+  }
+
+  const describedBy = [error ? errorId : hint ? hintId : null].filter(Boolean).join(" ") || undefined;
+  const inputValue = multiple ? query : (open ? query : selectedLabel);
+
+  const classes = [
+    "a1-autocomplete",
+    `a1-autocomplete--${resolvedSize}`,
+    resolvedVariant === "color" && "a1-autocomplete--color",
+    multiple && "a1-autocomplete--multiple",
+    error && "a1-autocomplete--error",
+    required && "a1-autocomplete--required",
+    disabled && "a1-autocomplete--disabled",
+    open && "a1-autocomplete--open",
+    className,
+  ].filter(Boolean).join(" ");
+
+  return (
+    <div className={classes} ref={rootRef} {...props}>
+      {label && (
+        <label className="a1-autocomplete__label" htmlFor={id}>
+          {label}
+          {required && resolvedSize === "comfortable" ? (
+            <MessageBadge status="info" subtle size="sm" icon={null}>{requiredText}</MessageBadge>
+          ) : required ? (
+            <span className="a1-autocomplete__asterisk" aria-hidden="true"> *</span>
+          ) : null}
+        </label>
+      )}
+
+      <div
+        ref={controlRef}
+        className="a1-autocomplete__control"
+        onClick={() => { if (!disabled) { setOpen(true); inputRef.current?.focus(); } }}
+      >
+        {multiple && selectedValues.map((v) => (
+          <span key={v} className="a1-autocomplete__chip">
+            {swatchFor(v) && <span className="a1-autocomplete__swatch" style={{ background: swatchFor(v) }} aria-hidden="true" />}
+            {iconFor(v) && <Icon name={iconFor(v)} className="a1-autocomplete__chip-icon" aria-hidden="true" />}
+            {labelFor(v)}
+            <button
+              type="button"
+              className="a1-autocomplete__chip-remove"
+              aria-label={`Remove ${labelFor(v)}`}
+              disabled={disabled}
+              onClick={(e) => { e.stopPropagation(); removeValue(v); }}
+            >
+              <Icon name="close" />
+            </button>
+          </span>
+        ))}
+
+        {!multiple && selectedSwatch && (
+          <span className="a1-autocomplete__swatch a1-autocomplete__swatch--leading" style={{ background: selectedSwatch }} aria-hidden="true" />
+        )}
+
+        {!multiple && !selectedSwatch && selectedIcon && !open && (
+          <Icon name={selectedIcon} className="a1-autocomplete__leading-icon" aria-hidden="true" />
+        )}
+
+        <input
+          ref={inputRef}
+          id={id}
+          name={name}
+          className="a1-autocomplete__input"
+          type="text"
+          role="combobox"
+          aria-expanded={open}
+          aria-controls={listId}
+          aria-autocomplete="list"
+          aria-label={ariaLabel}
+          aria-activedescendant={open && activeIndex >= 0 ? `${id}-opt-${activeIndex}` : undefined}
+          aria-describedby={describedBy}
+          autoComplete="off"
+          disabled={disabled}
+          required={required && selectedValues.length === 0}
+          value={inputValue}
+          onChange={(e) => { setQuery(e.target.value); setOpen(true); setActiveIndex(-1); }}
+          onFocus={() => setOpen(true)}
+          onKeyDown={handleKeyDown}
+        />
+
+        {!multiple && selectedValues.length > 0 && !disabled && (
+          <button
+            type="button"
+            className="a1-autocomplete__clear"
+            aria-label="Clear selection"
+            onClick={(e) => { e.stopPropagation(); removeValue(selectedValues[0]); setQuery(""); inputRef.current?.focus(); }}
+          >
+            <Icon name="close" />
+          </button>
+        )}
+        <Icon name="expand_more" className="a1-autocomplete__chevron" aria-hidden="true" />
+      </div>
+
+      {open && !disabled && menuPos && createPortal(
+        <ul
+          ref={listRef}
+          className="a1-autocomplete__listbox a1-autocomplete__listbox--floating"
+          role="listbox"
+          id={listId}
+          aria-multiselectable={multiple || undefined}
+          style={{ position: "fixed", top: menuPos.top, left: menuPos.left, width: menuPos.width }}
+        >
+          {visible.length === 0 ? (
+            <li className="a1-autocomplete__empty">{emptyText}</li>
+          ) : (
+            <>
+              {rows.map((row) => {
+                if (row.kind === "group") {
+                  return <li key={row.key} className="a1-autocomplete__group" role="presentation">{row.label}</li>;
+                }
+                const { opt, idx } = row;
+                const isSelected = !opt.__create && selectedValues.includes(opt.value);
+                return (
+                  <li
+                    key={opt.__create ? `__create-${opt.value}` : opt.value}
+                    id={`${id}-opt-${idx}`}
+                    role="option"
+                    aria-selected={isSelected}
+                    className={[
+                      "a1-autocomplete__option",
+                      idx === activeIndex && "a1-autocomplete__option--active",
+                      opt.__create && "a1-autocomplete__option--create",
+                    ].filter(Boolean).join(" ")}
+                    onMouseDown={(e) => { e.preventDefault(); commit(opt); }}
+                    onMouseEnter={() => setActiveIndex(idx)}
+                  >
+                    {opt.__create && <Icon name="add" className="a1-autocomplete__option-icon" aria-hidden="true" />}
+                    {multiple && !opt.__create && (
+                      <span className={`a1-autocomplete__checkbox${isSelected ? " a1-autocomplete__checkbox--on" : ""}`} aria-hidden="true" />
+                    )}
+                    {!opt.__create && swatchFor(opt.value) && (
+                      <span className="a1-autocomplete__swatch" style={{ background: swatchFor(opt.value) }} aria-hidden="true" />
+                    )}
+                    {!opt.__create && opt.icon && (
+                      <Icon name={opt.icon} className="a1-autocomplete__option-icon" aria-hidden="true" />
+                    )}
+                    <span className="a1-autocomplete__option-label">{opt.label}</span>
+                    {!multiple && isSelected && <Icon name="check" className="a1-autocomplete__option-check" aria-hidden="true" />}
+                  </li>
+                );
+              })}
+              {truncated && (
+                <li className="a1-autocomplete__more" role="presentation">{moreText(maxVisible)}</li>
+              )}
+            </>
+          )}
+        </ul>,
+        // When inside a modal <dialog> (top layer), portal into it so the
+        // listbox joins the dialog's top-layer stack and isn't painted behind
+        // it. Otherwise portal to <body>. See "Z-index and Layering" in
+        // project-foundations.md.
+        controlRef.current?.closest("dialog") ?? document.body,
+      )}
+
+      {error ? (
+        <p className="a1-autocomplete__message a1-autocomplete__message--error" id={errorId}>{error}</p>
+      ) : hint ? (
+        <p className="a1-autocomplete__message a1-autocomplete__message--hint" id={hintId}>{hint}</p>
+      ) : null}
+    </div>
+  );
+}