@type32/yaml-editor-form 0.1.3 → 0.1.5

package/README.md

@@ -96,7 +96,7 @@ const data = ref({
 </script>
 
 <template>
-    <YamlForm v-model="data" />
+    <YamlFormEditor v-model="data" />
 </template>
 ```
 
@@ -104,7 +104,7 @@ const data = ref({
 
 ```vue
 <script setup lang="ts">
-import type { YamlFieldType } from './useYamlFieldTypes'
+import type { YamlFieldType } from '@type32/yaml-editor-form'
 
 const customTypes: YamlFieldType[] = [
     {
@@ -112,6 +112,7 @@ const customTypes: YamlFieldType[] = [
         label: 'Image',
         icon: 'i-lucide-image',
         defaultValue: '',
+        baseType: 'string',
         component: 'image'
     }
 ]
@@ -123,11 +124,15 @@ const data = ref({
 </script>
 
 <template>
-    <YamlForm v-model="data" :field-types="customTypes">
-        <template #field-image="{ modelValue, readonly }">
-            <MyImagePicker v-model="modelValue" :disabled="readonly" />
+    <YamlFormEditor v-model="data" :field-types="customTypes">
+        <template #field-image="{ modelValue, readonly, updateModelValue }">
+            <MyImagePicker 
+                :model-value="modelValue" 
+                :disabled="readonly"
+                @update:model-value="updateModelValue"
+            />
         </template>
-    </YamlForm>
+    </YamlFormEditor>
 </template>
 ```
 
@@ -136,7 +141,7 @@ const data = ref({
 ### Component Hierarchy
 
 ```
-YamlForm.vue (Entry Point)
+YamlFormEditor.vue (Entry Point)
 └── YamlFormField.vue (Recursive Component)
     ├── YamlFieldInput.vue (Simple Types)
     │   ├── UInput (string)
@@ -147,7 +152,7 @@ YamlForm.vue (Entry Point)
     │   ├── UInputTags (string-array)
     │   └── Custom Slots (user-defined)
     └── YamlFormField.vue (Complex Types - Recursive)
-        ├── Collapsible (objects/arrays)
+        ├── YamlCollapsible (objects/arrays)
         └── Array/Object rendering
 ```
 
@@ -160,7 +165,7 @@ YamlFieldInput (v-model)
     ↓
 YamlFormField (v-model)
     ↓
-YamlForm (v-model)
+YamlFormEditor (v-model)
     ↓
 Parent Component (data binding)
 ```
@@ -179,7 +184,7 @@ Components (Rendering)
 
 ## Component API
 
-### YamlForm
+### YamlFormEditor
 
 Main entry point for the editor.
 
@@ -207,8 +212,33 @@ Main entry point for the editor.
 All custom field component slots are supported:
 
 ```vue
-<template #field-{component}="{ modelValue, readonly, valueType }">
+<template #field-{component}="{ modelValue, readonly, valueType, updateModelValue }">
     <!-- Your custom component -->
+    <!-- Use :model-value and @update:model-value, NOT v-model -->
+</template>
+```
+
+**Slot Props:**
+- `modelValue`: Current field value (read-only prop)
+- `readonly`: Whether field is in read-only mode
+- `valueType`: Type identifier string
+- `updateModelValue`: Function to update value: `(newValue) => void`
+
+**Important:** You cannot use `v-model` on slot props (they're read-only). Use `:model-value` and `@update:model-value` instead:
+
+```vue
+<!-- ❌ WRONG - v-model doesn't work on slot props -->
+<template #field-color="{ modelValue, readonly }">
+    <UColorPicker v-model="modelValue" :disabled="readonly" />
+</template>
+
+<!-- ✅ CORRECT - use updateModelValue function -->
+<template #field-color="{ modelValue, readonly, updateModelValue }">
+    <UColorPicker 
+        :model-value="modelValue" 
+        :disabled="readonly"
+        @update:model-value="updateModelValue"
+    />
 </template>
 ```
 
@@ -240,7 +270,7 @@ Recursive component that handles individual fields.
 
 #### Slots
 
-Same as YamlForm - all custom field slots are forwarded.
+Same as YamlFormEditor - all custom field slots are forwarded through the recursive hierarchy.
 
 ### YamlFieldInput
 
@@ -268,26 +298,73 @@ Renders input components for simple types.
 #### Slots
 
 ```vue
-<template #field-{component}="{ modelValue, readonly, valueType }">
+<template #field-{component}="{ modelValue, readonly, valueType, updateModelValue }">
     <!-- Custom input component -->
+    <!-- Use updateModelValue function for two-way binding -->
 </template>
 ```
 
+**Slot Props:**
+- `modelValue`: Current value (read-only)
+- `readonly`: Whether field is read-only
+- `valueType`: Type identifier
+- `updateModelValue`: Update function `(val) => void`
+
 ## Field Types
 
 ### Type Definition
 
 ```typescript
+// Valid base types (type-safe!)
+type YamlBaseType = 
+    | 'string'       // Text primitives
+    | 'number'       // Numeric primitives
+    | 'boolean'      // Boolean primitives
+    | 'date'         // Date without time
+    | 'datetime'     // Date with time
+    | 'string-array' // Array of strings (tags)
+    | 'array'        // Generic array
+    | 'object'       // Generic object
+    | 'null'         // Null value
+
 interface YamlFieldType {
-    type: string              // Unique type identifier
+    type: string              // Unique type identifier (e.g., 'color', 'email')
     label: string             // Display name in dropdowns
     icon: string              // Lucide icon name (i-lucide-*)
     defaultValue: any         // Default value or factory function
+    baseType: YamlBaseType    // REQUIRED: Base type for conversion rules
     component?: string        // Optional: slot name for custom rendering
     detect?: (value: any) => boolean  // Optional: auto-detection function
 }
 ```
 
+**The `baseType` Field (Type-Safe!):**
+
+The `baseType` field is **required** and must be one of the predefined base types. This provides:
+- ✅ **TypeScript autocomplete** - IntelliSense suggests valid base types
+- ✅ **Compile-time safety** - Typos are caught immediately
+- ✅ **Conversion inheritance** - Custom types inherit conversion rules from their base
+- ✅ **Clear semantics** - Explicit relationship between custom and base types
+
+**Examples:**
+```typescript
+// ✅ Valid - 'string' is a valid YamlBaseType
+{ type: 'color', baseType: 'string' }
+
+// ✅ Valid - 'number' is a valid YamlBaseType
+{ type: 'percentage', baseType: 'number' }
+
+// ❌ Invalid - TypeScript error (not a valid base type)
+{ type: 'custom', baseType: 'invalid' }  // Type error!
+```
+
+**Conversion Inheritance:**
+- A `color` type with `baseType: 'string'` can convert to/from anything a string can
+- A `percentage` type with `baseType: 'number'` inherits number conversions
+- Custom types can also convert directly to/from their base type
+
+This enables powerful type hierarchies without duplicating conversion logic.
+
 ### Built-in Types
 
 ```typescript
@@ -401,6 +478,7 @@ export const DEFAULT_FIELD_TYPES: YamlFieldType[] = [
         label: 'Email',
         icon: 'i-lucide-mail',
         defaultValue: '',
+        baseType: 'string',
         detect: (value) => typeof value === 'string' && /^[^@]+@[^@]+/.test(value)
     }
 ]
@@ -421,13 +499,14 @@ const customTypes: YamlFieldType[] = [
         label: 'URL',
         icon: 'i-lucide-link',
         defaultValue: 'https://',
+        baseType: 'string',
         detect: (value) => typeof value === 'string' && value.startsWith('http')
     }
 ]
 ```
 
 ```vue
-<YamlForm v-model="data" :field-types="customTypes" />
+<YamlFormEditor v-model="data" :field-types="customTypes" />
 ```
 
 ### Adding a Runtime Type (With Custom Component)
@@ -439,23 +518,25 @@ const customTypes: YamlFieldType[] = [
         label: 'Color',
         icon: 'i-lucide-palette',
         defaultValue: '#000000',
+        baseType: 'string',  // Inherits string conversions
         component: 'color',  // Enables slot
-        detect: (value) => /^#[0-9A-Fa-f]{6}$/.test(value)
+        detect: (value) => typeof value === 'string' && /^#[0-9A-Fa-f]{6}$/.test(value)
     }
 ]
 ```
 
 ```vue
-<YamlForm v-model="data" :field-types="customTypes">
-    <template #field-color="{ modelValue, readonly }">
+<YamlFormEditor v-model="data" :field-types="customTypes">
+    <template #field-color="{ modelValue, readonly, updateModelValue }">
         <input 
             type="color" 
-            v-model="modelValue"
+            :value="modelValue"
             :disabled="readonly"
+            @input="(e) => updateModelValue(e.target.value)"
             class="w-full h-10 rounded"
         />
     </template>
-</YamlForm>
+</YamlFormEditor>
 ```
 
 ### Overriding Built-in Types
@@ -467,17 +548,22 @@ const customTypes: YamlFieldType[] = [
         label: 'Rich Text',
         icon: 'i-lucide-file-text',
         defaultValue: '',
+        baseType: 'string',
         component: 'richtext'  // Now uses custom component
     }
 ]
 ```
 
 ```vue
-<YamlForm v-model="data" :field-types="customTypes">
-    <template #field-richtext="{ modelValue, readonly }">
-        <MyRichTextEditor v-model="modelValue" :read-only="readonly" />
+<YamlFormEditor v-model="data" :field-types="customTypes">
+    <template #field-richtext="{ modelValue, readonly, updateModelValue }">
+        <MyRichTextEditor 
+            :model-value="modelValue" 
+            :read-only="readonly"
+            @update:model-value="updateModelValue"
+        />
     </template>
-</YamlForm>
+</YamlFormEditor>
 ```
 
 ## Schema System
@@ -558,7 +644,7 @@ const config = ref({
 </script>
 
 <template>
-    <YamlForm v-model="config" />
+    <YamlFormEditor v-model="config" />
 </template>
 ```
 
@@ -577,7 +663,7 @@ const article = ref({
 </script>
 
 <template>
-    <YamlForm v-model="article" />
+    <YamlFormEditor v-model="article" />
 </template>
 ```
 
@@ -594,7 +680,7 @@ const data = ref({
 </script>
 
 <template>
-    <YamlForm v-model="data" />
+    <YamlFormEditor v-model="data" />
 </template>
 ```
 
@@ -602,7 +688,7 @@ const data = ref({
 
 ```vue
 <script setup lang="ts">
-import type { YamlFieldType } from './useYamlFieldTypes'
+import type { YamlFieldType } from '@type32/yaml-editor-form'
 
 // Define custom types
 const customTypes: YamlFieldType[] = [
@@ -611,6 +697,7 @@ const customTypes: YamlFieldType[] = [
         label: 'Image',
         icon: 'i-lucide-image',
         defaultValue: '',
+        baseType: 'string',
         component: 'image'
     },
     {
@@ -618,6 +705,7 @@ const customTypes: YamlFieldType[] = [
         label: 'Markdown',
         icon: 'i-lucide-file-text',
         defaultValue: '',
+        baseType: 'string',
         component: 'markdown'
     }
 ]
@@ -630,23 +718,25 @@ const post = ref({
 </script>
 
 <template>
-    <YamlForm v-model="post" :field-types="customTypes">
+    <YamlFormEditor v-model="post" :field-types="customTypes">
         <!-- Image picker component -->
-        <template #field-image="{ modelValue, readonly }">
+        <template #field-image="{ modelValue, readonly, updateModelValue }">
             <MyImagePicker 
-                v-model="modelValue" 
+                :model-value="modelValue" 
                 :disabled="readonly"
+                @update:model-value="updateModelValue"
             />
         </template>
         
         <!-- Markdown editor component -->
-        <template #field-markdown="{ modelValue, readonly }">
+        <template #field-markdown="{ modelValue, readonly, updateModelValue }">
             <MyMarkdownEditor 
-                v-model="modelValue"
+                :model-value="modelValue"
                 :read-only="readonly"
+                @update:model-value="updateModelValue"
             />
         </template>
-    </YamlForm>
+    </YamlFormEditor>
 </template>
 ```
 
@@ -660,19 +750,21 @@ const customTypes: YamlFieldType[] = [
         label: 'UUID',
         icon: 'i-lucide-fingerprint',
         defaultValue: () => crypto.randomUUID(),  // Function called each time
+        baseType: 'string',
         detect: (v) => /^[0-9a-f]{8}-[0-9a-f]{4}-/.test(v)
     },
     {
         type: 'timestamp',
         label: 'Timestamp',
         icon: 'i-lucide-clock',
-        defaultValue: () => new Date().toISOString()
+        defaultValue: () => new Date().toISOString(),
+        baseType: 'string'
     }
 ]
 </script>
 
 <template>
-    <YamlForm v-model="data" :field-types="customTypes" />
+    <YamlFormEditor v-model="data" :field-types="customTypes" />
 </template>
 ```
 
@@ -680,7 +772,7 @@ const customTypes: YamlFieldType[] = [
 
 ```vue
 <template>
-    <YamlForm v-model="data" readonly />
+    <YamlFormEditor v-model="data" readonly />
 </template>
 ```
 
@@ -712,7 +804,7 @@ const complexData = ref({
 </script>
 
 <template>
-    <YamlForm v-model="complexData" />
+    <YamlFormEditor v-model="complexData" />
 </template>
 ```
 
@@ -720,10 +812,10 @@ const complexData = ref({
 
 ```
 components/
-├── YamlForm.vue                           ← Entry component
+├── YamlFormEditor.vue                     ← Entry component
 ├── YamlFormField.vue                      ← Recursive field component
 ├── YamlFieldInput.vue                     ← Input rendering component
-└── Collapsible.vue                        ← Collapsible UI component
+└── YamlCollapsible.vue                    ← Collapsible UI component
 
 composables/
 └── useYamlFieldTypes.ts                   ← Type registry & composable
@@ -750,6 +842,7 @@ types/
     label: 'My Type',
     icon: 'i-lucide-my-icon',
     defaultValue: 'default',
+    baseType: 'string',  // Required: specify base type for conversions
     detect: (value) => /* detection logic */
 }
 ```
@@ -903,27 +996,89 @@ interface YamlFieldInputProps {
 
 ### Slot Forwarding
 
-Slots are automatically forwarded through the component hierarchy:
+Slots are automatically forwarded through the component hierarchy using Vue 3's dynamic slot forwarding:
+
+```
+YamlFormEditor (receives slot from parent)
+    ↓ forwards all slots with v-bind="slotProps"
+YamlFormField (receives & forwards slots)
+    ↓ forwards all slots with v-bind="slotProps"
+    ↓ (recursively for nested structures)
+YamlFieldInput (terminal - uses slot)
+    ↓ renders slot: #field-{component}
+    ↓ provides props: { modelValue, readonly, valueType, updateModelValue }
+Custom Component
+```
+
+**How It Works:**
+
+1. **YamlFormEditor** (lines 89-92): Receives slots and forwards to YamlFormField
+2. **YamlFormField** (lines 634-636): Forwards slots to YamlFieldInput OR itself (for recursion)
+3. **YamlFieldInput** (lines 88-95): Final destination - renders slot with props
+
+**Slot Props Flow:**
 
+The `updateModelValue` function is created at the YamlFieldInput level and allows your custom component to update the value:
+
+```typescript
+// In YamlFieldInput.vue
+:update-model-value="(val: YamlValue) => modelValue = val"
 ```
-YamlForm (defines slot)
-    ↓ forwards
-YamlFormField (forwards slot)
-    ↓ forwards
-YamlFieldInput (uses slot)
+
+This function captures the parent's `modelValue` ref and updates it directly, maintaining reactivity throughout the hierarchy.
+
+**Example with Nested Structure:**
+
+```vue
+<!-- Works at any depth! -->
+<YamlFormEditor v-model="data" :field-types="customTypes">
+    <template #field-color="{ modelValue, updateModelValue }">
+        <UColorPicker 
+            :model-value="modelValue"
+            @update:model-value="updateModelValue"
+        />
+    </template>
+</YamlFormEditor>
 ```
 
-This allows custom components to work at any nesting level.
+Even if your color field is deeply nested (`data.theme.colors.primary`), the slot works identically because slots are forwarded at every level.
 
 ### Type Priority
 
-When multiple types have `detect` functions that match:
+**Detection Order (NEW in v0.2.0):**
+
+Custom types with `detect` functions are now checked **before** default types:
+
+1. **Custom types** (checked first) - Your custom types take priority
+2. **Default types** (checked second) - Built-in types as fallback
+3. First matching type wins
+
+This means:
+- ✅ Your `color` type will be detected before the default `string` type
+- ✅ Custom types override default detection behavior
+- ✅ More specific types should still have more specific detect functions
+
+**Example:**
+```typescript
+// Custom color type checked FIRST
+const customTypes = [{
+    type: 'color',
+    baseType: 'string',
+    detect: (v) => typeof v === 'string' && /^#[0-9A-Fa-f]{6}$/.test(v)
+}]
+
+// Value '#FF0000' will match 'color' before 'string'
+```
+
+**Base Type Conversions:**
+
+When using `baseType`, conversion rules follow this logic:
 
-1. Types are checked in array order
-2. First matching type wins
-3. More specific types should come before general types
+1. Can convert between type and its baseType (e.g., `color` ↔ `string`)
+2. Can convert to anything the baseType can (e.g., `color` → `number` because `string` → `number`)
+3. Custom conversion rules take precedence over inherited rules
 
-**Example order:**
+**Example order for default types:**
 ```typescript
 [
     { type: 'datetime', detect: (v) => isDateTimeString(v) },  // Specific
@@ -1023,6 +1178,320 @@ Requires:
 - reka-ui (via Nuxt UI)
 - tailwindcss (via Nuxt)
 
+## Advanced Examples
+
+### Custom String Array Type
+
+Here's an example of a custom string array type with autocomplete suggestions:
+
+```vue
+<script setup lang="ts">
+import type { YamlFieldType } from '@type32/yaml-editor-form'
+
+const customTypes: YamlFieldType[] = [
+    {
+        type: 'skills',
+        label: 'Skills',
+        icon: 'i-lucide-sparkles',
+        defaultValue: [],
+        baseType: 'string-array',  // Inherits array conversions
+        component: 'skills',
+        detect: (value) => {
+            // Auto-detect arrays with skill-like strings
+            return Array.isArray(value) && 
+                   value.length > 0 && 
+                   value.every(v => typeof v === 'string' && v.length < 30)
+        }
+    }
+]
+
+const profile = ref({
+    name: 'John Doe',
+    skills: ['Vue.js', 'TypeScript', 'Nuxt']
+})
+
+// Predefined skill suggestions
+const skillSuggestions = [
+    'Vue.js', 'React', 'Angular', 'TypeScript', 'JavaScript',
+    'Node.js', 'Python', 'Nuxt', 'Next.js', 'Tailwind CSS'
+]
+</script>
+
+<template>
+    <YamlFormEditor v-model="profile" :field-types="customTypes">
+        <!-- Custom skills input with autocomplete -->
+        <template #field-skills="{ modelValue, readonly, updateModelValue }">
+            <div class="space-y-2">
+                <!-- Display current skills as badges -->
+                <div class="flex flex-wrap gap-2">
+                    <UBadge
+                        v-for="(skill, index) in (modelValue as string[])"
+                        :key="index"
+                        color="primary"
+                        variant="soft"
+                    >
+                        {{ skill }}
+                        <UButton
+                            v-if="!readonly"
+                            icon="i-lucide-x"
+                            size="2xs"
+                            variant="ghost"
+                            :padded="false"
+                            @click="updateModelValue((modelValue as string[]).filter((_, i) => i !== index))"
+                        />
+                    </UBadge>
+                </div>
+                
+                <!-- Add new skill with autocomplete -->
+                <UInputMenu
+                    v-if="!readonly"
+                    :options="skillSuggestions"
+                    placeholder="Add skill..."
+                    @update:model-value="(newSkill: string) => {
+                        if (newSkill && !(modelValue as string[]).includes(newSkill)) {
+                            updateModelValue([...(modelValue as string[]), newSkill])
+                        }
+                    }"
+                />
+            </div>
+        </template>
+    </YamlFormEditor>
+</template>
+```
+
+### Custom Object Array Type
+
+Here's an example of a custom object array type with card-based rendering:
+
+```vue
+<script setup lang="ts">
+import type { YamlFieldType } from '@type32/yaml-editor-form'
+
+const customTypes: YamlFieldType[] = [
+    {
+        type: 'contacts',
+        label: 'Contacts',
+        icon: 'i-lucide-users',
+        defaultValue: [],
+        baseType: 'array',  // Inherits array conversions
+        component: 'contacts',
+        detect: (value) => {
+            // Auto-detect arrays of contact-like objects
+            return Array.isArray(value) && 
+                   value.length > 0 &&
+                   value.every(v => 
+                       v && typeof v === 'object' && 
+                       ('name' in v || 'email' in v)
+                   )
+        }
+    }
+]
+
+const data = ref({
+    projectName: 'My Project',
+    contacts: [
+        { name: 'Alice Johnson', email: 'alice@example.com', role: 'Designer' },
+        { name: 'Bob Smith', email: 'bob@example.com', role: 'Developer' }
+    ]
+})
+</script>
+
+<template>
+    <YamlFormEditor v-model="data" :field-types="customTypes">
+        <!-- Custom contacts list with card UI -->
+        <template #field-contacts="{ modelValue, readonly, updateModelValue }">
+            <div class="space-y-3">
+                <!-- Contact cards -->
+                <UCard
+                    v-for="(contact, index) in (modelValue as any[])"
+                    :key="index"
+                    :ui="{ body: { padding: 'p-4' } }"
+                >
+                    <div class="flex items-start justify-between gap-3">
+                        <div class="flex-1 space-y-2">
+                            <!-- Name -->
+                            <UInput
+                                :model-value="contact.name"
+                                placeholder="Name"
+                                :disabled="readonly"
+                                @update:model-value="(val: string) => {
+                                    const updated = [...(modelValue as any[])]
+                                    updated[index] = { ...contact, name: val }
+                                    updateModelValue(updated)
+                                }"
+                            />
+                            
+                            <!-- Email -->
+                            <UInput
+                                :model-value="contact.email"
+                                type="email"
+                                placeholder="Email"
+                                icon="i-lucide-mail"
+                                :disabled="readonly"
+                                @update:model-value="(val: string) => {
+                                    const updated = [...(modelValue as any[])]
+                                    updated[index] = { ...contact, email: val }
+                                    updateModelValue(updated)
+                                }"
+                            />
+                            
+                            <!-- Role -->
+                            <UInput
+                                :model-value="contact.role"
+                                placeholder="Role"
+                                icon="i-lucide-briefcase"
+                                :disabled="readonly"
+                                @update:model-value="(val: string) => {
+                                    const updated = [...(modelValue as any[])]
+                                    updated[index] = { ...contact, role: val }
+                                    updateModelValue(updated)
+                                }"
+                            />
+                        </div>
+                        
+                        <!-- Remove button -->
+                        <UButton
+                            v-if="!readonly"
+                            icon="i-lucide-trash-2"
+                            color="red"
+                            variant="ghost"
+                            size="sm"
+                            @click="updateModelValue((modelValue as any[]).filter((_, i) => i !== index))"
+                        />
+                    </div>
+                </UCard>
+                
+                <!-- Add contact button -->
+                <UButton
+                    v-if="!readonly"
+                    icon="i-lucide-plus"
+                    label="Add Contact"
+                    variant="outline"
+                    block
+                    @click="updateModelValue([
+                        ...(modelValue as any[]),
+                        { name: '', email: '', role: '' }
+                    ])"
+                />
+            </div>
+        </template>
+    </YamlFormEditor>
+</template>
+```
+
+### Combined Example
+
+You can use both custom array types together:
+
+```vue
+<script setup lang="ts">
+import type { YamlFieldType } from '@type32/yaml-editor-form'
+
+const customTypes: YamlFieldType[] = [
+    // Custom string array
+    {
+        type: 'tags',
+        label: 'Tags',
+        icon: 'i-lucide-tag',
+        defaultValue: [],
+        baseType: 'string-array',
+        component: 'tags',
+        detect: (v) => Array.isArray(v) && v.every(i => typeof i === 'string')
+    },
+    // Custom object array
+    {
+        type: 'team',
+        label: 'Team Members',
+        icon: 'i-lucide-users',
+        defaultValue: [],
+        baseType: 'array',
+        component: 'team',
+        detect: (v) => Array.isArray(v) && v.every(i => i?.name || i?.email)
+    }
+]
+
+const project = ref({
+    name: 'Website Redesign',
+    tags: ['frontend', 'design', 'urgent'],
+    team: [
+        { name: 'Alice', email: 'alice@example.com' },
+        { name: 'Bob', email: 'bob@example.com' }
+    ]
+})
+</script>
+
+<template>
+    <YamlFormEditor v-model="project" :field-types="customTypes">
+        <!-- String array implementation -->
+        <template #field-tags="{ modelValue, readonly, updateModelValue }">
+            <UInputTags
+                :model-value="modelValue as string[]"
+                :disabled="readonly"
+                placeholder="Add tags..."
+                @update:model-value="updateModelValue"
+            />
+        </template>
+        
+        <!-- Object array implementation -->
+        <template #field-team="{ modelValue, readonly, updateModelValue }">
+            <!-- Your custom team member UI here -->
+            <div class="space-y-2">
+                <div
+                    v-for="(member, idx) in (modelValue as any[])"
+                    :key="idx"
+                    class="flex gap-2"
+                >
+                    <UInput
+                        :model-value="member.name"
+                        placeholder="Name"
+                        :disabled="readonly"
+                        @update:model-value="(val: string) => {
+                            const updated = [...(modelValue as any[])]
+                            updated[idx] = { ...member, name: val }
+                            updateModelValue(updated)
+                        }"
+                    />
+                    <UButton
+                        v-if="!readonly"
+                        icon="i-lucide-x"
+                        color="red"
+                        variant="ghost"
+                        @click="updateModelValue((modelValue as any[]).filter((_, i) => i !== idx))"
+                    />
+                </div>
+                <UButton
+                    v-if="!readonly"
+                    icon="i-lucide-plus"
+                    label="Add Member"
+                    size="sm"
+                    @click="updateModelValue([...(modelValue as any[]), { name: '', email: '' }])"
+                />
+            </div>
+        </template>
+    </YamlFormEditor>
+</template>
+```
+
+### Key Patterns for Array Types
+
+**String Arrays (`baseType: 'string-array'`):**
+- Use for specialized tag inputs, category lists, etc.
+- Can convert to/from regular arrays and strings
+- Good for: skills, tags, categories, keywords
+
+**Object Arrays (`baseType: 'array'`):**
+- Use for collections with structured data
+- Provide custom UI for adding/editing/removing items
+- Good for: contacts, team members, products, events
+
+**Important Notes:**
+1. **Type Assertions**: Use `(modelValue as string[])` or `(modelValue as any[])` for type safety
+2. **Immutability**: Always create new arrays when updating (spread operator `[...]`)
+3. **Index Management**: Track items by index for updates/deletions
+4. **Add Operations**: Spread existing array and add new items
+5. **Remove Operations**: Use `filter()` to remove by index
+6. **Update Operations**: Clone array, modify specific index, update entire array
+
 ## License
 
 This component is part of the Vertex project.
@@ -1046,11 +1515,11 @@ For issues, questions, or feature requests, refer to the main Vertex project doc
 
 ### Core Components
 
-- **YamlForm**: Entry point component for the editor
+- **YamlFormEditor**: Entry point component for the editor
 - **YamlFormField**: Recursive component handling individual fields
 - **YamlFieldInput**: Input rendering component for simple types
+- **YamlCollapsible**: UI component for collapsible sections
 - **useYamlFieldTypes**: Composable for type registry and management
-- **Collapsible**: UI component for collapsible sections
 
 ### Key Concepts
 
@@ -1077,11 +1546,15 @@ For issues, questions, or feature requests, refer to the main Vertex project doc
 
 **Add Custom Component:**
 ```vue
-<YamlForm>
-  <template #field-{type}="props">
-    <Component v-bind="props" />
+<YamlFormEditor v-model="data" :field-types="customTypes">
+  <template #field-{type}="{ modelValue, readonly, updateModelValue }">
+    <MyComponent 
+      :model-value="modelValue"
+      :disabled="readonly"
+      @update:model-value="updateModelValue"
+    />
   </template>
-</YamlForm>
+</YamlFormEditor>
 ```
 
 **Type Conversion:**