@formality-ui/react 0.1.0 → 0.2.1

package/dist/index.d.cts

@@ -202,10 +202,10 @@ declare function defineInputs<T extends Record<string, ReactInputConfig>>(inputs
  * `<Field>` renders your input component via React Hook Form's `<Controller>`.
  * At runtime Formality merges a `coreProps` bundle onto the component (name,
  * value, onChange, onBlur, and — as a React-special key — `ref`). The three
- * members below are the **intended injected-props contract**: `formState`
- * today reaches templates and render-prop children; `state` (subscribed field
- * state) and a top-level `forwardRef` key are part of the contract this type
- * codifies ahead of the runtime wiring (see "Runtime caveat" below).
+ * members below are the **injected-props contract**: `formState` reaches
+ * templates and render-prop children; `state` (subscribed field state) and a
+ * top-level `forwardRef` key are delivered at runtime by `<Field>` (see
+ * "Runtime delivery" below).
  *
  * **Destructure before forwarding.** Component authors MUST destructure
  * `state`, `formState`, and `forwardRef` OUT of props before spreading the
@@ -224,14 +224,14 @@ declare function defineInputs<T extends Record<string, ReactInputConfig>>(inputs
  * For MUI v9 components that no longer accept a top-level `inputRef`, wire it
  * via slots: `slotProps={{ input: { ref: forwardRef } }}` (PRD §5.3.8).
  *
- * **Runtime caveat (important).** Today `Field` delivers the RHF ref via the
- * React-special `ref` key (not a top-level `forwardRef` prop). To receive it
- * as `forwardRef` on a plain function component WITHOUT a `React.forwardRef`
- * wrap, either (a) wrap your component with `React.forwardRef`, or (b) target
- * React 19's ref-as-prop. Making Field deliver it as a top-level `forwardRef`
- * key for bare components is a FUTURE runtime task (out of scope for this
- * type-only change). The type ships the intended contract now so consumers
- * stop hand-rolling a lossy `WithFormality<P>`.
+ * **Runtime delivery (important).** `<Field>` delivers RHF's ref as a regular,
+ * top-level, enumerable prop named `forwardRef` — no `React.forwardRef` wrap
+ * is required for a plain function component that destructures `forwardRef`
+ * and wires it to the inner input (`ref={forwardRef}`). Consumers migrating
+ * off the old React-special `ref` key: a `React.forwardRef`-wrapped component
+ * should consume `props.forwardRef` (PRD §20.4), and under React 19
+ * ref-as-prop use `forwardRef` directly. The type ships the intended contract
+ * so consumers stop hand-rolling a lossy `WithFormality<P>`.
  *
  * @template P - the field component's own props (e.g. TextFieldProps). Defaults
  *   to `unknown` so existing `ComponentType<any>` casts remain valid.

package/dist/index.d.ts

@@ -202,10 +202,10 @@ declare function defineInputs<T extends Record<string, ReactInputConfig>>(inputs
  * `<Field>` renders your input component via React Hook Form's `<Controller>`.
  * At runtime Formality merges a `coreProps` bundle onto the component (name,
  * value, onChange, onBlur, and — as a React-special key — `ref`). The three
- * members below are the **intended injected-props contract**: `formState`
- * today reaches templates and render-prop children; `state` (subscribed field
- * state) and a top-level `forwardRef` key are part of the contract this type
- * codifies ahead of the runtime wiring (see "Runtime caveat" below).
+ * members below are the **injected-props contract**: `formState` reaches
+ * templates and render-prop children; `state` (subscribed field state) and a
+ * top-level `forwardRef` key are delivered at runtime by `<Field>` (see
+ * "Runtime delivery" below).
  *
  * **Destructure before forwarding.** Component authors MUST destructure
  * `state`, `formState`, and `forwardRef` OUT of props before spreading the
@@ -224,14 +224,14 @@ declare function defineInputs<T extends Record<string, ReactInputConfig>>(inputs
  * For MUI v9 components that no longer accept a top-level `inputRef`, wire it
  * via slots: `slotProps={{ input: { ref: forwardRef } }}` (PRD §5.3.8).
  *
- * **Runtime caveat (important).** Today `Field` delivers the RHF ref via the
- * React-special `ref` key (not a top-level `forwardRef` prop). To receive it
- * as `forwardRef` on a plain function component WITHOUT a `React.forwardRef`
- * wrap, either (a) wrap your component with `React.forwardRef`, or (b) target
- * React 19's ref-as-prop. Making Field deliver it as a top-level `forwardRef`
- * key for bare components is a FUTURE runtime task (out of scope for this
- * type-only change). The type ships the intended contract now so consumers
- * stop hand-rolling a lossy `WithFormality<P>`.
+ * **Runtime delivery (important).** `<Field>` delivers RHF's ref as a regular,
+ * top-level, enumerable prop named `forwardRef` — no `React.forwardRef` wrap
+ * is required for a plain function component that destructures `forwardRef`
+ * and wires it to the inner input (`ref={forwardRef}`). Consumers migrating
+ * off the old React-special `ref` key: a `React.forwardRef`-wrapped component
+ * should consume `props.forwardRef` (PRD §20.4), and under React 19
+ * ref-as-prop use `forwardRef` directly. The type ships the intended contract
+ * so consumers stop hand-rolling a lossy `WithFormality<P>`.
  *
  * @template P - the field component's own props (e.g. TextFieldProps). Defaults
  *   to `unknown` so existing `ComponentType<any>` casts remain valid.

package/dist/index.js

@@ -1,4 +1,4 @@
-import { createContext, useContext, useMemo, useRef, useState, useCallback, useEffect } from 'react';
+import { createContext, useContext, useMemo, useRef, useState, useCallback, useEffect, createElement } from 'react';
 import { jsx, Fragment } from 'react/jsx-runtime';
 import { useForm, FormProvider, useWatch, Controller, useFormContext as useFormContext$1 } from 'react-hook-form';
 import { debounce } from 'lodash-es';
@@ -560,11 +560,18 @@ function useInferredInputs(options) {
     selectProps,
     formDefaultFieldProps,
     providerDefaultFieldProps,
-    conditions = [],
-    subscribesTo = []
+    conditions,
+    subscribesTo
   } = options;
+  const signature = JSON.stringify({
+    selectProps,
+    formDefaultFieldProps,
+    providerDefaultFieldProps,
+    conditions,
+    subscribesTo
+  });
   return useMemo(() => {
-    const inferred = [...subscribesTo];
+    const inferred = [...subscribesTo ?? []];
     if (providerDefaultFieldProps) {
       inferred.push(...inferFieldsFromDescriptor(providerDefaultFieldProps));
     }
@@ -574,17 +581,11 @@ function useInferredInputs(options) {
     if (selectProps) {
       inferred.push(...inferFieldsFromDescriptor(selectProps));
     }
-    if (conditions.length > 0) {
+    if (conditions && conditions.length > 0) {
       inferred.push(...inferFieldsFromConditions(conditions));
     }
     return [...new Set(inferred)];
-  }, [
-    providerDefaultFieldProps,
-    formDefaultFieldProps,
-    selectProps,
-    conditions,
-    subscribesTo
-  ]);
+  }, [signature]);
 }
 
 // src/hooks/useConditions.ts
@@ -1115,21 +1116,33 @@ function Field({
             [inputConfig.inputFieldProp ?? "value"]: formattedValue,
             onChange: handleChange(field.onChange),
             onBlur: field.onBlur,
-            ref: field.ref
+            forwardRef: field.ref
           }
         });
         const Component = inputConfig.component;
+        const isHostComponent = typeof inputConfig.component === "string";
         const template = inputConfig.template ?? providerConfig.inputTemplates[type] ?? providerConfig.defaultInputTemplate;
         const TemplateComponent = template;
-        const renderedField = TemplateComponent ? /* @__PURE__ */ jsx(
-          TemplateComponent,
-          {
-            Field: Component,
-            fieldProps: finalProps,
-            fieldState,
-            formState
-          }
-        ) : /* @__PURE__ */ jsx(Component, { ...finalProps });
+        let renderedField;
+        if (TemplateComponent) {
+          renderedField = /* @__PURE__ */ jsx(
+            TemplateComponent,
+            {
+              Field: Component,
+              fieldProps: finalProps,
+              fieldState,
+              formState
+            }
+          );
+        } else if (isHostComponent) {
+          const { forwardRef: hostRef, ...restHostProps } = finalProps;
+          renderedField = createElement(inputConfig.component, {
+            ...restHostProps,
+            ref: hostRef
+          });
+        } else {
+          renderedField = /* @__PURE__ */ jsx(Component, { ...finalProps });
+        }
         if (typeof children === "function") {
           const result = children({
             fieldState,