@wix/patterns-fields 1.73.0 → 1.75.0

package/src/components/rich-text/rich-text-input/rich-text-editor/rich-text-editor.st.css.ts

@@ -5,7 +5,7 @@ import { classesRuntime, statesRuntime } from "../../../../stylable-esm-runtime.
 
 
 
-var _namespace_ = "richtexteditor770686478";
+var _namespace_ = "richtexteditor1211455191";
 var _style_ = classesRuntime.bind(null, _namespace_);
 
 export var cssStates = statesRuntime.bind(null, _namespace_);
@@ -13,12 +13,12 @@ export var style: import("@stylable/runtime").STFunction = _style_;
 export var st: import("@stylable/runtime").STFunction = _style_;
 
 export var namespace = _namespace_;
-export var classes = {"root":"richtexteditor770686478__root","nativeInput":"richtexteditor770686478__nativeInput","editor":"richtexteditor770686478__editor"};
+export var classes = {"root":"richtexteditor1211455191__root","nativeInput":"richtexteditor1211455191__nativeInput","editor":"richtexteditor1211455191__editor"};
 export var keyframes = {}; 
 export var layers = {};
 export var containers = {};
 export var stVars = {}; 
-export var vars = {"wds-color-blue-100":"--wds-color-blue-100","wds-color-blue-300":"--wds-color-blue-300","wds-color-red-100":"--wds-color-red-100","wds-color-red-300":"--wds-color-red-300","wds-color-yellow-100":"--wds-color-yellow-100","wds-color-yellow-300":"--wds-color-yellow-300","wds-color-black-700":"--wds-color-black-700","wds-input-shadow-focus-standard":"--wds-input-shadow-focus-standard","wds-border-radius-300":"--wds-border-radius-300"}; 
+export var vars = {"wds-input-border-color":"--wds-input-border-color","wds-input-border-color-focus":"--wds-input-border-color-focus","wds-input-shadow-focus-standard":"--wds-input-shadow-focus-standard","wds-input-shadow-focus-destructive":"--wds-input-shadow-focus-destructive","wds-input-shadow-focus-warning":"--wds-input-shadow-focus-warning","wds-input-border-radius-default-medium":"--wds-input-border-radius-default-medium","wds-color-border-destructive-secondary-active":"--wds-color-border-destructive-secondary-active","wds-color-border-warning-secondary-active":"--wds-color-border-warning-secondary-active","wsr-color-B10":"--wsr-color-B10","wsr-color-B40":"--wsr-color-B40","wsr-color-R10":"--wsr-color-R10","wsr-color-R40":"--wsr-color-R40","wsr-color-Y10":"--wsr-color-Y10","wsr-color-Y40":"--wsr-color-Y40","wsr-color-F00":"--wsr-color-F00","wsr-border-radius-06":"--wsr-border-radius-06","wds-color-black-700":"--wds-color-black-700"}; 
 
 
 

package/src/components/rich-text/rich-text-input/rich-text-editor/toolbar/toolbar.st.css.ts

@@ -5,7 +5,7 @@ import { classesRuntime, statesRuntime } from "../../../../../stylable-esm-runti
 
 
 
-var _namespace_ = "toolbar4106329138";
+var _namespace_ = "toolbar904415871";
 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":"toolbar4106329138__root","item":"toolbar4106329138__item","separator":"toolbar4106329138__separator","clearFormatting":"toolbar4106329138__clearFormatting","fullScreen":"toolbar4106329138__fullScreen","dropdownItemContent":"toolbar4106329138__dropdownItemContent","dropdownItemTitle":"toolbar4106329138__dropdownItemTitle","dropdownItemSubtitle":"toolbar4106329138__dropdownItemSubtitle","dropdownHeaderOne":"toolbar4106329138__dropdownHeaderOne","dropdownHeaderTwo":"toolbar4106329138__dropdownHeaderTwo","dropdownHeaderThree":"toolbar4106329138__dropdownHeaderThree","dropdownHeaderFour":"toolbar4106329138__dropdownHeaderFour","dropdownHeaderFive":"toolbar4106329138__dropdownHeaderFive","dropdownHeaderSix":"toolbar4106329138__dropdownHeaderSix","dropdownParagraphOne":"toolbar4106329138__dropdownParagraphOne","dropdownNormalText":"toolbar4106329138__dropdownNormalText","dropdownParagraphThree":"toolbar4106329138__dropdownParagraphThree"};
+export var classes = {"root":"toolbar904415871__root","item":"toolbar904415871__item","separator":"toolbar904415871__separator","clearFormatting":"toolbar904415871__clearFormatting","fullScreen":"toolbar904415871__fullScreen","dropdownItemContent":"toolbar904415871__dropdownItemContent","dropdownItemTitle":"toolbar904415871__dropdownItemTitle","dropdownItemSubtitle":"toolbar904415871__dropdownItemSubtitle","dropdownHeaderOne":"toolbar904415871__dropdownHeaderOne","dropdownHeaderTwo":"toolbar904415871__dropdownHeaderTwo","dropdownHeaderThree":"toolbar904415871__dropdownHeaderThree","dropdownHeaderFour":"toolbar904415871__dropdownHeaderFour","dropdownHeaderFive":"toolbar904415871__dropdownHeaderFive","dropdownHeaderSix":"toolbar904415871__dropdownHeaderSix","dropdownParagraphOne":"toolbar904415871__dropdownParagraphOne","dropdownNormalText":"toolbar904415871__dropdownNormalText","dropdownParagraphThree":"toolbar904415871__dropdownParagraphThree"};
 export var keyframes = {}; 
 export var layers = {};
 export var containers = {};

package/src/components/text/form-short-text-input.tsx

@@ -0,0 +1,121 @@
+import React, { useCallback, useMemo, useState } from 'react';
+import {
+  AutoComplete,
+  Input,
+  listItemSelectBuilder,
+  type DropdownLayoutValueOption,
+} from '@wix/design-system';
+
+import type { ControlledInputProps } from '../../types/controlled-input';
+
+export interface FormShortTextOption {
+  id: string;
+  value: string;
+}
+
+export interface FormShortTextInputProps extends ControlledInputProps<string> {
+  options?: FormShortTextOption[];
+  required?: boolean;
+  placeholder?: string;
+  emptyStateMessage?: string;
+  inputRef?: React.Ref<HTMLInputElement>;
+}
+
+export const FormShortTextInput: React.FC<FormShortTextInputProps> = ({
+  data,
+  onChange,
+  onBlur,
+  readOnly,
+  autoFocus,
+  invalid,
+  dataHook,
+  options,
+  required,
+  placeholder,
+  emptyStateMessage,
+  inputRef,
+}) => {
+  const [searchValue, setSearchValue] = useState<string>();
+  const selectedOption = options?.find((option) => option.id === data);
+  const selectedId = selectedOption?.id;
+  const displayValue = searchValue ?? selectedOption?.value ?? data;
+
+  const dropdownOptions = useMemo(() => {
+    const source = searchValue
+      ? options?.filter((option) =>
+          option.value.toLowerCase().includes(searchValue.toLowerCase()),
+        )
+      : options;
+    return (source ?? []).map((option) =>
+      listItemSelectBuilder({
+        id: option.id,
+        title: option.value,
+        selected: option.id === selectedId,
+      }),
+    );
+  }, [options, searchValue, selectedId]);
+
+  const handleSelect = useCallback(
+    (option: DropdownLayoutValueOption) => {
+      onChange(String(option.id));
+      setSearchValue(undefined);
+    },
+    [onChange],
+  );
+
+  const handleSearch = useCallback(
+    (event: React.ChangeEvent<HTMLInputElement>) => {
+      setSearchValue(event.target.value);
+      if (!event.target.value) {
+        onChange('');
+      }
+    },
+    [onChange],
+  );
+
+  const handleBlur = useCallback(() => {
+    setSearchValue(undefined);
+    onBlur?.();
+  }, [onBlur]);
+
+  if (!options?.length) {
+    return (
+      <Input
+        value={data}
+        onChange={(event) => onChange(event.target.value)}
+        onBlur={onBlur}
+        readOnly={readOnly}
+        autoFocus={autoFocus}
+        status={invalid ? 'error' : undefined}
+        inputRef={inputRef}
+        placeholder={placeholder}
+        dataHook={dataHook}
+      />
+    );
+  }
+
+  return (
+    <AutoComplete
+      value={displayValue}
+      selectedId={selectedId}
+      options={dropdownOptions}
+      onSelect={handleSelect}
+      onChange={handleSearch}
+      onClear={() => {
+        onChange('');
+        setSearchValue(undefined);
+      }}
+      onBlur={handleBlur}
+      disabled={readOnly}
+      autoFocus={autoFocus}
+      status={invalid ? 'error' : undefined}
+      clearButton={!required}
+      placeholder={placeholder}
+      emptyStateMessage={emptyStateMessage}
+      inputRef={inputRef}
+      dataHook={dataHook}
+    />
+  );
+};
+
+FormShortTextInput.displayName = 'FormShortTextInput';

package/src/components/text/form-short-text.driver.ts

@@ -29,6 +29,10 @@ export function FormShortTextDriver(
       hasSpecificValues
         ? autocomplete.inputDriver.getValue()
         : input.getValue(),
+    getPlaceholder: async () =>
+      hasSpecificValues
+        ? autocomplete.inputDriver.getPlaceholder()
+        : input.getPlaceholder(),
     enterText: async (value: string) =>
       hasSpecificValues
         ? autocomplete.inputDriver.enterText(value)

package/src/components/text/form-short-text.tsx

@@ -1,19 +1,13 @@
-import React, { useCallback, useMemo, useState } from 'react';
-import {
-  AutoComplete,
-  FormField,
-  Input,
-  listItemSelectBuilder,
-  type DropdownLayoutValueOption,
-} from '@wix/design-system';
+import React from 'react';
+import { FormField } from '@wix/design-system';
 import { observer } from 'mobx-react-lite';
-import type { Field, SpecificValue } from '@wix/bex-core';
 import { useWixPatternsContainer } from '@wix/bex-core/react';
 import { useController } from '@wix/bex-core/form';
 
 import { BaseInputProps } from '../../types/base-input';
 import { isEmpty, isLongerThan, isShorterThan } from '../../validations/string';
 import { useTranslations } from '../../hooks/use-translations';
+import { FormShortTextInput } from './form-short-text-input';
 
 export interface FormShortTextProps extends BaseInputProps<string> {}
 
@@ -24,6 +18,7 @@ const _FormShortText = (props: FormShortTextProps) => {
   const { field, dataHook, formControl, data } = props;
 
   const { translate: t } = useWixPatternsContainer();
+  const { t: tf } = useTranslations();
 
   const stringLengthRange = field.validation?.stringLengthRange;
   const minLength = stringLengthRange?.minLength;
@@ -78,107 +73,24 @@ const _FormShortText = (props: FormShortTextProps) => {
       statusMessage={controller.fieldState.error?.message}
       dataHook={dataHook}
     >
-      {specificValues?.length ? (
-        <ShortTextSpecificValues
-          field={field}
-          controller={controller}
-          specificValues={specificValues}
-        />
-      ) : (
-        <Input
-          value={controller.field.value}
-          onChange={(e) => controller.field.onChange?.(e.target.value)}
-          onBlur={controller.field.onBlur}
-          dataHook={`short-text-${field.id}`}
-          ref={controller.field.ref}
-        />
-      )}
+      <FormShortTextInput
+        data={controller.field.value ?? ''}
+        onChange={controller.field.onChange}
+        onBlur={controller.field.onBlur}
+        options={specificValues}
+        required={field.validation?.required}
+        invalid={Boolean(controller.fieldState.error)}
+        placeholder={
+          specificValues?.length
+            ? tf('auto-patterns.fields.select_placeholder')
+            : undefined
+        }
+        emptyStateMessage={tf('auto-patterns.fields.no_results_found')}
+        inputRef={controller.field.ref}
+        dataHook={`short-text-${field.id}`}
+      />
     </FormField>
   );
 };
 
-type ShortTextController = ReturnType<typeof useController>;
-
-interface ShortTextSpecificValuesProps {
-  field: Field;
-  controller: ShortTextController;
-  specificValues: SpecificValue[];
-}
-
-const ShortTextSpecificValues = ({
-  field,
-  controller,
-  specificValues,
-}: ShortTextSpecificValuesProps) => {
-  const { t: tf } = useTranslations();
-  const [searchValue, setSearchValue] = useState<string>();
-  const selectedOption = specificValues.find(
-    (option) => option.id === controller.field.value,
-  );
-  const selectedId = selectedOption ? selectedOption.id : undefined;
-  const displayValue =
-    searchValue ?? selectedOption?.value ?? controller.field.value ?? '';
-
-  const options = useMemo(() => {
-    const source = searchValue
-      ? specificValues.filter((option) =>
-          option.value.toLowerCase().includes(searchValue.toLowerCase()),
-        )
-      : specificValues;
-    return source.map((option) =>
-      listItemSelectBuilder({
-        id: option.id,
-        title: option.value,
-        selected: option.id === selectedId,
-      }),
-    );
-  }, [searchValue, specificValues, selectedId]);
-
-  const handleSelect = useCallback(
-    (option: DropdownLayoutValueOption) => {
-      const id = String(option.id);
-      controller.field.onChange(id);
-      setSearchValue(undefined);
-    },
-    [controller.field],
-  );
-
-  const handleSearch = useCallback(
-    (e: React.ChangeEvent<HTMLInputElement>) => {
-      setSearchValue(e.target.value);
-      if (!e.target.value) {
-        controller.field.onChange('');
-      }
-    },
-    [controller.field],
-  );
-
-  const handleClear = useCallback(() => {
-    controller.field.onChange('');
-    setSearchValue(undefined);
-  }, [controller.field]);
-
-  const handleBlur = useCallback(() => {
-    setSearchValue(undefined);
-    controller.field.onBlur();
-  }, [controller.field]);
-
-  return (
-    <AutoComplete
-      value={displayValue}
-      selectedId={selectedId}
-      options={options}
-      onSelect={handleSelect}
-      onChange={handleSearch}
-      onClear={handleClear}
-      onBlur={handleBlur}
-      clearButton={!field.validation?.required}
-      placeholder={tf('auto-patterns.fields.select_placeholder')}
-      emptyStateMessage={tf('auto-patterns.fields.no_results_found')}
-      inputRef={controller.field.ref}
-      dataHook={`short-text-${field.id}`}
-    />
-  );
-};
-
 export const FormShortText = observer(_FormShortText);

package/src/components/text/index.ts

@@ -3,3 +3,4 @@ export * from './cell-text-input';
 export * from './cell-autocomplete-input';
 export * from './form-long-text';
 export * from './form-short-text';
+export * from './form-short-text-input';

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

@@ -5,7 +5,7 @@ import { classesRuntime, statesRuntime } from "../../stylable-esm-runtime.js";
 
 
 
-var _namespace_ = "textview955586509";
+var _namespace_ = "textview3886369445";
 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":"textview955586509__root","textView":"textview955586509__textView"};
+export var classes = {"root":"textview3886369445__root","textView":"textview3886369445__textView"};
 export var keyframes = {}; 
 export var layers = {};
 export var containers = {};

package/src/components/time-input/form-time.tsx

@@ -6,7 +6,7 @@ import { useWixPatternsContainer } from '@wix/bex-core/react';
 import { useController } from '@wix/bex-core/form';
 
 import { BaseInputProps } from '../../types/base-input';
-import { useTranslations } from '../../hooks';
+import { fieldRefHandle, useTranslations } from '../../hooks';
 import {
   isDataValidOrNotSet,
   timeValidation,
@@ -40,10 +40,16 @@ const _FormTime = (props: FormTimeProps) => {
 
   // TimeInput has no DOM ref to hand to field.ref, so bridge its imperative
   // focus() — lets react-hook-form's shouldFocusError scroll to this field
-  // when it blocks save.
+  // when it blocks save. TimeInputImperativeActions has no select(), so the
+  // handle absorbs the calls react-hook-form makes beyond focus.
   const timeRef = useRef<TimeInputImperativeActions>(null);
   useEffect(() => {
-    controller.field.ref({ focus: () => timeRef.current?.focus() });
+    controller.field.ref(
+      fieldRefHandle(
+        () => timeRef.current?.focus(),
+        () => timeRef.current,
+      ),
+    );
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, []);
 

package/src/components/url/form-url-input.tsx

@@ -0,0 +1,42 @@
+import React from 'react';
+import { Input } from '@wix/design-system';
+import { Link } from '@wix/wix-ui-icons-common/lazy';
+
+import type { ControlledInputProps } from '../../types/controlled-input';
+
+export interface FormUrlInputProps extends ControlledInputProps<string> {
+  inputRef?: React.Ref<HTMLInputElement>;
+  placeholder?: string;
+}
+
+export const FormUrlInput: React.FC<FormUrlInputProps> = ({
+  data,
+  onChange,
+  onBlur,
+  readOnly,
+  autoFocus,
+  invalid,
+  dataHook,
+  inputRef,
+  placeholder,
+}) => (
+  <Input
+    prefix={
+      <Input.IconAffix>
+        <Link />
+      </Input.IconAffix>
+    }
+    type="url"
+    value={data}
+    onChange={(event) => onChange(event.target.value)}
+    onBlur={onBlur}
+    readOnly={readOnly}
+    autoFocus={autoFocus}
+    status={invalid ? 'error' : undefined}
+    inputRef={inputRef}
+    placeholder={placeholder}
+    dataHook={dataHook}
+  />
+);
+
+FormUrlInput.displayName = 'FormUrlInput';

package/src/components/url/form-url.tsx

@@ -1,13 +1,13 @@
 import React from 'react';
-import { FormField, Input } from '@wix/design-system';
+import { FormField } from '@wix/design-system';
 import { observer } from 'mobx-react-lite';
-import { Link } from '@wix/wix-ui-icons-common/lazy';
 import { useWixPatternsContainer } from '@wix/bex-core/react';
 import { useController } from '@wix/bex-core/form';
 
 import { BaseInputProps } from '../../types/base-input';
 import { isEmpty } from '../../validations/string';
 import { isValidUri } from '../../validations/url';
+import { FormUrlInput } from './form-url-input';
 
 export interface FormUrlProps extends BaseInputProps<string> {}
 
@@ -39,18 +39,14 @@ const _FormUrl = (props: FormUrlProps) => {
       status={controller.fieldState.error ? 'error' : undefined}
       statusMessage={controller.fieldState.error?.message}
     >
-      <Input
-        prefix={
-          <Input.IconAffix>
-            <Link />
-          </Input.IconAffix>
-        }
+      <FormUrlInput
         placeholder={t('cairo.customFields.url-input.placeholder')}
         dataHook={`url-${field.id}`}
-        value={controller.field.value}
-        onChange={(e) => controller.field.onChange?.(e.target.value)}
+        data={controller.field.value ?? ''}
+        onChange={controller.field.onChange}
         onBlur={controller.field.onBlur}
-        ref={controller.field.ref}
+        inputRef={controller.field.ref}
+        invalid={Boolean(controller.fieldState.error)}
       />
     </FormField>
   );

package/src/components/url/index.ts

@@ -1,3 +1,4 @@
 export * from './url-view';
 export * from './cell-url-input';
 export * from './form-url';
+export * from './form-url-input';

package/src/components/video/form-video.tsx

@@ -22,7 +22,7 @@ import { observer } from 'mobx-react-lite';
 import { useIsMobile, useWixPatternsContainer } from '@wix/bex-core/react';
 import { useController } from '@wix/bex-core/form';
 import { BaseInputProps } from '../../types/base-input';
-import { useTranslations } from '../../hooks';
+import { useFieldRef, useTranslations } from '../../hooks';
 import { isEmpty } from '../../validations/string';
 import { isDataValidOrNotSet } from '../../validations/validations';
 import * as videoValidation from '../../validations/video';
@@ -64,6 +64,8 @@ const _FormVideo = (props: FormVideoProps) => {
     },
   });
 
+  const setFieldRef = useFieldRef(controller.field.ref);
+
   async function openMedia() {
     if (!openMediaManager) return;
     try {
@@ -204,7 +206,7 @@ const _FormVideo = (props: FormVideoProps) => {
           <ImageViewer
             // Only the empty state can fail `required`, so the add button is
             // always the right target for react-hook-form's shouldFocusError.
-            ref={controller.field.ref}
+            ref={setFieldRef}
             dataHook={`video-${field.id}`}
             onAddImage={isMobile ? undefined : () => openMedia()}
             addImageInfo={t('auto-patterns.fields.add_video_tooltip')}

package/src/exports/unidriver.ts

@@ -1,2 +1,3 @@
 export { FormMediaGalleryFieldUniDriver } from '../components/media-gallery/form-media-gallery-field.uni.driver';
 export { ColorViewUniDriver } from '../components/color-view/color-view.uni.driver';
+export { ControlledInputUniDriver } from '../components/controlled-input.driver';

package/src/hooks/index.ts

@@ -7,5 +7,6 @@ export * from './use-translations';
 export * from './use-with-callback';
 export * from './use-resize-effect';
 export * from './use-cell-edit-keyboard';
+export * from './use-field-ref';
 export * from './use-merged-ref';
 export * from './use-scroll-to-error-ref';

package/src/hooks/pr-5746-kobiburnley-comments.md

@@ -0,0 +1,54 @@
+# PR #5746 — kobiburnley review
+
+[fix(fields): register a field ref that answers every call react-hook-form makes](https://github.com/wix-private/cairo/pull/5746)
+
+> **Verdict: Request changes** — 1 blocker. (Posted as a comment review because GitHub will not let the
+> author formally request changes on their own PR.)
+>
+> The diagnosis is right, and I checked it against the installed `react-hook-form` (7.56.4) rather than
+> taking it on trust […] `fieldRefHandle` / `useFieldRef` are a clean way to close it […] I also confirmed
+> the integration test is a real guard, not decoration.
+>
+> One blocker: the audit missed a call site with exactly the shape the helper exists for.
+>
+> — [pullrequestreview-5002194499](https://github.com/wix-private/cairo/pull/5746#pullrequestreview-5002194499)
+
+All claims below were checked against the branch before being written down. Every one holds.
+
+| # | Comment link | Description | Severity | Status | Resolution recommendation |
+|---|---|---|---|---|---|
+| 1 | [discussion_r3838295772](https://github.com/wix-private/cairo/pull/5746#discussion_r3838295772) — `packages/fields/src/components/time-input/form-time.tsx:46` | `form-time` registers a hand-rolled focus-only object, `controller.field.ref({ focus: () => timeRef.current?.focus() })`. Exactly the shape the helper exists for, missed by the audit, so it ships still broken while the PR reads as closing the trap. | Blocker | done | Fixed in `23dc894` — wrapped with `fieldRefHandle` as suggested. Missed originally because `form-time` calls `controller.field.ref(...)` directly in a `useEffect`, so the `inputRef=`/`ref=` grep never matched it. Covered by the table-driven `setFocus` guard. |
+| 2 | [review summary](https://github.com/wix-private/cairo/pull/5746#pullrequestreview-5002194499) | PR body claims "audited all nine that register directly"; there are ~23 `controller.field.ref` sites. The 7 passing `ref=` to a WDS `Input`/`InputArea` get `InputImperativeActions`, which has `select` but no `setCustomValidity`/`reportValidity` — so the `shouldUseNativeValidation` half stays open in `form-url`, `form-email`, `form-short-text` (Input branch), `form-long-text`, `form-color`, `form-array`, `form-object`. | Major (accuracy) | done | PR description rewritten with the full 23-site table. `InputImperativeActions` confirmed as `{ focus, blur, select, setSelectionRange, clear, input }`. The `shouldUseNativeValidation` gap in the 7 `ref=`-on-`Input` sites is left open and stated as a follow-up rather than implied fixed. |
+| 3 | [review summary](https://github.com/wix-private/cairo/pull/5746#pullrequestreview-5002194499) | Fix it once in `packages/core` instead. `packages/core/src/exports/form.ts` is `export * from 'react-hook-form'`, so core owns the entry point; a `useController` there installing the safe handle would cover all sites and every future one, making `useFieldRef` and the seven adopting edits unnecessary. As it stands the fix is opt-in — which is how `form-time` got missed. | Major (design) | dismiss | Not implemented; kept per-site by decision. Rationale recorded in the PR reply: core's `exports/form.ts` is a bare re-export, so wrapping `useController` there would turn it into real implementation and change behaviour for every consumer of `@wix/bex-core/form`, not just Cairo renderers. Filed as a follow-up — if it lands, `useFieldRef` and all adopting edits should be deleted and the `Input` group closes for free. |
+| 4 | [review summary](https://github.com/wix-private/cairo/pull/5746#pullrequestreview-5002194499) | The same 3-line comment is copy-pasted verbatim into seven files; the `fieldRefHandle` docblock already says it, and `AGENTS.md` asks for a comment only when it tells the reader something the code cannot. | Nit | done | Removed from all seven files in `b64bfc4`. |
+| 5 | [review summary](https://github.com/wix-private/cairo/pull/5746#pullrequestreview-5002194499) | `useFieldRef`'s type parameter `T` appears only in the return type, so every call site infers `FieldControl` and the annotation buys nothing. | Minor | done | `T` dropped in `a51e9c6`; takes and returns `FieldControl`. |
+| 6 | [review summary](https://github.com/wix-private/cairo/pull/5746#pullrequestreview-5002194499) | Lint is not clean: `use-field-ref.ts:56` trips `prettier/prettier`. | Minor | done | Fixed in `c6406f6`. Root cause of the false "clean" report: all changed files were passed as one joined argument, so eslint matched nothing. Re-verified one file at a time. `form-video.tsx:73` `curly` warning remains but is unchanged from master. |
+| 7 | [review summary](https://github.com/wix-private/cairo/pull/5746#pullrequestreview-5002194499) | Only `form-address` has an integration guard; the other six conversions would not notice a revert. | Test gap | done | Fixed in `94baa17`. Table-driven over one renderer per control shape: address, time, `FormDocument` (`AddItemActions`, shared with audio/multi-document/media-gallery), `FormImageInput` (`ImageViewer`, shared with video). Each verified failing via `git checkout origin/master -- <file>` — note `git checkout -- <file>` restores from HEAD and silently proves nothing once the change is committed. |
+| 8 | [review summary](https://github.com/wix-private/cairo/pull/5746#pullrequestreview-5002194499) | In `EntityPageCustomField`, the new `control` closure and the `focus` callback each resolve consumer-then-`querySelector` separately; not wrong (focus needs `scrollIntoView` between the steps) but they will drift. | Nit | done | Fixed in `91147ff`. Both paths read one `control()`. The identity check I first wrote was also wrong, not just duplicative: with nothing focusable, `target` and `consumerRef.current` were both `null`, so it skipped the scroll in exactly the case needing it. Now keyed off `!consumerRef.current`. |
+
+## Notes
+
+- #3 is the pivot. If the fix moves into core's `useController`, then #1, #2, #4, #5 and #7 mostly evaporate and this
+  PR shrinks to deleting `useFieldRef` and reverting the seven adopting edits. Worth settling before spending
+  effort on the others.
+- #1 is a blocker on its own terms and is a one-line fix either way, since `form-time` is broken today
+  regardless of which mechanism wins.
+- The reviewer independently reproduced the address integration test (revert → `1 failed, 3 passed`), so the
+  guard is trusted; the gap is coverage of the other six (#7), not the approach.
+
+## Outcome
+
+All eight resolved: seven fixed, one (row 3) dismissed with rationale. Commits on `fix/delegating-field-ref`,
+all pushed:
+
+| Commit | Row |
+|---|---|
+| `23dc894` fix(TimeInput): give form-time a field ref that answers every call | 1 |
+| `c6406f6` style(fields): format the fieldRefHandle call in useFieldRef | 6 |
+| `a51e9c6` refactor(fields): drop useFieldRef's unusable type parameter | 5 |
+| `b64bfc4` refactor(fields): drop the repeated useFieldRef comment | 4 |
+| `91147ff` refactor(EntityPageCustomField): resolve the control once | 8 |
+| `94baa17` test(fields): guard the other converted renderers against setFocus | 7 |
+
+Row 2 was a PR-description correction, not code. Row 3 answered in
+[issuecomment-5385655358](https://github.com/wix-private/cairo/pull/5746#issuecomment-5385655358).

package/src/hooks/use-field-ref.ts

@@ -0,0 +1,65 @@
+import type { MutableRefObject } from 'react';
+import { useCallback, useRef } from 'react';
+
+/**
+ * What a field's control may offer react-hook-form. A real input has all of
+ * it; a component handle usually has only `focus`.
+ */
+export interface FieldControl {
+  focus?: () => void;
+  select?: () => void;
+  setCustomValidity?: (message: string) => void;
+  reportValidity?: () => boolean;
+}
+
+/**
+ * Handle to register with react-hook-form, covering every method it may call.
+ *
+ * `useController` rewrites whatever is registered into
+ * `{ focus, select, setCustomValidity, reportValidity }` and calls all four
+ * through to the target. The guards check that wrapper rather than the target,
+ * so registering a control that only has `focus` makes `setFocus` with
+ * `shouldSelect`, or `shouldUseNativeValidation`, throw on the way to it.
+ *
+ * @param focus What to do when the field has to be reached.
+ * @param getControl The control the remaining calls go to, when there is one.
+ */
+export const fieldRefHandle = (
+  focus: () => void,
+  getControl: () => FieldControl | null | undefined,
+) => ({
+  focus,
+  select: () => getControl()?.select?.(),
+  setCustomValidity: (message: string) =>
+    getControl()?.setCustomValidity?.(message),
+  reportValidity: () => getControl()?.reportValidity?.() ?? true,
+});
+
+/**
+ * Callback ref for a field's control. Pass it where the control lands and
+ * react-hook-form gets a handle that reaches it.
+ *
+ * @param registerRef `controller.field.ref` from useController.
+ */
+export const useFieldRef = (
+  registerRef: (instance: unknown) => void,
+): ((instance: FieldControl | null) => void) => {
+  const control: MutableRefObject<FieldControl | null> =
+    useRef<FieldControl | null>(null);
+
+  return useCallback(
+    (instance: FieldControl | null) => {
+      control.current = instance;
+      if (!instance) {
+        return;
+      }
+      registerRef(
+        fieldRefHandle(
+          () => control.current?.focus?.(),
+          () => control.current,
+        ),
+      );
+    },
+    [registerRef],
+  );
+};