@behivetech/forms.form-field-managed 0.0.0-stage → 0.1.4

package/README.md

@@ -1,3 +1,127 @@
-# Temporary Holding Version
+# FormFieldManaged
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+`FormField` with its react-hook-form wiring already done — the control's
+value/onChange/onBlur/ref, the label association, and the error message.
+
+Use plain [`FormField`](../form-field) when you are managing state yourself;
+use this when the field belongs to a react-hook-form form.
+
+## Usage
+
+```jsx
+import { FormFieldManaged } from "@behivetech/forms.form-field-managed";
+import { Form, useForm } from "@behivetech/forms.form-provider";
+import { TextField } from "@behivetech/atoms.text-field";
+
+const methods = useForm({ defaultValues: { email: "" } });
+const save = (values) => alert(JSON.stringify(values));
+
+<Form methods={methods} onSubmit={save}>
+  <FormFieldManaged
+    name="email"
+    label="Email"
+    rules={{ required: "Email is required" }}
+  >
+    {(field) => <TextField {...field} />}
+  </FormFieldManaged>
+</Form>;
+```
+
+The error message comes from the field's own validation state — there is no
+`error` prop to pass, and no need to read `formState.errors`. `label`, `hint`,
+`required` and `className` pass through to `FormField`.
+
+`control` is optional; the field resolves it from the surrounding `Form` /
+`FormProvider` context.
+
+## Typing in TypeScript
+
+`field.value` is typed as the field `name` points at, so it spreads onto a
+control without a cast. Getting that narrowing depends on how the generics are
+supplied.
+
+Passing `control` infers both type parameters and needs no annotation:
+
+```tsx
+function Example() {
+  const methods = useForm({ defaultValues: { email: "" } });
+  return (
+    <Form
+      methods={methods}
+      onSubmit={(values) => alert(JSON.stringify(values))}
+    >
+      <FormFieldManaged control={methods.control} name="email" label="Email">
+        {(field) => <TextField {...field} />}
+      </FormFieldManaged>
+    </Form>
+  );
+}
+```
+
+Taking `control` from context instead means naming the field type too:
+
+```tsx
+type Values = { email: string };
+
+function Example() {
+  const methods = useForm<Values>({ defaultValues: { email: "" } });
+  return (
+    <Form
+      methods={methods}
+      onSubmit={(values) => alert(JSON.stringify(values))}
+    >
+      <FormFieldManaged<Values, "email"> name="email" label="Email">
+        {(field) => <TextField {...field} />}
+      </FormFieldManaged>
+    </Form>
+  );
+}
+```
+
+Supplying only the first type argument — `<FormFieldManaged<Values> name="email">`
+— does **not** narrow. TypeScript stops inferring the remaining parameters once
+any is given explicitly, so `TName` falls back to its default and `field.value`
+widens to a union of every field in the form. Prefer one of the two forms above.
+
+## Why a render prop
+
+The one thing that genuinely differs between controls is the prop they report
+changes on. Native inputs take the field as-is:
+
+```ts
+(field) => <TextField {...field} />
+```
+
+Radix-backed controls (`Select`, `Checkbox`, `Toggle`) report through
+`onValueChange` / `onCheckedChange`, so the caller maps that one prop:
+
+```ts
+(field) => (
+  <Select
+    id={field.id}
+    name={field.name}
+    options={roles}
+    value={field.value}
+    onValueChange={field.onChange}
+  />
+)
+```
+
+Making that visible is deliberate — it is the difference that matters, and it
+cannot be typed if hidden behind a clone.
+
+## Why not `register`
+
+`register()` returns an uncontrolled _native input_ contract
+(`{name, onChange, onBlur, ref}`). It works on `TextField` and `Textarea`,
+which render real `<input>` / `<textarea>` elements.
+
+It does not work on `Checkbox`, `Toggle` or `Select`. Those are Radix-backed:
+the ref would land on the trigger `<button>`, whose `value` is always `""`, and
+Radix reports changes through `onCheckedChange` / `onValueChange`, never
+`onChange`. The field would silently submit its default value with no type or
+runtime error. `FormFieldManaged` uses `useController`, which works for all of
+them.
+
+The render prop also receives the field's state as a second argument
+(`(field, fieldState) => …`) if you need `invalid`, `isDirty` or `isTouched`.

package/dist/index.cjs

@@ -0,0 +1,50 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// index.ts
+var index_exports = {};
+__export(index_exports, {
+  FormFieldManaged: () => FormFieldManaged
+});
+module.exports = __toCommonJS(index_exports);
+
+// form-field-managed.tsx
+var import_react = require("react");
+var import_forms = require("@behivetech/forms.form-field");
+var import_forms2 = require("@behivetech/forms.form-provider");
+var import_jsx_runtime = require("react/jsx-runtime");
+var FormFieldManaged = ({
+  name,
+  control,
+  rules,
+  children,
+  ...fieldProps
+}) => {
+  const id = (0, import_react.useId)();
+  const { field, fieldState } = (0, import_forms2.useController)({
+    name,
+    control,
+    rules
+  });
+  return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(import_forms.FormField, { ...fieldProps, htmlFor: id, error: fieldState.error?.message, children: children({ ...field, id }, fieldState) });
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  FormFieldManaged
+});

package/dist/index.d.ts

@@ -0,0 +1,67 @@
+import * as react from 'react';
+import { ReactNode } from 'react';
+import { FormFieldProps } from '@behivetech/forms.form-field';
+import { FieldValues, FieldPath, Control, RegisterOptions, ControllerRenderProps, ControllerFieldState } from '@behivetech/forms.form-provider';
+
+/**
+ * What the render prop receives: the wired field plus its `id`.
+ *
+ * `TName` is threaded through to `ControllerRenderProps` rather than left at its
+ * default. Without it `value` widens to the union of every field type in the
+ * form, so a call site spreading onto a `TextField` has to assert
+ * `value as string` — an assertion that keeps compiling if the field later
+ * changes type, which is the mistake the generic exists to catch.
+ */
+type ManagedField<TFieldValues extends FieldValues = FieldValues, TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>> = ControllerRenderProps<TFieldValues, TName> & {
+    /** Matches the label's `htmlFor`; spread onto the control or pass explicitly */
+    id: string;
+};
+interface FormFieldManagedProps<TFieldValues extends FieldValues = FieldValues, TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>> extends Omit<FormFieldProps, "children" | "error" | "htmlFor"> {
+    /** Field path in the form values; infers the field's value type */
+    name: TName;
+    /** Form control; falls back to the surrounding `useFormContext()` when omitted */
+    control?: Control<TFieldValues>;
+    /** Validation rules passed through to react-hook-form */
+    rules?: RegisterOptions<TFieldValues, TName>;
+    /** Renders the control from the wired field */
+    children: (field: ManagedField<TFieldValues, TName>, fieldState: ControllerFieldState) => ReactNode;
+}
+/**
+ * `FormField` with its react-hook-form wiring already done: the control's
+ * value/onChange/onBlur/ref, the label association, and the error message.
+ *
+ * Uses `useController` rather than `register` because `register` only works on
+ * controls that render a native input. `TextField` and `Textarea` do;
+ * `Checkbox`, `Toggle` and `Select` are Radix-backed, where the ref would land
+ * on the trigger button and the change callback is `onCheckedChange` /
+ * `onValueChange`, so `register` binds nothing and the field silently keeps its
+ * default. `useController` works for all of them.
+ *
+ * The control is supplied through a render prop rather than cloned, because the
+ * prop a control listens on is the one thing that genuinely differs between
+ * them — worth seeing at the call site, and impossible to type if hidden.
+ *
+ * Pass `control` and both type parameters infer, so `field.value` is the type
+ * of that one field and spreads onto a control without a cast:
+ *
+ * ```tsx
+ * <FormFieldManaged control={methods.control} name="email" label="Email">
+ *   {(field) => <TextField {...field} />}
+ * </FormFieldManaged>
+ * ```
+ *
+ * Taking `control` from context instead means naming both parameters. Supplying
+ * only the first — `<FormFieldManaged<Values> name="email">` — leaves `TName` at
+ * its default and widens `field.value` to a union of every field in the form,
+ * because TypeScript stops inferring the rest once any type argument is given
+ * explicitly:
+ *
+ * ```tsx
+ * <FormFieldManaged<Values, "email"> name="email" label="Email">
+ *   {(field) => <TextField {...field} />}
+ * </FormFieldManaged>
+ * ```
+ */
+declare const FormFieldManaged: <TFieldValues extends FieldValues = FieldValues, TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>>({ name, control, rules, children, ...fieldProps }: FormFieldManagedProps<TFieldValues, TName>) => react.JSX.Element;
+
+export { FormFieldManaged, type FormFieldManagedProps, type ManagedField };

package/dist/index.js

@@ -0,0 +1,25 @@
+// form-field-managed.tsx
+import { useId } from "react";
+import { FormField } from "@behivetech/forms.form-field";
+import {
+  useController
+} from "@behivetech/forms.form-provider";
+import { jsx } from "react/jsx-runtime";
+var FormFieldManaged = ({
+  name,
+  control,
+  rules,
+  children,
+  ...fieldProps
+}) => {
+  const id = useId();
+  const { field, fieldState } = useController({
+    name,
+    control,
+    rules
+  });
+  return /* @__PURE__ */ jsx(FormField, { ...fieldProps, htmlFor: id, error: fieldState.error?.message, children: children({ ...field, id }, fieldState) });
+};
+export {
+  FormFieldManaged
+};

package/docs.json

@@ -0,0 +1,77 @@
+{
+  "$schema": "https://github.com/behivetech/bht-component-registry/docs.schema.json",
+  "version": 2,
+  "generatedAt": "2026-10-20T05:50:11.164Z",
+  "docs": [
+    {
+      "displayName": "FormFieldManaged",
+      "description": "`FormField` with its react-hook-form wiring already done: the control's\nvalue/onChange/onBlur/ref, the label association, and the error message.\n\nUses `useController` rather than `register` because `register` only works on\ncontrols that render a native input. `TextField` and `Textarea` do;\n`Checkbox`, `Toggle` and `Select` are Radix-backed, where the ref would land\non the trigger button and the change callback is `onCheckedChange` /\n`onValueChange`, so `register` binds nothing and the field silently keeps its\ndefault. `useController` works for all of them.\n\nThe control is supplied through a render prop rather than cloned, because the\nprop a control listens on is the one thing that genuinely differs between\nthem — worth seeing at the call site, and impossible to type if hidden.\n\nPass `control` and both type parameters infer, so `field.value` is the type\nof that one field and spreads onto a control without a cast:\n\n```tsx\n<FormFieldManaged control={methods.control} name=\"email\" label=\"Email\">\n  {(field) => <TextField {...field} />}\n</FormFieldManaged>\n```\n\nTaking `control` from context instead means naming both parameters. Supplying\nonly the first — `<FormFieldManaged<Values> name=\"email\">` — leaves `TName` at\nits default and widens `field.value` to a union of every field in the form,\nbecause TypeScript stops inferring the rest once any type argument is given\nexplicitly:\n\n```tsx\n<FormFieldManaged<Values, \"email\"> name=\"email\" label=\"Email\">\n  {(field) => <TextField {...field} />}\n</FormFieldManaged>\n```",
+      "extendsNative": true,
+      "props": [
+        {
+          "name": "children",
+          "type": "(field: ManagedField<TFieldValues, TName>, fieldState: ControllerFieldState) => ReactNode",
+          "required": true,
+          "defaultValue": null,
+          "description": "Renders the control from the wired field"
+        },
+        {
+          "name": "name",
+          "type": "string",
+          "required": true,
+          "defaultValue": null,
+          "description": "Field path in the form values; infers the field's value type"
+        },
+        {
+          "name": "className",
+          "type": "string",
+          "required": false,
+          "defaultValue": null,
+          "description": "Additional class names to merge with the component root element"
+        },
+        {
+          "name": "control",
+          "type": "Control<TFieldValues>",
+          "required": false,
+          "defaultValue": null,
+          "description": "Form control; falls back to the surrounding `useFormContext()` when omitted"
+        },
+        {
+          "name": "hint",
+          "type": "ReactNode",
+          "required": false,
+          "defaultValue": null,
+          "description": "Supporting hint text; hidden while `error` is present"
+        },
+        {
+          "name": "label",
+          "type": "ReactNode",
+          "required": false,
+          "defaultValue": null,
+          "description": "Field label"
+        },
+        {
+          "name": "required",
+          "type": "boolean",
+          "required": false,
+          "defaultValue": null,
+          "description": "Shows a required marker next to the label"
+        },
+        {
+          "name": "rules",
+          "type": "RegisterOptions<TFieldValues, TName>",
+          "required": false,
+          "defaultValue": null,
+          "description": "Validation rules passed through to react-hook-form"
+        }
+      ]
+    },
+    {
+      "displayName": "PartialArgsStillWiden",
+      "description": "Supplying only `TFieldValues` leaves `TName` at its default, so `value` stays\nthe union — TypeScript stops inferring the remaining parameters as soon as\none is given explicitly. This is a language rule, not something the component\ncan type its way around, which is why the docstring steers callers to\n`control` or to naming both arguments.\n\nThe expected error is the guard: if a future TypeScript infers partial type\narguments, this line stops erroring and the comment above needs revisiting.",
+      "extendsNative": false,
+      "props": []
+    }
+  ],
+  "functions": []
+}

package/form-field-managed.example.tsx

@@ -0,0 +1,83 @@
+import { Button } from "@behivetech/atoms.button";
+import { Select } from "@behivetech/atoms.select";
+import { TextField } from "@behivetech/atoms.text-field";
+import { Toggle } from "@behivetech/atoms.toggle";
+import { Form, useForm } from "@behivetech/forms.form-provider";
+import { FormFieldManaged } from "./form-field-managed.js";
+
+interface DemoValues {
+  email: string;
+  role: string;
+  active: boolean;
+}
+
+const ROLES = [
+  { label: "Admin", value: "admin" },
+  { label: "Editor", value: "editor" },
+];
+
+/**
+ * One managed form covering both integration shapes: a native control, where
+ * the field spreads straight on, and two Radix controls, where the caller maps
+ * the one prop that differs.
+ *
+ * Each field passes `control` rather than naming type parameters. That is the
+ * shape worth copying: it infers both parameters, so `field.value` is the type
+ * of that one field and needs no cast. Reading `control` from context instead
+ * works too, but then the field type has to be named — `<FormFieldManaged<
+ * DemoValues, "email">` — because supplying one type argument stops TypeScript
+ * inferring the other.
+ */
+export const ManagedForm = () => {
+  const methods = useForm<DemoValues>({
+    defaultValues: { email: "", role: "", active: false },
+  });
+
+  return (
+    <Form methods={methods} onSubmit={(values) => console.log(values)}>
+      <FormFieldManaged
+        control={methods.control}
+        name="email"
+        label="Email"
+        hint="We only use this for sign-in"
+        required
+        rules={{ required: "Email is required" }}
+      >
+        {(field) => <TextField {...field} type="email" />}
+      </FormFieldManaged>
+
+      <FormFieldManaged
+        control={methods.control}
+        name="role"
+        label="Role"
+        rules={{ required: "Pick a role" }}
+      >
+        {(field) => (
+          <Select
+            id={field.id}
+            name={field.name}
+            options={ROLES}
+            value={field.value}
+            onValueChange={field.onChange}
+            placeholder="Pick one"
+          />
+        )}
+      </FormFieldManaged>
+
+      <FormFieldManaged control={methods.control} name="active" label="Active">
+        {(field) => (
+          <Toggle
+            id={field.id}
+            name={field.name}
+            checked={field.value}
+            onCheckedChange={field.onChange}
+          />
+        )}
+      </FormFieldManaged>
+
+      <Button type="submit" variant="primary" size="sm">
+        Save
+      </Button>
+    </Form>
+  );
+};

package/form-field-managed.tsx

@@ -0,0 +1,105 @@
+import { type ReactNode, useId } from "react";
+import { FormField, type FormFieldProps } from "@behivetech/forms.form-field";
+import {
+  useController,
+  type Control,
+  type ControllerFieldState,
+  type ControllerRenderProps,
+  type FieldPath,
+  type FieldValues,
+  type RegisterOptions,
+} from "@behivetech/forms.form-provider";
+
+/**
+ * What the render prop receives: the wired field plus its `id`.
+ *
+ * `TName` is threaded through to `ControllerRenderProps` rather than left at its
+ * default. Without it `value` widens to the union of every field type in the
+ * form, so a call site spreading onto a `TextField` has to assert
+ * `value as string` — an assertion that keeps compiling if the field later
+ * changes type, which is the mistake the generic exists to catch.
+ */
+export type ManagedField<
+  TFieldValues extends FieldValues = FieldValues,
+  TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>,
+> = ControllerRenderProps<TFieldValues, TName> & {
+  /** Matches the label's `htmlFor`; spread onto the control or pass explicitly */
+  id: string;
+};
+
+export interface FormFieldManagedProps<
+  TFieldValues extends FieldValues = FieldValues,
+  TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>,
+> extends Omit<FormFieldProps, "children" | "error" | "htmlFor"> {
+  /** Field path in the form values; infers the field's value type */
+  name: TName;
+  /** Form control; falls back to the surrounding `useFormContext()` when omitted */
+  control?: Control<TFieldValues>;
+  /** Validation rules passed through to react-hook-form */
+  rules?: RegisterOptions<TFieldValues, TName>;
+  /** Renders the control from the wired field */
+  children: (
+    field: ManagedField<TFieldValues, TName>,
+    fieldState: ControllerFieldState,
+  ) => ReactNode;
+}
+
+/**
+ * `FormField` with its react-hook-form wiring already done: the control's
+ * value/onChange/onBlur/ref, the label association, and the error message.
+ *
+ * Uses `useController` rather than `register` because `register` only works on
+ * controls that render a native input. `TextField` and `Textarea` do;
+ * `Checkbox`, `Toggle` and `Select` are Radix-backed, where the ref would land
+ * on the trigger button and the change callback is `onCheckedChange` /
+ * `onValueChange`, so `register` binds nothing and the field silently keeps its
+ * default. `useController` works for all of them.
+ *
+ * The control is supplied through a render prop rather than cloned, because the
+ * prop a control listens on is the one thing that genuinely differs between
+ * them — worth seeing at the call site, and impossible to type if hidden.
+ *
+ * Pass `control` and both type parameters infer, so `field.value` is the type
+ * of that one field and spreads onto a control without a cast:
+ *
+ * ```tsx
+ * <FormFieldManaged control={methods.control} name="email" label="Email">
+ *   {(field) => <TextField {...field} />}
+ * </FormFieldManaged>
+ * ```
+ *
+ * Taking `control` from context instead means naming both parameters. Supplying
+ * only the first — `<FormFieldManaged<Values> name="email">` — leaves `TName` at
+ * its default and widens `field.value` to a union of every field in the form,
+ * because TypeScript stops inferring the rest once any type argument is given
+ * explicitly:
+ *
+ * ```tsx
+ * <FormFieldManaged<Values, "email"> name="email" label="Email">
+ *   {(field) => <TextField {...field} />}
+ * </FormFieldManaged>
+ * ```
+ */
+export const FormFieldManaged = <
+  TFieldValues extends FieldValues = FieldValues,
+  TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>,
+>({
+  name,
+  control,
+  rules,
+  children,
+  ...fieldProps
+}: FormFieldManagedProps<TFieldValues, TName>) => {
+  const id = useId();
+  const { field, fieldState } = useController<TFieldValues, TName>({
+    name,
+    control,
+    rules,
+  });
+
+  return (
+    <FormField {...fieldProps} htmlFor={id} error={fieldState.error?.message}>
+      {children({ ...field, id }, fieldState)}
+    </FormField>
+  );
+};

package/index.ts

@@ -0,0 +1,5 @@
+export { FormFieldManaged } from "./form-field-managed.js";
+export type {
+  FormFieldManagedProps,
+  ManagedField,
+} from "./form-field-managed.js";

package/package.json

@@ -1,6 +1,64 @@
 {
   "name": "@behivetech/forms.form-field-managed",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.4",
+  "license": "MIT",
+  "type": "module",
+  "private": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "index.ts",
+    "form-field-managed.tsx",
+    "form-field-managed.module.scss",
+    "*.example.tsx",
+    "docs.json"
+  ],
+  "registry": {
+    "status": "stable",
+    "tags": []
+  },
+  "dependencies": {
+    "@behivetech/forms.form-field": "0.3.2",
+    "@behivetech/forms.form-provider": "0.1.4"
+  },
+  "peerDependencies": {
+    "react": "^19.2.7",
+    "react-dom": "^19.2.7"
+  },
+  "devDependencies": {
+    "@types/react": "19.2.17",
+    "@types/react-dom": "19.2.3",
+    "eslint": "^9.39.5",
+    "tsup": "^8.5.1",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.10",
+    "@behivetech/atoms.text-field": "0.3.2",
+    "@behivetech/atoms.toggle": "0.4.2",
+    "@bht-component-registry/env": "0.1.0",
+    "@behivetech/atoms.select": "0.4.2"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/behivetech/bht-galaxy.git",
+    "directory": "registry/behivetech/forms/form-field-managed"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "build": "tsup && bht-registry-docgen",
+    "dev": "tsup --watch",
+    "lint": "eslint . --max-warnings 0",
+    "check-types": "tsc --noEmit",
+    "test": "vitest run"
+  }
 }