@dynamic-field-kit/core 1.0.0 → 1.0.3

package/README.md

@@ -0,0 +1,299 @@
+# Dynamic Field Kit
+
+A lightweight, extensible **dynamic form engine** for React, built for scalable applications and design systems.
+
+`dynamic-field-kit` lets you define forms using **configuration objects** instead of hard-coded UI, and allows applications to **freely extend field types** (`text`, `number`, `checkbox`, `select`, `date`, `custom`, …) without modifying the library.
+
+---
+
+## ✨ Features
+
+- Schema-driven dynamic forms
+- Extensible field types (no enums, no hard-coded unions)
+- Pluggable field renderers via registry
+- Runtime conditional fields (`appearCondition`)
+- Clean TypeScript declarations (DTS-safe)
+- Core logic separated from React rendering
+- Ideal for form builders & design systems
+
+---
+
+## 📦 Packages
+
+| Package | Description |
+|------|------------|
+| `@dynamic-field-kit/core` | Core types and field registry |
+| `@dynamic-field-kit/react` | React components (FieldInput, MultiFieldInput, DynamicInput) |
+
+---
+
+## 📥 Installation
+
+```bash
+npm install @dynamic-field-kit/core @dynamic-field-kit/react
+```
+
+**Peer dependency**
+
+```txt
+react >= 17
+```
+
+---
+
+## 🧱 Core Concepts
+
+The library **does NOT define field types** like:
+```ts
+"text" | "number"
+```
+
+Instead, it exposes an **extendable interface** that applications can augment:
+```ts
+export interface FieldTypeMap {}
+```
+
+This allows:
+- Unlimited custom field types
+- Strong typing without locking consumers
+- No need to rebuild the library
+
+This pattern is used by mature libraries like **MUI, React Hook Form,** and **Redux Toolkit**.
+
+## 🧩 Defining Field Types (App Side)
+
+Create a `.d.ts` file in your app (e.g. src/types/dynamic-field.d.ts):
+
+```ts
+import "@dynamic-field-kit/core"
+
+declare module "@dynamic-field-kit/core" {
+  interface FieldTypeMap {
+    text: string
+    number: number
+    checkbox: boolean
+    select: string
+  }
+}
+```
+⚠️ Make sure this file is included in tsconfig.json.
+
+---
+
+## FieldRendererProps
+
+```ts
+export interface FieldRendererProps<T = any> {
+  value?: T
+  onValueChange?: (value: T) => void
+  label?: string
+}
+```
+👉 A common contract for all field renderers
+
+---
+
+### FieldDescription
+
+A `FieldDescription` defines **what a field is**, not **how it looks**.
+
+```ts
+import { FieldDescription } from "@dynamic-field-kit/core"
+
+const fields: FieldDescription[] = [
+  {
+    name: "username",
+    type: "text",
+    label: "Username"
+  },
+  {
+    name: "age",
+    type: "number",
+    label: "Age",
+    appearCondition: (data) => data.username !== ""
+  }
+]
+```
+
+**Common Properties**
+| Property	| Description |
+|------|------------|
+| name	| Field key in form data |
+| type	| Field renderer key |
+| label	| UI label |
+| value	| Default value |
+| appearCondition	| Runtime visibility condition |
+
+**Field Registry (Render Layer)**
+The library does **not** ship UI components.
+
+Instead, applications register their own renderers.
+
+```ts
+import { fieldRegistry } from "@dynamic-field-kit/core"
+
+fieldRegistry.register("text", ({ value, onValueChange, label }) => (
+  <div>
+    <label>{label}</label>
+    <input
+      value={value ?? ""}
+      onChange={(e) => onValueChange?.(e.target.value)}
+    />
+  </div>
+))
+
+fieldRegistry.register("checkbox", ({ value, onValueChange, label }) => (
+  <label>
+    <input
+      type="checkbox"
+      checked={!!value}
+      onChange={(e) => onValueChange?.(e.target.checked)}
+    />
+    {label}
+  </label>
+))
+
+```
+
+---
+
+## ⚛️ React Usage
+
+**MultiFieldInput (Main Form Engine)**
+
+```tsx
+import { MultiFieldInput } from "@dynamic-field-kit/react"
+import { FieldDescription } from "@dynamic-field-kit/core"
+
+const fields: FieldDescription[] = [
+  { name: "email", type: "text", label: "Email" },
+  { name: "age", type: "number", label: "Age" }
+]
+
+const Example = () => {
+  return (
+    <MultiFieldInput
+      fieldDescriptions={fields}
+      onChange={(data) => {
+        console.log("Form data:", data)
+      }}
+    />
+  )
+}
+```
+
+**Controlled Form**
+```tsx
+const [formData, setFormData] = useState({})
+
+<MultiFieldInput
+  fieldDescriptions={fields}
+  properties={formData}
+  onChange={setFormData}
+/>
+```
+
+---
+
+## ➕ Adding a New Field Type
+
+You **do not** need to modify the library.
+
+Just extend `FieldTypeMap`:
+
+```ts
+declare module "@dynamic-field-kit/react" {
+  interface FieldTypeMap {
+    date: Date
+  }
+}
+```
+
+Then register a renderer:
+
+```ts
+fieldRegistry.register("date", ({ value, onValueChange }) => (
+  <input
+    type="date"
+    value={value ? value.toISOString().slice(0, 10) : ""}
+    onChange={(e) =>
+      onValueChange?.(new Date(e.target.value))
+    }
+  />
+))
+```
+
+Now `"date"` is fully type-safe everywhere.
+
+---
+## 🧠 Domain Typing (Optional)
+The library intentionally avoids enforcing domain types.
+If you want strict typing, cast inside your app:
+
+```ts
+interface UserForm {
+  age: number
+}
+
+const fields: FieldDescription[] = [
+  {
+    name: "age",
+    type: "number",
+    appearCondition: (data) =>
+      (data as UserForm).age > 18
+  }
+]
+```
+This keeps the library generic while allowing strict typing in the app.
+
+---
+
+## 🧩 Components API
+
+**<DynamicInput />**
+
+Resolves and renders a field based on its type.
+
+```tsx
+<DynamicInput type="text" value="hello" />
+```
+---
+
+**<FieldInput />**
+
+Renders a single field with value binding.
+
+```tsx
+<FieldInput
+  fieldDescription={field}
+  renderInfos={formData}
+  onChange={(value, key) => {}}
+/>
+```
+
+## Demo
+- [Examples](https://github.com/vannt-dev/dynamic-field-kit-demo)
+
+---
+
+## 🏗 Architecture
+
+```
+dynamic-field-kit
+├─ packages/
+│  ├─ core    # framework-agnostic types
+│  └─ react   # React renderer + registry
+```
+
+---
+
+## 🚫 Non-Goals
+This library intentionally does not include:
+-Built-in UI components
+-Built-in UI components
+-Form state management library
+
+It is a **form engine**, not a full form framework.
+
+## 📄 License
+MIT © vannt-dev

package/dist/index.d.mts

@@ -16,12 +16,12 @@ interface FieldDescription<T extends FieldTypeKey = FieldTypeKey> {
     appearCondition?: (data: Properties) => boolean;
 }
 
-type Renderer = (props: FieldRendererProps<any>) => JSX.Element;
+type FieldRenderer<T = any> = (props: FieldRendererProps<T>) => JSX.Element;
 declare class FieldRegistry {
-    private map;
-    register<T extends FieldTypeKey>(type: T, renderer: (props: FieldRendererProps) => JSX.Element): void;
-    get(type: FieldTypeKey): Renderer | undefined;
+    private registry;
+    register<K extends keyof FieldTypeMap>(type: K, renderer: FieldRenderer<FieldTypeMap[K]>): void;
+    get<K extends keyof FieldTypeMap>(type: K): FieldRenderer<FieldTypeMap[K]> | undefined;
 }
 declare const fieldRegistry: FieldRegistry;
 
-export { type FieldDescription, type FieldRendererProps, type FieldTypeKey, type FieldTypeMap, type Properties, fieldRegistry };
+export { type FieldDescription, FieldRegistry, type FieldRenderer, type FieldRendererProps, type FieldTypeKey, type FieldTypeMap, type Properties, fieldRegistry };

package/dist/index.d.ts

@@ -16,12 +16,12 @@ interface FieldDescription<T extends FieldTypeKey = FieldTypeKey> {
     appearCondition?: (data: Properties) => boolean;
 }
 
-type Renderer = (props: FieldRendererProps<any>) => JSX.Element;
+type FieldRenderer<T = any> = (props: FieldRendererProps<T>) => JSX.Element;
 declare class FieldRegistry {
-    private map;
-    register<T extends FieldTypeKey>(type: T, renderer: (props: FieldRendererProps) => JSX.Element): void;
-    get(type: FieldTypeKey): Renderer | undefined;
+    private registry;
+    register<K extends keyof FieldTypeMap>(type: K, renderer: FieldRenderer<FieldTypeMap[K]>): void;
+    get<K extends keyof FieldTypeMap>(type: K): FieldRenderer<FieldTypeMap[K]> | undefined;
 }
 declare const fieldRegistry: FieldRegistry;
 
-export { type FieldDescription, type FieldRendererProps, type FieldTypeKey, type FieldTypeMap, type Properties, fieldRegistry };
+export { type FieldDescription, FieldRegistry, type FieldRenderer, type FieldRendererProps, type FieldTypeKey, type FieldTypeMap, type Properties, fieldRegistry };

package/dist/index.js

@@ -20,6 +20,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  FieldRegistry: () => FieldRegistry,
   fieldRegistry: () => fieldRegistry
 });
 module.exports = __toCommonJS(index_exports);
@@ -27,18 +28,21 @@ module.exports = __toCommonJS(index_exports);
 // src/fieldRegistry.ts
 var FieldRegistry = class {
   constructor() {
-    this.map = /* @__PURE__ */ new Map();
+    // ❗ INTERNAL = string, KHÔNG constrain
+    this.registry = {};
   }
+  // ✅ Type safety ở API
   register(type, renderer) {
-    this.map.set(type, renderer);
+    this.registry[type] = renderer;
   }
   get(type) {
-    return this.map.get(type);
+    return this.registry[type];
   }
 };
 var fieldRegistry = new FieldRegistry();
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  FieldRegistry,
   fieldRegistry
 });
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts","../src/fieldRegistry.ts"],"sourcesContent":["export * from \"./types\"\r\nexport * from \"./fieldRegistry\"\r\n","import { JSX } from \"react\"\r\nimport { FieldRendererProps, FieldTypeKey } from \"./types\"\r\n\r\ntype Renderer = (props: FieldRendererProps<any>) => JSX.Element\r\n\r\nclass FieldRegistry {\r\n    private map = new Map<FieldTypeKey, Renderer>()\r\n\r\n    register<T extends FieldTypeKey>(\r\n        type: T,\r\n        renderer: (props: FieldRendererProps) => JSX.Element\r\n    ) {\r\n        this.map.set(type, renderer)\r\n    }\r\n\r\n    get(type: FieldTypeKey) {\r\n        return this.map.get(type)\r\n    }\r\n}\r\n\r\nexport const fieldRegistry = new FieldRegistry()\r\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACKA,IAAM,gBAAN,MAAoB;AAAA,EAApB;AACI,SAAQ,MAAM,oBAAI,IAA4B;AAAA;AAAA,EAE9C,SACI,MACA,UACF;AACE,SAAK,IAAI,IAAI,MAAM,QAAQ;AAAA,EAC/B;AAAA,EAEA,IAAI,MAAoB;AACpB,WAAO,KAAK,IAAI,IAAI,IAAI;AAAA,EAC5B;AACJ;AAEO,IAAM,gBAAgB,IAAI,cAAc;","names":[]}
+{"version":3,"sources":["../src/index.ts","../src/fieldRegistry.ts"],"sourcesContent":["export * from \"./types\"\r\nexport * from \"./fieldRegistry\"\r\n","import { JSX } from \"react\"\r\nimport type { FieldRendererProps, FieldTypeMap } from \"./types\"\r\n\r\nexport type FieldRenderer<T = any> = (props: FieldRendererProps<T>) => JSX.Element\r\n\r\nexport class FieldRegistry {\r\n    // ❗ INTERNAL = string, KHÔNG constrain\r\n    private registry: Record<string, FieldRenderer<any>> = {}\r\n\r\n    // ✅ Type safety ở API\r\n    register<K extends keyof FieldTypeMap>(\r\n        type: K,\r\n        renderer: FieldRenderer<FieldTypeMap[K]>\r\n    ) {\r\n        this.registry[type as string] = renderer\r\n    }\r\n\r\n    get<K extends keyof FieldTypeMap>(\r\n        type: K\r\n    ): FieldRenderer<FieldTypeMap[K]> | undefined {\r\n        return this.registry[type as string]\r\n    }\r\n}\r\n\r\nexport const fieldRegistry = new FieldRegistry()\r\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACKO,IAAM,gBAAN,MAAoB;AAAA,EAApB;AAEH;AAAA,SAAQ,WAA+C,CAAC;AAAA;AAAA;AAAA,EAGxD,SACI,MACA,UACF;AACE,SAAK,SAAS,IAAc,IAAI;AAAA,EACpC;AAAA,EAEA,IACI,MAC0C;AAC1C,WAAO,KAAK,SAAS,IAAc;AAAA,EACvC;AACJ;AAEO,IAAM,gBAAgB,IAAI,cAAc;","names":[]}

package/dist/index.mjs

@@ -1,17 +1,20 @@
 // src/fieldRegistry.ts
 var FieldRegistry = class {
   constructor() {
-    this.map = /* @__PURE__ */ new Map();
+    // ❗ INTERNAL = string, KHÔNG constrain
+    this.registry = {};
   }
+  // ✅ Type safety ở API
   register(type, renderer) {
-    this.map.set(type, renderer);
+    this.registry[type] = renderer;
   }
   get(type) {
-    return this.map.get(type);
+    return this.registry[type];
   }
 };
 var fieldRegistry = new FieldRegistry();
 export {
+  FieldRegistry,
   fieldRegistry
 };
 //# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/fieldRegistry.ts"],"sourcesContent":["import { JSX } from \"react\"\r\nimport { FieldRendererProps, FieldTypeKey } from \"./types\"\r\n\r\ntype Renderer = (props: FieldRendererProps<any>) => JSX.Element\r\n\r\nclass FieldRegistry {\r\n    private map = new Map<FieldTypeKey, Renderer>()\r\n\r\n    register<T extends FieldTypeKey>(\r\n        type: T,\r\n        renderer: (props: FieldRendererProps) => JSX.Element\r\n    ) {\r\n        this.map.set(type, renderer)\r\n    }\r\n\r\n    get(type: FieldTypeKey) {\r\n        return this.map.get(type)\r\n    }\r\n}\r\n\r\nexport const fieldRegistry = new FieldRegistry()\r\n"],"mappings":";AAKA,IAAM,gBAAN,MAAoB;AAAA,EAApB;AACI,SAAQ,MAAM,oBAAI,IAA4B;AAAA;AAAA,EAE9C,SACI,MACA,UACF;AACE,SAAK,IAAI,IAAI,MAAM,QAAQ;AAAA,EAC/B;AAAA,EAEA,IAAI,MAAoB;AACpB,WAAO,KAAK,IAAI,IAAI,IAAI;AAAA,EAC5B;AACJ;AAEO,IAAM,gBAAgB,IAAI,cAAc;","names":[]}
+{"version":3,"sources":["../src/fieldRegistry.ts"],"sourcesContent":["import { JSX } from \"react\"\r\nimport type { FieldRendererProps, FieldTypeMap } from \"./types\"\r\n\r\nexport type FieldRenderer<T = any> = (props: FieldRendererProps<T>) => JSX.Element\r\n\r\nexport class FieldRegistry {\r\n    // ❗ INTERNAL = string, KHÔNG constrain\r\n    private registry: Record<string, FieldRenderer<any>> = {}\r\n\r\n    // ✅ Type safety ở API\r\n    register<K extends keyof FieldTypeMap>(\r\n        type: K,\r\n        renderer: FieldRenderer<FieldTypeMap[K]>\r\n    ) {\r\n        this.registry[type as string] = renderer\r\n    }\r\n\r\n    get<K extends keyof FieldTypeMap>(\r\n        type: K\r\n    ): FieldRenderer<FieldTypeMap[K]> | undefined {\r\n        return this.registry[type as string]\r\n    }\r\n}\r\n\r\nexport const fieldRegistry = new FieldRegistry()\r\n"],"mappings":";AAKO,IAAM,gBAAN,MAAoB;AAAA,EAApB;AAEH;AAAA,SAAQ,WAA+C,CAAC;AAAA;AAAA;AAAA,EAGxD,SACI,MACA,UACF;AACE,SAAK,SAAS,IAAc,IAAI;AAAA,EACpC;AAAA,EAEA,IACI,MAC0C;AAC1C,WAAO,KAAK,SAAS,IAAc;AAAA,EACvC;AACJ;AAEO,IAAM,gBAAgB,IAAI,cAAc;","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@dynamic-field-kit/core",
-    "version": "1.0.0",
+    "version": "1.0.3",
     "description": "Core types and field registry for dynamic-field-kit",
     "license": "MIT",
     "main": "dist/index.cjs",
@@ -21,4 +21,4 @@
         "build": "tsup",
         "clean": "rm -rf dist"
     }
-}
+}