@ng-forge/dynamic-form-mcp 0.7.0 → 0.8.0-next.2

package/bin/ng-forge-mcp.js

@@ -20,12 +20,6 @@ var FIELD_TYPES = [
         description: "HTML input type",
         required: false,
         default: "text"
-      },
-      placeholder: {
-        name: "placeholder",
-        type: "DynamicText",
-        description: "Placeholder text displayed when field is empty",
-        required: false
       }
     },
     validationSupported: true,
@@ -37,7 +31,8 @@ var FIELD_TYPES = [
   label: 'Email Address',
   required: true,
   email: true,
-  props: { type: 'email', placeholder: 'user@example.com' }
+  placeholder: 'user@example.com',
+  props: { type: 'email' }
 }`,
     minimalExample: `{ key: 'name', type: 'input', label: 'Name' }`
   },
@@ -54,12 +49,6 @@ var FIELD_TYPES = [
         description: "Number of visible text lines",
         required: false,
         default: 3
-      },
-      placeholder: {
-        name: "placeholder",
-        type: "DynamicText",
-        description: "Placeholder text displayed when field is empty",
-        required: false
       }
     },
     validationSupported: true,
@@ -69,7 +58,8 @@ var FIELD_TYPES = [
   key: 'description',
   type: 'textarea',
   label: 'Description',
-  props: { rows: 5, placeholder: 'Enter description...' }
+  placeholder: 'Enter description...',
+  props: { rows: 5 }
 }`,
     minimalExample: `{ key: 'bio', type: 'textarea', label: 'Bio' }`
   },
@@ -92,12 +82,6 @@ var FIELD_TYPES = [
         description: "Allow multiple selections",
         required: false,
         default: false
-      },
-      placeholder: {
-        name: "placeholder",
-        type: "DynamicText",
-        description: "Placeholder text for empty selection",
-        required: false
       }
     },
     validationSupported: true,
@@ -444,7 +428,7 @@ var FIELD_TYPES = [
   {
     type: "array",
     category: "container",
-    description: 'Repeatable field group for dynamic lists/arrays. Arrays do NOT have a label property. Use "fields" (not "template") to define the item template. Supports only \'hidden\' logic type for conditional visibility. Supports minLength/maxLength for array size validation. Each array item is rendered inside a `<div class="df-array-item">` wrapper with `role="group"`, `aria-label="Item N"` (1-based), `data-array-item-id`, and `data-array-item-index` attributes for styling, accessibility, and testing.',
+    description: 'Repeatable field group for dynamic lists/arrays. Arrays do NOT have a label property. Use "fields" (not "template") to define the item template. Supports only \'hidden\' logic type for conditional visibility. Supports minLength/maxLength for array size validation. Full-API arrays are positional \u2014 each item must have its own entry in `fields`. For homogeneous arrays driven by a value (e.g., tags, contacts), use the simplified array API (`template` + `value`) instead. Each array item is rendered inside a `<div class="df-array-item">` wrapper with `role="group"`, `aria-label="Item N"` (1-based), `data-array-item-id`, and `data-array-item-index` attributes for styling, accessibility, and testing.',
     valueType: "T[]",
     baseInterface: "FieldDef",
     props: {
@@ -961,6 +945,20 @@ var UI_ADAPTERS = [
             required: false,
             default: "dynamic"
           },
+          floatLabel: {
+            name: "floatLabel",
+            type: "'auto' | 'always' | 'never'",
+            description: "Label float behavior",
+            required: false,
+            default: "auto"
+          },
+          hideRequiredMarker: {
+            name: "hideRequiredMarker",
+            type: "boolean",
+            description: "Hide the required asterisk",
+            required: false,
+            default: false
+          },
           hint: {
             name: "hint",
             type: "DynamicText",
@@ -979,6 +977,26 @@ var UI_ADAPTERS = [
             description: "Material form field appearance",
             required: false,
             default: "outline"
+          },
+          floatLabel: {
+            name: "floatLabel",
+            type: "'auto' | 'always' | 'never'",
+            description: "Label float behavior",
+            required: false,
+            default: "auto"
+          },
+          hideRequiredMarker: {
+            name: "hideRequiredMarker",
+            type: "boolean",
+            description: "Hide the required asterisk",
+            required: false,
+            default: false
+          },
+          hint: {
+            name: "hint",
+            type: "DynamicText",
+            description: "Hint text below the field",
+            required: false
           }
         }
       },
@@ -999,12 +1017,118 @@ var UI_ADAPTERS = [
         type: "datepicker",
         componentName: "MatDatepickerFieldComponent",
         additionalProps: {
+          appearance: {
+            name: "appearance",
+            type: "'fill' | 'outline'",
+            description: "Material form field appearance",
+            required: false,
+            default: "outline"
+          },
+          subscriptSizing: {
+            name: "subscriptSizing",
+            type: "'fixed' | 'dynamic'",
+            description: "Error/hint text sizing",
+            required: false,
+            default: "dynamic"
+          },
+          floatLabel: {
+            name: "floatLabel",
+            type: "'auto' | 'always' | 'never'",
+            description: "Label float behavior",
+            required: false,
+            default: "auto"
+          },
+          hideRequiredMarker: {
+            name: "hideRequiredMarker",
+            type: "boolean",
+            description: "Hide the required asterisk",
+            required: false,
+            default: false
+          },
           startView: {
             name: "startView",
             type: "'month' | 'year' | 'multi-year'",
             description: "Initial calendar view",
             required: false,
             default: "month"
+          },
+          touchUi: {
+            name: "touchUi",
+            type: "boolean",
+            description: "Use touch-friendly calendar UI",
+            required: false,
+            default: false
+          },
+          hint: {
+            name: "hint",
+            type: "DynamicText",
+            description: "Hint text below the field",
+            required: false
+          }
+        }
+      },
+      {
+        type: "textarea",
+        componentName: "MatTextareaFieldComponent",
+        additionalProps: {
+          appearance: {
+            name: "appearance",
+            type: "'fill' | 'outline'",
+            description: "Material form field appearance",
+            required: false,
+            default: "outline"
+          },
+          subscriptSizing: {
+            name: "subscriptSizing",
+            type: "'fixed' | 'dynamic'",
+            description: "Error/hint text sizing",
+            required: false,
+            default: "dynamic"
+          },
+          floatLabel: {
+            name: "floatLabel",
+            type: "'auto' | 'always' | 'never'",
+            description: "Label float behavior",
+            required: false,
+            default: "auto"
+          },
+          hideRequiredMarker: {
+            name: "hideRequiredMarker",
+            type: "boolean",
+            description: "Hide the required asterisk",
+            required: false,
+            default: false
+          },
+          hint: {
+            name: "hint",
+            type: "DynamicText",
+            description: "Hint text below the field",
+            required: false
+          },
+          rows: {
+            name: "rows",
+            type: "number",
+            description: "Visible row count",
+            required: false
+          },
+          cols: {
+            name: "cols",
+            type: "number",
+            description: "Visible column count",
+            required: false
+          },
+          resize: {
+            name: "resize",
+            type: "'none' | 'both' | 'horizontal' | 'vertical'",
+            description: "Resize handle behavior",
+            required: false,
+            default: "vertical"
+          },
+          maxLength: {
+            name: "maxLength",
+            type: "number",
+            description: "Maximum character length",
+            required: false
           }
         }
       }
@@ -1279,6 +1403,160 @@ var DOCUMENTATION = [
   { id: "example-array", title: "Complete Array Form", category: "examples", url: `${BASE_URL}/examples/array-form` }
 ];
 
+// packages/dynamic-form-mcp/src/registry/wrappers.ts
+var WRAPPER_AUTHORING_CONTRACT = `All wrapper components MUST:
+
+1. Implement \`FieldWrapperContract\` from \`@ng-forge/dynamic-forms\`.
+2. Expose \`readonly fieldComponent = viewChild.required('fieldComponent', { read: ViewContainerRef });\`
+   \u2014 this is the slot where the inner wrapper (or the field) is rendered
+   imperatively by the outlet.
+3. Place the \`#fieldComponent\` template ref UNCONDITIONALLY. It cannot
+   live inside \`@if\`, \`@defer\`, \`@for\`, \`@switch\`, \`<ng-template>\`,
+   or any structural directive that delays view creation. The outlet reads
+   the \`ViewContainerRef\` immediately after creation \u2014 if the slot isn't
+   materialised yet, \`viewChild.required\` throws \`NG0951\`
+   (REQUIRED_QUERY_NO_VALUE), the wrapper chain is torn down, and the field
+   renders bare.
+4. Declare every config key the wrapper consumes as an Angular \`input()\`.
+   Unknown keys are silently dropped \u2014 the outlet probes
+   \`reflectComponentType(...).inputs\` before calling \`setInput()\`.
+   Runtime typos in config will NOT throw; rely on TypeScript (via
+   \`FieldRegistryWrappers\` module augmentation) to catch them.
+5. Optionally accept \`fieldInputs: input<WrapperFieldInputs>()\` to read
+   the wrapped field's mapper outputs and read-only form state.`;
+var WRAPPERS = [
+  {
+    type: "css",
+    category: "core",
+    availability: "shipping",
+    package: "@ng-forge/dynamic-forms",
+    description: "Invisible wrapper that applies CSS classes to the host element via a `DynamicText` input. Useful for decorating any field (or container) with styling without authoring a custom wrapper. Resolves `Signal<string>` / `Observable<string>` / `string` uniformly.",
+    props: {
+      cssClasses: {
+        name: "cssClasses",
+        type: "DynamicText",
+        description: "Space-separated CSS class names to apply to the wrapper host element. Accepts a literal string, a Signal<string>, or an Observable<string> \u2014 the wrapper subscribes and updates the host [class] binding reactively.",
+        required: false
+      }
+    },
+    autoAppliesTo: [],
+    componentName: "CssWrapperComponent",
+    contract: WRAPPER_AUTHORING_CONTRACT,
+    example: `// Field-level CSS wrapper (scoped to a single field)
+{
+  key: 'email',
+  type: 'input',
+  label: 'Email',
+  wrappers: [{ type: 'css', cssClasses: 'field--highlight' }]
+}
+
+// Dynamic classes via Signal<string>
+{
+  key: 'amount',
+  type: 'input',
+  label: 'Amount',
+  wrappers: [{ type: 'css', cssClasses: highlightClass }] // highlightClass: Signal<string>
+}
+
+// Chained with other wrappers (outer-most first)
+{
+  key: 'contact',
+  type: 'group',
+  wrappers: [
+    { type: 'section', title: 'Contact' }, // outer
+    { type: 'css', cssClasses: 'pad-lg' }  // inner
+  ],
+  fields: [...]
+}`,
+    minimalExample: `{ type: 'css', cssClasses: 'my-class' }`
+  },
+  {
+    type: "arraySection",
+    category: "demo",
+    availability: "demo-only",
+    package: "@internal/examples-shared-ui",
+    description: 'Demo wrapper used by the docs sandbox. Wraps an array field in a titled card whose header contains an "Add" button \u2014 the wrapper owns the append behaviour, dispatching `arrayEvent(key).append(itemTemplate)` on click via the `EventBus`. Lets the consumer config drop the separate `addArrayItem` button field. NOT a shipping primitive; copy the component out of `internal/examples-shared-ui/src/lib/demo-wrappers/` or author your own if you want this pattern in production.',
+    props: {
+      title: {
+        name: "title",
+        type: "string",
+        description: "Card header text rendered above the array.",
+        required: false
+      },
+      addLabel: {
+        name: "addLabel",
+        type: "string",
+        description: 'Text for the Add button in the header. Defaults to "Add" when omitted.',
+        required: false
+      },
+      itemTemplate: {
+        name: "itemTemplate",
+        type: "FieldDef<unknown> | readonly FieldDef<unknown>[]",
+        description: "Template passed to `arrayEvent(key).append(template)` when the Add button is clicked. Should match the array's `fields` shape.",
+        required: true
+      }
+    },
+    autoAppliesTo: [],
+    componentName: "ArraySectionWrapperComponent",
+    contract: WRAPPER_AUTHORING_CONTRACT,
+    example: `// Array wrapped with arraySection \u2014 the wrapper owns the Add button
+import { arrayEvent } from '@ng-forge/dynamic-forms';
+
+const tagItemTemplate = { key: 'tag', type: 'input', label: 'Tag' } as const satisfies FieldDef;
+
+{
+  key: 'tags',
+  type: 'array',
+  wrappers: [{
+    type: 'arraySection',
+    title: 'Tags',
+    addLabel: 'Add tag',
+    itemTemplate: tagItemTemplate,
+  }],
+  fields: [tagItemTemplate],
+}
+// Clicking the header button dispatches arrayEvent('tags').append(tagItemTemplate)`,
+    minimalExample: `{ type: 'arraySection', title: 'Items', itemTemplate: { key: 'item', type: 'input', label: 'Item' } }`
+  },
+  {
+    type: "section",
+    category: "demo",
+    availability: "demo-only",
+    package: "@internal/examples-shared-ui",
+    description: "Demo wrapper used by the docs sandbox. Renders a titled card around the wrapped content and is registered with every sandbox adapter so the Writing-a-Wrapper docs can demonstrate an end-to-end custom wrapper. NOT a shipping primitive \u2014 use as a pattern/template, not a dependency.",
+    props: {
+      title: {
+        name: "title",
+        type: "string",
+        description: "Card header text. Omit to render a header-less card.",
+        required: false
+      }
+    },
+    autoAppliesTo: [],
+    componentName: "SectionWrapperComponent",
+    contract: WRAPPER_AUTHORING_CONTRACT,
+    example: `// Section wrapper around a group
+{
+  key: 'address',
+  type: 'group',
+  wrappers: [{ type: 'section', title: 'Shipping address' }],
+  fields: [
+    { key: 'street', type: 'input', label: 'Street' },
+    { key: 'city', type: 'input', label: 'City' }
+  ]
+}
+
+// Header-less card (title omitted)
+{
+  key: 'details',
+  type: 'group',
+  wrappers: [{ type: 'section' }],
+  fields: [...]
+}`,
+    minimalExample: `{ type: 'section', title: 'Section title' }`
+  }
+];
+
 // packages/dynamic-form-mcp/src/registry/index.ts
 function getFieldTypes() {
   return FIELD_TYPES;
@@ -1304,6 +1582,15 @@ function getUIAdapters() {
 function getUIAdapter(library) {
   return UI_ADAPTERS.find((a) => a.library === library);
 }
+function getWrappers() {
+  return WRAPPERS;
+}
+function getWrapper(type) {
+  return WRAPPERS.find((w) => w.type === type);
+}
+function getWrappersByCategory(category) {
+  return WRAPPERS.filter((w) => w.category === category);
+}
 function getDocPages() {
   return DOCUMENTATION;
 }
@@ -1874,13 +2161,13 @@ For fields that collect user input (\`input\`, \`textarea\`, \`select\`, \`check
   label: 'Email Address',
   required: true,           // Shorthand validator
   email: true,              // Shorthand validator
+  placeholder: 'user@example.com',  // Field-level, not inside props
   validationMessages: {     // Always provide clear messages
     required: 'Email is required',
     email: 'Please enter a valid email'
   },
   props: {
     type: 'email',          // HTML input type
-    placeholder: 'user@example.com',
     hint: 'We will never share your email'  // UI library specific
   }
 }
@@ -1896,11 +2183,11 @@ MUST include \`options\` array:
   type: 'select',
   label: 'Country',
   required: true,
+  placeholder: 'Select a country',
   options: [
     { value: 'us', label: 'United States' },
     { value: 'uk', label: 'United Kingdom' }
-  ],
-  props: { placeholder: 'Select a country' }
+  ]
 }
 \`\`\`
 
@@ -2014,6 +2301,27 @@ Use shorthand properties directly on field definitions:
 
 Available shorthands: \`required\`, \`email\`, \`min\`, \`max\`, \`minLength\`, \`maxLength\`, \`pattern\`
 
+### Nullable Values
+
+Value fields accept a \`nullable?: boolean\` flag. When \`true\`:
+
+- \`value\` accepts \`null\` in addition to the field's normal value type.
+- An omitted \`value\` resolves to \`null\` (instead of the type-specific empty default like \`''\`, \`NaN\`, or \`[]\`).
+- Orthogonal to \`required\`. \`nullable\` declares that the **model** accepts \`null\`; \`required\` is a **validation** constraint. Angular's \`Validators.required\` treats \`null\` as invalid, so a field that is both \`nullable\` and \`required\` will fail required-validation when the value is \`null\` \u2014 the two flags describe different layers (data shape vs. validation), not conflicting semantics.
+- Map OpenAPI \`nullable: true\` (3.0) or \`type: [T, null]\` (3.1) to this flag.
+
+\`\`\`typescript
+{
+  key: 'middleName',
+  type: 'input',
+  label: 'Middle Name',
+  nullable: true,
+  value: null,  // valid; default-resolves to null
+}
+\`\`\`
+
+Read-side caveat: a user clearing a text input reads back as \`""\`, not \`null\` \u2014 this is a DOM/Web IDL contract, identical to classic Reactive Forms. \`nullable\` is a contract for accepted values, not a guarantee of emitted ones.
+
 ### Validation Messages
 
 ALWAYS provide validation messages. Use template variables:
@@ -2228,7 +2536,8 @@ Different UI libraries support different properties. Always validate against the
 |----------|----------|-----------|---------|-------|
 | \`appearance\` | \u2713 (fill, outline) | \u2717 | \u2717 | \u2713 (fill, outline) |
 | \`subscriptSizing\` | \u2713 | \u2717 | \u2717 | \u2717 |
-| \`floatLabel\` | \u2713 | \u2717 | \u2713 | \u2717 |
+| \`floatLabel\` | \u2713 (auto, always, never) | \u2717 | \u2717 | \u2717 |
+| \`hideRequiredMarker\` | \u2713 | \u2717 | \u2717 | \u2717 |
 | \`hint\` | \u2713 | \u2713 (as \`helpText\`) | \u2713 | \u2713 |
 
 ### Container Fields
@@ -2315,7 +2624,9 @@ var examples_default = [
           key: "title",
           type: "text",
           label: "Sign In",
-          props: { elementType: "h2" }
+          props: {
+            elementType: "h2"
+          }
         },
         {
           key: "email",
@@ -2323,8 +2634,13 @@ var examples_default = [
           label: "Email Address",
           required: true,
           email: true,
-          validationMessages: { email: "Please enter a valid email address" },
-          props: { type: "email", placeholder: "your@email.com" }
+          validationMessages: {
+            email: "Please enter a valid email address"
+          },
+          props: {
+            type: "email"
+          },
+          placeholder: "your@email.com"
         },
         {
           key: "password",
@@ -2332,7 +2648,10 @@ var examples_default = [
           label: "Password",
           required: true,
           minLength: 8,
-          props: { type: "password", placeholder: "Enter your password" }
+          props: {
+            type: "password"
+          },
+          placeholder: "Enter your password"
         },
         {
           key: "remember",
@@ -2343,7 +2662,9 @@ var examples_default = [
           key: "submit",
           type: "submit",
           label: "Sign In",
-          props: { color: "primary" }
+          props: {
+            color: "primary"
+          }
         }
       ]
     }
@@ -2365,7 +2686,7 @@ var examples_default = [
             required: "First name is required",
             minLength: "Must be at least {{requiredLength}} characters"
           },
-          props: { placeholder: "Enter your first name" }
+          placeholder: "Enter your first name"
         },
         {
           key: "lastName",
@@ -2377,7 +2698,7 @@ var examples_default = [
             required: "Last name is required",
             minLength: "Must be at least {{requiredLength}} characters"
           },
-          props: { placeholder: "Enter your last name" }
+          placeholder: "Enter your last name"
         },
         {
           key: "email",
@@ -2389,7 +2710,10 @@ var examples_default = [
             required: "Email is required",
             email: "Please enter a valid email address"
           },
-          props: { type: "email", placeholder: "user@example.com" }
+          props: {
+            type: "email"
+          },
+          placeholder: "user@example.com"
         },
         {
           key: "age",
@@ -2403,22 +2727,42 @@ var examples_default = [
             min: "Must be at least {{min}}",
             max: "Must not exceed {{max}}"
           },
-          props: { type: "number", placeholder: "18" }
+          props: {
+            type: "number"
+          },
+          placeholder: "18"
         },
         {
           key: "country",
           type: "select",
           label: "Country",
           required: true,
-          validationMessages: { required: "Please select a country" },
+          validationMessages: {
+            required: "Please select a country"
+          },
           options: [
-            { value: "us", label: "United States" },
-            { value: "uk", label: "United Kingdom" },
-            { value: "ca", label: "Canada" },
-            { value: "au", label: "Australia" },
-            { value: "de", label: "Germany" }
+            {
+              value: "us",
+              label: "United States"
+            },
+            {
+              value: "uk",
+              label: "United Kingdom"
+            },
+            {
+              value: "ca",
+              label: "Canada"
+            },
+            {
+              value: "au",
+              label: "Australia"
+            },
+            {
+              value: "de",
+              label: "Germany"
+            }
           ],
-          props: { placeholder: "Select your country" }
+          placeholder: "Select your country"
         },
         {
           key: "newsletter",
@@ -2430,13 +2774,17 @@ var examples_default = [
           type: "checkbox",
           label: "I agree to the terms and conditions",
           required: true,
-          validationMessages: { required: "You must accept the terms" }
+          validationMessages: {
+            required: "You must accept the terms"
+          }
         },
         {
           key: "submit",
           type: "submit",
           label: "Create Account",
-          props: { color: "primary" }
+          props: {
+            color: "primary"
+          }
         }
       ]
     }
@@ -2461,7 +2809,7 @@ var examples_default = [
               label: "First Name",
               required: true,
               col: 6,
-              props: { placeholder: "Your first name" }
+              placeholder: "Your first name"
             },
             {
               key: "lastName",
@@ -2469,7 +2817,7 @@ var examples_default = [
               label: "Last Name",
               required: true,
               col: 6,
-              props: { placeholder: "Your last name" }
+              placeholder: "Your last name"
             }
           ]
         },
@@ -2479,8 +2827,13 @@ var examples_default = [
           label: "Email Address",
           required: true,
           email: true,
-          validationMessages: { email: "Please enter a valid email" },
-          props: { type: "email", placeholder: "email@example.com" }
+          validationMessages: {
+            email: "Please enter a valid email"
+          },
+          props: {
+            type: "email"
+          },
+          placeholder: "email@example.com"
         },
         {
           key: "subject",
@@ -2488,12 +2841,24 @@ var examples_default = [
           label: "Subject",
           required: true,
           options: [
-            { value: "general", label: "General Inquiry" },
-            { value: "support", label: "Technical Support" },
-            { value: "billing", label: "Billing Question" },
-            { value: "feedback", label: "Feedback" }
+            {
+              value: "general",
+              label: "General Inquiry"
+            },
+            {
+              value: "support",
+              label: "Technical Support"
+            },
+            {
+              value: "billing",
+              label: "Billing Question"
+            },
+            {
+              value: "feedback",
+              label: "Feedback"
+            }
           ],
-          props: { placeholder: "Select a subject" }
+          placeholder: "Select a subject"
         },
         {
           key: "message",
@@ -2506,13 +2871,18 @@ var examples_default = [
             minLength: "Message must be at least {{requiredLength}} characters",
             maxLength: "Message cannot exceed {{requiredLength}} characters"
           },
-          props: { rows: 5, placeholder: "How can we help you?" }
+          props: {
+            rows: 5
+          },
+          placeholder: "How can we help you?"
         },
         {
           key: "submit",
           type: "submit",
           label: "Send Message",
-          props: { color: "primary" }
+          props: {
+            color: "primary"
+          }
         }
       ]
     }
@@ -2539,13 +2909,17 @@ var examples_default = [
           label: "Email",
           required: true,
           email: true,
-          props: { type: "email" }
+          props: {
+            type: "email"
+          }
         },
         {
           key: "addressTitle",
           type: "text",
           label: "Shipping Address",
-          props: { elementType: "h4" }
+          props: {
+            elementType: "h4"
+          }
         },
         {
           key: "address",
@@ -2561,8 +2935,20 @@ var examples_default = [
               key: "cityStateRow",
               type: "row",
               fields: [
-                { key: "city", type: "input", label: "City", required: true, col: 6 },
-                { key: "state", type: "input", label: "State", required: true, col: 3 },
+                {
+                  key: "city",
+                  type: "input",
+                  label: "City",
+                  required: true,
+                  col: 6
+                },
+                {
+                  key: "state",
+                  type: "input",
+                  label: "State",
+                  required: true,
+                  col: 3
+                },
                 {
                   key: "zip",
                   type: "input",
@@ -2570,7 +2956,9 @@ var examples_default = [
                   required: true,
                   col: 3,
                   pattern: "^\\d{5}$",
-                  validationMessages: { pattern: "ZIP must be 5 digits" }
+                  validationMessages: {
+                    pattern: "ZIP must be 5 digits"
+                  }
                 }
               ]
             },
@@ -2580,8 +2968,14 @@ var examples_default = [
               label: "Country",
               required: true,
               options: [
-                { value: "us", label: "United States" },
-                { value: "ca", label: "Canada" }
+                {
+                  value: "us",
+                  label: "United States"
+                },
+                {
+                  value: "ca",
+                  label: "Canada"
+                }
               ]
             }
           ]
@@ -2612,12 +3006,37 @@ var examples_default = [
               key: "stepTitle1",
               type: "text",
               label: "Step 1: Personal Information",
-              props: { elementType: "h3" }
+              props: {
+                elementType: "h3"
+              }
             },
-            { key: "firstName", type: "input", label: "First Name", required: true },
-            { key: "lastName", type: "input", label: "Last Name", required: true },
-            { key: "email", type: "input", label: "Email", required: true, email: true, props: { type: "email" } },
-            { key: "next1", type: "next", label: "Continue" }
+            {
+              key: "firstName",
+              type: "input",
+              label: "First Name",
+              required: true
+            },
+            {
+              key: "lastName",
+              type: "input",
+              label: "Last Name",
+              required: true
+            },
+            {
+              key: "email",
+              type: "input",
+              label: "Email",
+              required: true,
+              email: true,
+              props: {
+                type: "email"
+              }
+            },
+            {
+              key: "next1",
+              type: "next",
+              label: "Continue"
+            }
           ]
         },
         {
@@ -2628,17 +3047,44 @@ var examples_default = [
               key: "stepTitle2",
               type: "text",
               label: "Step 2: Address",
-              props: { elementType: "h3" }
+              props: {
+                elementType: "h3"
+              }
+            },
+            {
+              key: "street",
+              type: "input",
+              label: "Street Address",
+              required: true
+            },
+            {
+              key: "city",
+              type: "input",
+              label: "City",
+              required: true
+            },
+            {
+              key: "state",
+              type: "input",
+              label: "State",
+              required: true
             },
-            { key: "street", type: "input", label: "Street Address", required: true },
-            { key: "city", type: "input", label: "City", required: true },
-            { key: "state", type: "input", label: "State", required: true },
             {
               key: "navRow2",
               type: "row",
               fields: [
-                { key: "prev2", type: "previous", label: "Back", col: 6 },
-                { key: "next2", type: "next", label: "Continue", col: 6 }
+                {
+                  key: "prev2",
+                  type: "previous",
+                  label: "Back",
+                  col: 6
+                },
+                {
+                  key: "next2",
+                  type: "next",
+                  label: "Continue",
+                  col: 6
+                }
               ]
             }
           ]
@@ -2651,21 +3097,35 @@ var examples_default = [
               key: "stepTitle3",
               type: "text",
               label: "Step 3: Review & Submit",
-              props: { elementType: "h3" }
+              props: {
+                elementType: "h3"
+              }
             },
             {
               key: "confirm",
               type: "checkbox",
               label: "I confirm all information is correct",
               required: true,
-              validationMessages: { required: "Please confirm before submitting" }
+              validationMessages: {
+                required: "Please confirm before submitting"
+              }
             },
             {
               key: "navRow3",
               type: "row",
               fields: [
-                { key: "prev3", type: "previous", label: "Back", col: 6 },
-                { key: "submit", type: "submit", label: "Submit", col: 6 }
+                {
+                  key: "prev3",
+                  type: "previous",
+                  label: "Back",
+                  col: 6
+                },
+                {
+                  key: "submit",
+                  type: "submit",
+                  label: "Submit",
+                  col: 6
+                }
               ]
             }
           ]
@@ -2686,8 +3146,14 @@ var examples_default = [
           label: "Account Type",
           required: true,
           options: [
-            { value: "personal", label: "Personal" },
-            { value: "business", label: "Business" }
+            {
+              value: "personal",
+              label: "Personal"
+            },
+            {
+              value: "business",
+              label: "Business"
+            }
           ]
         },
         {
@@ -2714,7 +3180,9 @@ var examples_default = [
               }
             }
           ],
-          validationMessages: { required: "Business name is required" }
+          validationMessages: {
+            required: "Business name is required"
+          }
         },
         {
           key: "taxId",
@@ -2731,7 +3199,7 @@ var examples_default = [
               }
             }
           ],
-          props: { placeholder: "XX-XXXXXXX" }
+          placeholder: "XX-XXXXXXX"
         },
         {
           key: "newsletter",
@@ -2743,9 +3211,18 @@ var examples_default = [
           type: "select",
           label: "Email Frequency",
           options: [
-            { value: "daily", label: "Daily" },
-            { value: "weekly", label: "Weekly" },
-            { value: "monthly", label: "Monthly" }
+            {
+              value: "daily",
+              label: "Daily"
+            },
+            {
+              value: "weekly",
+              label: "Weekly"
+            },
+            {
+              value: "monthly",
+              label: "Monthly"
+            }
           ],
           logic: [
             {
@@ -2787,7 +3264,9 @@ var examples_default = [
           key: "contactsTitle",
           type: "text",
           label: "Emergency Contacts",
-          props: { elementType: "h4" }
+          props: {
+            elementType: "h4"
+          }
         },
         {
           key: "contacts",
@@ -2802,19 +3281,49 @@ var examples_default = [
                   key: "contactRow",
                   type: "row",
                   fields: [
-                    { key: "name", type: "input", label: "Contact Name", required: true, col: 4 },
-                    { key: "phone", type: "input", label: "Phone", required: true, col: 4, props: { type: "tel" } },
+                    {
+                      key: "name",
+                      type: "input",
+                      label: "Contact Name",
+                      required: true,
+                      col: 4
+                    },
+                    {
+                      key: "phone",
+                      type: "input",
+                      label: "Phone",
+                      required: true,
+                      col: 4,
+                      props: {
+                        type: "tel"
+                      }
+                    },
                     {
                       key: "relationship",
                       type: "select",
                       label: "Relationship",
                       col: 4,
                       options: [
-                        { value: "spouse", label: "Spouse" },
-                        { value: "parent", label: "Parent" },
-                        { value: "sibling", label: "Sibling" },
-                        { value: "friend", label: "Friend" },
-                        { value: "other", label: "Other" }
+                        {
+                          value: "spouse",
+                          label: "Spouse"
+                        },
+                        {
+                          value: "parent",
+                          label: "Parent"
+                        },
+                        {
+                          value: "sibling",
+                          label: "Sibling"
+                        },
+                        {
+                          value: "friend",
+                          label: "Friend"
+                        },
+                        {
+                          value: "other",
+                          label: "Other"
+                        }
                       ]
                     }
                   ]
@@ -2842,15 +3351,23 @@ var examples_default = [
           key: "title",
           type: "text",
           label: "Customer Feedback",
-          props: { elementType: "h2" }
+          props: {
+            elementType: "h2"
+          }
         },
         {
           key: "satisfaction",
           type: "slider",
           label: "Overall Satisfaction (1-10)",
           required: true,
-          props: { min: 1, max: 10, step: 1 },
-          validationMessages: { required: "Please rate your satisfaction" }
+          props: {
+            min: 1,
+            max: 10,
+            step: 1
+          },
+          validationMessages: {
+            required: "Please rate your satisfaction"
+          }
         },
         {
           key: "recommend",
@@ -2858,30 +3375,62 @@ var examples_default = [
           label: "Would you recommend us?",
           required: true,
           options: [
-            { value: "yes", label: "Yes, definitely" },
-            { value: "maybe", label: "Maybe" },
-            { value: "no", label: "No" }
+            {
+              value: "yes",
+              label: "Yes, definitely"
+            },
+            {
+              value: "maybe",
+              label: "Maybe"
+            },
+            {
+              value: "no",
+              label: "No"
+            }
           ],
-          validationMessages: { required: "Please select an option" }
+          validationMessages: {
+            required: "Please select an option"
+          }
         },
         {
           key: "improvements",
           type: "select",
           label: "What could we improve?",
-          props: { multiple: true, placeholder: "Select all that apply" },
+          props: {
+            multiple: true
+          },
           options: [
-            { value: "speed", label: "Response Time" },
-            { value: "quality", label: "Product Quality" },
-            { value: "price", label: "Pricing" },
-            { value: "support", label: "Customer Support" },
-            { value: "ui", label: "User Interface" }
-          ]
+            {
+              value: "speed",
+              label: "Response Time"
+            },
+            {
+              value: "quality",
+              label: "Product Quality"
+            },
+            {
+              value: "price",
+              label: "Pricing"
+            },
+            {
+              value: "support",
+              label: "Customer Support"
+            },
+            {
+              value: "ui",
+              label: "User Interface"
+            }
+          ],
+          placeholder: "Select all that apply"
         },
         {
           key: "comments",
           type: "textarea",
           label: "Additional Comments",
-          props: { rows: 4, placeholder: "Share any additional feedback..." }
+          props: {
+            rows: 4
+          },
+          placeholder: "Share any additional feedback..."
         },
         {
           key: "followUp",
@@ -2893,7 +3442,9 @@ var examples_default = [
           type: "input",
           label: "Email Address",
           email: true,
-          props: { type: "email", placeholder: "your@email.com" },
+          props: {
+            type: "email"
+          },
           logic: [
             {
               type: "hidden",
@@ -2917,7 +3468,8 @@ var examples_default = [
           validationMessages: {
             required: "Email required for follow-up",
             email: "Please enter a valid email"
-          }
+          },
+          placeholder: "your@email.com"
         },
         {
           key: "submit",
@@ -3366,7 +3918,7 @@ var MatButtonPropsSchema = z12.object({
 });
 
 // internal/dynamic-forms-zod/material/src/fields/mat-input-field.schema.ts
-import { z as z22 } from "zod";
+import { z as z23 } from "zod";
 
 // internal/dynamic-forms-zod/src/lib/schemas/field/field-def.schema.ts
 import { z as z14 } from "zod";
@@ -3828,16 +4380,31 @@ var FieldWithValidationSchema = z21.object({
   schemas: z21.array(SchemaApplicationConfigSchema).optional()
 });
 
+// internal/dynamic-forms-zod/src/lib/schemas/field/nullable-value.refinement.ts
+import { z as z22 } from "zod";
+var nullableValueRefine = (data, ctx) => {
+  if (!data || typeof data !== "object") return;
+  const field = data;
+  if (field.value === null && field.nullable !== true) {
+    ctx.addIssue({
+      code: z22.ZodIssueCode.custom,
+      path: ["value"],
+      message: "value: null is only allowed when nullable is true. Add `nullable: true` or remove the null value."
+    });
+  }
+};
+
 // internal/dynamic-forms-zod/material/src/fields/mat-input-field.schema.ts
-var MatInputFieldSchema = BaseFieldDefSchema.merge(FieldWithValidationSchema).extend({
+var MatInputFieldSchemaObject = BaseFieldDefSchema.merge(FieldWithValidationSchema).extend({
   /**
    * Field type discriminant.
    */
-  type: z22.literal("input"),
+  type: z23.literal("input"),
+  nullable: z23.boolean().optional(),
   /**
    * Initial value for the input.
    */
-  value: z22.string().optional(),
+  value: z23.string().nullable().optional(),
   /**
    * Placeholder text (can also be in props).
    */
@@ -3847,18 +4414,20 @@ var MatInputFieldSchema = BaseFieldDefSchema.merge(FieldWithValidationSchema).ex
    */
   props: MatInputPropsSchema.optional()
 });
+var MatInputFieldSchema = MatInputFieldSchemaObject.superRefine(nullableValueRefine);
 
 // internal/dynamic-forms-zod/material/src/fields/mat-textarea-field.schema.ts
-import { z as z23 } from "zod";
-var MatTextareaFieldSchema = BaseFieldDefSchema.merge(FieldWithValidationSchema).extend({
+import { z as z24 } from "zod";
+var MatTextareaFieldSchemaObject = BaseFieldDefSchema.merge(FieldWithValidationSchema).extend({
   /**
    * Field type discriminant.
    */
-  type: z23.literal("textarea"),
+  type: z24.literal("textarea"),
+  nullable: z24.boolean().optional(),
   /**
    * Initial value for the textarea.
    */
-  value: z23.string().optional(),
+  value: z24.string().nullable().optional(),
   /**
    * Placeholder text (can also be in props).
    */
@@ -3868,13 +4437,14 @@ var MatTextareaFieldSchema = BaseFieldDefSchema.merge(FieldWithValidationSchema)
    */
   props: MatTextareaPropsSchema.optional()
 });
+var MatTextareaFieldSchema = MatTextareaFieldSchemaObject.superRefine(nullableValueRefine);
 
 // internal/dynamic-forms-zod/material/src/fields/mat-select-field.schema.ts
-import { z as z25 } from "zod";
+import { z as z26 } from "zod";
 
 // internal/dynamic-forms-zod/src/lib/schemas/common/field-option.schema.ts
-import { z as z24 } from "zod";
-var FieldOptionSchema = z24.object({
+import { z as z25 } from "zod";
+var FieldOptionSchema = z25.object({
   /**
    * Display text for the option.
    */
@@ -3883,25 +4453,26 @@ var FieldOptionSchema = z24.object({
    * The actual value stored when this option is selected.
    * Can be any JSON-serializable value.
    */
-  value: z24.unknown(),
+  value: z25.unknown(),
   /**
    * Whether this option is disabled and cannot be selected.
    */
-  disabled: z24.boolean().optional()
+  disabled: z25.boolean().optional()
 }).passthrough();
-var FieldOptionsSchema = z24.array(FieldOptionSchema);
+var FieldOptionsSchema = z25.array(FieldOptionSchema);
 
 // internal/dynamic-forms-zod/material/src/fields/mat-select-field.schema.ts
-var MatSelectFieldSchema = BaseFieldDefSchema.merge(FieldWithValidationSchema).extend({
+var MatSelectFieldSchemaObject = BaseFieldDefSchema.merge(FieldWithValidationSchema).extend({
   /**
    * Field type discriminant.
    */
-  type: z25.literal("select"),
+  type: z26.literal("select"),
+  nullable: z26.boolean().optional(),
   /**
    * Initial value for the select.
    * Can be single value or array if multiple is enabled.
    */
-  value: z25.unknown().optional(),
+  value: z26.unknown().nullable().optional(),
   /**
    * Placeholder text (can also be in props).
    */
@@ -3915,18 +4486,19 @@ var MatSelectFieldSchema = BaseFieldDefSchema.merge(FieldWithValidationSchema).e
    */
   props: MatSelectPropsSchema.optional()
 });
+var MatSelectFieldSchema = MatSelectFieldSchemaObject.superRefine(nullableValueRefine);
 
 // internal/dynamic-forms-zod/material/src/fields/mat-checkbox-field.schema.ts
-import { z as z26 } from "zod";
+import { z as z27 } from "zod";
 var MatCheckboxFieldSchema = BaseFieldDefSchema.merge(FieldWithValidationSchema).extend({
   /**
    * Field type discriminant.
    */
-  type: z26.literal("checkbox"),
+  type: z27.literal("checkbox"),
   /**
    * Initial checked state.
    */
-  value: z26.boolean().optional(),
+  value: z27.boolean().optional(),
   /**
    * Placeholder/helper text.
    */
@@ -3938,16 +4510,17 @@ var MatCheckboxFieldSchema = BaseFieldDefSchema.merge(FieldWithValidationSchema)
 });
 
 // internal/dynamic-forms-zod/material/src/fields/mat-radio-field.schema.ts
-import { z as z27 } from "zod";
-var MatRadioFieldSchema = BaseFieldDefSchema.merge(FieldWithValidationSchema).extend({
+import { z as z28 } from "zod";
+var MatRadioFieldSchemaObject = BaseFieldDefSchema.merge(FieldWithValidationSchema).extend({
   /**
    * Field type discriminant.
    */
-  type: z27.literal("radio"),
+  type: z28.literal("radio"),
+  nullable: z28.boolean().optional(),
   /**
    * Initial selected value.
    */
-  value: z27.unknown().optional(),
+  value: z28.unknown().nullable().optional(),
   /**
    * Placeholder/helper text.
    */
@@ -3961,18 +4534,20 @@ var MatRadioFieldSchema = BaseFieldDefSchema.merge(FieldWithValidationSchema).ex
    */
   props: MatRadioPropsSchema.optional()
 });
+var MatRadioFieldSchema = MatRadioFieldSchemaObject.superRefine(nullableValueRefine);
 
 // internal/dynamic-forms-zod/material/src/fields/mat-multi-checkbox-field.schema.ts
-import { z as z28 } from "zod";
-var MatMultiCheckboxFieldSchema = BaseFieldDefSchema.merge(FieldWithValidationSchema).extend({
+import { z as z29 } from "zod";
+var MatMultiCheckboxFieldSchemaObject = BaseFieldDefSchema.merge(FieldWithValidationSchema).extend({
   /**
    * Field type discriminant.
    */
-  type: z28.literal("multi-checkbox"),
+  type: z29.literal("multi-checkbox"),
+  nullable: z29.boolean().optional(),
   /**
    * Initial selected values (array).
    */
-  value: z28.array(z28.unknown()).optional(),
+  value: z29.array(z29.unknown()).nullable().optional(),
   /**
    * Placeholder/helper text.
    */
@@ -3986,18 +4561,19 @@ var MatMultiCheckboxFieldSchema = BaseFieldDefSchema.merge(FieldWithValidationSc
    */
   props: MatMultiCheckboxPropsSchema.optional()
 });
+var MatMultiCheckboxFieldSchema = MatMultiCheckboxFieldSchemaObject.superRefine(nullableValueRefine);
 
 // internal/dynamic-forms-zod/material/src/fields/mat-toggle-field.schema.ts
-import { z as z29 } from "zod";
+import { z as z30 } from "zod";
 var MatToggleFieldSchema = BaseFieldDefSchema.merge(FieldWithValidationSchema).extend({
   /**
    * Field type discriminant.
    */
-  type: z29.literal("toggle"),
+  type: z30.literal("toggle"),
   /**
    * Initial toggle state.
    */
-  value: z29.boolean().optional(),
+  value: z30.boolean().optional(),
   /**
    * Placeholder/helper text.
    */
@@ -4009,28 +4585,29 @@ var MatToggleFieldSchema = BaseFieldDefSchema.merge(FieldWithValidationSchema).e
 });
 
 // internal/dynamic-forms-zod/material/src/fields/mat-slider-field.schema.ts
-import { z as z30 } from "zod";
-var MatSliderFieldSchema = BaseFieldDefSchema.merge(FieldWithValidationSchema).extend({
+import { z as z31 } from "zod";
+var MatSliderFieldSchemaObject = BaseFieldDefSchema.merge(FieldWithValidationSchema).extend({
   /**
    * Field type discriminant.
    */
-  type: z30.literal("slider"),
+  type: z31.literal("slider"),
+  nullable: z31.boolean().optional(),
   /**
    * Initial slider value.
    */
-  value: z30.number().optional(),
+  value: z31.number().nullable().optional(),
   /**
    * Minimum slider value.
    */
-  minValue: z30.number().optional(),
+  minValue: z31.number().optional(),
   /**
    * Maximum slider value.
    */
-  maxValue: z30.number().optional(),
+  maxValue: z31.number().optional(),
   /**
    * Step increment.
    */
-  step: z30.number().positive().optional(),
+  step: z31.number().positive().optional(),
   /**
    * Placeholder/helper text.
    */
@@ -4040,19 +4617,21 @@ var MatSliderFieldSchema = BaseFieldDefSchema.merge(FieldWithValidationSchema).e
    */
   props: MatSliderPropsSchema.optional()
 });
+var MatSliderFieldSchema = MatSliderFieldSchemaObject.superRefine(nullableValueRefine);
 
 // internal/dynamic-forms-zod/material/src/fields/mat-datepicker-field.schema.ts
-import { z as z31 } from "zod";
-var DateValueSchema = z31.union([z31.string(), z31.null()]);
-var MatDatepickerFieldSchema = BaseFieldDefSchema.merge(FieldWithValidationSchema).extend({
+import { z as z32 } from "zod";
+var DateValueSchema = z32.union([z32.string(), z32.null()]);
+var MatDatepickerFieldSchemaObject = BaseFieldDefSchema.merge(FieldWithValidationSchema).extend({
   /**
    * Field type discriminant.
    */
-  type: z31.literal("datepicker"),
+  type: z32.literal("datepicker"),
+  nullable: z32.boolean().optional(),
   /**
    * Initial date value (ISO string in JSON configs).
    */
-  value: DateValueSchema.optional(),
+  value: DateValueSchema.nullable().optional(),
   /**
    * Minimum selectable date.
    */
@@ -4074,24 +4653,25 @@ var MatDatepickerFieldSchema = BaseFieldDefSchema.merge(FieldWithValidationSchem
    */
   props: MatDatepickerPropsSchema.optional()
 });
+var MatDatepickerFieldSchema = MatDatepickerFieldSchemaObject.superRefine(nullableValueRefine);
 
 // internal/dynamic-forms-zod/material/src/fields/mat-button-field.schema.ts
-import { z as z32 } from "zod";
-var EventArgSchema = z32.union([z32.string(), z32.number(), z32.boolean(), z32.null(), z32.undefined()]);
+import { z as z33 } from "zod";
+var EventArgSchema = z33.union([z33.string(), z33.number(), z33.boolean(), z33.null(), z33.undefined()]);
 var MatButtonFieldSchema = BaseFieldDefSchema.extend({
   /**
    * Field type discriminant.
    */
-  type: z32.literal("button"),
+  type: z33.literal("button"),
   /**
    * Event type name (string reference to registered event).
    * Note: Full event configuration requires runtime setup.
    */
-  event: z32.string().optional(),
+  event: z33.string().optional(),
   /**
    * Arguments passed to the event constructor.
    */
-  eventArgs: z32.array(EventArgSchema).optional(),
+  eventArgs: z33.array(EventArgSchema).optional(),
   /**
    * Material-specific button properties.
    */
@@ -4102,45 +4682,45 @@ var MatButtonFieldSchema = BaseFieldDefSchema.extend({
   logic: LogicArraySchema.optional()
 });
 var MatSubmitButtonFieldSchema = BaseFieldDefSchema.extend({
-  type: z32.literal("submit"),
+  type: z33.literal("submit"),
   props: MatButtonPropsSchema.optional(),
   logic: LogicArraySchema.optional()
 });
 var MatNextButtonFieldSchema = BaseFieldDefSchema.extend({
-  type: z32.literal("next"),
+  type: z33.literal("next"),
   props: MatButtonPropsSchema.optional(),
   logic: LogicArraySchema.optional()
 });
 var MatPreviousButtonFieldSchema = BaseFieldDefSchema.extend({
-  type: z32.literal("previous"),
+  type: z33.literal("previous"),
   props: MatButtonPropsSchema.optional()
 });
 var MatAddArrayItemButtonFieldSchema = BaseFieldDefSchema.extend({
-  type: z32.literal("addArrayItem"),
+  type: z33.literal("addArrayItem"),
   /**
    * Key of the array field to add items to.
    * If omitted, uses the parent array context.
    */
-  arrayKey: z32.string().optional(),
+  arrayKey: z33.string().optional(),
   props: MatButtonPropsSchema.optional()
 });
 var MatRemoveArrayItemButtonFieldSchema = BaseFieldDefSchema.extend({
-  type: z32.literal("removeArrayItem"),
+  type: z33.literal("removeArrayItem"),
   /**
    * Key of the array field to remove items from.
    * If omitted, uses the parent array context.
    */
-  arrayKey: z32.string().optional(),
+  arrayKey: z33.string().optional(),
   props: MatButtonPropsSchema.optional()
 });
 
 // internal/dynamic-forms-zod/material/src/mat-leaf-field.schema.ts
-import { z as z35 } from "zod";
+import { z as z36 } from "zod";
 
 // internal/dynamic-forms-zod/src/lib/schemas/leaves/text-field.schema.ts
-import { z as z33 } from "zod";
-var TextElementTypeSchema = z33.enum(["p", "h1", "h2", "h3", "h4", "h5", "h6", "span"]);
-var TextPropsSchema = z33.object({
+import { z as z34 } from "zod";
+var TextElementTypeSchema = z34.enum(["p", "h1", "h2", "h3", "h4", "h5", "h6", "span"]);
+var TextPropsSchema = z34.object({
   /**
    * HTML element type to render the text.
    */
@@ -4150,7 +4730,7 @@ var TextFieldSchema = BaseFieldDefSchema.extend({
   /**
    * Field type discriminant.
    */
-  type: z33.literal("text"),
+  type: z34.literal("text"),
   /**
    * Text-specific properties.
    */
@@ -4162,9 +4742,9 @@ var TextFieldSchema = BaseFieldDefSchema.extend({
 });
 
 // internal/dynamic-forms-zod/src/lib/schemas/leaves/hidden-field.schema.ts
-import { z as z34 } from "zod";
-var HiddenScalarSchema = z34.union([z34.string(), z34.number(), z34.boolean()]);
-var HiddenValueSchema = z34.union([HiddenScalarSchema, z34.array(HiddenScalarSchema)]);
+import { z as z35 } from "zod";
+var HiddenScalarSchema = z35.union([z35.string(), z35.number(), z35.boolean()]);
+var HiddenValueSchema = z35.union([HiddenScalarSchema, z35.array(HiddenScalarSchema)]);
 var HiddenFieldSchema = BaseFieldDefSchema.omit({
   label: true,
   meta: true,
@@ -4180,7 +4760,7 @@ var HiddenFieldSchema = BaseFieldDefSchema.omit({
   /**
    * Field type discriminant.
    */
-  type: z34.literal("hidden"),
+  type: z35.literal("hidden"),
   /**
    * The value to store. Required for hidden fields.
    */
@@ -4188,20 +4768,20 @@ var HiddenFieldSchema = BaseFieldDefSchema.omit({
 });
 
 // internal/dynamic-forms-zod/material/src/mat-leaf-field.schema.ts
-var MatLeafFieldSchema = z35.discriminatedUnion("type", [
+var MatLeafFieldSchema = z36.discriminatedUnion("type", [
   // Default fields
   TextFieldSchema,
   HiddenFieldSchema,
   // Material value fields
-  MatInputFieldSchema,
-  MatTextareaFieldSchema,
-  MatSelectFieldSchema,
+  MatInputFieldSchemaObject,
+  MatTextareaFieldSchemaObject,
+  MatSelectFieldSchemaObject,
   MatCheckboxFieldSchema,
-  MatRadioFieldSchema,
-  MatMultiCheckboxFieldSchema,
+  MatRadioFieldSchemaObject,
+  MatMultiCheckboxFieldSchemaObject,
   MatToggleFieldSchema,
-  MatSliderFieldSchema,
-  MatDatepickerFieldSchema,
+  MatSliderFieldSchemaObject,
+  MatDatepickerFieldSchemaObject,
   // Material button fields
   MatButtonFieldSchema,
   MatSubmitButtonFieldSchema,
@@ -4209,18 +4789,18 @@ var MatLeafFieldSchema = z35.discriminatedUnion("type", [
   MatPreviousButtonFieldSchema,
   MatAddArrayItemButtonFieldSchema,
   MatRemoveArrayItemButtonFieldSchema
-]);
+]).superRefine(nullableValueRefine);
 
 // internal/dynamic-forms-zod/src/lib/schemas/containers/factories.ts
-import { z as z36 } from "zod";
-var ContainerLogicSchema = z36.object({
-  type: z36.literal("hidden"),
-  condition: z36.union([ConditionalExpressionSchema, z36.boolean()])
+import { z as z37 } from "zod";
+var ContainerLogicSchema = z37.object({
+  type: z37.literal("hidden"),
+  condition: z37.union([ConditionalExpressionSchema, z37.boolean()])
 });
 function createContainerSchemas(options) {
   const { leafFieldSchema } = options;
-  const AnyFieldSchema = z36.lazy(
-    () => z36.union([
+  const AnyFieldSchema = z37.lazy(
+    () => z37.union([
       leafFieldSchema,
       PageFieldSchema,
       RowFieldSchema,
@@ -4234,67 +4814,67 @@ function createContainerSchemas(options) {
   }).extend({
     // Explicitly forbid label on container fields
     // This makes Zod reject any value for these properties
-    label: z36.never().optional(),
-    meta: z36.never().optional()
+    label: z37.never().optional(),
+    meta: z37.never().optional()
   });
   const PageFieldSchema = ContainerBaseSchema.extend({
-    type: z36.literal("page"),
-    fields: z36.array(AnyFieldSchema),
-    logic: z36.array(ContainerLogicSchema).optional(),
+    type: z37.literal("page"),
+    fields: z37.array(AnyFieldSchema),
+    logic: z37.array(ContainerLogicSchema).optional(),
     // Also forbid title (common mistake)
-    title: z36.never().optional()
+    title: z37.never().optional()
   });
   const RowFieldSchema = ContainerBaseSchema.extend({
-    type: z36.literal("row"),
-    fields: z36.array(AnyFieldSchema),
+    type: z37.literal("row"),
+    fields: z37.array(AnyFieldSchema),
     // Container logic - only 'hidden' type allowed (same as pages)
-    logic: z36.array(ContainerLogicSchema).optional()
+    logic: z37.array(ContainerLogicSchema).optional()
   });
   const GroupFieldSchema = ContainerBaseSchema.extend({
-    type: z36.literal("group"),
-    fields: z36.array(AnyFieldSchema),
+    type: z37.literal("group"),
+    fields: z37.array(AnyFieldSchema),
     // Container logic - only 'hidden' type allowed (same as pages)
-    logic: z36.array(ContainerLogicSchema).optional()
+    logic: z37.array(ContainerLogicSchema).optional()
   });
-  const ArrayButtonConfigSchema = z36.object({
-    label: z36.string().optional(),
-    props: z36.record(z36.unknown()).optional()
+  const ArrayButtonConfigSchema = z37.object({
+    label: z37.string().optional(),
+    props: z37.record(z37.unknown()).optional()
   });
   const FullArrayFieldSchema = ContainerBaseSchema.extend({
-    type: z36.literal("array"),
-    fields: z36.array(AnyFieldSchema),
-    logic: z36.array(ContainerLogicSchema).optional(),
+    type: z37.literal("array"),
+    fields: z37.array(AnyFieldSchema),
+    logic: z37.array(ContainerLogicSchema).optional(),
     // Full API does not use template
-    template: z36.never().optional(),
+    template: z37.never().optional(),
     // Array length validation
-    minLength: z36.number().int().min(0).optional(),
-    maxLength: z36.number().int().min(0).optional()
+    minLength: z37.number().int().min(0).optional(),
+    maxLength: z37.number().int().min(0).optional()
   });
-  const ArrayAllowedChildSchema = z36.lazy(
+  const ArrayAllowedChildSchema = z37.lazy(
     () => AnyFieldSchema.refine((field) => field.type !== "page" && field.type !== "array", {
       message: "Array templates cannot contain page or array fields. Only leaf fields, rows, and groups are allowed."
     })
   );
   const SimplifiedArrayFieldSchema = ContainerBaseSchema.extend({
-    type: z36.literal("array"),
+    type: z37.literal("array"),
     // Template: single field (primitive array) or array of fields (object array)
     // Only ArrayAllowedChildren (leaf fields, rows, groups) are valid — no pages or nested arrays.
-    template: z36.union([ArrayAllowedChildSchema, z36.array(ArrayAllowedChildSchema)]),
+    template: z37.union([ArrayAllowedChildSchema, z37.array(ArrayAllowedChildSchema)]),
     // Initial values for the array
-    value: z36.array(z36.unknown()).optional(),
+    value: z37.array(z37.unknown()).optional(),
     // Button customization or opt-out (false to disable)
-    addButton: z36.union([ArrayButtonConfigSchema, z36.literal(false)]).optional(),
-    removeButton: z36.union([ArrayButtonConfigSchema, z36.literal(false)]).optional(),
-    logic: z36.array(ContainerLogicSchema).optional(),
+    addButton: z37.union([ArrayButtonConfigSchema, z37.literal(false)]).optional(),
+    removeButton: z37.union([ArrayButtonConfigSchema, z37.literal(false)]).optional(),
+    logic: z37.array(ContainerLogicSchema).optional(),
     // Array length validation
-    minLength: z36.number().int().min(0).optional(),
-    maxLength: z36.number().int().min(0).optional(),
+    minLength: z37.number().int().min(0).optional(),
+    maxLength: z37.number().int().min(0).optional(),
     // Simplified API does not use fields
-    fields: z36.never().optional(),
-    minItems: z36.never().optional(),
-    maxItems: z36.never().optional()
+    fields: z37.never().optional(),
+    minItems: z37.never().optional(),
+    maxItems: z37.never().optional()
   });
-  const ArrayFieldSchema = z36.union([FullArrayFieldSchema, SimplifiedArrayFieldSchema]);
+  const ArrayFieldSchema = z37.union([FullArrayFieldSchema, SimplifiedArrayFieldSchema]);
   const AllFieldsSchema = AnyFieldSchema;
   return {
     PageFieldSchema,
@@ -4316,48 +4896,48 @@ var MatArrayFieldSchema = containerSchemas.ArrayFieldSchema;
 var MatFieldSchema = containerSchemas.AllFieldsSchema;
 
 // internal/dynamic-forms-zod/material/src/mat-form-config.schema.ts
-import { z as z40 } from "zod";
+import { z as z41 } from "zod";
 
 // internal/dynamic-forms-zod/src/lib/schemas/form/form-config.schema.ts
-import { z as z39 } from "zod";
+import { z as z40 } from "zod";
 
 // internal/dynamic-forms-zod/src/lib/schemas/form/form-options.schema.ts
-import { z as z37 } from "zod";
-var SubmitButtonOptionsSchema = z37.object({
+import { z as z38 } from "zod";
+var SubmitButtonOptionsSchema = z38.object({
   /**
    * Whether to disable the submit button when the form is invalid.
    * Defaults to true.
    */
-  disableWhenInvalid: z37.boolean().optional(),
+  disableWhenInvalid: z38.boolean().optional(),
   /**
    * Whether to disable the submit button while the form is submitting.
    * Defaults to true.
    */
-  disableWhileSubmitting: z37.boolean().optional()
+  disableWhileSubmitting: z38.boolean().optional()
 });
-var NextButtonOptionsSchema = z37.object({
+var NextButtonOptionsSchema = z38.object({
   /**
    * Whether to disable the next button when the current page is invalid.
    * Defaults to true.
    */
-  disableWhenPageInvalid: z37.boolean().optional(),
+  disableWhenPageInvalid: z38.boolean().optional(),
   /**
    * Whether to disable the next button while the form is submitting.
    * Defaults to true.
    */
-  disableWhileSubmitting: z37.boolean().optional()
+  disableWhileSubmitting: z38.boolean().optional()
 });
-var FormOptionsSchema = z37.object({
+var FormOptionsSchema = z38.object({
   /**
    * Whether the entire form is disabled.
    */
-  disabled: z37.boolean().optional(),
+  disabled: z38.boolean().optional(),
   /**
    * Maximum number of derivation iterations before stopping.
    * Prevents infinite loops in circular derivations.
    * Defaults to 10.
    */
-  maxDerivationIterations: z37.number().positive().optional(),
+  maxDerivationIterations: z38.number().positive().optional(),
   /**
    * Options for the submit button behavior.
    */
@@ -4370,36 +4950,36 @@ var FormOptionsSchema = z37.object({
    * Whether to exclude values of hidden fields from submission output.
    * Overrides the global withValueExclusionDefaults() setting for this form.
    */
-  excludeValueIfHidden: z37.boolean().optional(),
+  excludeValueIfHidden: z38.boolean().optional(),
   /**
    * Whether to exclude values of disabled fields from submission output.
    * Overrides the global withValueExclusionDefaults() setting for this form.
    */
-  excludeValueIfDisabled: z37.boolean().optional(),
+  excludeValueIfDisabled: z38.boolean().optional(),
   /**
    * Whether to exclude values of readonly fields from submission output.
    * Overrides the global withValueExclusionDefaults() setting for this form.
    */
-  excludeValueIfReadonly: z37.boolean().optional()
+  excludeValueIfReadonly: z38.boolean().optional()
 });
 
 // internal/dynamic-forms-zod/src/lib/schemas/form/schema-definition.schema.ts
-import { z as z38 } from "zod";
-var SchemaDefinitionSchema = z38.object({
+import { z as z39 } from "zod";
+var SchemaDefinitionSchema = z39.object({
   /**
    * Unique identifier for the schema.
    * Used to reference the schema in SchemaApplicationConfig.
    */
-  name: z38.string(),
+  name: z39.string(),
   /**
    * Human-readable description of what this schema validates.
    */
-  description: z38.string().optional(),
+  description: z39.string().optional(),
   /**
    * Field path pattern for automatic schema application.
    * Supports glob-like patterns.
    */
-  pathPattern: z38.string().optional(),
+  pathPattern: z39.string().optional(),
   /**
    * Validators to apply to fields using this schema.
    */
@@ -4411,17 +4991,17 @@ var SchemaDefinitionSchema = z38.object({
   /**
    * Nested schema applications for composing schemas.
    */
-  subSchemas: z38.array(SchemaApplicationConfigSchema).optional()
+  subSchemas: z39.array(SchemaApplicationConfigSchema).optional()
 });
-var SchemaDefinitionsArraySchema = z38.array(SchemaDefinitionSchema);
+var SchemaDefinitionsArraySchema = z39.array(SchemaDefinitionSchema);
 
 // internal/dynamic-forms-zod/src/lib/schemas/form/form-config.schema.ts
 function createFormConfigSchema(fieldSchema, propsSchema) {
-  const baseSchema = z39.object({
+  const baseSchema = z40.object({
     /**
      * Array of field definitions that make up the form.
      */
-    fields: z39.array(fieldSchema),
+    fields: z40.array(fieldSchema),
     /**
      * Form-level options controlling behavior.
      */
@@ -4461,15 +5041,15 @@ function createFormConfigSchema(fieldSchema, propsSchema) {
   }
   return baseSchema;
 }
-var BaseFormConfigSchema = z39.object({
-  fields: z39.array(z39.any()),
+var BaseFormConfigSchema = z40.object({
+  fields: z40.array(z40.any()),
   options: FormOptionsSchema.optional(),
   schemas: SchemaDefinitionsArraySchema.optional(),
   defaultValidationMessages: ValidationMessagesSchema.optional()
 });
 
 // internal/dynamic-forms-zod/material/src/mat-form-config.schema.ts
-var MatFormDefaultPropsSchema = z40.object({
+var MatFormDefaultPropsSchema = z41.object({
   /**
    * Default form field appearance for all fields.
    */
@@ -4486,15 +5066,15 @@ var MatFormDefaultPropsSchema = z40.object({
 var MatFormConfigSchema = createFormConfigSchema(MatFieldSchema, MatFormDefaultPropsSchema);
 
 // internal/dynamic-forms-zod/bootstrap/src/props/index.ts
-import { z as z42 } from "zod";
+import { z as z43 } from "zod";
 
 // internal/dynamic-forms-zod/bootstrap/src/props/bs-common-props.schema.ts
-import { z as z41 } from "zod";
-var BsSizeSchema = z41.enum(["sm", "lg"]);
-var BsButtonVariantSchema = z41.enum(["primary", "secondary", "success", "danger", "warning", "info", "light", "dark", "link"]);
-var BsFormFieldPropsSchema = z41.object({
+import { z as z42 } from "zod";
+var BsSizeSchema = z42.enum(["sm", "lg"]);
+var BsButtonVariantSchema = z42.enum(["primary", "secondary", "success", "danger", "warning", "info", "light", "dark", "link"]);
+var BsFormFieldPropsSchema = z42.object({
   size: BsSizeSchema.optional(),
-  floatingLabel: z41.boolean().optional(),
+  floatingLabel: z42.boolean().optional(),
   hint: DynamicTextSchema.optional(),
   validFeedback: DynamicTextSchema.optional(),
   invalidFeedback: DynamicTextSchema.optional()
@@ -4502,194 +5082,208 @@ var BsFormFieldPropsSchema = z41.object({
 
 // internal/dynamic-forms-zod/bootstrap/src/props/index.ts
 var BsInputPropsSchema = BsFormFieldPropsSchema.extend({
-  type: z42.enum(["text", "email", "password", "number", "tel", "url"]).optional(),
+  type: z43.enum(["text", "email", "password", "number", "tel", "url"]).optional(),
   placeholder: DynamicTextSchema.optional(),
-  plaintext: z42.boolean().optional()
+  plaintext: z43.boolean().optional()
 });
 var BsTextareaPropsSchema = BsFormFieldPropsSchema.extend({
-  rows: z42.number().positive().optional(),
+  rows: z43.number().positive().optional(),
   placeholder: DynamicTextSchema.optional()
 });
 var BsSelectPropsSchema = BsFormFieldPropsSchema.extend({
-  multiple: z42.boolean().optional(),
-  htmlSize: z42.number().positive().optional(),
+  multiple: z43.boolean().optional(),
+  htmlSize: z43.number().positive().optional(),
   placeholder: DynamicTextSchema.optional()
 });
-var BsCheckboxPropsSchema = z42.object({
-  switch: z42.boolean().optional(),
-  inline: z42.boolean().optional(),
-  reverse: z42.boolean().optional(),
-  indeterminate: z42.boolean().optional(),
+var BsCheckboxPropsSchema = z43.object({
+  switch: z43.boolean().optional(),
+  inline: z43.boolean().optional(),
+  reverse: z43.boolean().optional(),
+  indeterminate: z43.boolean().optional(),
   hint: DynamicTextSchema.optional()
 });
-var BsRadioPropsSchema = z42.object({
-  inline: z42.boolean().optional(),
-  reverse: z42.boolean().optional(),
-  buttonGroup: z42.boolean().optional(),
+var BsRadioPropsSchema = z43.object({
+  inline: z43.boolean().optional(),
+  reverse: z43.boolean().optional(),
+  buttonGroup: z43.boolean().optional(),
   buttonSize: BsSizeSchema.optional(),
   hint: DynamicTextSchema.optional()
 });
-var BsMultiCheckboxPropsSchema = z42.object({
-  switch: z42.boolean().optional(),
-  inline: z42.boolean().optional(),
-  reverse: z42.boolean().optional(),
+var BsMultiCheckboxPropsSchema = z43.object({
+  switch: z43.boolean().optional(),
+  inline: z43.boolean().optional(),
+  reverse: z43.boolean().optional(),
   hint: DynamicTextSchema.optional()
 });
-var BsTogglePropsSchema = z42.object({
+var BsTogglePropsSchema = z43.object({
   size: BsSizeSchema.optional(),
-  reverse: z42.boolean().optional(),
-  inline: z42.boolean().optional(),
+  reverse: z43.boolean().optional(),
+  inline: z43.boolean().optional(),
   hint: DynamicTextSchema.optional()
 });
 var BsDatepickerPropsSchema = BsFormFieldPropsSchema.extend({
-  useNgBootstrap: z42.boolean().optional(),
-  displayMonths: z42.number().positive().optional(),
-  navigation: z42.enum(["select", "arrows", "none"]).optional(),
-  outsideDays: z42.enum(["visible", "collapsed", "hidden"]).optional(),
-  showWeekNumbers: z42.boolean().optional(),
+  useNgBootstrap: z43.boolean().optional(),
+  displayMonths: z43.number().positive().optional(),
+  navigation: z43.enum(["select", "arrows", "none"]).optional(),
+  outsideDays: z43.enum(["visible", "collapsed", "hidden"]).optional(),
+  showWeekNumbers: z43.boolean().optional(),
   placeholder: DynamicTextSchema.optional()
 });
-var BsSliderPropsSchema = z42.object({
-  showValue: z42.boolean().optional(),
-  valuePrefix: z42.string().optional(),
-  valueSuffix: z42.string().optional(),
+var BsSliderPropsSchema = z43.object({
+  showValue: z43.boolean().optional(),
+  valuePrefix: z43.string().optional(),
+  valueSuffix: z43.string().optional(),
   hint: DynamicTextSchema.optional(),
-  min: z42.number().optional(),
-  max: z42.number().optional(),
-  step: z42.number().positive().optional()
+  min: z43.number().optional(),
+  max: z43.number().optional(),
+  step: z43.number().positive().optional()
 });
-var BsButtonPropsSchema = z42.object({
+var BsButtonPropsSchema = z43.object({
   variant: BsButtonVariantSchema.optional(),
-  outline: z42.boolean().optional(),
+  outline: z43.boolean().optional(),
   size: BsSizeSchema.optional(),
-  block: z42.boolean().optional(),
-  active: z42.boolean().optional(),
-  type: z42.enum(["button", "submit", "reset"]).optional()
+  block: z43.boolean().optional(),
+  active: z43.boolean().optional(),
+  type: z43.enum(["button", "submit", "reset"]).optional()
 });
 
 // internal/dynamic-forms-zod/bootstrap/src/fields/index.ts
-import { z as z43 } from "zod";
+import { z as z44 } from "zod";
 var BsValueFieldBase = BaseFieldDefSchema.merge(FieldWithValidationSchema);
-var BsInputFieldSchema = BsValueFieldBase.extend({
-  type: z43.literal("input"),
-  value: z43.string().optional(),
+var BsInputFieldSchemaObject = BsValueFieldBase.extend({
+  type: z44.literal("input"),
+  nullable: z44.boolean().optional(),
+  value: z44.string().nullable().optional(),
   placeholder: DynamicTextSchema.optional(),
   props: BsInputPropsSchema.optional()
 });
-var BsTextareaFieldSchema = BsValueFieldBase.extend({
-  type: z43.literal("textarea"),
-  value: z43.string().optional(),
+var BsInputFieldSchema = BsInputFieldSchemaObject.superRefine(nullableValueRefine);
+var BsTextareaFieldSchemaObject = BsValueFieldBase.extend({
+  type: z44.literal("textarea"),
+  nullable: z44.boolean().optional(),
+  value: z44.string().nullable().optional(),
   placeholder: DynamicTextSchema.optional(),
   props: BsTextareaPropsSchema.optional()
 });
-var BsSelectFieldSchema = BsValueFieldBase.extend({
-  type: z43.literal("select"),
-  value: z43.string().optional(),
+var BsTextareaFieldSchema = BsTextareaFieldSchemaObject.superRefine(nullableValueRefine);
+var BsSelectFieldSchemaObject = BsValueFieldBase.extend({
+  type: z44.literal("select"),
+  nullable: z44.boolean().optional(),
+  value: z44.string().nullable().optional(),
   // Bootstrap select only supports strings
   placeholder: DynamicTextSchema.optional(),
   options: FieldOptionsSchema,
   props: BsSelectPropsSchema.optional()
 });
+var BsSelectFieldSchema = BsSelectFieldSchemaObject.superRefine(nullableValueRefine);
 var BsCheckboxFieldSchema = BsValueFieldBase.extend({
-  type: z43.literal("checkbox"),
-  value: z43.boolean().optional(),
+  type: z44.literal("checkbox"),
+  value: z44.boolean().optional(),
   placeholder: DynamicTextSchema.optional(),
   props: BsCheckboxPropsSchema.optional()
 });
-var BsRadioFieldSchema = BsValueFieldBase.extend({
-  type: z43.literal("radio"),
-  value: z43.unknown().optional(),
+var BsRadioFieldSchemaObject = BsValueFieldBase.extend({
+  type: z44.literal("radio"),
+  nullable: z44.boolean().optional(),
+  value: z44.unknown().nullable().optional(),
   placeholder: DynamicTextSchema.optional(),
   options: FieldOptionsSchema,
   props: BsRadioPropsSchema.optional()
 });
-var BsMultiCheckboxFieldSchema = BsValueFieldBase.extend({
-  type: z43.literal("multi-checkbox"),
-  value: z43.array(z43.unknown()).optional(),
+var BsRadioFieldSchema = BsRadioFieldSchemaObject.superRefine(nullableValueRefine);
+var BsMultiCheckboxFieldSchemaObject = BsValueFieldBase.extend({
+  type: z44.literal("multi-checkbox"),
+  nullable: z44.boolean().optional(),
+  value: z44.array(z44.unknown()).nullable().optional(),
   placeholder: DynamicTextSchema.optional(),
   options: FieldOptionsSchema,
   props: BsMultiCheckboxPropsSchema.optional()
 });
+var BsMultiCheckboxFieldSchema = BsMultiCheckboxFieldSchemaObject.superRefine(nullableValueRefine);
 var BsToggleFieldSchema = BsValueFieldBase.extend({
-  type: z43.literal("toggle"),
-  value: z43.boolean().optional(),
+  type: z44.literal("toggle"),
+  value: z44.boolean().optional(),
   placeholder: DynamicTextSchema.optional(),
   props: BsTogglePropsSchema.optional()
 });
-var BsDatepickerFieldSchema = BsValueFieldBase.extend({
-  type: z43.literal("datepicker"),
-  value: z43.union([z43.string(), z43.null()]).optional(),
-  minDate: z43.union([z43.string(), z43.null()]).optional(),
-  maxDate: z43.union([z43.string(), z43.null()]).optional(),
-  startAt: z43.union([z43.string(), z43.null()]).optional(),
+var BsDatepickerFieldSchemaObject = BsValueFieldBase.extend({
+  type: z44.literal("datepicker"),
+  nullable: z44.boolean().optional(),
+  value: z44.union([z44.string(), z44.null()]).optional(),
+  minDate: z44.union([z44.string(), z44.null()]).optional(),
+  maxDate: z44.union([z44.string(), z44.null()]).optional(),
+  startAt: z44.union([z44.string(), z44.null()]).optional(),
   placeholder: DynamicTextSchema.optional(),
   props: BsDatepickerPropsSchema.optional()
 });
-var BsSliderFieldSchema = BsValueFieldBase.extend({
-  type: z43.literal("slider"),
-  value: z43.number().optional(),
-  minValue: z43.number().optional(),
-  maxValue: z43.number().optional(),
-  step: z43.number().positive().optional(),
+var BsDatepickerFieldSchema = BsDatepickerFieldSchemaObject.superRefine(nullableValueRefine);
+var BsSliderFieldSchemaObject = BsValueFieldBase.extend({
+  type: z44.literal("slider"),
+  nullable: z44.boolean().optional(),
+  value: z44.number().nullable().optional(),
+  minValue: z44.number().optional(),
+  maxValue: z44.number().optional(),
+  step: z44.number().positive().optional(),
   placeholder: DynamicTextSchema.optional(),
   props: BsSliderPropsSchema.optional()
 });
+var BsSliderFieldSchema = BsSliderFieldSchemaObject.superRefine(nullableValueRefine);
 var BsButtonFieldSchema = BaseFieldDefSchema.extend({
-  type: z43.literal("button"),
-  event: z43.string().optional(),
-  eventArgs: z43.array(z43.union([z43.string(), z43.number(), z43.boolean(), z43.null(), z43.undefined()])).optional(),
+  type: z44.literal("button"),
+  event: z44.string().optional(),
+  eventArgs: z44.array(z44.union([z44.string(), z44.number(), z44.boolean(), z44.null(), z44.undefined()])).optional(),
   props: BsButtonPropsSchema.optional(),
   logic: LogicArraySchema.optional()
 });
 var BsSubmitButtonFieldSchema = BaseFieldDefSchema.extend({
-  type: z43.literal("submit"),
+  type: z44.literal("submit"),
   props: BsButtonPropsSchema.optional(),
   logic: LogicArraySchema.optional()
 });
 var BsNextButtonFieldSchema = BaseFieldDefSchema.extend({
-  type: z43.literal("next"),
+  type: z44.literal("next"),
   props: BsButtonPropsSchema.optional(),
   logic: LogicArraySchema.optional()
 });
 var BsPreviousButtonFieldSchema = BaseFieldDefSchema.extend({
-  type: z43.literal("previous"),
+  type: z44.literal("previous"),
   props: BsButtonPropsSchema.optional()
 });
 var BsAddArrayItemButtonFieldSchema = BaseFieldDefSchema.extend({
-  type: z43.literal("addArrayItem"),
-  arrayKey: z43.string().optional(),
+  type: z44.literal("addArrayItem"),
+  arrayKey: z44.string().optional(),
   props: BsButtonPropsSchema.optional()
 });
 var BsRemoveArrayItemButtonFieldSchema = BaseFieldDefSchema.extend({
-  type: z43.literal("removeArrayItem"),
-  arrayKey: z43.string().optional(),
+  type: z44.literal("removeArrayItem"),
+  arrayKey: z44.string().optional(),
   props: BsButtonPropsSchema.optional()
 });
 
 // internal/dynamic-forms-zod/bootstrap/src/bs-leaf-field.schema.ts
-import { z as z44 } from "zod";
-var BsLeafFieldSchema = z44.discriminatedUnion("type", [
+import { z as z45 } from "zod";
+var BsLeafFieldSchema = z45.discriminatedUnion("type", [
   TextFieldSchema,
   HiddenFieldSchema,
-  BsInputFieldSchema,
-  BsTextareaFieldSchema,
-  BsSelectFieldSchema,
+  BsInputFieldSchemaObject,
+  BsTextareaFieldSchemaObject,
+  BsSelectFieldSchemaObject,
   BsCheckboxFieldSchema,
-  BsRadioFieldSchema,
-  BsMultiCheckboxFieldSchema,
+  BsRadioFieldSchemaObject,
+  BsMultiCheckboxFieldSchemaObject,
   BsToggleFieldSchema,
-  BsDatepickerFieldSchema,
-  BsSliderFieldSchema,
+  BsDatepickerFieldSchemaObject,
+  BsSliderFieldSchemaObject,
   BsButtonFieldSchema,
   BsSubmitButtonFieldSchema,
   BsNextButtonFieldSchema,
   BsPreviousButtonFieldSchema,
   BsAddArrayItemButtonFieldSchema,
   BsRemoveArrayItemButtonFieldSchema
-]);
+]).superRefine(nullableValueRefine);
 
 // internal/dynamic-forms-zod/bootstrap/src/bs-form-config.schema.ts
-import { z as z45 } from "zod";
+import { z as z46 } from "zod";
 var containerSchemas2 = createContainerSchemas({
   leafFieldSchema: BsLeafFieldSchema
 });
@@ -4698,186 +5292,200 @@ var BsRowFieldSchema = containerSchemas2.RowFieldSchema;
 var BsGroupFieldSchema = containerSchemas2.GroupFieldSchema;
 var BsArrayFieldSchema = containerSchemas2.ArrayFieldSchema;
 var BsFieldSchema = containerSchemas2.AllFieldsSchema;
-var BsFormDefaultPropsSchema = z45.object({
+var BsFormDefaultPropsSchema = z46.object({
   size: BsSizeSchema.optional(),
-  floatingLabel: z45.boolean().optional()
+  floatingLabel: z46.boolean().optional()
 });
 var BsFormConfigSchema = createFormConfigSchema(BsFieldSchema, BsFormDefaultPropsSchema);
 
 // internal/dynamic-forms-zod/primeng/src/props/index.ts
-import { z as z46 } from "zod";
-var PrimeSeveritySchema = z46.enum(["primary", "secondary", "success", "info", "warn", "danger", "help", "contrast"]);
-var PrimeCommonPropsSchema = z46.object({
-  styleClass: z46.string().optional(),
+import { z as z47 } from "zod";
+var PrimeSeveritySchema = z47.enum(["primary", "secondary", "success", "info", "warn", "danger", "help", "contrast"]);
+var PrimeCommonPropsSchema = z47.object({
+  styleClass: z47.string().optional(),
   hint: DynamicTextSchema.optional()
 });
 var PrimeInputPropsSchema = PrimeCommonPropsSchema.extend({
-  type: z46.enum(["text", "email", "password", "number", "tel", "url"]).optional(),
+  type: z47.enum(["text", "email", "password", "number", "tel", "url"]).optional(),
   placeholder: DynamicTextSchema.optional(),
-  size: z46.enum(["small", "large"]).optional(),
-  variant: z46.enum(["outlined", "filled"]).optional()
+  size: z47.enum(["small", "large"]).optional(),
+  variant: z47.enum(["outlined", "filled"]).optional()
 });
 var PrimeCheckboxPropsSchema = PrimeCommonPropsSchema.extend({
-  binary: z46.boolean().optional(),
-  trueValue: z46.unknown().optional(),
-  falseValue: z46.unknown().optional()
+  binary: z47.boolean().optional(),
+  trueValue: z47.unknown().optional(),
+  falseValue: z47.unknown().optional()
 });
 var PrimeRadioPropsSchema = PrimeCommonPropsSchema.extend({
-  name: z46.string().optional()
+  name: z47.string().optional()
 });
 var PrimeSelectPropsSchema = PrimeCommonPropsSchema.extend({
-  multiple: z46.boolean().optional(),
-  filter: z46.boolean().optional(),
+  multiple: z47.boolean().optional(),
+  filter: z47.boolean().optional(),
   placeholder: DynamicTextSchema.optional(),
-  showClear: z46.boolean().optional()
+  showClear: z47.boolean().optional()
 });
 var PrimeMultiCheckboxPropsSchema = PrimeCommonPropsSchema;
 var PrimeDatepickerPropsSchema = PrimeCommonPropsSchema.extend({
-  dateFormat: z46.string().optional(),
-  inline: z46.boolean().optional(),
-  showIcon: z46.boolean().optional(),
-  showButtonBar: z46.boolean().optional(),
-  selectionMode: z46.enum(["single", "multiple", "range"]).optional(),
-  touchUI: z46.boolean().optional(),
-  view: z46.enum(["date", "month", "year"]).optional(),
+  dateFormat: z47.string().optional(),
+  inline: z47.boolean().optional(),
+  showIcon: z47.boolean().optional(),
+  showButtonBar: z47.boolean().optional(),
+  selectionMode: z47.enum(["single", "multiple", "range"]).optional(),
+  touchUI: z47.boolean().optional(),
+  view: z47.enum(["date", "month", "year"]).optional(),
   placeholder: DynamicTextSchema.optional()
 });
 var PrimeTextareaPropsSchema = PrimeCommonPropsSchema.extend({
-  rows: z46.number().positive().optional(),
-  autoResize: z46.boolean().optional(),
-  maxlength: z46.number().positive().optional(),
+  rows: z47.number().positive().optional(),
+  autoResize: z47.boolean().optional(),
+  maxlength: z47.number().positive().optional(),
   placeholder: DynamicTextSchema.optional()
 });
 var PrimeSliderPropsSchema = PrimeCommonPropsSchema.extend({
-  min: z46.number().optional(),
-  max: z46.number().optional(),
-  step: z46.number().positive().optional(),
-  range: z46.boolean().optional(),
-  orientation: z46.enum(["horizontal", "vertical"]).optional()
+  min: z47.number().optional(),
+  max: z47.number().optional(),
+  step: z47.number().positive().optional(),
+  range: z47.boolean().optional(),
+  orientation: z47.enum(["horizontal", "vertical"]).optional()
 });
 var PrimeTogglePropsSchema = PrimeCommonPropsSchema;
-var PrimeButtonPropsSchema = z46.object({
+var PrimeButtonPropsSchema = z47.object({
   severity: PrimeSeveritySchema.optional(),
-  text: z46.boolean().optional(),
-  outlined: z46.boolean().optional(),
-  raised: z46.boolean().optional(),
-  rounded: z46.boolean().optional(),
-  icon: z46.string().optional(),
-  iconPos: z46.enum(["left", "right", "top", "bottom"]).optional(),
-  type: z46.enum(["button", "submit", "reset"]).optional()
+  text: z47.boolean().optional(),
+  outlined: z47.boolean().optional(),
+  raised: z47.boolean().optional(),
+  rounded: z47.boolean().optional(),
+  icon: z47.string().optional(),
+  iconPos: z47.enum(["left", "right", "top", "bottom"]).optional(),
+  type: z47.enum(["button", "submit", "reset"]).optional()
 });
 
 // internal/dynamic-forms-zod/primeng/src/fields/index.ts
-import { z as z47 } from "zod";
+import { z as z48 } from "zod";
 var PrimeValueFieldBase = BaseFieldDefSchema.merge(FieldWithValidationSchema);
-var PrimeInputFieldSchema = PrimeValueFieldBase.extend({
-  type: z47.literal("input"),
-  value: z47.string().optional(),
+var PrimeInputFieldSchemaObject = PrimeValueFieldBase.extend({
+  type: z48.literal("input"),
+  nullable: z48.boolean().optional(),
+  value: z48.string().nullable().optional(),
   placeholder: DynamicTextSchema.optional(),
   props: PrimeInputPropsSchema.optional()
 });
+var PrimeInputFieldSchema = PrimeInputFieldSchemaObject.superRefine(nullableValueRefine);
 var PrimeCheckboxFieldSchema = PrimeValueFieldBase.extend({
-  type: z47.literal("checkbox"),
-  value: z47.boolean().optional(),
+  type: z48.literal("checkbox"),
+  value: z48.boolean().optional(),
   placeholder: DynamicTextSchema.optional(),
   props: PrimeCheckboxPropsSchema.optional()
 });
-var PrimeRadioFieldSchema = PrimeValueFieldBase.extend({
-  type: z47.literal("radio"),
-  value: z47.unknown().optional(),
+var PrimeRadioFieldSchemaObject = PrimeValueFieldBase.extend({
+  type: z48.literal("radio"),
+  nullable: z48.boolean().optional(),
+  value: z48.unknown().nullable().optional(),
   placeholder: DynamicTextSchema.optional(),
   options: FieldOptionsSchema,
   props: PrimeRadioPropsSchema.optional()
 });
-var PrimeSelectFieldSchema = PrimeValueFieldBase.extend({
-  type: z47.literal("select"),
-  value: z47.unknown().optional(),
+var PrimeRadioFieldSchema = PrimeRadioFieldSchemaObject.superRefine(nullableValueRefine);
+var PrimeSelectFieldSchemaObject = PrimeValueFieldBase.extend({
+  type: z48.literal("select"),
+  nullable: z48.boolean().optional(),
+  value: z48.unknown().nullable().optional(),
   placeholder: DynamicTextSchema.optional(),
   options: FieldOptionsSchema,
   props: PrimeSelectPropsSchema.optional()
 });
-var PrimeMultiCheckboxFieldSchema = PrimeValueFieldBase.extend({
-  type: z47.literal("multi-checkbox"),
-  value: z47.array(z47.unknown()).optional(),
+var PrimeSelectFieldSchema = PrimeSelectFieldSchemaObject.superRefine(nullableValueRefine);
+var PrimeMultiCheckboxFieldSchemaObject = PrimeValueFieldBase.extend({
+  type: z48.literal("multi-checkbox"),
+  nullable: z48.boolean().optional(),
+  value: z48.array(z48.unknown()).nullable().optional(),
   placeholder: DynamicTextSchema.optional(),
   options: FieldOptionsSchema,
   props: PrimeMultiCheckboxPropsSchema.optional()
 });
-var PrimeDatepickerFieldSchema = PrimeValueFieldBase.extend({
-  type: z47.literal("datepicker"),
-  value: z47.union([z47.string(), z47.null()]).optional(),
-  minDate: z47.union([z47.string(), z47.null()]).optional(),
-  maxDate: z47.union([z47.string(), z47.null()]).optional(),
-  startAt: z47.union([z47.string(), z47.null()]).optional(),
+var PrimeMultiCheckboxFieldSchema = PrimeMultiCheckboxFieldSchemaObject.superRefine(nullableValueRefine);
+var PrimeDatepickerFieldSchemaObject = PrimeValueFieldBase.extend({
+  type: z48.literal("datepicker"),
+  nullable: z48.boolean().optional(),
+  value: z48.union([z48.string(), z48.null()]).optional(),
+  minDate: z48.union([z48.string(), z48.null()]).optional(),
+  maxDate: z48.union([z48.string(), z48.null()]).optional(),
+  startAt: z48.union([z48.string(), z48.null()]).optional(),
   placeholder: DynamicTextSchema.optional(),
   props: PrimeDatepickerPropsSchema.optional()
 });
-var PrimeTextareaFieldSchema = PrimeValueFieldBase.extend({
-  type: z47.literal("textarea"),
-  value: z47.string().optional(),
+var PrimeDatepickerFieldSchema = PrimeDatepickerFieldSchemaObject.superRefine(nullableValueRefine);
+var PrimeTextareaFieldSchemaObject = PrimeValueFieldBase.extend({
+  type: z48.literal("textarea"),
+  nullable: z48.boolean().optional(),
+  value: z48.string().nullable().optional(),
   placeholder: DynamicTextSchema.optional(),
   props: PrimeTextareaPropsSchema.optional()
 });
-var PrimeSliderFieldSchema = PrimeValueFieldBase.extend({
-  type: z47.literal("slider"),
-  value: z47.number().optional(),
-  minValue: z47.number().optional(),
-  maxValue: z47.number().optional(),
-  step: z47.number().positive().optional(),
+var PrimeTextareaFieldSchema = PrimeTextareaFieldSchemaObject.superRefine(nullableValueRefine);
+var PrimeSliderFieldSchemaObject = PrimeValueFieldBase.extend({
+  type: z48.literal("slider"),
+  nullable: z48.boolean().optional(),
+  value: z48.number().nullable().optional(),
+  minValue: z48.number().optional(),
+  maxValue: z48.number().optional(),
+  step: z48.number().positive().optional(),
   placeholder: DynamicTextSchema.optional(),
   props: PrimeSliderPropsSchema.optional()
 });
+var PrimeSliderFieldSchema = PrimeSliderFieldSchemaObject.superRefine(nullableValueRefine);
 var PrimeToggleFieldSchema = PrimeValueFieldBase.extend({
-  type: z47.literal("toggle"),
-  value: z47.boolean().optional(),
+  type: z48.literal("toggle"),
+  value: z48.boolean().optional(),
   placeholder: DynamicTextSchema.optional(),
   props: PrimeTogglePropsSchema.optional()
 });
 var PrimeButtonFieldSchema = BaseFieldDefSchema.extend({
-  type: z47.literal("button"),
-  event: z47.string().optional(),
-  eventArgs: z47.array(z47.union([z47.string(), z47.number(), z47.boolean(), z47.null(), z47.undefined()])).optional(),
+  type: z48.literal("button"),
+  event: z48.string().optional(),
+  eventArgs: z48.array(z48.union([z48.string(), z48.number(), z48.boolean(), z48.null(), z48.undefined()])).optional(),
   props: PrimeButtonPropsSchema.optional(),
   logic: LogicArraySchema.optional()
 });
 var PrimeSubmitButtonFieldSchema = BaseFieldDefSchema.extend({
-  type: z47.literal("submit"),
+  type: z48.literal("submit"),
   props: PrimeButtonPropsSchema.optional(),
   logic: LogicArraySchema.optional()
 });
 var PrimeNextButtonFieldSchema = BaseFieldDefSchema.extend({
-  type: z47.literal("next"),
+  type: z48.literal("next"),
   props: PrimeButtonPropsSchema.optional(),
   logic: LogicArraySchema.optional()
 });
 var PrimePreviousButtonFieldSchema = BaseFieldDefSchema.extend({
-  type: z47.literal("previous"),
+  type: z48.literal("previous"),
   props: PrimeButtonPropsSchema.optional()
 });
 var PrimeAddArrayItemButtonFieldSchema = BaseFieldDefSchema.extend({
-  type: z47.literal("addArrayItem"),
-  arrayKey: z47.string().optional(),
+  type: z48.literal("addArrayItem"),
+  arrayKey: z48.string().optional(),
   props: PrimeButtonPropsSchema.optional()
 });
 var PrimeRemoveArrayItemButtonFieldSchema = BaseFieldDefSchema.extend({
-  type: z47.literal("removeArrayItem"),
-  arrayKey: z47.string().optional(),
+  type: z48.literal("removeArrayItem"),
+  arrayKey: z48.string().optional(),
   props: PrimeButtonPropsSchema.optional()
 });
 
 // internal/dynamic-forms-zod/primeng/src/prime-leaf-field.schema.ts
-import { z as z48 } from "zod";
-var PrimeLeafFieldSchema = z48.discriminatedUnion("type", [
+import { z as z49 } from "zod";
+var PrimeLeafFieldSchema = z49.discriminatedUnion("type", [
   TextFieldSchema,
   HiddenFieldSchema,
-  PrimeInputFieldSchema,
+  PrimeInputFieldSchemaObject,
   PrimeCheckboxFieldSchema,
-  PrimeRadioFieldSchema,
-  PrimeSelectFieldSchema,
-  PrimeMultiCheckboxFieldSchema,
-  PrimeDatepickerFieldSchema,
-  PrimeTextareaFieldSchema,
-  PrimeSliderFieldSchema,
+  PrimeRadioFieldSchemaObject,
+  PrimeSelectFieldSchemaObject,
+  PrimeMultiCheckboxFieldSchemaObject,
+  PrimeDatepickerFieldSchemaObject,
+  PrimeTextareaFieldSchemaObject,
+  PrimeSliderFieldSchemaObject,
   PrimeToggleFieldSchema,
   PrimeButtonFieldSchema,
   PrimeSubmitButtonFieldSchema,
@@ -4885,10 +5493,10 @@ var PrimeLeafFieldSchema = z48.discriminatedUnion("type", [
   PrimePreviousButtonFieldSchema,
   PrimeAddArrayItemButtonFieldSchema,
   PrimeRemoveArrayItemButtonFieldSchema
-]);
+]).superRefine(nullableValueRefine);
 
 // internal/dynamic-forms-zod/primeng/src/prime-form-config.schema.ts
-import { z as z49 } from "zod";
+import { z as z50 } from "zod";
 var containerSchemas3 = createContainerSchemas({
   leafFieldSchema: PrimeLeafFieldSchema
 });
@@ -4897,240 +5505,254 @@ var PrimeRowFieldSchema = containerSchemas3.RowFieldSchema;
 var PrimeGroupFieldSchema = containerSchemas3.GroupFieldSchema;
 var PrimeArrayFieldSchema = containerSchemas3.ArrayFieldSchema;
 var PrimeFieldSchema = containerSchemas3.AllFieldsSchema;
-var PrimeFormDefaultPropsSchema = z49.object({
-  styleClass: z49.string().optional()
+var PrimeFormDefaultPropsSchema = z50.object({
+  styleClass: z50.string().optional()
 });
 var PrimeFormConfigSchema = createFormConfigSchema(PrimeFieldSchema, PrimeFormDefaultPropsSchema);
 
 // internal/dynamic-forms-zod/ionic/src/props/index.ts
-import { z as z50 } from "zod";
-var IonicColorSchema = z50.enum(["primary", "secondary", "tertiary", "success", "warning", "danger", "light", "medium", "dark"]);
-var IonicLabelPlacementSchema = z50.enum(["start", "end", "fixed", "stacked", "floating"]);
-var IonicJustifySchema = z50.enum(["start", "end", "space-between"]);
-var IonicFillSchema = z50.enum(["solid", "outline", "clear", "default"]);
-var IonicInputPropsSchema = z50.object({
-  fill: z50.enum(["solid", "outline"]).optional(),
-  shape: z50.literal("round").optional(),
+import { z as z51 } from "zod";
+var IonicColorSchema = z51.enum(["primary", "secondary", "tertiary", "success", "warning", "danger", "light", "medium", "dark"]);
+var IonicLabelPlacementSchema = z51.enum(["start", "end", "fixed", "stacked", "floating"]);
+var IonicJustifySchema = z51.enum(["start", "end", "space-between"]);
+var IonicFillSchema = z51.enum(["solid", "outline", "clear", "default"]);
+var IonicInputPropsSchema = z51.object({
+  fill: z51.enum(["solid", "outline"]).optional(),
+  shape: z51.literal("round").optional(),
   labelPlacement: IonicLabelPlacementSchema.optional(),
   color: IonicColorSchema.optional(),
   hint: DynamicTextSchema.optional(),
   errorText: DynamicTextSchema.optional(),
-  counter: z50.boolean().optional(),
-  maxlength: z50.number().positive().optional(),
-  clearInput: z50.boolean().optional(),
-  type: z50.enum(["text", "email", "password", "number", "tel", "url"]).optional(),
+  counter: z51.boolean().optional(),
+  maxlength: z51.number().positive().optional(),
+  clearInput: z51.boolean().optional(),
+  type: z51.enum(["text", "email", "password", "number", "tel", "url"]).optional(),
   placeholder: DynamicTextSchema.optional()
 });
-var IonicCheckboxPropsSchema = z50.object({
-  labelPlacement: z50.enum(["start", "end", "fixed", "stacked"]).optional(),
+var IonicCheckboxPropsSchema = z51.object({
+  labelPlacement: z51.enum(["start", "end", "fixed", "stacked"]).optional(),
   justify: IonicJustifySchema.optional(),
-  color: z50.enum(["primary", "secondary", "tertiary", "success", "warning", "danger"]).optional(),
-  indeterminate: z50.boolean().optional(),
+  color: z51.enum(["primary", "secondary", "tertiary", "success", "warning", "danger"]).optional(),
+  indeterminate: z51.boolean().optional(),
   hint: DynamicTextSchema.optional()
 });
-var IonicRadioPropsSchema = z50.object({
-  labelPlacement: z50.enum(["start", "end", "fixed", "stacked"]).optional(),
+var IonicRadioPropsSchema = z51.object({
+  labelPlacement: z51.enum(["start", "end", "fixed", "stacked"]).optional(),
   justify: IonicJustifySchema.optional(),
-  color: z50.enum(["primary", "secondary", "tertiary", "success", "warning", "danger"]).optional(),
+  color: z51.enum(["primary", "secondary", "tertiary", "success", "warning", "danger"]).optional(),
   hint: DynamicTextSchema.optional()
 });
-var IonicTogglePropsSchema = z50.object({
-  labelPlacement: z50.enum(["start", "end", "fixed", "stacked"]).optional(),
+var IonicTogglePropsSchema = z51.object({
+  labelPlacement: z51.enum(["start", "end", "fixed", "stacked"]).optional(),
   justify: IonicJustifySchema.optional(),
-  color: z50.enum(["primary", "secondary", "tertiary", "success", "warning", "danger"]).optional(),
-  enableOnOffLabels: z50.boolean().optional(),
+  color: z51.enum(["primary", "secondary", "tertiary", "success", "warning", "danger"]).optional(),
+  enableOnOffLabels: z51.boolean().optional(),
   hint: DynamicTextSchema.optional()
 });
-var IonicSliderPropsSchema = z50.object({
-  min: z50.number().optional(),
-  max: z50.number().optional(),
-  step: z50.number().positive().optional(),
-  dualKnobs: z50.boolean().optional(),
-  pin: z50.boolean().optional(),
-  ticks: z50.boolean().optional(),
-  snaps: z50.boolean().optional(),
-  color: z50.enum(["primary", "secondary", "tertiary", "success", "warning", "danger"]).optional(),
-  labelPlacement: z50.enum(["start", "end", "fixed", "stacked"]).optional(),
+var IonicSliderPropsSchema = z51.object({
+  min: z51.number().optional(),
+  max: z51.number().optional(),
+  step: z51.number().positive().optional(),
+  dualKnobs: z51.boolean().optional(),
+  pin: z51.boolean().optional(),
+  ticks: z51.boolean().optional(),
+  snaps: z51.boolean().optional(),
+  color: z51.enum(["primary", "secondary", "tertiary", "success", "warning", "danger"]).optional(),
+  labelPlacement: z51.enum(["start", "end", "fixed", "stacked"]).optional(),
   hint: DynamicTextSchema.optional()
 });
-var IonicDatepickerPropsSchema = z50.object({
-  presentation: z50.enum(["date", "date-time", "time", "time-date", "month", "month-year", "year"]).optional(),
-  multiple: z50.boolean().optional(),
-  preferWheel: z50.boolean().optional(),
-  showDefaultButtons: z50.boolean().optional(),
-  showDefaultTitle: z50.boolean().optional(),
-  showDefaultTimeLabel: z50.boolean().optional(),
-  showClearButton: z50.boolean().optional(),
-  doneText: z50.string().optional(),
-  cancelText: z50.string().optional(),
-  size: z50.enum(["cover", "fixed"]).optional(),
-  color: z50.enum(["primary", "secondary", "tertiary", "success", "warning", "danger"]).optional(),
+var IonicDatepickerPropsSchema = z51.object({
+  presentation: z51.enum(["date", "date-time", "time", "time-date", "month", "month-year", "year"]).optional(),
+  multiple: z51.boolean().optional(),
+  preferWheel: z51.boolean().optional(),
+  showDefaultButtons: z51.boolean().optional(),
+  showDefaultTitle: z51.boolean().optional(),
+  showDefaultTimeLabel: z51.boolean().optional(),
+  showClearButton: z51.boolean().optional(),
+  doneText: z51.string().optional(),
+  cancelText: z51.string().optional(),
+  size: z51.enum(["cover", "fixed"]).optional(),
+  color: z51.enum(["primary", "secondary", "tertiary", "success", "warning", "danger"]).optional(),
   hint: DynamicTextSchema.optional(),
   placeholder: DynamicTextSchema.optional()
 });
-var IonicSelectPropsSchema = z50.object({
-  multiple: z50.boolean().optional(),
-  interface: z50.enum(["action-sheet", "popover", "alert"]).optional(),
-  cancelText: z50.string().optional(),
-  okText: z50.string().optional(),
+var IonicSelectPropsSchema = z51.object({
+  multiple: z51.boolean().optional(),
+  interface: z51.enum(["action-sheet", "popover", "alert"]).optional(),
+  cancelText: z51.string().optional(),
+  okText: z51.string().optional(),
   placeholder: DynamicTextSchema.optional(),
-  fill: z50.enum(["solid", "outline"]).optional(),
-  shape: z50.literal("round").optional(),
+  fill: z51.enum(["solid", "outline"]).optional(),
+  shape: z51.literal("round").optional(),
   labelPlacement: IonicLabelPlacementSchema.optional(),
-  color: z50.enum(["primary", "secondary", "tertiary", "success", "warning", "danger"]).optional(),
+  color: z51.enum(["primary", "secondary", "tertiary", "success", "warning", "danger"]).optional(),
   hint: DynamicTextSchema.optional()
 });
-var IonicTextareaPropsSchema = z50.object({
-  rows: z50.number().positive().optional(),
-  autoGrow: z50.boolean().optional(),
-  maxlength: z50.number().positive().optional(),
-  counter: z50.boolean().optional(),
-  fill: z50.enum(["solid", "outline"]).optional(),
-  shape: z50.literal("round").optional(),
+var IonicTextareaPropsSchema = z51.object({
+  rows: z51.number().positive().optional(),
+  autoGrow: z51.boolean().optional(),
+  maxlength: z51.number().positive().optional(),
+  counter: z51.boolean().optional(),
+  fill: z51.enum(["solid", "outline"]).optional(),
+  shape: z51.literal("round").optional(),
   labelPlacement: IonicLabelPlacementSchema.optional(),
   hint: DynamicTextSchema.optional(),
   errorText: DynamicTextSchema.optional(),
   color: IonicColorSchema.optional(),
   placeholder: DynamicTextSchema.optional()
 });
-var IonicMultiCheckboxPropsSchema = z50.object({
-  labelPlacement: z50.enum(["start", "end", "fixed", "stacked"]).optional(),
+var IonicMultiCheckboxPropsSchema = z51.object({
+  labelPlacement: z51.enum(["start", "end", "fixed", "stacked"]).optional(),
   justify: IonicJustifySchema.optional(),
-  color: z50.enum(["primary", "secondary", "tertiary", "success", "warning", "danger"]).optional(),
+  color: z51.enum(["primary", "secondary", "tertiary", "success", "warning", "danger"]).optional(),
   hint: DynamicTextSchema.optional()
 });
-var IonicButtonPropsSchema = z50.object({
-  expand: z50.enum(["full", "block"]).optional(),
+var IonicButtonPropsSchema = z51.object({
+  expand: z51.enum(["full", "block"]).optional(),
   fill: IonicFillSchema.optional(),
-  shape: z50.literal("round").optional(),
-  size: z50.enum(["small", "default", "large"]).optional(),
+  shape: z51.literal("round").optional(),
+  size: z51.enum(["small", "default", "large"]).optional(),
   color: IonicColorSchema.optional(),
-  strong: z50.boolean().optional(),
-  type: z50.enum(["button", "submit", "reset"]).optional()
+  strong: z51.boolean().optional(),
+  type: z51.enum(["button", "submit", "reset"]).optional()
 });
 
 // internal/dynamic-forms-zod/ionic/src/fields/index.ts
-import { z as z51 } from "zod";
+import { z as z52 } from "zod";
 var IonicValueFieldBase = BaseFieldDefSchema.merge(FieldWithValidationSchema);
-var IonicInputFieldSchema = IonicValueFieldBase.extend({
-  type: z51.literal("input"),
-  value: z51.string().optional(),
+var IonicInputFieldSchemaObject = IonicValueFieldBase.extend({
+  type: z52.literal("input"),
+  nullable: z52.boolean().optional(),
+  value: z52.string().nullable().optional(),
   placeholder: DynamicTextSchema.optional(),
   props: IonicInputPropsSchema.optional()
 });
+var IonicInputFieldSchema = IonicInputFieldSchemaObject.superRefine(nullableValueRefine);
 var IonicCheckboxFieldSchema = IonicValueFieldBase.extend({
-  type: z51.literal("checkbox"),
-  value: z51.boolean().optional(),
+  type: z52.literal("checkbox"),
+  value: z52.boolean().optional(),
   placeholder: DynamicTextSchema.optional(),
   props: IonicCheckboxPropsSchema.optional()
 });
-var IonicRadioFieldSchema = IonicValueFieldBase.extend({
-  type: z51.literal("radio"),
-  value: z51.unknown().optional(),
+var IonicRadioFieldSchemaObject = IonicValueFieldBase.extend({
+  type: z52.literal("radio"),
+  nullable: z52.boolean().optional(),
+  value: z52.unknown().nullable().optional(),
   placeholder: DynamicTextSchema.optional(),
   options: FieldOptionsSchema,
   props: IonicRadioPropsSchema.optional()
 });
+var IonicRadioFieldSchema = IonicRadioFieldSchemaObject.superRefine(nullableValueRefine);
 var IonicToggleFieldSchema = IonicValueFieldBase.extend({
-  type: z51.literal("toggle"),
-  value: z51.boolean().optional(),
+  type: z52.literal("toggle"),
+  value: z52.boolean().optional(),
   placeholder: DynamicTextSchema.optional(),
   props: IonicTogglePropsSchema.optional()
 });
-var IonicSliderFieldSchema = IonicValueFieldBase.extend({
-  type: z51.literal("slider"),
-  value: z51.number().optional(),
-  minValue: z51.number().optional(),
-  maxValue: z51.number().optional(),
-  step: z51.number().positive().optional(),
+var IonicSliderFieldSchemaObject = IonicValueFieldBase.extend({
+  type: z52.literal("slider"),
+  nullable: z52.boolean().optional(),
+  value: z52.number().nullable().optional(),
+  minValue: z52.number().optional(),
+  maxValue: z52.number().optional(),
+  step: z52.number().positive().optional(),
   placeholder: DynamicTextSchema.optional(),
   props: IonicSliderPropsSchema.optional()
 });
-var IonicDatepickerFieldSchema = IonicValueFieldBase.extend({
-  type: z51.literal("datepicker"),
-  value: z51.union([z51.string(), z51.null()]).optional(),
-  minDate: z51.union([z51.string(), z51.null()]).optional(),
-  maxDate: z51.union([z51.string(), z51.null()]).optional(),
-  startAt: z51.union([z51.string(), z51.null()]).optional(),
+var IonicSliderFieldSchema = IonicSliderFieldSchemaObject.superRefine(nullableValueRefine);
+var IonicDatepickerFieldSchemaObject = IonicValueFieldBase.extend({
+  type: z52.literal("datepicker"),
+  nullable: z52.boolean().optional(),
+  value: z52.union([z52.string(), z52.null()]).optional(),
+  minDate: z52.union([z52.string(), z52.null()]).optional(),
+  maxDate: z52.union([z52.string(), z52.null()]).optional(),
+  startAt: z52.union([z52.string(), z52.null()]).optional(),
   placeholder: DynamicTextSchema.optional(),
   props: IonicDatepickerPropsSchema.optional()
 });
-var IonicSelectFieldSchema = IonicValueFieldBase.extend({
-  type: z51.literal("select"),
-  value: z51.unknown().optional(),
+var IonicDatepickerFieldSchema = IonicDatepickerFieldSchemaObject.superRefine(nullableValueRefine);
+var IonicSelectFieldSchemaObject = IonicValueFieldBase.extend({
+  type: z52.literal("select"),
+  nullable: z52.boolean().optional(),
+  value: z52.unknown().nullable().optional(),
   placeholder: DynamicTextSchema.optional(),
   options: FieldOptionsSchema,
   props: IonicSelectPropsSchema.optional()
 });
-var IonicTextareaFieldSchema = IonicValueFieldBase.extend({
-  type: z51.literal("textarea"),
-  value: z51.string().optional(),
+var IonicSelectFieldSchema = IonicSelectFieldSchemaObject.superRefine(nullableValueRefine);
+var IonicTextareaFieldSchemaObject = IonicValueFieldBase.extend({
+  type: z52.literal("textarea"),
+  nullable: z52.boolean().optional(),
+  value: z52.string().nullable().optional(),
   placeholder: DynamicTextSchema.optional(),
   props: IonicTextareaPropsSchema.optional()
 });
-var IonicMultiCheckboxFieldSchema = IonicValueFieldBase.extend({
-  type: z51.literal("multi-checkbox"),
-  value: z51.array(z51.unknown()).optional(),
+var IonicTextareaFieldSchema = IonicTextareaFieldSchemaObject.superRefine(nullableValueRefine);
+var IonicMultiCheckboxFieldSchemaObject = IonicValueFieldBase.extend({
+  type: z52.literal("multi-checkbox"),
+  nullable: z52.boolean().optional(),
+  value: z52.array(z52.unknown()).nullable().optional(),
   placeholder: DynamicTextSchema.optional(),
   options: FieldOptionsSchema,
   props: IonicMultiCheckboxPropsSchema.optional()
 });
+var IonicMultiCheckboxFieldSchema = IonicMultiCheckboxFieldSchemaObject.superRefine(nullableValueRefine);
 var IonicButtonFieldSchema = BaseFieldDefSchema.extend({
-  type: z51.literal("button"),
-  event: z51.string().optional(),
-  eventArgs: z51.array(z51.union([z51.string(), z51.number(), z51.boolean(), z51.null(), z51.undefined()])).optional(),
+  type: z52.literal("button"),
+  event: z52.string().optional(),
+  eventArgs: z52.array(z52.union([z52.string(), z52.number(), z52.boolean(), z52.null(), z52.undefined()])).optional(),
   props: IonicButtonPropsSchema.optional(),
   logic: LogicArraySchema.optional()
 });
 var IonicSubmitButtonFieldSchema = BaseFieldDefSchema.extend({
-  type: z51.literal("submit"),
+  type: z52.literal("submit"),
   props: IonicButtonPropsSchema.optional(),
   logic: LogicArraySchema.optional()
 });
 var IonicNextButtonFieldSchema = BaseFieldDefSchema.extend({
-  type: z51.literal("next"),
+  type: z52.literal("next"),
   props: IonicButtonPropsSchema.optional(),
   logic: LogicArraySchema.optional()
 });
 var IonicPreviousButtonFieldSchema = BaseFieldDefSchema.extend({
-  type: z51.literal("previous"),
+  type: z52.literal("previous"),
   props: IonicButtonPropsSchema.optional()
 });
 var IonicAddArrayItemButtonFieldSchema = BaseFieldDefSchema.extend({
-  type: z51.literal("addArrayItem"),
-  arrayKey: z51.string().optional(),
+  type: z52.literal("addArrayItem"),
+  arrayKey: z52.string().optional(),
   props: IonicButtonPropsSchema.optional()
 });
 var IonicRemoveArrayItemButtonFieldSchema = BaseFieldDefSchema.extend({
-  type: z51.literal("removeArrayItem"),
-  arrayKey: z51.string().optional(),
+  type: z52.literal("removeArrayItem"),
+  arrayKey: z52.string().optional(),
   props: IonicButtonPropsSchema.optional()
 });
 
 // internal/dynamic-forms-zod/ionic/src/ionic-leaf-field.schema.ts
-import { z as z52 } from "zod";
-var IonicLeafFieldSchema = z52.discriminatedUnion("type", [
+import { z as z53 } from "zod";
+var IonicLeafFieldSchema = z53.discriminatedUnion("type", [
   TextFieldSchema,
   HiddenFieldSchema,
-  IonicInputFieldSchema,
+  IonicInputFieldSchemaObject,
   IonicCheckboxFieldSchema,
-  IonicRadioFieldSchema,
+  IonicRadioFieldSchemaObject,
   IonicToggleFieldSchema,
-  IonicSliderFieldSchema,
-  IonicDatepickerFieldSchema,
-  IonicSelectFieldSchema,
-  IonicTextareaFieldSchema,
-  IonicMultiCheckboxFieldSchema,
+  IonicSliderFieldSchemaObject,
+  IonicDatepickerFieldSchemaObject,
+  IonicSelectFieldSchemaObject,
+  IonicTextareaFieldSchemaObject,
+  IonicMultiCheckboxFieldSchemaObject,
   IonicButtonFieldSchema,
   IonicSubmitButtonFieldSchema,
   IonicNextButtonFieldSchema,
   IonicPreviousButtonFieldSchema,
   IonicAddArrayItemButtonFieldSchema,
   IonicRemoveArrayItemButtonFieldSchema
-]);
+]).superRefine(nullableValueRefine);
 
 // internal/dynamic-forms-zod/ionic/src/ionic-form-config.schema.ts
-import { z as z53 } from "zod";
+import { z as z54 } from "zod";
 var containerSchemas4 = createContainerSchemas({
   leafFieldSchema: IonicLeafFieldSchema
 });
@@ -5139,7 +5761,7 @@ var IonicRowFieldSchema = containerSchemas4.RowFieldSchema;
 var IonicGroupFieldSchema = containerSchemas4.GroupFieldSchema;
 var IonicArrayFieldSchema = containerSchemas4.ArrayFieldSchema;
 var IonicFieldSchema = containerSchemas4.AllFieldsSchema;
-var IonicFormDefaultPropsSchema = z53.object({
+var IonicFormDefaultPropsSchema = z54.object({
   color: IonicColorSchema.optional(),
   labelPlacement: IonicLabelPlacementSchema.optional()
 });
@@ -5870,6 +6492,110 @@ ${fieldTypes.map((ft) => `- ${ft}`).join("\n")}
   });
 }
 
+// packages/dynamic-form-mcp/src/resources/wrappers.resource.ts
+function registerWrappersResource(server) {
+  server.resource("ng-forge Wrappers", "ng-forge://wrappers", async () => {
+    const wrappers = getWrappers();
+    return {
+      contents: [
+        {
+          uri: "ng-forge://wrappers",
+          mimeType: "application/json",
+          text: JSON.stringify(
+            {
+              description: 'Available ng-forge field wrappers. Wrappers decorate the rendered output of a field or container without changing form data. Compose via `wrappers: [{ type: "...", ...props }]`.',
+              categories: {
+                core: "Ships from @ng-forge/dynamic-forms \u2014 always importable.",
+                demo: "Ships from @internal/examples-shared-ui for the docs sandbox \u2014 NOT a library primitive.",
+                adapter: "Ships from a UI adapter library (reserved)."
+              },
+              authoringContract: WRAPPER_AUTHORING_CONTRACT,
+              wrappers: wrappers.map((w) => ({
+                type: w.type,
+                category: w.category,
+                availability: w.availability,
+                package: w.package,
+                description: w.description,
+                autoAppliesTo: w.autoAppliesTo
+              }))
+            },
+            null,
+            2
+          )
+        }
+      ]
+    };
+  });
+  server.resource("Wrapper Details", "ng-forge://wrappers/{type}", async (uri) => {
+    const match = uri.href.match(/ng-forge:\/\/wrappers\/(.+)/);
+    const typeName = match?.[1];
+    if (!typeName) {
+      return {
+        contents: [
+          {
+            uri: uri.href,
+            mimeType: "text/plain",
+            text: "Wrapper type not specified in URI"
+          }
+        ]
+      };
+    }
+    const wrapper = getWrapper(typeName);
+    if (!wrapper) {
+      return {
+        contents: [
+          {
+            uri: uri.href,
+            mimeType: "text/plain",
+            text: `Wrapper type '${typeName}' not found. Available types: ${getWrappers().map((w) => w.type).join(", ")}`
+          }
+        ]
+      };
+    }
+    return {
+      contents: [
+        {
+          uri: uri.href,
+          mimeType: "application/json",
+          text: JSON.stringify(wrapper, null, 2)
+        }
+      ]
+    };
+  });
+  server.resource("Wrappers by Category", "ng-forge://wrappers/category/{category}", async (uri) => {
+    const match = uri.href.match(/ng-forge:\/\/wrappers\/category\/(.+)/);
+    const category = match?.[1];
+    if (!category || !["core", "demo", "adapter"].includes(category)) {
+      return {
+        contents: [
+          {
+            uri: uri.href,
+            mimeType: "text/plain",
+            text: "Valid categories: core, demo, adapter"
+          }
+        ]
+      };
+    }
+    const wrappers = getWrappersByCategory(category);
+    return {
+      contents: [
+        {
+          uri: uri.href,
+          mimeType: "application/json",
+          text: JSON.stringify(
+            {
+              category,
+              wrappers
+            },
+            null,
+            2
+          )
+        }
+      ]
+    };
+  });
+}
+
 // packages/dynamic-form-mcp/src/resources/index.ts
 function registerResources(server) {
   registerInstructionsResource(server);
@@ -5877,22 +6603,24 @@ function registerResources(server) {
   registerFieldTypesResource(server);
   registerValidatorsResource(server);
   registerUIAdaptersResource(server);
+  registerWrappersResource(server);
   registerDocumentationResource(server);
   registerSchemasResource(server);
 }
 
 // packages/dynamic-form-mcp/src/tools/lookup.tool.ts
-import { z as z54 } from "zod";
+import { z as z55 } from "zod";
 
 // packages/dynamic-form-mcp/src/tools/data/lookup-topics.ts
 var TOPICS = {
   // ========== FIELD TYPES ==========
   input: {
     brief: `\`\`\`typescript
-{ key: 'email', type: 'input', label: 'Email', required: true, email: true, props: { type: 'email', placeholder: 'you@example.com' } }
+{ key: 'email', type: 'input', label: 'Email', required: true, email: true, placeholder: 'you@example.com', props: { type: 'email' } }
 \`\`\`
 **Shorthand:** required, email, min, max, minLength, maxLength, pattern
-**Props:** type (text|email|password|number|tel|url), placeholder, appearance (Material)`,
+**Field-level:** placeholder
+**Props:** type (text|email|password|number|tel|url), appearance (Material)`,
     full: `# Input Field
 
 \`\`\`typescript
@@ -5902,9 +6630,9 @@ var TOPICS = {
   label: 'Email',
   required: true,
   email: true,
+  placeholder: 'you@example.com',
   props: {
     type: 'email',           // 'text' | 'email' | 'password' | 'number' | 'tel' | 'url'
-    placeholder: 'you@example.com',
     appearance: 'outline'    // Material: 'outline' | 'fill'
   }
 }
@@ -5912,7 +6640,8 @@ var TOPICS = {
 
 **Validation shorthand:** \`required\`, \`email\`, \`min\`, \`max\`, \`minLength\`, \`maxLength\`, \`pattern\`
 
-**Props:** \`type\`, \`placeholder\`, \`appearance\` (Material), \`hint\` (Material)
+**Field-level:** \`placeholder\`
+**Props:** \`type\`, \`appearance\` (Material), \`hint\` (Material)
 
 **Value Type:** \`string | number\`
 
@@ -5920,7 +6649,7 @@ var TOPICS = {
   },
   select: {
     brief: `\`\`\`typescript
-{ key: 'country', type: 'select', label: 'Country', options: [{ label: 'USA', value: 'us' }], props: { placeholder: 'Choose...' } }
+{ key: 'country', type: 'select', label: 'Country', placeholder: 'Choose...', options: [{ label: 'USA', value: 'us' }] }
 \`\`\`
 \u26A0\uFE0F **options at FIELD level, NOT in props!**`,
     full: `# Select Field
@@ -5935,8 +6664,8 @@ var TOPICS = {
     { label: 'USA', value: 'us' },
     { label: 'Canada', value: 'ca' }
   ],
+  placeholder: 'Choose...',
   props: {
-    placeholder: 'Choose...',
     multiple: false             // Allow multiple selection
   }
 }
@@ -6029,7 +6758,7 @@ For multiple selections, use **multi-checkbox** type.`,
   },
   textarea: {
     brief: `\`\`\`typescript
-{ key: 'bio', type: 'textarea', label: 'Bio', maxLength: 500, props: { rows: 4, placeholder: 'Tell us about yourself...' } }
+{ key: 'bio', type: 'textarea', label: 'Bio', maxLength: 500, placeholder: 'Tell us about yourself...', props: { rows: 4 } }
 \`\`\``,
     full: `# Textarea Field
 
@@ -6039,9 +6768,9 @@ For multiple selections, use **multi-checkbox** type.`,
   type: 'textarea',
   label: 'Biography',
   maxLength: 500,
+  placeholder: 'Tell us about yourself...',
   props: {
     rows: 4,
-    placeholder: 'Tell us about yourself...'
   }
 }
 \`\`\`
@@ -8304,7 +9033,13 @@ var TOPIC_DESCRIPTIONS = {
   conditions: "Condition operators and types for logic rules",
   "common-expressions": "Frequently used derivation expressions (age, math, concatenation)",
   "type-narrowing": "TypeScript type safety with as const satisfies FormConfig",
-  workflow: "Recommended tool usage guide \u2014 start here"
+  workflow: "Recommended tool usage guide \u2014 start here",
+  // Wrappers
+  wrappers: "Overview of the wrapper chain: how to apply, compose, and author wrappers",
+  wrapper: "Overview of the wrapper chain (alias of `wrappers`)",
+  css: "Built-in CSS wrapper \u2014 applies DynamicText class names to the host element",
+  arraySection: "Demo wrapper \u2014 array card whose header owns the Add button (examples-shared-ui)",
+  section: "Demo wrapper \u2014 titled card around any field or container (examples-shared-ui)"
 };
 var TOPIC_ALIASES = {
   // Field type aliases
@@ -8431,7 +9166,21 @@ var TOPIC_ALIASES = {
   // Workflow aliases
   "how-to": "workflow",
   guide: "workflow",
-  "getting-started": "workflow"
+  "getting-started": "workflow",
+  // Wrapper aliases
+  wrapper: "wrappers",
+  "field-wrapper": "wrappers",
+  "field-wrappers": "wrappers",
+  decorator: "wrappers",
+  decorators: "wrappers",
+  "wrapper-chain": "wrappers",
+  "css-wrapper": "css",
+  csswrapper: "css",
+  cssclasses: "css",
+  "array-section": "arraySection",
+  arraysection: "arraySection",
+  "section-wrapper": "section",
+  sectionwrapper: "section"
 };
 
 // packages/dynamic-form-mcp/src/services/topic-mapper.ts
@@ -8528,6 +9277,7 @@ function formatTopicItem(key) {
 function getTopicList() {
   const fieldTypes = ["input", "select", "slider", "radio", "checkbox", "textarea", "datepicker", "toggle", "text", "hidden"];
   const containers = ["group", "row", "array", "simplified-array", "page"];
+  const wrappers = ["wrappers", ...getWrappers().map((w) => w.type)];
   const concepts = [
     "validation",
     "validation-messages",
@@ -8563,6 +9313,9 @@ ${fieldTypes.map(formatTopicItem).join("\n")}
 ## Containers
 ${containers.map(formatTopicItem).join("\n")}
 
+## Wrappers
+${wrappers.map(formatTopicItem).join("\n")}
+
 ## Concepts
 ${concepts.map(formatTopicItem).join("\n")}
 
@@ -8629,7 +9382,144 @@ function formatFieldInfoFull(field, uiFieldType) {
   lines.push("```");
   return lines.join("\n");
 }
+function formatWrapperInfo(wrapper) {
+  const lines = [];
+  lines.push(`# ${wrapper.type} wrapper`);
+  lines.push("");
+  lines.push(`**Category:** ${wrapper.category}`);
+  lines.push(`**Availability:** ${wrapper.availability}`);
+  lines.push(`**Package:** \`${wrapper.package}\``);
+  lines.push(`**Component:** \`${wrapper.componentName}\``);
+  lines.push(`**Description:** ${wrapper.description}`);
+  if (wrapper.availability === "demo-only") {
+    lines.push("");
+    lines.push(
+      "> **Note:** This is a demo wrapper that ships with the docs sandbox, not a library primitive. Use it as a pattern/template and author your own wrapper (or copy the component out of `internal/examples-shared-ui/src/lib/demo-wrappers/`) when adopting the idea in production."
+    );
+  }
+  if (wrapper.autoAppliesTo.length > 0) {
+    lines.push("");
+    lines.push(`**Auto-applies to:** ${wrapper.autoAppliesTo.join(", ")}`);
+    lines.push(
+      "_(Injected automatically into these field types. Can be overridden via `FormConfig.defaultWrappers` or per-field `wrappers: [...]`; clear entirely with `wrappers: null`.)_"
+    );
+  } else {
+    lines.push("");
+    lines.push("**Auto-applies to:** _(none \u2014 opt-in via the field's `wrappers` array)_");
+  }
+  if (Object.keys(wrapper.props).length > 0) {
+    lines.push("");
+    lines.push("### Config Props");
+    for (const prop of Object.values(wrapper.props)) {
+      const req = prop.required ? " **(required)**" : "";
+      const def = prop.default !== void 0 ? ` (default: ${JSON.stringify(prop.default)})` : "";
+      lines.push(`- \`${prop.name}\`: ${prop.type}${req}${def} \u2014 ${prop.description}`);
+    }
+  } else {
+    lines.push("");
+    lines.push("### Config Props");
+    lines.push("_(none \u2014 no configurable inputs on this wrapper)_");
+  }
+  if (wrapper.minimalExample) {
+    lines.push("");
+    lines.push("### Minimal Config");
+    lines.push("```typescript");
+    lines.push(wrapper.minimalExample);
+    lines.push("```");
+  }
+  lines.push("");
+  lines.push("### Full Example");
+  lines.push("```typescript");
+  lines.push(wrapper.example);
+  lines.push("```");
+  lines.push("");
+  lines.push("### Authoring Contract");
+  lines.push(wrapper.contract);
+  return lines.join("\n");
+}
+function formatWrappersOverview() {
+  const wrappers = getWrappers();
+  const lines = [];
+  lines.push("# Wrappers");
+  lines.push("");
+  lines.push(
+    "Wrappers decorate the rendered output of a field (or container) without changing the form data structure. They are composed as a chain: each wrapper exposes a `#fieldComponent` `ViewContainerRef` slot where the next wrapper \u2014 or the field itself \u2014 is rendered."
+  );
+  lines.push("");
+  lines.push("## Applying a wrapper");
+  lines.push("");
+  lines.push("```typescript");
+  lines.push(`// Per-field wrapper chain (outer-most first)
+{
+  key: 'email',
+  type: 'input',
+  label: 'Email',
+  wrappers: [
+    { type: 'section', title: 'Account' }, // outer
+    { type: 'css', cssClasses: 'pad-lg' }   // inner
+  ]
+}
+
+// Form-level defaults applied to every field
+const config = {
+  defaultWrappers: [{ type: 'css', cssClasses: 'field-default' }],
+  fields: [...]
+} as const satisfies FormConfig;
+
+// Clear all wrappers on a specific field (overrides defaults + auto)
+{ key: 'id', type: 'hidden', value: 'abc', wrappers: null }`);
+  lines.push("```");
+  lines.push("");
+  lines.push("## Registered Wrappers");
+  lines.push("");
+  for (const w of wrappers) {
+    const flag = w.availability === "demo-only" ? " _(demo-only)_" : "";
+    lines.push(`- **${w.type}** (${w.category}, \`${w.package}\`)${flag} \u2014 ${w.description.split(".")[0]}.`);
+  }
+  lines.push("");
+  lines.push('Use `ngforge_lookup topic="<name>"` for full details on any individual wrapper.');
+  lines.push("");
+  lines.push("## Authoring Contract");
+  lines.push("");
+  lines.push(wrappers[0]?.contract ?? "");
+  return lines.join("\n");
+}
 async function resolveTopicContent(resolvedTopic, depth, uiIntegration) {
+  if (resolvedTopic === "wrappers" || resolvedTopic === "wrapper") {
+    if (depth === "brief") {
+      const wrappers = getWrappers();
+      return [
+        "**Wrappers** decorate a field's rendered output without changing form data.",
+        "",
+        "Registered:",
+        ...wrappers.map((w) => `- \`${w.type}\` (${w.category}${w.availability === "demo-only" ? ", demo-only" : ""})`),
+        "",
+        'Use `wrappers: [{ type: "css", cssClasses: "..." }]` on any field. See `ngforge_lookup topic="wrappers"` for the full overview.'
+      ].join("\n");
+    }
+    return formatWrappersOverview();
+  }
+  const wrapperInfo = getWrapper(resolvedTopic);
+  if (wrapperInfo) {
+    const formatted = formatWrapperInfo(wrapperInfo);
+    if (depth === "brief") {
+      const lines = [
+        `# ${wrapperInfo.type} wrapper`,
+        "",
+        `${wrapperInfo.description.split(".")[0]}.`,
+        "",
+        "```typescript",
+        wrapperInfo.minimalExample ?? `{ type: '${wrapperInfo.type}' }`,
+        "```"
+      ];
+      if (wrapperInfo.availability === "demo-only") {
+        lines.push("");
+        lines.push(`**Demo-only** \u2014 ships from \`${wrapperInfo.package}\`, not \`@ng-forge/dynamic-forms\`.`);
+      }
+      return lines.join("\n");
+    }
+    return formatted;
+  }
   if (depth === "brief") {
     const topicContent2 = TOPICS[resolvedTopic];
     if (topicContent2) {
@@ -8717,7 +9607,12 @@ var NEXT_STEPS = {
   "logic-matrix": '**Next:** `ngforge_lookup topic="conditional"` for condition syntax \xB7 `ngforge_lookup topic="derivation"` for derivation syntax',
   "field-placement": '**Next:** `ngforge_lookup topic="containers"` for container overview',
   conditions: '**Next:** `ngforge_lookup topic="conditional"` for full conditional logic docs \xB7 `ngforge_examples pattern="minimal-conditional"` for working example',
-  workflow: '**Next:** `ngforge_lookup topic="golden-path"` for form structure templates \xB7 `ngforge_examples pattern="complete"` for a full working example'
+  workflow: '**Next:** `ngforge_lookup topic="golden-path"` for form structure templates \xB7 `ngforge_examples pattern="complete"` for a full working example',
+  // Wrappers
+  wrappers: '**Next:** `ngforge_lookup topic="css"` for the shipping CSS wrapper \xB7 `ngforge_lookup topic="section"` or `ngforge_lookup topic="arraySection"` for demo wrappers \xB7 `ngforge_examples pattern="wrapper-array-actions"` for a working array-section example',
+  css: '**Next:** `ngforge_lookup topic="wrappers"` for the full wrapper overview \xB7 `ngforge_lookup topic="field-placement"` for where wrappers can apply',
+  arraySection: '**Next:** `ngforge_lookup topic="wrappers"` for the wrapper overview \xB7 `ngforge_lookup topic="array"` for array field docs \xB7 `ngforge_lookup topic="array-buttons"` for the button-field alternative',
+  section: '**Next:** `ngforge_lookup topic="wrappers"` for the wrapper overview \xB7 `ngforge_lookup topic="css"` for the shipping CSS wrapper'
 };
 function getNextSteps(topic) {
   return NEXT_STEPS[topic];
@@ -8738,6 +9633,8 @@ Field types: input, select, slider, radio, checkbox, textarea, datepicker, toggl
 
 Containers: group, row, array, simplified-array, page
 
+Wrappers: wrappers (overview), css (shipping), section, arraySection (demo-only)
+
 Concepts: validation, conditional, derivation, property-derivation, options-format, expression-variables, async-validators
 
 Patterns: field-placement, logic-matrix, context-api, containers, multi-page-gotchas
@@ -8745,11 +9642,11 @@ Patterns: field-placement, logic-matrix, context-api, containers, multi-page-got
 Use topic="list" to see all available topics with descriptions.
 Use ngforge_search query="your question" to find topics by keyword.`,
     {
-      topic: z54.string().describe(
-        'Topic to look up: field types (input, select, hidden, group, row, array, page), concepts (validation, conditional, derivation, property-derivation, options-format), patterns (golden-path, pitfalls, multi-page-gotchas), or "list" to see all topics'
+      topic: z55.string().describe(
+        'Topic to look up: field types (input, select, hidden, group, row, array, page), wrappers (wrappers, css, section, arraySection), concepts (validation, conditional, derivation, property-derivation, options-format), patterns (golden-path, pitfalls, multi-page-gotchas), or "list" to see all topics'
       ),
-      depth: z54.enum(["brief", "full", "schema"]).default("full").describe("brief=quick syntax (~20 lines), full=complete docs with examples, schema=include JSON schema"),
-      uiIntegration: z54.enum(UI_INTEGRATIONS2).optional().describe("Filter UI-specific info (only with depth=schema). material, bootstrap, primeng, ionic")
+      depth: z55.enum(["brief", "full", "schema"]).default("full").describe("brief=quick syntax (~20 lines), full=complete docs with examples, schema=include JSON schema"),
+      uiIntegration: z55.enum(UI_INTEGRATIONS2).optional().describe("Filter UI-specific info (only with depth=schema). material, bootstrap, primeng, ionic")
     },
     async ({ topic, depth, uiIntegration }) => {
       const normalizedTopic = topic.toLowerCase().trim();
@@ -8797,7 +9694,7 @@ ${nextSteps}`;
 }
 
 // packages/dynamic-form-mcp/src/tools/examples.tool.ts
-import { z as z55 } from "zod";
+import { z as z56 } from "zod";
 var PATTERNS = {
   // ========== MINIMAL PATTERNS (NEW) ==========
   "minimal-multipage": {
@@ -10780,7 +11677,7 @@ const megaFormConfig = {
         { key: 'pageHeader', type: 'text', label: 'All Field Types Demo', props: { elementType: 'h1' } },
 
         // TEXT INPUTS
-        { key: 'textInput', type: 'input', label: 'Text Input', props: { placeholder: 'Type here' } },
+        { key: 'textInput', type: 'input', label: 'Text Input', placeholder: 'Type here' },
         { key: 'emailInput', type: 'input', label: 'Email', email: true, props: { type: 'email' } },
         { key: 'passwordInput', type: 'input', label: 'Password', minLength: 8, props: { type: 'password' } },
         { key: 'numberInput', type: 'input', label: 'Number', min: 0, max: 100, props: { type: 'number' } },
@@ -11023,10 +11920,10 @@ Standard patterns: derivation, property-derivation, multi-page, conditional, val
 Use pattern="list" to see all available patterns.
 Use depth="minimal" for code-only output (no markdown).`,
     {
-      pattern: z55.string().optional().describe(
+      pattern: z56.string().optional().describe(
         'Pattern to get: minimal-multipage, minimal-array, minimal-simplified-array, minimal-conditional, minimal-validation, minimal-hidden, derivation, property-derivation, multi-page, conditional, validation, complete, mega. Use "list" to see all.'
       ),
-      depth: z55.enum(["minimal", "brief", "full", "explained"]).default("full").describe(
+      depth: z56.enum(["minimal", "brief", "full", "explained"]).default("full").describe(
         "minimal=code only (~20-50 lines), brief=code+summary, full=code+comments (default), explained=code+detailed explanation"
       )
     },
@@ -11103,7 +12000,7 @@ function extractCode(markdown) {
 }
 
 // packages/dynamic-form-mcp/src/tools/validate.tool.ts
-import { z as z56 } from "zod";
+import { z as z57 } from "zod";
 import { readFile } from "fs/promises";
 
 // packages/dynamic-form-mcp/src/utils/ast-extractor.ts
@@ -11717,10 +12614,10 @@ Example errors you'll see:
 - "options MUST be at FIELD level, NOT inside props"
 - "containers only support 'hidden' logic type"`,
     {
-      config: z56.union([z56.string(), z56.object({}).passthrough()]).describe(
+      config: z57.union([z57.string(), z57.object({}).passthrough()]).describe(
         "File path (.ts/.js) OR JSON string OR JSON object. Auto-detects: paths ending in .ts/.js or starting with / are treated as files."
       ),
-      uiIntegration: z56.enum(UI_INTEGRATIONS3).default("material").describe("UI library to validate against (material, bootstrap, primeng, ionic). Defaults to material.")
+      uiIntegration: z57.enum(UI_INTEGRATIONS3).default("material").describe("UI library to validate against (material, bootstrap, primeng, ionic). Defaults to material.")
     },
     async ({ config, uiIntegration }) => {
       try {
@@ -11826,7 +12723,7 @@ If validating JSON, ensure:
 }
 
 // packages/dynamic-form-mcp/src/tools/scaffold.tool.ts
-import { z as z57 } from "zod";
+import { z as z58 } from "zod";
 var UI_INTEGRATIONS4 = ["material", "bootstrap", "primeng", "ionic"];
 function parseFieldDefs(fields) {
   return fields.map((f) => {
@@ -12081,12 +12978,12 @@ Examples:
 - With groups: pages=0 groups=["address","billing"]
 - With hidden: hidden=["userId:abc123","source:web"]`,
     {
-      pages: z57.number().min(0).max(10).default(0).describe("Number of pages (0 = single-page form, 1-10 = multi-page wizard)"),
-      arrays: z57.array(z57.string()).optional().describe('Array field names for dynamic lists, e.g., ["contacts", "addresses"]'),
-      groups: z57.array(z57.string()).optional().describe('Group field names for nested objects, e.g., ["address", "billing"]'),
-      hidden: z57.array(z57.string()).optional().describe('Hidden fields as "name:value" pairs, e.g., ["userId:abc", "version:1"]'),
-      fields: z57.array(z57.string()).optional().describe('Basic fields as "name:type" pairs, e.g., ["email:input", "country:select", "age:slider"]'),
-      uiIntegration: z57.enum(UI_INTEGRATIONS4).default("material").describe("UI library (for future UI-specific props). Defaults to material.")
+      pages: z58.number().min(0).max(10).default(0).describe("Number of pages (0 = single-page form, 1-10 = multi-page wizard)"),
+      arrays: z58.array(z58.string()).optional().describe('Array field names for dynamic lists, e.g., ["contacts", "addresses"]'),
+      groups: z58.array(z58.string()).optional().describe('Group field names for nested objects, e.g., ["address", "billing"]'),
+      hidden: z58.array(z58.string()).optional().describe('Hidden fields as "name:value" pairs, e.g., ["userId:abc", "version:1"]'),
+      fields: z58.array(z58.string()).optional().describe('Basic fields as "name:type" pairs, e.g., ["email:input", "country:select", "age:slider"]'),
+      uiIntegration: z58.enum(UI_INTEGRATIONS4).default("material").describe("UI library (for future UI-specific props). Defaults to material.")
     },
     async ({ pages, arrays = [], groups = [], hidden = [], fields = [] }) => {
       const fieldDefs = parseFieldDefs(fields);
@@ -12128,7 +13025,7 @@ Examples:
 }
 
 // packages/dynamic-form-mcp/src/tools/search.tool.ts
-import { z as z58 } from "zod";
+import { z as z59 } from "zod";
 var searchIndex = null;
 function getTopicSubcategory(key) {
   const fieldTypes = ["input", "select", "slider", "radio", "checkbox", "textarea", "datepicker", "toggle", "text", "hidden"];
@@ -12183,6 +13080,18 @@ function buildIndex() {
       toolCall: `ngforge_examples pattern="${key}"`
     });
   }
+  for (const wrapper of getWrappers()) {
+    const subcategory = wrapper.availability === "demo-only" ? `Wrapper (demo, ${wrapper.category})` : `Wrapper (${wrapper.category})`;
+    entries.push({
+      id: wrapper.type,
+      category: "wrapper",
+      subcategory,
+      description: wrapper.description,
+      aliases: [],
+      content: `${wrapper.type} wrapper ${wrapper.description} ${wrapper.package}`.toLowerCase(),
+      toolCall: `ngforge_lookup topic="${wrapper.type}"`
+    });
+  }
   searchIndex = entries;
   return entries;
 }
@@ -12225,7 +13134,7 @@ Try broader terms or check available topics:
   const lines = ["# Search Results", ""];
   for (let i = 0; i < results.length; i++) {
     const { entry } = results[i];
-    const categoryLabel = entry.category === "topic" ? `Topic \xB7 ${entry.subcategory}` : `Example \xB7 ${entry.subcategory}`;
+    const categoryLabel = entry.category === "topic" ? `Topic \xB7 ${entry.subcategory}` : entry.category === "wrapper" ? entry.subcategory : `Example \xB7 ${entry.subcategory}`;
     lines.push(`${i + 1}. **${entry.id}** (${categoryLabel})`);
     lines.push(`   ${entry.description}`);
     lines.push(`   \u2192 \`${entry.toolCall}\``);
@@ -12252,7 +13161,7 @@ Use this when you don't know the exact topic name.
 
 New to ng-forge? Start with: ngforge_lookup topic="workflow"`,
     {
-      query: z58.string().describe("Natural language or keywords to search for")
+      query: z59.string().describe("Natural language or keywords to search for")
     },
     async ({ query }) => {
       const index = buildIndex();