@nucleux/form 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nucleux
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,26 @@
+# @nucleux/form
+
+Accessible form primitives — Nucleux agentic UI for React.
+
+Part of **[Nucleux](https://github.com/intelligaia-open-labs/nucleux)** — agentic UI components for React. Install a single component, or the full kit via [`@nucleux/react`](https://www.npmjs.com/package/@nucleux/react).
+
+## Install
+
+```bash
+pnpm add @nucleux/form @nucleux/tokens
+```
+
+`react` / `react-dom` are peer dependencies.
+
+## Usage
+
+```tsx
+import { Form } from "@nucleux/form";
+```
+
+Requires the theme once in your app: `import "@nucleux/tokens/styles.css";`
+and the Tailwind preset from `@nucleux/tokens/preset`.
+
+## License
+
+MIT © Nucleux

package/dist/index.cjs

@@ -0,0 +1,115 @@
+"use client";
+'use strict';
+
+var React = require('react');
+var reactHookForm = require('react-hook-form');
+var utils = require('@nucleux/utils');
+var jsxRuntime = require('react/jsx-runtime');
+
+function _interopNamespace(e) {
+  if (e && e.__esModule) return e;
+  var n = Object.create(null);
+  if (e) {
+    Object.keys(e).forEach(function (k) {
+      if (k !== 'default') {
+        var d = Object.getOwnPropertyDescriptor(e, k);
+        Object.defineProperty(n, k, d.get ? d : {
+          enumerable: true,
+          get: function () { return e[k]; }
+        });
+      }
+    });
+  }
+  n.default = e;
+  return Object.freeze(n);
+}
+
+var React__namespace = /*#__PURE__*/_interopNamespace(React);
+
+// src/index.tsx
+var Form = reactHookForm.FormProvider;
+var FormFieldContext = React__namespace.createContext({});
+var FormField = (props) => /* @__PURE__ */ jsxRuntime.jsx(FormFieldContext.Provider, { value: { name: props.name }, children: /* @__PURE__ */ jsxRuntime.jsx(reactHookForm.Controller, { ...props }) });
+var FormItemContext = React__namespace.createContext({});
+function useFormField() {
+  const fieldContext = React__namespace.useContext(FormFieldContext);
+  const itemContext = React__namespace.useContext(FormItemContext);
+  const { getFieldState, formState } = reactHookForm.useFormContext();
+  if (!fieldContext?.name) throw new Error("useFormField must be used within a <FormField>");
+  const fieldState = getFieldState(fieldContext.name, formState);
+  const { id } = itemContext;
+  return {
+    id,
+    name: fieldContext.name,
+    formItemId: `${id}-form-item`,
+    formDescriptionId: `${id}-form-item-description`,
+    formMessageId: `${id}-form-item-message`,
+    ...fieldState
+  };
+}
+var FormItem = React__namespace.forwardRef(
+  ({ className, ...props }, ref) => {
+    const id = React__namespace.useId();
+    return /* @__PURE__ */ jsxRuntime.jsx(FormItemContext.Provider, { value: { id }, children: /* @__PURE__ */ jsxRuntime.jsx("div", { ref, className: utils.cn("space-y-2", className), ...props }) });
+  }
+);
+FormItem.displayName = "FormItem";
+var FormLabel = React__namespace.forwardRef(
+  ({ className, ...props }, ref) => {
+    const { error, formItemId } = useFormField();
+    return /* @__PURE__ */ jsxRuntime.jsx(
+      "label",
+      {
+        ref,
+        htmlFor: formItemId,
+        className: utils.cn("text-sm font-medium leading-none text-foreground", error && "text-destructive", className),
+        ...props
+      }
+    );
+  }
+);
+FormLabel.displayName = "FormLabel";
+function FormControl({ children }) {
+  const { error, formItemId, formDescriptionId, formMessageId } = useFormField();
+  return React__namespace.cloneElement(children, {
+    id: formItemId,
+    "aria-describedby": error ? `${formDescriptionId} ${formMessageId}` : formDescriptionId,
+    "aria-invalid": error ? true : void 0
+  });
+}
+var FormDescription = React__namespace.forwardRef(
+  ({ className, ...props }, ref) => {
+    const { formDescriptionId } = useFormField();
+    return /* @__PURE__ */ jsxRuntime.jsx("p", { ref, id: formDescriptionId, className: utils.cn("text-sm text-muted-foreground", className), ...props });
+  }
+);
+FormDescription.displayName = "FormDescription";
+var FormMessage = React__namespace.forwardRef(
+  ({ className, children, ...props }, ref) => {
+    const { error, formMessageId } = useFormField();
+    const body = error ? String(error.message ?? "") : children;
+    if (!body) return null;
+    return /* @__PURE__ */ jsxRuntime.jsx(
+      "p",
+      {
+        ref,
+        id: formMessageId,
+        className: utils.cn("text-sm font-medium text-destructive", className),
+        ...props,
+        children: body
+      }
+    );
+  }
+);
+FormMessage.displayName = "FormMessage";
+
+exports.Form = Form;
+exports.FormControl = FormControl;
+exports.FormDescription = FormDescription;
+exports.FormField = FormField;
+exports.FormItem = FormItem;
+exports.FormLabel = FormLabel;
+exports.FormMessage = FormMessage;
+exports.useFormField = useFormField;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.tsx"],"names":["FormProvider","React","jsx","Controller","useFormContext","cn"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;AAYO,IAAM,IAAA,GAAOA;AAKpB,IAAM,gBAAA,GAAyBC,gBAAA,CAAA,aAAA,CAAqC,EAA2B,CAAA;AAGxF,IAAM,YAAY,CAIvB,KAAA,qBAEAC,cAAA,CAAC,gBAAA,CAAiB,UAAjB,EAA0B,KAAA,EAAO,EAAE,IAAA,EAAM,MAAM,IAAA,EAAK,EACnD,yCAACC,wBAAA,EAAA,EAAY,GAAG,OAAO,CAAA,EACzB;AAMF,IAAM,eAAA,GAAwBF,gBAAA,CAAA,aAAA,CAAoC,EAA0B,CAAA;AAGrF,SAAS,YAAA,GAAe;AAC7B,EAAA,MAAM,YAAA,GAAqBA,4BAAW,gBAAgB,CAAA;AACtD,EAAA,MAAM,WAAA,GAAoBA,4BAAW,eAAe,CAAA;AACpD,EAAA,MAAM,EAAE,aAAA,EAAe,SAAA,EAAU,GAAIG,4BAAA,EAAe;AAEpD,EAAA,IAAI,CAAC,YAAA,EAAc,IAAA,EAAM,MAAM,IAAI,MAAM,gDAAgD,CAAA;AACzF,EAAA,MAAM,UAAA,GAAa,aAAA,CAAc,YAAA,CAAa,IAAA,EAAM,SAAS,CAAA;AAC7D,EAAA,MAAM,EAAE,IAAG,GAAI,WAAA;AAEf,EAAA,OAAO;AAAA,IACL,EAAA;AAAA,IACA,MAAM,YAAA,CAAa,IAAA;AAAA,IACnB,UAAA,EAAY,GAAG,EAAE,CAAA,UAAA,CAAA;AAAA,IACjB,iBAAA,EAAmB,GAAG,EAAE,CAAA,sBAAA,CAAA;AAAA,IACxB,aAAA,EAAe,GAAG,EAAE,CAAA,kBAAA,CAAA;AAAA,IACpB,GAAG;AAAA,GACL;AACF;AAGO,IAAM,QAAA,GAAiBH,gBAAA,CAAA,UAAA;AAAA,EAC5B,CAAC,EAAE,SAAA,EAAW,GAAG,KAAA,IAAS,GAAA,KAAQ;AAChC,IAAA,MAAM,KAAWA,gBAAA,CAAA,KAAA,EAAM;AACvB,IAAA,sCACG,eAAA,CAAgB,QAAA,EAAhB,EAAyB,KAAA,EAAO,EAAE,IAAG,EACpC,QAAA,kBAAAC,cAAA,CAAC,KAAA,EAAA,EAAI,GAAA,EAAU,WAAWG,QAAA,CAAG,WAAA,EAAa,SAAS,CAAA,EAAI,GAAG,OAAO,CAAA,EACnE,CAAA;AAAA,EAEJ;AACF;AACA,QAAA,CAAS,WAAA,GAAc,UAAA;AAGhB,IAAM,SAAA,GAAkBJ,gBAAA,CAAA,UAAA;AAAA,EAC7B,CAAC,EAAE,SAAA,EAAW,GAAG,KAAA,IAAS,GAAA,KAAQ;AAChC,IAAA,MAAM,EAAE,KAAA,EAAO,UAAA,EAAW,GAAI,YAAA,EAAa;AAC3C,IAAA,uBACEC,cAAA;AAAA,MAAC,OAAA;AAAA,MAAA;AAAA,QACC,GAAA;AAAA,QACA,OAAA,EAAS,UAAA;AAAA,QACT,SAAA,EAAWG,QAAA,CAAG,kDAAA,EAAoD,KAAA,IAAS,oBAAoB,SAAS,CAAA;AAAA,QACvG,GAAG;AAAA;AAAA,KACN;AAAA,EAEJ;AACF;AACA,SAAA,CAAU,WAAA,GAAc,WAAA;AAGjB,SAAS,WAAA,CAAY,EAAE,QAAA,EAAS,EAAqC;AAC1E,EAAA,MAAM,EAAE,KAAA,EAAO,UAAA,EAAY,iBAAA,EAAmB,aAAA,KAAkB,YAAA,EAAa;AAC7E,EAAA,OAAaJ,8BAAa,QAAA,EAAU;AAAA,IAClC,EAAA,EAAI,UAAA;AAAA,IACJ,oBAAoB,KAAA,GAAQ,CAAA,EAAG,iBAAiB,CAAA,CAAA,EAAI,aAAa,CAAA,CAAA,GAAK,iBAAA;AAAA,IACtE,cAAA,EAAgB,QAAQ,IAAA,GAAO;AAAA,GACK,CAAA;AACxC;AAGO,IAAM,eAAA,GAAwBA,gBAAA,CAAA,UAAA;AAAA,EACnC,CAAC,EAAE,SAAA,EAAW,GAAG,KAAA,IAAS,GAAA,KAAQ;AAChC,IAAA,MAAM,EAAE,iBAAA,EAAkB,GAAI,YAAA,EAAa;AAC3C,IAAA,uBACEC,cAAA,CAAC,GAAA,EAAA,EAAE,GAAA,EAAU,EAAA,EAAI,iBAAA,EAAmB,SAAA,EAAWG,QAAA,CAAG,+BAAA,EAAiC,SAAS,CAAA,EAAI,GAAG,KAAA,EAAO,CAAA;AAAA,EAE9G;AACF;AACA,eAAA,CAAgB,WAAA,GAAc,iBAAA;AAGvB,IAAM,WAAA,GAAoBJ,gBAAA,CAAA,UAAA;AAAA,EAC/B,CAAC,EAAE,SAAA,EAAW,UAAU,GAAG,KAAA,IAAS,GAAA,KAAQ;AAC1C,IAAA,MAAM,EAAE,KAAA,EAAO,aAAA,EAAc,GAAI,YAAA,EAAa;AAC9C,IAAA,MAAM,OAAO,KAAA,GAAQ,MAAA,CAAO,KAAA,CAAM,OAAA,IAAW,EAAE,CAAA,GAAI,QAAA;AACnD,IAAA,IAAI,CAAC,MAAM,OAAO,IAAA;AAClB,IAAA,uBACEC,cAAA;AAAA,MAAC,GAAA;AAAA,MAAA;AAAA,QACC,GAAA;AAAA,QACA,EAAA,EAAI,aAAA;AAAA,QACJ,SAAA,EAAWG,QAAA,CAAG,sCAAA,EAAwC,SAAS,CAAA;AAAA,QAC9D,GAAG,KAAA;AAAA,QAEH,QAAA,EAAA;AAAA;AAAA,KACH;AAAA,EAEJ;AACF;AACA,WAAA,CAAY,WAAA,GAAc,aAAA","file":"index.cjs","sourcesContent":["import * as React from \"react\";\nimport {\n  Controller,\n  FormProvider,\n  useFormContext,\n  type ControllerProps,\n  type FieldPath,\n  type FieldValues,\n} from \"react-hook-form\";\nimport { cn } from \"@nucleux/utils\";\n\n/** The form root — a re-export of react-hook-form's FormProvider. */\nexport const Form = FormProvider;\n\ninterface FormFieldContextValue {\n  name: string;\n}\nconst FormFieldContext = React.createContext<FormFieldContextValue>({} as FormFieldContextValue);\n\n/** Connects a single field to react-hook-form and the surrounding Form context. */\nexport const FormField = <\n  TFieldValues extends FieldValues = FieldValues,\n  TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>,\n>(\n  props: ControllerProps<TFieldValues, TName>,\n) => (\n  <FormFieldContext.Provider value={{ name: props.name }}>\n    <Controller {...props} />\n  </FormFieldContext.Provider>\n);\n\ninterface FormItemContextValue {\n  id: string;\n}\nconst FormItemContext = React.createContext<FormItemContextValue>({} as FormItemContextValue);\n\n/** Reads field state + generated ids for the current {@link FormField}/{@link FormItem}. */\nexport function useFormField() {\n  const fieldContext = React.useContext(FormFieldContext);\n  const itemContext = React.useContext(FormItemContext);\n  const { getFieldState, formState } = useFormContext();\n\n  if (!fieldContext?.name) throw new Error(\"useFormField must be used within a <FormField>\");\n  const fieldState = getFieldState(fieldContext.name, formState);\n  const { id } = itemContext;\n\n  return {\n    id,\n    name: fieldContext.name,\n    formItemId: `${id}-form-item`,\n    formDescriptionId: `${id}-form-item-description`,\n    formMessageId: `${id}-form-item-message`,\n    ...fieldState,\n  };\n}\n\n/** Groups a label, control, description, and message; supplies a shared id. */\nexport const FormItem = React.forwardRef<HTMLDivElement, React.HTMLAttributes<HTMLDivElement>>(\n  ({ className, ...props }, ref) => {\n    const id = React.useId();\n    return (\n      <FormItemContext.Provider value={{ id }}>\n        <div ref={ref} className={cn(\"space-y-2\", className)} {...props} />\n      </FormItemContext.Provider>\n    );\n  },\n);\nFormItem.displayName = \"FormItem\";\n\n/** A label wired to its control; turns destructive on validation error. */\nexport const FormLabel = React.forwardRef<HTMLLabelElement, React.LabelHTMLAttributes<HTMLLabelElement>>(\n  ({ className, ...props }, ref) => {\n    const { error, formItemId } = useFormField();\n    return (\n      <label\n        ref={ref}\n        htmlFor={formItemId}\n        className={cn(\"text-sm font-medium leading-none text-foreground\", error && \"text-destructive\", className)}\n        {...props}\n      />\n    );\n  },\n);\nFormLabel.displayName = \"FormLabel\";\n\n/** Wraps the field control, injecting id + aria wiring from the field state. */\nexport function FormControl({ children }: { children: React.ReactElement }) {\n  const { error, formItemId, formDescriptionId, formMessageId } = useFormField();\n  return React.cloneElement(children, {\n    id: formItemId,\n    \"aria-describedby\": error ? `${formDescriptionId} ${formMessageId}` : formDescriptionId,\n    \"aria-invalid\": error ? true : undefined,\n  } as React.HTMLAttributes<HTMLElement>);\n}\n\n/** Helper text describing the field. */\nexport const FormDescription = React.forwardRef<HTMLParagraphElement, React.HTMLAttributes<HTMLParagraphElement>>(\n  ({ className, ...props }, ref) => {\n    const { formDescriptionId } = useFormField();\n    return (\n      <p ref={ref} id={formDescriptionId} className={cn(\"text-sm text-muted-foreground\", className)} {...props} />\n    );\n  },\n);\nFormDescription.displayName = \"FormDescription\";\n\n/** Renders the field's validation error (or explicit children). */\nexport const FormMessage = React.forwardRef<HTMLParagraphElement, React.HTMLAttributes<HTMLParagraphElement>>(\n  ({ className, children, ...props }, ref) => {\n    const { error, formMessageId } = useFormField();\n    const body = error ? String(error.message ?? \"\") : children;\n    if (!body) return null;\n    return (\n      <p\n        ref={ref}\n        id={formMessageId}\n        className={cn(\"text-sm font-medium text-destructive\", className)}\n        {...props}\n      >\n        {body}\n      </p>\n    );\n  },\n);\nFormMessage.displayName = \"FormMessage\";\n"]}

package/dist/index.d.cts

@@ -0,0 +1,35 @@
+import * as react_hook_form from 'react-hook-form';
+import { FieldValues, FieldPath, ControllerProps } from 'react-hook-form';
+import * as React from 'react';
+
+/** The form root — a re-export of react-hook-form's FormProvider. */
+declare const Form: <TFieldValues extends FieldValues, TContext = any, TTransformedValues = TFieldValues>({ children, watch, getValues, getErrors, getFieldState, setError, clearErrors, setValue, setValues, trigger, formState, resetField, reset, resetDefaultValues, handleSubmit, unregister, control, register, setFocus, subscribe, }: react_hook_form.FormProviderProps<TFieldValues, TContext, TTransformedValues>) => React.JSX.Element;
+/** Connects a single field to react-hook-form and the surrounding Form context. */
+declare const FormField: <TFieldValues extends FieldValues = FieldValues, TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>>(props: ControllerProps<TFieldValues, TName>) => React.JSX.Element;
+/** Reads field state + generated ids for the current {@link FormField}/{@link FormItem}. */
+declare function useFormField(): {
+    invalid: boolean;
+    isDirty: boolean;
+    isTouched: boolean;
+    isValidating: boolean;
+    error?: react_hook_form.FieldError | undefined;
+    id: string;
+    name: string;
+    formItemId: string;
+    formDescriptionId: string;
+    formMessageId: string;
+};
+/** Groups a label, control, description, and message; supplies a shared id. */
+declare const FormItem: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLDivElement> & React.RefAttributes<HTMLDivElement>>;
+/** A label wired to its control; turns destructive on validation error. */
+declare const FormLabel: React.ForwardRefExoticComponent<React.LabelHTMLAttributes<HTMLLabelElement> & React.RefAttributes<HTMLLabelElement>>;
+/** Wraps the field control, injecting id + aria wiring from the field state. */
+declare function FormControl({ children }: {
+    children: React.ReactElement;
+}): React.ReactElement<any, string | React.JSXElementConstructor<any>>;
+/** Helper text describing the field. */
+declare const FormDescription: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLParagraphElement> & React.RefAttributes<HTMLParagraphElement>>;
+/** Renders the field's validation error (or explicit children). */
+declare const FormMessage: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLParagraphElement> & React.RefAttributes<HTMLParagraphElement>>;
+
+export { Form, FormControl, FormDescription, FormField, FormItem, FormLabel, FormMessage, useFormField };

package/dist/index.d.ts

@@ -0,0 +1,35 @@
+import * as react_hook_form from 'react-hook-form';
+import { FieldValues, FieldPath, ControllerProps } from 'react-hook-form';
+import * as React from 'react';
+
+/** The form root — a re-export of react-hook-form's FormProvider. */
+declare const Form: <TFieldValues extends FieldValues, TContext = any, TTransformedValues = TFieldValues>({ children, watch, getValues, getErrors, getFieldState, setError, clearErrors, setValue, setValues, trigger, formState, resetField, reset, resetDefaultValues, handleSubmit, unregister, control, register, setFocus, subscribe, }: react_hook_form.FormProviderProps<TFieldValues, TContext, TTransformedValues>) => React.JSX.Element;
+/** Connects a single field to react-hook-form and the surrounding Form context. */
+declare const FormField: <TFieldValues extends FieldValues = FieldValues, TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>>(props: ControllerProps<TFieldValues, TName>) => React.JSX.Element;
+/** Reads field state + generated ids for the current {@link FormField}/{@link FormItem}. */
+declare function useFormField(): {
+    invalid: boolean;
+    isDirty: boolean;
+    isTouched: boolean;
+    isValidating: boolean;
+    error?: react_hook_form.FieldError | undefined;
+    id: string;
+    name: string;
+    formItemId: string;
+    formDescriptionId: string;
+    formMessageId: string;
+};
+/** Groups a label, control, description, and message; supplies a shared id. */
+declare const FormItem: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLDivElement> & React.RefAttributes<HTMLDivElement>>;
+/** A label wired to its control; turns destructive on validation error. */
+declare const FormLabel: React.ForwardRefExoticComponent<React.LabelHTMLAttributes<HTMLLabelElement> & React.RefAttributes<HTMLLabelElement>>;
+/** Wraps the field control, injecting id + aria wiring from the field state. */
+declare function FormControl({ children }: {
+    children: React.ReactElement;
+}): React.ReactElement<any, string | React.JSXElementConstructor<any>>;
+/** Helper text describing the field. */
+declare const FormDescription: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLParagraphElement> & React.RefAttributes<HTMLParagraphElement>>;
+/** Renders the field's validation error (or explicit children). */
+declare const FormMessage: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLParagraphElement> & React.RefAttributes<HTMLParagraphElement>>;
+
+export { Form, FormControl, FormDescription, FormField, FormItem, FormLabel, FormMessage, useFormField };

package/dist/index.js

@@ -0,0 +1,86 @@
+"use client";
+import * as React from 'react';
+import { useFormContext, FormProvider, Controller } from 'react-hook-form';
+import { cn } from '@nucleux/utils';
+import { jsx } from 'react/jsx-runtime';
+
+// src/index.tsx
+var Form = FormProvider;
+var FormFieldContext = React.createContext({});
+var FormField = (props) => /* @__PURE__ */ jsx(FormFieldContext.Provider, { value: { name: props.name }, children: /* @__PURE__ */ jsx(Controller, { ...props }) });
+var FormItemContext = React.createContext({});
+function useFormField() {
+  const fieldContext = React.useContext(FormFieldContext);
+  const itemContext = React.useContext(FormItemContext);
+  const { getFieldState, formState } = useFormContext();
+  if (!fieldContext?.name) throw new Error("useFormField must be used within a <FormField>");
+  const fieldState = getFieldState(fieldContext.name, formState);
+  const { id } = itemContext;
+  return {
+    id,
+    name: fieldContext.name,
+    formItemId: `${id}-form-item`,
+    formDescriptionId: `${id}-form-item-description`,
+    formMessageId: `${id}-form-item-message`,
+    ...fieldState
+  };
+}
+var FormItem = React.forwardRef(
+  ({ className, ...props }, ref) => {
+    const id = React.useId();
+    return /* @__PURE__ */ jsx(FormItemContext.Provider, { value: { id }, children: /* @__PURE__ */ jsx("div", { ref, className: cn("space-y-2", className), ...props }) });
+  }
+);
+FormItem.displayName = "FormItem";
+var FormLabel = React.forwardRef(
+  ({ className, ...props }, ref) => {
+    const { error, formItemId } = useFormField();
+    return /* @__PURE__ */ jsx(
+      "label",
+      {
+        ref,
+        htmlFor: formItemId,
+        className: cn("text-sm font-medium leading-none text-foreground", error && "text-destructive", className),
+        ...props
+      }
+    );
+  }
+);
+FormLabel.displayName = "FormLabel";
+function FormControl({ children }) {
+  const { error, formItemId, formDescriptionId, formMessageId } = useFormField();
+  return React.cloneElement(children, {
+    id: formItemId,
+    "aria-describedby": error ? `${formDescriptionId} ${formMessageId}` : formDescriptionId,
+    "aria-invalid": error ? true : void 0
+  });
+}
+var FormDescription = React.forwardRef(
+  ({ className, ...props }, ref) => {
+    const { formDescriptionId } = useFormField();
+    return /* @__PURE__ */ jsx("p", { ref, id: formDescriptionId, className: cn("text-sm text-muted-foreground", className), ...props });
+  }
+);
+FormDescription.displayName = "FormDescription";
+var FormMessage = React.forwardRef(
+  ({ className, children, ...props }, ref) => {
+    const { error, formMessageId } = useFormField();
+    const body = error ? String(error.message ?? "") : children;
+    if (!body) return null;
+    return /* @__PURE__ */ jsx(
+      "p",
+      {
+        ref,
+        id: formMessageId,
+        className: cn("text-sm font-medium text-destructive", className),
+        ...props,
+        children: body
+      }
+    );
+  }
+);
+FormMessage.displayName = "FormMessage";
+
+export { Form, FormControl, FormDescription, FormField, FormItem, FormLabel, FormMessage, useFormField };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.tsx"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["import * as React from \"react\";\nimport {\n  Controller,\n  FormProvider,\n  useFormContext,\n  type ControllerProps,\n  type FieldPath,\n  type FieldValues,\n} from \"react-hook-form\";\nimport { cn } from \"@nucleux/utils\";\n\n/** The form root — a re-export of react-hook-form's FormProvider. */\nexport const Form = FormProvider;\n\ninterface FormFieldContextValue {\n  name: string;\n}\nconst FormFieldContext = React.createContext<FormFieldContextValue>({} as FormFieldContextValue);\n\n/** Connects a single field to react-hook-form and the surrounding Form context. */\nexport const FormField = <\n  TFieldValues extends FieldValues = FieldValues,\n  TName extends FieldPath<TFieldValues> = FieldPath<TFieldValues>,\n>(\n  props: ControllerProps<TFieldValues, TName>,\n) => (\n  <FormFieldContext.Provider value={{ name: props.name }}>\n    <Controller {...props} />\n  </FormFieldContext.Provider>\n);\n\ninterface FormItemContextValue {\n  id: string;\n}\nconst FormItemContext = React.createContext<FormItemContextValue>({} as FormItemContextValue);\n\n/** Reads field state + generated ids for the current {@link FormField}/{@link FormItem}. */\nexport function useFormField() {\n  const fieldContext = React.useContext(FormFieldContext);\n  const itemContext = React.useContext(FormItemContext);\n  const { getFieldState, formState } = useFormContext();\n\n  if (!fieldContext?.name) throw new Error(\"useFormField must be used within a <FormField>\");\n  const fieldState = getFieldState(fieldContext.name, formState);\n  const { id } = itemContext;\n\n  return {\n    id,\n    name: fieldContext.name,\n    formItemId: `${id}-form-item`,\n    formDescriptionId: `${id}-form-item-description`,\n    formMessageId: `${id}-form-item-message`,\n    ...fieldState,\n  };\n}\n\n/** Groups a label, control, description, and message; supplies a shared id. */\nexport const FormItem = React.forwardRef<HTMLDivElement, React.HTMLAttributes<HTMLDivElement>>(\n  ({ className, ...props }, ref) => {\n    const id = React.useId();\n    return (\n      <FormItemContext.Provider value={{ id }}>\n        <div ref={ref} className={cn(\"space-y-2\", className)} {...props} />\n      </FormItemContext.Provider>\n    );\n  },\n);\nFormItem.displayName = \"FormItem\";\n\n/** A label wired to its control; turns destructive on validation error. */\nexport const FormLabel = React.forwardRef<HTMLLabelElement, React.LabelHTMLAttributes<HTMLLabelElement>>(\n  ({ className, ...props }, ref) => {\n    const { error, formItemId } = useFormField();\n    return (\n      <label\n        ref={ref}\n        htmlFor={formItemId}\n        className={cn(\"text-sm font-medium leading-none text-foreground\", error && \"text-destructive\", className)}\n        {...props}\n      />\n    );\n  },\n);\nFormLabel.displayName = \"FormLabel\";\n\n/** Wraps the field control, injecting id + aria wiring from the field state. */\nexport function FormControl({ children }: { children: React.ReactElement }) {\n  const { error, formItemId, formDescriptionId, formMessageId } = useFormField();\n  return React.cloneElement(children, {\n    id: formItemId,\n    \"aria-describedby\": error ? `${formDescriptionId} ${formMessageId}` : formDescriptionId,\n    \"aria-invalid\": error ? true : undefined,\n  } as React.HTMLAttributes<HTMLElement>);\n}\n\n/** Helper text describing the field. */\nexport const FormDescription = React.forwardRef<HTMLParagraphElement, React.HTMLAttributes<HTMLParagraphElement>>(\n  ({ className, ...props }, ref) => {\n    const { formDescriptionId } = useFormField();\n    return (\n      <p ref={ref} id={formDescriptionId} className={cn(\"text-sm text-muted-foreground\", className)} {...props} />\n    );\n  },\n);\nFormDescription.displayName = \"FormDescription\";\n\n/** Renders the field's validation error (or explicit children). */\nexport const FormMessage = React.forwardRef<HTMLParagraphElement, React.HTMLAttributes<HTMLParagraphElement>>(\n  ({ className, children, ...props }, ref) => {\n    const { error, formMessageId } = useFormField();\n    const body = error ? String(error.message ?? \"\") : children;\n    if (!body) return null;\n    return (\n      <p\n        ref={ref}\n        id={formMessageId}\n        className={cn(\"text-sm font-medium text-destructive\", className)}\n        {...props}\n      >\n        {body}\n      </p>\n    );\n  },\n);\nFormMessage.displayName = \"FormMessage\";\n"]}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@nucleux/form",
+  "version": "0.2.0",
+  "type": "module",
+  "sideEffects": false,
+  "description": "Accessible form primitives — Nucleux agentic UI for React.",
+  "keywords": [
+    "nucleux",
+    "react",
+    "ui",
+    "components",
+    "agentic",
+    "ai",
+    "tailwind",
+    "form"
+  ],
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "peerDependencies": {
+    "react": ">=18",
+    "react-dom": ">=18"
+  },
+  "dependencies": {
+    "react-hook-form": "^7.54.2",
+    "@nucleux/utils": "0.2.0"
+  },
+  "devDependencies": {
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.2",
+    "@types/react": "^18.3.18",
+    "react": "^18.3.1",
+    "lucide-react": "^0.469.0",
+    "zod": "^3.24.1",
+    "@hookform/resolvers": "^3.10.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/intelligaia-open-labs/nucleux.git",
+    "directory": "packages/form"
+  },
+  "homepage": "https://github.com/intelligaia-open-labs/nucleux#readme",
+  "scripts": {
+    "build": "tsup"
+  }
+}