@unif/react-native-design 0.20.0 → 0.21.0

package/src/components/ui/TextField/TextFieldBase.tsx

@@ -1,35 +1,40 @@
-import React, { type ComponentRef, forwardRef, useState } from 'react';
-import { Text, TextInput, View } from 'react-native';
-import { control, r, space, useColors, useThemedStyles } from '../../../theme';
+import React, {
+  type ComponentRef,
+  forwardRef,
+  useEffect,
+  useImperativeHandle,
+  useState,
+} from 'react';
+import { Platform, Text, TextInput, View } from 'react-native';
+import type { TextInputProps } from 'react-native';
+import { fixed, space, useColors, useThemedStyles } from '../../../theme';
 import { childTestID } from '../../../utils/testID';
+import { createLogger } from '../../../utils/logger';
+import {
+  normalizeInputHeight,
+  normalizeTextareaHeights,
+  sanitizeTextFieldContainerStyle,
+} from './normalize';
 import { makeStyles } from './styles';
-import type { TextFieldBaseProps } from './types';
+import { TextFieldSlot } from './TextFieldSlot';
+import type { TextFieldBaseProps, TextFieldHandle } from './types';
+import { useErrorAnnouncement } from './useErrorAnnouncement';
+import { useTextFieldValue } from './useTextFieldValue';
 
-/** `TextInput` 在 react-native-strict-api 下是组件类型(`TextInputType`),
- *  ref 实例类型走 `ComponentRef<typeof TextInput>`(对应内部 `_TextInputInstance`)。 */
-export type TextInputRef = ComponentRef<typeof TextInput>;
+const log = createLogger('TextField');
 
-/**
- * Input / Textarea 共享 primitive —— internal,不在主 barrel 导出。
- *
- * 行为:
- * - 视觉 4 态:idle(浅灰)/ focus(白底 brand 边)/ filled(白底 outline 边)/ error
- * - leading / trailing 左右 slot
- * - disabled 优先于 editable
- * - multiline=false → 单行 fixed height(默认 control.lg)
- * - multiline=true → 多行 minHeight/maxHeight,文字顶对齐,wrap 上下加 padding
- * - forwardRef<TextInput> —— 业务表单 inputRef.current?.focus() 聚焦
- *
- * 公开 API 是 Input / Textarea(本组件不直接给业务用)。
- */
-export const TextFieldBase = forwardRef<TextInputRef, TextFieldBaseProps>(
-  function TextFieldBase(
-    {
-      multiline = false,
-      height = control.lg,
-      // [L-81] multiline minHeight 裸 96 → r(96),随设备缩放
-      minHeight = r(96),
+/** internal native ref type;公开 ref 一律用 TextFieldHandle。 */
+type NativeTextInputRef = ComponentRef<typeof TextInput>;
+
+/** Input / Textarea / Search 共享的严格输入 primitive — internal,不进公共 barrel。 */
+export const TextFieldBase = forwardRef<TextFieldHandle, TextFieldBaseProps>(
+  function TextFieldBase(props, forwardedRef): React.JSX.Element {
+    const {
+      multiline,
+      height,
+      minHeight,
       maxHeight,
+      searchLayout,
       leading,
       trailing,
       error,
@@ -37,29 +42,96 @@ export const TextFieldBase = forwardRef<TextInputRef, TextFieldBaseProps>(
       editable,
       containerStyle,
       value,
+      defaultValue,
+      onChangeText,
+      accessibilityState,
+      accessibilityRole,
+      placeholderTextColor: callerPlaceholder,
       onFocus,
       onBlur,
-      onChangeText,
       testID,
-      ...rest
-    },
-    ref
-  ): React.JSX.Element {
-    const c = useColors();
+      style: _style,
+      numberOfLines: _numberOfLines,
+      ['aria-disabled']: _ariaDisabled,
+      readOnly: _readOnly,
+      role: _role,
+      enterKeyHint: _enterKeyHint,
+      clearTextOnFocus: _clearTextOnFocus,
+      ...allowedNativeProps
+    } = props as TextFieldBaseProps & Record<string, unknown>;
+    const removedNativeAliasKey = Object.entries({
+      'style': _style,
+      'numberOfLines': _numberOfLines,
+      'aria-disabled': _ariaDisabled,
+      'readOnly': _readOnly,
+      'role': _role,
+      'enterKeyHint': _enterKeyHint,
+      'clearTextOnFocus': _clearTextOnFocus,
+    })
+      .filter(([, entry]) => entry !== undefined)
+      .map(([name]) => name)
+      .join(',');
+    const colors = useColors();
     const styles = useThemedStyles(makeStyles);
     const [focused, setFocused] = useState(false);
-    // [M-9] 内部镜像 state:非受控场景 value 不传,用 _mirror 做 hasValue 判断
-    const [_mirror, setMirror] = useState('');
-    // [M-9] filled 在受控 value 和内部镜像 state 之间取 hasValue,
-    // 保证非受控场景 filled 视觉态能正确响应用户输入,且受控用法行为不变
-    const filled =
-      value != null ? String(value).length > 0 : _mirror.length > 0;
-    const isEditable = disabled ? false : editable;
-    // [L-31] editable=false(非 disabled)时也应进入 disabled a11y state
-    const isDisabledA11y = disabled || editable === false;
+    const nativeRef = React.useRef<NativeTextInputRef>(null);
+    const scope = multiline ? 'Textarea' : 'Input';
+    const controller = useTextFieldValue(
+      {
+        value,
+        defaultValue,
+        onChangeText:
+          typeof onChangeText === 'function'
+            ? (onChangeText as (next: string) => void)
+            : undefined,
+      },
+      scope
+    );
+    const normalizedInputHeight = normalizeInputHeight(
+      height === undefined ? fixed.hitTarget : height
+    );
+    const normalizedTextareaHeights = normalizeTextareaHeights(
+      minHeight,
+      maxHeight
+    );
+    const sanitizedContainer = sanitizeTextFieldContainerStyle(containerStyle);
+    const effectiveEditable = disabled !== true && editable !== false;
+    const mergedAccessibilityState = {
+      ...accessibilityState,
+      disabled: !effectiveEditable,
+    };
+    const normalizedHeight = multiline
+      ? normalizedTextareaHeights.minHeight
+      : normalizedInputHeight.value;
+    const filled = controller.value.length > 0;
+    const diagnostics = [
+      ...normalizedInputHeight.diagnostics,
+      ...normalizedTextareaHeights.diagnostics,
+      ...sanitizedContainer.diagnostics,
+    ];
+    const diagnosticKey = diagnostics.join(',');
+
+    useEffect(() => {
+      if (diagnosticKey.length > 0) {
+        log.warn(`${scope}: 非法布局值(${diagnosticKey})已回退。`);
+      }
+    }, [diagnosticKey, scope]);
+    useEffect(() => {
+      if (removedNativeAliasKey.length > 0) {
+        log.warn(`${scope}: 已忽略受管原生 props(${removedNativeAliasKey})。`);
+      }
+    }, [removedNativeAliasKey, scope]);
+    useErrorAnnouncement(error);
+
+    useImperativeHandle(
+      forwardedRef,
+      () => ({
+        focus: () => nativeRef.current?.focus(),
+        blur: () => nativeRef.current?.blur(),
+      }),
+      []
+    );
 
-    // 视觉态优先级:error > focused > filled > idle。
-    // active 三态(focus/filled/error)共享 wrapActive 白底,各自只覆 borderColor 差量。
     const wrapStateStyles = error
       ? [styles.wrapActive, styles.wrapError]
       : focused
@@ -67,62 +139,95 @@ export const TextFieldBase = forwardRef<TextInputRef, TextFieldBaseProps>(
         : filled
           ? [styles.wrapActive, styles.wrapFilled]
           : [styles.wrapIdle];
+    const interactiveHeight =
+      searchLayout?.interactiveHeight ?? normalizedHeight;
 
     return (
       <View
-        style={[containerStyle, disabled && styles.containerDisabled]}
+        style={[
+          sanitizedContainer.style,
+          !effectiveEditable && styles.containerDisabled,
+          searchLayout !== undefined && !multiline && styles.rootCentered,
+          { minWidth: fixed.hitTarget, minHeight: normalizedHeight },
+        ]}
         testID={testID}
       >
         <View
           style={[
             styles.wrap,
             multiline && styles.wrapMultiline,
-            ...wrapStateStyles,
+            searchLayout === undefined && wrapStateStyles,
+            searchLayout !== undefined && styles.searchInteractiveRow,
             multiline
-              ? { minHeight, ...(maxHeight != null && { maxHeight }) }
-              : { height },
+              ? {
+                  minHeight: normalizedHeight,
+                  ...(normalizedTextareaHeights.maxHeight !== undefined && {
+                    maxHeight: normalizedTextareaHeights.maxHeight,
+                  }),
+                }
+              : { height: interactiveHeight },
           ]}
         >
-          {leading != null ? <View>{leading}</View> : null}
+          {searchLayout ? (
+            <View
+              pointerEvents="none"
+              style={[
+                styles.searchVisibleSurface,
+                ...wrapStateStyles,
+                {
+                  top: searchLayout.verticalInset,
+                  bottom: searchLayout.verticalInset,
+                },
+              ]}
+            />
+          ) : null}
+          <TextFieldSlot
+            slot={leading}
+            effectiveEditable={effectiveEditable}
+            testID={childTestID(testID, 'leading')}
+          />
           <TextInput
-            ref={ref}
-            {...rest}
-            editable={isEditable}
-            value={value}
-            onChangeText={(text) => {
-              // [M-9] 同步内部镜像,非受控场景 filled 视觉态依赖此 state
-              setMirror(text);
-              onChangeText?.(text);
-            }}
+            ref={nativeRef}
+            {...(allowedNativeProps as TextInputProps)}
+            value={controller.value}
+            onChangeText={controller.onChangeText}
+            editable={effectiveEditable}
             multiline={multiline}
-            onFocus={(e) => {
+            onFocus={(event) => {
               setFocused(true);
-              onFocus?.(e);
+              onFocus?.(event);
             }}
-            onBlur={(e) => {
+            onBlur={(event) => {
               setFocused(false);
-              onBlur?.(e);
+              onBlur?.(event);
             }}
             style={[
               styles.input,
               multiline && styles.inputMultiline,
-              // multiline:wrap 上下 padding 为 space[4]*2=20,input 内部 minHeight 减掉避免溢出
               multiline && {
-                minHeight: Math.max(0, minHeight - space[4] * 2),
+                minHeight: Math.max(0, normalizedHeight - space[4] * 2),
+              },
+              searchLayout !== undefined && {
+                minHeight: searchLayout.interactiveHeight,
               },
             ]}
-            placeholderTextColor={c.foregroundSubtle}
-            // [L-31] editable=false 并入 disabled a11y state,SR 能正确播报不可编辑
-            accessibilityState={isDisabledA11y ? { disabled: true } : undefined}
+            placeholderTextColor={callerPlaceholder ?? colors.foregroundSubtle}
+            accessibilityRole={accessibilityRole}
+            accessibilityState={mergedAccessibilityState}
             testID={childTestID(testID, 'input')}
           />
-          {trailing != null ? <View>{trailing}</View> : null}
+          <TextFieldSlot
+            slot={trailing}
+            effectiveEditable={effectiveEditable}
+            testID={childTestID(testID, 'trailing')}
+          />
         </View>
-        {/* [L-31] error Text 补 accessibilityLiveRegion="polite" —— 错误出现时 SR 自动播报 */}
         {error ? (
           <Text
             style={styles.errorMsg}
-            accessibilityLiveRegion="polite"
+            accessibilityLiveRegion={
+              Platform.OS === 'android' ? 'polite' : undefined
+            }
             testID={childTestID(testID, 'error')}
           >
             {error}

package/src/components/ui/TextField/TextFieldSlot.tsx

@@ -0,0 +1,91 @@
+import { useEffect } from 'react';
+import { Text, View } from 'react-native';
+import { Pressable } from 'react-native-gesture-handler';
+import { useColors, useThemedStyles } from '../../../theme';
+import { createLogger } from '../../../utils/logger';
+import { A11Y_HIDDEN_PROPS } from '../shared/a11y';
+import { Icon } from '../Icon';
+import { normalizeSlotIconSize, normalizeTextFieldSlot } from './normalize';
+import { makeStyles } from './styles';
+import type { TextFieldSlot as TextFieldSlotConfig } from './types';
+
+const log = createLogger('TextFieldSlot');
+
+type TextFieldSlotProps = {
+  slot: TextFieldSlotConfig | unknown;
+  effectiveEditable: boolean;
+  testID?: string;
+};
+
+/**
+ * 受控 slot renderer。展示内容与真实操作在这里分叉,避免未知 ReactNode 绕过
+ * 44pt action frame 或可访问名称约束。
+ */
+export function TextFieldSlot({
+  slot,
+  effectiveEditable,
+  testID,
+}: TextFieldSlotProps): React.JSX.Element | null {
+  const colors = useColors();
+  const styles = useThemedStyles(makeStyles);
+  const normalizedSlot = normalizeTextFieldSlot(slot);
+  const safeSlot = normalizedSlot.slot;
+  const iconSize =
+    safeSlot?.kind === 'icon'
+      ? normalizeSlotIconSize(safeSlot.size)
+      : undefined;
+  const iconDiagnosticKey = iconSize?.diagnostics.join(',') ?? '';
+  const slotDiagnosticKey = normalizedSlot.diagnostics.join(',');
+
+  useEffect(() => {
+    if (iconDiagnosticKey.length > 0) {
+      log.warn('slot.icon.size 非法，已回退为 18。');
+    }
+  }, [iconDiagnosticKey]);
+  useEffect(() => {
+    if (slotDiagnosticKey.length > 0) {
+      log.warn(`非法 TextField slot(${slotDiagnosticKey})已移除。`);
+    }
+  }, [slotDiagnosticKey]);
+
+  if (!safeSlot) return null;
+
+  switch (safeSlot.kind) {
+    case 'icon':
+      return (
+        <View {...A11Y_HIDDEN_PROPS} style={styles.slotDisplay} testID={testID}>
+          <Icon
+            name={safeSlot.icon}
+            size={iconSize?.value ?? 18}
+            color={safeSlot.color ?? colors.foregroundMuted}
+          />
+        </View>
+      );
+    case 'text':
+      return (
+        <Text
+          {...A11Y_HIDDEN_PROPS}
+          style={[styles.slotDisplay, styles.slotText]}
+          testID={testID}
+        >
+          {safeSlot.value}
+        </Text>
+      );
+    case 'action': {
+      const disabled = !effectiveEditable || safeSlot.disabled === true;
+      return (
+        <Pressable
+          onPress={disabled ? undefined : safeSlot.onPress}
+          disabled={disabled}
+          accessibilityRole="button"
+          accessibilityLabel={safeSlot.accessibilityLabel}
+          accessibilityState={{ disabled }}
+          style={styles.actionFrame}
+          testID={testID}
+        >
+          <Icon name={safeSlot.icon} size={18} color={colors.foregroundMuted} />
+        </Pressable>
+      );
+    }
+  }
+}

package/src/components/ui/TextField/normalize.ts

@@ -0,0 +1,280 @@
+import { StyleSheet } from 'react-native';
+import type { StyleProp, ViewStyle } from 'react-native';
+import { fixed } from '../../../theme';
+import { ICONS, type IconName } from '../../../icons';
+import { normalizeNonBlankText } from '../shared/accessibilityName';
+import type {
+  SearchFieldLayout,
+  TextFieldContainerStyle,
+  TextFieldSlot,
+} from './types';
+
+/**
+ * TextField 家族的**纯布局归一化** —— 无 React 依赖,可直接单测。
+ *
+ * 纪律与 Pulse 一致:非法值**整体回退默认值并记诊断**,不做 clamp、不做取整。
+ * 悄悄把 `height: 20` 夹成 44 会让调用方永远发现不了自己传了一个碰不到的输入框。
+ */
+
+/** slot 图标的默认与合法上界。18 是 body 字号下视觉平衡的取值;>32 会撑破 44pt frame。 */
+const DEFAULT_SLOT_ICON_SIZE = 18;
+const MAX_SLOT_ICON_SIZE = 32;
+/** Textarea 默认最小高度(约 5 行)。 */
+const DEFAULT_TEXTAREA_MIN_HEIGHT = 96;
+const DEFAULT_SEARCH_VISIBLE_HEIGHT = 36;
+
+/** 这六个字段会破坏 TextField 自持的最小命中框,一律从 containerStyle 剥离。 */
+const RESERVED_CONTAINER_KEYS = [
+  'height',
+  'minHeight',
+  'maxHeight',
+  'minWidth',
+  'maxWidth',
+  'overflow',
+] as const;
+
+const isFiniteAtLeast = (value: unknown, min: number): value is number =>
+  typeof value === 'number' && Number.isFinite(value) && value >= min;
+
+const isFiniteWithin = (
+  value: unknown,
+  min: number,
+  max: number
+): value is number =>
+  typeof value === 'number' &&
+  Number.isFinite(value) &&
+  value >= min &&
+  value <= max;
+
+export type NormalizedNumber = {
+  value: number;
+  diagnostics: readonly string[];
+};
+
+/** 单行高度 —— 不得低于 `fixed.hitTarget`(44pt),否则整行都碰不满一个手指。 */
+export function normalizeInputHeight(value: unknown): NormalizedNumber {
+  return isFiniteAtLeast(value, fixed.hitTarget)
+    ? { value, diagnostics: [] }
+    : { value: fixed.hitTarget, diagnostics: ['height'] };
+}
+
+export type NormalizedTextareaHeights = {
+  minHeight: number;
+  maxHeight: number | undefined;
+  diagnostics: readonly string[];
+};
+
+/** 多行高度 —— `maxHeight` 只有在有限且不小于归一化后的 `minHeight` 时才保留。 */
+export function normalizeTextareaHeights(
+  minHeight: unknown,
+  maxHeight: unknown
+): NormalizedTextareaHeights {
+  const diagnostics: string[] = [];
+  let safeMin: number;
+  if (minHeight === undefined) {
+    safeMin = DEFAULT_TEXTAREA_MIN_HEIGHT;
+  } else if (isFiniteAtLeast(minHeight, fixed.hitTarget)) {
+    safeMin = minHeight;
+  } else {
+    safeMin = DEFAULT_TEXTAREA_MIN_HEIGHT;
+    diagnostics.push('minHeight');
+  }
+  if (maxHeight === undefined) {
+    return { minHeight: safeMin, maxHeight: undefined, diagnostics };
+  }
+  // 注意用**归一化后**的 min 比较:min 被回退时 max 必须跟着重新判定,
+  // 否则会留下一个比实际 min 还小的 max,直接把内容压没。
+  if (isFiniteAtLeast(maxHeight, safeMin)) {
+    return { minHeight: safeMin, maxHeight, diagnostics };
+  }
+  diagnostics.push('maxHeight');
+  return { minHeight: safeMin, maxHeight: undefined, diagnostics };
+}
+
+/** slot 图标尺寸 —— 只接受有限的 `[1, 32]`。 */
+export function normalizeSlotIconSize(value: unknown): NormalizedNumber {
+  return isFiniteWithin(value, 1, MAX_SLOT_ICON_SIZE)
+    ? { value, diagnostics: [] }
+    : { value: DEFAULT_SLOT_ICON_SIZE, diagnostics: ['slot.size'] };
+}
+
+export type NormalizedTextFieldSlot = {
+  slot: TextFieldSlot | undefined;
+  diagnostics: readonly string[];
+};
+
+function isIconName(value: unknown): value is IconName {
+  return (
+    typeof value === 'string' &&
+    Object.prototype.hasOwnProperty.call(ICONS, value)
+  );
+}
+
+/** 未类型化 JS 必须完整匹配一个受支持分支，不能靠 discriminant 后 cast 绕过校验。 */
+export function normalizeTextFieldSlot(slot: unknown): NormalizedTextFieldSlot {
+  if (slot === undefined) {
+    return { slot: undefined, diagnostics: [] };
+  }
+  if (typeof slot !== 'object' || slot === null) {
+    return { slot: undefined, diagnostics: ['slot'] };
+  }
+  const candidate = slot as Record<string, unknown>;
+  switch (candidate.kind) {
+    case 'icon': {
+      const size =
+        typeof candidate.size === 'number' && Number.isFinite(candidate.size)
+          ? candidate.size
+          : undefined;
+      const color =
+        typeof candidate.color === 'string' ? candidate.color : undefined;
+      const hasValidSize = candidate.size === undefined || size !== undefined;
+      const hasValidColor =
+        candidate.color === undefined || color !== undefined;
+      if (!isIconName(candidate.icon) || !hasValidSize || !hasValidColor) {
+        return { slot: undefined, diagnostics: ['slot.icon'] };
+      }
+      return {
+        slot: {
+          kind: 'icon',
+          icon: candidate.icon,
+          ...(size !== undefined && { size }),
+          ...(color !== undefined && { color }),
+        },
+        diagnostics: [],
+      };
+    }
+    case 'text':
+      if (
+        typeof candidate.value !== 'string' &&
+        typeof candidate.value !== 'number'
+      ) {
+        return { slot: undefined, diagnostics: ['slot.text'] };
+      }
+      return {
+        slot: { kind: 'text', value: candidate.value },
+        diagnostics: [],
+      };
+    case 'action': {
+      const accessibilityLabel = normalizeNonBlankText(
+        candidate.accessibilityLabel
+      );
+      const hasValidDisabled =
+        candidate.disabled === undefined ||
+        typeof candidate.disabled === 'boolean';
+      const slotDisabled =
+        typeof candidate.disabled === 'boolean'
+          ? candidate.disabled
+          : undefined;
+      if (
+        !isIconName(candidate.icon) ||
+        typeof candidate.onPress !== 'function' ||
+        accessibilityLabel === undefined ||
+        !hasValidDisabled
+      ) {
+        return { slot: undefined, diagnostics: ['slot.action'] };
+      }
+      return {
+        slot: {
+          kind: 'action',
+          icon: candidate.icon,
+          onPress: candidate.onPress as () => void,
+          accessibilityLabel,
+          ...(slotDisabled !== undefined && { disabled: slotDisabled }),
+        },
+        diagnostics: [],
+      };
+    }
+    default:
+      return { slot: undefined, diagnostics: ['slot.kind'] };
+  }
+}
+
+export type NormalizedSearchLayout = SearchFieldLayout & {
+  diagnostics: readonly string[];
+};
+
+/** 搜索框的可见面可为 36pt,但承载输入/操作的实际行永远不得小于 44pt。 */
+export function normalizeSearchLayout(
+  interactiveHeight: unknown,
+  visibleHeight: unknown
+): NormalizedSearchLayout {
+  const diagnostics: string[] = [];
+  const safeInteractive = isFiniteAtLeast(interactiveHeight, fixed.hitTarget)
+    ? interactiveHeight
+    : fixed.hitTarget;
+  if (safeInteractive !== interactiveHeight) {
+    diagnostics.push('interactiveHeight');
+  }
+  const safeVisible =
+    typeof visibleHeight === 'number' &&
+    Number.isFinite(visibleHeight) &&
+    visibleHeight > 0 &&
+    visibleHeight <= safeInteractive
+      ? visibleHeight
+      : DEFAULT_SEARCH_VISIBLE_HEIGHT;
+  if (safeVisible !== visibleHeight) {
+    diagnostics.push('visibleHeight');
+  }
+  return {
+    interactiveHeight: safeInteractive,
+    visibleHeight: safeVisible,
+    verticalInset: (safeInteractive - safeVisible) / 2,
+    diagnostics,
+  };
+}
+
+export type SanitizedContainerStyle = {
+  style: TextFieldContainerStyle;
+  diagnostics: readonly string[];
+};
+
+export type SanitizedTextFieldWrapperProps = {
+  props: Record<string, unknown>;
+  diagnostics: readonly string[];
+};
+
+/**
+ * 公开 Input / Textarea 不允许未类型化 JS 覆盖内部 layout 开关。
+ *
+ * 返回新对象而不是 delete 原 props，既不改变调用方对象，也让 wrapper 能在安全 spread
+ * 后由可信边界写入自己的 `multiline`。
+ */
+export function sanitizeTextFieldWrapperProps(
+  props: Record<string, unknown>
+): SanitizedTextFieldWrapperProps {
+  const { multiline, searchLayout, ...safeProps } = props;
+  const diagnostics: string[] = [];
+  if (multiline !== undefined) {
+    diagnostics.push('multiline');
+  }
+  if (searchLayout !== undefined) {
+    diagnostics.push('searchLayout');
+  }
+  return { props: safeProps, diagnostics };
+}
+
+/**
+ * 剥掉 containerStyle 里会覆盖最小 frame 的六个字段。
+ *
+ * 先 `StyleSheet.flatten` 再解构到新对象 —— 绝不原地修改调用方对象或已注册的
+ * StyleSheet 条目(那会污染同一 sheet 的其他使用者)。
+ */
+export function sanitizeTextFieldContainerStyle(
+  style: StyleProp<ViewStyle> | undefined
+): SanitizedContainerStyle {
+  const flattened = (StyleSheet.flatten(style) ?? {}) as Record<
+    string,
+    unknown
+  >;
+  const reserved: readonly string[] = RESERVED_CONTAINER_KEYS;
+  const sanitized: Record<string, unknown> = {};
+  const diagnostics: string[] = [];
+  for (const [key, entry] of Object.entries(flattened)) {
+    if (reserved.includes(key)) {
+      diagnostics.push(key);
+      continue;
+    }
+    sanitized[key] = entry;
+  }
+  return { style: sanitized as TextFieldContainerStyle, diagnostics };
+}