@dloizides/ui-forms 1.11.1 → 1.13.1

package/CHANGELOG.md

@@ -1,6 +1,21 @@
 # Changelog
 
-## 1.11.0
+## 1.12.0
+
+**`FormField` gained `labelHidden` — hide the visible label, keep the accessible name.**
+
+A field whose placeholder already names it (a toolbar search box, an inline filter) does
+not want a stacked visible label: the label wastes a row and, worse, pushes the input a
+label-row lower than a bare button beside it, so the two misalign. Until now the only way
+to drop the visible label was to blank `label` — which ALSO blanked the input's
+`accessibilityLabel`, silently stripping the accessible name.
+
+`labelHidden` removes ONLY the visible `<label>` row: `label` stays required and the input
+keeps `accessibilityLabel={label}`, so a screen reader reads the same name and the field
+still resolves by role + name. Additive and backward-compatible — default `false`, every
+existing call renders unchanged.
+
+## 1.11.1
 
 **`ThemedTextInput` shipped no metrics, so every direct caller got a raw 19px input.**
 

package/dist/index.d.mts

@@ -380,11 +380,22 @@ declare const FormActions: ({ onSave, onCancel, saveLabel, cancelLabel, saveHint
  */
 interface FormFieldProps extends Omit<TextInputProps, 'style'> {
     label: string;
+    /**
+     * Hide the VISIBLE label row while keeping the accessible name.
+     *
+     * For a field whose placeholder already names it (a toolbar search box, an inline
+     * filter) the stacked visible label both wastes a row and misaligns the input
+     * against a bare button beside it. Setting this drops ONLY the visible `<label>`:
+     * the input still carries `accessibilityLabel={label}`, so a screen reader reads
+     * the same name and `label` stays REQUIRED — you never lose the accessible name by
+     * blanking it, which is the trap this option exists to remove. Default `false`.
+     */
+    labelHidden?: boolean;
     required?: boolean;
     error?: string;
     containerStyle?: ViewStyle;
 }
-declare const FormField: ({ label, required, error, containerStyle, ...textInputProps }: FormFieldProps) => React.ReactElement;
+declare const FormField: ({ label, labelHidden, required, error, containerStyle, ...textInputProps }: FormFieldProps) => React.ReactElement;
 
 /**
  * `ThemedTextInput` — the shared, readable + lively text-input primitive. A thin `<TextInput>`
@@ -722,17 +733,20 @@ declare function DateRangeControl({ value, onChange, onSubmit, fromLabel, toLabe
 /**
  * `AnchoredMenu` — the floating option list shared by `SelectControl` and `TypeaheadControl`.
  *
- * Renders an in-tree, absolutely-positioned popover under its anchor (the pattern aml-v2's
- * CountryPicker proved: `position:absolute; top:100%; zIndex; elevation`), so it floats over
- * sibling fields without a portal. On web it dismisses on outside-click / Escape; on native the
- * caller closes it on blur/select. Purely presentational + theme-flat, so it stays reusable.
+ * By default it renders an in-tree, absolutely-positioned popover under its anchor
+ * (`position:absolute; top:100%; zIndex; elevation`). Set {@link AnchoredMenuProps.usePortal} to
+ * render it — on web only — in a PORTAL to `document.body` with `position: fixed` at the trigger's
+ * measured rect instead: that escapes react-native-web's trapped `z-index: 0` stacking contexts and
+ * any ancestor `overflow: hidden`, so the menu is never painted under / clipped by later siblings
+ * (the fix for the Country typeahead menu that hid behind the content below it). See {@link menuPortal}.
+ * On web it dismisses on outside-click / Escape; on native the caller closes it on blur/select.
+ * Purely presentational + theme-flat, so it stays reusable.
  *
  * Promoted verbatim out of `@dloizides/ui-tables`' private `Filters/components/AnchoredMenu`.
  *
- * Deliberately in-tree (no `ui-layout` dependency). That was a considered choice in `ui-tables`
- * and it still holds here: `ui-forms` is a low-level primitive and must not take a runtime
- * dependency on the higher-level `ui-layout` `ModalDropdown` — that would invert the graph for
- * every consumer. Apps needing the responsive modal/bottom-sheet variant inject it instead.
+ * Deliberately no `ui-layout` dependency: `ui-forms` is a low-level primitive and must not take a
+ * runtime dependency on the higher-level `ui-layout` `ModalDropdown` — that would invert the graph
+ * for every consumer. The portal mechanism therefore lives locally in {@link menuPortal}.
  */
 
 /** The four theme colours the menu paints with — passed in, so the menu stays theme-flat. */
@@ -755,8 +769,16 @@ interface AnchoredMenuProps {
     testID: string;
     /** Node whose clicks count as "inside" (the anchor) so its own press doesn't self-dismiss. */
     anchorRef: React.RefObject<View | null>;
+    /**
+     * On web, render the popover in a portal to `document.body` with `position: fixed` at the anchor's
+     * measured rect, so it escapes react-native-web's trapped stacking contexts and any ancestor
+     * `overflow: hidden` (the fix for a menu that paints under / is clipped by the content below it).
+     * No effect on native. Default `false` — the existing in-tree behaviour, so `SelectControl`
+     * usages are unchanged; `TypeaheadControl` opts in.
+     */
+    usePortal?: boolean;
 }
-declare function AnchoredMenu({ options, selectedValue, onSelect, onDismiss, colors, optionHint, testID, anchorRef, }: AnchoredMenuProps): React.ReactElement;
+declare function AnchoredMenu({ options, selectedValue, onSelect, onDismiss, colors, optionHint, testID, anchorRef, usePortal, }: AnchoredMenuProps): React.ReactElement;
 
 declare const controlStyles: {
     /**

package/dist/index.d.ts

@@ -380,11 +380,22 @@ declare const FormActions: ({ onSave, onCancel, saveLabel, cancelLabel, saveHint
  */
 interface FormFieldProps extends Omit<TextInputProps, 'style'> {
     label: string;
+    /**
+     * Hide the VISIBLE label row while keeping the accessible name.
+     *
+     * For a field whose placeholder already names it (a toolbar search box, an inline
+     * filter) the stacked visible label both wastes a row and misaligns the input
+     * against a bare button beside it. Setting this drops ONLY the visible `<label>`:
+     * the input still carries `accessibilityLabel={label}`, so a screen reader reads
+     * the same name and `label` stays REQUIRED — you never lose the accessible name by
+     * blanking it, which is the trap this option exists to remove. Default `false`.
+     */
+    labelHidden?: boolean;
     required?: boolean;
     error?: string;
     containerStyle?: ViewStyle;
 }
-declare const FormField: ({ label, required, error, containerStyle, ...textInputProps }: FormFieldProps) => React.ReactElement;
+declare const FormField: ({ label, labelHidden, required, error, containerStyle, ...textInputProps }: FormFieldProps) => React.ReactElement;
 
 /**
  * `ThemedTextInput` — the shared, readable + lively text-input primitive. A thin `<TextInput>`
@@ -722,17 +733,20 @@ declare function DateRangeControl({ value, onChange, onSubmit, fromLabel, toLabe
 /**
  * `AnchoredMenu` — the floating option list shared by `SelectControl` and `TypeaheadControl`.
  *
- * Renders an in-tree, absolutely-positioned popover under its anchor (the pattern aml-v2's
- * CountryPicker proved: `position:absolute; top:100%; zIndex; elevation`), so it floats over
- * sibling fields without a portal. On web it dismisses on outside-click / Escape; on native the
- * caller closes it on blur/select. Purely presentational + theme-flat, so it stays reusable.
+ * By default it renders an in-tree, absolutely-positioned popover under its anchor
+ * (`position:absolute; top:100%; zIndex; elevation`). Set {@link AnchoredMenuProps.usePortal} to
+ * render it — on web only — in a PORTAL to `document.body` with `position: fixed` at the trigger's
+ * measured rect instead: that escapes react-native-web's trapped `z-index: 0` stacking contexts and
+ * any ancestor `overflow: hidden`, so the menu is never painted under / clipped by later siblings
+ * (the fix for the Country typeahead menu that hid behind the content below it). See {@link menuPortal}.
+ * On web it dismisses on outside-click / Escape; on native the caller closes it on blur/select.
+ * Purely presentational + theme-flat, so it stays reusable.
  *
  * Promoted verbatim out of `@dloizides/ui-tables`' private `Filters/components/AnchoredMenu`.
  *
- * Deliberately in-tree (no `ui-layout` dependency). That was a considered choice in `ui-tables`
- * and it still holds here: `ui-forms` is a low-level primitive and must not take a runtime
- * dependency on the higher-level `ui-layout` `ModalDropdown` — that would invert the graph for
- * every consumer. Apps needing the responsive modal/bottom-sheet variant inject it instead.
+ * Deliberately no `ui-layout` dependency: `ui-forms` is a low-level primitive and must not take a
+ * runtime dependency on the higher-level `ui-layout` `ModalDropdown` — that would invert the graph
+ * for every consumer. The portal mechanism therefore lives locally in {@link menuPortal}.
  */
 
 /** The four theme colours the menu paints with — passed in, so the menu stays theme-flat. */
@@ -755,8 +769,16 @@ interface AnchoredMenuProps {
     testID: string;
     /** Node whose clicks count as "inside" (the anchor) so its own press doesn't self-dismiss. */
     anchorRef: React.RefObject<View | null>;
+    /**
+     * On web, render the popover in a portal to `document.body` with `position: fixed` at the anchor's
+     * measured rect, so it escapes react-native-web's trapped stacking contexts and any ancestor
+     * `overflow: hidden` (the fix for a menu that paints under / is clipped by the content below it).
+     * No effect on native. Default `false` — the existing in-tree behaviour, so `SelectControl`
+     * usages are unchanged; `TypeaheadControl` opts in.
+     */
+    usePortal?: boolean;
 }
-declare function AnchoredMenu({ options, selectedValue, onSelect, onDismiss, colors, optionHint, testID, anchorRef, }: AnchoredMenuProps): React.ReactElement;
+declare function AnchoredMenu({ options, selectedValue, onSelect, onDismiss, colors, optionHint, testID, anchorRef, usePortal, }: AnchoredMenuProps): React.ReactElement;
 
 declare const controlStyles: {
     /**

package/dist/index.js

@@ -6,6 +6,7 @@ var uiFeedback = require('@dloizides/ui-feedback');
 var jsxRuntime = require('react/jsx-runtime');
 var uiButtons = require('@dloizides/ui-buttons');
 var a11y = require('@dloizides/a11y');
+var reactDom = require('react-dom');
 
 function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
 
@@ -612,23 +613,33 @@ var ThemedTextInput = React2__default.default.forwardRef(function ThemedTextInpu
 });
 var FormField = ({
   label,
+  labelHidden = false,
   required = false,
   error,
   containerStyle,
   ...textInputProps
-}) => /* @__PURE__ */ jsxRuntime.jsx(Field, { containerStyle, error, label, required, children: ({ describedById, hasError, controlId }) => /* @__PURE__ */ jsxRuntime.jsx(
-  ThemedTextInput,
+}) => /* @__PURE__ */ jsxRuntime.jsx(
+  Field,
   {
-    accessibilityHint: `Enter ${label}`,
-    accessibilityLabel: label,
-    describedById,
-    hasError,
-    id: controlId,
-    requiredField: required,
-    testID: "form-field-input",
-    ...textInputProps
+    containerStyle,
+    error,
+    label: labelHidden ? void 0 : label,
+    required,
+    children: ({ describedById, hasError, controlId }) => /* @__PURE__ */ jsxRuntime.jsx(
+      ThemedTextInput,
+      {
+        accessibilityHint: `Enter ${label}`,
+        accessibilityLabel: label,
+        describedById,
+        hasError,
+        id: controlId,
+        requiredField: required,
+        testID: "form-field-input",
+        ...textInputProps
+      }
+    )
   }
-) });
+);
 var TRANSPARENT_COLOR = "transparent";
 var WHITE_COLOR = "#fff";
 var SOLID_RADIUS = 20;
@@ -997,13 +1008,76 @@ var FormCheckbox = ({
     }
   );
 };
-var IS_WEB5 = typeof document !== "undefined";
+var IS_WEB5 = reactNative.Platform.OS === "web";
+var MENU_PORTAL_Z_INDEX = 1e3;
+var MENU_TOP_GAP2 = 4;
+function toDomNode(ref) {
+  const node = ref.current;
+  if (node === null || typeof node.getBoundingClientRect !== "function") return null;
+  return node;
+}
+function readAnchorRect(ref) {
+  if (!IS_WEB5) return null;
+  const node = toDomNode(ref);
+  if (node === null) return null;
+  const r = node.getBoundingClientRect();
+  return { top: r.top, left: r.left, width: r.width, bottom: r.bottom };
+}
+function buildPortalPopoverStyle(rect) {
+  return {
+    // RN's ViewStyle union omits 'fixed', but react-native-web honours it at runtime.
+    // eslint-disable-next-line @typescript-eslint/consistent-type-assertions -- web-only position value
+    position: "fixed",
+    top: rect.bottom + MENU_TOP_GAP2,
+    left: rect.left,
+    width: rect.width,
+    zIndex: MENU_PORTAL_Z_INDEX
+  };
+}
+function useAnchorRect(ref, enabled) {
+  const [rect, setRect] = React2.useState(null);
+  React2.useLayoutEffect(() => {
+    if (!IS_WEB5 || !enabled) {
+      setRect(null);
+      return void 0;
+    }
+    let frame = null;
+    let disposed = false;
+    const apply = () => {
+      frame = null;
+      if (disposed) return;
+      setRect(readAnchorRect(ref));
+    };
+    const schedule = () => {
+      if (frame !== null) return;
+      frame = window.requestAnimationFrame(apply);
+    };
+    apply();
+    document.addEventListener("scroll", schedule, true);
+    window.addEventListener("resize", schedule);
+    const node = toDomNode(ref);
+    const observer = typeof ResizeObserver === "function" ? new ResizeObserver(schedule) : null;
+    if (observer !== null) {
+      if (node !== null) observer.observe(node);
+      observer.observe(document.body);
+    }
+    return () => {
+      disposed = true;
+      if (frame !== null) window.cancelAnimationFrame(frame);
+      document.removeEventListener("scroll", schedule, true);
+      window.removeEventListener("resize", schedule);
+      if (observer !== null) observer.disconnect();
+    };
+  }, [ref, enabled]);
+  return IS_WEB5 && enabled ? rect : null;
+}
+var IS_WEB6 = typeof document !== "undefined";
 var ESCAPE_KEY = "Escape";
 var ACTIVE_WEIGHT = "700";
 var IDLE_WEIGHT = "400";
 function useDismiss(anchorRef, menuRef, onDismiss) {
   React2.useEffect(() => {
-    if (!IS_WEB5) return void 0;
+    if (!IS_WEB6) return void 0;
     const onMouseDown = (event) => {
       const anchorNode = anchorRef.current;
       const menuNode = menuRef.current;
@@ -1031,16 +1105,19 @@ function AnchoredMenu({
   colors,
   optionHint,
   testID,
-  anchorRef
+  anchorRef,
+  usePortal = false
 }) {
   const menuRef = React2__default.default.useRef(null);
   useDismiss(anchorRef, menuRef, onDismiss);
-  return /* @__PURE__ */ jsxRuntime.jsx(
+  const rect = useAnchorRect(anchorRef, usePortal);
+  const portalStyle = rect !== null ? buildPortalPopoverStyle(rect) : null;
+  const menu = /* @__PURE__ */ jsxRuntime.jsx(
     reactNative.View,
     {
       ref: menuRef,
       accessibilityRole: "menu",
-      style: [controlStyles.menu, { borderColor: colors.border, backgroundColor: colors.surface }],
+      style: [controlStyles.menu, { borderColor: colors.border, backgroundColor: colors.surface }, portalStyle],
       testID: `${testID}-menu`,
       children: options.map((opt) => {
         const active = opt.value === selectedValue;
@@ -1062,6 +1139,8 @@ function AnchoredMenu({
       })
     }
   );
+  if (usePortal && IS_WEB6) return reactDom.createPortal(menu, document.body);
+  return menu;
 }
 var CHEVRON_DOWN = "\u25BE";
 var CHEVRON_UP = "\u25B4";
@@ -1245,7 +1324,8 @@ function TypeaheadControl({
         colors: { text: colors.text, border: colors.border, surface: colors.surface, brand: palette.primary["500"] },
         optionHint,
         testID,
-        anchorRef
+        anchorRef,
+        usePortal: true
       }
     ) : null,
     hasError ? /* @__PURE__ */ jsxRuntime.jsx(reactNative.Text, { role: "alert", style: [controlStyles.error, { color: semantic.error["500"] }], testID: `${testID}-error`, children: error }) : null