@unif/react-native-design 0.31.3 → 0.32.1

package/src/components/ui/Pulse/constants.ts

@@ -0,0 +1,14 @@
+import type { PulseDefaults } from '../shared/pulse/types';
+
+export const PULSE_DEFAULTS: Readonly<PulseDefaults> = {
+  duration: 700,
+  delay: 0,
+  from: 0.6,
+  to: 1,
+};
+export const PULSE_DOT_DEFAULTS: Readonly<PulseDefaults> = {
+  duration: 700,
+  delay: 0,
+  from: 0.5,
+  to: 1,
+};

package/src/components/ui/Pulse/types.ts

@@ -1,6 +1,6 @@
 import type { StyleProp, ViewStyle } from 'react-native';
 
-export type PulseOptions = {
+export interface PulseOptions {
   /** 透明度下界（默认 0.6） */
   from?: number;
   /** 透明度上界（默认 1） */
@@ -9,20 +9,20 @@ export type PulseOptions = {
   duration?: number;
   /** 首次周期之前的延迟（默认 0） */
   delay?: number;
-};
+}
 
-export type PulseDotProps = PulseOptions & {
+export interface PulseDotProps extends PulseOptions {
   size?: number;
   color?: string;
   /** 容器附加样式(margin / position 等布局微调)。 */
   style?: StyleProp<ViewStyle>;
   /** E2E / 测试定位 */
   testID?: string;
-};
+}
 
-export type PulseProps = PulseOptions & {
+export interface PulseProps extends PulseOptions {
   /** 容器附加样式(margin / position 等布局微调)。 */
   style?: StyleProp<ViewStyle>;
   /** E2E / 测试定位 */
   testID?: string;
-};
+}

package/src/components/ui/Pulse/usePulse.ts

@@ -1,87 +1,10 @@
-import { useEffect, useMemo } from 'react';
 import { createLogger } from '../../../utils/logger';
-import { normalizePulseOptions } from './normalizePulseOptions';
-import type { PulseDefaults } from './normalizePulseOptions';
-import { usePulseDriver } from './usePulseDriver';
+import { usePulseAnimation } from '../shared/pulse/usePulseAnimation';
+import { PULSE_DEFAULTS } from './constants';
 import type { PulseOptions } from './types';
 
-/**
- * 在两个 opacity 值之间无限循环,返回可直接拼到 Animated.View 上的 style。
- *
- * 这是**唯一**的公共实现:参数校验、默认值与 dev 诊断全在这里完成,平台差异只下沉到
- * `usePulseDriver(.web).ts`。此前 native / web 各有一份 `usePulse`,两边各自读原始
- * props、各自解释默认值,web 侧还把未校验的 duration 直接喂给 `setInterval`。
- */
-
-const BASE_DEFAULTS: PulseDefaults = {
-  duration: 700,
-  delay: 0,
-  from: 0.6,
-  to: 1,
-};
-
-/** PulseDot / Skeleton 的默认值 —— 只有 from 更低,圆点 / 骨架淡到 0.5。 */
-export const DOT_DEFAULTS: PulseDefaults = {
-  duration: 700,
-  delay: 0,
-  from: 0.5,
-  to: 1,
-};
-
-// logger 在模块加载时一次性建好 —— render 期创建每次都会产生新对象。
-const pulseLog = createLogger('Pulse');
-const pulseDotLog = createLogger('PulseDot');
-const skeletonLog = createLogger('Skeleton');
-
-/** 诊断告警的固定 scope 集合。 */
-export type PulseScope = 'Pulse' | 'PulseDot' | 'Skeleton';
-
-function loggerForScope(scope: PulseScope) {
-  switch (scope) {
-    case 'Pulse':
-      return pulseLog;
-    case 'PulseDot':
-      return pulseDotLog;
-    case 'Skeleton':
-      return skeletonLog;
-  }
-}
-
-/** 内部:让 PulseDot / Skeleton 复用同一条归一化 + 诊断 + driver 链路。 */
-export function usePulseWithDefaults(
-  options: PulseOptions | undefined,
-  defaults: PulseDefaults,
-  scope: PulseScope
-) {
-  // 依赖列表**故意**拆到 primitive:options / defaults 对象每次 render 都可能是新引用
-  // (调用方常写内联字面量),直接依赖对象会让 memo 恒失效、并连带每帧重启 driver 的 effect。
-  // 这八个 primitive 就是归一化的全部输入,拆开后覆盖完整、无遗漏。
-  const normalized = useMemo(
-    () => normalizePulseOptions(options, defaults),
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-    [
-      options?.duration,
-      options?.delay,
-      options?.from,
-      options?.to,
-      defaults.duration,
-      defaults.delay,
-      defaults.from,
-      defaults.to,
-    ]
-  );
-  useEffect(() => {
-    if (typeof __DEV__ !== 'undefined' && __DEV__) {
-      for (const item of normalized.diagnostics) {
-        loggerForScope(scope).warn(
-          `${item.field}=${String(item.received)} 无效,已回退为 ${item.fallback}`
-        );
-      }
-    }
-  }, [normalized.diagnostics, scope]);
-  return usePulseDriver(normalized);
-}
+const log = createLogger('Pulse');
 
 export function usePulse(options: PulseOptions = {}) {
-  return usePulseWithDefaults(options, BASE_DEFAULTS, 'Pulse');
+  return usePulseAnimation(options, PULSE_DEFAULTS, log);
 }

package/src/components/ui/Skeleton/Skeleton.tsx

@@ -1,9 +1,13 @@
 import React from 'react';
 import Animated from 'react-native-reanimated';
-import { DOT_DEFAULTS, usePulseWithDefaults } from '../Pulse/usePulse';
+import { createLogger } from '../../../utils/logger';
+import { usePulseAnimation } from '../shared/pulse/usePulseAnimation';
+import { SKELETON_DEFAULTS } from './constants';
 import { r, useColors } from '../../../theme';
 import type { SkeletonProps } from './types';
 
+const log = createLogger('Skeleton');
+
 /**
  * 页面级加载占位骨架。3 个形状由 `shape` 切换。
  *
@@ -26,11 +30,7 @@ export function Skeleton({
   testID,
 }: SkeletonProps): React.JSX.Element {
   const c = useColors();
-  const animatedStyle = usePulseWithDefaults(
-    undefined,
-    DOT_DEFAULTS,
-    'Skeleton'
-  );
+  const animatedStyle = usePulseAnimation(undefined, SKELETON_DEFAULTS, log);
 
   // 按形状推默认尺寸 + 圆角;caller 显式传 width / height / radius 时 override
   const dim = (() => {

package/src/components/ui/Skeleton/constants.ts

@@ -0,0 +1,8 @@
+import type { PulseDefaults } from '../shared/pulse/types';
+
+export const SKELETON_DEFAULTS: Readonly<PulseDefaults> = {
+  duration: 700,
+  delay: 0,
+  from: 0.5,
+  to: 1,
+};

package/src/components/ui/Skeleton/types.ts

@@ -2,7 +2,7 @@ import type { DimensionValue, StyleProp, ViewStyle } from 'react-native';
 
 export type SkeletonShape = 'line' | 'rect' | 'circle';
 
-export type SkeletonProps = {
+export interface SkeletonProps {
   /** 形状,默认 'rect'。
    *  - 'line' → width 100% / height 11 / radius 3(文本占位)
    *  - 'rect' → width 100% / height 80 / radius 8(图片或卡片占位)
@@ -19,4 +19,4 @@ export type SkeletonProps = {
   style?: StyleProp<ViewStyle>;
   /** E2E / 测试定位 */
   testID?: string;
-};
+}

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

@@ -7,7 +7,7 @@ import React, {
 } from 'react';
 import { Platform, Text, TextInput, View } from 'react-native';
 import type { TextInputProps } from 'react-native';
-import { fixed, space, useColors, useThemedStyles } from '../../../theme';
+import { fixed, useColors, useThemedStyles } from '../../../theme';
 import { childTestID } from '../../../utils/testID';
 import { createLogger } from '../../../utils/logger';
 import {
@@ -20,6 +20,7 @@ import { TextFieldSlot } from './TextFieldSlot';
 import type { TextFieldBaseProps, TextFieldHandle } from './types';
 import { useErrorAnnouncement } from './useErrorAnnouncement';
 import { useTextFieldValue } from './useTextFieldValue';
+import { useMultilineLayout } from './useMultilineLayout';
 
 const log = createLogger('TextField');
 
@@ -49,6 +50,9 @@ export const TextFieldBase = forwardRef<TextFieldHandle, TextFieldBaseProps>(
       placeholderTextColor: callerPlaceholder,
       onFocus,
       onBlur,
+      onContentSizeChange,
+      onLayout,
+      scrollEnabled,
       testID,
       style: _style,
       numberOfLines: _numberOfLines,
@@ -94,6 +98,15 @@ export const TextFieldBase = forwardRef<TextFieldHandle, TextFieldBaseProps>(
       minHeight,
       maxHeight
     );
+    const multilineLayout = useMultilineLayout({
+      enabled: multiline,
+      value: controller.value,
+      minHeight: normalizedTextareaHeights.minHeight,
+      maxHeight: normalizedTextareaHeights.maxHeight,
+      fontSize: styles.input.fontSize,
+      placeholder: allowedNativeProps.placeholder as string | undefined,
+      inputRef: nativeRef,
+    });
     const sanitizedContainer = sanitizeTextFieldContainerStyle(containerStyle);
     const effectiveEditable = disabled !== true && editable !== false;
     const mergedAccessibilityState = {
@@ -193,6 +206,15 @@ export const TextFieldBase = forwardRef<TextFieldHandle, TextFieldBaseProps>(
             onChangeText={controller.onChangeText}
             editable={effectiveEditable}
             multiline={multiline}
+            onContentSizeChange={onContentSizeChange}
+            onLayout={(event) => {
+              if (multiline) multilineLayout.onLayout?.(event);
+              onLayout?.(event);
+            }}
+            scrollEnabled={
+              scrollEnabled ??
+              (multiline ? multilineLayout.scrollEnabled : undefined)
+            }
             onFocus={(event) => {
               setFocused(true);
               onFocus?.(event);
@@ -204,9 +226,11 @@ export const TextFieldBase = forwardRef<TextFieldHandle, TextFieldBaseProps>(
             style={[
               styles.input,
               multiline && styles.inputMultiline,
-              multiline && {
-                minHeight: Math.max(0, normalizedHeight - space[4] * 2),
-              },
+              multiline &&
+                (multilineLayout.scrollEnabled
+                  ? styles.inputScrolling
+                  : styles.inputClipped),
+              multiline && multilineLayout.inputStyle,
               searchLayout !== undefined && {
                 minHeight: searchLayout.interactiveHeight,
               },

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

@@ -0,0 +1,6 @@
+import { space } from '../../../theme';
+
+export const TEXT_FIELD_BORDER_WIDTH = 1;
+export const TEXTAREA_VERTICAL_PADDING = space[4];
+export const TEXTAREA_VERTICAL_INSET =
+  2 * (TEXTAREA_VERTICAL_PADDING + TEXT_FIELD_BORDER_WIDTH);

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

@@ -1,6 +1,10 @@
 import { StyleSheet } from 'react-native';
 import { fw, radius, space, type as t } from '../../../theme';
 import type { ColorTokens } from '../../../theme';
+import {
+  TEXTAREA_VERTICAL_PADDING,
+  TEXT_FIELD_BORDER_WIDTH,
+} from './constants';
 
 /** TextField primitive styles —— Input + Textarea 共享。 */
 export const makeStyles = (c: ColorTokens) =>
@@ -11,10 +15,10 @@ export const makeStyles = (c: ColorTokens) =>
       gap: space[3],
       paddingHorizontal: space[5],
       borderRadius: radius.md,
-      borderWidth: 1,
+      borderWidth: TEXT_FIELD_BORDER_WIDTH,
     },
     wrapMultiline: {
-      paddingVertical: space[4],
+      paddingVertical: TEXTAREA_VERTICAL_PADDING,
       alignItems: 'flex-start',
     },
     /** Search 的可见底色/边框绝不承载命中区域。 */
@@ -59,6 +63,8 @@ export const makeStyles = (c: ColorTokens) =>
     inputMultiline: {
       textAlignVertical: 'top' as const,
     },
+    inputScrolling: { overflow: 'scroll' },
+    inputClipped: { overflow: 'hidden' },
     slotDisplay: {
       alignItems: 'center',
       justifyContent: 'center',

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

@@ -1,4 +1,11 @@
-import type { StyleProp, TextInputProps, ViewStyle } from 'react-native';
+import type { ComponentRef, RefObject } from 'react';
+import type { TextInput } from 'react-native';
+import type {
+  StyleProp,
+  TextInputProps,
+  TextStyle,
+  ViewStyle,
+} from 'react-native';
 import type { IconName } from '../Icon';
 
 /**
@@ -7,18 +14,18 @@ import type { IconName } from '../Icon';
  * `defaultValue?: never` 让「同时传 value 和 defaultValue」在类型层就报错 ——
  * 那是最常见的受控/非受控混用写法,运行时表现为「defaultValue 被静默忽略」。
  */
-export type ControlledTextValueProps = {
+export interface ControlledTextValueProps {
   value: string;
   onChangeText: (value: string) => void;
   defaultValue?: never;
-};
+}
 
 /** 非受控:内部持值,`defaultValue` 只在首次 render 读一次。 */
-export type UncontrolledTextValueProps = {
+export interface UncontrolledTextValueProps {
   value?: never;
   defaultValue?: string;
   onChangeText?: (value: string) => void;
-};
+}
 
 /** internal —— 由 InputProps / TextareaProps / SearchProps 组合进公共类型。 */
 export type TextFieldValueProps =
@@ -31,10 +38,10 @@ export type TextFieldValueProps =
  * 为什么不暴露原生 TextInput —— `clear()` 会绕过值状态机(受控下把 UI 清空但调用方
  * state 不变),`setNativeProps()` 能直接改任意原生属性,两者都会让公共契约失效。
  */
-export type TextFieldHandle = {
+export interface TextFieldHandle {
   focus: () => void;
   blur: () => void;
-};
+}
 
 /**
  * 左右 slot 的可验证配置。**不接受任意 ReactNode** ——
@@ -67,14 +74,14 @@ export type TextFieldContainerStyle = Omit<
 >;
 
 /** internal:Search 把真实交互行与仅作视觉的 surface 明确分层。 */
-export type SearchFieldLayout = {
+export interface SearchFieldLayout {
   interactiveHeight: number;
   visibleHeight: number;
   verticalInset: number;
-};
+}
 
 /** TextField 家族共享的非值 props(内部)。 */
-export type TextFieldCommonProps = {
+export interface TextFieldCommonProps {
   /** 左侧 slot —— 图标 / 文本 / 带 handler 与名称的操作 */
   leading?: TextFieldSlot;
   /** 右侧 slot —— 图标 / 文本 / 带 handler 与名称的操作 */
@@ -85,7 +92,7 @@ export type TextFieldCommonProps = {
   disabled?: boolean;
   /** 外层容器样式;不接受会破坏最小 frame 的尺寸字段 */
   containerStyle?: StyleProp<TextFieldContainerStyle>;
-};
+}
 
 /**
  * 这些原生 TextInput props 从公共类型删除:
@@ -127,3 +134,26 @@ export type TextFieldBaseProps = Omit<TextInputProps, RemovedTextInputProps> &
     /** internal:Search 的 44pt interactive row + 36pt decorative surface。 */
     searchLayout?: SearchFieldLayout;
   };
+
+export interface MultilineLayoutInput {
+  enabled: boolean;
+  value: string;
+  minHeight: number;
+  maxHeight: number | undefined;
+  fontSize: number | undefined;
+  placeholder: string | undefined;
+  inputRef: RefObject<ComponentRef<typeof TextInput> | null>;
+}
+
+export interface MultilineLayout {
+  inputStyle: Pick<TextStyle, 'height' | 'minHeight' | 'maxHeight'>;
+  scrollEnabled: boolean;
+  onLayout?: TextInputProps['onLayout'];
+}
+
+/** RN Web 的公开 host ref 仅在平台实现内使用这两个 DOM 测量属性。 */
+export interface WebTextInputMeasurement {
+  scrollHeight: number;
+  scrollTop: number;
+  style: { height: string; minHeight: string };
+}

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

@@ -0,0 +1,20 @@
+import { TEXTAREA_VERTICAL_INSET } from './constants';
+import type { MultilineLayout, MultilineLayoutInput } from './types';
+
+/** 原生 Yoga 直接测量文本；固定 height 会阻断 iOS Fabric 的后续内容尺寸通知。 */
+export function useMultilineLayout({
+  minHeight,
+  maxHeight,
+}: MultilineLayoutInput): MultilineLayout {
+  return {
+    inputStyle: {
+      minHeight: Math.max(0, minHeight - TEXTAREA_VERTICAL_INSET),
+      maxHeight:
+        maxHeight === undefined
+          ? undefined
+          : Math.max(0, maxHeight - TEXTAREA_VERTICAL_INSET),
+    },
+    // 原生仅在内容溢出时滚动；min=max 时也不等待不会再变化的框高事件。
+    scrollEnabled: true,
+  };
+}

package/src/components/ui/TextField/useMultilineLayout.web.ts

@@ -0,0 +1,59 @@
+import { useCallback, useLayoutEffect, useState } from 'react';
+import { TEXTAREA_VERTICAL_INSET } from './constants';
+import type {
+  MultilineLayout,
+  MultilineLayoutInput,
+  WebTextInputMeasurement,
+} from './types';
+
+/** RNW 的 contentSize 使用 scrollHeight，固定高度会阻止缩短，须临时解除高度后测量。 */
+export function useMultilineLayout({
+  enabled,
+  value,
+  minHeight,
+  maxHeight,
+  fontSize,
+  placeholder,
+  inputRef,
+}: MultilineLayoutInput): MultilineLayout {
+  const [contentHeight, setContentHeight] = useState(0);
+  const [width, setWidth] = useState(0);
+  const minimum = Math.max(0, minHeight - TEXTAREA_VERTICAL_INSET);
+  const maximum =
+    maxHeight === undefined
+      ? Infinity
+      : Math.max(0, maxHeight - TEXTAREA_VERTICAL_INSET);
+  useLayoutEffect(() => {
+    if (!enabled || inputRef.current === null) return;
+    const node = inputRef.current as unknown as WebTextInputMeasurement;
+    const { height, minHeight: previousMinimum } = node.style;
+    const scrollTop = node.scrollTop;
+    node.style.height = '0px';
+    node.style.minHeight = '0px';
+    const measured = node.scrollHeight;
+    node.style.height = height;
+    node.style.minHeight = previousMinimum;
+    node.scrollTop = scrollTop;
+    if (Number.isFinite(measured)) setContentHeight(measured);
+  }, [
+    enabled,
+    value,
+    width,
+    fontSize,
+    placeholder,
+    minHeight,
+    maxHeight,
+    inputRef,
+  ]);
+  const onLayout = useCallback<NonNullable<MultilineLayout['onLayout']>>(
+    (event) => setWidth(event.nativeEvent.layout.width),
+    []
+  );
+  return {
+    inputStyle: {
+      height: Math.min(maximum, Math.max(minimum, contentHeight)),
+    },
+    scrollEnabled: contentHeight > maximum,
+    onLayout,
+  };
+}

package/src/components/ui/Textarea/types.ts

@@ -13,9 +13,12 @@ import type {
  */
 export type TextareaProps = Omit<TextInputProps, RemovedTextInputProps> &
   TextFieldCommonProps &
-  TextFieldValueProps & {
-    /** 最小高度，默认 96（约 5 行） */
-    minHeight?: number;
-    /** 最大高度（超过后内部滚动），默认不限制 */
-    maxHeight?: number;
-  };
+  TextFieldValueProps &
+  TextareaHeightProps;
+
+interface TextareaHeightProps {
+  /** 最小高度，默认 96（约 5 行） */
+  minHeight?: number;
+  /** 最大高度（超过后内部滚动），默认不限制 */
+  maxHeight?: number;
+}

package/src/components/ui/Thumbnail/Thumbnail.tsx

@@ -5,8 +5,11 @@ import { resolveImageSource } from '../../../utils/imageSource';
 import { createLogger } from '../../../utils/logger';
 import { ImageAttempt } from '../shared/ImageAttempt';
 import { A11Y_HIDDEN_PROPS } from '../shared/a11y';
-import { sanitizeThumbnailImageStyle } from './normalize';
-import { makeStyles, sizingFor } from './styles';
+import {
+  normalizeThumbnailDimensions,
+  sanitizeThumbnailImageStyle,
+} from './normalize';
+import { makeStyles } from './styles';
 import type { ThumbnailProps } from './types';
 
 const log = createLogger('Thumbnail');
@@ -22,6 +25,7 @@ export function Thumbnail(props: ThumbnailProps): React.JSX.Element {
     uri,
     source,
     size = 'md',
+    fallback,
     selected,
     containerStyle,
     imageStyle,
@@ -31,7 +35,8 @@ export function Thumbnail(props: ThumbnailProps): React.JSX.Element {
   } = props;
   const colors = useColors();
   const styles = useThemedStyles(makeStyles);
-  const dim = sizingFor(size);
+  const normalizedDimensions = normalizeThumbnailDimensions(size);
+  const dim = normalizedDimensions.dimensions;
   const hasUri = hasOwn(props, 'uri');
   const hasSource = hasOwn(props, 'source');
   const sourceCandidate =
@@ -43,6 +48,7 @@ export function Thumbnail(props: ThumbnailProps): React.JSX.Element {
   const resolvedSource = resolveImageSource(sourceCandidate);
   const sanitizedImageStyle = sanitizeThumbnailImageStyle(imageStyle);
   const diagnostics = [
+    ...normalizedDimensions.diagnostics,
     ...(resolvedSource === undefined ? ['source'] : []),
     ...sanitizedImageStyle.diagnostics.map((field) =>
       field === 'style' ? 'imageStyle' : `imageStyle.${field}`
@@ -72,16 +78,24 @@ export function Thumbnail(props: ThumbnailProps): React.JSX.Element {
     borderRadius: dim.borderRadius,
     borderColor: selected ? colors.primary : 'transparent',
   };
+  const fallbackContent =
+    fallback === undefined ? null : (
+      <View {...imageAccessibilityProps} style={styles.fallback}>
+        {fallback}
+      </View>
+    );
 
   return (
     <View style={containerStyle} testID={testID}>
       <View style={[styles.visualFrame, dim]}>
-        {resolvedSource === undefined ? null : (
+        {resolvedSource === undefined ? (
+          fallbackContent
+        ) : (
           <ImageAttempt
             {...imageAccessibilityProps}
             key={resolvedSource.key}
             source={resolvedSource.source}
-            fallback={null}
+            fallback={fallbackContent}
             style={[sanitizedImageStyle.style, StyleSheet.absoluteFill]}
             resizeMode={resizeMode}
           />

package/src/components/ui/Thumbnail/constants.ts

@@ -0,0 +1,24 @@
+import { r } from '../../../theme';
+import type { ThumbnailDimensions, ThumbnailSize } from './types';
+
+export const THUMBNAIL_DIMENSIONS: Readonly<
+  Record<ThumbnailSize, Required<ThumbnailDimensions>>
+> = {
+  sm: { width: r(64), height: r(40), borderRadius: r(6) },
+  md: { width: r(113), height: r(67), borderRadius: r(8) },
+  lg: { width: r(160), height: r(96), borderRadius: r(10) },
+};
+
+export const RESERVED_IMAGE_STYLE_KEYS = [
+  'position',
+  'top',
+  'right',
+  'bottom',
+  'left',
+  'width',
+  'height',
+  'minWidth',
+  'minHeight',
+  'maxWidth',
+  'maxHeight',
+] as const;

package/src/components/ui/Thumbnail/index.ts

@@ -1,5 +1,6 @@
 export { Thumbnail } from './Thumbnail';
 export type {
+  ThumbnailDimensions,
   ThumbnailImageStyle,
   ThumbnailProps,
   ThumbnailSize,

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

@@ -1,25 +1,44 @@
 import { StyleSheet } from 'react-native';
 import type { StyleProp } from 'react-native';
-import type { ThumbnailImageStyle } from './types';
+import type {
+  NormalizedThumbnailDimensions,
+  SanitizedThumbnailImageStyle,
+  ThumbnailImageStyle,
+} from './types';
+import { RESERVED_IMAGE_STYLE_KEYS, THUMBNAIL_DIMENSIONS } from './constants';
 
-const RESERVED_IMAGE_STYLE_KEYS = [
-  'position',
-  'top',
-  'right',
-  'bottom',
-  'left',
-  'width',
-  'height',
-  'minWidth',
-  'minHeight',
-  'maxWidth',
-  'maxHeight',
-] as const;
-
-type SanitizedThumbnailImageStyle = {
-  style: ThumbnailImageStyle;
-  diagnostics: readonly string[];
-};
+export function normalizeThumbnailDimensions(
+  size: unknown
+): NormalizedThumbnailDimensions {
+  if (size === undefined || size === 'sm' || size === 'md' || size === 'lg') {
+    return { dimensions: THUMBNAIL_DIMENSIONS[size ?? 'md'], diagnostics: [] };
+  }
+  if (typeof size === 'object' && size !== null && !Array.isArray(size)) {
+    const { width, height, borderRadius } = size as Record<string, unknown>;
+    if (
+      typeof width === 'number' &&
+      Number.isFinite(width) &&
+      width > 0 &&
+      typeof height === 'number' &&
+      Number.isFinite(height) &&
+      height > 0 &&
+      (borderRadius === undefined ||
+        (typeof borderRadius === 'number' &&
+          Number.isFinite(borderRadius) &&
+          borderRadius >= 0))
+    ) {
+      return {
+        dimensions: {
+          width,
+          height,
+          borderRadius: borderRadius ?? THUMBNAIL_DIMENSIONS.md.borderRadius,
+        },
+        diagnostics: [],
+      };
+    }
+  }
+  return { dimensions: THUMBNAIL_DIMENSIONS.md, diagnostics: ['size'] };
+}
 
 function invalidStyle(): SanitizedThumbnailImageStyle {
   return { style: {}, diagnostics: ['style'] };