@coinbase/cds-web 9.26.1 → 9.27.0

package/CHANGELOG.md

@@ -1,3 +1,24 @@
+## 9.27.0 (2026-09-18)
+
+### 🚀 Features
+
+- Feat: add native-style typeahead keyboard selection to the web `Select (Alpha)`, supporting a multi-character search buffer, repeated-key cycling, and matching both when the listbox is open and closed.
+
+### 🩹 Fixes
+
+- Fix: constrain the MCP server's `get-cds-doc` tool to files inside its bundled `mcp-docs` directory. Routes that resolve outside of it are now reported as not found.
+
+## 9.26.2 (2026-09-11)
+
+### 🩹 Fixes
+
+- Fix: vertically align the helper-text error icon with the text in web and mobile inputs.
+- Fix: dismiss the Android soft keyboard when the mobile `TextInput` unmounts while focused.
+
+### 🧱 Updated Dependencies
+
+- Updated illustrations to 4.48.1
+
 ## 9.26.1 (2026-09-03)
 
 ### 🩹 Fixes

package/dts/alpha/select/Select.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Select.d.ts","sourceRoot":"","sources":["../../../src/alpha/select/Select.tsx"],"names":[],"mappings":"AAUA,OAAO,EAAiC,KAAK,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAgB/F,OAAO,EAEL,KAAK,mBAAmB,EACxB,KAAK,WAAW,EAChB,KAAK,UAAU,EAChB,MAAM,SAAS,CAAC;AAGjB,YAAY,EACV,eAAe,EACf,sBAAsB,EACtB,kBAAkB,EAClB,uBAAuB,EACvB,mBAAmB,EACnB,mCAAmC,EACnC,+BAA+B,EAC/B,YAAY,EACZ,qBAAqB,EACrB,oBAAoB,EACpB,iBAAiB,EACjB,0BAA0B,EAC1B,yBAAyB,EACzB,sBAAsB,EACtB,iBAAiB,EACjB,WAAW,EACX,UAAU,EACV,UAAU,GACX,MAAM,SAAS,CAAC;AAGjB,OAAO,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC;AAE9C,eAAO,MAAM,yBAAyB,EAAE,mBAAmB,CAAC,oBAAoB,CAG/E,CAAC;AAEF,MAAM,MAAM,SAAS,GAAG,WAAW,GACjC,IAAI,CAAC,WAAW,EAAE,MAAM,GAAG,SAAS,CAAC,GAAG;IACtC,IAAI,EAAE,iBAAiB,CAAC,MAAM,CAAC,CAAC;CACjC,CAAC;AAEJ,KAAK,eAAe,GAAG,CACrB,IAAI,SAAS,UAAU,GAAG,QAAQ,EAClC,iBAAiB,SAAS,MAAM,GAAG,MAAM,EAEzC,KAAK,EAAE,WAAW,CAAC,IAAI,EAAE,iBAAiB,CAAC,GAAG;IAAE,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,SAAS,CAAC,CAAA;CAAE,KACzE,KAAK,CAAC,YAAY,CAAC;AAoUxB,eAAO,MAAM,MAAM,EAAiB,eAAe,CAAC"}
+{"version":3,"file":"Select.d.ts","sourceRoot":"","sources":["../../../src/alpha/select/Select.tsx"],"names":[],"mappings":"AACA,OAAO,EAAiC,KAAK,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAgB/F,OAAO,EAEL,KAAK,mBAAmB,EACxB,KAAK,WAAW,EAChB,KAAK,UAAU,EAChB,MAAM,SAAS,CAAC;AAIjB,YAAY,EACV,eAAe,EACf,sBAAsB,EACtB,kBAAkB,EAClB,uBAAuB,EACvB,mBAAmB,EACnB,mCAAmC,EACnC,+BAA+B,EAC/B,YAAY,EACZ,qBAAqB,EACrB,oBAAoB,EACpB,iBAAiB,EACjB,0BAA0B,EAC1B,yBAAyB,EACzB,sBAAsB,EACtB,iBAAiB,EACjB,WAAW,EACX,UAAU,EACV,UAAU,GACX,MAAM,SAAS,CAAC;AAGjB,OAAO,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC;AAE9C,eAAO,MAAM,yBAAyB,EAAE,mBAAmB,CAAC,oBAAoB,CAG/E,CAAC;AAEF,MAAM,MAAM,SAAS,GAAG,WAAW,GACjC,IAAI,CAAC,WAAW,EAAE,MAAM,GAAG,SAAS,CAAC,GAAG;IACtC,IAAI,EAAE,iBAAiB,CAAC,MAAM,CAAC,CAAC;CACjC,CAAC;AAEJ,KAAK,eAAe,GAAG,CACrB,IAAI,SAAS,UAAU,GAAG,QAAQ,EAClC,iBAAiB,SAAS,MAAM,GAAG,MAAM,EAEzC,KAAK,EAAE,WAAW,CAAC,IAAI,EAAE,iBAAiB,CAAC,GAAG;IAAE,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,SAAS,CAAC,CAAA;CAAE,KACzE,KAAK,CAAC,YAAY,CAAC;AAySxB,eAAO,MAAM,MAAM,EAAiB,eAAe,CAAC"}

package/dts/alpha/select/useTypeahead.d.ts

@@ -0,0 +1,45 @@
+export declare const TYPEAHEAD_RESET_MS = 500;
+export declare function isPrintableTypeaheadKey(key: string): boolean;
+export declare function isTypeaheadKeyEvent(event: React.KeyboardEvent | KeyboardEvent): boolean;
+export declare function normalizeOptionText(text: string | null | undefined): string;
+export declare function getTypeaheadMatchIndex(
+  labels: string[],
+  search: string,
+  currentIndex: number,
+): number;
+type ElementRef = {
+  current: HTMLElement | null;
+};
+export type UseTypeaheadOptions = {
+  /** Whether the items container is visible (open). */
+  areItemsVisible: boolean;
+  /** Setter used to reveal items when typing while hidden. */
+  setAreItemsVisible: (visible: boolean) => void;
+  /** Ref to the trigger element. */
+  triggerRef: ElementRef;
+  /** Ref to the container element that hosts the items. */
+  itemsContainerRef: ElementRef;
+  /** Role used to query item elements within the container. */
+  itemRole: string;
+  disabled?: boolean;
+  readOnly?: boolean;
+};
+export type UseTypeaheadResult = {
+  /** Attach to the control's `onKeyDown`; handles the closed-state type-to-open path. */
+  onControlKeyDown: (event: React.KeyboardEvent) => void;
+};
+/**
+ * Native `<select>`-style typeahead for the Select (Alpha). Printable keys build a short-lived
+ * buffer that focuses the matching option, both while closed (type-to-open) and open.
+ */
+export declare function useTypeahead({
+  areItemsVisible,
+  setAreItemsVisible,
+  triggerRef,
+  itemsContainerRef,
+  itemRole,
+  disabled,
+  readOnly,
+}: UseTypeaheadOptions): UseTypeaheadResult;
+export {};
+//# sourceMappingURL=useTypeahead.d.ts.map

package/dts/alpha/select/useTypeahead.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useTypeahead.d.ts","sourceRoot":"","sources":["../../../src/alpha/select/useTypeahead.ts"],"names":[],"mappings":"AAKA,eAAO,MAAM,kBAAkB,MAAM,CAAC;AAItC,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAE5D;AAID,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,KAAK,CAAC,aAAa,GAAG,aAAa,GAAG,OAAO,CAGvF;AAGD,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,CAE3E;AAID,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,MAAM,EAAE,EAChB,MAAM,EAAE,MAAM,EACd,YAAY,EAAE,MAAM,GACnB,MAAM,CAgBR;AAED,KAAK,UAAU,GAAG;IAAE,OAAO,EAAE,WAAW,GAAG,IAAI,CAAA;CAAE,CAAC;AAElD,MAAM,MAAM,mBAAmB,GAAG;IAChC,qDAAqD;IACrD,eAAe,EAAE,OAAO,CAAC;IACzB,4DAA4D;IAC5D,kBAAkB,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,CAAC;IAC/C,kCAAkC;IAClC,UAAU,EAAE,UAAU,CAAC;IACvB,yDAAyD;IACzD,iBAAiB,EAAE,UAAU,CAAC;IAC9B,6DAA6D;IAC7D,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG;IAC/B,uFAAuF;IACvF,gBAAgB,EAAE,CAAC,KAAK,EAAE,KAAK,CAAC,aAAa,KAAK,IAAI,CAAC;CACxD,CAAC;AAEF;;;GAGG;AACH,wBAAgB,YAAY,CAAC,EAC3B,eAAe,EACf,kBAAkB,EAClB,UAAU,EACV,iBAAiB,EACjB,QAAQ,EACR,QAAQ,EACR,QAAQ,GACT,EAAE,mBAAmB,GAAG,kBAAkB,CA+F1C"}

package/dts/controls/HelperText.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"HelperText.d.ts","sourceRoot":"","sources":["../../src/controls/HelperText.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAe,MAAM,OAAO,CAAC;AACpC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iCAAiC,CAAC;AAMjE,OAAO,EAAQ,KAAK,kBAAkB,EAAE,KAAK,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAEnF,MAAM,MAAM,eAAe,GAAG;IAC5B,+DAA+D;IAC/D,KAAK,CAAC,EAAE,SAAS,CAAC,KAAK,CAAC;IACxB,sDAAsD;IACtD,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,6CAA6C;IAC7C,2BAA2B,CAAC,EAAE,MAAM,CAAC;IACrC,iCAAiC;IACjC,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,+EAA+E;IAC/E,MAAM,CAAC,EAAE;QACP,wBAAwB;QACxB,IAAI,CAAC,EAAE,KAAK,CAAC,aAAa,CAAC;QAC3B,yBAAyB;QACzB,IAAI,CAAC,EAAE,KAAK,CAAC,aAAa,CAAC;KAC5B,CAAC;IACF,6EAA6E;IAC7E,UAAU,CAAC,EAAE;QACX,wBAAwB;QACxB,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,yBAAyB;QACzB,IAAI,CAAC,EAAE,MAAM,CAAC;KACf,CAAC;CACH,GAAG,SAAS,CAAC,kBAAkB,CAAC,CAAC;AAOlC,eAAO,MAAM,UAAU,6CAoDrB,CAAC"}
+{"version":3,"file":"HelperText.d.ts","sourceRoot":"","sources":["../../src/controls/HelperText.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAwB,MAAM,OAAO,CAAC;AAC7C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iCAAiC,CAAC;AAKjE,OAAO,EAAQ,KAAK,kBAAkB,EAAE,KAAK,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAEnF,MAAM,MAAM,eAAe,GAAG;IAC5B,+DAA+D;IAC/D,KAAK,CAAC,EAAE,SAAS,CAAC,KAAK,CAAC;IACxB,sDAAsD;IACtD,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,6CAA6C;IAC7C,2BAA2B,CAAC,EAAE,MAAM,CAAC;IACrC,iCAAiC;IACjC,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,+EAA+E;IAC/E,MAAM,CAAC,EAAE;QACP,wBAAwB;QACxB,IAAI,CAAC,EAAE,KAAK,CAAC,aAAa,CAAC;QAC3B,yBAAyB;QACzB,IAAI,CAAC,EAAE,KAAK,CAAC,aAAa,CAAC;KAC5B,CAAC;IACF,6EAA6E;IAC7E,UAAU,CAAC,EAAE;QACX,wBAAwB;QACxB,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,yBAAyB;QACzB,IAAI,CAAC,EAAE,MAAM,CAAC;KACf,CAAC;CACH,GAAG,SAAS,CAAC,kBAAkB,CAAC,CAAC;AAElC,eAAO,MAAM,UAAU,6CA8DrB,CAAC"}

package/esm/alpha/select/Select.js

@@ -3,7 +3,7 @@ function _objectSpread(e) { for (var r = 1; r < arguments.length; r++) { var t =
 function _defineProperty(e, r, t) { return (r = _toPropertyKey(r)) in e ? Object.defineProperty(e, r, { value: t, enumerable: !0, configurable: !0, writable: !0 }) : e[r] = t, e; }
 function _toPropertyKey(t) { var i = _toPrimitive(t, "string"); return "symbol" == typeof i ? i : i + ""; }
 function _toPrimitive(t, r) { if ("object" != typeof t || !t) return t; var e = t[Symbol.toPrimitive]; if (void 0 !== e) { var i = e.call(t, r || "default"); if ("object" != typeof i) return i; throw new TypeError("@@toPrimitive must return a primitive value."); } return ("string" === r ? String : Number)(t); }
-import { forwardRef, memo, useCallback, useEffect, useImperativeHandle, useMemo, useRef, useState } from 'react';
+import { forwardRef, memo, useImperativeHandle, useMemo, useRef, useState } from 'react';
 import { autoUpdate, flip, useFloating } from '@floating-ui/react-dom';
 import { cx } from '../../cx';
 import { useClickOutside } from '../../hooks/useClickOutside';
@@ -19,6 +19,7 @@ import { DefaultSelectEmptyDropdownContents } from './DefaultSelectEmptyDropdown
 import { DefaultSelectOption } from './DefaultSelectOption';
 import { DefaultSelectOptionGroup } from './DefaultSelectOptionGroup';
 import { defaultSelectSize } from './types';
+import { useTypeahead } from './useTypeahead';
 
 // Re-export all types for backward compatibility
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
@@ -29,6 +30,7 @@ export const defaultAccessibilityRoles = {
   option: 'option'
 };
 const SelectBase = /*#__PURE__*/memo(/*#__PURE__*/forwardRef((_props, ref) => {
+  var _accessibilityRoles$o;
   const mergedProps = useComponentConfig('Select', _props);
   const {
     value,
@@ -85,9 +87,7 @@ const SelectBase = /*#__PURE__*/memo(/*#__PURE__*/forwardRef((_props, ref) => {
     testID
   } = mergedProps;
   const hasMounted = useHasMounted();
-  // The dropdown keeps a binary density toggle instead of the t-shirt scale, so Select owns
-  // the translation: only the smallest control size renders a compact dropdown. The control
-  // still receives the raw `compact` because it needs it for legacy label placement.
+  // Dropdown density is binary, so only the smallest size renders compact.
   const dropdownCompact = (size !== null && size !== void 0 ? size : compact ? 's' : defaultSelectSize) === 's';
   const [openInternal, setOpenInternal] = useState(defaultOpen !== null && defaultOpen !== void 0 ? defaultOpen : false);
   const open = openProp !== null && openProp !== void 0 ? openProp : openInternal;
@@ -106,34 +106,18 @@ const SelectBase = /*#__PURE__*/memo(/*#__PURE__*/forwardRef((_props, ref) => {
     ref: refs.floating,
     excludeRefs: [refs.reference]
   });
-  const pendingTypeAheadKeyRef = useRef(null);
-  const handleControlKeyDown = useCallback(event => {
-    if (disabled || readOnly || open) return;
-    if (event.ctrlKey || event.metaKey || event.altKey) return;
-    const key = event.key;
-    if (/^[a-z]$/.test(key)) {
-      pendingTypeAheadKeyRef.current = key;
-      setOpen(true);
-    }
-  }, [disabled, readOnly, open, setOpen]);
-  useEffect(() => {
-    var _accessibilityRoles$o;
-    if (!open || !pendingTypeAheadKeyRef.current) return;
-    const key = pendingTypeAheadKeyRef.current;
-    pendingTypeAheadKeyRef.current = null;
-    const floatingEl = refs.floating.current;
-    if (!floatingEl) return;
-    const optionRole = (_accessibilityRoles$o = accessibilityRoles === null || accessibilityRoles === void 0 ? void 0 : accessibilityRoles.option) !== null && _accessibilityRoles$o !== void 0 ? _accessibilityRoles$o : 'option';
-    const options = floatingEl.querySelectorAll("[role=\"".concat(optionRole, "\"]"));
-    const matchingOption = Array.from(options).find(option => {
-      var _option$textContent, _firstLetterMatch$;
-      const firstLetterMatch = (_option$textContent = option.textContent) === null || _option$textContent === void 0 ? void 0 : _option$textContent.match(/[a-z]/i);
-      return (firstLetterMatch === null || firstLetterMatch === void 0 || (_firstLetterMatch$ = firstLetterMatch[0]) === null || _firstLetterMatch$ === void 0 ? void 0 : _firstLetterMatch$.toLowerCase()) === key;
-    });
-    if (matchingOption) {
-      matchingOption.focus();
-    }
-  }, [open, refs.floating, accessibilityRoles === null || accessibilityRoles === void 0 ? void 0 : accessibilityRoles.option]);
+  const optionRole = (_accessibilityRoles$o = accessibilityRoles === null || accessibilityRoles === void 0 ? void 0 : accessibilityRoles.option) !== null && _accessibilityRoles$o !== void 0 ? _accessibilityRoles$o : 'option';
+  const {
+    onControlKeyDown
+  } = useTypeahead({
+    areItemsVisible: open,
+    setAreItemsVisible: setOpen,
+    triggerRef: refs.reference,
+    itemsContainerRef: refs.floating,
+    itemRole: optionRole,
+    disabled,
+    readOnly
+  });
   const rootStyles = useMemo(() => _objectSpread(_objectSpread({}, style), styles === null || styles === void 0 ? void 0 : styles.root), [style, styles === null || styles === void 0 ? void 0 : styles.root]);
   const controlStyles = useMemo(() => ({
     controlStartNode: styles === null || styles === void 0 ? void 0 : styles.controlStartNode,
@@ -212,7 +196,7 @@ const SelectBase = /*#__PURE__*/memo(/*#__PURE__*/forwardRef((_props, ref) => {
       labelVariant: labelVariant,
       maxSelectedOptionsToShow: maxSelectedOptionsToShow,
       onChange: onChange,
-      onKeyDown: handleControlKeyDown,
+      onKeyDown: onControlKeyDown,
       open: open,
       options: options,
       placeholder: placeholder,

package/esm/alpha/select/useTypeahead.js

@@ -0,0 +1,121 @@
+import { useCallback, useEffect, useRef } from 'react';
+import { getBrowserGlobals } from '../../utils/browser';
+
+// ~500ms buffer reset, matching native `<select>`.
+export const TYPEAHEAD_RESET_MS = 500;
+const printableTypeaheadKeyRegex = /^[a-z0-9]$/i;
+export function isPrintableTypeaheadKey(key) {
+  return printableTypeaheadKeyRegex.test(key);
+}
+
+// Union accepts both React's synthetic event (control handler) and the native event (window listener).
+// Bare printable key, no modifier (shared by closed and open paths).
+export function isTypeaheadKeyEvent(event) {
+  if (event.ctrlKey || event.metaKey || event.altKey) return false;
+  return isPrintableTypeaheadKey(event.key);
+}
+
+// Strip leading non-alphanumerics (e.g. icon/checkbox glyphs) so prefixes match.
+export function normalizeOptionText(text) {
+  return (text !== null && text !== void 0 ? text : '').toLowerCase().replace(/^[^a-z0-9]+/, '');
+}
+
+// Native `<select>` semantics: a single (or repeated) char cycles options by first letter;
+// a multi-char buffer keeps the focused option while it still prefix-matches.
+export function getTypeaheadMatchIndex(labels, search, currentIndex) {
+  const total = labels.length;
+  if (!search || total === 0) return -1;
+  const isRepeatedChar = search.length > 1 && [...search].every(char => char === search[0]);
+  const query = isRepeatedChar ? search[0] : search;
+  const startOffset = query.length === 1 ? 1 : 0;
+  const startFrom = currentIndex < 0 ? 0 : currentIndex + startOffset;
+  for (let i = 0; i < total; i++) {
+    const index = (startFrom + i) % total;
+    if (labels[index].startsWith(query)) return index;
+  }
+  return -1;
+}
+/**
+ * Native `<select>`-style typeahead for the Select (Alpha). Printable keys build a short-lived
+ * buffer that focuses the matching option, both while closed (type-to-open) and open.
+ */
+export function useTypeahead(_ref) {
+  let {
+    areItemsVisible,
+    setAreItemsVisible,
+    triggerRef,
+    itemsContainerRef,
+    itemRole,
+    disabled,
+    readOnly
+  } = _ref;
+  const typeaheadBufferRef = useRef('');
+  const typeaheadResetTimeoutRef = useRef(null);
+  const pendingTypeaheadRef = useRef(false);
+  const appendToTypeaheadBuffer = useCallback(key => {
+    typeaheadBufferRef.current += key.toLowerCase();
+    if (typeaheadResetTimeoutRef.current) clearTimeout(typeaheadResetTimeoutRef.current);
+    typeaheadResetTimeoutRef.current = setTimeout(() => {
+      typeaheadBufferRef.current = '';
+    }, TYPEAHEAD_RESET_MS);
+  }, []);
+  const focusTypeaheadMatch = useCallback(() => {
+    var _getBrowserGlobals;
+    const search = typeaheadBufferRef.current;
+    if (!search) return;
+    const containerEl = itemsContainerRef.current;
+    if (!containerEl) return;
+    const optionElements = Array.from(containerEl.querySelectorAll("[role=\"".concat(itemRole, "\"]"))).filter(option => !option.disabled && option.getAttribute('aria-disabled') !== 'true');
+    if (optionElements.length === 0) return;
+    const labels = optionElements.map(option => normalizeOptionText(option.textContent));
+    const activeElement = (_getBrowserGlobals = getBrowserGlobals()) === null || _getBrowserGlobals === void 0 ? void 0 : _getBrowserGlobals.document.activeElement;
+    const currentIndex = activeElement ? optionElements.indexOf(activeElement) : -1;
+    const matchIndex = getTypeaheadMatchIndex(labels, search, currentIndex);
+    if (matchIndex >= 0) optionElements[matchIndex].focus();
+  }, [itemsContainerRef, itemRole]);
+  const onControlKeyDown = useCallback(event => {
+    // When items are visible, the window listener owns typeahead.
+    if (disabled || readOnly || areItemsVisible || !isTypeaheadKeyEvent(event)) return;
+    appendToTypeaheadBuffer(event.key);
+    pendingTypeaheadRef.current = true;
+    setAreItemsVisible(true);
+  }, [disabled, readOnly, areItemsVisible, setAreItemsVisible, appendToTypeaheadBuffer]);
+
+  // After a type-to-open, focus the match once the dropdown (and its options) have rendered.
+  useEffect(() => {
+    if (!areItemsVisible || !pendingTypeaheadRef.current) return;
+    pendingTypeaheadRef.current = false;
+    focusTypeaheadMatch();
+  }, [areItemsVisible, focusTypeaheadMatch]);
+
+  // Window listener needed: focus moves into the portaled dropdown, past the control's handler.
+  useEffect(() => {
+    if (!areItemsVisible || disabled || readOnly) return;
+    const globals = getBrowserGlobals();
+    if (!globals) return;
+    const {
+      window: browserWindow,
+      document: browserDocument
+    } = globals;
+    const handleWindowKeyDown = event => {
+      if (!isTypeaheadKeyEvent(event)) return;
+      const triggerElement = triggerRef.current;
+      const containerElement = itemsContainerRef.current;
+      const activeElement = browserDocument.activeElement;
+      const withinSelect = !!triggerElement && triggerElement.contains(activeElement) || !!containerElement && containerElement.contains(activeElement);
+      if (!withinSelect) return;
+      appendToTypeaheadBuffer(event.key);
+      focusTypeaheadMatch();
+    };
+    browserWindow.addEventListener('keydown', handleWindowKeyDown);
+    // A reset timeout is only ever pending during an open interaction, so clearing it here also
+    // covers unmount (no dedicated cleanup-only effect needed).
+    return () => {
+      browserWindow.removeEventListener('keydown', handleWindowKeyDown);
+      if (typeaheadResetTimeoutRef.current) clearTimeout(typeaheadResetTimeoutRef.current);
+    };
+  }, [areItemsVisible, disabled, readOnly, triggerRef, itemsContainerRef, appendToTypeaheadBuffer, focusTypeaheadMatch]);
+  return {
+    onControlKeyDown
+  };
+}

package/esm/controls/HelperText.js

@@ -1,4 +1,4 @@
-const _excluded = ["color", "id", "errorIconAccessibilityLabel", "errorIconTestID", "children", "dangerouslySetColor", "textAlign", "style", "styles", "className", "classNames"];
+const _excluded = ["color", "errorIconAccessibilityLabel", "errorIconTestID", "styles", "classNames"];
 function ownKeys(e, r) { var t = Object.keys(e); if (Object.getOwnPropertySymbols) { var o = Object.getOwnPropertySymbols(e); r && (o = o.filter(function (r) { return Object.getOwnPropertyDescriptor(e, r).enumerable; })), t.push.apply(t, o); } return t; }
 function _objectSpread(e) { for (var r = 1; r < arguments.length; r++) { var t = null != arguments[r] ? arguments[r] : {}; r % 2 ? ownKeys(Object(t), !0).forEach(function (r) { _defineProperty(e, r, t[r]); }) : Object.getOwnPropertyDescriptors ? Object.defineProperties(e, Object.getOwnPropertyDescriptors(t)) : ownKeys(Object(t)).forEach(function (r) { Object.defineProperty(e, r, Object.getOwnPropertyDescriptor(t, r)); }); } return e; }
 function _defineProperty(e, r, t) { return (r = _toPropertyKey(r)) in e ? Object.defineProperty(e, r, { value: t, enumerable: !0, configurable: !0, writable: !0 }) : e[r] = t, e; }
@@ -6,60 +6,64 @@ function _toPropertyKey(t) { var i = _toPrimitive(t, "string"); return "symbol"
 function _toPrimitive(t, r) { if ("object" != typeof t || !t) return t; var e = t[Symbol.toPrimitive]; if (void 0 !== e) { var i = e.call(t, r || "default"); if ("object" != typeof i) return i; throw new TypeError("@@toPrimitive must return a primitive value."); } return ("string" === r ? String : Number)(t); }
 function _objectWithoutProperties(e, t) { if (null == e) return {}; var o, r, i = _objectWithoutPropertiesLoose(e, t); if (Object.getOwnPropertySymbols) { var n = Object.getOwnPropertySymbols(e); for (r = 0; r < n.length; r++) o = n[r], -1 === t.indexOf(o) && {}.propertyIsEnumerable.call(e, o) && (i[o] = e[o]); } return i; }
 function _objectWithoutPropertiesLoose(r, e) { if (null == r) return {}; var t = {}; for (var n in r) if ({}.hasOwnProperty.call(r, n)) { if (-1 !== e.indexOf(n)) continue; t[n] = r[n]; } return t; }
-import React, { memo } from 'react';
+import React, { memo, useMemo } from 'react';
 import { cx } from '../cx';
 import { Icon } from '../icons/Icon';
-import { Box } from '../layout/Box';
+import { HStack } from '../layout/HStack';
 import { Text } from '../typography/Text';
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-const iconCss = "iconCss-i1ej5caw";
 export const HelperText = /*#__PURE__*/memo(function HelperTex(_ref) {
   let {
       color,
-      id,
       errorIconAccessibilityLabel,
       errorIconTestID,
-      children,
-      dangerouslySetColor,
-      textAlign = 'start',
-      style,
       styles,
-      className,
       classNames
     } = _ref,
     props = _objectWithoutProperties(_ref, _excluded);
-  const rootStyle = _objectSpread(_objectSpread({}, style), styles === null || styles === void 0 ? void 0 : styles.root);
+  const rootStyle = _objectSpread(_objectSpread({}, props.style), styles === null || styles === void 0 ? void 0 : styles.root);
   // TODO: when we actually remove dangerouslySetColor:
   // when migrating from dangerouslySetColor to style.color,
   // root style/className color will not automatically style the error icon like dangerouslySetColor.
   // Consumers must set both styles.root and styles.icon (or classNames equivalents).
   // We need to have a migrator handle this or document in future migration guide.
-  const iconStyle = styles === null || styles === void 0 ? void 0 : styles.icon;
-  return /*#__PURE__*/_jsxs(Text, _objectSpread(_objectSpread({
-    className: cx(className, classNames === null || classNames === void 0 ? void 0 : classNames.root),
-    color: color,
-    dangerouslySetColor: dangerouslySetColor,
-    display: "block",
-    font: "label2",
-    id: id,
-    style: rootStyle,
-    textAlign: textAlign
-  }, props), {}, {
-    children: [color === 'fgNegative' && /*#__PURE__*/_jsx(Box, {
-      as: "span",
-      className: iconCss,
-      children: /*#__PURE__*/_jsx(Icon, {
+  const iconStyle = useMemo(() => _objectSpread({
+    // Sit on the first line of label2, matching nested-text alignment.
+    marginTop: 'calc((var(--lineHeight-label2) - var(--iconSize-xs)) / 2)'
+  }, styles === null || styles === void 0 ? void 0 : styles.icon), [styles === null || styles === void 0 ? void 0 : styles.icon]);
+  const justifyContent = props.textAlign === 'end' ? 'flex-end' : props.textAlign === 'center' ? 'center' : 'flex-start';
+  if (color === 'fgNegative') {
+    return /*#__PURE__*/_jsxs(HStack, {
+      alignItems: "flex-start",
+      gap: 0.5,
+      justifyContent: justifyContent,
+      children: [/*#__PURE__*/_jsx(Icon, {
         active: true,
         accessibilityLabel: errorIconAccessibilityLabel,
         className: classNames === null || classNames === void 0 ? void 0 : classNames.icon,
         color: "fgNegative",
-        dangerouslySetColor: dangerouslySetColor,
+        dangerouslySetColor: props.dangerouslySetColor,
         name: "info",
         size: "xs",
         style: iconStyle,
         testID: errorIconTestID
-      })
-    }), children]
+      }), /*#__PURE__*/_jsx(Text, _objectSpread(_objectSpread({
+        color: color,
+        display: "block",
+        font: "label2"
+      }, props), {}, {
+        className: cx(props.className, classNames === null || classNames === void 0 ? void 0 : classNames.root),
+        flexShrink: 1,
+        style: rootStyle
+      }))]
+    });
+  }
+  return /*#__PURE__*/_jsx(Text, _objectSpread(_objectSpread({
+    color: color,
+    display: "block",
+    font: "label2"
+  }, props), {}, {
+    className: cx(props.className, classNames === null || classNames === void 0 ? void 0 : classNames.root),
+    style: rootStyle
   }));
-});
-import "./HelperText.css";
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coinbase/cds-web",
-  "version": "9.26.1",
+  "version": "9.27.0",
   "description": "Coinbase Design System - Web",
   "repository": {
     "type": "git",
@@ -227,9 +227,9 @@
     "react-dom": "^18.0.0 || ~19.1.2"
   },
   "dependencies": {
-    "@coinbase/cds-common": "^9.26.1",
-    "@coinbase/cds-icons": "^5.22.0",
-    "@coinbase/cds-illustrations": "^4.48.0",
+    "@coinbase/cds-common": "^9.27.0",
+    "@coinbase/cds-icons": "^5.25.0",
+    "@coinbase/cds-illustrations": "^4.48.1",
     "@coinbase/cds-lottie-files": "^3.3.4",
     "@coinbase/cds-utils": "^2.3.5",
     "@floating-ui/react-dom": "^2.1.1",

package/esm/controls/HelperText.css

@@ -1 +0,0 @@
-@layer cds{.iconCss-i1ej5caw{display:inline-block;padding-inline-end:var(--space-0_5);}}