@multiplatform.one/forms 7.46.0 → 7.47.0

package/src/Button/index.tsx

@@ -1,5 +1,5 @@
 import { IconSlot } from "@multiplatform.one/theme";
-import { transitionProps } from "@multiplatform.one/theme";
+import { transitionProps, SizableText } from "@multiplatform.one/theme";
 import { pressSlopProps } from "../shared/pressSlopProps";
 import {
   Children,
@@ -37,7 +37,7 @@ import { useFormField } from "../shared/utils";
 import {
   Button as TamaguiButton,
   type ButtonProps as TamaguiButtonProps,
-  SizableText,
+  SizableText as TamaguiSizableText,
   View,
   XStack,
   YStack,
@@ -339,6 +339,14 @@ export interface ButtonProps extends Omit<
    * `control`.
    */
   recipeFamily?: RecipeFamilyName;
+  /**
+   * A chromeless button at a container edge (a toolbar's back button) pulls
+   * out by its own horizontal padding, so its glyph sits on the content
+   * gutter while the press target reaches into the margin (MUI IconButton
+   * `edge`, iOS / Material top-bar navigation icon). No effect on a button
+   * that paints a frame: the frame is what aligns there.
+   */
+  edge?: "start" | "end";
 }
 
 export function Button({
@@ -363,6 +371,7 @@ export function Button({
   nested = false,
   circular,
   chromeless,
+  edge,
   verb,
   noun,
   actionRole,
@@ -444,6 +453,14 @@ export function Button({
   const touch = useTouchSurface();
   const recipe = resolveButtonSizeRecipe(resolvedSize, recipeFamily, touch);
   const padX = recipe.paddingHorizontal;
+  // `edge` cancels the padding the frame actually paints: an escaped number,
+  // a passed-through space token, or the recipe's.
+  const edgePull =
+    sizeRecipeEscaped && typeof paddingHorizontalProp === "number"
+      ? -paddingHorizontalProp
+      : typeof paddingHorizontalProp === "string" && paddingHorizontalProp.startsWith("$")
+        ? (`$-${paddingHorizontalProp.slice(1)}` as "$4")
+        : -padX;
   const radiusToken = knobProps.borderRadius.borderRadius;
   const radiusStop: SizeRecipeRadiusStop | undefined =
     typeof radiusToken === "string"
@@ -523,6 +540,10 @@ export function Button({
   const isLow = knobProps.textAccent === "low";
   const isMedium = knobProps.textAccent === "medium";
   const resolvedBorderWidth = knobProps.borderRadius.borderWidth;
+  // Tamagui applies props in key order, and a JSX prop that repeats a spread
+  // key keeps the spread's slot: left in, the fragment's `borderColor` would
+  // sit before `outlined`, whose `$borderColor` then beats the LC-148 hairline.
+  const { borderColor: knobBorderColor, ...radiusFragment } = knobProps.borderRadius;
   const [hovering, setHovering] = useState(false);
   const [pressing, setPressing] = useState(false);
   const handlePressIn = useCallback(() => {
@@ -574,7 +595,7 @@ export function Button({
     : recipe.iconSize;
 
   const renderLabelText = (label: string | number, key?: string) => (
-    <SizableText
+    <TamaguiSizableText
       key={key}
       userSelect="none"
       flexGrow={0}
@@ -602,7 +623,7 @@ export function Button({
       {...transitionProps(knobProps.motion.control)}
     >
       {label}
-    </SizableText>
+    </TamaguiSizableText>
   );
   // LC-82 TEXT-RIDES-TEXT: wrap ALL bare string/number children — the
   // array path (coalesced runs), not just the singleton case.
@@ -734,16 +755,11 @@ export function Button({
       aria-busy={loading || undefined}
       opacity={1}
       {...transitionProps(knobProps.motion.control, ["borderRadius", "borderWidth"])}
-      {...knobProps.borderRadius}
+      {...radiusFragment}
       {...(radiusStop === "medium" || radiusStop == null
         ? { borderRadius: paintedRadius.radius }
         : undefined)}
       borderWidth={resolvedBorderWidth}
-      // MPO-19 X3: the borderRadius knob fragment carries `$borderColor` for
-      // bordered chrome, but a filled Button's edge is transparent by contract
-      // (reference §6.1) — same-width invisible border keeps filled and
-      // outlined boxes identical without the filled one showing a ring.
-      borderColor={outlined ? "$borderColor" : "transparent"}
       size={resolvedSize}
       {...(chromeless ? undefined : knobProps.elevationChrome)}
       elevation={knobProps.elevation}
@@ -753,6 +769,11 @@ export function Button({
       // knob-driven caller passes `knobProps.outlined`, which is a real
       // boolean, so this fired on most screens.
       outlined={outlined || undefined}
+      // MPO-19 X3: the borderRadius knob fragment carries `$borderColor` for
+      // bordered chrome, but a filled Button's edge is transparent by contract
+      // (reference §6.1) — same-width invisible border keeps filled and
+      // outlined boxes identical without the filled one showing a ring.
+      borderColor={outlined ? knobBorderColor : "transparent"}
       circular={!nested && isCircular ? true : undefined}
       chromeless={selectedFill ? false : chromeless}
       selected={selectedFill || undefined}
@@ -767,6 +788,11 @@ export function Button({
             minHeight: visualPx,
           }
         : undefined)}
+      {...(edge && chromeless && !selectedFill && !isCircular
+        ? edge === "start"
+          ? { marginInlineStart: edgePull }
+          : { marginInlineEnd: edgePull }
+        : undefined)}
       {...(restFill ? { backgroundColor: restFill } : undefined)}
       // Solid-intent sub-themes carry the on-fill foreground as `$color`
       // (LC-05); outlined frames sit on the page, so re-anchor inherited
@@ -940,4 +966,4 @@ export function Button({
 }
 
 Button.Icon = TamaguiButton.Icon;
-Button.Text = SizableText;
+Button.Text = TamaguiSizableText;

package/src/Chip/Chip.stories.tsx

@@ -2,8 +2,9 @@ import { action } from "@multiplatform.one/storybook";
 import { CheckIcon, LightningIcon, TagIcon } from "@phosphor-icons/react";
 import type { Meta, StoryObj } from "@storybook/react-native-web-vite";
 import { useState } from "react";
-import { Text, XStack, YStack } from "tamagui";
+import { XStack, YStack } from "tamagui";
 import { Chip, type ChipColor, type ChipSize, type ChipVariantProp } from "./index";
+import { Text } from "@multiplatform.one/theme";
 
 const meta: Meta<typeof Chip> = {
   title: "Forms/Chip",

package/src/ContextualSaveBar/ContextualSaveBar.stories.tsx

@@ -1,7 +1,7 @@
 import { action } from "@multiplatform.one/storybook";
 import type { Meta, StoryObj } from "@storybook/react-native-web-vite";
 import { useState } from "react";
-import { SizableText, YStack } from "tamagui";
+import { YStack } from "tamagui";
 import { Button } from "../Button";
 import { Checkbox } from "../fields/Checkbox";
 import { Input } from "../fields/Input";
@@ -9,6 +9,7 @@ import { RadioGroup } from "../fields/RadioGroup";
 import { Switch } from "../fields/Switch";
 import { Form } from "../Form";
 import { ContextualSaveBar } from "./index";
+import { SizableText } from "@multiplatform.one/theme";
 
 const fields = (
   <YStack gap="$4" width="100%" maxWidth={640} padding="$4" minHeight={360}>

package/src/ContextualSaveBar/UnsavedChangesDialog.stories.tsx

@@ -1,9 +1,10 @@
 import { action } from "@multiplatform.one/storybook";
 import type { Meta, StoryObj } from "@storybook/react-native-web-vite";
 import { useState } from "react";
-import { Paragraph, YStack } from "tamagui";
+import { YStack } from "tamagui";
 import { Button } from "../Button";
 import { UnsavedChangesDialog } from "./UnsavedChangesDialog";
+import { Paragraph } from "@multiplatform.one/theme";
 
 const meta: Meta<typeof UnsavedChangesDialog> = {
   title: "Forms/ContextualSaveBar/UnsavedChangesDialog",

package/src/ControlGroup/ControlGroup.stories.tsx

@@ -1,9 +1,10 @@
 import type { GuardrailSpecimenParameter } from "@multiplatform.one/theme";
 import type { Meta, StoryObj } from "@storybook/react-native-web-vite";
-import { Paragraph, YStack } from "tamagui";
+import { YStack } from "tamagui";
 import { Button } from "../Button";
 import { Input } from "../InputParts";
 import { ControlGroup } from "./index";
+import { Paragraph } from "@multiplatform.one/theme";
 
 const meta: Meta<typeof ControlGroup> = {
   title: "Forms/ControlGroup",

package/src/DescriptionList/DescriptionList.stories.tsx

@@ -1,8 +1,9 @@
 import type { Meta, StoryObj } from "@storybook/react-native-web-vite";
-import { Paragraph, YStack } from "tamagui";
+import { YStack } from "tamagui";
 import { FormGrid } from "../FormGrid";
 import { FormSection, FormSectionStack } from "../FormSection";
 import { DescriptionList, type DescriptionListItem } from "./index";
+import { Paragraph } from "@multiplatform.one/theme";
 
 const meta: Meta<typeof DescriptionList> = {
   title: "Forms/DescriptionList",

package/src/ErrorSummary.stories.tsx

@@ -2,13 +2,14 @@ import { action } from "@multiplatform.one/storybook";
 import type { Meta, StoryObj } from "@storybook/react-native-web-vite";
 import { useForm } from "@tanstack/react-form";
 import { useState } from "react";
-import { Paragraph, YStack } from "tamagui";
+import { YStack } from "tamagui";
 import { Button } from "./Button";
 import { ErrorSummary, collectFormFieldErrors } from "./ErrorSummary";
 import { FieldLayout } from "./fieldLayout";
 import { Form } from "./Form";
 import { FormSection } from "./FormSection";
 import { Input as InputParts } from "./InputParts";
+import { Paragraph } from "@multiplatform.one/theme";
 
 const meta: Meta<typeof ErrorSummary> = {
   title: "Forms/ErrorSummary",

package/src/ErrorSummary.tsx

@@ -1,7 +1,7 @@
-import { FOCUS_RING_HALO_OFFSET, useResolvedKnobs } from "@multiplatform.one/theme";
+import { FOCUS_RING_HALO_OFFSET, useResolvedKnobs, H4 } from "@multiplatform.one/theme";
 import { WarningCircleIcon } from "@phosphor-icons/react";
 import { type ReactNode, useEffect, useId, useRef } from "react";
-import { Anchor, H4, Paragraph, YStack, isWeb } from "tamagui";
+import { Anchor, Paragraph, YStack, isWeb } from "tamagui";
 import { formCommonColors } from "./shared/colorRamps";
 import { t } from "./shared/t";
 import { warnBannedErrorWords as warnBannedErrorWordsShared } from "./shared/devWarn";

package/src/FieldDisplay/FieldDisplay.stories.tsx

@@ -1,7 +1,8 @@
 import type { Meta, StoryObj } from "@storybook/react-native-web-vite";
-import { Paragraph, XStack, YStack } from "tamagui";
+import { XStack, YStack } from "tamagui";
 import type { FieldDisplayType } from "./index";
 import { FieldDisplay } from "./index";
+import { Paragraph } from "@multiplatform.one/theme";
 
 const meta: Meta<typeof FieldDisplay> = {
   title: "Forms/FieldDisplay",

package/src/FieldLayout.stories.tsx

@@ -2,8 +2,8 @@ import { action } from "@multiplatform.one/storybook";
 import type { Meta, StoryObj } from "@storybook/react-native-web-vite";
 import { useForm } from "@tanstack/react-form";
 import { useState } from "react";
-import { Preset } from "@multiplatform.one/theme";
-import { Paragraph, YStack, XStack } from "tamagui";
+import { Preset, Paragraph } from "@multiplatform.one/theme";
+import { YStack, XStack } from "tamagui";
 import { Button } from "./Button";
 import { Form } from "./Form";
 import { Field, FieldLayout } from "./fieldLayout";

package/src/FloatingPanel/FloatingPanel.stories.tsx

@@ -1,7 +1,7 @@
 import { useState } from "react";
 import type { Meta, StoryObj } from "@storybook/react-native-web-vite";
-import { Preset } from "@multiplatform.one/theme";
-import { H4, Paragraph, ScrollView, Separator, Text, View, XStack, YStack } from "tamagui";
+import { Preset, Paragraph, H4, Text } from "@multiplatform.one/theme";
+import { ScrollView, Separator, View, XStack, YStack } from "tamagui";
 import { FloatingPanel } from "./index";
 import { Button } from "../Button";
 import { Select } from "../fields/Select";

package/src/FloatingPanel/PanelPortal.tsx

@@ -102,6 +102,7 @@ export function PanelPortal({ anchor, children }: PanelPortalProps) {
     const guard = event.currentTarget;
     const from = event.relatedTarget;
     const forward =
+      typeof Node === "undefined" ||
       !(from instanceof Node) ||
       Boolean(guard.compareDocumentPosition(from) & Node.DOCUMENT_POSITION_PRECEDING);
     const inside = tabbablesIn(portalRef.current);

package/src/FloatingPanel/index.native.tsx

@@ -88,6 +88,7 @@ import { useKeyboardInset } from "../shared/useKeyboardInset";
 import type { FloatingPanelProps } from "./index";
 import { placeAtPoint, type PanelBounds, type PanelPoint } from "./pointAnchor";
 import { panelViewportPadding } from "./useFloatingPanel";
+import { TrailingActionOverlay, TriggerWithTrailingAction } from "./trailingAction";
 
 // Re-export the hook + constants so Select / Combobox / external consumers
 // resolve identically on native (their floating cores are unused on device
@@ -472,6 +473,7 @@ export function FloatingPanel({
         style={{
           flexDirection: "row",
           alignItems: "center",
+          position: "relative",
           width: triggerSizing === "content" ? undefined : "100%",
         }}
       >
@@ -503,10 +505,10 @@ export function FloatingPanel({
             collapsable={false}
             style={{ width: triggerSizing === "content" ? undefined : "100%" }}
           >
-            {trigger}
+            <TriggerWithTrailingAction trigger={trigger} triggerEnd={triggerEnd} />
           </RNView>
         </Pressable>
-        {triggerEnd}
+        <TrailingActionOverlay>{triggerEnd}</TrailingActionOverlay>
       </RNView>
       <Modal
         visible={open}

package/src/FloatingPanel/index.tsx

@@ -23,6 +23,7 @@ import {
 import { isWeb, Sheet, View, YStack } from "tamagui";
 import { useClick, useDismiss, useInteractions } from "@floating-ui/react";
 import { ScrollArrow } from "../shared/floatingList";
+import { TrailingActionOverlay, TriggerWithTrailingAction } from "./trailingAction";
 import { useReturnFocusOnClose, useSheetModalFocus } from "../shared/focusManagement";
 import { useSheetEscapeDismiss } from "../shared/useSheetEscapeDismiss";
 import { useFloatingPanel, panelViewportPadding } from "./useFloatingPanel";
@@ -206,7 +207,14 @@ function useKeyboardFocusIntoPanel(
       if (!frame) return;
       if (!wasKeyboardFocus() && !keyboardOpenRef?.current) return;
       const active = document.activeElement;
-      if (active instanceof HTMLElement && frame.contains(active) && active !== frame) return;
+      if (
+        typeof HTMLElement !== "undefined" &&
+        active instanceof HTMLElement &&
+        frame.contains(active) &&
+        active !== frame
+      ) {
+        return;
+      }
       // Initial keyboard focus belongs to an action, not the repeated close row.
       const first = Array.from(frame.querySelectorAll<HTMLElement>(PANEL_FOCUSABLE)).find(
         (el) => !el.closest("[data-fp-trigger-row]"),
@@ -552,6 +560,7 @@ function FloatingPanelSheet({
         <View
           flexDirection="row"
           alignItems="center"
+          position="relative"
           width={triggerSizing === "content" ? "auto" : "100%"}
         >
           <View
@@ -562,9 +571,9 @@ function FloatingPanelSheet({
             opacity={disabled ? 0.5 : 1}
             {...triggerActivation}
           >
-            {trigger}
+            <TriggerWithTrailingAction trigger={trigger} triggerEnd={triggerEnd} />
           </View>
-          {triggerEnd}
+          <TrailingActionOverlay>{triggerEnd}</TrailingActionOverlay>
         </View>
       )}
       <Sheet
@@ -1112,7 +1121,8 @@ function FloatingPanelWeb({
     if (open || disabled || isContextMenu || event.button !== 0 || !isWeb) return;
     const reference = panel.triggerRef.current;
     if (!reference) return;
-    const target = event.target instanceof Element ? event.target : null;
+    const target =
+      typeof Element !== "undefined" && event.target instanceof Element ? event.target : null;
     const pressed = target?.closest<HTMLElement>(PANEL_FOCUSABLE);
     const focusable =
       pressed && reference.contains(pressed)

package/src/FloatingPanel/trailingAction.tsx

@@ -0,0 +1,37 @@
+import type { ReactNode } from "react";
+import { View, isWeb } from "tamagui";
+import { FieldTrailingOverlay } from "../InputParts";
+
+/**
+ * LC-149 FIELD-TRAILING-ACTION for picker triggers. `triggerEnd` stays out of
+ * the trigger's press capture (Fabric steals the responder from anything
+ * inside it), so it cannot live in the Box. It is laid over the Box's
+ * trailing edge instead, and the Box keeps that end cap empty for it: the
+ * clear reads as part of the field, not a button beside it.
+ */
+export function TriggerWithTrailingAction({
+  trigger,
+  triggerEnd,
+}: {
+  trigger: ReactNode;
+  triggerEnd?: ReactNode;
+}) {
+  const active = triggerEnd != null && triggerEnd !== false;
+  return <FieldTrailingOverlay active={active}>{trigger}</FieldTrailingOverlay>;
+}
+
+export function TrailingActionOverlay({ children }: { children?: ReactNode }) {
+  if (children == null || children === false) return null;
+  return (
+    <View
+      position="absolute"
+      top={0}
+      bottom={0}
+      {...(isWeb ? { insetInlineEnd: 0 } : { end: 0 })}
+      justifyContent="center"
+      data-field-action-overlay=""
+    >
+      {children}
+    </View>
+  );
+}

package/src/Form/Form.stories.tsx

@@ -11,7 +11,7 @@ import {
 } from "@phosphor-icons/react";
 import { useForm } from "@tanstack/react-form";
 import { useCallback, useState } from "react";
-import { H3, Separator, YStack } from "tamagui";
+import { Separator, YStack } from "tamagui";
 import { Button } from "../Button";
 import { FieldGroup } from "../FieldGroup";
 import { FormGrid } from "../FormGrid";
@@ -52,6 +52,7 @@ import { ToggleGroup } from "../fields/ToggleGroup";
 import { formatFieldError } from "../ErrorSummary";
 import type { AnyFormApi } from "../types";
 import { Form, FormActions } from "./index";
+import { H3 } from "@multiplatform.one/theme";
 
 const meta: Meta<typeof Form> = {
   title: "Forms/Form",

package/src/FormGrid.stories.tsx

@@ -1,9 +1,10 @@
 import type { Meta, StoryObj } from "@storybook/react-native-web-vite";
-import { Paragraph, YStack } from "tamagui";
+import { YStack } from "tamagui";
 import { FieldGroup } from "./FieldGroup";
 import { FormGrid } from "./FormGrid";
 import { FormSection, FormSectionStack } from "./FormSection";
 import { Input } from "./fields/Input";
+import { Paragraph } from "@multiplatform.one/theme";
 
 const meta: Meta<typeof FormGrid> = {
   title: "Forms/FormGrid",

package/src/FormGrid.tsx

@@ -115,6 +115,7 @@ function FormGridWeb({
     update(el.getBoundingClientRect().width);
 
     if (typeof ResizeObserver === "undefined") {
+      if (typeof window === "undefined" || typeof window.addEventListener !== "function") return;
       const onResize = () => update(el.getBoundingClientRect().width);
       window.addEventListener("resize", onResize);
       return () => window.removeEventListener("resize", onResize);

package/src/FormsIntegration.stories.tsx

@@ -1,15 +1,9 @@
 import { action } from "@multiplatform.one/storybook";
-import {
-  EnvelopeIcon,
-  KeyIcon,
-  MagnifyingGlassIcon,
-  EyeIcon,
-  EyeSlashIcon,
-} from "@phosphor-icons/react";
+import { EnvelopeIcon, KeyIcon, MagnifyingGlassIcon } from "@phosphor-icons/react";
 import type { Meta, StoryObj } from "@storybook/react-native-web-vite";
 import { useForm } from "@tanstack/react-form";
 import { useState } from "react";
-import { Paragraph, ScrollView, Separator, View, YStack } from "tamagui";
+import { ScrollView, Separator, View, YStack } from "tamagui";
 import {
   Button,
   Checkbox,
@@ -26,6 +20,7 @@ import {
   useFocusManagement,
 } from "./index";
 import type { AnyFormApi } from "./types";
+import { Paragraph } from "@multiplatform.one/theme";
 
 const meta: Meta<typeof Form> = {
   title: "Forms/FormsIntegration",
@@ -266,8 +261,6 @@ export const multiStepRegistration: Story = {
 
 export const inputComposition: Story = {
   render: function InputComposition() {
-    const [showPassword, setShowPassword] = useState(false);
-
     return (
       <ScrollView>
         <View padding="$4" maxWidth={600} alignSelf="center">
@@ -283,15 +276,8 @@ export const inputComposition: Story = {
               <Input
                 label="Password"
                 placeholder="Enter password"
-                secureTextEntry={!showPassword}
+                secureTextEntry
                 leftIcon={<KeyIcon />}
-                rightIcon={
-                  showPassword ? (
-                    <EyeSlashIcon cursor="pointer" onClick={() => setShowPassword(false)} />
-                  ) : (
-                    <EyeIcon cursor="pointer" onClick={() => setShowPassword(true)} />
-                  )
-                }
               />
 
               <Input label="Required Field" placeholder="This field is required" required />

package/src/InputParts/InputParts.stories.tsx

@@ -3,12 +3,14 @@ import type { Meta, StoryObj } from "@storybook/react-native-web-vite";
 import {
   EnvelopeIcon,
   EyeIcon,
+  EyeSlashIcon,
   MagnifyingGlassIcon,
   WarningCircleIcon,
 } from "@phosphor-icons/react";
 import { useState } from "react";
-import { Paragraph, YStack } from "tamagui";
+import { YStack } from "tamagui";
 import { Input as InputParts } from "./index";
+import { Paragraph } from "@multiplatform.one/theme";
 
 const meta: Meta<typeof InputParts> = {
   title: "Forms/InputParts",
@@ -107,8 +109,9 @@ export const Adornments: Story = {
 };
 
 /**
- * `InputParts.Button` is the pressable end-cap — a reveal toggle, a clear, a
- * copy. It squares off to the control height so the frame stays rectangular.
+ * `InputParts.Action` is the field's own action (LC-149): a reveal toggle, a
+ * clear, a copy. A chromeless glyph that squares off to the control height
+ * inside the frame, never a bordered button beside it.
  */
 export const TrailingButton: Story = {
   render: () => {
@@ -124,19 +127,16 @@ export const TrailingButton: Story = {
               secureTextEntry={secure}
               onChangeText={action("onChangeText")}
             />
-            <InputParts.Button
-              glyphRing
-              type="button"
-              aria-label={secure ? "Show password" : "Hide password"}
+            <InputParts.Action
+              label={secure ? "Show password" : "Hide password"}
+              pressed={!secure}
               onPress={() => {
                 setSecure((prev) => !prev);
                 action("togglePasswordVisibility")(!secure);
               }}
             >
-              <InputParts.Icon aria-hidden>
-                <EyeIcon />
-              </InputParts.Icon>
-            </InputParts.Button>
+              {secure ? <EyeIcon /> : <EyeSlashIcon />}
+            </InputParts.Action>
           </InputParts.Box>
           <InputParts.Meta helperText={secure ? "Hidden" : "Visible"} />
         </InputParts>

package/src/InputParts/PasswordReveal.tsx

@@ -0,0 +1,94 @@
+import { EyeIcon, EyeSlashIcon } from "@phosphor-icons/react";
+import type { RefObject } from "react";
+import { useCallback, useEffect, useLayoutEffect, useRef, useState } from "react";
+import type { FontSizeTokens, SizeTokens } from "tamagui";
+import { Input } from "./index";
+
+export const SHOW_PASSWORD = "Show password";
+export const HIDE_PASSWORD = "Hide password";
+
+type Selection = { start: number; end: number };
+
+function domInput(node: unknown, id?: string): HTMLInputElement | null {
+  const fromRef = node as { setSelectionRange?: unknown } | null;
+  if (fromRef && typeof fromRef.setSelectionRange === "function") {
+    return fromRef as HTMLInputElement;
+  }
+  if (typeof document === "undefined" || !id) return null;
+  return document.getElementById(id) as HTMLInputElement | null;
+}
+
+function readSelection(node: unknown, id?: string): Selection | null {
+  const el = domInput(node, id);
+  if (!el || typeof el.selectionStart !== "number") return null;
+  return { start: el.selectionStart, end: el.selectionEnd ?? el.selectionStart };
+}
+
+/**
+ * Reveal state for a masked field. Toggling keeps focus and the caret where
+ * they were (web swaps the input type, which would otherwise drop both), and
+ * an emptied field goes back to masked.
+ */
+export function usePasswordReveal({
+  inputRef,
+  id,
+  text,
+}: {
+  inputRef: RefObject<unknown>;
+  id?: string;
+  text: string;
+}) {
+  const [revealed, setRevealed] = useState(false);
+  const pendingSelection = useRef<Selection | null>(null);
+
+  useEffect(() => {
+    if (!text) setRevealed(false);
+  }, [text]);
+
+  useLayoutEffect(() => {
+    const selection = pendingSelection.current;
+    if (!selection) return;
+    pendingSelection.current = null;
+    const el = domInput(inputRef.current, id);
+    el?.focus();
+    el?.setSelectionRange(selection.start, selection.end);
+  }, [id, inputRef, revealed]);
+
+  const toggle = useCallback(() => {
+    pendingSelection.current = readSelection(inputRef.current, id);
+    setRevealed((open) => !open);
+  }, [id, inputRef]);
+
+  return { revealed, toggle };
+}
+
+export interface PasswordRevealProps {
+  revealed: boolean;
+  onToggle: () => void;
+  /** id of the masked input. */
+  controls?: string;
+  disabled?: boolean;
+  size?: SizeTokens | FontSizeTokens;
+}
+
+/** LC-149: the reveal is the field's trailing action, eye / eye-slash. */
+export function PasswordReveal({
+  revealed,
+  onToggle,
+  controls,
+  disabled,
+  size,
+}: PasswordRevealProps) {
+  return (
+    <Input.Action
+      label={revealed ? HIDE_PASSWORD : SHOW_PASSWORD}
+      pressed={revealed}
+      controls={controls}
+      disabled={disabled}
+      size={size}
+      onPress={onToggle}
+    >
+      {revealed ? <EyeSlashIcon /> : <EyeIcon />}
+    </Input.Action>
+  );
+}