@rafaelsilvadeveloper/zod-meta-form 1.0.2

package/README.md

@@ -0,0 +1,99 @@
+# @rafaelsilvadeveloper/zod-meta-form
+
+A framework-agnostic generator of Form UI metadata from Zod schemas, converting schemas into dynamic, client-ready forms.
+
+[![NPM Version](https://img.shields.io/npm/v/@rafaelsilvadeveloper/zod-meta-form.svg?style=flat-square)](https://www.npmjs.com/package/@rafaelsilvadeveloper/zod-meta-form)
+[![Discord Support](https://img.shields.io/discord/1111111111?color=7289da&label=Discord&logo=discord&style=flat-square)](https://discord.gg/7Fw7snafYS)
+[![Zero Dependencies](https://img.shields.io/badge/dependencies-zero-blueviolet.svg?style=flat-square)](https://www.npmjs.com/package/@rafaelsilvadeveloper/zod-meta-form)
+
+## Features
+
+*   🎯 **Framework Agnostic**: Outputs pure JSON-serializable UI form trees. Works with React, Vue, Svelte, Angular, or Vanilla JS.
+*   🔄 **Recursive Parsing**: Deeply inspects nested `ZodObject` and `ZodArray` schemas.
+*   🏷️ **Auto-Label Generation**: Automatically converts camelCase, snake_case, and kebab-case field names into clean, readable Title Case labels.
+*   🛠️ **Zod Constraint Mapping**: Translates string and number constraints (email, url, uuid, min, max, regex) into form validation rules.
+*   🎛️ **Supports Enums**: Converts Zod `enum` and `nativeEnum` options directly into dropdown options lists.
+
+## Installation
+
+```bash
+npm install @rafaelsilvadeveloper/zod-meta-form zod
+```
+
+## Usage
+
+```typescript
+import { z } from 'zod';
+import { zodToFormMeta } from '@rafaelsilvadeveloper/zod-meta-form';
+
+// 1. Define your Zod schema
+const signupSchema = z.object({
+  firstName: z.string().min(2).describe('Your first name'),
+  email: z.string().email(),
+  role: z.enum(['developer', 'designer', 'manager']).default('developer'),
+  subscribeToNewsletter: z.boolean().optional(),
+});
+
+// 2. Generate form UI metadata
+const formMeta = zodToFormMeta(signupSchema);
+
+console.log(JSON.stringify(formMeta, null, 2));
+```
+
+### Output Form Metadata Structure
+
+```json
+{
+  "type": "object",
+  "label": "",
+  "required": true,
+  "fields": {
+    "firstName": {
+      "type": "text",
+      "label": "First Name",
+      "required": true,
+      "description": "Your first name",
+      "validations": {
+        "min": { "value": 2 }
+      }
+    },
+    "email": {
+      "type": "email",
+      "label": "Email",
+      "required": true,
+      "validations": {
+        "email": true
+      }
+    },
+    "role": {
+      "type": "select",
+      "label": "Role",
+      "required": true,
+      "defaultValue": "developer",
+      "options": ["developer", "designer", "manager"]
+    },
+    "subscribeToNewsletter": {
+      "type": "checkbox",
+      "label": "Subscribe To Newsletter",
+      "required": false
+    }
+  }
+}
+```
+
+## API
+
+### `zodToFormMeta(schema: z.ZodTypeAny, fieldName?: string): FormMeta`
+Recursively generates form controls, type mappings, validation rules, default values, options, and descriptions from a Zod schema.
+
+### `toLabel(fieldName: string): string`
+Converts `camelCase`, `snake_case`, and `kebab-case` string patterns into standard capitalized labels.
+
+## Support
+
+For support, questions, or discussions, join our Discord server:
+
+[![Discord Server](https://img.shields.io/discord/1111111111?color=7289da&label=Discord&logo=discord&style=for-the-badge)](https://discord.gg/7Fw7snafYS)
+
+## License
+MIT

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { zodToFormMeta, toLabel } from './zodToFormMeta';
+export type * from './types';

package/dist/index.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toLabel = exports.zodToFormMeta = void 0;
+var zodToFormMeta_1 = require("./zodToFormMeta");
+Object.defineProperty(exports, "zodToFormMeta", { enumerable: true, get: function () { return zodToFormMeta_1.zodToFormMeta; } });
+Object.defineProperty(exports, "toLabel", { enumerable: true, get: function () { return zodToFormMeta_1.toLabel; } });

package/dist/types.d.ts

@@ -0,0 +1,24 @@
+export type FieldType = 'text' | 'email' | 'url' | 'number' | 'checkbox' | 'select' | 'date' | 'object' | 'array';
+export interface ValidationRule {
+    value: any;
+    message?: string;
+}
+export interface FieldMeta {
+    type: FieldType;
+    label: string;
+    required: boolean;
+    defaultValue?: any;
+    description?: string;
+    options?: string[];
+    validations?: {
+        min?: ValidationRule;
+        max?: ValidationRule;
+        email?: boolean;
+        url?: boolean;
+        uuid?: boolean;
+        regex?: ValidationRule;
+    };
+    fields?: Record<string, FieldMeta>;
+    element?: FieldMeta;
+}
+export type FormMeta = FieldMeta;

package/dist/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/zodToFormMeta.d.ts

@@ -0,0 +1,11 @@
+import { z } from 'zod';
+import type { FormMeta } from './types';
+export declare function toLabel(str: string): string;
+/**
+ * Recursively parses a Zod schema to produce a UI-friendly form metadata object.
+ *
+ * @param schema The Zod schema to inspect.
+ * @param fieldName The original name of the field (used to generate human-readable labels).
+ * @returns A structured metadata configuration for generating form fields.
+ */
+export declare function zodToFormMeta(schema: z.ZodTypeAny, fieldName?: string): FormMeta;

package/dist/zodToFormMeta.js

@@ -0,0 +1,136 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toLabel = toLabel;
+exports.zodToFormMeta = zodToFormMeta;
+function toLabel(str) {
+    if (!str)
+        return '';
+    const words = str
+        .replace(/([A-Z])/g, ' $1')
+        .replace(/[_-]+/g, ' ')
+        .trim()
+        .split(/\s+/);
+    return words.map((w) => w.charAt(0).toUpperCase() + w.slice(1).toLowerCase()).join(' ');
+}
+function unwrapZodType(schema) {
+    let current = schema;
+    let required = true;
+    let defaultValue = undefined;
+    const description = schema.description;
+    while (true) {
+        const typeName = current._def.typeName;
+        if (typeName === 'ZodOptional' || typeName === 'ZodNullable') {
+            required = false;
+            current = current.unwrap();
+        }
+        else if (typeName === 'ZodDefault') {
+            defaultValue = current._def.defaultValue();
+            current = current._def.innerType;
+        }
+        else if (typeName === 'ZodEffects') {
+            current = current.innerType();
+        }
+        else {
+            break;
+        }
+    }
+    return { unwrapped: current, required, defaultValue, description };
+}
+/**
+ * Recursively parses a Zod schema to produce a UI-friendly form metadata object.
+ *
+ * @param schema The Zod schema to inspect.
+ * @param fieldName The original name of the field (used to generate human-readable labels).
+ * @returns A structured metadata configuration for generating form fields.
+ */
+function zodToFormMeta(schema, fieldName = '') {
+    const { unwrapped, required, defaultValue, description } = unwrapZodType(schema);
+    const typeName = unwrapped._def.typeName;
+    const label = fieldName ? toLabel(fieldName) : '';
+    const meta = {
+        type: 'text',
+        label,
+        required,
+    };
+    if (defaultValue !== undefined) {
+        meta.defaultValue = defaultValue;
+    }
+    if (description !== undefined) {
+        meta.description = description;
+    }
+    if (typeName === 'ZodString') {
+        meta.type = 'text';
+        const checks = unwrapped._def.checks;
+        const validations = {};
+        for (const check of checks) {
+            if (check.kind === 'email') {
+                meta.type = 'email';
+                validations.email = true;
+            }
+            else if (check.kind === 'url') {
+                meta.type = 'url';
+                validations.url = true;
+            }
+            else if (check.kind === 'uuid') {
+                validations.uuid = true;
+            }
+            else if (check.kind === 'min') {
+                validations.min = { value: check.value, message: check.message };
+            }
+            else if (check.kind === 'max') {
+                validations.max = { value: check.value, message: check.message };
+            }
+            else if (check.kind === 'regex') {
+                validations.regex = { value: check.regex.source, message: check.message };
+            }
+        }
+        if (Object.keys(validations).length > 0) {
+            meta.validations = validations;
+        }
+    }
+    else if (typeName === 'ZodNumber') {
+        meta.type = 'number';
+        const checks = unwrapped._def.checks;
+        const validations = {};
+        for (const check of checks) {
+            if (check.kind === 'min') {
+                validations.min = { value: check.value, message: check.message };
+            }
+            else if (check.kind === 'max') {
+                validations.max = { value: check.value, message: check.message };
+            }
+        }
+        if (Object.keys(validations).length > 0) {
+            meta.validations = validations;
+        }
+    }
+    else if (typeName === 'ZodBoolean') {
+        meta.type = 'checkbox';
+    }
+    else if (typeName === 'ZodDate') {
+        meta.type = 'date';
+    }
+    else if (typeName === 'ZodEnum') {
+        meta.type = 'select';
+        meta.options = unwrapped._def.values;
+    }
+    else if (typeName === 'ZodNativeEnum') {
+        meta.type = 'select';
+        const enumObj = unwrapped._def.values;
+        meta.options = Object.values(enumObj).filter((v) => typeof v === 'string');
+    }
+    else if (typeName === 'ZodObject') {
+        meta.type = 'object';
+        const shape = unwrapped.shape;
+        const fields = {};
+        for (const key of Object.keys(shape)) {
+            fields[key] = zodToFormMeta(shape[key], key);
+        }
+        meta.fields = fields;
+    }
+    else if (typeName === 'ZodArray') {
+        meta.type = 'array';
+        meta.element = zodToFormMeta(unwrapped.element, '');
+    }
+    return meta;
+}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@rafaelsilvadeveloper/zod-meta-form",
+  "version": "1.0.2",
+  "description": "A framework-agnostic generator of Form UI metadata from Zod schemas, converting schemas into client-ready forms.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rafael-packages/zod-meta-form.git"
+  },
+  "bugs": {
+    "url": "https://github.com/rafael-packages/zod-meta-form/issues"
+  },
+  "homepage": "https://github.com/rafael-packages/zod-meta-form#readme",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "scripts": {
+    "build": "tsc",
+    "test": "bun test",
+    "prepare": "bun run build",
+    "lint": "eslint src/**/*.ts",
+    "format": "prettier --write src/**/*.ts tests/**/*.ts"
+  },
+  "keywords": [
+    "zod",
+    "form",
+    "metadata",
+    "form-generator",
+    "typescript",
+    "schema",
+    "validation"
+  ],
+  "author": "realkalashnikov",
+  "license": "MIT",
+  "peerDependencies": {
+    "typescript": "^5.0.0",
+    "zod": "^3.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.9.1",
+    "@typescript-eslint/eslint-plugin": "^7.18.0",
+    "@typescript-eslint/parser": "^7.18.0",
+    "eslint": "^8.57.0",
+    "prettier": "^3.3.3",
+    "zod": "^3.23.8"
+  }
+}