@multiplatform.one/forms 6.1.0 → 6.3.0

package/src/InputParts/index.tsx

@@ -1,8 +1,9 @@
 import { getFontSized } from "@tamagui/get-font-sized";
 import { getSpace } from "@tamagui/get-token";
 import type { SizeVariantSpreadFunction } from "@tamagui/web";
-import { useEffect, useState } from "react";
+import { useEffect, useState, type ReactNode } from "react";
 import type { ComponentProps, Ref, RefObject } from "react";
+import { Pressable as RNPressable } from "react-native";
 import type { ColorTokens, FontSizeTokens, TamaguiElement } from "tamagui";
 import {
   Button as TButton,
@@ -19,11 +20,31 @@ import {
   useGetThemedIcon,
   useTheme,
 } from "tamagui";
-import { useResolvedKnobs } from "@multiplatform.one/theme";
+import {
+  ensureFocusVisibleRing,
+  useResolvedKnobs,
+  warnOutlineNone,
+  warnPositiveTabIndex,
+} from "@multiplatform.one/theme";
 import { formButtonColors, formCommonColors, formInputColors } from "../shared/colorRamps";
 import { useControlGrouped } from "../shared/groupContext";
 import { useIsInTableCell } from "../shared/tableCellContext";
-import { useFieldDescribedBy } from "../fieldLayout";
+import { useFieldA11y, useFieldDescribedBy } from "../fieldLayout";
+
+/**
+ * Native-only accessible name/hint from the field context. Web keeps its
+ * audited aria-labelledby/-describedby wiring; iOS needs the strings on the
+ * control itself. Spread BEFORE consumer props so an explicit
+ * accessibilityLabel / aria-label ejects.
+ */
+function useNativeFieldA11yProps() {
+  const fieldA11y = useFieldA11y();
+  if (isWeb || !fieldA11y) return undefined;
+  return {
+    ...(fieldA11y.label ? { accessibilityLabel: fieldA11y.label } : undefined),
+    ...(fieldA11y.description ? { accessibilityHint: fieldA11y.description } : undefined),
+  };
+}
 
 // ---------------------------------------------------------------------------
 // Context
@@ -69,6 +90,55 @@ export const useForwardFocus = (target: RefObject<TamaguiElement | null>) => {
 // Default group styles
 // ---------------------------------------------------------------------------
 
+/**
+ * Tamagui named transitions (`quick`, etc.) compile to `transition: all …`.
+ * That tweens outline-color/width on blur — in dark theme `$outlineColor` is
+ * near-white, so the ring flashes white while settling. Scope the frame
+ * transition to non-outline paint props instead.
+ */
+const inputFrameCssTimings: Record<string, string> = {
+  bouncy: "ease-in 200ms",
+  lazy: "ease-in 600ms",
+  slow: "ease-in 500ms",
+  medium: "ease-in-out 250ms",
+  quick: "ease-in 100ms",
+  tooltip: "ease-in 400ms",
+  snappy: "ease-out 80ms",
+  gentle: "ease-in-out 450ms",
+};
+
+export function getInputFrameTransitionProps(transition: string | undefined) {
+  if (!transition) return undefined;
+  if (!isWeb) return { transition };
+  const timing = inputFrameCssTimings[transition] ?? inputFrameCssTimings.quick;
+  return {
+    // Prefer explicit CSS over Tamagui's `transition: all` named prop.
+    style: {
+      transition: [
+        `background-color ${timing}`,
+        `border-color ${timing}`,
+        `color ${timing}`,
+        `opacity ${timing}`,
+        `box-shadow ${timing}`,
+        `transform ${timing}`,
+      ].join(", "),
+    },
+  };
+}
+
+/** Resting outline: transparent + 0 width so blur never lands on theme `$outlineColor`. */
+const inputOutlineRest = {
+  outlineWidth: 0,
+  outlineColor: "transparent",
+  outlineStyle: "solid" as any,
+} as const;
+
+const inputOutlineFocus = {
+  outlineColor: "$outlineColor",
+  outlineWidth: 2,
+  outlineStyle: "solid" as any,
+} as const;
+
 export const defaultInputGroupStyles = {
   size: "$true",
   fontFamily: "$body",
@@ -87,18 +157,20 @@ export const defaultInputGroupStyles = {
   backgroundColor: formInputColors.background.base,
 
   minWidth: 0,
-  outlineStyle: "none" as any,
+  ...inputOutlineRest,
+
+  hoverStyle: {
+    borderColor: formInputColors.border.hover,
+  },
 
   focusStyle: {
     borderColor: formInputColors.border.focus,
-    backgroundColor: formInputColors.background.focus,
-    outlineStyle: "none" as any,
+    ...inputOutlineFocus,
   },
 
   focusVisibleStyle: {
     borderColor: formInputColors.border.focus,
-    backgroundColor: formInputColors.background.focus,
-    outlineStyle: "none" as any,
+    ...inputOutlineFocus,
   },
 } as const;
 
@@ -133,35 +205,136 @@ const InputGroupFrame = styled(XGroup, {
   },
 });
 
+// RN's `elevation` style prop must be a number — the Tamagui token string
+// ("$1") that knobProps.elevation carries crashes the Android ReactHost at
+// mount (String → Double cast). Web resolves the token via Tamagui's
+// elevation variant, so it keeps the token; native gets explicit shadow
+// props (values mirror elevationToProps in ../shared/utils).
+const nativeElevationShadow: Record<string, Record<string, any>> = {
+  $1: {
+    shadowColor: "#000",
+    shadowOffset: { width: 0, height: 1 },
+    shadowOpacity: 0.12,
+    // house light angle: blur = 2 x y-offset on every tier (Axiom 14)
+    shadowRadius: 2,
+    elevation: 2,
+  },
+  $2: {
+    shadowColor: "#000",
+    shadowOffset: { width: 0, height: 3 },
+    shadowOpacity: 0.15,
+    shadowRadius: 6,
+    elevation: 4,
+  },
+  $4: {
+    shadowColor: "#000",
+    shadowOffset: { width: 0, height: 10 },
+    shadowOpacity: 0.15,
+    shadowRadius: 20,
+    elevation: 8,
+  },
+};
+
+// On native the theme now emits NUMERIC tokens.size values ($1=20, $2=28,
+// $4=44) instead of token strings (SB-N-04 central fix); accept both.
+const elevationKeyAlias: Record<string, string> = { "20": "$1", "28": "$2", "44": "$4" };
+
+function getBoxElevationProps(token: string | number | undefined): Record<string, any> {
+  if (token == null) return { elevation: undefined };
+  if (isWeb) return { elevation: token };
+  const key = elevationKeyAlias[String(token)] ?? String(token);
+  return nativeElevationShadow[key] || nativeElevationShadow.$2;
+}
+
+/**
+ * Fabric + Tamagui XGroup often claims the responder without firing `onPress`,
+ * so Select/Date/Combobox triggers look tappable but never open. On native,
+ * own the gesture with a core RN Pressable and disable hit-testing on the
+ * XGroup chrome (buttons that must stay tappable — clear, chip dismiss —
+ * should sit outside InputParts.Box, e.g. FloatingPanel triggerEnd).
+ */
+function wrapNativePressable(
+  onPress: ((e?: any) => void) | undefined,
+  disabled: boolean | undefined,
+  node: ReactNode,
+) {
+  if (isWeb || !onPress) return node;
+  return (
+    <RNPressable
+      onPress={onPress}
+      disabled={!!disabled}
+      accessibilityRole="button"
+      style={disabled ? { opacity: 0.5 } : undefined}
+    >
+      <View pointerEvents="none" collapsable={false} width="100%">
+        {node}
+      </View>
+    </RNPressable>
+  );
+}
+
 const InputGroupImpl = InputGroupFrame.styleable((groupProps, forwardedRef) => {
-  const { children, ...props } = groupProps;
+  const { children, onPress, disabled, ...props } = groupProps as typeof groupProps & {
+    onPress?: (e?: any) => void;
+    disabled?: boolean;
+  };
   const [focused, setFocused] = useState(false);
-  const { knobProps, control } = useResolvedKnobs();
+  const { knobProps, control, disabledState } = useResolvedKnobs();
   const grouped = useControlGrouped();
   const inTableCell = useIsInTableCell();
+  // Native Pressable owns onPress; do not also pass it to XGroup (double-fire).
+  const framePressProps = isWeb ? { onPress, disabled } : { disabled };
+
+  // DG-A11Y-01 / DG-A11Y-03 — DEV guardrails (tree-shaken in production).
+  warnPositiveTabIndex({
+    value: (props as { tabIndex?: number | string }).tabIndex,
+    component: "Input.Box",
+  });
+  warnOutlineNone((props as { focusVisibleStyle?: object }).focusVisibleStyle, {
+    component: "Input.Box",
+  });
 
   // Chromeless rendering inside table cells
   if (inTableCell) {
     return (
       <FocusContext.Provider focused={focused} setFocused={setFocused}>
-        <InputGroupFrame
-          ref={forwardedRef}
-          borderWidth={0}
-          borderRadius={0}
-          backgroundColor="transparent"
-          flex={1}
-          elevation={undefined}
-          {...props}
-          overflow="visible"
-        >
-          {children}
-        </InputGroupFrame>
+        {wrapNativePressable(
+          onPress,
+          disabled,
+          <InputGroupFrame
+            ref={forwardedRef}
+            borderWidth={0}
+            borderRadius={0}
+            backgroundColor="transparent"
+            // Expanded (not the `flex` shorthand): the shorthand's basis-0
+            // beats consumer width/flex overrides in the merge, collapsing
+            // fixed-size boxes (OTP digit cells) to 0pt inside row layouts.
+            // Basis auto keeps explicit widths as the base; lone inputs in
+            // column cells still grow to fill exactly as before.
+            flexGrow={1}
+            flexShrink={1}
+            flexBasis="auto"
+            // LC-06/LC-10 (UX-P12): the chromeless frame must never lay out
+            // wider than its cell — cap at the cell width and allow shrink
+            // below the inner input's intrinsic width.
+            maxWidth="100%"
+            minWidth={0}
+            elevation={undefined}
+            {...props}
+            {...framePressProps}
+            overflow="visible"
+          >
+            {children}
+          </InputGroupFrame>,
+        )}
       </FocusContext.Provider>
     );
   }
 
   if (grouped) {
-    return (
+    return wrapNativePressable(
+      onPress,
+      disabled,
       <InputGroupFrame
         ref={forwardedRef}
         borderWidth={0}
@@ -170,55 +343,80 @@ const InputGroupImpl = InputGroupFrame.styleable((groupProps, forwardedRef) => {
         flex={1}
         elevation={undefined}
         {...props}
+        {...framePressProps}
         overflow="visible"
       >
         {children}
-      </InputGroupFrame>
+      </InputGroupFrame>,
     );
   }
 
   return (
     <FocusContext.Provider focused={focused} setFocused={setFocused}>
-      <InputGroupFrame
-        ref={forwardedRef}
-        {...knobProps.body}
-        size={knobProps.sizeToken}
-        backgroundColor={knobProps.outlined ? "transparent" : formInputColors.background.base}
-        elevation={knobProps.elevation}
-        {...knobProps.borderRadius}
-        {...(knobProps.transition ? { transition: knobProps.transition } : undefined)}
-        {...(control.hoverKnobProps && { hoverStyle: control.hoverKnobProps })}
-        {...(control.pressKnobProps && { pressStyle: control.pressKnobProps })}
-        {...(control.focusKnobProps && {
-          focusStyle: {
+      {wrapNativePressable(
+        onPress,
+        disabled,
+        <InputGroupFrame
+          ref={forwardedRef}
+          {...knobProps.body}
+          size={knobProps.sizeToken}
+          backgroundColor={knobProps.outlined ? "transparent" : formInputColors.background.base}
+          {...getBoxElevationProps(knobProps.elevation)}
+          {...knobProps.borderRadius}
+          {...getInputFrameTransitionProps(
+            typeof knobProps.transition === "string" ? knobProps.transition : undefined,
+          )}
+          hoverStyle={{
+            borderColor: formInputColors.border.hover,
+            ...control.hoverKnobProps,
+          }}
+          pressStyle={{
+            ...control.pressKnobProps,
+          }}
+          focusStyle={{
             borderColor: formInputColors.border.focus,
-            backgroundColor: knobProps.outlined ? "transparent" : formInputColors.background.focus,
-            outlineStyle: "none",
+            ...inputOutlineFocus,
             ...control.focusKnobProps,
-          },
-        })}
-        {...(control.focusVisibleKnobProps && {
-          focusVisibleStyle: {
+          }}
+          focusVisibleStyle={ensureFocusVisibleRing({
             borderColor: formInputColors.border.focus,
-            backgroundColor: knobProps.outlined ? "transparent" : formInputColors.background.focus,
-            outlineStyle: "none",
+            ...inputOutlineFocus,
             ...control.focusVisibleKnobProps,
-          },
-        })}
-        {...props}
-        {...(focused
-          ? {
-              borderColor: formInputColors.border.focus,
-              backgroundColor: knobProps.outlined
-                ? "transparent"
-                : formInputColors.background.focus,
-              ...control.focusKnobProps,
-            }
-          : undefined)}
-        overflow="hidden"
-      >
-        {children}
-      </InputGroupFrame>
+          })}
+          {...props}
+          {...framePressProps}
+          {...(focused
+            ? {
+                // Focus is forwarded from the inner input, so the ring is applied
+                // as inline props rather than focusStyle.
+                borderColor: formInputColors.border.focus,
+                ...ensureFocusVisibleRing({
+                  ...inputOutlineFocus,
+                  ...control.focusKnobProps,
+                  ...control.focusVisibleKnobProps,
+                }),
+              }
+            : {
+                // Explicit rest — avoid leaving theme `$outlineColor` (near-white in
+                // dark) as the computed outline-color while width settles.
+                // Keep outline-transparent rest (border-flicker fix); do not warn.
+                ...inputOutlineRest,
+              })}
+          // LC-40 DISABLED-VISIBLE: the input frame is text-bearing chrome —
+          // keepLabel washes fill/border (value text keeps >= AA) and
+          // dimWhole leaves the dim to the FieldLayout assembly. Read-only
+          // never reaches this branch (a different state, never dimmed).
+          {...(disabled
+            ? {
+                ...disabledState.surfaceKnobProps,
+                hoverStyle: { ...disabledState.surfaceKnobProps },
+              }
+            : undefined)}
+          overflow="hidden"
+        >
+          {children}
+        </InputGroupFrame>,
+      )}
     </FocusContext.Provider>
   );
 });
@@ -229,9 +427,9 @@ const InputGroupImpl = InputGroupFrame.styleable((groupProps, forwardedRef) => {
 
 export const inputSizeVariant: SizeVariantSpreadFunction<any> = (val = "$true", extras) => {
   const size = val || "$true";
-  // Use shift: 0 for balanced horizontal padding that matches vertical spacing
+  // shift: -1 matches Bento's tighter horizontal padding
   const paddingHorizontal = getSpace(size, {
-    shift: 0,
+    shift: -1,
     bounds: [2],
   });
   const fontStyle = getFontSized(size as FontSizeTokens, extras);
@@ -281,15 +479,24 @@ const InputAreaImpl = InputFrame.styleable<{
   const { knobProps } = useResolvedKnobs();
   const theme = useTheme();
   const fieldDescribedBy = useFieldDescribedBy();
+  const nativeA11yProps = useNativeFieldA11yProps();
+  const inTableCell = useIsInTableCell();
 
   return (
-    <View flex={1}>
+    // LC-06/LC-10 (UX-P12): in a table cell the flex wrapper and the raw
+    // input must be allowed to shrink below the <input>'s intrinsic width
+    // (min-width:auto floors flex items at it); width 100% makes the input
+    // adopt the flexed width instead of its size-attribute default. Explicit
+    // consumer widths (OTP digit boxes) still win via the later spread.
+    <View flex={1} {...(inTableCell ? { minWidth: 0 } : undefined)}>
       <InputFrame
         aria-describedby={fieldDescribedBy}
+        {...nativeA11yProps}
         ref={ref}
         size={size}
         color={knobProps.textAccentColor}
-        placeholderTextColor={theme.color7?.val ?? "$color7"}
+        placeholderTextColor={theme.placeholderColor?.val ?? "$placeholderColor"}
+        {...(inTableCell ? { width: "100%" as const, minWidth: 0 } : undefined)}
         {...knobProps.body}
         type={secureTextEntry ? "password" : props.type}
         inputMode={
@@ -431,14 +638,15 @@ const InputIcon = InputIconFrame.styleable<{
   const iconSize = getIconSize(size as FontSizeTokens, resolvedScaleIcon);
 
   // Calculate padding based on adornment position for consistent spacing
-  // Leading icons: padding on left only (input area has its own left padding)
-  // Trailing icons: padding on right only (input area has its own right padding)
+  // Leading icons: padding on the start side only (input area has its own
+  // start padding); trailing icons: padding on the end side only. Logical
+  // props so the spacing mirrors in RTL.
   const padding = getSpace(size, { shift: 0, bounds: [2] });
   const paddingProps =
     adornment === "leading"
-      ? { paddingLeft: padding, paddingRight: 0 }
+      ? { paddingInlineStart: padding, paddingInlineEnd: 0 }
       : adornment === "trailing"
-        ? { paddingRight: padding, paddingLeft: 0 }
+        ? { paddingInlineEnd: padding, paddingInlineStart: 0 }
         : { paddingHorizontal: padding };
 
   const getThemedIcon = useGetThemedIcon({ size: iconSize, color: color as any });
@@ -482,11 +690,17 @@ export const InputContainerFrame = styled(View, {
 
 const InputContainerImpl = InputContainerFrame.styleable((props, forwardedRef) => {
   const { knobProps } = useResolvedKnobs();
+  const inTableCell = useIsInTableCell();
   return (
     <InputContainerFrame
       ref={forwardedRef}
       size={knobProps.sizeToken}
       {...knobProps.body}
+      // LC-06/LC-10 (UX-P12): inside a table cell the field root must adopt
+      // the cell width — the raw web <input> carries an intrinsic width that
+      // otherwise floors the whole column at ~200px and lays out past the
+      // cell clip box (measured 109.8px past on the stepper columns).
+      {...(inTableCell ? { maxWidth: "100%" as const, minWidth: 0 } : undefined)}
       {...props}
     />
   );
@@ -511,12 +725,7 @@ const InputLabelFrame = styled(Label, {
 export const InputLabel = InputLabelFrame.styleable((props, ref) => {
   const { knobProps } = useResolvedKnobs();
   return (
-    <InputLabelFrame
-      ref={ref}
-      {...knobProps.heading}
-      color={knobProps.textAccentColor}
-      {...props}
-    />
+    <InputLabelFrame ref={ref} {...knobProps.body} color={knobProps.textAccentColor} {...props} />
   );
 });
 
@@ -560,8 +769,9 @@ export const InputInfo = InputInfoFrame.styleable((props, ref) => {
 });
 
 /**
- * Caption under the control: optional helper, then optional validation error on its own line.
- * Keeps helper visible when both exist (clearer than replacing the only hint with the error).
+ * Caption under the control: one reserved message slot (Axiom 8 STABLE GROUND /
+ * DG-FORM-04). The validation error replaces the helper in place — never a
+ * second line — so surfacing an error shifts no layout. Matches FieldLayout.
  */
 export function InputFieldMeta({
   helperText,
@@ -574,17 +784,15 @@ export function InputFieldMeta({
     displayError && typeof displayError === "string" && displayError.length > 0
       ? displayError
       : undefined;
-  if (!helperText && !errorMessage) return null;
-  return (
-    <>
-      {helperText ? <InputInfo>{helperText}</InputInfo> : null}
-      {errorMessage ? (
-        <InputInfo color={formCommonColors.error} role="alert" aria-live="polite">
-          {errorMessage}
-        </InputInfo>
-      ) : null}
-    </>
-  );
+  if (errorMessage) {
+    return (
+      <InputInfo color={formCommonColors.error} role="alert" aria-live="polite">
+        {errorMessage}
+      </InputInfo>
+    );
+  }
+  if (!helperText) return null;
+  return <InputInfo>{helperText}</InputInfo>;
 }
 
 // ---------------------------------------------------------------------------
@@ -621,10 +829,12 @@ export function FocusWiredTextArea(props: TamaguiTextAreaProps & { innerRef?: Re
   const { setFocused } = FocusContext.useStyledContext();
   const { innerRef, onFocus, onBlur, ...rest } = props;
   const fieldDescribedBy = useFieldDescribedBy();
+  const nativeA11yProps = useNativeFieldA11yProps();
   return (
     <View flex={1}>
       <ThemedTextArea
         aria-describedby={fieldDescribedBy}
+        {...nativeA11yProps}
         ref={innerRef}
         width="100%"
         onFocus={(e: any) => {

package/src/Label/Label.stories.tsx

@@ -0,0 +1,55 @@
+import type { Meta, StoryObj } from "@storybook/react-native-web-vite";
+import { Input as TamaguiInput, YStack } from "tamagui";
+import { Label } from "./index";
+
+const meta: Meta<typeof Label> = {
+  title: "Forms/Label",
+  component: Label,
+  parameters: { status: { type: "beta" } },
+  argTypes: {
+    children: { control: "text" },
+    size: { control: "select", options: ["$1", "$2", "$3", "$4", "$6", "$8"] },
+    htmlFor: { control: "text" },
+  },
+  args: {
+    children: "Email address",
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof Label>;
+
+export const Basic: Story = {
+  render: (args) => <Label {...args} />,
+};
+
+export const WithControl: Story = {
+  render: () => (
+    <YStack gap="$2" maxWidth={320}>
+      <Label htmlFor="label-story-input">Email address</Label>
+      <TamaguiInput id="label-story-input" placeholder="you@example.com" />
+    </YStack>
+  ),
+};
+
+export const EdgeCases: Story = {
+  render: () => (
+    <YStack gap="$4" maxWidth={360}>
+      <YStack gap="$2">
+        <Label htmlFor="label-empty">{""}</Label>
+        <TamaguiInput id="label-empty" placeholder="empty label above" />
+      </YStack>
+      <YStack gap="$2">
+        <Label htmlFor="label-long">
+          This is an extremely long label that keeps going and going to check wrapping behaviour of
+          label text over multiple lines without breaking the layout of the associated control
+        </Label>
+        <TamaguiInput id="label-long" placeholder="long label above" />
+      </YStack>
+      <YStack gap="$2">
+        <Label htmlFor="label-rtl">تسمية باللغة العربية</Label>
+        <TamaguiInput id="label-rtl" placeholder="rtl label above" />
+      </YStack>
+    </YStack>
+  ),
+};