@uniform-ts/core 0.0.1 → 0.0.3

package/README.md

@@ -14,7 +14,7 @@ UniForm takes a Zod schema and automatically renders a fully customizable form.
 - **Per-field `onChange` in `fields` prop** — react to individual field changes inline, with typed values and full form control methods
 - **Per-field custom components** — pass any `React.ComponentType<FieldProps>` directly as `meta.component` (inline, no registry) or register under a custom string key; direct components bypass the registry _and_ the default `ArrayField`/`ObjectField` routing, allowing fully custom multi-value widgets for `array`-typed fields
 - **Layout hooks** — `classNames`, `fieldWrapper`, `layout.formWrapper`, `layout.sectionWrapper`, `layout.submitButton`
-- **Section grouping** — group fields into named sections via `meta.section`
+- **Section grouping** — group fields into named sections via `meta.section`; style or swap individual section wrappers via `layout.sections`
 - **Conditional fields** — show/hide fields based on form values with `meta.condition`; hidden fields automatically reset to their default value
 - **Field ordering** — control render order with `meta.order`
 - **`createAutoForm()` factory** — bake in your design system defaults once, use everywhere
@@ -178,7 +178,7 @@ const MyAutoForm = createAutoForm({
 | -------------- | ---------------------------------------- | ------------------------------------------------ |
 | `components`   | `ComponentRegistry`                      | Deep merge (instance overrides specific keys)    |
 | `fieldWrapper` | `React.ComponentType<FieldWrapperProps>` | Instance replaces factory                        |
-| `layout`       | `LayoutSlots`                            | Shallow merge                                    |
+| `layout`       | `LayoutSlots`                            | Shallow merge (except `sections` — deep-merged)  |
 | `classNames`   | `FormClassNames`                         | Shallow merge                                    |
 | `disabled`     | `boolean`                                | OR logic (either `true` → disabled)              |
 | `coercions`    | `CoercionMap`                            | Shallow merge                                    |
@@ -307,11 +307,29 @@ type LayoutSlots = {
   sectionWrapper?: React.ComponentType<{
     children: React.ReactNode
     title: string
+    className?: string
   }>
   submitButton?: React.ComponentType<{ isSubmitting: boolean }>
   arrayRowLayout?: React.ComponentType<ArrayRowLayoutProps>
   /** Shown while async `defaultValues` are resolving. Default: `<p>Loading…</p>` */
   loadingFallback?: React.ReactNode
+  /** Per-section styling / component overrides keyed by section title. */
+  sections?: Record<string, SectionConfig>
+}
+```
+
+#### `SectionConfig`
+
+```ts
+type SectionConfig = {
+  /** CSS class name forwarded to the section wrapper. */
+  className?: string
+  /** Replace the section wrapper component for this section only. */
+  component?: React.ComponentType<{
+    children: React.ReactNode
+    title: string
+    className?: string
+  }>
 }
 ```
 
@@ -468,7 +486,26 @@ const schema = z.object({
 
 Zod still validates the array (`.min(1)` etc.) — only the _render_ is taken over by your component.
 
-#### Option 2 — Named key in the registry
+#### Option 2 — String field as select
+
+A `z.string()` field can be rendered as a select by setting `meta.component: 'select'` together with `meta.options`. UniForm treats it as type `"select"` during introspection:
+
+```ts
+const schema = z.object({
+  role: z.string().meta({
+    component: 'select',
+    options: [
+      { label: 'User', value: 'user' },
+      { label: 'Admin', value: 'admin' },
+      { label: 'Editor', value: 'editor' },
+    ],
+  }),
+})
+```
+
+This is an alternative to `z.enum(...)` — useful when the option list is dynamic or when you need a plain `string` output type rather than a union literal.
+
+#### Option 3 — Named key in the registry
 
 Register a component under a custom string key — either in `createAutoForm` or the `components` prop — then reference it with `meta.component: 'yourKey'`:
 
@@ -614,8 +651,8 @@ The `span` value is set as `--field-span` CSS custom property on each field wrap
     city: { section: 'Address', order: 4 },
   }}
   layout={{
-    sectionWrapper: ({ children, title }) => (
-      <fieldset>
+    sectionWrapper: ({ children, title, className }) => (
+      <fieldset className={className}>
         <legend>{title}</legend>
         {children}
       </fieldset>
@@ -624,6 +661,23 @@ The `span` value is set as `--field-span` CSS custom property on each field wrap
 />
 ```
 
+Use `layout.sections` to style or swap the wrapper for individual sections:
+
+```tsx
+<AutoForm
+  form={myForm}
+  onSubmit={handleSubmit}
+  layout={{
+    sections: {
+      Personal: { className: 'bg-blue-50 p-4 rounded' },
+      Address: { component: AddressCard }, // completely different component
+    },
+  }}
+/>
+```
+
+`className` is forwarded as a prop to the active wrapper (global `sectionWrapper` or the per-section `component`). Factory-level and instance-level `sections` are merged — instance wins on conflicts.
+
 ### Conditional Fields
 
 Show a field only when another field has a specific value. Conditional fields are fully lifecycle-managed:

package/dist/index.d.mts

@@ -181,6 +181,26 @@ type FieldConfigBase = {
     required: boolean;
     /** Merged UI metadata for the field. */
     meta: FieldMeta;
+    /**
+     * The original Zod schema for this field, after transparent wrappers
+     * (`optional`, `nullable`, `default`, `pipe`) have been stripped.
+     *
+     * This is a general escape hatch for custom components that need to inspect
+     * the raw schema — for example, to read union variants, access custom Zod
+     * metadata not captured by introspection, or build schema-aware validation UI.
+     *
+     * @example
+     * function MyUnionInput({ field }: FieldProps) {
+     *   // Inspect the original schema for any edge case
+     *   const schema = field.schema
+     *   if (schema._zod.def.type === 'union') {
+     *     const variants = (schema._zod.def as z.$ZodUnionDef).options
+     *     // render a type-switcher using the raw Zod variants
+     *   }
+     *   return <input ... />
+     * }
+     */
+    schema: z.$ZodType;
 };
 /**
  * The fully resolved configuration for a single form field, produced by
@@ -256,6 +276,12 @@ type FieldProps = {
     options?: SelectOption[];
     /** Full field metadata, including any custom keys. */
     meta: FieldMeta;
+    /**
+     * The original Zod schema for this field (after transparent wrappers are stripped).
+     * Use this as an escape hatch when you need capabilities beyond what `FieldConfig`
+     * exposes — e.g. inspecting union variants, accessing custom Zod refinements, etc.
+     */
+    schema: z.$ZodType;
 };
 /**
  * A map of field type keys to React components used to render them.
@@ -321,6 +347,20 @@ type ArrayRowLayoutProps = {
     /** Total number of rows currently in the array. */
     rowCount: number;
 };
+/**
+ * Per-section styling overrides forwarded to the `sectionWrapper` component.
+ * Keys are section titles; values control how that section wrapper is styled.
+ */
+type SectionConfig = {
+    /** CSS class name(s) applied to the section wrapper. */
+    className?: string;
+    /** Replaces the section wrapper component entirely for this section. */
+    component?: React.ComponentType<{
+        children: React.ReactNode;
+        title: string;
+        className?: string;
+    }>;
+};
 /**
  * Optional layout slot overrides for top-level structural components of the
  * form. Provide only the slots you want to replace; omitted slots fall back
@@ -335,6 +375,7 @@ type LayoutSlots = {
     sectionWrapper?: React.ComponentType<{
         children: React.ReactNode;
         title: string;
+        className?: string;
     }>;
     /** Custom submit button component. */
     submitButton?: React.ComponentType<{
@@ -348,6 +389,11 @@ type LayoutSlots = {
      * Defaults to a simple `<p>Loading…</p>` when not provided.
      */
     loadingFallback?: React.ReactNode;
+    /**
+     * Per-section config keyed by section title.
+     * Forwarded to the `sectionWrapper` component as a `className` prop.
+     */
+    sections?: Record<string, SectionConfig>;
 };
 /**
  * The resolved version of `LayoutSlots` used internally, where all slots are
@@ -360,6 +406,7 @@ type ResolvedLayoutSlots = {
     sectionWrapper: React.ComponentType<{
         children: React.ReactNode;
         title: string;
+        className?: string;
     }>;
     submitButton: React.ComponentType<{
         isSubmitting: boolean;

package/dist/index.d.ts

@@ -181,6 +181,26 @@ type FieldConfigBase = {
     required: boolean;
     /** Merged UI metadata for the field. */
     meta: FieldMeta;
+    /**
+     * The original Zod schema for this field, after transparent wrappers
+     * (`optional`, `nullable`, `default`, `pipe`) have been stripped.
+     *
+     * This is a general escape hatch for custom components that need to inspect
+     * the raw schema — for example, to read union variants, access custom Zod
+     * metadata not captured by introspection, or build schema-aware validation UI.
+     *
+     * @example
+     * function MyUnionInput({ field }: FieldProps) {
+     *   // Inspect the original schema for any edge case
+     *   const schema = field.schema
+     *   if (schema._zod.def.type === 'union') {
+     *     const variants = (schema._zod.def as z.$ZodUnionDef).options
+     *     // render a type-switcher using the raw Zod variants
+     *   }
+     *   return <input ... />
+     * }
+     */
+    schema: z.$ZodType;
 };
 /**
  * The fully resolved configuration for a single form field, produced by
@@ -256,6 +276,12 @@ type FieldProps = {
     options?: SelectOption[];
     /** Full field metadata, including any custom keys. */
     meta: FieldMeta;
+    /**
+     * The original Zod schema for this field (after transparent wrappers are stripped).
+     * Use this as an escape hatch when you need capabilities beyond what `FieldConfig`
+     * exposes — e.g. inspecting union variants, accessing custom Zod refinements, etc.
+     */
+    schema: z.$ZodType;
 };
 /**
  * A map of field type keys to React components used to render them.
@@ -321,6 +347,20 @@ type ArrayRowLayoutProps = {
     /** Total number of rows currently in the array. */
     rowCount: number;
 };
+/**
+ * Per-section styling overrides forwarded to the `sectionWrapper` component.
+ * Keys are section titles; values control how that section wrapper is styled.
+ */
+type SectionConfig = {
+    /** CSS class name(s) applied to the section wrapper. */
+    className?: string;
+    /** Replaces the section wrapper component entirely for this section. */
+    component?: React.ComponentType<{
+        children: React.ReactNode;
+        title: string;
+        className?: string;
+    }>;
+};
 /**
  * Optional layout slot overrides for top-level structural components of the
  * form. Provide only the slots you want to replace; omitted slots fall back
@@ -335,6 +375,7 @@ type LayoutSlots = {
     sectionWrapper?: React.ComponentType<{
         children: React.ReactNode;
         title: string;
+        className?: string;
     }>;
     /** Custom submit button component. */
     submitButton?: React.ComponentType<{
@@ -348,6 +389,11 @@ type LayoutSlots = {
      * Defaults to a simple `<p>Loading…</p>` when not provided.
      */
     loadingFallback?: React.ReactNode;
+    /**
+     * Per-section config keyed by section title.
+     * Forwarded to the `sectionWrapper` component as a `className` prop.
+     */
+    sections?: Record<string, SectionConfig>;
 };
 /**
  * The resolved version of `LayoutSlots` used internally, where all slots are
@@ -360,6 +406,7 @@ type ResolvedLayoutSlots = {
     sectionWrapper: React.ComponentType<{
         children: React.ReactNode;
         title: string;
+        className?: string;
     }>;
     submitButton: React.ComponentType<{
         isSubmitting: boolean;

package/dist/index.js

@@ -83,25 +83,30 @@ function introspectSchema(schema, name = "", parentPath = "") {
   let maxItems;
   try {
     if (kind === "string") {
-      type = "string";
-      const defFormat = def.format;
-      if (defFormat === "email") {
-        mergedMeta["inputType"] = "email";
-      } else if (defFormat === "url") {
-        mergedMeta["inputType"] = "url";
-      } else if (defFormat === "uuid") {
-        mergedMeta["inputType"] = "uuid";
+      if (mergedMeta.component === "select" && Array.isArray(mergedMeta.options) && mergedMeta.options.length > 0) {
+        type = "select";
+        options = mergedMeta.options;
       } else {
-        const checks = def.checks ?? [];
-        const hasFormat = (fmt) => checks.some(
-          (c) => c._zod.def.check === "string_format" && c._zod.def.format === fmt
-        );
-        if (hasFormat("email")) {
+        type = "string";
+        const defFormat = def.format;
+        if (defFormat === "email") {
           mergedMeta["inputType"] = "email";
-        } else if (hasFormat("url")) {
+        } else if (defFormat === "url") {
           mergedMeta["inputType"] = "url";
-        } else if (hasFormat("uuid")) {
+        } else if (defFormat === "uuid") {
           mergedMeta["inputType"] = "uuid";
+        } else {
+          const checks = def.checks ?? [];
+          const hasFormat = (fmt) => checks.some(
+            (c) => c._zod.def.check === "string_format" && c._zod.def.format === fmt
+          );
+          if (hasFormat("email")) {
+            mergedMeta["inputType"] = "email";
+          } else if (hasFormat("url")) {
+            mergedMeta["inputType"] = "url";
+          } else if (hasFormat("uuid")) {
+            mergedMeta["inputType"] = "uuid";
+          }
         }
       }
     } else if (kind === "number") {
@@ -138,15 +143,24 @@ function introspectSchema(schema, name = "", parentPath = "") {
         }
       }
     } else if (def.type === "union") {
-      type = "union";
       const unionDef = def;
+      const variants = unionDef.options;
       if ("discriminator" in unionDef) {
+        type = "union";
         discriminatorKey = unionDef.discriminator;
+        unionVariants = variants.map(
+          (variant, i) => introspectSchema(variant, String(i), path)
+        );
+      } else {
+        const collapsed = introspectSchema(variants[0], name, parentPath);
+        return {
+          ...collapsed,
+          name: path,
+          label,
+          meta: { ...collapsed.meta, ...mergedMeta },
+          schema: inner
+        };
       }
-      const variants = unionDef.options;
-      unionVariants = variants.map(
-        (variant, i) => introspectSchema(variant, String(i), path)
-      );
     }
   } catch {
     type = "unknown";
@@ -157,6 +171,7 @@ function introspectSchema(schema, name = "", parentPath = "") {
     label,
     required,
     meta: mergedMeta,
+    schema: inner,
     ...options !== void 0 && { options },
     ...children !== void 0 && { children },
     ...itemConfig !== void 0 && { itemConfig },
@@ -195,6 +210,7 @@ function parseDiscriminatedUnionMeta(schema) {
     label: deriveLabel(discriminatorKey),
     required: true,
     meta: {},
+    schema,
     options: discriminatorOptions
   };
   return {
@@ -382,9 +398,10 @@ function DefaultFormWrapper({ children }) {
 }
 function DefaultSectionWrapper({
   children,
-  title
+  title,
+  className
 }) {
-  return /* @__PURE__ */ jsxRuntime.jsxs("fieldset", { children: [
+  return /* @__PURE__ */ jsxRuntime.jsxs("fieldset", { className, children: [
     /* @__PURE__ */ jsxRuntime.jsx("legend", { children: title }),
     children
   ] });
@@ -495,7 +512,7 @@ function ScalarField({
           onChange: (value) => {
             const coerced = coerceValue(field.type, value, coercions);
             rhfField.onChange(coerced);
-            field.meta.onChange?.(coerced, formMethods);
+            void field.meta.onChange?.(coerced, formMethods);
           },
           onBlur: rhfField.onBlur,
           ref: rhfField.ref,
@@ -505,7 +522,9 @@ function ScalarField({
           error: fieldState.error?.message,
           required: field.required,
           disabled: field.meta.disabled || contextDisabled,
-          meta: field.meta
+          options: field.meta.options,
+          meta: field.meta,
+          schema: field.schema
         }
       )
     }
@@ -537,7 +556,7 @@ function BooleanField({
           value: rhfField.value ?? false,
           onChange: (value) => {
             rhfField.onChange(value);
-            field.meta.onChange?.(value, formMethods);
+            void field.meta.onChange?.(value, formMethods);
           },
           onBlur: rhfField.onBlur,
           ref: rhfField.ref,
@@ -547,7 +566,8 @@ function BooleanField({
           error: fieldState.error?.message,
           required: field.required,
           disabled: field.meta.disabled || rhfField.disabled || contextDisabled,
-          meta: field.meta
+          meta: field.meta,
+          schema: field.schema
         }
       )
     }
@@ -579,7 +599,7 @@ function SelectField({
           value: rhfField.value ?? "",
           onChange: (value) => {
             rhfField.onChange(value);
-            field.meta.onChange?.(value, formMethods);
+            void field.meta.onChange?.(value, formMethods);
           },
           onBlur: rhfField.onBlur,
           ref: rhfField.ref,
@@ -590,7 +610,8 @@ function SelectField({
           required: field.required,
           disabled: field.meta.disabled || contextDisabled,
           options: field.options,
-          meta: field.meta
+          meta: field.meta,
+          schema: field.schema
         }
       )
     }
@@ -1505,7 +1526,17 @@ function AutoForm(props) {
           if (section.title === null) {
             return /* @__PURE__ */ jsxRuntime.jsx(React3__namespace.Fragment, { children: renderedFields }, "__ungrouped");
           }
-          return /* @__PURE__ */ jsxRuntime.jsx(SectionWrapper, { title: section.title, children: renderedFields }, section.title);
+          const sectionConfig = layout?.sections?.[section.title];
+          const PerSectionWrapper = sectionConfig?.component ?? SectionWrapper;
+          return /* @__PURE__ */ jsxRuntime.jsx(
+            PerSectionWrapper,
+            {
+              title: section.title,
+              className: sectionConfig?.className,
+              children: renderedFields
+            },
+            section.title
+          );
         }),
         /* @__PURE__ */ jsxRuntime.jsx(
           SubmitButton,
@@ -1525,7 +1556,11 @@ function createAutoForm(config) {
       [props.components]
     );
     const mergedLayout = React3__namespace.useMemo(
-      () => ({ ...config.layout, ...props.layout }),
+      () => ({
+        ...config.layout,
+        ...props.layout,
+        sections: config.layout?.sections || props.layout?.sections ? { ...config.layout?.sections, ...props.layout?.sections } : void 0
+      }),
       [props.layout]
     );
     const mergedClassNames = React3__namespace.useMemo(