From 54fc633af469a1422558790769dcfd5d609eb7e2 Mon Sep 17 00:00:00 2001
From: william garrity <wgarrity@mieweb.com>
Date: Thu, 23 Jul 2026 18:05:07 -0400
Subject: [PATCH 01/10] fix: prevent clipping of dropdowns, autocompletes, and
 floating menus

Add shared useAnchoredPosition hook that portals floating panels to
document.body with fixed positioning (vertical flip, viewport clamping,
max-height constraint, scroll/resize tracking, transitions suppressed so
position updates never animate). Migrate 14 components from inline
absolute or hand-rolled portal positioning. Extend useClickOutside to
accept multiple refs for portaled menus.
---
 src/components/Autocomplete/Autocomplete.tsx  | 151 +++++-----
 .../BookingDialog/BookingDialog.tsx           |  77 +++--
 .../BusinessHoursEditor.tsx                   |  53 ++--
 src/components/CodeLookup/CodeLookup.tsx      | 239 ++++++++--------
 src/components/CountBadge/CountBadge.tsx      | 196 ++++++++-----
 .../CountryCodeDropdown.tsx                   | 205 +++++++-------
 .../DateRangePicker/DateRangePicker.tsx       | 230 ++++++++-------
 src/components/Dropdown/Dropdown.tsx          | 195 +++++++------
 .../LanguageSelector/LanguageSelector.tsx     |  99 ++++---
 src/components/Messaging/MessageComposer.tsx  | 114 +++++---
 .../PatientHeader/PatientHeader.tsx           | 235 +++++++++-------
 .../ProviderSearchFilters.tsx                 | 230 ++++++++-------
 .../ProviderSelector/ProviderSelector.tsx     | 265 ++++++++++--------
 src/components/Select/Select.tsx              |  68 ++---
 src/hooks/index.ts                            |   6 +
 src/hooks/useAnchoredPosition.ts              | 212 ++++++++++++++
 src/hooks/useClickOutside.ts                  |  10 +-
 17 files changed, 1511 insertions(+), 1074 deletions(-)
 create mode 100644 src/hooks/useAnchoredPosition.ts

diff --git a/src/components/Autocomplete/Autocomplete.tsx b/src/components/Autocomplete/Autocomplete.tsx
index 9ab7d5dcb..b91eb614b 100644
--- a/src/components/Autocomplete/Autocomplete.tsx
+++ b/src/components/Autocomplete/Autocomplete.tsx
@@ -1,7 +1,9 @@
 import * as React from 'react';
+import { createPortal } from 'react-dom';
 import { type VariantProps } from 'class-variance-authority';
 import { cn } from '../../utils/cn';
 import { useClickOutside } from '../../hooks/useClickOutside';
+import { useAnchoredPosition } from '../../hooks/useAnchoredPosition';
 import { inputVariants } from '../Input';
 
 export interface AutocompleteProps<T> extends Pick<
@@ -120,15 +122,7 @@ function Autocomplete<T>({
   const containerRef = React.useRef<HTMLDivElement>(null);
   const listId = React.useId();
 
-  useClickOutside(containerRef, () => setOpen(false), open);
-
-  const setQuery = React.useCallback(
-    (next: string) => {
-      if (!isControlled) setUncontrolledValue(next);
-      onValueChange?.(next);
-    },
-    [isControlled, onValueChange]
-  );
+  const meetsMinLength = query.length >= minQueryLength;
 
   const filteredItems = React.useMemo(() => {
     if (!filter) return items;
@@ -149,11 +143,31 @@ function Autocomplete<T>({
     return itemRows;
   }, [filteredItems, showCreate, getItemKey]);
 
-  const meetsMinLength = query.length >= minQueryLength;
   const hasContent =
     rows.length > 0 || (meetsMinLength && emptyMessage != null);
   const isOpen = open && meetsMinLength && hasContent;
 
+  // Portal + fixed positioning so the listbox escapes overflow-hidden
+  // ancestors (cards, dialogs, scroll containers, …).
+  const { anchorRef, floatingRef, style } = useAnchoredPosition<
+    HTMLDivElement,
+    HTMLDivElement
+  >({ open: isOpen, matchWidth: true, maxHeight: 300 });
+
+  const outsideRefs = React.useMemo(
+    () => [containerRef, floatingRef],
+    [floatingRef]
+  );
+  useClickOutside(outsideRefs, () => setOpen(false), open);
+
+  const setQuery = React.useCallback(
+    (next: string) => {
+      if (!isControlled) setUncontrolledValue(next);
+      onValueChange?.(next);
+    },
+    [isControlled, onValueChange]
+  );
+
   React.useEffect(() => {
     if (!isOpen) setActiveIndex(-1);
   }, [isOpen]);
@@ -207,7 +221,10 @@ function Autocomplete<T>({
 
   return (
     <div
-      ref={containerRef}
+      ref={(node) => {
+        containerRef.current = node;
+        anchorRef.current = node;
+      }}
       data-slot="autocomplete"
       className={cn('relative', className)}
     >
@@ -234,60 +251,66 @@ function Autocomplete<T>({
         {...inputProps}
       />
 
-      {isOpen && (
-        <div
-          id={listId}
-          role="listbox"
-          data-slot="autocomplete-list"
-          className={cn(
-            'border-border absolute z-50 mt-1 w-full overflow-auto rounded-md border',
-            'bg-card text-card-foreground max-h-[300px] shadow-lg'
-          )}
-        >
-          {rows.length === 0
-            ? emptyMessage != null && (
-                <div
-                  data-slot="autocomplete-empty"
-                  className="text-muted-foreground px-4 py-3 text-sm"
-                >
-                  {emptyMessage}
-                </div>
-              )
-            : rows.map((row, index) => {
-                const isActive = index === activeIndex;
-                const optionId = `${listId}-opt-${row.key}`;
-                return (
-                  <button
-                    key={row.key}
-                    id={optionId}
-                    type="button"
-                    role="option"
-                    aria-selected={isActive}
-                    data-slot={
-                      row.kind === 'create'
-                        ? 'autocomplete-create'
-                        : 'autocomplete-option'
-                    }
-                    onMouseEnter={() => setActiveIndex(index)}
-                    onMouseDown={(e) => e.preventDefault()}
-                    onClick={() => commitRow(row)}
-                    className={cn(
-                      'w-full px-4 py-3 text-left text-sm transition-colors',
-                      'border-border border-b last:border-b-0',
-                      'focus:outline-none',
-                      isActive ? 'bg-muted text-foreground' : 'hover:bg-muted',
-                      row.kind === 'create' &&
-                        'text-primary-800 flex items-center gap-2 font-medium'
-                    )}
+      {isOpen &&
+        createPortal(
+          <div
+            ref={floatingRef}
+            style={style}
+            id={listId}
+            role="listbox"
+            data-slot="autocomplete-list"
+            className={cn(
+              'border-border overflow-auto rounded-md border',
+              'bg-card text-card-foreground shadow-lg'
+            )}
+          >
+            {rows.length === 0
+              ? emptyMessage != null && (
+                  <div
+                    data-slot="autocomplete-empty"
+                    className="text-muted-foreground px-4 py-3 text-sm"
                   >
-                    {row.kind === 'create'
-                      ? createLabel!(query)
-                      : renderItem(row.item)}
-                  </button>
-                );
-              })}
-        </div>
-      )}
+                    {emptyMessage}
+                  </div>
+                )
+              : rows.map((row, index) => {
+                  const isActive = index === activeIndex;
+                  const optionId = `${listId}-opt-${row.key}`;
+                  return (
+                    <button
+                      key={row.key}
+                      id={optionId}
+                      type="button"
+                      role="option"
+                      aria-selected={isActive}
+                      data-slot={
+                        row.kind === 'create'
+                          ? 'autocomplete-create'
+                          : 'autocomplete-option'
+                      }
+                      onMouseEnter={() => setActiveIndex(index)}
+                      onMouseDown={(e) => e.preventDefault()}
+                      onClick={() => commitRow(row)}
+                      className={cn(
+                        'w-full px-4 py-3 text-left text-sm transition-colors',
+                        'border-border border-b last:border-b-0',
+                        'focus:outline-none',
+                        isActive
+                          ? 'bg-muted text-foreground'
+                          : 'hover:bg-muted',
+                        row.kind === 'create' &&
+                          'text-primary-800 flex items-center gap-2 font-medium'
+                      )}
+                    >
+                      {row.kind === 'create'
+                        ? createLabel!(query)
+                        : renderItem(row.item)}
+                    </button>
+                  );
+                })}
+          </div>,
+          document.body
+        )}
     </div>
   );
 }
diff --git a/src/components/BookingDialog/BookingDialog.tsx b/src/components/BookingDialog/BookingDialog.tsx
index a6482238e..1be4e6154 100644
--- a/src/components/BookingDialog/BookingDialog.tsx
+++ b/src/components/BookingDialog/BookingDialog.tsx
@@ -1,6 +1,8 @@
 import * as React from 'react';
+import { createPortal } from 'react-dom';
 import { cva, type VariantProps } from 'class-variance-authority';
 import { cn } from '../../utils/cn';
+import { useAnchoredPosition } from '../../hooks/useAnchoredPosition';
 import { isStorybookDocsMode } from '../../utils/environment';
 
 // =============================================================================
@@ -151,18 +153,26 @@ export function ServiceSelect({
   const [isOpen, setIsOpen] = React.useState(false);
   const dropdownRef = React.useRef<HTMLDivElement>(null);
 
+  // Portal + fixed positioning so the dropdown escapes overflow-hidden
+  // ancestors (the dialog itself scrolls/clips).
+  const { anchorRef, floatingRef, style } = useAnchoredPosition<
+    HTMLDivElement,
+    HTMLDivElement
+  >({ open: isOpen, matchWidth: true, maxHeight: 240 });
+
   React.useEffect(() => {
     function handleClickOutside(event: MouseEvent) {
       if (
         dropdownRef.current &&
-        !dropdownRef.current.contains(event.target as Node)
+        !dropdownRef.current.contains(event.target as Node) &&
+        !floatingRef.current?.contains(event.target as Node)
       ) {
         setIsOpen(false);
       }
     }
     document.addEventListener('mousedown', handleClickOutside);
     return () => document.removeEventListener('mousedown', handleClickOutside);
-  }, []);
+  }, [floatingRef]);
 
   const toggleService = (serviceSlug: string) => {
     if (selectedServices.includes(serviceSlug)) {
@@ -178,7 +188,10 @@ export function ServiceSelect({
 
   return (
     <div
-      ref={dropdownRef}
+      ref={(node) => {
+        dropdownRef.current = node;
+        anchorRef.current = node;
+      }}
       className={cn('relative', className)}
       data-slot="service-select"
     >
@@ -218,33 +231,37 @@ export function ServiceSelect({
         />
       </button>
 
-      {isOpen && (
-        <div
-          className="border-border bg-card absolute z-50 mt-1 max-h-60 w-full overflow-auto rounded-lg border shadow-lg"
-          data-slot="service-select-dropdown"
-        >
-          {services.map((service) => (
-            <label
-              key={service.slug}
-              data-slot="service-select-option"
-              className="hover:bg-muted flex cursor-pointer items-center gap-3 px-4 py-3"
-            >
-              <input
-                type="checkbox"
-                checked={selectedServices.includes(service.slug)}
-                onChange={() => toggleService(service.slug)}
-                className="text-primary-800 focus:ring-primary-500 border-input h-4 w-4 rounded"
-              />
-              <span className="text-foreground">{service.name}</span>
-            </label>
-          ))}
-          {services.length === 0 && (
-            <div className="text-muted-foreground px-4 py-3 text-center">
-              No services available
-            </div>
-          )}
-        </div>
-      )}
+      {isOpen &&
+        createPortal(
+          <div
+            ref={floatingRef}
+            style={style}
+            className="border-border bg-card overflow-auto rounded-lg border shadow-lg"
+            data-slot="service-select-dropdown"
+          >
+            {services.map((service) => (
+              <label
+                key={service.slug}
+                data-slot="service-select-option"
+                className="hover:bg-muted flex cursor-pointer items-center gap-3 px-4 py-3"
+              >
+                <input
+                  type="checkbox"
+                  checked={selectedServices.includes(service.slug)}
+                  onChange={() => toggleService(service.slug)}
+                  className="text-primary-800 focus:ring-primary-500 border-input h-4 w-4 rounded"
+                />
+                <span className="text-foreground">{service.name}</span>
+              </label>
+            ))}
+            {services.length === 0 && (
+              <div className="text-muted-foreground px-4 py-3 text-center">
+                No services available
+              </div>
+            )}
+          </div>,
+          document.body
+        )}
 
       {error && (
         <p
diff --git a/src/components/BusinessHoursEditor/BusinessHoursEditor.tsx b/src/components/BusinessHoursEditor/BusinessHoursEditor.tsx
index fccd91518..9c1227bd8 100644
--- a/src/components/BusinessHoursEditor/BusinessHoursEditor.tsx
+++ b/src/components/BusinessHoursEditor/BusinessHoursEditor.tsx
@@ -4,6 +4,7 @@ import * as React from 'react';
 import { useCallback } from 'react';
 import { Button } from '../Button/Button';
 import { Input } from '../Input/Input';
+import { Dropdown, DropdownItem } from '../Dropdown';
 import { cn } from '../../utils/cn';
 
 // ============================================================================
@@ -226,36 +227,34 @@ export function BusinessHoursEditor({
               </h4>
               <div className="flex items-center gap-2">
                 {hours.length > 0 && (
-                  <div className="group relative">
-                    <Button
-                      type="button"
-                      variant="ghost"
-                      size="sm"
-                      disabled={disabled}
-                      className="text-xs"
-                    >
-                      <CopyIcon className="mr-1 h-3 w-3" />
-                      Copy
-                    </Button>
-                    <div className="invisible absolute top-full right-0 z-10 mt-1 rounded-md border border-gray-200 bg-white opacity-0 shadow-lg transition-all group-hover:visible group-hover:opacity-100 dark:border-gray-700 dark:bg-gray-800">
-                      <button
+                  <Dropdown
+                    placement="bottom-end"
+                    trigger={
+                      <Button
                         type="button"
-                        className="block w-full px-3 py-2 text-left text-xs whitespace-nowrap hover:bg-gray-100 dark:hover:bg-gray-700"
-                        onClick={() => handleCopyToAll(dayIndex)}
+                        variant="ghost"
+                        size="sm"
                         disabled={disabled}
+                        className="text-xs"
                       >
-                        Copy to all days
-                      </button>
-                      <button
-                        type="button"
-                        className="block w-full px-3 py-2 text-left text-xs whitespace-nowrap hover:bg-gray-100 dark:hover:bg-gray-700"
-                        onClick={() => handleCopyToWeekdays(dayIndex)}
-                        disabled={disabled}
-                      >
-                        Copy to weekdays
-                      </button>
-                    </div>
-                  </div>
+                        <CopyIcon className="mr-1 h-3 w-3" />
+                        Copy
+                      </Button>
+                    }
+                  >
+                    <DropdownItem
+                      onClick={() => handleCopyToAll(dayIndex)}
+                      disabled={disabled}
+                    >
+                      Copy to all days
+                    </DropdownItem>
+                    <DropdownItem
+                      onClick={() => handleCopyToWeekdays(dayIndex)}
+                      disabled={disabled}
+                    >
+                      Copy to weekdays
+                    </DropdownItem>
+                  </Dropdown>
                 )}
                 <Button
                   type="button"
diff --git a/src/components/CodeLookup/CodeLookup.tsx b/src/components/CodeLookup/CodeLookup.tsx
index 2c19271aa..ba8e83098 100644
--- a/src/components/CodeLookup/CodeLookup.tsx
+++ b/src/components/CodeLookup/CodeLookup.tsx
@@ -9,7 +9,9 @@
  */
 
 import * as React from 'react';
+import { createPortal } from 'react-dom';
 import { cn } from '../../utils/cn';
+import { useAnchoredPosition } from '../../hooks/useAnchoredPosition';
 import { Card, CardContent } from '../Card/Card';
 import {
   SearchIcon,
@@ -453,8 +455,15 @@ export const CodeLookup = React.forwardRef<HTMLDivElement, CodeLookupProps>(
         list.length > 0 ||
         Boolean(onFreeText && query.trim() !== ''));
 
+    // Portal + fixed positioning so the dropdown escapes overflow-hidden
+    // ancestors (Cards, scroll containers, …).
+    const { anchorRef, floatingRef, style } = useAnchoredPosition<
+      HTMLDivElement,
+      HTMLDivElement
+    >({ open: dropdownOpen, matchWidth: true });
+
     const searchBox = (
-      <div className="relative">
+      <div className="relative" ref={anchorRef}>
         <SearchIcon
           size={16}
           className="text-muted-foreground absolute top-5 left-3 -translate-y-1/2"
@@ -488,132 +497,140 @@ export const CodeLookup = React.forwardRef<HTMLDivElement, CodeLookupProps>(
           )}
         />
 
-        {/* floating dropdown */}
-        {dropdownOpen && (
-          <div
-            role="presentation"
-            className={cn(
-              'bg-card border-border absolute top-11 right-0 left-0 z-20',
-              'overflow-hidden rounded-md border shadow-lg'
-            )}
-            // keep input focus when clicking inside the dropdown
-            onMouseDown={(e) => e.preventDefault()}
-          >
-            {drill && (
-              <div className="border-border bg-muted/50 flex items-center gap-1.5 border-b px-2 py-1.5">
-                <button
-                  type="button"
-                  onClick={closeDrill}
-                  aria-label="Back to search results"
-                  className="text-muted-foreground hover:text-foreground flex items-center gap-1 text-xs"
-                >
-                  <ChevronLeftIcon size={14} />
-                  Back
-                </button>
-                <span className="text-foreground text-xs font-semibold">
-                  {drill.parent.label}
-                </span>
-                <span className="text-muted-foreground text-xs">
-                  — {DETAIL_NOUN[drill.parent.domain] ?? 'related codes'}
-                  {drill.results === null ? '…' : ` (${drill.results.length})`}
-                </span>
-              </div>
-            )}
-
-            <ul
-              id={resultsId}
-              role="listbox"
-              aria-label={
-                drill
-                  ? `${DETAIL_NOUN[drill.parent.domain] ?? 'related codes'} of ${drill.parent.label}`
-                  : 'Code search results'
-              }
-              className="divide-border max-h-80 divide-y overflow-y-auto"
+        {/* floating dropdown — portaled so no ancestor can clip it */}
+        {dropdownOpen &&
+          createPortal(
+            <div
+              ref={floatingRef}
+              style={style}
+              role="presentation"
+              className={cn(
+                'bg-card border-border flex flex-col',
+                'overflow-hidden rounded-md border shadow-lg'
+              )}
+              // keep input focus when clicking inside the dropdown
+              onMouseDown={(e) => e.preventDefault()}
             >
-              {list.map((r, i) => (
-                <li
-                  key={r.fullid}
-                  role="presentation"
-                  className="flex items-stretch"
-                >
+              {drill && (
+                <div className="border-border bg-muted/50 flex items-center gap-1.5 border-b px-2 py-1.5">
                   <button
                     type="button"
-                    id={optionId(i)}
-                    role="option"
-                    aria-selected={i === activeIndex}
-                    // focus stays on the input (aria-activedescendant); a
-                    // tabbable option would be unmounted by the input's
-                    // onBlur closing the dropdown, dropping focus
-                    tabIndex={-1}
-                    onClick={() => pick(r)}
-                    onMouseMove={() => activeIndex !== i && setActiveIndex(i)}
-                    className={cn(
-                      'flex min-w-0 flex-1 items-baseline gap-2 px-3 py-1.5 text-left text-sm',
-                      'hover:bg-muted/60 focus:bg-muted/60 focus:outline-none',
-                      i === activeIndex && 'bg-muted/60'
-                    )}
+                    onClick={closeDrill}
+                    aria-label="Back to search results"
+                    className="text-muted-foreground hover:text-foreground flex items-center gap-1 text-xs"
                   >
-                    <span className="text-foreground min-w-0 flex-1 truncate">
-                      {r.label}
-                    </span>
-                    <span
-                      className={cn(
-                        'text-muted-foreground shrink-0 text-[11px] whitespace-nowrap',
-                        DOMAIN_TEXT[r.domain]
-                      )}
-                    >
-                      {r.codetype}{' '}
-                      <span className="font-mono">{r.fullcode}</span>
-                    </span>
+                    <ChevronLeftIcon size={14} />
+                    Back
                   </button>
-                  {!drill && isDrillable(r) && (
+                  <span className="text-foreground text-xs font-semibold">
+                    {drill.parent.label}
+                  </span>
+                  <span className="text-muted-foreground text-xs">
+                    — {DETAIL_NOUN[drill.parent.domain] ?? 'related codes'}
+                    {drill.results === null
+                      ? '…'
+                      : ` (${drill.results.length})`}
+                  </span>
+                </div>
+              )}
+
+              <ul
+                id={resultsId}
+                role="listbox"
+                aria-label={
+                  drill
+                    ? `${DETAIL_NOUN[drill.parent.domain] ?? 'related codes'} of ${drill.parent.label}`
+                    : 'Code search results'
+                }
+                className="divide-border max-h-80 min-h-0 divide-y overflow-y-auto"
+              >
+                {list.map((r, i) => (
+                  <li
+                    key={r.fullid}
+                    role="presentation"
+                    className="flex items-stretch"
+                  >
                     <button
                       type="button"
+                      id={optionId(i)}
+                      role="option"
+                      aria-selected={i === activeIndex}
+                      // focus stays on the input (aria-activedescendant); a
+                      // tabbable option would be unmounted by the input's
+                      // onBlur closing the dropdown, dropping focus
                       tabIndex={-1}
-                      aria-label={`Show ${DETAIL_NOUN[r.domain] ?? 'related codes'} of ${r.label}`}
-                      title={`${DETAIL_NOUN[r.domain] ?? 'Related codes'} (→)`}
-                      onClick={() => openDrill(r)}
+                      onClick={() => pick(r)}
                       onMouseMove={() => activeIndex !== i && setActiveIndex(i)}
                       className={cn(
-                        'text-muted-foreground hover:text-foreground shrink-0 px-1.5',
-                        'hover:bg-muted/60 focus:outline-none',
-                        i === activeIndex
-                          ? 'bg-muted/60 opacity-100'
-                          : 'opacity-40'
+                        'flex min-w-0 flex-1 items-baseline gap-2 px-3 py-1.5 text-left text-sm',
+                        'hover:bg-muted/60 focus:bg-muted/60 focus:outline-none',
+                        i === activeIndex && 'bg-muted/60'
                       )}
                     >
-                      <ChevronRightIcon size={14} />
+                      <span className="text-foreground min-w-0 flex-1 truncate">
+                        {r.label}
+                      </span>
+                      <span
+                        className={cn(
+                          'text-muted-foreground shrink-0 text-[11px] whitespace-nowrap',
+                          DOMAIN_TEXT[r.domain]
+                        )}
+                      >
+                        {r.codetype}{' '}
+                        <span className="font-mono">{r.fullcode}</span>
+                      </span>
                     </button>
+                    {!drill && isDrillable(r) && (
+                      <button
+                        type="button"
+                        tabIndex={-1}
+                        aria-label={`Show ${DETAIL_NOUN[r.domain] ?? 'related codes'} of ${r.label}`}
+                        title={`${DETAIL_NOUN[r.domain] ?? 'Related codes'} (→)`}
+                        onClick={() => openDrill(r)}
+                        onMouseMove={() =>
+                          activeIndex !== i && setActiveIndex(i)
+                        }
+                        className={cn(
+                          'text-muted-foreground hover:text-foreground shrink-0 px-1.5',
+                          'hover:bg-muted/60 focus:outline-none',
+                          i === activeIndex
+                            ? 'bg-muted/60 opacity-100'
+                            : 'opacity-40'
+                        )}
+                      >
+                        <ChevronRightIcon size={14} />
+                      </button>
+                    )}
+                  </li>
+                ))}
+                {drill &&
+                  drill.results !== null &&
+                  drill.results.length === 0 && (
+                    <li className="text-muted-foreground px-3 py-2 text-sm">
+                      No related entries found — press ← to go back.
+                    </li>
                   )}
-                </li>
-              ))}
-              {drill &&
-                drill.results !== null &&
-                drill.results.length === 0 && (
-                  <li className="text-muted-foreground px-3 py-2 text-sm">
-                    No related entries found — press ← to go back.
+                {!drill && onFreeText && query.trim() !== '' && (
+                  <li role="presentation" className="border-border border-t">
+                    <button
+                      type="button"
+                      // outside the tab order for the same reason as the
+                      // options — focus is managed on the input
+                      tabIndex={-1}
+                      onClick={submitFreeText}
+                      className={cn(
+                        'text-muted-foreground hover:text-foreground hover:bg-muted/60 w-full px-3 py-1.5 text-left text-sm italic',
+                        'focus:bg-muted/60 focus:outline-none'
+                      )}
+                    >
+                      Use “{query.trim()}” as free text…
+                    </button>
                   </li>
                 )}
-              {!drill && onFreeText && query.trim() !== '' && (
-                <li role="presentation" className="border-border border-t">
-                  <button
-                    type="button"
-                    // outside the tab order for the same reason as the
-                    // options — focus is managed on the input
-                    tabIndex={-1}
-                    onClick={submitFreeText}
-                    className={cn(
-                      'text-muted-foreground hover:text-foreground hover:bg-muted/60 w-full px-3 py-1.5 text-left text-sm italic',
-                      'focus:bg-muted/60 focus:outline-none'
-                    )}
-                  >
-                    Use “{query.trim()}” as free text…
-                  </button>
-                </li>
-              )}
-            </ul>
-          </div>
-        )}
+              </ul>
+            </div>,
+            document.body
+          )}
       </div>
     );
 
diff --git a/src/components/CountBadge/CountBadge.tsx b/src/components/CountBadge/CountBadge.tsx
index 9722b9e9a..f70b12e30 100644
--- a/src/components/CountBadge/CountBadge.tsx
+++ b/src/components/CountBadge/CountBadge.tsx
@@ -2,6 +2,7 @@ import * as React from 'react';
 import * as ReactDOM from 'react-dom';
 import { cva, type VariantProps } from 'class-variance-authority';
 import { cn } from '../../utils/cn';
+import { useAnchoredPosition } from '../../hooks/useAnchoredPosition';
 import {
   MoreHorizontalIcon,
   ShareIcon,
@@ -332,10 +333,14 @@ function HoverMenu({
   items,
   actions,
   variant,
+  floatingRef,
+  style,
 }: {
   items: CountBadgeItem[];
   actions: CountBadgeAction[];
   variant: CountBadgeProps['variant'];
+  floatingRef: React.RefObject<HTMLDivElement | null>;
+  style: React.CSSProperties;
 }) {
   // Variant-aware header accent
   const headerBg: Record<string, string> = {
@@ -350,11 +355,13 @@ function HoverMenu({
   return (
     /* eslint-disable-next-line jsx-a11y/no-static-element-interactions */
     <div
+      ref={floatingRef}
+      style={style}
       data-slot="count-badge-menu"
       className={cn(
-        'absolute top-full right-0 z-50 mt-2',
         'w-[320px] rounded-lg border border-neutral-200 bg-white shadow-xl',
         'dark:border-neutral-700 dark:bg-neutral-800',
+        'flex flex-col',
         'animate-in fade-in slide-in-from-top-1 duration-150'
       )}
       // Prevent click-outside handler from immediately closing when interacting
@@ -375,7 +382,7 @@ function HoverMenu({
       {/* Table */}
       <div
         data-slot="count-badge-menu-scroll"
-        className="max-h-[240px] overflow-y-auto"
+        className="max-h-[240px] min-h-0 overflow-y-auto"
       >
         <table className="w-full text-left text-xs">
           <thead>
@@ -472,22 +479,41 @@ function ViewModalActions({
   const [shareOpen, setShareOpen] = React.useState(false);
   const shareRef = React.useRef<HTMLDivElement>(null);
 
+  // Portal + fixed positioning so the dropdown escapes the modal's clipping.
+  const {
+    anchorRef: shareAnchorRef,
+    floatingRef: shareFloatingRef,
+    style: shareStyle,
+  } = useAnchoredPosition<HTMLDivElement, HTMLDivElement>({
+    open: shareOpen,
+  });
+
   // Close share dropdown on outside click
   React.useEffect(() => {
     if (!shareOpen) return;
     const handleClick = (e: MouseEvent) => {
-      if (shareRef.current && !shareRef.current.contains(e.target as Node)) {
+      if (
+        shareRef.current &&
+        !shareRef.current.contains(e.target as Node) &&
+        !shareFloatingRef.current?.contains(e.target as Node)
+      ) {
         setShareOpen(false);
       }
     };
     document.addEventListener('mousedown', handleClick);
     return () => document.removeEventListener('mousedown', handleClick);
-  }, [shareOpen]);
+  }, [shareOpen, shareFloatingRef]);
 
   return (
     <div className="mb-4 flex items-center gap-1 border-b border-neutral-200 pb-3 dark:border-neutral-700">
       {/* Share with dropdown */}
-      <div ref={shareRef} className="relative">
+      <div
+        ref={(node) => {
+          shareRef.current = node;
+          shareAnchorRef.current = node;
+        }}
+        className="relative"
+      >
         <Button
           variant="ghost"
           size="sm"
@@ -506,66 +532,69 @@ function ViewModalActions({
           />
         </Button>
 
-        {shareOpen && (
-          <div
-            role="menu"
-            className={cn(
-              'absolute top-full left-0 z-50 mt-1',
-              'min-w-[10rem] rounded-lg border border-neutral-200 bg-white py-1 shadow-lg',
-              'dark:border-neutral-700 dark:bg-neutral-800',
-              'animate-in fade-in zoom-in-95 duration-100'
-            )}
-          >
-            <button
-              role="menuitem"
-              type="button"
+        {shareOpen &&
+          ReactDOM.createPortal(
+            <div
+              ref={shareFloatingRef}
+              style={shareStyle}
+              role="menu"
               className={cn(
-                'flex w-full items-center gap-2 px-3 py-1.5 text-left text-sm',
-                'text-neutral-700 hover:bg-neutral-100',
-                'dark:text-neutral-300 dark:hover:bg-neutral-700'
+                'min-w-[10rem] overflow-auto rounded-lg border border-neutral-200 bg-white py-1 shadow-lg',
+                'dark:border-neutral-700 dark:bg-neutral-800',
+                'animate-in fade-in zoom-in-95 duration-100'
               )}
-              onClick={() => {
-                console.warn('Share with physician', viewTarget);
-                setShareOpen(false);
-              }}
             >
-              <StethoscopeIcon size={14} />
-              Physician
-            </button>
-            <button
-              role="menuitem"
-              type="button"
-              className={cn(
-                'flex w-full items-center gap-2 px-3 py-1.5 text-left text-sm',
-                'text-neutral-700 hover:bg-neutral-100',
-                'dark:text-neutral-300 dark:hover:bg-neutral-700'
-              )}
-              onClick={() => {
-                console.warn('Share with patient', viewTarget);
-                setShareOpen(false);
-              }}
-            >
-              <UserIcon size={14} />
-              Patient
-            </button>
-            <button
-              role="menuitem"
-              type="button"
-              className={cn(
-                'flex w-full items-center gap-2 px-3 py-1.5 text-left text-sm',
-                'text-neutral-700 hover:bg-neutral-100',
-                'dark:text-neutral-300 dark:hover:bg-neutral-700'
-              )}
-              onClick={() => {
-                console.warn('Share via email', viewTarget);
-                setShareOpen(false);
-              }}
-            >
-              <MailIcon size={14} />
-              Email
-            </button>
-          </div>
-        )}
+              <button
+                role="menuitem"
+                type="button"
+                className={cn(
+                  'flex w-full items-center gap-2 px-3 py-1.5 text-left text-sm',
+                  'text-neutral-700 hover:bg-neutral-100',
+                  'dark:text-neutral-300 dark:hover:bg-neutral-700'
+                )}
+                onClick={() => {
+                  console.warn('Share with physician', viewTarget);
+                  setShareOpen(false);
+                }}
+              >
+                <StethoscopeIcon size={14} />
+                Physician
+              </button>
+              <button
+                role="menuitem"
+                type="button"
+                className={cn(
+                  'flex w-full items-center gap-2 px-3 py-1.5 text-left text-sm',
+                  'text-neutral-700 hover:bg-neutral-100',
+                  'dark:text-neutral-300 dark:hover:bg-neutral-700'
+                )}
+                onClick={() => {
+                  console.warn('Share with patient', viewTarget);
+                  setShareOpen(false);
+                }}
+              >
+                <UserIcon size={14} />
+                Patient
+              </button>
+              <button
+                role="menuitem"
+                type="button"
+                className={cn(
+                  'flex w-full items-center gap-2 px-3 py-1.5 text-left text-sm',
+                  'text-neutral-700 hover:bg-neutral-100',
+                  'dark:text-neutral-300 dark:hover:bg-neutral-700'
+                )}
+                onClick={() => {
+                  console.warn('Share via email', viewTarget);
+                  setShareOpen(false);
+                }}
+              >
+                <MailIcon size={14} />
+                Email
+              </button>
+            </div>,
+            document.body
+          )}
       </div>
 
       <Button
@@ -657,13 +686,25 @@ const CountBadge = React.forwardRef<HTMLButtonElement, CountBadgeProps>(
 
     const showMenu = items && items.length > 0;
 
+    // Portal + fixed positioning so the menu escapes overflow-hidden ancestors.
+    const {
+      anchorRef,
+      floatingRef,
+      style: menuStyle,
+    } = useAnchoredPosition<HTMLDivElement, HTMLDivElement>({
+      open: Boolean(showMenu && open),
+      placement: 'bottom-end',
+      offset: 8,
+    });
+
     // Close on click outside
     React.useEffect(() => {
       if (!open) return;
       const handleClickOutside = (e: MouseEvent) => {
         if (
           containerRef.current &&
-          !containerRef.current.contains(e.target as Node)
+          !containerRef.current.contains(e.target as Node) &&
+          !floatingRef.current?.contains(e.target as Node)
         ) {
           setOpen(false);
         }
@@ -671,7 +712,7 @@ const CountBadge = React.forwardRef<HTMLButtonElement, CountBadgeProps>(
       document.addEventListener('mousedown', handleClickOutside);
       return () =>
         document.removeEventListener('mousedown', handleClickOutside);
-    }, [open]);
+    }, [open, floatingRef]);
 
     // Close on Escape
     React.useEffect(() => {
@@ -718,7 +759,13 @@ const CountBadge = React.forwardRef<HTMLButtonElement, CountBadgeProps>(
 
     return (
       <>
-        <div ref={containerRef} className="relative inline-flex">
+        <div
+          ref={(node) => {
+            containerRef.current = node;
+            anchorRef.current = node;
+          }}
+          className="relative inline-flex"
+        >
           <button
             ref={ref}
             type="button"
@@ -746,13 +793,18 @@ const CountBadge = React.forwardRef<HTMLButtonElement, CountBadgeProps>(
             </span>
           </button>
 
-          {showMenu && open && (
-            <HoverMenu
-              items={items}
-              actions={resolvedActions}
-              variant={variant}
-            />
-          )}
+          {showMenu &&
+            open &&
+            ReactDOM.createPortal(
+              <HoverMenu
+                items={items}
+                actions={resolvedActions}
+                variant={variant}
+                floatingRef={floatingRef}
+                style={menuStyle}
+              />,
+              document.body
+            )}
         </div>
 
         {/* Delete confirmation modal */}
diff --git a/src/components/CountryCodeDropdown/CountryCodeDropdown.tsx b/src/components/CountryCodeDropdown/CountryCodeDropdown.tsx
index 107e8eec1..fcfb97da3 100644
--- a/src/components/CountryCodeDropdown/CountryCodeDropdown.tsx
+++ b/src/components/CountryCodeDropdown/CountryCodeDropdown.tsx
@@ -1,8 +1,10 @@
 import * as React from 'react';
+import { createPortal } from 'react-dom';
 import * as libphonenumber from 'google-libphonenumber';
 import { cn } from '../../utils/cn';
 import { useClickOutside } from '../../hooks/useClickOutside';
 import { useEscapeKey } from '../../hooks/useEscapeKey';
+import { useAnchoredPosition } from '../../hooks/useAnchoredPosition';
 
 const PhoneNumberUtil =
   (libphonenumber as unknown as { default?: typeof libphonenumber }).default
@@ -238,7 +240,17 @@ function CountryCodeDropdown({
     setSearch('');
   }, []);
 
-  useClickOutside(containerRef, close);
+  // Portal + fixed positioning so the panel escapes overflow-hidden ancestors.
+  const { anchorRef, floatingRef, style } = useAnchoredPosition<
+    HTMLDivElement,
+    HTMLDivElement
+  >({ open: isOpen, placement });
+
+  const outsideRefs = React.useMemo(
+    () => [containerRef, floatingRef],
+    [containerRef, floatingRef]
+  );
+  useClickOutside(outsideRefs, close);
   useEscapeKey(close, isOpen);
 
   // Focus search input when opening
@@ -290,14 +302,12 @@ function CountryCodeDropdown({
     [isOpen]
   );
 
-  const placementClass =
-    placement === 'bottom-end'
-      ? 'top-full right-0 mt-1'
-      : 'top-full left-0 mt-1';
-
   return (
     <div
-      ref={containerRef}
+      ref={(node) => {
+        containerRef.current = node;
+        anchorRef.current = node;
+      }}
       data-slot="country-dropdown"
       className="relative inline-flex"
     >
@@ -349,98 +359,101 @@ function CountryCodeDropdown({
       </button>
 
       {/* Dropdown panel */}
-      {isOpen && (
-        <div
-          id={menuId}
-          role="listbox"
-          data-slot="country-dropdown-panel"
-          aria-label={ariaLabel}
-          tabIndex={-1}
-          onKeyDown={handleKeyDown}
-          className={cn(
-            'absolute z-50 w-72',
-            'rounded-xl border border-neutral-200 bg-white shadow-lg',
-            'dark:border-neutral-700 dark:bg-neutral-800',
-            'animate-in fade-in zoom-in-95 duration-100',
-            placementClass
-          )}
-        >
-          {/* Search input */}
-          <div
-            data-slot="country-dropdown-search"
-            className="border-b border-neutral-200 p-2 dark:border-neutral-700"
-          >
-            <input
-              ref={searchInputRef}
-              type="text"
-              data-slot="country-dropdown-search-input"
-              value={search}
-              onChange={(e) => setSearch(e.target.value)}
-              placeholder={searchPlaceholder}
-              aria-label="Search countries"
-              className={cn(
-                'w-full rounded-lg border border-neutral-200 px-3 py-1.5 text-sm',
-                'text-foreground placeholder:text-muted-foreground bg-white',
-                'focus:ring-ring focus:border-transparent focus:ring-2 focus:outline-none',
-                'dark:border-neutral-600 dark:bg-neutral-700 dark:text-neutral-100'
-              )}
-            />
-          </div>
-
-          {/* Country list */}
+      {isOpen &&
+        createPortal(
           <div
-            ref={listRef}
-            data-slot="country-dropdown-list"
-            className="max-h-60 overflow-y-auto p-1"
+            ref={floatingRef}
+            style={style}
+            id={menuId}
+            role="listbox"
+            data-slot="country-dropdown-panel"
+            aria-label={ariaLabel}
+            tabIndex={-1}
+            onKeyDown={handleKeyDown}
+            className={cn(
+              'flex w-72 flex-col',
+              'rounded-xl border border-neutral-200 bg-white shadow-lg',
+              'dark:border-neutral-700 dark:bg-neutral-800',
+              'animate-in fade-in zoom-in-95 duration-100'
+            )}
           >
-            {filtered.length === 0 ? (
-              <div className="text-muted-foreground px-3 py-4 text-center text-sm">
-                No countries found
-              </div>
-            ) : (
-              filtered.map((country) => (
-                <button
-                  key={country.code}
-                  type="button"
-                  role="option"
-                  data-slot="country-dropdown-option"
-                  aria-selected={country.code === selected.code}
-                  onClick={() => handleSelect(country)}
-                  className={cn(
-                    'flex w-full items-center gap-3 rounded-lg px-3 py-2 text-left text-sm',
-                    'transition-colors duration-150',
-                    'focus:outline-none',
-                    country.code === selected.code
-                      ? 'bg-neutral-100 font-medium text-neutral-900 dark:bg-neutral-700 dark:text-white'
-                      : 'text-neutral-700 hover:bg-neutral-50 dark:text-neutral-300 dark:hover:bg-neutral-700/50',
-                    'focus:bg-neutral-100 dark:focus:bg-neutral-700'
-                  )}
-                >
-                  <span
-                    data-slot="country-dropdown-option-flag"
-                    className="text-base leading-none"
-                    aria-hidden="true"
-                  >
-                    {country.flag}
-                  </span>
-                  <span
-                    data-slot="country-dropdown-option-name"
-                    className="flex-1 truncate"
+            {/* Search input */}
+            <div
+              data-slot="country-dropdown-search"
+              className="border-b border-neutral-200 p-2 dark:border-neutral-700"
+            >
+              <input
+                ref={searchInputRef}
+                type="text"
+                data-slot="country-dropdown-search-input"
+                value={search}
+                onChange={(e) => setSearch(e.target.value)}
+                placeholder={searchPlaceholder}
+                aria-label="Search countries"
+                className={cn(
+                  'w-full rounded-lg border border-neutral-200 px-3 py-1.5 text-sm',
+                  'text-foreground placeholder:text-muted-foreground bg-white',
+                  'focus:ring-ring focus:border-transparent focus:ring-2 focus:outline-none',
+                  'dark:border-neutral-600 dark:bg-neutral-700 dark:text-neutral-100'
+                )}
+              />
+            </div>
+
+            {/* Country list */}
+            <div
+              ref={listRef}
+              data-slot="country-dropdown-list"
+              className="max-h-60 min-h-0 overflow-y-auto p-1"
+            >
+              {filtered.length === 0 ? (
+                <div className="text-muted-foreground px-3 py-4 text-center text-sm">
+                  No countries found
+                </div>
+              ) : (
+                filtered.map((country) => (
+                  <button
+                    key={country.code}
+                    type="button"
+                    role="option"
+                    data-slot="country-dropdown-option"
+                    aria-selected={country.code === selected.code}
+                    onClick={() => handleSelect(country)}
+                    className={cn(
+                      'flex w-full items-center gap-3 rounded-lg px-3 py-2 text-left text-sm',
+                      'transition-colors duration-150',
+                      'focus:outline-none',
+                      country.code === selected.code
+                        ? 'bg-neutral-100 font-medium text-neutral-900 dark:bg-neutral-700 dark:text-white'
+                        : 'text-neutral-700 hover:bg-neutral-50 dark:text-neutral-300 dark:hover:bg-neutral-700/50',
+                      'focus:bg-neutral-100 dark:focus:bg-neutral-700'
+                    )}
                   >
-                    {country.name}
-                  </span>
-                  <span
-                    data-slot="country-dropdown-option-dialcode"
-                    className="text-muted-foreground shrink-0 text-xs"
-                  >
-                    {country.dialCode}
-                  </span>
-                </button>
-              ))
-            )}
-          </div>
-        </div>
-      )}
+                    <span
+                      data-slot="country-dropdown-option-flag"
+                      className="text-base leading-none"
+                      aria-hidden="true"
+                    >
+                      {country.flag}
+                    </span>
+                    <span
+                      data-slot="country-dropdown-option-name"
+                      className="flex-1 truncate"
+                    >
+                      {country.name}
+                    </span>
+                    <span
+                      data-slot="country-dropdown-option-dialcode"
+                      className="text-muted-foreground shrink-0 text-xs"
+                    >
+                      {country.dialCode}
+                    </span>
+                  </button>
+                ))
+              )}
+            </div>
+          </div>,
+          document.body
+        )}
     </div>
   );
 }
diff --git a/src/components/DateRangePicker/DateRangePicker.tsx b/src/components/DateRangePicker/DateRangePicker.tsx
index 07b3806dd..c64ac00aa 100644
--- a/src/components/DateRangePicker/DateRangePicker.tsx
+++ b/src/components/DateRangePicker/DateRangePicker.tsx
@@ -1,8 +1,10 @@
 import * as React from 'react';
+import { createPortal } from 'react-dom';
 import { cn } from '../../utils/cn';
 import { useClickOutside } from '../../hooks/useClickOutside';
 import { useEscapeKey } from '../../hooks/useEscapeKey';
 import { useFocusTrap } from '../../hooks/useFocusTrap';
+import { useAnchoredPosition } from '../../hooks/useAnchoredPosition';
 import { isStorybookDocsMode } from '../../utils/environment';
 import { Button } from '../Button';
 import { Dropdown, DropdownItem } from '../Dropdown';
@@ -383,13 +385,27 @@ export function DateRangePicker({
 
   // Close calendar on click outside (supports touch via hook)
   const wrapperRef = React.useRef<HTMLDivElement>(null);
-  useClickOutside(wrapperRef, () => {
+  const outsideRefs = React.useMemo(
+    () => [wrapperRef, calendarRef],
+    [calendarRef]
+  );
+  useClickOutside(outsideRefs, () => {
     if (isCalendarOpen) {
       setIsCalendarOpen(false);
       setSelectingEnd(false);
     }
   });
 
+  // Portal + fixed positioning for the desktop popup so it escapes
+  // overflow-hidden ancestors.
+  const { anchorRef, floatingRef, style } = useAnchoredPosition<
+    HTMLDivElement,
+    HTMLDivElement
+  >({
+    open: !isMobileVariant && isCalendarOpen,
+    placement: resolvedAlign === 'end' ? 'bottom-end' : 'bottom-start',
+  });
+
   // Close on Escape and restore focus to trigger
   useEscapeKey(() => {
     setIsCalendarOpen(false);
@@ -681,7 +697,10 @@ export function DateRangePicker({
 
   return (
     <div
-      ref={wrapperRef}
+      ref={(node) => {
+        wrapperRef.current = node;
+        anchorRef.current = node;
+      }}
       className={cn('relative inline-block', className)}
       data-slot="date-range-picker"
     >
@@ -808,127 +827,134 @@ export function DateRangePicker({
       )}
 
       {/* Desktop / Responsive popup */}
-      {!isMobileVariant && isCalendarOpen && (
-        <div
-          ref={calendarRef}
-          className={cn(
-            'absolute top-full z-50 mt-1',
-            resolvedAlign === 'end' ? 'right-0' : 'left-0',
-            'bg-background border-border rounded-lg border shadow-lg'
-          )}
-          role="dialog"
-          aria-label="Choose date range"
-          data-slot="date-range-popup"
-        >
-          <div className="flex">
-            {/* Preset sidebar — hidden on small screens in responsive mode */}
-            {showPresets && (
-              <div
-                className={cn(
-                  'border-border flex w-[200px] shrink-0 flex-col gap-0.5 border-r p-3',
-                  isResponsive && 'hidden md:flex'
-                )}
-                data-slot="date-range-presets"
-              >
-                {finalPresets.map((preset) => (
-                  <button
-                    key={preset.key}
-                    type="button"
-                    onClick={() => handlePresetSelect(preset.key)}
-                    data-slot="date-range-preset"
-                    className={cn(
-                      'rounded-md px-3 py-1.5 text-left text-sm transition-colors',
-                      'hover:bg-muted',
-                      activePreset === preset.key && 'bg-primary-800 text-white'
-                    )}
-                  >
-                    {preset.label}
-                  </button>
-                ))}
-              </div>
+      {!isMobileVariant &&
+        isCalendarOpen &&
+        createPortal(
+          <div
+            ref={(node) => {
+              calendarRef.current = node;
+              floatingRef.current = node;
+            }}
+            style={style}
+            className={cn(
+              'overflow-auto',
+              'bg-background border-border rounded-lg border shadow-lg'
             )}
-
-            {/* Calendar panel */}
-            <div className="p-4" data-slot="date-range-calendar">
-              {/* Subtitle */}
-              <p
-                className="text-muted-foreground mb-4 text-sm"
-                data-slot="date-range-subtitle"
-              >
-                Select a start and end date from the calendar.
-              </p>
-
-              <div
-                className="flex gap-8"
-                onMouseLeave={() => setHoverDate(null)}
-                data-slot="date-range-calendars"
-              >
-                {/* Left month */}
-                <div>
-                  <div
-                    className="mb-3 flex items-center"
-                    data-slot="date-range-month-header"
-                  >
+            role="dialog"
+            aria-label="Choose date range"
+            data-slot="date-range-popup"
+          >
+            <div className="flex">
+              {/* Preset sidebar — hidden on small screens in responsive mode */}
+              {showPresets && (
+                <div
+                  className={cn(
+                    'border-border flex w-[200px] shrink-0 flex-col gap-0.5 border-r p-3',
+                    isResponsive && 'hidden md:flex'
+                  )}
+                  data-slot="date-range-presets"
+                >
+                  {finalPresets.map((preset) => (
                     <button
+                      key={preset.key}
                       type="button"
-                      onClick={goToPrevMonth}
-                      className="hover:bg-muted rounded-md p-1 transition-colors"
-                      aria-label="Previous month"
-                      data-slot="date-range-nav"
+                      onClick={() => handlePresetSelect(preset.key)}
+                      data-slot="date-range-preset"
+                      className={cn(
+                        'rounded-md px-3 py-1.5 text-left text-sm transition-colors',
+                        'hover:bg-muted',
+                        activePreset === preset.key &&
+                          'bg-primary-800 text-white'
+                      )}
                     >
-                      <ChevronLeft className="h-4 w-4" />
+                      {preset.label}
                     </button>
+                  ))}
+                </div>
+              )}
+
+              {/* Calendar panel */}
+              <div className="p-4" data-slot="date-range-calendar">
+                {/* Subtitle */}
+                <p
+                  className="text-muted-foreground mb-4 text-sm"
+                  data-slot="date-range-subtitle"
+                >
+                  Select a start and end date from the calendar.
+                </p>
+
+                <div
+                  className="flex gap-8"
+                  onMouseLeave={() => setHoverDate(null)}
+                  data-slot="date-range-calendars"
+                >
+                  {/* Left month */}
+                  <div>
                     <div
-                      className="flex-1 text-center text-sm font-medium"
-                      data-slot="date-range-month-label"
+                      className="mb-3 flex items-center"
+                      data-slot="date-range-month-header"
                     >
-                      {monthNames[leftMonth]} {leftYear}
-                    </div>
-                    {/* Show right chevron on left month in responsive single-cal mode */}
-                    {isResponsive && (
                       <button
                         type="button"
-                        onClick={goToNextMonth}
-                        className="hover:bg-muted rounded-md p-1 transition-colors md:hidden"
-                        aria-label="Next month"
+                        onClick={goToPrevMonth}
+                        className="hover:bg-muted rounded-md p-1 transition-colors"
+                        aria-label="Previous month"
                         data-slot="date-range-nav"
                       >
-                        <ChevronRight className="h-4 w-4" />
+                        <ChevronLeft className="h-4 w-4" />
                       </button>
-                    )}
+                      <div
+                        className="flex-1 text-center text-sm font-medium"
+                        data-slot="date-range-month-label"
+                      >
+                        {monthNames[leftMonth]} {leftYear}
+                      </div>
+                      {/* Show right chevron on left month in responsive single-cal mode */}
+                      {isResponsive && (
+                        <button
+                          type="button"
+                          onClick={goToNextMonth}
+                          className="hover:bg-muted rounded-md p-1 transition-colors md:hidden"
+                          aria-label="Next month"
+                          data-slot="date-range-nav"
+                        >
+                          <ChevronRight className="h-4 w-4" />
+                        </button>
+                      )}
+                    </div>
+                    {renderMonthGrid(leftMonth, leftYear)}
                   </div>
-                  {renderMonthGrid(leftMonth, leftYear)}
-                </div>
 
-                {/* Right month — hidden on small screens in responsive mode */}
-                <div className={cn(isResponsive && 'hidden md:block')}>
-                  <div
-                    className="mb-3 flex items-center"
-                    data-slot="date-range-month-header"
-                  >
+                  {/* Right month — hidden on small screens in responsive mode */}
+                  <div className={cn(isResponsive && 'hidden md:block')}>
                     <div
-                      className="flex-1 text-center text-sm font-medium"
-                      data-slot="date-range-month-label"
+                      className="mb-3 flex items-center"
+                      data-slot="date-range-month-header"
                     >
-                      {monthNames[rightMonth]} {rightYear}
+                      <div
+                        className="flex-1 text-center text-sm font-medium"
+                        data-slot="date-range-month-label"
+                      >
+                        {monthNames[rightMonth]} {rightYear}
+                      </div>
+                      <button
+                        type="button"
+                        onClick={goToNextMonth}
+                        className="hover:bg-muted rounded-md p-1 transition-colors"
+                        aria-label="Next month"
+                        data-slot="date-range-nav"
+                      >
+                        <ChevronRight className="h-4 w-4" />
+                      </button>
                     </div>
-                    <button
-                      type="button"
-                      onClick={goToNextMonth}
-                      className="hover:bg-muted rounded-md p-1 transition-colors"
-                      aria-label="Next month"
-                      data-slot="date-range-nav"
-                    >
-                      <ChevronRight className="h-4 w-4" />
-                    </button>
+                    {renderMonthGrid(rightMonth, rightYear)}
                   </div>
-                  {renderMonthGrid(rightMonth, rightYear)}
                 </div>
               </div>
             </div>
-          </div>
-        </div>
-      )}
+          </div>,
+          document.body
+        )}
     </div>
   );
 }
diff --git a/src/components/Dropdown/Dropdown.tsx b/src/components/Dropdown/Dropdown.tsx
index 2b882966d..6cafa4667 100644
--- a/src/components/Dropdown/Dropdown.tsx
+++ b/src/components/Dropdown/Dropdown.tsx
@@ -1,16 +1,15 @@
 import * as React from 'react';
+import { createPortal } from 'react-dom';
 import { cn } from '../../utils/cn';
 import { useClickOutside } from '../../hooks/useClickOutside';
 import { useEscapeKey } from '../../hooks/useEscapeKey';
+import {
+  useAnchoredPosition,
+  type AnchoredPlacement,
+} from '../../hooks/useAnchoredPosition';
 import { inputVariants } from '../Input';
 
-export type DropdownPlacement =
-  | 'bottom-start'
-  | 'bottom-end'
-  | 'bottom'
-  | 'top-start'
-  | 'top-end'
-  | 'top';
+export type DropdownPlacement = AnchoredPlacement;
 
 export interface DropdownProps {
   /** The trigger element (usually a button) */
@@ -57,14 +56,7 @@ export interface DropdownProps {
   selectAllLabel?: React.ReactNode;
 }
 
-const placementStyles: Record<DropdownPlacement, string> = {
-  'bottom-start': 'top-full left-0 mt-2',
-  'bottom-end': 'top-full right-0 mt-2',
-  bottom: 'top-full left-1/2 -translate-x-1/2 mt-2',
-  'top-start': 'bottom-full left-0 mb-2',
-  'top-end': 'bottom-full right-0 mb-2',
-  top: 'bottom-full left-1/2 -translate-x-1/2 mb-2',
-};
+const placementOffset = 8; // matches the previous mt-2/mb-2 gap
 
 interface DropdownContextValue {
   multiSelect: boolean;
@@ -399,9 +391,25 @@ function Dropdown({
     [multiSelect, selectedValues, toggleSelectedValue]
   );
 
-  useClickOutside(containerRef, handleClose, isOpen);
   useEscapeKey(handleClose, isOpen);
 
+  // Portal + fixed positioning so the menu escapes overflow-hidden ancestors.
+  const { anchorRef, floatingRef, style } = useAnchoredPosition<
+    HTMLDivElement,
+    HTMLDivElement
+  >({
+    open: isOpen,
+    placement,
+    offset: placementOffset,
+    matchMinWidth: width === 'trigger',
+  });
+
+  const outsideRefs = React.useMemo(
+    () => [containerRef, floatingRef],
+    [floatingRef]
+  );
+  useClickOutside(outsideRefs, handleClose, isOpen);
+
   React.useEffect(() => {
     if (!isOpen) {
       setSearchQuery('');
@@ -422,12 +430,7 @@ function Dropdown({
     disabled: disabled || trigger.props.disabled,
   });
 
-  const widthStyle =
-    typeof width === 'number'
-      ? { width: `${width}px` }
-      : width === 'trigger'
-        ? { minWidth: '100%' }
-        : {};
+  const widthStyle = typeof width === 'number' ? { width: `${width}px` } : {};
 
   const filteredChildren = React.useMemo(
     () => filterDropdownChildren(children, searchQuery),
@@ -470,80 +473,88 @@ function Dropdown({
 
   return (
     <DropdownContext.Provider value={dropdownContext}>
-      <div ref={containerRef} className="relative inline-flex">
+      <div
+        ref={(node) => {
+          containerRef.current = node;
+          anchorRef.current = node;
+        }}
+        className="relative inline-flex"
+      >
         {triggerElement}
-        {isOpen && (
-          <div
-            style={widthStyle}
-            data-slot="dropdown-menu"
-            className={cn(
-              'absolute z-50 min-w-[12rem]',
-              'rounded-xl border border-neutral-200 bg-white shadow-lg',
-              'dark:border-neutral-700 dark:bg-neutral-800',
-              'animate-in fade-in zoom-in-95 duration-100',
-              placementStyles[placement],
-              className
-            )}
-          >
-            {searchable && (
-              <div
-                className="border-b border-neutral-200 p-2 dark:border-neutral-700"
-                data-slot="dropdown-search"
-              >
-                <input
-                  ref={searchInputRef}
-                  type="search"
-                  value={searchQuery}
-                  onChange={(event) => setSearchQuery(event.target.value)}
-                  placeholder={searchPlaceholder}
-                  aria-label={searchAriaLabel}
-                  aria-controls={menuId}
-                  aria-autocomplete="list"
-                  data-slot="dropdown-search-input"
-                  className={cn(
-                    inputVariants({ size: 'sm' }),
-                    'text-sm',
-                    'dark:border-neutral-600 dark:bg-neutral-700 dark:text-neutral-100'
+        {isOpen &&
+          createPortal(
+            <div
+              ref={floatingRef}
+              style={{ ...style, ...widthStyle }}
+              data-slot="dropdown-menu"
+              className={cn(
+                'min-w-[12rem] overflow-auto',
+                'rounded-xl border border-neutral-200 bg-white shadow-lg',
+                'dark:border-neutral-700 dark:bg-neutral-800',
+                'animate-in fade-in zoom-in-95 duration-100',
+                className
+              )}
+            >
+              {searchable && (
+                <div
+                  className="border-b border-neutral-200 p-2 dark:border-neutral-700"
+                  data-slot="dropdown-search"
+                >
+                  <input
+                    ref={searchInputRef}
+                    type="search"
+                    value={searchQuery}
+                    onChange={(event) => setSearchQuery(event.target.value)}
+                    placeholder={searchPlaceholder}
+                    aria-label={searchAriaLabel}
+                    aria-controls={menuId}
+                    aria-autocomplete="list"
+                    data-slot="dropdown-search-input"
+                    className={cn(
+                      inputVariants({ size: 'sm' }),
+                      'text-sm',
+                      'dark:border-neutral-600 dark:bg-neutral-700 dark:text-neutral-100'
+                    )}
+                  />
+                </div>
+              )}
+              <div id={menuId} role="menu">
+                {multiSelect &&
+                  showSelectAll &&
+                  visibleSelectableValues.length > 0 && (
+                    <>
+                      <div className="p-2" data-slot="dropdown-select-all">
+                        <DropdownItem
+                          checked={allVisibleSelected}
+                          indeterminate={
+                            !allVisibleSelected && someVisibleSelected
+                          }
+                          onClick={handleSelectAll}
+                        >
+                          {selectAllLabel}
+                        </DropdownItem>
+                      </div>
+                      <DropdownSeparator />
+                    </>
                   )}
-                />
-              </div>
-            )}
-            <div id={menuId} role="menu">
-              {multiSelect &&
-                showSelectAll &&
-                visibleSelectableValues.length > 0 && (
-                  <>
-                    <div className="p-2" data-slot="dropdown-select-all">
-                      <DropdownItem
-                        checked={allVisibleSelected}
-                        indeterminate={
-                          !allVisibleSelected && someVisibleSelected
-                        }
-                        onClick={handleSelectAll}
-                      >
-                        {selectAllLabel}
-                      </DropdownItem>
+                {searchable ? (
+                  hasSearchResults ? (
+                    filteredChildren
+                  ) : (
+                    <div
+                      className="text-muted-foreground px-3 py-4 text-center text-sm"
+                      data-slot="dropdown-empty"
+                    >
+                      {searchEmptyState}
                     </div>
-                    <DropdownSeparator />
-                  </>
-                )}
-              {searchable ? (
-                hasSearchResults ? (
-                  filteredChildren
+                  )
                 ) : (
-                  <div
-                    className="text-muted-foreground px-3 py-4 text-center text-sm"
-                    data-slot="dropdown-empty"
-                  >
-                    {searchEmptyState}
-                  </div>
-                )
-              ) : (
-                children
-              )}
-            </div>
-          </div>
-        )}
+                  children
+                )}
+              </div>
+            </div>,
+            document.body
+          )}
       </div>
     </DropdownContext.Provider>
   );
diff --git a/src/components/LanguageSelector/LanguageSelector.tsx b/src/components/LanguageSelector/LanguageSelector.tsx
index c5ffb5735..e02860105 100644
--- a/src/components/LanguageSelector/LanguageSelector.tsx
+++ b/src/components/LanguageSelector/LanguageSelector.tsx
@@ -1,6 +1,8 @@
 import * as React from 'react';
+import { createPortal } from 'react-dom';
 import { cva, type VariantProps } from 'class-variance-authority';
 import { cn } from '../../utils/cn';
+import { useAnchoredPosition } from '../../hooks/useAnchoredPosition';
 
 // =============================================================================
 // Types
@@ -137,6 +139,13 @@ export function LanguageSelector({
   const [isOpen, setIsOpen] = React.useState(false);
   const containerRef = React.useRef<HTMLDivElement>(null);
 
+  // Portal + fixed positioning so the dropdown escapes overflow-hidden
+  // ancestors (headers, cards, …).
+  const { anchorRef, floatingRef, style } = useAnchoredPosition<
+    HTMLDivElement,
+    HTMLDivElement
+  >({ open: isOpen, matchMinWidth: true, maxHeight: 240 });
+
   // Find selected language
   const selectedLanguage = languages.find((l) => l.code === value);
 
@@ -145,7 +154,8 @@ export function LanguageSelector({
     const handleClickOutside = (e: MouseEvent) => {
       if (
         containerRef.current &&
-        !containerRef.current.contains(e.target as Node)
+        !containerRef.current.contains(e.target as Node) &&
+        !floatingRef.current?.contains(e.target as Node)
       ) {
         setIsOpen(false);
       }
@@ -153,7 +163,7 @@ export function LanguageSelector({
 
     document.addEventListener('mousedown', handleClickOutside);
     return () => document.removeEventListener('mousedown', handleClickOutside);
-  }, []);
+  }, [floatingRef]);
 
   // Close on escape
   React.useEffect(() => {
@@ -172,7 +182,10 @@ export function LanguageSelector({
 
   return (
     <div
-      ref={containerRef}
+      ref={(node) => {
+        containerRef.current = node;
+        anchorRef.current = node;
+      }}
       data-slot="language-selector"
       className={cn(selectorVariants({ size }), className)}
     >
@@ -210,47 +223,47 @@ export function LanguageSelector({
       </button>
 
       {/* Dropdown */}
-      {isOpen && (
-        <div
-          data-slot="language-selector-dropdown"
-          className={cn(
-            'absolute z-50 mt-1 w-full min-w-[180px] rounded-lg border border-gray-200 bg-white shadow-lg',
-            'dark:border-gray-700 dark:bg-gray-800',
-            'animate-in fade-in slide-in-from-top-1 duration-150'
-          )}
-        >
-          <ul
-            role="listbox"
-            aria-label={label}
-            className="max-h-60 overflow-auto py-1"
+      {isOpen &&
+        createPortal(
+          <div
+            ref={floatingRef}
+            style={style}
+            data-slot="language-selector-dropdown"
+            className={cn(
+              'min-w-[180px] overflow-auto rounded-lg border border-gray-200 bg-white shadow-lg',
+              'dark:border-gray-700 dark:bg-gray-800',
+              'animate-in fade-in slide-in-from-top-1 duration-150'
+            )}
           >
-            {languages.map((language) => (
-              <li
-                key={language.code}
-                role="option"
-                aria-selected={language.code === value}
-                onClick={() => handleSelect(language)}
-                onKeyDown={(e) => e.key === 'Enter' && handleSelect(language)}
-                data-slot="language-selector-option"
-                className={cn(
-                  'flex cursor-pointer items-center gap-2 px-3 py-2 text-sm transition-colors',
-                  language.code === value
-                    ? 'bg-primary-50 text-primary-700 dark:bg-primary-900/20 dark:text-primary-400'
-                    : 'text-gray-700 hover:bg-gray-100 dark:text-gray-200 dark:hover:bg-gray-700'
-                )}
-              >
-                {showFlags && language.flag && (
-                  <span className="text-base">{language.flag}</span>
-                )}
-                <span className="flex-1">{language.name}</span>
-                {language.code === value && (
-                  <CheckIcon className="text-primary-800 dark:text-primary-400 h-4 w-4" />
-                )}
-              </li>
-            ))}
-          </ul>
-        </div>
-      )}
+            <ul role="listbox" aria-label={label} className="py-1">
+              {languages.map((language) => (
+                <li
+                  key={language.code}
+                  role="option"
+                  aria-selected={language.code === value}
+                  onClick={() => handleSelect(language)}
+                  onKeyDown={(e) => e.key === 'Enter' && handleSelect(language)}
+                  data-slot="language-selector-option"
+                  className={cn(
+                    'flex cursor-pointer items-center gap-2 px-3 py-2 text-sm transition-colors',
+                    language.code === value
+                      ? 'bg-primary-50 text-primary-700 dark:bg-primary-900/20 dark:text-primary-400'
+                      : 'text-gray-700 hover:bg-gray-100 dark:text-gray-200 dark:hover:bg-gray-700'
+                  )}
+                >
+                  {showFlags && language.flag && (
+                    <span className="text-base">{language.flag}</span>
+                  )}
+                  <span className="flex-1">{language.name}</span>
+                  {language.code === value && (
+                    <CheckIcon className="text-primary-800 dark:text-primary-400 h-4 w-4" />
+                  )}
+                </li>
+              ))}
+            </ul>
+          </div>,
+          document.body
+        )}
     </div>
   );
 }
diff --git a/src/components/Messaging/MessageComposer.tsx b/src/components/Messaging/MessageComposer.tsx
index ce5986b0a..0cbe70d9a 100644
--- a/src/components/Messaging/MessageComposer.tsx
+++ b/src/components/Messaging/MessageComposer.tsx
@@ -1,6 +1,8 @@
 import * as React from 'react';
+import { createPortal } from 'react-dom';
 import { cva, type VariantProps } from 'class-variance-authority';
 import { cn } from '../../utils/cn';
+import { useAnchoredPosition } from '../../hooks/useAnchoredPosition';
 import type { AttachmentType, NewMessage } from './types';
 import {
   AttachmentPicker,
@@ -423,6 +425,18 @@ const MessageComposer = React.forwardRef<
 
     const mentionMenuOpen =
       mentionsEnabled && mention !== null && mentionSuggestions.length > 0;
+
+    // Portal + fixed positioning so the mention menu escapes overflow-hidden
+    // ancestors.
+    const {
+      anchorRef: mentionAnchorRef,
+      floatingRef: mentionFloatingRef,
+      style: mentionStyle,
+    } = useAnchoredPosition<HTMLDivElement, HTMLUListElement>({
+      open: mentionMenuOpen,
+      placement: 'top-start',
+      maxHeight: 224,
+    });
     // Clamp the highlight to the current suggestion range so the active option
     // never points at a stale/out-of-range index (the list can shrink while the
     // menu is open as the query narrows). The same clamped index drives
@@ -711,54 +725,62 @@ const MessageComposer = React.forwardRef<
             )}
 
             {/* Text input */}
-            <div data-slot="composer-input-wrapper" className="relative flex-1">
-              {mentionMenuOpen && (
-                <ul
-                  id={mentionListId}
-                  role="listbox"
-                  aria-label="Mention"
-                  data-slot="composer-mention-list"
-                  className="absolute bottom-full left-0 z-10 mb-1 max-h-56 w-64 overflow-y-auto rounded-lg border border-neutral-200 bg-white py-1 shadow-lg dark:border-neutral-700 dark:bg-neutral-800"
-                >
-                  {mentionSuggestions.map((option, i) => (
-                    <li key={option.id}>
-                      <button
-                        type="button"
-                        id={mentionOptionId(i)}
-                        role="option"
-                        aria-selected={i === clampedMentionHighlight}
-                        // onMouseDown (not onClick) so the textarea keeps focus.
-                        onMouseDown={(e) => {
-                          e.preventDefault();
-                          insertMention(option);
-                        }}
-                        onMouseEnter={() => setMentionHighlight(i)}
-                        className={cn(
-                          'flex w-full items-center gap-2 px-3 py-1.5 text-left text-sm',
-                          i === clampedMentionHighlight
-                            ? 'bg-primary-100 text-primary-900 dark:bg-primary-900/40 dark:text-primary-100'
-                            : 'text-neutral-700 dark:text-neutral-200'
-                        )}
-                      >
-                        {option.icon}
-                        <span className="min-w-0 flex-1 truncate">
-                          <span className="font-medium">{option.label}</span>
-                          {option.description && (
-                            <span className="ml-1 text-xs text-neutral-400">
-                              {option.description}
-                            </span>
+            <div
+              data-slot="composer-input-wrapper"
+              className="relative flex-1"
+              ref={mentionAnchorRef}
+            >
+              {mentionMenuOpen &&
+                createPortal(
+                  <ul
+                    ref={mentionFloatingRef}
+                    style={mentionStyle}
+                    id={mentionListId}
+                    role="listbox"
+                    aria-label="Mention"
+                    data-slot="composer-mention-list"
+                    className="w-64 overflow-y-auto rounded-lg border border-neutral-200 bg-white py-1 shadow-lg dark:border-neutral-700 dark:bg-neutral-800"
+                  >
+                    {mentionSuggestions.map((option, i) => (
+                      <li key={option.id}>
+                        <button
+                          type="button"
+                          id={mentionOptionId(i)}
+                          role="option"
+                          aria-selected={i === clampedMentionHighlight}
+                          // onMouseDown (not onClick) so the textarea keeps focus.
+                          onMouseDown={(e) => {
+                            e.preventDefault();
+                            insertMention(option);
+                          }}
+                          onMouseEnter={() => setMentionHighlight(i)}
+                          className={cn(
+                            'flex w-full items-center gap-2 px-3 py-1.5 text-left text-sm',
+                            i === clampedMentionHighlight
+                              ? 'bg-primary-100 text-primary-900 dark:bg-primary-900/40 dark:text-primary-100'
+                              : 'text-neutral-700 dark:text-neutral-200'
                           )}
-                        </span>
-                        {option.meta && (
-                          <span className="text-[10px] text-neutral-400">
-                            {option.meta}
+                        >
+                          {option.icon}
+                          <span className="min-w-0 flex-1 truncate">
+                            <span className="font-medium">{option.label}</span>
+                            {option.description && (
+                              <span className="ml-1 text-xs text-neutral-400">
+                                {option.description}
+                              </span>
+                            )}
                           </span>
-                        )}
-                      </button>
-                    </li>
-                  ))}
-                </ul>
-              )}
+                          {option.meta && (
+                            <span className="text-[10px] text-neutral-400">
+                              {option.meta}
+                            </span>
+                          )}
+                        </button>
+                      </li>
+                    ))}
+                  </ul>,
+                  document.body
+                )}
               <textarea
                 ref={textareaRef}
                 data-slot="composer-input"
diff --git a/src/components/PatientHeader/PatientHeader.tsx b/src/components/PatientHeader/PatientHeader.tsx
index 275a539df..383f31e2f 100644
--- a/src/components/PatientHeader/PatientHeader.tsx
+++ b/src/components/PatientHeader/PatientHeader.tsx
@@ -1,7 +1,9 @@
 import * as React from 'react';
+import { createPortal } from 'react-dom';
 import { cn } from '../../utils/cn';
 import { useClickOutside } from '../../hooks/useClickOutside';
 import { useEscapeKey } from '../../hooks/useEscapeKey';
+import { useAnchoredPosition } from '../../hooks/useAnchoredPosition';
 import { Avatar } from '../Avatar';
 import { Badge } from '../Badge';
 import { Button } from '../Button';
@@ -314,8 +316,18 @@ function PatientOverflowMenu({
   const [open, setOpen] = React.useState(false);
   const menuRef = React.useRef<HTMLDivElement>(null);
 
+  // Portal + fixed positioning so the menu escapes overflow-hidden ancestors.
+  const { anchorRef, floatingRef, style } = useAnchoredPosition<
+    HTMLDivElement,
+    HTMLDivElement
+  >({ open, placement: 'bottom-end' });
+
+  const outsideRefs = React.useMemo(
+    () => [menuRef, floatingRef],
+    [floatingRef]
+  );
   useClickOutside(
-    menuRef,
+    outsideRefs,
     React.useCallback(() => setOpen(false), [])
   );
   useEscapeKey(
@@ -329,7 +341,13 @@ function PatientOverflowMenu({
   };
 
   return (
-    <div className="relative" ref={menuRef}>
+    <div
+      className="relative"
+      ref={(node) => {
+        menuRef.current = node;
+        anchorRef.current = node;
+      }}
+    >
       <Button
         variant="ghost"
         size="icon"
@@ -342,125 +360,128 @@ function PatientOverflowMenu({
         <MoreVerticalIcon size={18} />
       </Button>
 
-      {open && (
-        <div
-          role="menu"
-          aria-label="Patient actions"
-          className={cn(
-            'absolute top-full right-0 z-50 mt-1',
-            'w-[calc(100vw_-_2rem)] md:w-auto',
-            'border-border bg-card rounded-xl border py-1 shadow-lg',
-            'max-h-[calc(100vh_-_3rem)] overflow-y-auto md:max-h-[calc(100vh_-_4rem)]',
-            'motion-safe:animate-fade-in'
-          )}
-        >
-          {/* ── Quick Actions + Add: stacked on mobile, side-by-side on md+ ── */}
-          <div className="flex flex-col md:flex-row">
-            {/* Quick Actions column */}
-            <div className="min-w-[13rem]">
-              <div className="px-3 py-1.5">
-                <span className="text-muted-foreground text-[11px] font-semibold tracking-wide uppercase">
-                  Quick Actions
-                </span>
-              </div>
-              <OverflowMenuItem
-                icon={<PencilIcon size={15} />}
-                label="Edit Patient"
-                onClick={() => handleAction('edit-patient')}
-              />
-              <OverflowMenuItem
-                icon={<PhoneIcon size={15} />}
-                label="Contact"
-                onClick={() => handleAction('contact')}
-              />
-              <OverflowMenuItem
-                icon={<SendIcon size={15} />}
-                label="Send Message"
-                onClick={() => handleAction('send-message')}
-              />
-              <OverflowMenuItem
-                icon={<CalendarIcon size={15} />}
-                label="Schedule Appointment"
-                onClick={() => handleAction('schedule-appointment')}
-              />
-              <OverflowMenuItem
-                icon={<PrinterIcon size={15} />}
-                label="Print Summary"
-                onClick={() => handleAction('print-summary')}
-              />
-              <OverflowMenuItem
-                icon={<DownloadIcon size={15} />}
-                label="Export Record"
-                onClick={() => handleAction('export-record')}
-              />
-            </div>
-
-            {/* Divider: horizontal on mobile, vertical on desktop */}
-            <div className="border-border my-1 border-t md:my-0 md:border-t-0 md:border-l" />
-
-            {/* Add column */}
-            <div className="md:min-w-[26rem]">
-              <div className="px-3 py-1.5">
-                <span className="text-muted-foreground text-[11px] font-semibold tracking-wide uppercase">
-                  Add
-                </span>
-              </div>
-              <div className="grid grid-cols-1 gap-1 md:grid-cols-2 md:gap-2">
-                <OverflowMenuItem
-                  icon={<ClipboardPlusIcon size={15} />}
-                  label="Task"
-                  onClick={() => handleAction('add-task')}
-                />
-                <OverflowMenuItem
-                  icon={<StethoscopeIcon size={15} />}
-                  label="Encounter"
-                  onClick={() => handleAction('add-encounter')}
-                />
-                <OverflowMenuItem
-                  icon={<ClipboardCheckIcon size={15} />}
-                  label="Due List Item"
-                  onClick={() => handleAction('add-due-list')}
-                />
-                <OverflowMenuItem
-                  icon={<FilePlusIcon size={15} />}
-                  label="Order Request"
-                  onClick={() => handleAction('add-order')}
-                />
+      {open &&
+        createPortal(
+          <div
+            ref={floatingRef}
+            style={style}
+            role="menu"
+            aria-label="Patient actions"
+            className={cn(
+              'w-[calc(100vw_-_2rem)] md:w-auto',
+              'border-border bg-card rounded-xl border py-1 shadow-lg',
+              'overflow-y-auto',
+              'motion-safe:animate-fade-in'
+            )}
+          >
+            {/* ── Quick Actions + Add: stacked on mobile, side-by-side on md+ ── */}
+            <div className="flex flex-col md:flex-row">
+              {/* Quick Actions column */}
+              <div className="min-w-[13rem]">
+                <div className="px-3 py-1.5">
+                  <span className="text-muted-foreground text-[11px] font-semibold tracking-wide uppercase">
+                    Quick Actions
+                  </span>
+                </div>
                 <OverflowMenuItem
-                  icon={<FileCheckIcon size={15} />}
-                  label="eSign Request"
-                  onClick={() => handleAction('add-esign')}
+                  icon={<PencilIcon size={15} />}
+                  label="Edit Patient"
+                  onClick={() => handleAction('edit-patient')}
                 />
                 <OverflowMenuItem
-                  icon={<AllergyIcon size={15} />}
-                  label="Allergy"
-                  onClick={() => handleAction('add-allergy')}
+                  icon={<PhoneIcon size={15} />}
+                  label="Contact"
+                  onClick={() => handleAction('contact')}
                 />
                 <OverflowMenuItem
-                  icon={<PillIcon size={15} />}
-                  label="Medication"
-                  onClick={() => handleAction('add-medication')}
+                  icon={<SendIcon size={15} />}
+                  label="Send Message"
+                  onClick={() => handleAction('send-message')}
                 />
                 <OverflowMenuItem
-                  icon={<BellIcon size={15} />}
-                  label="Alert"
-                  onClick={() => handleAction('add-alert')}
+                  icon={<CalendarIcon size={15} />}
+                  label="Schedule Appointment"
+                  onClick={() => handleAction('schedule-appointment')}
                 />
                 <OverflowMenuItem
-                  icon={<FileHeartIcon size={15} />}
-                  label="Condition"
-                  onClick={() => handleAction('add-condition')}
+                  icon={<PrinterIcon size={15} />}
+                  label="Print Summary"
+                  onClick={() => handleAction('print-summary')}
                 />
                 <OverflowMenuItem
-                  icon={<HeartPulseIcon size={15} />}
-                  label="Vitals"
-                  onClick={() => handleAction('add-vitals')}
+                  icon={<DownloadIcon size={15} />}
+                  label="Export Record"
+                  onClick={() => handleAction('export-record')}
                 />
               </div>
+
+              {/* Divider: horizontal on mobile, vertical on desktop */}
+              <div className="border-border my-1 border-t md:my-0 md:border-t-0 md:border-l" />
+
+              {/* Add column */}
+              <div className="md:min-w-[26rem]">
+                <div className="px-3 py-1.5">
+                  <span className="text-muted-foreground text-[11px] font-semibold tracking-wide uppercase">
+                    Add
+                  </span>
+                </div>
+                <div className="grid grid-cols-1 gap-1 md:grid-cols-2 md:gap-2">
+                  <OverflowMenuItem
+                    icon={<ClipboardPlusIcon size={15} />}
+                    label="Task"
+                    onClick={() => handleAction('add-task')}
+                  />
+                  <OverflowMenuItem
+                    icon={<StethoscopeIcon size={15} />}
+                    label="Encounter"
+                    onClick={() => handleAction('add-encounter')}
+                  />
+                  <OverflowMenuItem
+                    icon={<ClipboardCheckIcon size={15} />}
+                    label="Due List Item"
+                    onClick={() => handleAction('add-due-list')}
+                  />
+                  <OverflowMenuItem
+                    icon={<FilePlusIcon size={15} />}
+                    label="Order Request"
+                    onClick={() => handleAction('add-order')}
+                  />
+                  <OverflowMenuItem
+                    icon={<FileCheckIcon size={15} />}
+                    label="eSign Request"
+                    onClick={() => handleAction('add-esign')}
+                  />
+                  <OverflowMenuItem
+                    icon={<AllergyIcon size={15} />}
+                    label="Allergy"
+                    onClick={() => handleAction('add-allergy')}
+                  />
+                  <OverflowMenuItem
+                    icon={<PillIcon size={15} />}
+                    label="Medication"
+                    onClick={() => handleAction('add-medication')}
+                  />
+                  <OverflowMenuItem
+                    icon={<BellIcon size={15} />}
+                    label="Alert"
+                    onClick={() => handleAction('add-alert')}
+                  />
+                  <OverflowMenuItem
+                    icon={<FileHeartIcon size={15} />}
+                    label="Condition"
+                    onClick={() => handleAction('add-condition')}
+                  />
+                  <OverflowMenuItem
+                    icon={<HeartPulseIcon size={15} />}
+                    label="Vitals"
+                    onClick={() => handleAction('add-vitals')}
+                  />
+                </div>
+              </div>
             </div>
-          </div>
-        </div>
-      )}
+          </div>,
+          document.body
+        )}
     </div>
   );
 }
diff --git a/src/components/ProviderSearchFilters/ProviderSearchFilters.tsx b/src/components/ProviderSearchFilters/ProviderSearchFilters.tsx
index 3f87beede..ade2cef62 100644
--- a/src/components/ProviderSearchFilters/ProviderSearchFilters.tsx
+++ b/src/components/ProviderSearchFilters/ProviderSearchFilters.tsx
@@ -1,8 +1,10 @@
 'use client';
 
 import * as React from 'react';
+import { createPortal } from 'react-dom';
 import { cva, type VariantProps } from 'class-variance-authority';
 import { cn } from '../../utils/cn';
+import { useAnchoredPosition } from '../../hooks/useAnchoredPosition';
 
 // ============================================================================
 // Types
@@ -324,19 +326,26 @@ export function ServiceMultiSelect({
   const inputRef = React.useRef<HTMLInputElement>(null);
   const listboxId = React.useId();
 
+  // Portal + fixed positioning so the panel escapes overflow-hidden ancestors.
+  const { anchorRef, floatingRef, style } = useAnchoredPosition<
+    HTMLDivElement,
+    HTMLDivElement
+  >({ open: isOpen, matchWidth: true, maxHeight: 240 });
+
   // Close dropdown when clicking outside
   React.useEffect(() => {
     function handleClickOutside(event: MouseEvent) {
       if (
         containerRef.current &&
-        !containerRef.current.contains(event.target as Node)
+        !containerRef.current.contains(event.target as Node) &&
+        !floatingRef.current?.contains(event.target as Node)
       ) {
         setIsOpen(false);
       }
     }
     document.addEventListener('mousedown', handleClickOutside);
     return () => document.removeEventListener('mousedown', handleClickOutside);
-  }, []);
+  }, [floatingRef]);
 
   // Filter services based on search
   const filteredServices = React.useMemo(() => {
@@ -388,7 +397,10 @@ export function ServiceMultiSelect({
 
   return (
     <div
-      ref={containerRef}
+      ref={(node) => {
+        containerRef.current = node;
+        anchorRef.current = node;
+      }}
       className="relative"
       data-slot="provider-service-select"
     >
@@ -431,113 +443,119 @@ export function ServiceMultiSelect({
       </div>
 
       {/* Dropdown panel */}
-      {isOpen && (
-        <div
-          className={cn(
-            'absolute z-50 mt-1 w-full rounded-md border border-neutral-200 bg-white shadow-lg',
-            'dark:border-neutral-700 dark:bg-neutral-800',
-            'max-h-60 overflow-auto'
-          )}
-          role="listbox"
-          id={listboxId}
-          aria-multiselectable="true"
-        >
-          {/* Search input */}
-          <div className="sticky top-0 border-b border-neutral-200 bg-white p-2 dark:border-neutral-700 dark:bg-neutral-800">
-            <input
-              ref={inputRef}
-              type="text"
-              value={searchTerm}
-              onChange={(e) => setSearchTerm(e.target.value)}
-              placeholder="Search services..."
-              className={cn(inputVariants({ hasIcon: true }), 'pl-8')}
-              // eslint-disable-next-line jsx-a11y/no-autofocus
-              autoFocus
-            />
-            <SearchIcon className="absolute top-1/2 left-4 -translate-y-1/2 text-neutral-400" />
-          </div>
+      {isOpen &&
+        createPortal(
+          <div
+            ref={floatingRef}
+            style={style}
+            className={cn(
+              'rounded-md border border-neutral-200 bg-white shadow-lg',
+              'dark:border-neutral-700 dark:bg-neutral-800',
+              'overflow-auto'
+            )}
+            role="listbox"
+            id={listboxId}
+            aria-multiselectable="true"
+          >
+            {/* Search input */}
+            <div className="sticky top-0 border-b border-neutral-200 bg-white p-2 dark:border-neutral-700 dark:bg-neutral-800">
+              <input
+                ref={inputRef}
+                type="text"
+                value={searchTerm}
+                onChange={(e) => setSearchTerm(e.target.value)}
+                placeholder="Search services..."
+                className={cn(inputVariants({ hasIcon: true }), 'pl-8')}
+                // eslint-disable-next-line jsx-a11y/no-autofocus
+                autoFocus
+              />
+              <SearchIcon className="absolute top-1/2 left-4 -translate-y-1/2 text-neutral-400" />
+            </div>
 
-          {/* Service options */}
-          {Object.entries(groupedServices).length > 0 ? (
-            Object.entries(groupedServices).map(
-              ([category, categoryServices]) => (
-                <div key={category}>
-                  {services.some((s) => s.category) && (
-                    <div className="bg-neutral-50 px-3 py-2 text-xs font-semibold tracking-wider text-neutral-500 uppercase dark:bg-neutral-900 dark:text-neutral-400">
-                      {category}
-                    </div>
-                  )}
-                  {categoryServices.map((service) => {
-                    const isSelected = selectedServices.includes(service.value);
-                    return (
-                      <button
-                        key={service.value}
-                        type="button"
-                        role="option"
-                        aria-selected={isSelected}
-                        onClick={() => handleToggleService(service.value)}
-                        className={cn(
-                          'flex w-full items-center justify-between px-3 py-2 text-left text-sm',
-                          'hover:bg-neutral-100 dark:hover:bg-neutral-700',
-                          isSelected && 'bg-primary-50 dark:bg-primary-900/20'
-                        )}
-                      >
-                        <span className="flex items-center gap-2">
-                          <span
-                            className={cn(
-                              'flex h-4 w-4 items-center justify-center rounded border',
-                              isSelected
-                                ? 'bg-primary-800 border-primary-500 text-white'
-                                : 'border-neutral-300 dark:border-neutral-600'
-                            )}
-                          >
-                            {isSelected && (
-                              <svg
-                                aria-hidden="true"
-                                className="h-3 w-3"
-                                viewBox="0 0 12 12"
-                                fill="currentColor"
-                              >
-                                <path d="M10.28 2.28L4.75 7.81 1.72 4.78a.75.75 0 00-1.06 1.06l3.75 3.75a.75.75 0 001.06 0l6.25-6.25a.75.75 0 00-1.06-1.06z" />
-                              </svg>
-                            )}
-                          </span>
-                          {service.label}
-                        </span>
-                        {showCounts && service.count !== undefined && (
-                          <span className="text-xs text-neutral-400">
-                            ({service.count})
+            {/* Service options */}
+            {Object.entries(groupedServices).length > 0 ? (
+              Object.entries(groupedServices).map(
+                ([category, categoryServices]) => (
+                  <div key={category}>
+                    {services.some((s) => s.category) && (
+                      <div className="bg-neutral-50 px-3 py-2 text-xs font-semibold tracking-wider text-neutral-500 uppercase dark:bg-neutral-900 dark:text-neutral-400">
+                        {category}
+                      </div>
+                    )}
+                    {categoryServices.map((service) => {
+                      const isSelected = selectedServices.includes(
+                        service.value
+                      );
+                      return (
+                        <button
+                          key={service.value}
+                          type="button"
+                          role="option"
+                          aria-selected={isSelected}
+                          onClick={() => handleToggleService(service.value)}
+                          className={cn(
+                            'flex w-full items-center justify-between px-3 py-2 text-left text-sm',
+                            'hover:bg-neutral-100 dark:hover:bg-neutral-700',
+                            isSelected && 'bg-primary-50 dark:bg-primary-900/20'
+                          )}
+                        >
+                          <span className="flex items-center gap-2">
+                            <span
+                              className={cn(
+                                'flex h-4 w-4 items-center justify-center rounded border',
+                                isSelected
+                                  ? 'bg-primary-800 border-primary-500 text-white'
+                                  : 'border-neutral-300 dark:border-neutral-600'
+                              )}
+                            >
+                              {isSelected && (
+                                <svg
+                                  aria-hidden="true"
+                                  className="h-3 w-3"
+                                  viewBox="0 0 12 12"
+                                  fill="currentColor"
+                                >
+                                  <path d="M10.28 2.28L4.75 7.81 1.72 4.78a.75.75 0 00-1.06 1.06l3.75 3.75a.75.75 0 001.06 0l6.25-6.25a.75.75 0 00-1.06-1.06z" />
+                                </svg>
+                              )}
+                            </span>
+                            {service.label}
                           </span>
-                        )}
-                      </button>
-                    );
-                  })}
-                </div>
+                          {showCounts && service.count !== undefined && (
+                            <span className="text-xs text-neutral-400">
+                              ({service.count})
+                            </span>
+                          )}
+                        </button>
+                      );
+                    })}
+                  </div>
+                )
               )
-            )
-          ) : (
-            <div className="text-muted-foreground px-3 py-4 text-center text-sm">
-              No services found
-            </div>
-          )}
+            ) : (
+              <div className="text-muted-foreground px-3 py-4 text-center text-sm">
+                No services found
+              </div>
+            )}
 
-          {/* Clear selection */}
-          {selectedServices.length > 0 && (
-            <div className="sticky bottom-0 border-t border-neutral-200 bg-white p-2 dark:border-neutral-700 dark:bg-neutral-800">
-              <button
-                type="button"
-                onClick={() => onSelectionChange([])}
-                className={cn(
-                  'w-full rounded-md px-3 py-2 text-center text-sm',
-                  'text-red-600 hover:bg-red-50 dark:text-red-400 dark:hover:bg-red-900/20'
-                )}
-              >
-                Clear selection
-              </button>
-            </div>
-          )}
-        </div>
-      )}
+            {/* Clear selection */}
+            {selectedServices.length > 0 && (
+              <div className="sticky bottom-0 border-t border-neutral-200 bg-white p-2 dark:border-neutral-700 dark:bg-neutral-800">
+                <button
+                  type="button"
+                  onClick={() => onSelectionChange([])}
+                  className={cn(
+                    'w-full rounded-md px-3 py-2 text-center text-sm',
+                    'text-red-600 hover:bg-red-50 dark:text-red-400 dark:hover:bg-red-900/20'
+                  )}
+                >
+                  Clear selection
+                </button>
+              </div>
+            )}
+          </div>,
+          document.body
+        )}
     </div>
   );
 }
diff --git a/src/components/ProviderSelector/ProviderSelector.tsx b/src/components/ProviderSelector/ProviderSelector.tsx
index 8adc5c4ea..f851a774c 100644
--- a/src/components/ProviderSelector/ProviderSelector.tsx
+++ b/src/components/ProviderSelector/ProviderSelector.tsx
@@ -1,7 +1,9 @@
 'use client';
 
 import * as React from 'react';
+import { createPortal } from 'react-dom';
 import { cn } from '../../utils/cn';
+import { useAnchoredPosition } from '../../hooks/useAnchoredPosition';
 
 export interface ProviderOption {
   /** Unique identifier */
@@ -65,12 +67,20 @@ export function ProviderSelector({
   const [searchQuery, setSearchQuery] = React.useState('');
   const containerRef = React.useRef<HTMLDivElement>(null);
 
+  // Portal + fixed positioning so the dropdown escapes overflow-hidden
+  // ancestors.
+  const { anchorRef, floatingRef, style } = useAnchoredPosition<
+    HTMLDivElement,
+    HTMLDivElement
+  >({ open: isOpen, matchWidth: true });
+
   // Close on click outside
   React.useEffect(() => {
     function handleClickOutside(event: MouseEvent) {
       if (
         containerRef.current &&
-        !containerRef.current.contains(event.target as Node)
+        !containerRef.current.contains(event.target as Node) &&
+        !floatingRef.current?.contains(event.target as Node)
       ) {
         setIsOpen(false);
       }
@@ -78,7 +88,7 @@ export function ProviderSelector({
 
     document.addEventListener('mousedown', handleClickOutside);
     return () => document.removeEventListener('mousedown', handleClickOutside);
-  }, []);
+  }, [floatingRef]);
 
   // Close on escape
   React.useEffect(() => {
@@ -134,7 +144,10 @@ export function ProviderSelector({
     <div
       data-slot="provider-selector"
       className={cn('relative', className)}
-      ref={containerRef}
+      ref={(node) => {
+        containerRef.current = node;
+        anchorRef.current = node;
+      }}
     >
       {label && (
         <label
@@ -246,139 +259,143 @@ export function ProviderSelector({
       </button>
 
       {/* Dropdown */}
-      {isOpen && (
-        <div
-          data-slot="provider-selector-dropdown"
-          className="border-border bg-card absolute z-50 mt-1 w-full overflow-hidden rounded-lg border shadow-lg"
-        >
-          {/* Search */}
-          {searchable && (
-            <div className="border-border border-b p-2">
-              <div className="relative">
-                <svg
-                  aria-hidden="true"
-                  className="text-muted-foreground absolute top-1/2 left-3 h-4 w-4 -translate-y-1/2"
-                  fill="none"
-                  viewBox="0 0 24 24"
-                  stroke="currentColor"
-                >
-                  <path
-                    strokeLinecap="round"
-                    strokeLinejoin="round"
-                    strokeWidth={2}
-                    d="M21 21l-6-6m2-5a7 7 0 11-14 0 7 7 0 0114 0z"
+      {isOpen &&
+        createPortal(
+          <div
+            ref={floatingRef}
+            style={style}
+            data-slot="provider-selector-dropdown"
+            className="border-border bg-card flex flex-col overflow-hidden rounded-lg border shadow-lg"
+          >
+            {/* Search */}
+            {searchable && (
+              <div className="border-border border-b p-2">
+                <div className="relative">
+                  <svg
+                    aria-hidden="true"
+                    className="text-muted-foreground absolute top-1/2 left-3 h-4 w-4 -translate-y-1/2"
+                    fill="none"
+                    viewBox="0 0 24 24"
+                    stroke="currentColor"
+                  >
+                    <path
+                      strokeLinecap="round"
+                      strokeLinejoin="round"
+                      strokeWidth={2}
+                      d="M21 21l-6-6m2-5a7 7 0 11-14 0 7 7 0 0114 0z"
+                    />
+                  </svg>
+                  <input
+                    type="text"
+                    data-slot="provider-selector-search"
+                    placeholder={searchPlaceholder}
+                    value={searchQuery}
+                    onChange={(e) => setSearchQuery(e.target.value)}
+                    className="border-input bg-background text-foreground placeholder:text-muted-foreground focus:ring-ring w-full rounded-md border py-2 pr-4 pl-9 text-sm focus:ring-1 focus:outline-none"
+                    // eslint-disable-next-line jsx-a11y/no-autofocus
+                    autoFocus
                   />
-                </svg>
-                <input
-                  type="text"
-                  data-slot="provider-selector-search"
-                  placeholder={searchPlaceholder}
-                  value={searchQuery}
-                  onChange={(e) => setSearchQuery(e.target.value)}
-                  className="border-input bg-background text-foreground placeholder:text-muted-foreground focus:ring-ring w-full rounded-md border py-2 pr-4 pl-9 text-sm focus:ring-1 focus:outline-none"
-                  // eslint-disable-next-line jsx-a11y/no-autofocus
-                  autoFocus
-                />
-              </div>
-            </div>
-          )}
-
-          {/* Options list */}
-          <div className="max-h-64 overflow-y-auto">
-            {filteredProviders.length === 0 ? (
-              <div className="text-muted-foreground px-4 py-6 text-center">
-                No providers found
+                </div>
               </div>
-            ) : (
-              filteredProviders.map((provider) => (
-                <button
-                  key={provider.id}
-                  type="button"
-                  data-slot="provider-selector-option"
-                  onClick={() => handleSelect(provider)}
-                  className={cn(
-                    'flex w-full items-center gap-3 px-4 py-3 text-left transition-colors',
-                    'hover:bg-muted',
-                    selectedProvider?.id === provider.id && 'bg-primary/10'
-                  )}
-                >
-                  {/* Provider avatar/logo */}
-                  {provider.logoUrl ? (
-                    <img
-                      data-slot="provider-selector-option-avatar"
-                      src={provider.logoUrl}
-                      alt={provider.name}
-                      className="h-8 w-8 rounded object-cover"
-                    />
-                  ) : (
-                    <div
-                      data-slot="provider-selector-option-avatar"
-                      className="bg-muted text-muted-foreground flex h-8 w-8 items-center justify-center rounded text-sm font-medium"
-                    >
-                      {getInitials(provider.name)}
-                    </div>
-                  )}
+            )}
 
-                  <div className="min-w-0 flex-1">
-                    <div className="flex items-center gap-2">
-                      <span
-                        data-slot="provider-selector-option-name"
-                        className="text-foreground font-medium"
+            {/* Options list */}
+            <div className="max-h-64 overflow-y-auto">
+              {filteredProviders.length === 0 ? (
+                <div className="text-muted-foreground px-4 py-6 text-center">
+                  No providers found
+                </div>
+              ) : (
+                filteredProviders.map((provider) => (
+                  <button
+                    key={provider.id}
+                    type="button"
+                    data-slot="provider-selector-option"
+                    onClick={() => handleSelect(provider)}
+                    className={cn(
+                      'flex w-full items-center gap-3 px-4 py-3 text-left transition-colors',
+                      'hover:bg-muted',
+                      selectedProvider?.id === provider.id && 'bg-primary/10'
+                    )}
+                  >
+                    {/* Provider avatar/logo */}
+                    {provider.logoUrl ? (
+                      <img
+                        data-slot="provider-selector-option-avatar"
+                        src={provider.logoUrl}
+                        alt={provider.name}
+                        className="h-8 w-8 rounded object-cover"
+                      />
+                    ) : (
+                      <div
+                        data-slot="provider-selector-option-avatar"
+                        className="bg-muted text-muted-foreground flex h-8 w-8 items-center justify-center rounded text-sm font-medium"
                       >
-                        {provider.name}
-                      </span>
-                      {provider.code && (
+                        {getInitials(provider.name)}
+                      </div>
+                    )}
+
+                    <div className="min-w-0 flex-1">
+                      <div className="flex items-center gap-2">
                         <span
-                          data-slot="provider-selector-option-code"
-                          className="text-xs text-neutral-600 dark:text-neutral-400"
+                          data-slot="provider-selector-option-name"
+                          className="text-foreground font-medium"
                         >
-                          ({provider.code})
+                          {provider.name}
                         </span>
-                      )}
-                      {provider.isActive === false && (
-                        <span
-                          data-slot="provider-selector-option-badge"
-                          className="bg-muted rounded px-1.5 py-0.5 text-xs font-medium text-neutral-600 dark:text-neutral-400"
+                        {provider.code && (
+                          <span
+                            data-slot="provider-selector-option-code"
+                            className="text-xs text-neutral-600 dark:text-neutral-400"
+                          >
+                            ({provider.code})
+                          </span>
+                        )}
+                        {provider.isActive === false && (
+                          <span
+                            data-slot="provider-selector-option-badge"
+                            className="bg-muted rounded px-1.5 py-0.5 text-xs font-medium text-neutral-600 dark:text-neutral-400"
+                          >
+                            Inactive
+                          </span>
+                        )}
+                      </div>
+                      {(provider.location || provider.type) && (
+                        <div
+                          data-slot="provider-selector-option-detail"
+                          className="text-muted-foreground truncate text-sm"
                         >
-                          Inactive
-                        </span>
+                          {[provider.type, provider.location]
+                            .filter(Boolean)
+                            .join(' • ')}
+                        </div>
                       )}
                     </div>
-                    {(provider.location || provider.type) && (
-                      <div
-                        data-slot="provider-selector-option-detail"
-                        className="text-muted-foreground truncate text-sm"
+
+                    {/* Selected checkmark */}
+                    {selectedProvider?.id === provider.id && (
+                      <svg
+                        aria-hidden="true"
+                        className="text-primary-800 dark:text-primary-400 h-5 w-5 flex-shrink-0"
+                        fill="none"
+                        viewBox="0 0 24 24"
+                        stroke="currentColor"
                       >
-                        {[provider.type, provider.location]
-                          .filter(Boolean)
-                          .join(' • ')}
-                      </div>
+                        <path
+                          strokeLinecap="round"
+                          strokeLinejoin="round"
+                          strokeWidth={2}
+                          d="M5 13l4 4L19 7"
+                        />
+                      </svg>
                     )}
-                  </div>
-
-                  {/* Selected checkmark */}
-                  {selectedProvider?.id === provider.id && (
-                    <svg
-                      aria-hidden="true"
-                      className="text-primary-800 dark:text-primary-400 h-5 w-5 flex-shrink-0"
-                      fill="none"
-                      viewBox="0 0 24 24"
-                      stroke="currentColor"
-                    >
-                      <path
-                        strokeLinecap="round"
-                        strokeLinejoin="round"
-                        strokeWidth={2}
-                        d="M5 13l4 4L19 7"
-                      />
-                    </svg>
-                  )}
-                </button>
-              ))
-            )}
-          </div>
-        </div>
-      )}
+                  </button>
+                ))
+              )}
+            </div>
+          </div>,
+          document.body
+        )}
     </div>
   );
 }
diff --git a/src/components/Select/Select.tsx b/src/components/Select/Select.tsx
index 98a6c6fc0..ffbd7d189 100644
--- a/src/components/Select/Select.tsx
+++ b/src/components/Select/Select.tsx
@@ -3,6 +3,7 @@ import { createPortal } from 'react-dom';
 import { cva, type VariantProps } from 'class-variance-authority';
 import { cn } from '../../utils/cn';
 import { useEscapeKey } from '../../hooks/useEscapeKey';
+import { useAnchoredPosition } from '../../hooks/useAnchoredPosition';
 
 // ============================================================================
 // Types
@@ -238,53 +239,15 @@ function Select({
   }, isOpen);
 
   // Track trigger position for portal dropdown
-  const [dropdownStyle, setDropdownStyle] = React.useState<React.CSSProperties>(
-    {}
-  );
-
-  const updateDropdownPosition = React.useCallback(() => {
-    if (!triggerRef.current) return;
-    const rect = triggerRef.current.getBoundingClientRect();
-    const spaceBelow = window.innerHeight - rect.bottom;
-    const spaceAbove = rect.top;
-    const isCondensed = document.body.classList.contains('condensed');
-    const optionHeight = isCondensed ? 28 : 40;
-    const estimatedDropdownHeight = Math.min(
-      flatOptions.length * optionHeight + 16,
-      300
-    );
-    const openAbove =
-      spaceBelow < estimatedDropdownHeight && spaceAbove > spaceBelow;
-
-    setDropdownStyle({
-      position: 'fixed',
-      ...(openAbove
-        ? { bottom: window.innerHeight - rect.top + 4 }
-        : { top: rect.bottom + 4 }),
-      left: rect.left,
-      width: rect.width,
-      maxHeight: Math.max(
-        Math.min(openAbove ? spaceAbove - 8 : spaceBelow - 8, 300),
-        0
-      ),
-      display: 'flex',
-      flexDirection: 'column' as const,
-      overflow: 'hidden',
-      zIndex: 9999,
-    });
-  }, [flatOptions.length]);
-
-  React.useEffect(() => {
-    if (!isOpen) return;
-    updateDropdownPosition();
-
-    window.addEventListener('scroll', updateDropdownPosition, true);
-    window.addEventListener('resize', updateDropdownPosition);
-    return () => {
-      window.removeEventListener('scroll', updateDropdownPosition, true);
-      window.removeEventListener('resize', updateDropdownPosition);
-    };
-  }, [isOpen, updateDropdownPosition]);
+  const {
+    anchorRef,
+    floatingRef,
+    style: dropdownStyle,
+  } = useAnchoredPosition<HTMLButtonElement, HTMLDivElement>({
+    open: isOpen,
+    matchWidth: true,
+    maxHeight: 300,
+  });
 
   // Handle value change
   const handleValueChange = React.useCallback(
@@ -388,7 +351,10 @@ function Select({
         {/* Trigger Button */}
         <button
           data-slot="select-trigger"
-          ref={triggerRef}
+          ref={(node) => {
+            triggerRef.current = node;
+            anchorRef.current = node;
+          }}
           id={selectId}
           type="button"
           role="combobox"
@@ -426,10 +392,14 @@ function Select({
           createPortal(
             <div
               data-slot="select-dropdown"
-              ref={dropdownRef}
+              ref={(node) => {
+                dropdownRef.current = node;
+                floatingRef.current = node;
+              }}
               style={dropdownStyle}
               className={cn(
                 'border-border bg-card rounded-lg border shadow-lg',
+                'flex flex-col overflow-hidden',
                 'animate-in fade-in zoom-in-95 duration-100'
               )}
             >
diff --git a/src/hooks/index.ts b/src/hooks/index.ts
index bc6ea01a8..172a1cc77 100644
--- a/src/hooks/index.ts
+++ b/src/hooks/index.ts
@@ -1,6 +1,12 @@
 export { useTheme, type Theme, type ResolvedTheme } from './useTheme';
 export { usePrefersReducedMotion } from './usePrefersReducedMotion';
 export { useClickOutside } from './useClickOutside';
+export {
+  useAnchoredPosition,
+  type AnchoredPlacement,
+  type UseAnchoredPositionOptions,
+  type UseAnchoredPositionReturn,
+} from './useAnchoredPosition';
 export { useEscapeKey } from './useEscapeKey';
 export { useFocusTrap } from './useFocusTrap';
 export {
diff --git a/src/hooks/useAnchoredPosition.ts b/src/hooks/useAnchoredPosition.ts
new file mode 100644
index 000000000..8ff40c940
--- /dev/null
+++ b/src/hooks/useAnchoredPosition.ts
@@ -0,0 +1,212 @@
+'use client';
+
+import * as React from 'react';
+
+export type AnchoredPlacement =
+  | 'bottom-start'
+  | 'bottom-end'
+  | 'bottom'
+  | 'top-start'
+  | 'top-end'
+  | 'top';
+
+export interface UseAnchoredPositionOptions {
+  /** Whether the floating element is currently shown */
+  open: boolean;
+  /** Preferred placement relative to the anchor (flips when out of space) */
+  placement?: AnchoredPlacement;
+  /** Gap between the anchor and the floating element, in px */
+  offset?: number;
+  /** Force the floating element to the anchor's width */
+  matchWidth?: boolean;
+  /** Use the anchor's width as the floating element's minimum width */
+  matchMinWidth?: boolean;
+  /** Minimum distance from the viewport edges, in px */
+  viewportPadding?: number;
+  /** Cap the floating element's height, in px */
+  maxHeight?: number;
+}
+
+export interface UseAnchoredPositionReturn<
+  TAnchor extends HTMLElement,
+  TFloating extends HTMLElement,
+> {
+  /** Attach to the element the popup is anchored to (trigger/input) */
+  anchorRef: React.RefObject<TAnchor | null>;
+  /** Attach to the floating element (menu/listbox/panel) */
+  floatingRef: React.RefObject<TFloating | null>;
+  /** Fixed-position style for the floating element — spread onto it */
+  style: React.CSSProperties;
+  /** Vertical side in use after flipping ('top' or 'bottom') */
+  actualSide: 'top' | 'bottom';
+  /** Recompute the position (e.g. after async content loads) */
+  update: () => void;
+}
+
+const HIDDEN_STYLE: React.CSSProperties = {
+  position: 'fixed',
+  top: 0,
+  left: 0,
+  visibility: 'hidden',
+  zIndex: 9999,
+  // Never let `transition-*` utilities animate top/left from the hidden
+  // (0,0) mount position to the computed one (keyframe animations like
+  // `animate-in` are unaffected).
+  transition: 'none',
+};
+
+/**
+ * Positions a floating element (dropdown menu, autocomplete listbox,
+ * date-picker calendar, …) relative to an anchor using `position: fixed`,
+ * so it is never clipped by `overflow: hidden` ancestors.
+ *
+ * Render the floating element through `createPortal(..., document.body)`
+ * and spread the returned `style` onto it. The hook:
+ * - flips vertically when there is not enough space on the preferred side
+ * - clamps horizontally to the viewport
+ * - constrains `maxHeight` to the available space (add `overflow-auto`)
+ * - tracks scroll, resize, and anchor/content size changes while open
+ *
+ * @example
+ * ```tsx
+ * const { anchorRef, floatingRef, style } = useAnchoredPosition<
+ *   HTMLButtonElement,
+ *   HTMLDivElement
+ * >({ open, placement: 'bottom-start' });
+ *
+ * <button ref={anchorRef} onClick={() => setOpen(!open)}>Open</button>
+ * {open &&
+ *   createPortal(
+ *     <div ref={floatingRef} style={style} className="overflow-auto …">…</div>,
+ *     document.body
+ *   )}
+ * ```
+ */
+export function useAnchoredPosition<
+  TAnchor extends HTMLElement = HTMLElement,
+  TFloating extends HTMLElement = HTMLElement,
+>({
+  open,
+  placement = 'bottom-start',
+  offset = 4,
+  matchWidth = false,
+  matchMinWidth = false,
+  viewportPadding = 8,
+  maxHeight,
+}: UseAnchoredPositionOptions): UseAnchoredPositionReturn<TAnchor, TFloating> {
+  const anchorRef = React.useRef<TAnchor | null>(null);
+  const floatingRef = React.useRef<TFloating | null>(null);
+  const [style, setStyle] = React.useState<React.CSSProperties>(HIDDEN_STYLE);
+  const [actualSide, setActualSide] = React.useState<'top' | 'bottom'>(
+    placement.startsWith('top') ? 'top' : 'bottom'
+  );
+
+  const update = React.useCallback(() => {
+    const anchor = anchorRef.current;
+    const floating = floatingRef.current;
+    if (!anchor || !floating) return;
+
+    const rect = anchor.getBoundingClientRect();
+    const viewportWidth = window.innerWidth;
+    const viewportHeight = window.innerHeight;
+
+    // Natural content size (scrollHeight so a previously applied maxHeight
+    // doesn't skew the flip decision).
+    const contentHeight = Math.min(
+      floating.scrollHeight,
+      maxHeight ?? Infinity
+    );
+    const floatingWidth = matchWidth ? rect.width : floating.offsetWidth;
+
+    // --- Vertical: preferred side, flip when out of space -------------------
+    const spaceBelow = viewportHeight - rect.bottom - offset - viewportPadding;
+    const spaceAbove = rect.top - offset - viewportPadding;
+    const preferTop = placement.startsWith('top');
+    let side: 'top' | 'bottom';
+    if (preferTop) {
+      side =
+        spaceAbove < contentHeight && spaceBelow > spaceAbove
+          ? 'bottom'
+          : 'top';
+    } else {
+      side =
+        spaceBelow < contentHeight && spaceAbove > spaceBelow
+          ? 'top'
+          : 'bottom';
+    }
+    const availableHeight = Math.max(
+      side === 'top' ? spaceAbove : spaceBelow,
+      0
+    );
+
+    // --- Horizontal: -start aligns left edges, -end aligns right edges ------
+    const align = placement.endsWith('-start')
+      ? 'left'
+      : placement.endsWith('-end')
+        ? 'right'
+        : 'center';
+    let left =
+      align === 'left'
+        ? rect.left
+        : align === 'right'
+          ? rect.right - floatingWidth
+          : rect.left + rect.width / 2 - floatingWidth / 2;
+    left = Math.min(
+      Math.max(left, viewportPadding),
+      Math.max(viewportWidth - floatingWidth - viewportPadding, viewportPadding)
+    );
+
+    setActualSide(side);
+    setStyle({
+      position: 'fixed',
+      left,
+      ...(side === 'top'
+        ? { bottom: viewportHeight - rect.top + offset }
+        : { top: rect.bottom + offset }),
+      ...(matchWidth ? { width: rect.width } : {}),
+      ...(matchMinWidth ? { minWidth: rect.width } : {}),
+      maxHeight: Math.min(availableHeight, maxHeight ?? Infinity),
+      zIndex: 9999,
+      transition: 'none',
+    });
+  }, [
+    matchMinWidth,
+    matchWidth,
+    maxHeight,
+    offset,
+    placement,
+    viewportPadding,
+  ]);
+
+  // Position synchronously before paint when opening / re-rendering open.
+  React.useLayoutEffect(() => {
+    if (open) {
+      update();
+    } else {
+      setStyle(HIDDEN_STYLE);
+    }
+  }, [open, update]);
+
+  // Track scroll/resize and anchor/content size changes while open.
+  React.useEffect(() => {
+    if (!open) return;
+
+    window.addEventListener('scroll', update, true);
+    window.addEventListener('resize', update);
+
+    let resizeObserver: globalThis.ResizeObserver | undefined;
+    if (typeof globalThis.ResizeObserver !== 'undefined') {
+      resizeObserver = new globalThis.ResizeObserver(update);
+      if (anchorRef.current) resizeObserver.observe(anchorRef.current);
+      if (floatingRef.current) resizeObserver.observe(floatingRef.current);
+    }
+
+    return () => {
+      window.removeEventListener('scroll', update, true);
+      window.removeEventListener('resize', update);
+      resizeObserver?.disconnect();
+    };
+  }, [open, update]);
+
+  return { anchorRef, floatingRef, style, actualSide, update };
+}
diff --git a/src/hooks/useClickOutside.ts b/src/hooks/useClickOutside.ts
index 4b04a7d4b..5a3dd0171 100644
--- a/src/hooks/useClickOutside.ts
+++ b/src/hooks/useClickOutside.ts
@@ -22,7 +22,7 @@ import { useEffect, type RefObject } from 'react';
  * ```
  */
 export function useClickOutside<T extends HTMLElement>(
-  ref: RefObject<T | null>,
+  ref: RefObject<T | null> | Array<RefObject<HTMLElement | null>>,
   callback: () => void,
   enabled: boolean = true
 ): void {
@@ -30,10 +30,10 @@ export function useClickOutside<T extends HTMLElement>(
     if (!enabled) return;
 
     const handleClick = (event: Event) => {
-      if (
-        ref.current &&
-        !ref.current.contains(event.target as globalThis.Node)
-      ) {
+      const refs = Array.isArray(ref) ? ref : [ref];
+      const target = event.target as globalThis.Node;
+      const inside = refs.some((r) => r.current && r.current.contains(target));
+      if (refs.some((r) => r.current) && !inside) {
         callback();
       }
     };

From aaae715ce732f8464a2705cb1f14454f11d06b8d Mon Sep 17 00:00:00 2001
From: william garrity <wgarrity@mieweb.com>
Date: Thu, 23 Jul 2026 18:19:15 -0400
Subject: [PATCH 02/10] fix(useAnchoredPosition): account for matchMinWidth in
 horizontal clamping

The clamp used offsetWidth measured before minWidth applied, so panels
widened by matchMinWidth could overflow the right viewport edge on
first open.
---
 src/hooks/useAnchoredPosition.ts | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/src/hooks/useAnchoredPosition.ts b/src/hooks/useAnchoredPosition.ts
index 8ff40c940..41a123e78 100644
--- a/src/hooks/useAnchoredPosition.ts
+++ b/src/hooks/useAnchoredPosition.ts
@@ -116,7 +116,11 @@ export function useAnchoredPosition<
       floating.scrollHeight,
       maxHeight ?? Infinity
     );
-    const floatingWidth = matchWidth ? rect.width : floating.offsetWidth;
+    // With matchMinWidth the rendered width is at least the anchor's width,
+    // even if offsetWidth was measured before minWidth applied.
+    const floatingWidth = matchWidth
+      ? rect.width
+      : Math.max(floating.offsetWidth, matchMinWidth ? rect.width : 0);
 
     // --- Vertical: preferred side, flip when out of space -------------------
     const spaceBelow = viewportHeight - rect.bottom - offset - viewportPadding;

From 36a1dddde5fdd9ec34a35f4b269e915c86012a66 Mon Sep 17 00:00:00 2001
From: william garrity <wgarrity@mieweb.com>
Date: Thu, 23 Jul 2026 18:30:25 -0400
Subject: [PATCH 03/10] fix: let clamped floating panels clip and inner lists
 shrink/scroll

When useAnchoredPosition clamps a panel's maxHeight below its content,
the panel needs overflow-hidden and inner lists need min-h-0 so they
shrink and scroll instead of painting past the clamp. Also mark fixed
headers shrink-0 so only the scroll regions give up height.

Addresses Copilot review on PR #332.
---
 src/components/CodeLookup/CodeLookup.tsx                   | 2 +-
 src/components/CountBadge/CountBadge.tsx                   | 4 ++--
 src/components/CountryCodeDropdown/CountryCodeDropdown.tsx | 4 ++--
 src/components/ProviderSelector/ProviderSelector.tsx       | 4 ++--
 4 files changed, 7 insertions(+), 7 deletions(-)

diff --git a/src/components/CodeLookup/CodeLookup.tsx b/src/components/CodeLookup/CodeLookup.tsx
index ba8e83098..8deb87fbd 100644
--- a/src/components/CodeLookup/CodeLookup.tsx
+++ b/src/components/CodeLookup/CodeLookup.tsx
@@ -512,7 +512,7 @@ export const CodeLookup = React.forwardRef<HTMLDivElement, CodeLookupProps>(
               onMouseDown={(e) => e.preventDefault()}
             >
               {drill && (
-                <div className="border-border bg-muted/50 flex items-center gap-1.5 border-b px-2 py-1.5">
+                <div className="border-border bg-muted/50 flex shrink-0 items-center gap-1.5 border-b px-2 py-1.5">
                   <button
                     type="button"
                     onClick={closeDrill}
diff --git a/src/components/CountBadge/CountBadge.tsx b/src/components/CountBadge/CountBadge.tsx
index f70b12e30..f7d3d989e 100644
--- a/src/components/CountBadge/CountBadge.tsx
+++ b/src/components/CountBadge/CountBadge.tsx
@@ -361,7 +361,7 @@ function HoverMenu({
       className={cn(
         'w-[320px] rounded-lg border border-neutral-200 bg-white shadow-xl',
         'dark:border-neutral-700 dark:bg-neutral-800',
-        'flex flex-col',
+        'flex flex-col overflow-hidden',
         'animate-in fade-in slide-in-from-top-1 duration-150'
       )}
       // Prevent click-outside handler from immediately closing when interacting
@@ -370,7 +370,7 @@ function HoverMenu({
       {/* Header */}
       <div
         className={cn(
-          'rounded-t-lg border-b border-neutral-200 px-3 py-2 dark:border-neutral-700',
+          'shrink-0 rounded-t-lg border-b border-neutral-200 px-3 py-2 dark:border-neutral-700',
           headerBg[variant ?? 'default']
         )}
       >
diff --git a/src/components/CountryCodeDropdown/CountryCodeDropdown.tsx b/src/components/CountryCodeDropdown/CountryCodeDropdown.tsx
index fcfb97da3..aaee048ae 100644
--- a/src/components/CountryCodeDropdown/CountryCodeDropdown.tsx
+++ b/src/components/CountryCodeDropdown/CountryCodeDropdown.tsx
@@ -371,7 +371,7 @@ function CountryCodeDropdown({
             tabIndex={-1}
             onKeyDown={handleKeyDown}
             className={cn(
-              'flex w-72 flex-col',
+              'flex w-72 flex-col overflow-hidden',
               'rounded-xl border border-neutral-200 bg-white shadow-lg',
               'dark:border-neutral-700 dark:bg-neutral-800',
               'animate-in fade-in zoom-in-95 duration-100'
@@ -380,7 +380,7 @@ function CountryCodeDropdown({
             {/* Search input */}
             <div
               data-slot="country-dropdown-search"
-              className="border-b border-neutral-200 p-2 dark:border-neutral-700"
+              className="shrink-0 border-b border-neutral-200 p-2 dark:border-neutral-700"
             >
               <input
                 ref={searchInputRef}
diff --git a/src/components/ProviderSelector/ProviderSelector.tsx b/src/components/ProviderSelector/ProviderSelector.tsx
index f851a774c..142f8150c 100644
--- a/src/components/ProviderSelector/ProviderSelector.tsx
+++ b/src/components/ProviderSelector/ProviderSelector.tsx
@@ -269,7 +269,7 @@ export function ProviderSelector({
           >
             {/* Search */}
             {searchable && (
-              <div className="border-border border-b p-2">
+              <div className="border-border shrink-0 border-b p-2">
                 <div className="relative">
                   <svg
                     aria-hidden="true"
@@ -300,7 +300,7 @@ export function ProviderSelector({
             )}
 
             {/* Options list */}
-            <div className="max-h-64 overflow-y-auto">
+            <div className="max-h-64 min-h-0 overflow-y-auto">
               {filteredProviders.length === 0 ? (
                 <div className="text-muted-foreground px-4 py-6 text-center">
                   No providers found

From b0b23d7550a350dea8c3bf7ccf52c6225e320c66 Mon Sep 17 00:00:00 2001
From: william garrity <wgarrity@mieweb.com>
Date: Thu, 23 Jul 2026 18:38:57 -0400
Subject: [PATCH 04/10] fix(useClickOutside): accept readonly ref arrays

Widen the multi-ref parameter to ReadonlyArray so callers can pass
readonly tuples (e.g. built with 'as const') without casting.
---
 src/hooks/useClickOutside.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/hooks/useClickOutside.ts b/src/hooks/useClickOutside.ts
index 5a3dd0171..641653737 100644
--- a/src/hooks/useClickOutside.ts
+++ b/src/hooks/useClickOutside.ts
@@ -22,7 +22,7 @@ import { useEffect, type RefObject } from 'react';
  * ```
  */
 export function useClickOutside<T extends HTMLElement>(
-  ref: RefObject<T | null> | Array<RefObject<HTMLElement | null>>,
+  ref: RefObject<T | null> | ReadonlyArray<RefObject<HTMLElement | null>>,
   callback: () => void,
   enabled: boolean = true
 ): void {

From d4a3413fbb055cb9691e2235b79f8cc62e62d96f Mon Sep 17 00:00:00 2001
From: william garrity <wgarrity@mieweb.com>
Date: Thu, 23 Jul 2026 19:00:03 -0400
Subject: [PATCH 05/10] perf(useAnchoredPosition): coalesce scroll/resize
 updates with rAF

Batch bursty scroll/resize/ResizeObserver events into one layout read
and state update per frame, cancelling any pending frame on cleanup.

Also tighten useClickOutside: guard event.target instanceof Node instead
of casting, and avoid traversing the ref list twice.
---
 src/hooks/useAnchoredPosition.ts | 22 +++++++++++++++++-----
 src/hooks/useClickOutside.ts     |  9 ++++++---
 2 files changed, 23 insertions(+), 8 deletions(-)

diff --git a/src/hooks/useAnchoredPosition.ts b/src/hooks/useAnchoredPosition.ts
index 41a123e78..923605301 100644
--- a/src/hooks/useAnchoredPosition.ts
+++ b/src/hooks/useAnchoredPosition.ts
@@ -195,19 +195,31 @@ export function useAnchoredPosition<
   React.useEffect(() => {
     if (!open) return;
 
-    window.addEventListener('scroll', update, true);
-    window.addEventListener('resize', update);
+    // Coalesce bursts (scroll/resize fire per event) into one layout
+    // read + state update per frame.
+    let frame = 0;
+    const scheduleUpdate = () => {
+      if (frame) return;
+      frame = window.requestAnimationFrame(() => {
+        frame = 0;
+        update();
+      });
+    };
+
+    window.addEventListener('scroll', scheduleUpdate, true);
+    window.addEventListener('resize', scheduleUpdate);
 
     let resizeObserver: globalThis.ResizeObserver | undefined;
     if (typeof globalThis.ResizeObserver !== 'undefined') {
-      resizeObserver = new globalThis.ResizeObserver(update);
+      resizeObserver = new globalThis.ResizeObserver(scheduleUpdate);
       if (anchorRef.current) resizeObserver.observe(anchorRef.current);
       if (floatingRef.current) resizeObserver.observe(floatingRef.current);
     }
 
     return () => {
-      window.removeEventListener('scroll', update, true);
-      window.removeEventListener('resize', update);
+      if (frame) window.cancelAnimationFrame(frame);
+      window.removeEventListener('scroll', scheduleUpdate, true);
+      window.removeEventListener('resize', scheduleUpdate);
       resizeObserver?.disconnect();
     };
   }, [open, update]);
diff --git a/src/hooks/useClickOutside.ts b/src/hooks/useClickOutside.ts
index 641653737..1bb0485a5 100644
--- a/src/hooks/useClickOutside.ts
+++ b/src/hooks/useClickOutside.ts
@@ -31,9 +31,12 @@ export function useClickOutside<T extends HTMLElement>(
 
     const handleClick = (event: Event) => {
       const refs = Array.isArray(ref) ? ref : [ref];
-      const target = event.target as globalThis.Node;
-      const inside = refs.some((r) => r.current && r.current.contains(target));
-      if (refs.some((r) => r.current) && !inside) {
+      const target = event.target;
+      if (!(target instanceof globalThis.Node)) return;
+      const attachedRefs = refs.filter((r) => r.current !== null);
+      if (attachedRefs.length === 0) return;
+      const inside = attachedRefs.some((r) => r.current?.contains(target));
+      if (!inside) {
         callback();
       }
     };

From 3080a85caa8f74079bce92be7e65255687447490 Mon Sep 17 00:00:00 2001
From: william garrity <wgarrity@mieweb.com>
Date: Thu, 23 Jul 2026 19:10:57 -0400
Subject: [PATCH 06/10] test(useAnchoredPosition): add unit tests; clarify
 maxHeight doc

12 renderHook tests covering hidden style, bottom/top placement,
vertical flipping, horizontal viewport clamping, matchWidth /
matchMinWidth, maxHeight capping, viewport height clamping,
rAF-coalesced scroll updates, and close reset.

Also clarify that maxHeight is an additional cap on top of the
always-applied viewport space clamp.
---
 src/hooks/useAnchoredPosition.test.ts | 216 ++++++++++++++++++++++++++
 src/hooks/useAnchoredPosition.ts      |   6 +-
 2 files changed, 221 insertions(+), 1 deletion(-)
 create mode 100644 src/hooks/useAnchoredPosition.test.ts

diff --git a/src/hooks/useAnchoredPosition.test.ts b/src/hooks/useAnchoredPosition.test.ts
new file mode 100644
index 000000000..8c774bf77
--- /dev/null
+++ b/src/hooks/useAnchoredPosition.test.ts
@@ -0,0 +1,216 @@
+import { act, renderHook } from '@testing-library/react';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import {
+  useAnchoredPosition,
+  type UseAnchoredPositionOptions,
+} from './useAnchoredPosition';
+
+// jsdom viewport defaults used throughout: 1024 x 768.
+const VIEWPORT_WIDTH = 1024;
+const VIEWPORT_HEIGHT = 768;
+
+interface RectInit {
+  top: number;
+  left: number;
+  width: number;
+  height: number;
+}
+
+function makeRect({ top, left, width, height }: RectInit): globalThis.DOMRect {
+  return {
+    top,
+    left,
+    width,
+    height,
+    right: left + width,
+    bottom: top + height,
+    x: left,
+    y: top,
+    toJSON: () => ({}),
+  } as globalThis.DOMRect;
+}
+
+interface SetupInput {
+  options?: Omit<UseAnchoredPositionOptions, 'open'>;
+  anchorRect: RectInit;
+  /** Natural content size of the floating element */
+  floatingSize?: { width: number; height: number };
+}
+
+/**
+ * Renders the hook closed, attaches mock anchor/floating elements with
+ * stubbed layout measurements, then opens it so `update()` runs.
+ */
+function setup({
+  options = {},
+  anchorRect,
+  floatingSize = { width: 250, height: 200 },
+}: SetupInput) {
+  const anchor = document.createElement('button');
+  anchor.getBoundingClientRect = () => makeRect(anchorRect);
+
+  const floating = document.createElement('div');
+  Object.defineProperty(floating, 'scrollHeight', {
+    configurable: true,
+    get: () => floatingSize.height,
+  });
+  Object.defineProperty(floating, 'offsetWidth', {
+    configurable: true,
+    get: () => floatingSize.width,
+  });
+
+  const { result, rerender } = renderHook(
+    (props: UseAnchoredPositionOptions) => useAnchoredPosition(props),
+    { initialProps: { open: false, ...options } }
+  );
+  result.current.anchorRef.current = anchor;
+  result.current.floatingRef.current = floating;
+  act(() => rerender({ open: true, ...options }));
+
+  return { result, rerender, anchor, floating, options };
+}
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+});
+
+describe('useAnchoredPosition', () => {
+  it('hides the floating element while closed, without transitions', () => {
+    const { result } = renderHook(() => useAnchoredPosition({ open: false }));
+    expect(result.current.style).toMatchObject({
+      position: 'fixed',
+      visibility: 'hidden',
+      transition: 'none',
+    });
+  });
+
+  it('positions below the anchor for bottom-start', () => {
+    const { result } = setup({
+      anchorRect: { top: 100, left: 200, width: 150, height: 40 },
+    });
+    expect(result.current.actualSide).toBe('bottom');
+    expect(result.current.style).toMatchObject({
+      position: 'fixed',
+      top: 140 + 4, // anchor bottom + default offset
+      left: 200,
+      transition: 'none',
+    });
+    // Available space below: 768 - 140 - 4 (offset) - 8 (padding)
+    expect(result.current.style.maxHeight).toBe(616);
+  });
+
+  it('flips above the anchor when there is not enough space below', () => {
+    const { result } = setup({
+      anchorRect: { top: 600, left: 200, width: 150, height: 40 },
+      floatingSize: { width: 250, height: 200 },
+    });
+    expect(result.current.actualSide).toBe('top');
+    expect(result.current.style.top).toBeUndefined();
+    // Anchored to the anchor's top edge via `bottom`
+    expect(result.current.style.bottom).toBe(VIEWPORT_HEIGHT - 600 + 4);
+  });
+
+  it('keeps the preferred top placement when space allows', () => {
+    const { result } = setup({
+      options: { placement: 'top-start' },
+      anchorRect: { top: 600, left: 200, width: 150, height: 40 },
+    });
+    expect(result.current.actualSide).toBe('top');
+  });
+
+  it('clamps the left edge to the viewport padding', () => {
+    const { result } = setup({
+      options: { placement: 'bottom-end' },
+      anchorRect: { top: 100, left: 10, width: 50, height: 40 },
+      floatingSize: { width: 250, height: 200 },
+    });
+    // right-aligned would be 60 - 250 = -190 → clamped to padding
+    expect(result.current.style.left).toBe(8);
+  });
+
+  it('clamps the right edge to the viewport padding', () => {
+    const { result } = setup({
+      anchorRect: { top: 100, left: 900, width: 100, height: 40 },
+      floatingSize: { width: 250, height: 200 },
+    });
+    // left-aligned would be 900 → clamped to 1024 - 250 - 8
+    expect(result.current.style.left).toBe(VIEWPORT_WIDTH - 250 - 8);
+  });
+
+  it('matches the anchor width with matchWidth', () => {
+    const { result } = setup({
+      options: { matchWidth: true },
+      anchorRect: { top: 100, left: 200, width: 150, height: 40 },
+    });
+    expect(result.current.style.width).toBe(150);
+  });
+
+  it('uses the anchor width as a minimum with matchMinWidth', () => {
+    const { result } = setup({
+      options: { matchMinWidth: true },
+      anchorRect: { top: 100, left: 800, width: 300, height: 40 },
+      floatingSize: { width: 100, height: 200 },
+    });
+    expect(result.current.style.minWidth).toBe(300);
+    // Horizontal clamping accounts for the min width, not offsetWidth
+    expect(result.current.style.left).toBe(VIEWPORT_WIDTH - 300 - 8);
+  });
+
+  it('caps the height with maxHeight when space allows more', () => {
+    const { result } = setup({
+      options: { maxHeight: 300 },
+      anchorRect: { top: 100, left: 200, width: 150, height: 40 },
+      floatingSize: { width: 250, height: 500 },
+    });
+    expect(result.current.style.maxHeight).toBe(300);
+  });
+
+  it('clamps the height to the viewport even without maxHeight', () => {
+    const { result } = setup({
+      anchorRect: { top: 700, left: 200, width: 150, height: 40 },
+      floatingSize: { width: 250, height: 10 },
+    });
+    // Tiny content prefers bottom; only 768 - 740 - 4 - 8 px available
+    expect(result.current.style.maxHeight).toBe(16);
+  });
+
+  it('coalesces scroll events into one update per animation frame', () => {
+    const rafQueue: globalThis.FrameRequestCallback[] = [];
+    vi.stubGlobal(
+      'requestAnimationFrame',
+      (cb: globalThis.FrameRequestCallback) => {
+        rafQueue.push(cb);
+        return rafQueue.length;
+      }
+    );
+    vi.stubGlobal('cancelAnimationFrame', vi.fn());
+
+    const { result, anchor } = setup({
+      anchorRect: { top: 100, left: 200, width: 150, height: 40 },
+    });
+    expect(result.current.style.top).toBe(144);
+
+    // Anchor moves, then several scroll events land in the same frame.
+    anchor.getBoundingClientRect = () =>
+      makeRect({ top: 50, left: 200, width: 150, height: 40 });
+    act(() => {
+      window.dispatchEvent(new Event('scroll'));
+      window.dispatchEvent(new Event('scroll'));
+      window.dispatchEvent(new Event('scroll'));
+    });
+    expect(rafQueue).toHaveLength(1);
+    expect(result.current.style.top).toBe(144); // not yet recomputed
+
+    act(() => rafQueue.forEach((cb) => cb(0)));
+    expect(result.current.style.top).toBe(90 + 4);
+  });
+
+  it('returns to the hidden style when closed again', () => {
+    const { result, rerender } = setup({
+      anchorRect: { top: 100, left: 200, width: 150, height: 40 },
+    });
+    act(() => rerender({ open: false }));
+    expect(result.current.style.visibility).toBe('hidden');
+  });
+});
diff --git a/src/hooks/useAnchoredPosition.ts b/src/hooks/useAnchoredPosition.ts
index 923605301..9fb72d032 100644
--- a/src/hooks/useAnchoredPosition.ts
+++ b/src/hooks/useAnchoredPosition.ts
@@ -23,7 +23,11 @@ export interface UseAnchoredPositionOptions {
   matchMinWidth?: boolean;
   /** Minimum distance from the viewport edges, in px */
   viewportPadding?: number;
-  /** Cap the floating element's height, in px */
+  /**
+   * Additional cap on the floating element's height, in px. The height is
+   * always clamped to the available viewport space; this only lowers that
+   * limit further (omitting it does not remove the viewport constraint).
+   */
   maxHeight?: number;
 }
 

From 5313f6e7ec9f132bcdea388d855d1f1ce34b578b Mon Sep 17 00:00:00 2001
From: william garrity <wgarrity@mieweb.com>
Date: Thu, 23 Jul 2026 19:30:47 -0400
Subject: [PATCH 07/10] refactor: replace hand-rolled click-outside effects
 with useClickOutside

Seven duplicated mousedown handlers cast event.target to Node without a
guard. The shared useClickOutside hook already guards with instanceof
Node and accepts ref arrays for portaled panels, so use it instead:
LanguageSelector, ProviderSelector, ProviderSearchFilters,
BookingDialog ServiceSelect, CountBadge (menu, share, container), and
Select.
---
 .../BookingDialog/BookingDialog.tsx           | 19 ++-----
 src/components/CountBadge/CountBadge.tsx      | 57 +++++--------------
 .../LanguageSelector/LanguageSelector.tsx     | 20 ++-----
 .../ProviderSearchFilters.tsx                 | 19 ++-----
 .../ProviderSelector/ProviderSelector.tsx     | 20 ++-----
 src/components/Select/Select.tsx              | 19 +------
 6 files changed, 40 insertions(+), 114 deletions(-)

diff --git a/src/components/BookingDialog/BookingDialog.tsx b/src/components/BookingDialog/BookingDialog.tsx
index 1be4e6154..18eca8c58 100644
--- a/src/components/BookingDialog/BookingDialog.tsx
+++ b/src/components/BookingDialog/BookingDialog.tsx
@@ -3,6 +3,7 @@ import { createPortal } from 'react-dom';
 import { cva, type VariantProps } from 'class-variance-authority';
 import { cn } from '../../utils/cn';
 import { useAnchoredPosition } from '../../hooks/useAnchoredPosition';
+import { useClickOutside } from '../../hooks/useClickOutside';
 import { isStorybookDocsMode } from '../../utils/environment';
 
 // =============================================================================
@@ -160,19 +161,11 @@ export function ServiceSelect({
     HTMLDivElement
   >({ open: isOpen, matchWidth: true, maxHeight: 240 });
 
-  React.useEffect(() => {
-    function handleClickOutside(event: MouseEvent) {
-      if (
-        dropdownRef.current &&
-        !dropdownRef.current.contains(event.target as Node) &&
-        !floatingRef.current?.contains(event.target as Node)
-      ) {
-        setIsOpen(false);
-      }
-    }
-    document.addEventListener('mousedown', handleClickOutside);
-    return () => document.removeEventListener('mousedown', handleClickOutside);
-  }, [floatingRef]);
+  const outsideRefs = React.useMemo(
+    () => [dropdownRef, floatingRef],
+    [floatingRef]
+  );
+  useClickOutside(outsideRefs, () => setIsOpen(false), isOpen);
 
   const toggleService = (serviceSlug: string) => {
     if (selectedServices.includes(serviceSlug)) {
diff --git a/src/components/CountBadge/CountBadge.tsx b/src/components/CountBadge/CountBadge.tsx
index f7d3d989e..c524d9f7b 100644
--- a/src/components/CountBadge/CountBadge.tsx
+++ b/src/components/CountBadge/CountBadge.tsx
@@ -3,6 +3,7 @@ import * as ReactDOM from 'react-dom';
 import { cva, type VariantProps } from 'class-variance-authority';
 import { cn } from '../../utils/cn';
 import { useAnchoredPosition } from '../../hooks/useAnchoredPosition';
+import { useClickOutside } from '../../hooks/useClickOutside';
 import {
   MoreHorizontalIcon,
   ShareIcon,
@@ -211,21 +212,8 @@ function RowActionMenu({
   const buttonRef = React.useRef<HTMLButtonElement>(null);
 
   // Close on outside click
-  React.useEffect(() => {
-    if (!open) return;
-    function handleClick(e: MouseEvent) {
-      if (
-        menuRef.current &&
-        !menuRef.current.contains(e.target as Node) &&
-        buttonRef.current &&
-        !buttonRef.current.contains(e.target as Node)
-      ) {
-        setOpen(false);
-      }
-    }
-    document.addEventListener('mousedown', handleClick);
-    return () => document.removeEventListener('mousedown', handleClick);
-  }, [open]);
+  const outsideRefs = React.useMemo(() => [menuRef, buttonRef], []);
+  useClickOutside(outsideRefs, () => setOpen(false), open);
 
   // Close on Escape
   React.useEffect(() => {
@@ -489,20 +477,11 @@ function ViewModalActions({
   });
 
   // Close share dropdown on outside click
-  React.useEffect(() => {
-    if (!shareOpen) return;
-    const handleClick = (e: MouseEvent) => {
-      if (
-        shareRef.current &&
-        !shareRef.current.contains(e.target as Node) &&
-        !shareFloatingRef.current?.contains(e.target as Node)
-      ) {
-        setShareOpen(false);
-      }
-    };
-    document.addEventListener('mousedown', handleClick);
-    return () => document.removeEventListener('mousedown', handleClick);
-  }, [shareOpen, shareFloatingRef]);
+  const shareOutsideRefs = React.useMemo(
+    () => [shareRef, shareFloatingRef],
+    [shareFloatingRef]
+  );
+  useClickOutside(shareOutsideRefs, () => setShareOpen(false), shareOpen);
 
   return (
     <div className="mb-4 flex items-center gap-1 border-b border-neutral-200 pb-3 dark:border-neutral-700">
@@ -698,21 +677,11 @@ const CountBadge = React.forwardRef<HTMLButtonElement, CountBadgeProps>(
     });
 
     // Close on click outside
-    React.useEffect(() => {
-      if (!open) return;
-      const handleClickOutside = (e: MouseEvent) => {
-        if (
-          containerRef.current &&
-          !containerRef.current.contains(e.target as Node) &&
-          !floatingRef.current?.contains(e.target as Node)
-        ) {
-          setOpen(false);
-        }
-      };
-      document.addEventListener('mousedown', handleClickOutside);
-      return () =>
-        document.removeEventListener('mousedown', handleClickOutside);
-    }, [open, floatingRef]);
+    const outsideRefs = React.useMemo(
+      () => [containerRef, floatingRef],
+      [floatingRef]
+    );
+    useClickOutside(outsideRefs, () => setOpen(false), open);
 
     // Close on Escape
     React.useEffect(() => {
diff --git a/src/components/LanguageSelector/LanguageSelector.tsx b/src/components/LanguageSelector/LanguageSelector.tsx
index e02860105..cb60987d1 100644
--- a/src/components/LanguageSelector/LanguageSelector.tsx
+++ b/src/components/LanguageSelector/LanguageSelector.tsx
@@ -3,6 +3,7 @@ import { createPortal } from 'react-dom';
 import { cva, type VariantProps } from 'class-variance-authority';
 import { cn } from '../../utils/cn';
 import { useAnchoredPosition } from '../../hooks/useAnchoredPosition';
+import { useClickOutside } from '../../hooks/useClickOutside';
 
 // =============================================================================
 // Types
@@ -150,20 +151,11 @@ export function LanguageSelector({
   const selectedLanguage = languages.find((l) => l.code === value);
 
   // Close on click outside
-  React.useEffect(() => {
-    const handleClickOutside = (e: MouseEvent) => {
-      if (
-        containerRef.current &&
-        !containerRef.current.contains(e.target as Node) &&
-        !floatingRef.current?.contains(e.target as Node)
-      ) {
-        setIsOpen(false);
-      }
-    };
-
-    document.addEventListener('mousedown', handleClickOutside);
-    return () => document.removeEventListener('mousedown', handleClickOutside);
-  }, [floatingRef]);
+  const outsideRefs = React.useMemo(
+    () => [containerRef, floatingRef],
+    [floatingRef]
+  );
+  useClickOutside(outsideRefs, () => setIsOpen(false), isOpen);
 
   // Close on escape
   React.useEffect(() => {
diff --git a/src/components/ProviderSearchFilters/ProviderSearchFilters.tsx b/src/components/ProviderSearchFilters/ProviderSearchFilters.tsx
index ade2cef62..64476c9e9 100644
--- a/src/components/ProviderSearchFilters/ProviderSearchFilters.tsx
+++ b/src/components/ProviderSearchFilters/ProviderSearchFilters.tsx
@@ -5,6 +5,7 @@ import { createPortal } from 'react-dom';
 import { cva, type VariantProps } from 'class-variance-authority';
 import { cn } from '../../utils/cn';
 import { useAnchoredPosition } from '../../hooks/useAnchoredPosition';
+import { useClickOutside } from '../../hooks/useClickOutside';
 
 // ============================================================================
 // Types
@@ -333,19 +334,11 @@ export function ServiceMultiSelect({
   >({ open: isOpen, matchWidth: true, maxHeight: 240 });
 
   // Close dropdown when clicking outside
-  React.useEffect(() => {
-    function handleClickOutside(event: MouseEvent) {
-      if (
-        containerRef.current &&
-        !containerRef.current.contains(event.target as Node) &&
-        !floatingRef.current?.contains(event.target as Node)
-      ) {
-        setIsOpen(false);
-      }
-    }
-    document.addEventListener('mousedown', handleClickOutside);
-    return () => document.removeEventListener('mousedown', handleClickOutside);
-  }, [floatingRef]);
+  const outsideRefs = React.useMemo(
+    () => [containerRef, floatingRef],
+    [floatingRef]
+  );
+  useClickOutside(outsideRefs, () => setIsOpen(false), isOpen);
 
   // Filter services based on search
   const filteredServices = React.useMemo(() => {
diff --git a/src/components/ProviderSelector/ProviderSelector.tsx b/src/components/ProviderSelector/ProviderSelector.tsx
index 142f8150c..698f13411 100644
--- a/src/components/ProviderSelector/ProviderSelector.tsx
+++ b/src/components/ProviderSelector/ProviderSelector.tsx
@@ -4,6 +4,7 @@ import * as React from 'react';
 import { createPortal } from 'react-dom';
 import { cn } from '../../utils/cn';
 import { useAnchoredPosition } from '../../hooks/useAnchoredPosition';
+import { useClickOutside } from '../../hooks/useClickOutside';
 
 export interface ProviderOption {
   /** Unique identifier */
@@ -75,20 +76,11 @@ export function ProviderSelector({
   >({ open: isOpen, matchWidth: true });
 
   // Close on click outside
-  React.useEffect(() => {
-    function handleClickOutside(event: MouseEvent) {
-      if (
-        containerRef.current &&
-        !containerRef.current.contains(event.target as Node) &&
-        !floatingRef.current?.contains(event.target as Node)
-      ) {
-        setIsOpen(false);
-      }
-    }
-
-    document.addEventListener('mousedown', handleClickOutside);
-    return () => document.removeEventListener('mousedown', handleClickOutside);
-  }, [floatingRef]);
+  const outsideRefs = React.useMemo(
+    () => [containerRef, floatingRef],
+    [floatingRef]
+  );
+  useClickOutside(outsideRefs, () => setIsOpen(false), isOpen);
 
   // Close on escape
   React.useEffect(() => {
diff --git a/src/components/Select/Select.tsx b/src/components/Select/Select.tsx
index bf847f731..93fbc215b 100644
--- a/src/components/Select/Select.tsx
+++ b/src/components/Select/Select.tsx
@@ -3,6 +3,7 @@ import { createPortal } from 'react-dom';
 import { cva, type VariantProps } from 'class-variance-authority';
 import { cn } from '../../utils/cn';
 import { useEscapeKey } from '../../hooks/useEscapeKey';
+import { useClickOutside } from '../../hooks/useClickOutside';
 import { useAnchoredPosition } from '../../hooks/useAnchoredPosition';
 
 // ============================================================================
@@ -218,22 +219,8 @@ function Select({
   const selectedOption = flatOptions.find((opt) => opt.value === value);
 
   // Close dropdown on click outside (handles both container and portaled dropdown)
-  React.useEffect(() => {
-    if (!isOpen) return;
-    const handleClickOutside = (e: MouseEvent) => {
-      const target = e.target as Node;
-      if (
-        containerRef.current &&
-        !containerRef.current.contains(target) &&
-        dropdownRef.current &&
-        !dropdownRef.current.contains(target)
-      ) {
-        setIsOpen(false);
-      }
-    };
-    document.addEventListener('mousedown', handleClickOutside);
-    return () => document.removeEventListener('mousedown', handleClickOutside);
-  }, [isOpen]);
+  const outsideRefs = React.useMemo(() => [containerRef, dropdownRef], []);
+  useClickOutside(outsideRefs, () => setIsOpen(false), isOpen);
 
   useEscapeKey(() => {
     if (isOpen) {

From de20eed37b2b91d0ecb4754ef3948977a588aa85 Mon Sep 17 00:00:00 2001
From: william garrity <wgarrity@mieweb.com>
Date: Thu, 23 Jul 2026 19:40:43 -0400
Subject: [PATCH 08/10] fix(useClickOutside): stop re-registering listeners on
 callback change

Use the latest-ref pattern so the effect only depends on ref/enabled.
Inline close callbacks (the norm at call sites) no longer cause the
document mousedown/touchstart listeners to detach/attach on every
re-render while a panel is open.
---
 src/hooks/useClickOutside.ts | 11 ++++++++---
 1 file changed, 8 insertions(+), 3 deletions(-)

diff --git a/src/hooks/useClickOutside.ts b/src/hooks/useClickOutside.ts
index 1bb0485a5..d0f8c12bf 100644
--- a/src/hooks/useClickOutside.ts
+++ b/src/hooks/useClickOutside.ts
@@ -1,4 +1,4 @@
-import { useEffect, type RefObject } from 'react';
+import { useEffect, useRef, type RefObject } from 'react';
 
 /**
  * Hook that detects clicks outside of a specified element.
@@ -26,6 +26,11 @@ export function useClickOutside<T extends HTMLElement>(
   callback: () => void,
   enabled: boolean = true
 ): void {
+  // Latest-ref pattern: keep the document listeners attached for the whole
+  // enabled cycle even when callers pass a new inline callback each render.
+  const callbackRef = useRef(callback);
+  callbackRef.current = callback;
+
   useEffect(() => {
     if (!enabled) return;
 
@@ -37,7 +42,7 @@ export function useClickOutside<T extends HTMLElement>(
       if (attachedRefs.length === 0) return;
       const inside = attachedRefs.some((r) => r.current?.contains(target));
       if (!inside) {
-        callback();
+        callbackRef.current();
       }
     };
 
@@ -48,5 +53,5 @@ export function useClickOutside<T extends HTMLElement>(
       document.removeEventListener('mousedown', handleClick);
       document.removeEventListener('touchstart', handleClick);
     };
-  }, [ref, callback, enabled]);
+  }, [ref, enabled]);
 }

From 0f9ab1b1ca55cac3bf46ae0d126a9cf4b6b627bb Mon Sep 17 00:00:00 2001
From: william garrity <wgarrity@mieweb.com>
Date: Thu, 23 Jul 2026 19:48:59 -0400
Subject: [PATCH 09/10] fix: gate useClickOutside listeners on open state

PatientHeader, DateRangePicker, and CountryCodeDropdown called
useClickOutside without the enabled argument, keeping document
mousedown/touchstart listeners attached while closed. Pass the open
state (and drop DateRangePicker's now-redundant isCalendarOpen guard).
---
 .../CountryCodeDropdown/CountryCodeDropdown.tsx        |  2 +-
 src/components/DateRangePicker/DateRangePicker.tsx     | 10 ++++++----
 src/components/PatientHeader/PatientHeader.tsx         |  3 ++-
 3 files changed, 9 insertions(+), 6 deletions(-)

diff --git a/src/components/CountryCodeDropdown/CountryCodeDropdown.tsx b/src/components/CountryCodeDropdown/CountryCodeDropdown.tsx
index aaee048ae..d224f9227 100644
--- a/src/components/CountryCodeDropdown/CountryCodeDropdown.tsx
+++ b/src/components/CountryCodeDropdown/CountryCodeDropdown.tsx
@@ -250,7 +250,7 @@ function CountryCodeDropdown({
     () => [containerRef, floatingRef],
     [containerRef, floatingRef]
   );
-  useClickOutside(outsideRefs, close);
+  useClickOutside(outsideRefs, close, isOpen);
   useEscapeKey(close, isOpen);
 
   // Focus search input when opening
diff --git a/src/components/DateRangePicker/DateRangePicker.tsx b/src/components/DateRangePicker/DateRangePicker.tsx
index c64ac00aa..9f8871d54 100644
--- a/src/components/DateRangePicker/DateRangePicker.tsx
+++ b/src/components/DateRangePicker/DateRangePicker.tsx
@@ -389,12 +389,14 @@ export function DateRangePicker({
     () => [wrapperRef, calendarRef],
     [calendarRef]
   );
-  useClickOutside(outsideRefs, () => {
-    if (isCalendarOpen) {
+  useClickOutside(
+    outsideRefs,
+    () => {
       setIsCalendarOpen(false);
       setSelectingEnd(false);
-    }
-  });
+    },
+    isCalendarOpen
+  );
 
   // Portal + fixed positioning for the desktop popup so it escapes
   // overflow-hidden ancestors.
diff --git a/src/components/PatientHeader/PatientHeader.tsx b/src/components/PatientHeader/PatientHeader.tsx
index 383f31e2f..d97bdc5bd 100644
--- a/src/components/PatientHeader/PatientHeader.tsx
+++ b/src/components/PatientHeader/PatientHeader.tsx
@@ -328,7 +328,8 @@ function PatientOverflowMenu({
   );
   useClickOutside(
     outsideRefs,
-    React.useCallback(() => setOpen(false), [])
+    React.useCallback(() => setOpen(false), []),
+    open
   );
   useEscapeKey(
     React.useCallback(() => setOpen(false), []),

From d9e71a5419d3030944767ae73dcce2b467c205ee Mon Sep 17 00:00:00 2001
From: william garrity <wgarrity@mieweb.com>
Date: Thu, 23 Jul 2026 19:56:20 -0400
Subject: [PATCH 10/10] fix: keep Dropdown search visible when clamped; passive
 touchstart
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Apply the clamped-panel pattern to Dropdown's portaled menu (flex-col +
overflow-hidden panel, shrink-0 search header, min-h-0 scrolling menu)
so the search input stays visible while the list scrolls under the
computed maxHeight.

Mark useClickOutside's document touchstart listener passive — the
handler never calls preventDefault, and passive avoids scroll-blocking
warnings.
---
 src/components/Dropdown/Dropdown.tsx | 6 +++---
 src/hooks/useClickOutside.ts         | 2 +-
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/src/components/Dropdown/Dropdown.tsx b/src/components/Dropdown/Dropdown.tsx
index 6cafa4667..67c502693 100644
--- a/src/components/Dropdown/Dropdown.tsx
+++ b/src/components/Dropdown/Dropdown.tsx
@@ -488,7 +488,7 @@ function Dropdown({
               style={{ ...style, ...widthStyle }}
               data-slot="dropdown-menu"
               className={cn(
-                'min-w-[12rem] overflow-auto',
+                'flex min-w-[12rem] flex-col overflow-hidden',
                 'rounded-xl border border-neutral-200 bg-white shadow-lg',
                 'dark:border-neutral-700 dark:bg-neutral-800',
                 'animate-in fade-in zoom-in-95 duration-100',
@@ -497,7 +497,7 @@ function Dropdown({
             >
               {searchable && (
                 <div
-                  className="border-b border-neutral-200 p-2 dark:border-neutral-700"
+                  className="shrink-0 border-b border-neutral-200 p-2 dark:border-neutral-700"
                   data-slot="dropdown-search"
                 >
                   <input
@@ -518,7 +518,7 @@ function Dropdown({
                   />
                 </div>
               )}
-              <div id={menuId} role="menu">
+              <div id={menuId} role="menu" className="min-h-0 overflow-y-auto">
                 {multiSelect &&
                   showSelectAll &&
                   visibleSelectableValues.length > 0 && (
diff --git a/src/hooks/useClickOutside.ts b/src/hooks/useClickOutside.ts
index d0f8c12bf..4aecb9007 100644
--- a/src/hooks/useClickOutside.ts
+++ b/src/hooks/useClickOutside.ts
@@ -47,7 +47,7 @@ export function useClickOutside<T extends HTMLElement>(
     };
 
     document.addEventListener('mousedown', handleClick);
-    document.addEventListener('touchstart', handleClick);
+    document.addEventListener('touchstart', handleClick, { passive: true });
 
     return () => {
       document.removeEventListener('mousedown', handleClick);