@dloizides/ui-forms 1.22.0 → 1.23.1

package/dist/index.mjs

@@ -1,4 +1,4 @@
-import React2, { useState, useCallback, useMemo, useEffect, useRef, useLayoutEffect } from 'react';
+import React2, { forwardRef, useState, useCallback, useMemo, useRef, useEffect, useLayoutEffect } from 'react';
 import { Platform, StyleSheet, TextInput, View, Text, useWindowDimensions, ScrollView, Pressable, Switch, Image, TouchableOpacity } from 'react-native';
 import { useUi } from '@dloizides/ui-feedback';
 import { jsx, jsxs, Fragment } from 'react/jsx-runtime';
@@ -544,9 +544,59 @@ var controlStyles = StyleSheet.create({
   optionText: { fontSize: OPTION_FONT },
   error: { fontSize: ERROR_FONT, marginTop: ERROR_GAP }
 });
+var ACTIVE_WEIGHT = "700";
+var IDLE_WEIGHT = "400";
+var DETAIL_FONT = 12;
+var DETAIL_GAP = 12;
+var STACK_GAP = 2;
+var DETAIL_BESIDE_MIN_MENU_WIDTH = 400;
+var styles7 = StyleSheet.create({
+  beside: { alignItems: "baseline", flexDirection: "row", gap: DETAIL_GAP, justifyContent: "space-between" },
+  stacked: { gap: STACK_GAP },
+  shrink: { flexShrink: 1 },
+  detail: { flexShrink: 1, fontSize: DETAIL_FONT }
+});
+function optionDomId(testID, value) {
+  return `${testID}-option-${value}`.replace(/\s+/g, "_");
+}
+function listboxDomId(testID) {
+  return `${testID}-listbox`;
+}
+function isDetailBesideTitle(menuWidth) {
+  return menuWidth >= DETAIL_BESIDE_MIN_MENU_WIDTH;
+}
+function rowInk(colors, isActive, isHighlighted) {
+  if (isHighlighted) return { title: colors.surface, detail: colors.surface };
+  return { title: isActive ? colors.brand : colors.text, detail: colors.textSecondary ?? colors.text };
+}
+function OptionRow({ option, isActive, isHighlighted, isListboxRow, menuWidth, hint, colors, testID, onSelect }) {
+  const hasDetail = option.detail !== void 0 && option.detail !== "";
+  const label = hasDetail ? `${option.label}, ${option.detail}` : option.label;
+  const roleProps = isListboxRow ? { role: "option", tabIndex: -1, id: optionDomId(testID, option.value), "aria-selected": isHighlighted } : { accessibilityRole: "menuitem", "aria-selected": isActive };
+  const isBold = isActive || isHighlighted;
+  const ink = rowInk(colors, isActive, isHighlighted);
+  return /* @__PURE__ */ jsx(
+    Pressable,
+    {
+      ...roleProps,
+      accessibilityLabel: label,
+      accessibilityHint: hint,
+      accessibilityState: { selected: isActive },
+      onPress: () => onSelect(option.value),
+      style: [controlStyles.option, isHighlighted ? { backgroundColor: colors.text } : null],
+      testID: `${testID}-option-${option.value}`,
+      children: /* @__PURE__ */ jsxs(View, { style: isDetailBesideTitle(menuWidth) ? styles7.beside : styles7.stacked, children: [
+        /* @__PURE__ */ jsx(Text, { style: [controlStyles.optionText, styles7.shrink, { color: ink.title, fontWeight: isBold ? ACTIVE_WEIGHT : IDLE_WEIGHT }], children: option.label }),
+        hasDetail ? /* @__PURE__ */ jsx(Text, { style: [styles7.detail, { color: ink.detail }], children: option.detail }) : null
+      ] })
+    }
+  );
+}
 var IS_WEB3 = Platform.OS === "web";
 var MENU_PORTAL_Z_INDEX = Z_INDEX.popover;
 var MENU_TOP_GAP2 = 4;
+var MENU_MIN_HEIGHT = 96;
+var VIEWPORT_MARGIN = 8;
 function toDomNode(ref) {
   const node = ref.current;
   if (node === null || typeof node.getBoundingClientRect !== "function") return null;
@@ -559,8 +609,9 @@ function readAnchorRect(ref) {
   const r = node.getBoundingClientRect();
   return { top: r.top, left: r.left, width: r.width, bottom: r.bottom };
 }
-function buildPortalPopoverStyle(rect) {
+function buildPortalPopoverStyle(rect, viewportBottom) {
   return {
+    ...viewportBottom !== void 0 ? { maxHeight: menuMaxHeight(rect.bottom, viewportBottom) } : null,
     // RN's ViewStyle union omits 'fixed', but react-native-web honours it at runtime.
     // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- web-only position value
     position: "fixed",
@@ -607,10 +658,64 @@ function useAnchorRect(ref, enabled) {
   }, [ref, enabled]);
   return IS_WEB3 && enabled ? rect : null;
 }
+function roomUnderAnchor(anchorBottom, viewportBottom) {
+  return viewportBottom - anchorBottom - MENU_TOP_GAP2 - VIEWPORT_MARGIN;
+}
+function menuMaxHeight(anchorBottom, viewportBottom) {
+  return Math.min(MENU_MAX_HEIGHT, Math.max(MENU_MIN_HEIGHT, roomUnderAnchor(anchorBottom, viewportBottom)));
+}
+function anchorScrollBlock(anchorBottom, viewportBottom) {
+  return roomUnderAnchor(anchorBottom, viewportBottom) < MENU_MAX_HEIGHT ? "start" : "nearest";
+}
+function readViewportBottom() {
+  const viewport = window.visualViewport ?? null;
+  return viewport === null ? window.innerHeight : viewport.offsetTop + viewport.height;
+}
+function useVisualViewportBottom(enabled) {
+  const [bottom, setBottom] = useState(null);
+  useLayoutEffect(() => {
+    if (!IS_WEB3 || !enabled) {
+      setBottom(null);
+      return void 0;
+    }
+    const update = () => setBottom(readViewportBottom());
+    update();
+    const viewport = window.visualViewport ?? null;
+    viewport?.addEventListener("resize", update);
+    viewport?.addEventListener("scroll", update);
+    window.addEventListener("resize", update);
+    return () => {
+      viewport?.removeEventListener("resize", update);
+      viewport?.removeEventListener("scroll", update);
+      window.removeEventListener("resize", update);
+    };
+  }, [enabled]);
+  return bottom;
+}
+function scrollNodeIntoView(node, block) {
+  if (node !== null && typeof node.scrollIntoView === "function") node.scrollIntoView({ block });
+}
+function scrollAnchorIntoView(ref, marginTop) {
+  if (!IS_WEB3) return;
+  const node = toDomNode(ref);
+  if (node === null) return;
+  node.style.scrollMarginTop = `${marginTop}px`;
+  scrollNodeIntoView(node, anchorScrollBlock(node.getBoundingClientRect().bottom, readViewportBottom()));
+}
+function useKeepAnchorInRoom(ref, marginTop, enabled) {
+  useLayoutEffect(() => {
+    if (!IS_WEB3 || !enabled) return void 0;
+    const place = () => scrollAnchorIntoView(ref, marginTop);
+    place();
+    const viewport = window.visualViewport ?? null;
+    viewport?.addEventListener("resize", place);
+    return () => viewport?.removeEventListener("resize", place);
+  }, [ref, marginTop, enabled]);
+}
 var IS_WEB4 = typeof document !== "undefined";
 var ESCAPE_KEY = "Escape";
-var ACTIVE_WEIGHT = "700";
-var IDLE_WEIGHT = "400";
+var LISTBOX_ROLE = { role: "listbox" };
+var KEEP_FIELD_FOCUS = { onMouseDown: (event) => event.preventDefault() };
 function useDismiss(anchorRef, menuRef, onDismiss) {
   useEffect(() => {
     if (!IS_WEB4) return void 0;
@@ -633,6 +738,12 @@ function useDismiss(anchorRef, menuRef, onDismiss) {
     };
   }, [anchorRef, menuRef, onDismiss]);
 }
+function useKeepHighlightInView(testID, highlightedValue) {
+  useEffect(() => {
+    if (!IS_WEB4 || highlightedValue === void 0 || highlightedValue === "") return;
+    scrollNodeIntoView(document.getElementById(optionDomId(testID, highlightedValue)), "nearest");
+  }, [testID, highlightedValue]);
+}
 function AnchoredMenu({
   options,
   selectedValue,
@@ -643,38 +754,48 @@ function AnchoredMenu({
   accessibilityLabel,
   testID,
   anchorRef,
-  usePortal = true
+  usePortal = true,
+  listbox
 }) {
   const menuRef = React2.useRef(null);
   useDismiss(anchorRef, menuRef, onDismiss);
+  useKeepHighlightInView(testID, listbox?.highlightedValue);
   const rect = useAnchorRect(anchorRef, usePortal);
-  const portalStyle = rect !== null ? buildPortalPopoverStyle(rect) : null;
-  const menu = /* @__PURE__ */ jsx(
+  const viewportBottom = useVisualViewportBottom(usePortal);
+  const portalStyle = rect !== null ? buildPortalPopoverStyle(rect, viewportBottom ?? void 0) : null;
+  const { width: windowWidth } = useWindowDimensions();
+  const menuWidth = rect?.width ?? windowWidth;
+  const isListbox = listbox !== void 0;
+  const statusText = listbox?.statusText;
+  const rows = options.map((option) => /* @__PURE__ */ jsx(
+    OptionRow,
+    {
+      colors,
+      hint: optionHint,
+      isActive: option.value === selectedValue,
+      isHighlighted: option.value === listbox?.highlightedValue,
+      isListboxRow: isListbox,
+      menuWidth,
+      option,
+      testID,
+      onSelect
+    },
+    option.value
+  ));
+  const listboxBody = options.length > 0 ? /* @__PURE__ */ jsx(View, { accessibilityLabel, id: listboxDomId(testID), ...LISTBOX_ROLE, testID: listboxDomId(testID), children: rows }) : null;
+  const menu = /* @__PURE__ */ jsxs(
     View,
     {
+      ...isListbox ? KEEP_FIELD_FOCUS : null,
       ref: menuRef,
-      accessibilityLabel,
-      accessibilityRole: "menu",
+      accessibilityLabel: isListbox ? void 0 : accessibilityLabel,
+      accessibilityRole: isListbox ? void 0 : "menu",
       style: [controlStyles.menu, { borderColor: colors.border, backgroundColor: colors.surface }, portalStyle],
       testID: `${testID}-menu`,
-      children: /* @__PURE__ */ jsx(ScrollView, { keyboardShouldPersistTaps: "handled", nestedScrollEnabled: true, children: options.map((opt) => {
-        const active = opt.value === selectedValue;
-        return /* @__PURE__ */ jsx(
-          Pressable,
-          {
-            accessibilityRole: "menuitem",
-            accessibilityLabel: opt.label,
-            accessibilityHint: optionHint,
-            accessibilityState: { selected: active },
-            "aria-selected": active,
-            onPress: () => onSelect(opt.value),
-            style: controlStyles.option,
-            testID: `${testID}-option-${opt.value}`,
-            children: /* @__PURE__ */ jsx(Text, { style: [controlStyles.optionText, { color: active ? colors.brand : colors.text, fontWeight: active ? ACTIVE_WEIGHT : IDLE_WEIGHT }], children: opt.label })
-          },
-          opt.value
-        );
-      }) })
+      children: [
+        isListbox ? /* @__PURE__ */ jsx(Text, { role: "status", style: statusText !== void 0 ? [controlStyles.option, controlStyles.optionText, { color: colors.text }] : void 0, children: statusText ?? "" }) : null,
+        /* @__PURE__ */ jsx(ScrollView, { keyboardShouldPersistTaps: "handled", nestedScrollEnabled: true, children: isListbox ? listboxBody : rows })
+      ]
     }
   );
   if (usePortal && IS_WEB4) return createPortal(menu, document.body);
@@ -1249,7 +1370,7 @@ function chipIdentity(option, selected, config) {
     ariaChecked: isRadio ? selected : void 0
   };
 }
-var styles7 = StyleSheet.create({
+var styles8 = StyleSheet.create({
   chipContainer: {
     flexDirection: "row",
     flexWrap: "wrap",
@@ -1335,7 +1456,7 @@ var ChipSelector = ({
         View,
         {
           accessibilityRole: isRadioGroup ? "radiogroup" : void 0,
-          style: styles7.chipContainer,
+          style: styles8.chipContainer,
           ...webFieldA11y({ describedById, hasError }),
           ...radio.groupProps,
           children: options.map(renderChip)
@@ -1345,7 +1466,7 @@ var ChipSelector = ({
   );
 };
 var DESCRIPTION_FONT_SIZE2 = 12;
-var styles8 = StyleSheet.create({
+var styles9 = StyleSheet.create({
   container: {
     flexDirection: "row",
     justifyContent: "space-between",
@@ -1406,15 +1527,15 @@ var FormSwitch = ({
         accessible: false,
         disabled,
         onPress: toggle,
-        style: [styles8.container, containerStyle],
+        style: [styles9.container, containerStyle],
         tabIndex: -1,
         testID: `${testID}-row`,
         children: [
-          /* @__PURE__ */ jsxs(View, { style: styles8.textColumn, children: [
-            /* @__PURE__ */ jsx(Text, { style: [styles8.label, themeStyles.label], children: label }),
-            hasDescription ? /* @__PURE__ */ jsx(Text, { style: [styles8.description, themeStyles.description], children: description }) : null
+          /* @__PURE__ */ jsxs(View, { style: styles9.textColumn, children: [
+            /* @__PURE__ */ jsx(Text, { style: [styles9.label, themeStyles.label], children: label }),
+            hasDescription ? /* @__PURE__ */ jsx(Text, { style: [styles9.description, themeStyles.description], children: description }) : null
           ] }),
-          /* @__PURE__ */ jsx(View, { pointerEvents: "none", style: styles8.switchSlot, testID: `${testID}-hitbox`, children: /* @__PURE__ */ jsx(
+          /* @__PURE__ */ jsx(View, { pointerEvents: "none", style: styles9.switchSlot, testID: `${testID}-hitbox`, children: /* @__PURE__ */ jsx(
             Switch,
             {
               accessibilityHint: accessibilityHint ?? label,
@@ -1443,7 +1564,7 @@ var DISABLED_OPACITY = 0.5;
 var FOCUS_RING_WIDTH = 2;
 var WEB_NO_DEFAULT_OUTLINE = { outlineStyle: "none" };
 var FOCUS_RING_INSET = -6;
-var styles9 = StyleSheet.create({
+var styles10 = StyleSheet.create({
   container: {
     flexDirection: "row",
     alignItems: "flex-start",
@@ -1548,8 +1669,8 @@ var FormCheckbox = ({
       onPress: toggle,
       role: "checkbox",
       style: [
-        styles9.container,
-        hasHint ? null : styles9.centered,
+        styles10.container,
+        hasHint ? null : styles10.centered,
         containerStyle,
         disabled ? { opacity: DISABLED_OPACITY } : null,
         Platform.OS === "web" ? WEB_NO_DEFAULT_OUTLINE : null
@@ -1557,13 +1678,13 @@ var FormCheckbox = ({
       testID,
       ...keyboardProps,
       children: [
-        /* @__PURE__ */ jsxs(View, { style: [styles9.box, value ? themeStyles.boxOn : themeStyles.boxOff], testID: `${testID}-box`, children: [
-          focused ? /* @__PURE__ */ jsx(View, { pointerEvents: "none", style: [styles9.focusRing, themeStyles.ring], testID: `${testID}-focus-ring` }) : null,
-          value ? /* @__PURE__ */ jsx(Text, { style: [styles9.check, { color: colors.surface }], accessibilityElementsHidden: true, children: "\u2713" }) : null
+        /* @__PURE__ */ jsxs(View, { style: [styles10.box, value ? themeStyles.boxOn : themeStyles.boxOff], testID: `${testID}-box`, children: [
+          focused ? /* @__PURE__ */ jsx(View, { pointerEvents: "none", style: [styles10.focusRing, themeStyles.ring], testID: `${testID}-focus-ring` }) : null,
+          value ? /* @__PURE__ */ jsx(Text, { style: [styles10.check, { color: colors.surface }], accessibilityElementsHidden: true, children: "\u2713" }) : null
         ] }),
-        /* @__PURE__ */ jsxs(View, { style: styles9.textColumn, children: [
-          /* @__PURE__ */ jsx(Text, { style: [styles9.label, themeStyles.label], children: label }),
-          hasHint ? /* @__PURE__ */ jsx(Text, { nativeID: hintId, style: [styles9.hint, themeStyles.hint], children: hintText }) : null
+        /* @__PURE__ */ jsxs(View, { style: styles10.textColumn, children: [
+          /* @__PURE__ */ jsx(Text, { style: [styles10.label, themeStyles.label], children: label }),
+          hasHint ? /* @__PURE__ */ jsx(Text, { nativeID: hintId, style: [styles10.hint, themeStyles.hint], children: hintText }) : null
         ] })
       ]
     }
@@ -1638,6 +1759,24 @@ function SelectControl({
     ) : null
   ] });
 }
+var CLOSE_DELAY_MS2 = 140;
+function useDelayedBlurClose(open, close) {
+  const timerRef = useRef(null);
+  const cancelClose = useCallback(() => {
+    if (timerRef.current !== null) clearTimeout(timerRef.current);
+    timerRef.current = null;
+  }, []);
+  useEffect(() => cancelClose, [cancelClose]);
+  const handleFocus = useCallback(() => {
+    cancelClose();
+    open();
+  }, [cancelClose, open]);
+  const handleBlur = useCallback(() => {
+    cancelClose();
+    timerRef.current = setTimeout(close, CLOSE_DELAY_MS2);
+  }, [cancelClose, close]);
+  return { handleFocus, handleBlur };
+}
 
 // src/controls/suggestOptions.ts
 var RANK_VALUE_EXACT = 0;
@@ -1670,94 +1809,212 @@ function isUnmatched(options, text) {
   if (needle === "") return false;
   return !options.some((o) => o.value.toLowerCase() === needle || o.label.toLowerCase() === needle);
 }
-var CLOSE_DELAY_MS2 = 140;
-var DEFAULT_TYPEAHEAD_MIN_CHARS = 1;
-var DEFAULT_TYPEAHEAD_MAX_SUGGESTIONS = 8;
-function TypeaheadControl({
-  options,
-  value,
-  onChange,
-  onSubmit,
-  placeholder,
-  accessibilityLabel,
-  accessibilityHint,
-  optionHint = "",
-  error,
-  minChars = DEFAULT_TYPEAHEAD_MIN_CHARS,
-  maxSuggestions = DEFAULT_TYPEAHEAD_MAX_SUGGESTIONS,
-  style,
-  testID
-}) {
-  const { theme } = useUi();
-  const { colors, palette } = theme;
-  const anchorRef = useRef(null);
+var DEFAULT_TYPEAHEAD_DEBOUNCE_MS = 250;
+var IDLE = { results: [], isLoading: false, hasFailed: false, hasSettled: false };
+function useTypeaheadSearch(load, query, enabled, debounceMs) {
+  const [state, setState] = useState(IDLE);
+  const loadRef = useRef(load);
+  loadRef.current = load;
+  useEffect(() => {
+    if (!enabled) {
+      setState(IDLE);
+      return void 0;
+    }
+    setState((current) => ({ ...current, isLoading: true, hasFailed: false }));
+    const controller = new AbortController();
+    const settle = (next) => {
+      if (!controller.signal.aborted) setState(next);
+    };
+    const timer = setTimeout(() => {
+      Promise.resolve().then(() => loadRef.current?.(query, controller.signal) ?? []).then(
+        (results) => settle({ results, isLoading: false, hasFailed: false, hasSettled: true }),
+        () => settle({ results: [], isLoading: false, hasFailed: true, hasSettled: true })
+      );
+    }, debounceMs);
+    return () => {
+      clearTimeout(timer);
+      controller.abort();
+    };
+  }, [query, enabled, debounceMs]);
+  return state;
+}
+
+// src/TypeaheadControl/hooks/useTypeaheadState.ts
+var NO_HIGHLIGHT = -1;
+var FORWARD = 1;
+var BACKWARD = -1;
+var NO_ROWS = [];
+function nextHighlight(current, count, delta) {
+  if (count === 0) return NO_HIGHLIGHT;
+  if (current === NO_HIGHLIGHT) return delta > 0 ? 0 : count - 1;
+  return (current + delta + count) % count;
+}
+function searchStatusText(found, search) {
+  if (found.hasFailed) return search.errorText;
+  if (found.results.length > 0) return void 0;
+  if (found.isLoading) return search.loadingText;
+  return found.hasSettled ? search.emptyText : void 0;
+}
+function useTypeaheadRows(input, isOpen, isPicked) {
+  const { options, search, value, minChars, maxSuggestions } = input;
+  const query = value.trim();
+  const isSearching = search !== void 0 && isOpen && !isPicked && query.length >= minChars;
+  const found = useTypeaheadSearch(search?.load, query, isSearching, search?.debounceMs ?? DEFAULT_TYPEAHEAD_DEBOUNCE_MS);
+  const staticRows = useMemo(() => {
+    if (options === void 0 || options.some((o) => o.label === value)) return NO_ROWS;
+    return suggestOptions(options, value, minChars, maxSuggestions);
+  }, [options, value, minChars, maxSuggestions]);
+  const foundRows = useMemo(() => found.results.slice(0, maxSuggestions), [found.results, maxSuggestions]);
+  if (search === void 0) return { rows: staticRows, statusText: void 0 };
+  return { rows: foundRows, statusText: searchStatusText(found, search) };
+}
+function useTypeaheadState(input) {
+  const { search, value, onChange, onSubmit } = input;
   const [isOpen, setIsOpen] = useState(false);
-  const exactPick = useMemo(() => options.some((o) => o.label === value), [options, value]);
-  const suggestions = useMemo(
-    () => exactPick ? [] : suggestOptions(options, value, minChars, maxSuggestions),
-    [exactPick, options, value, minChars, maxSuggestions]
+  const [picked, setPicked] = useState(null);
+  const [highlightIndex, setHighlightIndex] = useState(NO_HIGHLIGHT);
+  const { rows, statusText } = useTypeaheadRows(input, isOpen, picked !== null && picked.label === value);
+  const rowKey = rows.map((row) => row.value).join("\n");
+  const highlighted = isOpen ? rows[highlightIndex] : void 0;
+  useEffect(() => setHighlightIndex(NO_HIGHLIGHT), [rowKey]);
+  useEffect(() => setPicked((current) => current !== null && current.label !== value ? null : current), [value]);
+  const open = useCallback(() => setIsOpen(true), []);
+  const close = useCallback(() => {
+    setIsOpen(false);
+    setHighlightIndex(NO_HIGHLIGHT);
+  }, []);
+  const pick = useCallback(
+    (option) => {
+      setPicked(option);
+      onChange(option.label);
+      search?.onPick(option);
+      close();
+    },
+    [onChange, search, close]
+  );
+  const selectValue = useCallback(
+    (optionValue) => {
+      const option = rows.find((row) => row.value === optionValue);
+      if (option !== void 0) pick(option);
+    },
+    [rows, pick]
   );
-  const showMenu = isOpen && suggestions.length > 0;
   const handleChange = useCallback(
     (next) => {
+      if (picked !== null) {
+        setPicked(null);
+        search?.onPick(null);
+      }
       onChange(next);
       setIsOpen(true);
+      setHighlightIndex(NO_HIGHLIGHT);
     },
-    [onChange]
-  );
-  const pick = useCallback(
-    (optionValue) => {
-      const opt = options.find((o) => o.value === optionValue);
-      onChange(opt?.label ?? optionValue);
-      setIsOpen(false);
-    },
-    [options, onChange]
+    [picked, search, onChange]
   );
-  const handleBlur = useCallback(() => {
-    setTimeout(() => setIsOpen(false), CLOSE_DELAY_MS2);
-  }, []);
+  const handleKeyPress = useTypeaheadKeys({ rowCount: rows.length, isOpen, highlighted, setIsOpen, setHighlightIndex, close, pick });
   const handleSubmit = useCallback(() => {
-    setIsOpen(false);
+    if (highlighted !== void 0) {
+      pick(highlighted);
+      return;
+    }
+    close();
     onSubmit?.();
-  }, [onSubmit]);
+  }, [highlighted, pick, close, onSubmit]);
+  return { rows, statusText, isOpen, picked, highlighted, open, close, selectValue, handleChange, handleKeyPress, handleSubmit };
+}
+function useTypeaheadKeys(input) {
+  const { rowCount, isOpen, highlighted, setIsOpen, setHighlightIndex, close, pick } = input;
+  return useCallback(
+    (event) => {
+      const { key } = event.nativeEvent;
+      if (key === "ArrowDown" || key === "ArrowUp") {
+        event.preventDefault();
+        setIsOpen(true);
+        setHighlightIndex((current) => nextHighlight(current, rowCount, key === "ArrowDown" ? FORWARD : BACKWARD));
+      } else if (key === "Escape" && isOpen) {
+        event.preventDefault();
+        close();
+      } else if (key === "Enter" && highlighted !== void 0) {
+        event.preventDefault();
+        pick(highlighted);
+      }
+    },
+    [rowCount, isOpen, highlighted, setIsOpen, setHighlightIndex, close, pick]
+  );
+}
+var DEFAULT_TYPEAHEAD_MIN_CHARS = 1;
+var DEFAULT_TYPEAHEAD_MAX_SUGGESTIONS = 8;
+function comboboxAria(testID, isExpanded, highlighted) {
+  return {
+    role: "combobox",
+    "aria-autocomplete": "list",
+    "aria-expanded": isExpanded,
+    "aria-controls": isExpanded ? listboxDomId(testID) : void 0,
+    "aria-activedescendant": highlighted !== void 0 ? optionDomId(testID, highlighted.value) : void 0
+  };
+}
+function TypeaheadControlImpl(props, ref) {
+  const { value, onChange, onSubmit, placeholder, accessibilityLabel, accessibilityHint, optionHint = "", error, minChars = DEFAULT_TYPEAHEAD_MIN_CHARS, style, testID } = props;
+  const { id, describedById } = props;
+  const search = "search" in props ? props.search : void 0;
+  const options = "options" in props ? props.options : void 0;
+  const maxSuggestions = ("search" in props ? props.search.maxResults : props.maxSuggestions) ?? DEFAULT_TYPEAHEAD_MAX_SUGGESTIONS;
+  const { theme } = useUi();
+  const { colors, palette } = theme;
+  const anchorRef = useRef(null);
+  const state = useTypeaheadState({ options, search, value, minChars, maxSuggestions, onChange, onSubmit });
+  const { handleFocus, handleBlur } = useDelayedBlurClose(state.open, state.close);
+  const showMenu = state.isOpen && (state.rows.length > 0 || state.statusText !== void 0);
+  const isExpanded = state.isOpen && state.rows.length > 0;
   const hasError = error !== void 0 && error !== "";
+  useKeepAnchorInRoom(anchorRef, search?.scrollMarginTop ?? 0, search !== void 0 && state.isOpen);
   return /* @__PURE__ */ jsxs(View, { ref: anchorRef, style: [controlStyles.anchor, style], children: [
     /* @__PURE__ */ jsx(
       TextInput,
       {
+        ref,
+        id,
+        ...comboboxAria(testID, isExpanded, state.highlighted),
+        ...webFieldA11y({ describedById }),
         accessibilityLabel,
         accessibilityHint,
         autoCapitalize: "none",
+        autoComplete: "off",
         autoCorrect: false,
+        blurOnSubmit: search === void 0,
         placeholder,
         placeholderTextColor: colors.textSecondary,
         spellCheck: false,
         value,
-        onChangeText: handleChange,
-        onFocus: () => setIsOpen(true),
+        onChangeText: state.handleChange,
+        onFocus: handleFocus,
         onBlur: handleBlur,
-        onSubmitEditing: handleSubmit,
+        onKeyPress: state.handleKeyPress,
+        onSubmitEditing: state.handleSubmit,
         style: [controlStyles.input, { borderColor: hasError ? fieldErrorInk(theme) : colors.border, backgroundColor: colors.surface, color: colors.text }],
-        testID: `${testID}-input`
+        testID: search?.inputTestID ?? `${testID}-input`
       }
     ),
     showMenu ? /* @__PURE__ */ jsx(
       AnchoredMenu,
       {
-        options: suggestions,
-        selectedValue: value,
-        onSelect: pick,
-        onDismiss: () => setIsOpen(false),
-        colors: { text: colors.text, border: colors.border, surface: colors.surface, brand: palette.primary["500"] },
+        accessibilityLabel,
+        options: state.rows,
+        selectedValue: search !== void 0 ? state.picked?.value ?? "" : value,
+        onSelect: state.selectValue,
+        onDismiss: state.close,
+        colors: { text: colors.text, textSecondary: colors.textSecondary, border: colors.border, surface: colors.surface, brand: palette.primary["500"] },
         optionHint,
         testID,
         anchorRef,
+        listbox: { highlightedValue: state.highlighted?.value ?? "", statusText: state.statusText },
         usePortal: true
       }
     ) : null,
     hasError ? /* @__PURE__ */ jsx(Text, { role: "alert", style: [controlStyles.error, { color: fieldErrorInk(theme) }], testID: `${testID}-error`, children: error }) : null
   ] });
 }
+var TypeaheadControl = forwardRef(TypeaheadControlImpl);
 var WEB_DATE_PROPS = typeof document !== "undefined" ? { type: "date" } : {};
 function DateInput(p) {
   return /* @__PURE__ */ jsxs(View, { style: controlStyles.dateCol, children: [
@@ -1858,7 +2115,7 @@ var ROW_GAP = 4;
 var TAB_PADDING = 4;
 var INDICATOR_WIDTH = 2;
 var TAB_FONT_SIZE = 12;
-var styles10 = StyleSheet.create({
+var styles11 = StyleSheet.create({
   row: { flexDirection: "row", flexWrap: "nowrap", gap: ROW_GAP },
   tab: {
     borderBottomWidth: INDICATOR_WIDTH,
@@ -1898,13 +2155,13 @@ var StepperTab = ({
       accessibilityRole: "tab",
       accessibilityState: { selected },
       "aria-selected": selected,
-      style: [styles10.tab, { borderBottomColor: indicator }, ring.ringStyle],
+      style: [styles11.tab, { borderBottomColor: indicator }, ring.ringStyle],
       testID,
       onBlur: ring.onBlur,
       onFocus: ring.onFocus,
       onPress: () => onStep(step.key),
       ...webKeyProps,
-      children: /* @__PURE__ */ jsx(Text, { style: [styles10.text, { color: theme.colors.text }, selected ? styles10.textSelected : void 0], children: step.label })
+      children: /* @__PURE__ */ jsx(Text, { style: [styles11.text, { color: theme.colors.text }, selected ? styles11.textSelected : void 0], children: step.label })
     }
   );
 };
@@ -1914,7 +2171,7 @@ var StepperTabs = ({
   onStep,
   stepHint,
   testID
-}) => /* @__PURE__ */ jsx(View, { accessibilityRole: "tablist", style: styles10.row, testID, children: steps.map((step) => /* @__PURE__ */ jsx(
+}) => /* @__PURE__ */ jsx(View, { accessibilityRole: "tablist", style: styles11.row, testID, children: steps.map((step) => /* @__PURE__ */ jsx(
   StepperTab,
   {
     hint: stepHint,
@@ -1933,7 +2190,7 @@ function resolveStepNeighbours(steps, current) {
   return { previous: steps[index - 1] ?? null, next: steps[index + 1] ?? null };
 }
 var ROW_GAP2 = 8;
-var styles11 = StyleSheet.create({
+var styles12 = StyleSheet.create({
   cell: { flex: 1, minWidth: 0 },
   row: { flexDirection: "row", gap: ROW_GAP2 }
 });
@@ -1945,8 +2202,8 @@ var StepperNav = ({
   testID
 }) => {
   const { previous, next } = resolveStepNeighbours(steps, current);
-  return /* @__PURE__ */ jsxs(View, { style: styles11.row, testID, children: [
-    /* @__PURE__ */ jsx(View, { style: styles11.cell, children: /* @__PURE__ */ jsx(
+  return /* @__PURE__ */ jsxs(View, { style: styles12.row, testID, children: [
+    /* @__PURE__ */ jsx(View, { style: styles12.cell, children: /* @__PURE__ */ jsx(
       Button,
       {
         fullWidth: true,
@@ -1962,7 +2219,7 @@ var StepperNav = ({
         }
       }
     ) }),
-    next === null ? null : /* @__PURE__ */ jsx(View, { style: styles11.cell, children: /* @__PURE__ */ jsx(
+    next === null ? null : /* @__PURE__ */ jsx(View, { style: styles12.cell, children: /* @__PURE__ */ jsx(
       Button,
       {
         fullWidth: true,
@@ -1976,12 +2233,29 @@ var StepperNav = ({
     ) })
   ] });
 };
+var STATUS_FONT = 16;
+var styles13 = StyleSheet.create({
+  line: { fontSize: STATUS_FONT }
+});
+function FormStatusLine({ message, testID, style }) {
+  const { theme } = useUi();
+  if (message === null || message === void 0 || message === "") return null;
+  return /* @__PURE__ */ jsx(Text, { role: "alert", style: [styles13.line, { color: theme.colors.text }, style], testID, children: message });
+}
+function useFocusFirstInvalid(refs) {
+  const latest = useRef(refs);
+  latest.current = refs;
+  return useCallback((invalid) => {
+    const first = invalid.map((field) => latest.current[field].current).find((node) => node !== null);
+    first?.focus();
+  }, []);
+}
 var DEFAULT_PREVIEW_PX = 48;
 var PREVIEW_RADIUS = 8;
 var GAP = 8;
 var TITLE_FONT_SIZE = 14;
 var HELP_FONT_SIZE = 13;
-var styles12 = StyleSheet.create({
+var styles14 = StyleSheet.create({
   help: { flex: 1, fontSize: HELP_FONT_SIZE },
   root: { gap: GAP },
   tile: { alignItems: "center", flexDirection: "row", gap: GAP },
@@ -2003,11 +2277,11 @@ var UploadWithLinkField = ({
   const url = value ?? "";
   const [pasting, setPasting] = useState(url !== "");
   const previewBox = { borderRadius: PREVIEW_RADIUS, height: previewSize, width: previewSize };
-  return /* @__PURE__ */ jsxs(View, { style: styles12.root, children: [
-    /* @__PURE__ */ jsx(Text, { style: [styles12.title, { color: theme.colors.text }], children: labels.title }),
-    /* @__PURE__ */ jsxs(View, { style: styles12.tile, children: [
+  return /* @__PURE__ */ jsxs(View, { style: styles14.root, children: [
+    /* @__PURE__ */ jsx(Text, { style: [styles14.title, { color: theme.colors.text }], children: labels.title }),
+    /* @__PURE__ */ jsxs(View, { style: styles14.tile, children: [
       url === "" ? /* @__PURE__ */ jsx(View, { style: [previewBox, { backgroundColor: theme.colors.border }] }) : /* @__PURE__ */ jsx(Image, { accessible: false, source: { uri: url }, style: previewBox, testID: `${testID}-preview` }),
-      labels.help === void 0 ? null : /* @__PURE__ */ jsx(Text, { style: [styles12.help, { color: theme.colors.text }], children: labels.help })
+      labels.help === void 0 ? null : /* @__PURE__ */ jsx(Text, { style: [styles14.help, { color: theme.colors.text }], children: labels.help })
     ] }),
     uploadControl,
     /* @__PURE__ */ jsx(
@@ -2018,12 +2292,12 @@ var UploadWithLinkField = ({
         accessibilityRole: "button",
         accessibilityState: { expanded: pasting },
         "aria-expanded": pasting,
-        style: [styles12.toggle, ring.ringStyle],
+        style: [styles14.toggle, ring.ringStyle],
         testID: `${testID}-paste`,
         onBlur: ring.onBlur,
         onFocus: ring.onFocus,
         onPress: () => setPasting(!pasting),
-        children: /* @__PURE__ */ jsx(Text, { style: [styles12.toggleText, { color: theme.colors.text }], children: labels.pasteToggle })
+        children: /* @__PURE__ */ jsx(Text, { style: [styles14.toggleText, { color: theme.colors.text }], children: labels.pasteToggle })
       }
     ),
     pasting ? /* @__PURE__ */ jsx(
@@ -2041,6 +2315,6 @@ var UploadWithLinkField = ({
   ] });
 };
 
-export { AlignToControl, AnchoredMenu, ChipSelector, DEFAULT_MAX_RECENTS, DEFAULT_OPTIONAL_LABEL, DEFAULT_TYPEAHEAD_MAX_SUGGESTIONS, DEFAULT_TYPEAHEAD_MIN_CHARS, DateRangeControl, Field, FormActions, FormCell, FormCheckbox, FormField, FormGrid, FormSection, FormSwitch, INLINE_FIELD_ROW_MIN_WIDTH, InlineFieldRow, SelectControl, StepperNav, StepperTabs, ThemedTextInput, TypeaheadControl, UploadWithLinkField, controlStyles, groupAriaChecked, inlineFieldRowLayout, isUnmatched, resolveGroupSelection, resolveStepNeighbours, suggestOptions, toggleGroupSelection, useRecentValues, useThemedInput };
+export { AlignToControl, AnchoredMenu, ChipSelector, DEFAULT_MAX_RECENTS, DEFAULT_OPTIONAL_LABEL, DEFAULT_TYPEAHEAD_MAX_SUGGESTIONS, DEFAULT_TYPEAHEAD_MIN_CHARS, DateRangeControl, Field, FormActions, FormCell, FormCheckbox, FormField, FormGrid, FormSection, FormStatusLine, FormSwitch, INLINE_FIELD_ROW_MIN_WIDTH, InlineFieldRow, SelectControl, StepperNav, StepperTabs, ThemedTextInput, TypeaheadControl, UploadWithLinkField, controlStyles, groupAriaChecked, inlineFieldRowLayout, isUnmatched, resolveGroupSelection, resolveStepNeighbours, suggestOptions, toggleGroupSelection, useFocusFirstInvalid, useRecentValues, useThemedInput };
 //# sourceMappingURL=index.mjs.map
 //# sourceMappingURL=index.mjs.map