@wix/patterns-fields 1.87.0 → 1.89.0

package/src/components/address/input/address-input.st.css.ts

@@ -5,7 +5,7 @@ import { classesRuntime, statesRuntime } from "../../../stylable-esm-runtime.js"
 
 
 
-var _namespace_ = "addressinput1180413843";
+var _namespace_ = "addressinput3855729996";
 var _style_ = classesRuntime.bind(null, _namespace_);
 
 export var cssStates = statesRuntime.bind(null, _namespace_);
@@ -13,7 +13,7 @@ export var style: import("@stylable/runtime").STFunction = _style_;
 export var st: import("@stylable/runtime").STFunction = _style_;
 
 export var namespace = _namespace_;
-export var classes = {"root":"addressinput1180413843__root","tableAddressInput":"addressinput1180413843__tableAddressInput"};
+export var classes = {"root":"addressinput3855729996__root","tableAddressInput":"addressinput3855729996__tableAddressInput"};
 export var keyframes = {}; 
 export var layers = {};
 export var containers = {};

package/src/components/audio/actions/actions-menu/actions-menu.st.css.ts

@@ -5,7 +5,7 @@ import { classesRuntime, statesRuntime } from "../../../../stylable-esm-runtime.
 
 
 
-var _namespace_ = "actionsmenu2383203063";
+var _namespace_ = "actionsmenu1397751256";
 var _style_ = classesRuntime.bind(null, _namespace_);
 
 export var cssStates = statesRuntime.bind(null, _namespace_);
@@ -13,7 +13,7 @@ export var style: import("@stylable/runtime").STFunction = _style_;
 export var st: import("@stylable/runtime").STFunction = _style_;
 
 export var namespace = _namespace_;
-export var classes = {"root":"actionsmenu2383203063__root","action":"actionsmenu2383203063__action"};
+export var classes = {"root":"actionsmenu1397751256__root","action":"actionsmenu1397751256__action"};
 export var keyframes = {}; 
 export var layers = {};
 export var containers = {};

package/src/components/audio/audio-field/controlled-audio.uni.driver.ts

@@ -0,0 +1,35 @@
+import { UniDriver } from '@wix/wix-ui-test-utils/unidriver';
+import { AddItemUniDriver } from '@wix/design-system/dist/testkit/unidriver';
+
+import { baseUniDriverFactory } from '../../../testkit/base-driver';
+
+export function ControlledAudioInputUniDriver(
+  base: UniDriver,
+  body: UniDriver,
+) {
+  // The dataHook sits on the AddItem in the empty state and on the wrapper Box
+  // in the filled one, so `base` is either.
+  const addItem = AddItemUniDriver(base, body);
+  const moreButton = base.$('[data-hook="fromAudioInput.button.more"]');
+  const deleteAction = body.$('[data-hook="fromAudioInput.button.delete"]');
+  const replaceAction = body.$('[data-hook="fromAudioInput.button.replace"]');
+
+  const isDisabled = async (element: UniDriver) =>
+    (await element.attr('disabled')) !== null ||
+    (await element.attr('aria-disabled')) === 'true';
+
+  return {
+    ...baseUniDriverFactory(base),
+    getAddButtonText: () => base.text(),
+    clickAddButton: () => addItem.click(),
+    isAddButtonFocused: () => addItem.isFocused(),
+    getAudioName: () => base.$('[data-hook="fromAudioInput.audioName"]').text(),
+    audioPlayerExists: () =>
+      base.$('[data-hook="fromAudioInput.player"]').exists(),
+    clickMore: () => moreButton.click(),
+    clickDelete: () => deleteAction.click(),
+    clickReplace: () => replaceAction.click(),
+    isDeleteDisabled: () => isDisabled(deleteAction),
+    isReplaceDisabled: () => isDisabled(replaceAction),
+  };
+}

package/src/components/audio/audio-field/form-audio-field.st.css.ts

@@ -5,7 +5,7 @@ import { classesRuntime, statesRuntime } from "../../../stylable-esm-runtime.js"
 
 
 
-var _namespace_ = "formaudiofield3511882057";
+var _namespace_ = "formaudiofield3743157660";
 var _style_ = classesRuntime.bind(null, _namespace_);
 
 export var cssStates = statesRuntime.bind(null, _namespace_);
@@ -13,7 +13,7 @@ export var style: import("@stylable/runtime").STFunction = _style_;
 export var st: import("@stylable/runtime").STFunction = _style_;
 
 export var namespace = _namespace_;
-export var classes = {"root":"formaudiofield3511882057__root","addItem":"formaudiofield3511882057__addItem","mediaTitle":"formaudiofield3511882057__mediaTitle"};
+export var classes = {"root":"formaudiofield3743157660__root","addItem":"formaudiofield3743157660__addItem","mediaTitle":"formaudiofield3743157660__mediaTitle"};
 export var keyframes = {}; 
 export var layers = {};
 export var containers = {};

package/src/components/audio/audio-field/form-audio-field.tsx

@@ -9,6 +9,7 @@ import { useMergedRef, useTranslations, useWithCallback } from '../../../hooks';
 import { getMediaTitle, MEDIA_TYPES } from '../../../utils';
 
 import { Z_INDEX_MODAL_POPOVER } from '../../common';
+import type { ControlledInputProps } from '../../../types/controlled-input';
 import type { FormMediaControlProps } from '../../media-control';
 import { useMediaControl, useMediaHandlers } from '../../media-control';
 import { MediaLoader } from '../../media-loader';
@@ -17,11 +18,21 @@ import { buildAudioActions } from '../actions/audio-actions';
 
 import { style, classes } from './form-audio-field.st.css.js';
 
-export const FormAudioField: FC<FormMediaControlProps> = ({
+export interface FormAudioFieldProps extends FormMediaControlProps {
+  /**
+   * Fires when the media manager closes, whether or not a file was picked.
+   * A media field has no text control to blur, so the picker closing is its
+   * blur signal.
+   */
+  onBlur?: () => void;
+}
+
+export const FormAudioField: FC<FormAudioFieldProps> = ({
   data,
   onChange: onChangeAudio,
   onClear: onClearAudio,
   onInput,
+  onBlur,
   autoFocus,
   readOnly,
   invalid,
@@ -44,6 +55,7 @@ export const FormAudioField: FC<FormMediaControlProps> = ({
     readOnly,
     inputRef,
     viewRef,
+    onBlur,
   });
 
   const { handleReplace, handleDownload, handleDelete } = useMediaHandlers({
@@ -143,3 +155,31 @@ export const FormAudioField: FC<FormMediaControlProps> = ({
     </Box>
   );
 };
+
+export type ControlledAudioInputProps = ControlledInputProps<
+  string | undefined
+>;
+
+export const ControlledAudioInput: FC<ControlledAudioInputProps> = ({
+  data,
+  onChange,
+  onBlur,
+  readOnly,
+  autoFocus,
+  invalid,
+  dataHook,
+}) => (
+  <FormAudioField
+    data={data}
+    onChange={onChange}
+    // FormAudioField reports deletion through onClear, not onChange.
+    onClear={() => onChange(undefined)}
+    onBlur={onBlur}
+    readOnly={readOnly}
+    autoFocus={autoFocus}
+    invalid={invalid}
+    dataHook={dataHook}
+  />
+);
+
+ControlledAudioInput.displayName = 'ControlledAudioInput';

package/src/components/audio/audio-player/audio-player.st.css.ts

@@ -5,7 +5,7 @@ import { classesRuntime, statesRuntime } from "../../../stylable-esm-runtime.js"
 
 
 
-var _namespace_ = "audioplayer3608168487";
+var _namespace_ = "audioplayer2787828225";
 var _style_ = classesRuntime.bind(null, _namespace_);
 
 export var cssStates = statesRuntime.bind(null, _namespace_);
@@ -13,7 +13,7 @@ export var style: import("@stylable/runtime").STFunction = _style_;
 export var st: import("@stylable/runtime").STFunction = _style_;
 
 export var namespace = _namespace_;
-export var classes = {"root":"audioplayer3608168487__root"};
+export var classes = {"root":"audioplayer2787828225__root"};
 export var keyframes = {}; 
 export var layers = {};
 export var containers = {};

package/src/components/color-view/cell-color-view.st.css.ts

@@ -5,7 +5,7 @@ import { classesRuntime, statesRuntime } from "../../stylable-esm-runtime.js";
 
 
 
-var _namespace_ = "cellcolorview2388263273";
+var _namespace_ = "cellcolorview4225418284";
 var _style_ = classesRuntime.bind(null, _namespace_);
 
 export var cssStates = statesRuntime.bind(null, _namespace_);
@@ -13,7 +13,7 @@ export var style: import("@stylable/runtime").STFunction = _style_;
 export var st: import("@stylable/runtime").STFunction = _style_;
 
 export var namespace = _namespace_;
-export var classes = {"root":"cellcolorview2388263273__root","hashPrefix":"cellcolorview2388263273__hashPrefix"};
+export var classes = {"root":"cellcolorview4225418284__root","hashPrefix":"cellcolorview4225418284__hashPrefix"};
 export var keyframes = {}; 
 export var layers = {};
 export var containers = {};

package/src/components/color-view/color-view.st.css.ts

@@ -5,7 +5,7 @@ import { classesRuntime, statesRuntime } from "../../stylable-esm-runtime.js";
 
 
 
-var _namespace_ = "colorview3869873986";
+var _namespace_ = "colorview3472694465";
 var _style_ = classesRuntime.bind(null, _namespace_);
 
 export var cssStates = statesRuntime.bind(null, _namespace_);
@@ -13,7 +13,7 @@ export var style: import("@stylable/runtime").STFunction = _style_;
 export var st: import("@stylable/runtime").STFunction = _style_;
 
 export var namespace = _namespace_;
-export var classes = {"root":"colorview3869873986__root","view":"colorview3869873986__view","fillPreview":"colorview3869873986__fillPreview"};
+export var classes = {"root":"colorview3472694465__root","view":"colorview3472694465__view","fillPreview":"colorview3472694465__fillPreview"};
 export var keyframes = {}; 
 export var layers = {};
 export var containers = {};

package/src/components/controlled-input.uni.driver.ts

@@ -13,7 +13,10 @@ import {
   CalendarPopoverUniDriver,
   InlineCalendarPopoverUniDriver,
 } from '../testkit/popover-driver';
+import { ControlledAudioInputUniDriver } from './audio/audio-field/controlled-audio.uni.driver';
 import { DateTimeInputUniDriver } from './datetime-input/controlled-date-time-input.uni.driver';
+import { ControlledImageInputUniDriver } from './image/controlled-image.uni.driver';
+import { ControlledVideoInputUniDriver } from './video/controlled-video.uni.driver';
 
 export function ControlledInputUniDriver(base: UniDriver, body: UniDriver) {
   const datePicker = DatePickerUniDriver(base, body);
@@ -30,5 +33,8 @@ export function ControlledInputUniDriver(base: UniDriver, body: UniDriver) {
     radioGroup: RadioGroupUniDriver(base, body),
     calendarPopover: CalendarPopoverUniDriver(datePicker, body),
     inlineCalendarPopover: InlineCalendarPopoverUniDriver(base),
+    audio: ControlledAudioInputUniDriver(base, body),
+    image: ControlledImageInputUniDriver(base, body),
+    video: ControlledVideoInputUniDriver(base, body),
   };
 }

package/src/components/delete-dialog/delete-dialog.st.css.ts

@@ -5,7 +5,7 @@ import { classesRuntime, statesRuntime } from "../../stylable-esm-runtime.js";
 
 
 
-var _namespace_ = "deletedialog1056046943";
+var _namespace_ = "deletedialog3903000196";
 var _style_ = classesRuntime.bind(null, _namespace_);
 
 export var cssStates = statesRuntime.bind(null, _namespace_);
@@ -13,7 +13,7 @@ export var style: import("@stylable/runtime").STFunction = _style_;
 export var st: import("@stylable/runtime").STFunction = _style_;
 
 export var namespace = _namespace_;
-export var classes = {"root":"deletedialog1056046943__root","layout":"deletedialog1056046943__layout"};
+export var classes = {"root":"deletedialog3903000196__root","layout":"deletedialog3903000196__layout"};
 export var keyframes = {}; 
 export var layers = {};
 export var containers = {};

package/src/components/document/form-document-field.st.css.ts

@@ -5,7 +5,7 @@ import { classesRuntime, statesRuntime } from "../../stylable-esm-runtime.js";
 
 
 
-var _namespace_ = "formdocumentfield2151681735";
+var _namespace_ = "formdocumentfield3549365286";
 var _style_ = classesRuntime.bind(null, _namespace_);
 
 export var cssStates = statesRuntime.bind(null, _namespace_);
@@ -13,7 +13,7 @@ export var style: import("@stylable/runtime").STFunction = _style_;
 export var st: import("@stylable/runtime").STFunction = _style_;
 
 export var namespace = _namespace_;
-export var classes = {"root":"formdocumentfield2151681735__root","viewWrapper":"formdocumentfield2151681735__viewWrapper","textWidth":"formdocumentfield2151681735__textWidth","documentLoader":"formdocumentfield2151681735__documentLoader","addDocument":"formdocumentfield2151681735__addDocument","addItemWrapper":"formdocumentfield2151681735__addItemWrapper"};
+export var classes = {"root":"formdocumentfield3549365286__root","viewWrapper":"formdocumentfield3549365286__viewWrapper","textWidth":"formdocumentfield3549365286__textWidth","documentLoader":"formdocumentfield3549365286__documentLoader","addDocument":"formdocumentfield3549365286__addDocument","addItemWrapper":"formdocumentfield3549365286__addItemWrapper"};
 export var keyframes = {}; 
 export var layers = {};
 export var containers = {};

package/src/components/exclamation/exclamation.st.css.ts

@@ -5,7 +5,7 @@ import { classesRuntime, statesRuntime } from "../../stylable-esm-runtime.js";
 
 
 
-var _namespace_ = "exclamation929712031";
+var _namespace_ = "exclamation627976924";
 var _style_ = classesRuntime.bind(null, _namespace_);
 
 export var cssStates = statesRuntime.bind(null, _namespace_);
@@ -13,7 +13,7 @@ export var style: import("@stylable/runtime").STFunction = _style_;
 export var st: import("@stylable/runtime").STFunction = _style_;
 
 export var namespace = _namespace_;
-export var classes = {"root":"exclamation929712031__root","exclamation":"exclamation929712031__exclamation","actions":"exclamation929712031__actions","action":"exclamation929712031__action"};
+export var classes = {"root":"exclamation627976924__root","exclamation":"exclamation627976924__exclamation","actions":"exclamation627976924__actions","action":"exclamation627976924__action"};
 export var keyframes = {}; 
 export var layers = {};
 export var containers = {};

package/src/components/field-validation-settings/field-validation-settings-input.tsx

@@ -15,6 +15,7 @@ import { v4 as uuid } from 'uuid';
 import type { ControlledInputProps } from '../../types/controlled-input';
 import type {
   CharactersLimitFieldValidationRuleConfig,
+  FieldValidationRule,
   FieldValidationRuleConfig,
   FieldValidationSettingsValue,
   PatternFieldValidationRuleConfig,
@@ -29,6 +30,8 @@ export interface FieldValidationSettingsInputProps
     'autoFocus' | 'onBlur'
   > {
   rules: readonly FieldValidationRuleConfig[];
+  /** Rules the caller has fixed and the user can't toggle, independent of `readOnly`. */
+  disabledRules?: readonly FieldValidationRule[];
 }
 
 interface RuleToggleProps {
@@ -73,7 +76,10 @@ export const FieldValidationSettingsInput = ({
   invalid,
   dataHook = 'field-validation-settings',
   rules,
+  disabledRules,
 }: FieldValidationSettingsInputProps) => {
+  const isRuleDisabled = (rule: FieldValidationRule) =>
+    Boolean(readOnly) || Boolean(disabledRules?.includes(rule));
   const supportedRules = rules.map(({ type }) => type);
   const violations = getFieldValidationSettingsViolations(data, supportedRules);
   const supportsSpecificValues = rules.some(
@@ -102,7 +108,7 @@ export const FieldValidationSettingsInput = ({
       key="required"
       dataHook="field-validation-required"
       checked={Boolean(data.required)}
-      disabled={readOnly}
+      disabled={isRuleDisabled('required')}
       label={rule.label}
       infoContent={rule.tooltip}
       onChange={() => update({ required: !data.required })}
@@ -135,7 +141,10 @@ export const FieldValidationSettingsInput = ({
         <RuleToggle
           dataHook="field-validation-characters-limit"
           checked={hasCharactersLimit}
-          disabled={readOnly || (hasSpecificValues && !hasCharactersLimit)}
+          disabled={
+            isRuleDisabled('charactersLimit') ||
+            (hasSpecificValues && !hasCharactersLimit)
+          }
           label={rule.label}
           infoContent={rule.tooltip}
           onChange={() =>
@@ -150,7 +159,7 @@ export const FieldValidationSettingsInput = ({
                   dataHook="field-validation-min-characters"
                   size="small"
                   value={data.charactersLimit?.min}
-                  disabled={readOnly}
+                  disabled={isRuleDisabled('charactersLimit')}
                   status={
                     hasUnattributedInvalidState || minViolation
                       ? 'error'
@@ -184,7 +193,7 @@ export const FieldValidationSettingsInput = ({
                   dataHook="field-validation-max-characters"
                   size="small"
                   value={data.charactersLimit?.max}
-                  disabled={readOnly}
+                  disabled={isRuleDisabled('charactersLimit')}
                   status={
                     hasUnattributedInvalidState ||
                     maxOutOfBoundsViolation ||
@@ -227,7 +236,8 @@ export const FieldValidationSettingsInput = ({
         dataHook="field-validation-specific-values"
         checked={hasSpecificValues}
         disabled={
-          readOnly || ((hasCharactersLimit || hasPattern) && !hasSpecificValues)
+          isRuleDisabled('specificValues') ||
+          ((hasCharactersLimit || hasPattern) && !hasSpecificValues)
         }
         label={rule.label}
         infoContent={rule.tooltip}
@@ -251,7 +261,7 @@ export const FieldValidationSettingsInput = ({
                     dataHook={`field-validation-specific-value-${index}`}
                     size="small"
                     value={option.value}
-                    disabled={readOnly}
+                    disabled={isRuleDisabled('specificValues')}
                     status={
                       optionViolation || hasUnattributedInvalidState
                         ? 'error'
@@ -280,7 +290,7 @@ export const FieldValidationSettingsInput = ({
                     dataHook={`field-validation-specific-value-remove-${index}`}
                     size="tiny"
                     priority="secondary"
-                    disabled={readOnly}
+                    disabled={isRuleDisabled('specificValues')}
                     ariaLabel={rule.removeButton}
                     onClick={() =>
                       update({
@@ -301,7 +311,7 @@ export const FieldValidationSettingsInput = ({
               dataHook="field-validation-specific-value-add"
               size="small"
               prefixIcon={<AddSmall />}
-              disabled={readOnly}
+              disabled={isRuleDisabled('specificValues')}
               onClick={() =>
                 update({
                   specificValues: [
@@ -335,7 +345,9 @@ export const FieldValidationSettingsInput = ({
         <RuleToggle
           dataHook="field-validation-pattern"
           checked={hasPattern}
-          disabled={readOnly || (hasSpecificValues && !hasPattern)}
+          disabled={
+            isRuleDisabled('pattern') || (hasSpecificValues && !hasPattern)
+          }
           label={rule.label}
           infoContent={rule.tooltip}
           onChange={() => update({ pattern: hasPattern ? undefined : '' })}
@@ -346,7 +358,7 @@ export const FieldValidationSettingsInput = ({
               dataHook="field-validation-pattern-input"
               size="small"
               value={data.pattern}
-              disabled={readOnly}
+              disabled={isRuleDisabled('pattern')}
               status={
                 hasUnattributedInvalidState || invalidPatternViolation
                   ? 'error'

package/src/components/highlighted-text/highlighted-text.st.css.ts

@@ -5,7 +5,7 @@ import { classesRuntime, statesRuntime } from "../../stylable-esm-runtime.js";
 
 
 
-var _namespace_ = "highlightedtext3600485196";
+var _namespace_ = "highlightedtext3674572764";
 var _style_ = classesRuntime.bind(null, _namespace_);
 
 export var cssStates = statesRuntime.bind(null, _namespace_);
@@ -13,8 +13,8 @@ export var style: import("@stylable/runtime").STFunction = _style_;
 export var st: import("@stylable/runtime").STFunction = _style_;
 
 export var namespace = _namespace_;
-export var classes = {"root":"highlightedtext3600485196__root","substring":"highlightedtext3600485196__substring"};
-export var keyframes = {"highlighted":"highlightedtext3600485196__highlighted","highlighted-match":"highlightedtext3600485196__highlighted-match"}; 
+export var classes = {"root":"highlightedtext3674572764__root","substring":"highlightedtext3674572764__substring"};
+export var keyframes = {"highlighted":"highlightedtext3674572764__highlighted","highlighted-match":"highlightedtext3674572764__highlighted-match"}; 
 export var layers = {};
 export var containers = {};
 export var stVars = {}; 

package/src/components/image/controlled-image.uni.driver.ts

@@ -0,0 +1,30 @@
+import { UniDriver } from '@wix/wix-ui-test-utils/unidriver';
+import {
+  AddItemUniDriver,
+  ImageViewerUniDriver,
+} from '@wix/design-system/dist/testkit/unidriver';
+
+export function ControlledImageInputUniDriver(
+  base: UniDriver,
+  body: UniDriver,
+) {
+  const imageViewer = ImageViewerUniDriver(base, body);
+  // `add-image` is ImageViewer's own hook for its empty-state AddItem.
+  const addItem = AddItemUniDriver(base.$('[data-hook="add-image"]'), body);
+  const addButton = base.$('[data-hook="add-image"] [data-hook="additem"]');
+  const currentImage = base.$('[data-hook="image-viewer-current-image"]');
+
+  return {
+    ...imageViewer,
+    clickAddButton: () => imageViewer.clickAdd(),
+    isAddButtonFocused: () => addItem.isFocused(),
+    isAddButtonDisabled: async () =>
+      (await addButton.attr('disabled')) !== null,
+    containsFocus: async () =>
+      (await base.getNative()).contains(document.activeElement),
+    // ImageViewer hides its edit affordances behind a loader until the image
+    // loads, and jsdom never fires that event on its own.
+    simulateImageLoad: async () =>
+      (await currentImage.getNative()).dispatchEvent(new Event('load')),
+  };
+}

package/src/components/image/form-image-field.tsx

@@ -0,0 +1,124 @@
+import type { FC } from 'react';
+import React from 'react';
+
+import { Box, ImageViewer } from '@wix/design-system';
+import { useIsMobile, useWixPatternsContainer } from '@wix/bex-core/react';
+
+import type { ControlledInputProps } from '../../types/controlled-input';
+import { useMergedRef, useWithCallback } from '../../hooks';
+import { getImageUrl } from '../../utils/get-image-url';
+import { MEDIA_HEIGHT, MEDIA_MAX_WIDTH } from '../../utils/media-constants';
+import { MEDIA_TYPES } from '../../utils';
+import type { FormMediaControlProps } from '../media-control';
+import { useMediaControl } from '../media-control';
+
+interface ImageViewerActions {
+  focus: () => void;
+}
+
+// `invalid` is not part of this contract. ImageViewer has no error prop; it
+// takes its error styling from the enclosing WDS FormField's status context.
+// To show an error, render the field inside a FormField with status="error".
+export interface FormImageFieldProps
+  extends Omit<FormMediaControlProps, 'invalid'> {
+  /**
+   * Fires when the media manager closes, whether or not a file was picked.
+   * A media field has no text control to blur, so the picker closing is its
+   * blur signal.
+   */
+  onBlur?: () => void;
+}
+
+export const FormImageField: FC<FormImageFieldProps> = ({
+  data,
+  onChange: onChangeImage,
+  onClear: onClearImage,
+  onInput,
+  onBlur,
+  readOnly,
+  autoFocus,
+  dataHook,
+  inputRef: forwardedRef,
+}) => {
+  const { translate: t } = useWixPatternsContainer();
+  const isMobile = useIsMobile();
+
+  const onChange = useWithCallback(onChangeImage, onInput);
+  const onClear = useWithCallback(onClearImage, onInput);
+
+  const [inputRef, setInputRef] =
+    useMergedRef<ImageViewerActions>(forwardedRef);
+
+  const { callMedia, onMediaLoad } = useMediaControl({
+    mediaType: MEDIA_TYPES.IMAGE,
+    value: data,
+    onChange,
+    autoFocus,
+    readOnly,
+    onBlur,
+    inputRef,
+    // The focus target is hidden behind ImageViewer's loader until the image
+    // arrives, so focusing has to wait for onImageLoad.
+    initialLoading: true,
+  });
+
+  const canEdit = !isMobile && !readOnly;
+
+  return (
+    <Box width="100%" maxWidth={MEDIA_MAX_WIDTH}>
+      <ImageViewer
+        // ImageViewer keeps its focus node on whichever button is live, so
+        // one ref serves both the empty and filled states.
+        ref={setInputRef}
+        imageUrl={data && getImageUrl(data)}
+        dataHook={dataHook}
+        onImageLoad={onMediaLoad}
+        onAddImage={canEdit ? callMedia : undefined}
+        onUpdateImage={canEdit ? callMedia : undefined}
+        // Empty, the only control is the add button, so anything that blocks
+        // picking disables the viewer. Filled, removal still works on mobile.
+        disabled={data ? Boolean(readOnly) : !canEdit}
+        // The buttons render whether or not a handler is given, so the states
+        // that cannot use them have to take them away explicitly.
+        showUpdateButton={canEdit}
+        showRemoveButton={!readOnly && Boolean(onClearImage)}
+        updateImageInfo={t('cairo.replace-image.tooltip')}
+        removeImageInfo={t('cairo.remove-image.tooltip')}
+        addImageInfo={t('cairo.add-image.tooltip')}
+        height={MEDIA_HEIGHT}
+        width="100%"
+        fit="cover"
+        onRemoveImage={onClear}
+      />
+    </Box>
+  );
+};
+
+FormImageField.displayName = 'FormImageField';
+
+export type ControlledImageInputProps = Omit<
+  ControlledInputProps<string | undefined>,
+  'invalid'
+>;
+
+export const ControlledImageInput: FC<ControlledImageInputProps> = ({
+  data,
+  onChange,
+  onBlur,
+  readOnly,
+  autoFocus,
+  dataHook,
+}) => (
+  <FormImageField
+    data={data}
+    onChange={onChange}
+    // FormImageField reports removal through onClear, not onChange.
+    onClear={() => onChange(undefined)}
+    onBlur={onBlur}
+    readOnly={readOnly}
+    autoFocus={autoFocus}
+    dataHook={dataHook}
+  />
+);
+
+ControlledImageInput.displayName = 'ControlledImageInput';