@pixpilot/formily-shadcn 0.10.0 → 0.11.1

package/README.md

@@ -56,7 +56,11 @@ const schema = {
 
 function MyForm() {
   return (
-    <Form form={form} onSubmit={(values) => console.log(values)}>
+    <Form
+      form={form}
+      layout={{ density: 'comfortable' }}
+      onSubmit={(values) => console.log(values)}
+    >
       <SchemaField schema={schema} />
       <button type="submit">Submit</button>
     </Form>
@@ -149,6 +153,28 @@ import {
 - `x-component-props`: Props passed to the component
 - `x-decorator-props`: Props passed to the decorator
 
+## Documentation
+
+### [Form Layout Options](./docs/form-layout-options.md)
+
+Learn how to configure form layout and visual settings using the `FormLayoutOptions` interface:
+
+- **Density** - Control spacing between form elements (compact, normal, comfortable, responsive)
+- **Description Placement** - Configure where field descriptions appear (top, bottom, popover)
+- **Label Placement** - Set label position relative to inputs (top, bottom, start, end)
+- **Custom Classes** - Apply custom CSS classes to form elements
+
+[Read the full documentation →](./docs/form-layout-options.md)
+
+### [JSON Schema Form: Headless vs Default Pattern](./docs/json-schema-form-headless-vs-default.md)
+
+Learn about the difference between `JsonSchemaFormRenderer` (headless) and `JsonSchemaForm` (batteries-included) components:
+
+- **`JsonSchemaFormRenderer`** - Pure, headless component that requires you to provide all components explicitly. Ideal for custom component registries and bundle size optimization.
+- **`JsonSchemaForm`** - Convenience wrapper that comes pre-loaded with all standard components (Slider, Combobox, TagsInput, etc.). Perfect for getting started quickly.
+
+[Read the full documentation →](./docs/json-schema-form-headless-vs-default.md)
+
 ## API Reference
 
 ### createForm

package/dist/components/checkbox.d.cts

@@ -1,4 +1,4 @@
-import * as react1 from "react";
+import * as react0 from "react";
 import * as _radix_ui_react_checkbox0 from "@radix-ui/react-checkbox";
 
 //#region src/components/checkbox.d.ts
@@ -6,6 +6,6 @@ import * as _radix_ui_react_checkbox0 from "@radix-ui/react-checkbox";
  * Formily-connected Checkbox component
  * Maps Formily field checked state to shadcn Checkbox
  */
-declare const Checkbox: react1.ForwardRefExoticComponent<Omit<Partial<_radix_ui_react_checkbox0.CheckboxProps & react1.RefAttributes<HTMLButtonElement>>, "ref"> & react1.RefAttributes<unknown>>;
+declare const Checkbox: react0.ForwardRefExoticComponent<Omit<Partial<_radix_ui_react_checkbox0.CheckboxProps & react0.RefAttributes<HTMLButtonElement>>, "ref"> & react0.RefAttributes<unknown>>;
 //#endregion
 export { Checkbox };

package/dist/components/checkbox.d.ts

@@ -1,4 +1,4 @@
-import * as react0 from "react";
+import * as react5 from "react";
 import * as _radix_ui_react_checkbox0 from "@radix-ui/react-checkbox";
 
 //#region src/components/checkbox.d.ts
@@ -6,6 +6,6 @@ import * as _radix_ui_react_checkbox0 from "@radix-ui/react-checkbox";
  * Formily-connected Checkbox component
  * Maps Formily field checked state to shadcn Checkbox
  */
-declare const Checkbox: react0.ForwardRefExoticComponent<Omit<Partial<_radix_ui_react_checkbox0.CheckboxProps & react0.RefAttributes<HTMLButtonElement>>, "ref"> & react0.RefAttributes<unknown>>;
+declare const Checkbox: react5.ForwardRefExoticComponent<Omit<Partial<_radix_ui_react_checkbox0.CheckboxProps & react5.RefAttributes<HTMLButtonElement>>, "ref"> & react5.RefAttributes<unknown>>;
 //#endregion
 export { Checkbox };

package/dist/components/column.d.ts

@@ -1,5 +1,5 @@
 import React from "react";
-import * as react_jsx_runtime0 from "react/jsx-runtime";
+import * as react_jsx_runtime1 from "react/jsx-runtime";
 
 //#region src/components/column.d.ts
 interface IColumnProps {
@@ -36,6 +36,6 @@ interface IColumnProps {
 declare function Column({
   className,
   children
-}: IColumnProps): react_jsx_runtime0.JSX.Element;
+}: IColumnProps): react_jsx_runtime1.JSX.Element;
 //#endregion
 export { Column };

package/dist/components/context/context.d.cts

@@ -1,2 +1,2 @@
-import { FormContextStates } from "./form-context.cjs";
+import { FormContextStates, FormLayoutOptions } from "./form-context.cjs";
 import "react";

package/dist/components/context/context.d.ts

@@ -1,2 +1,2 @@
-import { FormContextStates } from "./form-context.js";
+import { FormContextStates, FormLayoutOptions } from "./form-context.js";
 import "react";

package/dist/components/context/form-context.d.cts

@@ -1,4 +1,5 @@
 import { FormSpace } from "../../types/form.cjs";
+import { DescriptionPlacement, LabelPlacement } from "../../types/form-item.cjs";
 import React from "react";
 import { FileUploadProgressCallBacks, IconProvider, RichTextEditorProps } from "@pixpilot/shadcn-ui";
 
@@ -25,14 +26,42 @@ interface FormConfigProps {
   fileUpload?: FomFileUpload;
   richTextEditor?: RichTextEditorProps;
 }
-interface FormContextStates extends FormSpace {
+/**
+ * Layout configuration options for form components.
+ * Groups all visual and layout-related settings.
+ */
+interface FormLayoutOptions {
+  /** Form density - affects spacing between elements */
+  density?: FormSpace['density'];
+  /** Default description placement for FormItem decorators */
+  descriptionPlacement?: DescriptionPlacement;
+  /** Default label placement for FormItem decorators */
+  labelPlacement?: LabelPlacement;
+  /** Custom class names for FormItem elements */
   itemProps?: {
-    className?: string;
+    classes?: {
+      label?: string;
+      description?: string;
+      inputWrapper?: string;
+      errorMessage?: string;
+    };
   };
-  objectContainerProps?: {
-    className?: string;
+  /** Custom class names for ObjectContainer elements */
+  objectContainer?: {
+    classes?: {
+      card?: string;
+      header?: string;
+      title?: string;
+      description?: string;
+      content?: string;
+    };
   };
+}
+interface FormContextStates {
+  /** Layout configuration options */
+  layout?: FormLayoutOptions;
+  /** Form-level configuration settings */
   settings?: FormConfigProps;
 }
 //#endregion
-export { FomFileUpload, FormConfigProps, FormContextStates };
+export { FomFileUpload, FormConfigProps, FormContextStates, FormLayoutOptions };

package/dist/components/context/form-context.d.ts

@@ -1,4 +1,5 @@
 import { FormSpace } from "../../types/form.js";
+import { DescriptionPlacement, LabelPlacement } from "../../types/form-item.js";
 import React from "react";
 import { FileUploadProgressCallBacks, IconProvider, RichTextEditorProps } from "@pixpilot/shadcn-ui";
 
@@ -25,14 +26,42 @@ interface FormConfigProps {
   fileUpload?: FomFileUpload;
   richTextEditor?: RichTextEditorProps;
 }
-interface FormContextStates extends FormSpace {
+/**
+ * Layout configuration options for form components.
+ * Groups all visual and layout-related settings.
+ */
+interface FormLayoutOptions {
+  /** Form density - affects spacing between elements */
+  density?: FormSpace['density'];
+  /** Default description placement for FormItem decorators */
+  descriptionPlacement?: DescriptionPlacement;
+  /** Default label placement for FormItem decorators */
+  labelPlacement?: LabelPlacement;
+  /** Custom class names for FormItem elements */
   itemProps?: {
-    className?: string;
+    classes?: {
+      label?: string;
+      description?: string;
+      inputWrapper?: string;
+      errorMessage?: string;
+    };
   };
-  objectContainerProps?: {
-    className?: string;
+  /** Custom class names for ObjectContainer elements */
+  objectContainer?: {
+    classes?: {
+      card?: string;
+      header?: string;
+      title?: string;
+      description?: string;
+      content?: string;
+    };
   };
+}
+interface FormContextStates {
+  /** Layout configuration options */
+  layout?: FormLayoutOptions;
+  /** Form-level configuration settings */
   settings?: FormConfigProps;
 }
 //#endregion
-export { FomFileUpload, FormConfigProps, FormContextStates };
+export { FomFileUpload, FormConfigProps, FormContextStates, FormLayoutOptions };

package/dist/components/context/index.d.cts

@@ -1,2 +1,2 @@
-import { FomFileUpload, FormConfigProps, FormContextStates } from "./form-context.cjs";
+import { FomFileUpload, FormConfigProps, FormContextStates, FormLayoutOptions } from "./form-context.cjs";
 import "./context.cjs";

package/dist/components/context/index.d.ts

@@ -1,2 +1,2 @@
-import { FomFileUpload, FormConfigProps, FormContextStates } from "./form-context.js";
+import { FomFileUpload, FormConfigProps, FormContextStates, FormLayoutOptions } from "./form-context.js";
 import "./context.js";

package/dist/components/date-picker.d.cts

@@ -1,11 +1,11 @@
-import * as react0 from "react";
+import * as react2 from "react";
 import { DatePickerProps } from "@pixpilot/shadcn-ui";
 
 //#region src/components/date-picker.d.ts
-declare const DatePicker: react0.ForwardRefExoticComponent<Partial<{
+declare const DatePicker: react2.ForwardRefExoticComponent<Partial<{
   value?: Date;
   onChange?: (date: Date | undefined) => void;
   placeholder?: string;
-} & Omit<DatePickerProps, "onSelect" | "selected" | "mode">> & react0.RefAttributes<unknown>>;
+} & Omit<DatePickerProps, "onSelect" | "selected" | "mode">> & react2.RefAttributes<unknown>>;
 //#endregion
 export { DatePicker };

package/dist/components/date-picker.d.ts

@@ -1,11 +1,11 @@
-import * as react2 from "react";
+import * as react16 from "react";
 import { DatePickerProps } from "@pixpilot/shadcn-ui";
 
 //#region src/components/date-picker.d.ts
-declare const DatePicker$1: react2.ForwardRefExoticComponent<Partial<{
+declare const DatePicker$1: react16.ForwardRefExoticComponent<Partial<{
   value?: Date;
   onChange?: (date: Date | undefined) => void;
   placeholder?: string;
-} & Omit<DatePickerProps, "onSelect" | "selected" | "mode">> & react2.RefAttributes<unknown>>;
+} & Omit<DatePickerProps, "onSelect" | "selected" | "mode">> & react16.RefAttributes<unknown>>;
 //#endregion
 export { DatePicker$1 as DatePicker };

package/dist/components/file-upload/file-upload-inline.d.cts

@@ -1,5 +1,5 @@
 import React from "react";
-import * as _pixpilot_shadcn_ui8 from "@pixpilot/shadcn-ui";
+import * as _pixpilot_shadcn_ui0 from "@pixpilot/shadcn-ui";
 
 //#region src/components/file-upload/file-upload-inline.d.ts
 
@@ -7,14 +7,14 @@ import * as _pixpilot_shadcn_ui8 from "@pixpilot/shadcn-ui";
  * Formily-connected FileUploadInline component
  * Automatically connects shadcn FileUploadInline to Formily field state
  */
-declare const FileUploadInline: React.ForwardRefExoticComponent<(Omit<Partial<_pixpilot_shadcn_ui8.FileUploadInlineBaseProps & {
+declare const FileUploadInline: React.ForwardRefExoticComponent<(Omit<Partial<_pixpilot_shadcn_ui0.FileUploadInlineBaseProps & {
   multiple: true;
-  value?: _pixpilot_shadcn_ui8.FileMetadata[];
-  onChange?: _pixpilot_shadcn_ui8.OnChangeMultipleFiles;
-} & _pixpilot_shadcn_ui8.FileUploadBaseProps>, "ref"> | Omit<Partial<_pixpilot_shadcn_ui8.FileUploadInlineBaseProps & {
+  value?: _pixpilot_shadcn_ui0.FileMetadata[];
+  onChange?: _pixpilot_shadcn_ui0.OnChangeMultipleFiles;
+} & _pixpilot_shadcn_ui0.FileUploadBaseProps>, "ref"> | Omit<Partial<_pixpilot_shadcn_ui0.FileUploadInlineBaseProps & {
   multiple?: false;
-  value?: _pixpilot_shadcn_ui8.FileMetadata | null;
-  onChange?: _pixpilot_shadcn_ui8.OnChangeSingleFile;
-} & _pixpilot_shadcn_ui8.FileUploadBaseProps>, "ref">) & React.RefAttributes<unknown>>;
+  value?: _pixpilot_shadcn_ui0.FileMetadata | null;
+  onChange?: _pixpilot_shadcn_ui0.OnChangeSingleFile;
+} & _pixpilot_shadcn_ui0.FileUploadBaseProps>, "ref">) & React.RefAttributes<unknown>>;
 //#endregion
 export { FileUploadInline };

package/dist/components/file-upload/file-upload-inline.d.ts

@@ -1,5 +1,5 @@
 import React from "react";
-import * as _pixpilot_shadcn_ui0 from "@pixpilot/shadcn-ui";
+import * as _pixpilot_shadcn_ui294 from "@pixpilot/shadcn-ui";
 
 //#region src/components/file-upload/file-upload-inline.d.ts
 
@@ -7,14 +7,14 @@ import * as _pixpilot_shadcn_ui0 from "@pixpilot/shadcn-ui";
  * Formily-connected FileUploadInline component
  * Automatically connects shadcn FileUploadInline to Formily field state
  */
-declare const FileUploadInline$1: React.ForwardRefExoticComponent<(Omit<Partial<_pixpilot_shadcn_ui0.FileUploadInlineBaseProps & {
+declare const FileUploadInline$1: React.ForwardRefExoticComponent<(Omit<Partial<_pixpilot_shadcn_ui294.FileUploadInlineBaseProps & {
   multiple: true;
-  value?: _pixpilot_shadcn_ui0.FileMetadata[];
-  onChange?: _pixpilot_shadcn_ui0.OnChangeMultipleFiles;
-} & _pixpilot_shadcn_ui0.FileUploadBaseProps>, "ref"> | Omit<Partial<_pixpilot_shadcn_ui0.FileUploadInlineBaseProps & {
+  value?: _pixpilot_shadcn_ui294.FileMetadata[];
+  onChange?: _pixpilot_shadcn_ui294.OnChangeMultipleFiles;
+} & _pixpilot_shadcn_ui294.FileUploadBaseProps>, "ref"> | Omit<Partial<_pixpilot_shadcn_ui294.FileUploadInlineBaseProps & {
   multiple?: false;
-  value?: _pixpilot_shadcn_ui0.FileMetadata | null;
-  onChange?: _pixpilot_shadcn_ui0.OnChangeSingleFile;
-} & _pixpilot_shadcn_ui0.FileUploadBaseProps>, "ref">) & React.RefAttributes<unknown>>;
+  value?: _pixpilot_shadcn_ui294.FileMetadata | null;
+  onChange?: _pixpilot_shadcn_ui294.OnChangeSingleFile;
+} & _pixpilot_shadcn_ui294.FileUploadBaseProps>, "ref">) & React.RefAttributes<unknown>>;
 //#endregion
 export { FileUploadInline$1 as FileUploadInline };

package/dist/components/file-upload/file-upload.d.cts

@@ -1,5 +1,5 @@
 import React from "react";
-import * as _pixpilot_shadcn_ui0 from "@pixpilot/shadcn-ui";
+import * as _pixpilot_shadcn_ui8 from "@pixpilot/shadcn-ui";
 
 //#region src/components/file-upload/file-upload.d.ts
 
@@ -7,14 +7,14 @@ import * as _pixpilot_shadcn_ui0 from "@pixpilot/shadcn-ui";
  * Formily-connected FileUploadInline component
  * Automatically connects shadcn FileUploadInline to Formily field state
  */
-declare const FileUpload: React.ForwardRefExoticComponent<(Omit<Partial<_pixpilot_shadcn_ui0.FileUploadInlineBaseProps & {
+declare const FileUpload: React.ForwardRefExoticComponent<(Omit<Partial<_pixpilot_shadcn_ui8.FileUploadInlineBaseProps & {
   multiple: true;
-  value?: _pixpilot_shadcn_ui0.FileMetadata[];
-  onChange?: _pixpilot_shadcn_ui0.OnChangeMultipleFiles;
-} & _pixpilot_shadcn_ui0.FileUploadBaseProps>, "ref"> | Omit<Partial<_pixpilot_shadcn_ui0.FileUploadInlineBaseProps & {
+  value?: _pixpilot_shadcn_ui8.FileMetadata[];
+  onChange?: _pixpilot_shadcn_ui8.OnChangeMultipleFiles;
+} & _pixpilot_shadcn_ui8.FileUploadBaseProps>, "ref"> | Omit<Partial<_pixpilot_shadcn_ui8.FileUploadInlineBaseProps & {
   multiple?: false;
-  value?: _pixpilot_shadcn_ui0.FileMetadata | null;
-  onChange?: _pixpilot_shadcn_ui0.OnChangeSingleFile;
-} & _pixpilot_shadcn_ui0.FileUploadBaseProps>, "ref">) & React.RefAttributes<unknown>>;
+  value?: _pixpilot_shadcn_ui8.FileMetadata | null;
+  onChange?: _pixpilot_shadcn_ui8.OnChangeSingleFile;
+} & _pixpilot_shadcn_ui8.FileUploadBaseProps>, "ref">) & React.RefAttributes<unknown>>;
 //#endregion
 export { FileUpload };

package/dist/components/file-upload/file-upload.d.ts

@@ -1,5 +1,5 @@
 import React from "react";
-import * as _pixpilot_shadcn_ui8 from "@pixpilot/shadcn-ui";
+import * as _pixpilot_shadcn_ui286 from "@pixpilot/shadcn-ui";
 
 //#region src/components/file-upload/file-upload.d.ts
 
@@ -7,14 +7,14 @@ import * as _pixpilot_shadcn_ui8 from "@pixpilot/shadcn-ui";
  * Formily-connected FileUploadInline component
  * Automatically connects shadcn FileUploadInline to Formily field state
  */
-declare const FileUpload$1: React.ForwardRefExoticComponent<(Omit<Partial<_pixpilot_shadcn_ui8.FileUploadInlineBaseProps & {
+declare const FileUpload$1: React.ForwardRefExoticComponent<(Omit<Partial<_pixpilot_shadcn_ui286.FileUploadInlineBaseProps & {
   multiple: true;
-  value?: _pixpilot_shadcn_ui8.FileMetadata[];
-  onChange?: _pixpilot_shadcn_ui8.OnChangeMultipleFiles;
-} & _pixpilot_shadcn_ui8.FileUploadBaseProps>, "ref"> | Omit<Partial<_pixpilot_shadcn_ui8.FileUploadInlineBaseProps & {
+  value?: _pixpilot_shadcn_ui286.FileMetadata[];
+  onChange?: _pixpilot_shadcn_ui286.OnChangeMultipleFiles;
+} & _pixpilot_shadcn_ui286.FileUploadBaseProps>, "ref"> | Omit<Partial<_pixpilot_shadcn_ui286.FileUploadInlineBaseProps & {
   multiple?: false;
-  value?: _pixpilot_shadcn_ui8.FileMetadata | null;
-  onChange?: _pixpilot_shadcn_ui8.OnChangeSingleFile;
-} & _pixpilot_shadcn_ui8.FileUploadBaseProps>, "ref">) & React.RefAttributes<unknown>>;
+  value?: _pixpilot_shadcn_ui286.FileMetadata | null;
+  onChange?: _pixpilot_shadcn_ui286.OnChangeSingleFile;
+} & _pixpilot_shadcn_ui286.FileUploadBaseProps>, "ref">) & React.RefAttributes<unknown>>;
 //#endregion
 export { FileUpload$1 as FileUpload };

package/dist/components/form-grid.d.ts

@@ -1,5 +1,5 @@
 import React from "react";
-import * as react_jsx_runtime1 from "react/jsx-runtime";
+import * as react_jsx_runtime0 from "react/jsx-runtime";
 
 //#region src/components/form-grid.d.ts
 interface IFormGridProps extends React.HTMLAttributes<HTMLDivElement> {}
@@ -7,6 +7,6 @@ declare function FormGrid({
   className,
   children,
   ...rest
-}: IFormGridProps): react_jsx_runtime1.JSX.Element;
+}: IFormGridProps): react_jsx_runtime0.JSX.Element;
 //#endregion
 export { FormGrid };

package/dist/components/form-item/base-form-item.cjs

@@ -0,0 +1,85 @@
+const require_rolldown_runtime = require('../../_virtual/rolldown_runtime.cjs');
+const require_use_form_context = require('../../hooks/use-form-context.cjs');
+const require_use_label = require('../../hooks/use-label.cjs');
+require('../../hooks/index.cjs');
+const require_form_item_label = require('./form-item-label.cjs');
+const require_spacing_config = require('./spacing-config.cjs');
+let __formily_react = require("@formily/react");
+__formily_react = require_rolldown_runtime.__toESM(__formily_react);
+let react = require("react");
+react = require_rolldown_runtime.__toESM(react);
+let react_jsx_runtime = require("react/jsx-runtime");
+react_jsx_runtime = require_rolldown_runtime.__toESM(react_jsx_runtime);
+let __pixpilot_shadcn = require("@pixpilot/shadcn");
+__pixpilot_shadcn = require_rolldown_runtime.__toESM(__pixpilot_shadcn);
+
+//#region src/components/form-item/base-form-item.tsx
+function resolveLegacyDescriptionPlacement(labelPlacement) {
+	return labelPlacement === "top" ? "top" : "bottom";
+}
+const BaseFormItem = ({ className, children, label, description, descriptionPlacement, asterisk, feedbackStatus, feedbackText, labelPlacement = "top",...props }) => {
+	const field = (0, __formily_react.useField)();
+	const fieldProps = field?.componentProps ?? {};
+	const effectiveLabel = require_use_label.useLabel(label);
+	const { layout } = require_use_form_context.useFormContext();
+	const { classes } = layout?.itemProps || {};
+	const contextDescriptionPlacement = layout?.descriptionPlacement;
+	const effectiveLabelPlacement = fieldProps.labelPlacement ?? labelPlacement;
+	const resolvedDescriptionPlacement = fieldProps.descriptionPlacement ?? descriptionPlacement ?? contextDescriptionPlacement ?? resolveLegacyDescriptionPlacement(effectiveLabelPlacement);
+	const id = field?.componentProps?.id ?? `form-${field?.address?.toString()?.replace(/\./gu, "-")}`;
+	const descriptionId = react.default.useId();
+	const feedbackId = react.default.useId();
+	const descriptionRenderedInline = description != null && resolvedDescriptionPlacement !== "popover";
+	const spacingConfig = require_spacing_config.getSpacingConfig(resolvedDescriptionPlacement, descriptionRenderedInline);
+	const ariaDescribedBy = [descriptionRenderedInline ? descriptionId : void 0, feedbackText != null ? feedbackId : void 0].filter(Boolean).join(" ");
+	const labelElement = effectiveLabel != null && /* @__PURE__ */ (0, react_jsx_runtime.jsx)(require_form_item_label.FormItemLabel, {
+		id,
+		label: effectiveLabel,
+		asterisk,
+		error: feedbackStatus === "error",
+		shrink: effectiveLabelPlacement === "end" || effectiveLabelPlacement === "start",
+		labelClassName: (0, __pixpilot_shadcn.cn)(spacingConfig.label, classes?.label),
+		description,
+		descriptionInPopover: resolvedDescriptionPlacement === "popover" && description != null
+	});
+	const inputElement = /* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
+		className: (0, __pixpilot_shadcn.cn)("relative", classes?.inputWrapper),
+		children: react.default.isValidElement(children) ? react.default.cloneElement(children, {
+			id,
+			"aria-describedby": ariaDescribedBy || void 0,
+			"aria-invalid": feedbackStatus === "error" ? "true" : void 0
+		}) : children
+	});
+	const descriptionElement = descriptionRenderedInline ? /* @__PURE__ */ (0, react_jsx_runtime.jsx)("p", {
+		id: descriptionId,
+		className: (0, __pixpilot_shadcn.cn)("text-muted-foreground text-[0.8rem]", spacingConfig.description, classes?.description),
+		children: description
+	}) : null;
+	const contentElement = /* @__PURE__ */ (0, react_jsx_runtime.jsxs)(react_jsx_runtime.Fragment, { children: [
+		effectiveLabelPlacement === "top" && labelElement,
+		resolvedDescriptionPlacement === "top" && descriptionElement,
+		(effectiveLabelPlacement === "start" || effectiveLabelPlacement === "end") && /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+			className: (0, __pixpilot_shadcn.cn)("flex items-center gap-2", effectiveLabelPlacement === "start" && "flex-row"),
+			children: [
+				effectiveLabelPlacement === "start" && labelElement,
+				inputElement,
+				effectiveLabelPlacement === "end" && labelElement
+			]
+		}),
+		effectiveLabelPlacement === "top" && inputElement,
+		resolvedDescriptionPlacement === "bottom" && descriptionElement
+	] });
+	return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+		"data-slot": "form-item",
+		className: (0, __pixpilot_shadcn.cn)("flex flex-col ", className),
+		...props,
+		children: [contentElement, Boolean(feedbackText) && /* @__PURE__ */ (0, react_jsx_runtime.jsx)("p", {
+			id: feedbackId,
+			className: (0, __pixpilot_shadcn.cn)("text-[0.8rem]", spacingConfig.feedback, feedbackStatus === "error" && "text-destructive font-medium", feedbackStatus === "warning" && "text-amber-600", feedbackStatus === "success" && "text-green-600", classes?.errorMessage),
+			children: typeof feedbackText === "string" ? feedbackText.split("\n").map((line, index) => /* @__PURE__ */ (0, react_jsx_runtime.jsxs)(react.default.Fragment, { children: [line, index < feedbackText.split("\n").length - 1 && /* @__PURE__ */ (0, react_jsx_runtime.jsx)("br", {})] }, index)) : feedbackText
+		})]
+	});
+};
+
+//#endregion
+exports.BaseFormItem = BaseFormItem;

package/dist/components/form-item/base-form-item.d.cts

@@ -0,0 +1,2 @@
+import "./form-item-types.cjs";
+import React from "react";

package/dist/components/form-item/base-form-item.d.ts

@@ -0,0 +1,2 @@
+import "./form-item-types.js";
+import React from "react";

package/dist/components/form-item/base-form-item.js

@@ -0,0 +1,80 @@
+import { useFormContext } from "../../hooks/use-form-context.js";
+import { useLabel } from "../../hooks/use-label.js";
+import "../../hooks/index.js";
+import { FormItemLabel } from "./form-item-label.js";
+import { getSpacingConfig } from "./spacing-config.js";
+import { useField } from "@formily/react";
+import React from "react";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+import { cn } from "@pixpilot/shadcn";
+
+//#region src/components/form-item/base-form-item.tsx
+function resolveLegacyDescriptionPlacement(labelPlacement) {
+	return labelPlacement === "top" ? "top" : "bottom";
+}
+const BaseFormItem = ({ className, children, label, description, descriptionPlacement, asterisk, feedbackStatus, feedbackText, labelPlacement = "top",...props }) => {
+	const field = useField();
+	const fieldProps = field?.componentProps ?? {};
+	const effectiveLabel = useLabel(label);
+	const { layout } = useFormContext();
+	const { classes } = layout?.itemProps || {};
+	const contextDescriptionPlacement = layout?.descriptionPlacement;
+	const effectiveLabelPlacement = fieldProps.labelPlacement ?? labelPlacement;
+	const resolvedDescriptionPlacement = fieldProps.descriptionPlacement ?? descriptionPlacement ?? contextDescriptionPlacement ?? resolveLegacyDescriptionPlacement(effectiveLabelPlacement);
+	const id = field?.componentProps?.id ?? `form-${field?.address?.toString()?.replace(/\./gu, "-")}`;
+	const descriptionId = React.useId();
+	const feedbackId = React.useId();
+	const descriptionRenderedInline = description != null && resolvedDescriptionPlacement !== "popover";
+	const spacingConfig = getSpacingConfig(resolvedDescriptionPlacement, descriptionRenderedInline);
+	const ariaDescribedBy = [descriptionRenderedInline ? descriptionId : void 0, feedbackText != null ? feedbackId : void 0].filter(Boolean).join(" ");
+	const labelElement = effectiveLabel != null && /* @__PURE__ */ jsx(FormItemLabel, {
+		id,
+		label: effectiveLabel,
+		asterisk,
+		error: feedbackStatus === "error",
+		shrink: effectiveLabelPlacement === "end" || effectiveLabelPlacement === "start",
+		labelClassName: cn(spacingConfig.label, classes?.label),
+		description,
+		descriptionInPopover: resolvedDescriptionPlacement === "popover" && description != null
+	});
+	const inputElement = /* @__PURE__ */ jsx("div", {
+		className: cn("relative", classes?.inputWrapper),
+		children: React.isValidElement(children) ? React.cloneElement(children, {
+			id,
+			"aria-describedby": ariaDescribedBy || void 0,
+			"aria-invalid": feedbackStatus === "error" ? "true" : void 0
+		}) : children
+	});
+	const descriptionElement = descriptionRenderedInline ? /* @__PURE__ */ jsx("p", {
+		id: descriptionId,
+		className: cn("text-muted-foreground text-[0.8rem]", spacingConfig.description, classes?.description),
+		children: description
+	}) : null;
+	const contentElement = /* @__PURE__ */ jsxs(Fragment, { children: [
+		effectiveLabelPlacement === "top" && labelElement,
+		resolvedDescriptionPlacement === "top" && descriptionElement,
+		(effectiveLabelPlacement === "start" || effectiveLabelPlacement === "end") && /* @__PURE__ */ jsxs("div", {
+			className: cn("flex items-center gap-2", effectiveLabelPlacement === "start" && "flex-row"),
+			children: [
+				effectiveLabelPlacement === "start" && labelElement,
+				inputElement,
+				effectiveLabelPlacement === "end" && labelElement
+			]
+		}),
+		effectiveLabelPlacement === "top" && inputElement,
+		resolvedDescriptionPlacement === "bottom" && descriptionElement
+	] });
+	return /* @__PURE__ */ jsxs("div", {
+		"data-slot": "form-item",
+		className: cn("flex flex-col ", className),
+		...props,
+		children: [contentElement, Boolean(feedbackText) && /* @__PURE__ */ jsx("p", {
+			id: feedbackId,
+			className: cn("text-[0.8rem]", spacingConfig.feedback, feedbackStatus === "error" && "text-destructive font-medium", feedbackStatus === "warning" && "text-amber-600", feedbackStatus === "success" && "text-green-600", classes?.errorMessage),
+			children: typeof feedbackText === "string" ? feedbackText.split("\n").map((line, index) => /* @__PURE__ */ jsxs(React.Fragment, { children: [line, index < feedbackText.split("\n").length - 1 && /* @__PURE__ */ jsx("br", {})] }, index)) : feedbackText
+		})]
+	});
+};
+
+//#endregion
+export { BaseFormItem };

package/dist/components/form-item/connected-form-item.cjs

@@ -0,0 +1,47 @@
+const require_rolldown_runtime = require('../../_virtual/rolldown_runtime.cjs');
+const require_base_form_item = require('./base-form-item.cjs');
+let __formily_react = require("@formily/react");
+__formily_react = require_rolldown_runtime.__toESM(__formily_react);
+let __formily_core = require("@formily/core");
+__formily_core = require_rolldown_runtime.__toESM(__formily_core);
+
+//#region src/components/form-item/connected-form-item.tsx
+/**
+* FormItem component connected to Formily field state.
+* Automatically maps field validation state to component props.
+*/
+const FormItem = (0, __formily_react.connect)(require_base_form_item.BaseFormItem, (0, __formily_react.mapProps)((props, field) => {
+	if ((0, __formily_core.isVoidField)(field)) return {
+		label: field.title ?? props.label,
+		description: props.description ?? field.description,
+		asterisk: props.asterisk
+	};
+	const takeFeedbackStatus = () => {
+		if (field.validating) return void 0;
+		if (field.selfErrors?.length) return "error";
+		if (field.selfWarnings?.length) return "warning";
+		if (field.selfSuccesses?.length) return "success";
+	};
+	const takeFeedbackText = () => {
+		if (field.validating) return void 0;
+		if (props.feedbackText != null) return props.feedbackText;
+		if (field.selfErrors?.length) return field.selfErrors.join(", ");
+		if (field.selfWarnings?.length) return field.selfWarnings.join(", ");
+		if (field.selfSuccesses?.length) return field.selfSuccesses.join(", ");
+	};
+	const takeAsterisk = () => {
+		if (field.required && field.pattern !== "readPretty") return true;
+		if ("asterisk" in props) return Boolean(props.asterisk);
+		return false;
+	};
+	return {
+		label: props.label ?? field.title,
+		description: props.description ?? field.description,
+		feedbackStatus: takeFeedbackStatus(),
+		feedbackText: takeFeedbackText(),
+		asterisk: takeAsterisk()
+	};
+}));
+
+//#endregion
+exports.FormItem = FormItem;

package/dist/components/form-item/connected-form-item.d.cts

@@ -0,0 +1,13 @@
+import { FormItemProps } from "./form-item-types.cjs";
+import * as react1341 from "react";
+
+//#region src/components/form-item/connected-form-item.d.ts
+/**
+ * FormItem component connected to Formily field state.
+ * Automatically maps field validation state to component props.
+ */
+declare const FormItem: react1341.ForwardRefExoticComponent<Omit<Partial<FormItemProps & {
+  children?: react1341.ReactNode | undefined;
+}>, "ref"> & react1341.RefAttributes<unknown>>;
+//#endregion
+export { FormItem };

package/dist/components/form-item/connected-form-item.d.ts

@@ -0,0 +1,13 @@
+import { FormItemProps } from "./form-item-types.js";
+import * as react1341 from "react";
+
+//#region src/components/form-item/connected-form-item.d.ts
+/**
+ * FormItem component connected to Formily field state.
+ * Automatically maps field validation state to component props.
+ */
+declare const FormItem: react1341.ForwardRefExoticComponent<Omit<Partial<FormItemProps & {
+  children?: react1341.ReactNode | undefined;
+}>, "ref"> & react1341.RefAttributes<unknown>>;
+//#endregion
+export { FormItem };