@ng-forge/dynamic-form-mcp 1.0.0-rc.3 → 1.0.0

package/src/index.js

@@ -648,9 +648,9 @@ var FIELD_TYPES = [
     minimalExample: `{ key: 'submit', type: 'submit', label: 'Submit' }`
   },
   {
-    type: "addArrayItem",
+    type: "add-array-item",
     category: "button",
-    description: "Button to add a new item to an array field. Must be placed within or near the array container.",
+    description: "Button to append a new item to the end of an array field. Must be placed within or near the array container. (Legacy alias: addArrayItem.)",
     valueType: void 0,
     baseInterface: "FieldDef",
     props: {},
@@ -659,15 +659,50 @@ var FIELD_TYPES = [
     allowedIn: ["array", "row", "group"],
     example: `{
   key: 'addContact',
-  type: 'addArrayItem',
+  type: 'add-array-item',
   label: 'Add Contact'
 }`,
-    minimalExample: `{ key: 'add', type: 'addArrayItem', label: 'Add Item' }`
+    minimalExample: `{ key: 'add', type: 'add-array-item', label: 'Add Item' }`
   },
   {
-    type: "removeArrayItem",
+    type: "prepend-array-item",
     category: "button",
-    description: "Button to remove the current item from an array field. Typically placed within each array item template.",
+    description: "Button to add a new item to the beginning of an array field. (Legacy alias: prependArrayItem.)",
+    valueType: void 0,
+    baseInterface: "FieldDef",
+    props: {},
+    validationSupported: false,
+    source: "adapter",
+    allowedIn: ["array", "row", "group"],
+    example: `{
+  key: 'prependContact',
+  type: 'prepend-array-item',
+  label: 'Add to Top'
+}`,
+    minimalExample: `{ key: 'prepend', type: 'prepend-array-item', label: 'Add First' }`
+  },
+  {
+    type: "insert-array-item",
+    category: "button",
+    description: "Button to insert a new item at a specific index in an array field (set via the index property). (Legacy alias: insertArrayItem.)",
+    valueType: void 0,
+    baseInterface: "FieldDef",
+    props: {},
+    validationSupported: false,
+    source: "adapter",
+    allowedIn: ["array", "row", "group"],
+    example: `{
+  key: 'insertContact',
+  type: 'insert-array-item',
+  label: 'Insert',
+  index: 1
+}`,
+    minimalExample: `{ key: 'insert', type: 'insert-array-item', label: 'Insert', index: 0 }`
+  },
+  {
+    type: "remove-array-item",
+    category: "button",
+    description: "Button to remove the current item from an array field. Typically placed within each array item template. (Legacy alias: removeArrayItem.)",
     valueType: void 0,
     baseInterface: "FieldDef",
     props: {},
@@ -676,10 +711,46 @@ var FIELD_TYPES = [
     allowedIn: ["array", "row", "group"],
     example: `{
   key: 'removeContact',
-  type: 'removeArrayItem',
+  type: 'remove-array-item',
   label: 'Remove'
 }`,
-    minimalExample: `{ key: 'remove', type: 'removeArrayItem', label: 'Remove' }`
+    minimalExample: `{ key: 'remove', type: 'remove-array-item', label: 'Remove' }`
+  },
+  {
+    type: "pop-array-item",
+    category: "button",
+    description: "Button to remove the last item from an array field. (Legacy alias: popArrayItem.)",
+    valueType: void 0,
+    baseInterface: "FieldDef",
+    props: {},
+    validationSupported: false,
+    source: "adapter",
+    allowedIn: ["array", "row", "group"],
+    example: `{
+  key: 'popContact',
+  type: 'pop-array-item',
+  label: 'Remove Last',
+  arrayKey: 'contacts'
+}`,
+    minimalExample: `{ key: 'pop', type: 'pop-array-item', label: 'Remove Last', arrayKey: 'items' }`
+  },
+  {
+    type: "shift-array-item",
+    category: "button",
+    description: "Button to remove the first item from an array field. (Legacy alias: shiftArrayItem.)",
+    valueType: void 0,
+    baseInterface: "FieldDef",
+    props: {},
+    validationSupported: false,
+    source: "adapter",
+    allowedIn: ["array", "row", "group"],
+    example: `{
+  key: 'shiftContact',
+  type: 'shift-array-item',
+  label: 'Remove First',
+  arrayKey: 'contacts'
+}`,
+    minimalExample: `{ key: 'shift', type: 'shift-array-item', label: 'Remove First', arrayKey: 'items' }`
   }
 ];
 
@@ -1470,7 +1541,7 @@ var WRAPPERS = [
     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.',
+    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 `add-array-item` 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",
@@ -2858,6 +2929,8 @@ Evaluates a JavaScript expression with access to \`formValue\`, \`fieldValue\`,
 }
 \`\`\`
 
+**Condition scoping:** in logic conditions, \`formValue\` is the whole form value regardless of where the field sits, except inside array items where it is scoped to the current item (use \`rootFormValue\` for the rest of the form). Reference group-nested fields by their full path, e.g. \`formValue.person.firstName\`. Note that \`derivation\` expressions scope differently: there \`formValue\` is also scoped to the parent group for group-nested fields.
+
 #### Custom Condition
 
 Invokes a registered custom function by name:
@@ -3035,7 +3108,7 @@ All features are exported from \`@ng-forge/dynamic-forms\`.
 
 ## CRITICAL: UI Library Differences
 
-Different UI libraries support different properties. Always validate against the correct library using \`ngforge_validate_form_config\` with the appropriate \`uiIntegration\` parameter.
+Different UI libraries support different properties. Always validate against the correct library using \`ngforge_validate\` with the appropriate \`uiIntegration\` parameter.
 
 ### Property Differences by Library
 
@@ -3078,24 +3151,24 @@ Container fields (\`page\`, \`group\`, \`row\`) do NOT support these properties:
    { key: 'volume', type: 'slider', label: 'Volume', min: 0, max: 100 }
    \`\`\`
 
-5. **Using unsupported field types** - Each UI library supports specific field types. Use \`ngforge_get_field_schema\` to see available types.
+5. **Using unsupported field types** - Each UI library supports specific field types. Use \`ngforge_lookup\` with \`depth: "schema"\` to see available types.
 
 ## Validation Before Use
 
-Always validate your FormConfig using the \`ngforge_validate_form_config\` tool before using it. This tool uses the actual TypeScript/Zod schemas, so if validation passes, the config will work correctly at runtime.
+Always validate your FormConfig using the \`ngforge_validate\` tool before using it. This tool uses the actual TypeScript/Zod schemas, so if validation passes, the config will work correctly at runtime.
 
 \`\`\`typescript
 // Always specify the UI integration you're using
-ngforge_validate_form_config({
+ngforge_validate({
   uiIntegration: 'material',  // or 'bootstrap', 'primeng', 'ionic'
   config: { fields: [...] }
 })
 \`\`\`
 
-To understand what properties are supported for each field type, use \`ngforge_get_field_schema\`:
+To understand what properties are supported for each field type, use \`ngforge_lookup\` with \`depth: "schema"\`:
 
 \`\`\`typescript
-ngforge_get_field_schema({ uiIntegration: 'material' })
+ngforge_lookup({ topic: 'input', depth: 'schema', uiIntegration: 'material' })
 \`\`\`
 `;
 
@@ -5211,7 +5284,7 @@ var MatPreviousButtonFieldSchema = BaseFieldDefSchema.extend({
   props: MatButtonPropsSchema.optional()
 });
 var MatAddArrayItemButtonFieldSchema = BaseFieldDefSchema.extend({
-  type: z33.literal("addArrayItem"),
+  type: z33.literal("add-array-item"),
   /**
    * Key of the array field to add items to.
    * If omitted, uses the parent array context.
@@ -5220,7 +5293,7 @@ var MatAddArrayItemButtonFieldSchema = BaseFieldDefSchema.extend({
   props: MatButtonPropsSchema.optional()
 });
 var MatRemoveArrayItemButtonFieldSchema = BaseFieldDefSchema.extend({
-  type: z33.literal("removeArrayItem"),
+  type: z33.literal("remove-array-item"),
   /**
    * Key of the array field to remove items from.
    * If omitted, uses the parent array context.
@@ -5228,6 +5301,44 @@ var MatRemoveArrayItemButtonFieldSchema = BaseFieldDefSchema.extend({
   arrayKey: z33.string().optional(),
   props: MatButtonPropsSchema.optional()
 });
+var MatPrependArrayItemButtonFieldSchema = BaseFieldDefSchema.extend({
+  type: z33.literal("prepend-array-item"),
+  /**
+   * Key of the array field to prepend items to.
+   * If omitted, uses the parent array context.
+   */
+  arrayKey: z33.string().optional(),
+  props: MatButtonPropsSchema.optional()
+});
+var MatInsertArrayItemButtonFieldSchema = BaseFieldDefSchema.extend({
+  type: z33.literal("insert-array-item"),
+  /**
+   * Key of the array field to insert items into.
+   * If omitted, uses the parent array context.
+   */
+  arrayKey: z33.string().optional(),
+  /**
+   * Index at which to insert the new item.
+   */
+  index: z33.number(),
+  props: MatButtonPropsSchema.optional()
+});
+var MatPopArrayItemButtonFieldSchema = BaseFieldDefSchema.extend({
+  type: z33.literal("pop-array-item"),
+  /**
+   * Key of the array field to pop items from.
+   */
+  arrayKey: z33.string(),
+  props: MatButtonPropsSchema.optional()
+});
+var MatShiftArrayItemButtonFieldSchema = BaseFieldDefSchema.extend({
+  type: z33.literal("shift-array-item"),
+  /**
+   * Key of the array field to shift items from.
+   */
+  arrayKey: z33.string(),
+  props: MatButtonPropsSchema.optional()
+});
 
 // internal/dynamic-forms-zod/material/src/mat-leaf-field.schema.ts
 import { z as z36 } from "zod";
@@ -5303,7 +5414,11 @@ var MatLeafFieldSchema = z36.discriminatedUnion("type", [
   MatNextButtonFieldSchema,
   MatPreviousButtonFieldSchema,
   MatAddArrayItemButtonFieldSchema,
-  MatRemoveArrayItemButtonFieldSchema
+  MatRemoveArrayItemButtonFieldSchema,
+  MatPrependArrayItemButtonFieldSchema,
+  MatInsertArrayItemButtonFieldSchema,
+  MatPopArrayItemButtonFieldSchema,
+  MatShiftArrayItemButtonFieldSchema
 ]).superRefine(nullableValueRefine);
 
 // internal/dynamic-forms-zod/src/lib/schemas/containers/factories.ts
@@ -5771,15 +5886,36 @@ var BsPreviousButtonFieldSchema = BaseFieldDefSchema.extend({
   props: BsButtonPropsSchema.optional()
 });
 var BsAddArrayItemButtonFieldSchema = BaseFieldDefSchema.extend({
-  type: z44.literal("addArrayItem"),
+  type: z44.literal("add-array-item"),
   arrayKey: z44.string().optional(),
   props: BsButtonPropsSchema.optional()
 });
 var BsRemoveArrayItemButtonFieldSchema = BaseFieldDefSchema.extend({
-  type: z44.literal("removeArrayItem"),
+  type: z44.literal("remove-array-item"),
   arrayKey: z44.string().optional(),
   props: BsButtonPropsSchema.optional()
 });
+var BsPrependArrayItemButtonFieldSchema = BaseFieldDefSchema.extend({
+  type: z44.literal("prepend-array-item"),
+  arrayKey: z44.string().optional(),
+  props: BsButtonPropsSchema.optional()
+});
+var BsInsertArrayItemButtonFieldSchema = BaseFieldDefSchema.extend({
+  type: z44.literal("insert-array-item"),
+  arrayKey: z44.string().optional(),
+  index: z44.number(),
+  props: BsButtonPropsSchema.optional()
+});
+var BsPopArrayItemButtonFieldSchema = BaseFieldDefSchema.extend({
+  type: z44.literal("pop-array-item"),
+  arrayKey: z44.string(),
+  props: BsButtonPropsSchema.optional()
+});
+var BsShiftArrayItemButtonFieldSchema = BaseFieldDefSchema.extend({
+  type: z44.literal("shift-array-item"),
+  arrayKey: z44.string(),
+  props: BsButtonPropsSchema.optional()
+});
 
 // internal/dynamic-forms-zod/bootstrap/src/bs-leaf-field.schema.ts
 import { z as z45 } from "zod";
@@ -5800,7 +5936,11 @@ var BsLeafFieldSchema = z45.discriminatedUnion("type", [
   BsNextButtonFieldSchema,
   BsPreviousButtonFieldSchema,
   BsAddArrayItemButtonFieldSchema,
-  BsRemoveArrayItemButtonFieldSchema
+  BsRemoveArrayItemButtonFieldSchema,
+  BsPrependArrayItemButtonFieldSchema,
+  BsInsertArrayItemButtonFieldSchema,
+  BsPopArrayItemButtonFieldSchema,
+  BsShiftArrayItemButtonFieldSchema
 ]).superRefine(nullableValueRefine);
 
 // internal/dynamic-forms-zod/bootstrap/src/bs-form-config.schema.ts
@@ -5983,15 +6123,36 @@ var PrimePreviousButtonFieldSchema = BaseFieldDefSchema.extend({
   props: PrimeButtonPropsSchema.optional()
 });
 var PrimeAddArrayItemButtonFieldSchema = BaseFieldDefSchema.extend({
-  type: z48.literal("addArrayItem"),
+  type: z48.literal("add-array-item"),
   arrayKey: z48.string().optional(),
   props: PrimeButtonPropsSchema.optional()
 });
 var PrimeRemoveArrayItemButtonFieldSchema = BaseFieldDefSchema.extend({
-  type: z48.literal("removeArrayItem"),
+  type: z48.literal("remove-array-item"),
+  arrayKey: z48.string().optional(),
+  props: PrimeButtonPropsSchema.optional()
+});
+var PrimePrependArrayItemButtonFieldSchema = BaseFieldDefSchema.extend({
+  type: z48.literal("prepend-array-item"),
   arrayKey: z48.string().optional(),
   props: PrimeButtonPropsSchema.optional()
 });
+var PrimeInsertArrayItemButtonFieldSchema = BaseFieldDefSchema.extend({
+  type: z48.literal("insert-array-item"),
+  arrayKey: z48.string().optional(),
+  index: z48.number(),
+  props: PrimeButtonPropsSchema.optional()
+});
+var PrimePopArrayItemButtonFieldSchema = BaseFieldDefSchema.extend({
+  type: z48.literal("pop-array-item"),
+  arrayKey: z48.string(),
+  props: PrimeButtonPropsSchema.optional()
+});
+var PrimeShiftArrayItemButtonFieldSchema = BaseFieldDefSchema.extend({
+  type: z48.literal("shift-array-item"),
+  arrayKey: z48.string(),
+  props: PrimeButtonPropsSchema.optional()
+});
 
 // internal/dynamic-forms-zod/primeng/src/prime-leaf-field.schema.ts
 import { z as z49 } from "zod";
@@ -6012,7 +6173,11 @@ var PrimeLeafFieldSchema = z49.discriminatedUnion("type", [
   PrimeNextButtonFieldSchema,
   PrimePreviousButtonFieldSchema,
   PrimeAddArrayItemButtonFieldSchema,
-  PrimeRemoveArrayItemButtonFieldSchema
+  PrimeRemoveArrayItemButtonFieldSchema,
+  PrimePrependArrayItemButtonFieldSchema,
+  PrimeInsertArrayItemButtonFieldSchema,
+  PrimePopArrayItemButtonFieldSchema,
+  PrimeShiftArrayItemButtonFieldSchema
 ]).superRefine(nullableValueRefine);
 
 // internal/dynamic-forms-zod/primeng/src/prime-form-config.schema.ts
@@ -6237,13 +6402,34 @@ var IonicPreviousButtonFieldSchema = BaseFieldDefSchema.extend({
   props: IonicButtonPropsSchema.optional()
 });
 var IonicAddArrayItemButtonFieldSchema = BaseFieldDefSchema.extend({
-  type: z52.literal("addArrayItem"),
+  type: z52.literal("add-array-item"),
   arrayKey: z52.string().optional(),
   props: IonicButtonPropsSchema.optional()
 });
 var IonicRemoveArrayItemButtonFieldSchema = BaseFieldDefSchema.extend({
-  type: z52.literal("removeArrayItem"),
+  type: z52.literal("remove-array-item"),
+  arrayKey: z52.string().optional(),
+  props: IonicButtonPropsSchema.optional()
+});
+var IonicPrependArrayItemButtonFieldSchema = BaseFieldDefSchema.extend({
+  type: z52.literal("prepend-array-item"),
+  arrayKey: z52.string().optional(),
+  props: IonicButtonPropsSchema.optional()
+});
+var IonicInsertArrayItemButtonFieldSchema = BaseFieldDefSchema.extend({
+  type: z52.literal("insert-array-item"),
   arrayKey: z52.string().optional(),
+  index: z52.number(),
+  props: IonicButtonPropsSchema.optional()
+});
+var IonicPopArrayItemButtonFieldSchema = BaseFieldDefSchema.extend({
+  type: z52.literal("pop-array-item"),
+  arrayKey: z52.string(),
+  props: IonicButtonPropsSchema.optional()
+});
+var IonicShiftArrayItemButtonFieldSchema = BaseFieldDefSchema.extend({
+  type: z52.literal("shift-array-item"),
+  arrayKey: z52.string(),
   props: IonicButtonPropsSchema.optional()
 });
 
@@ -6266,7 +6452,11 @@ var IonicLeafFieldSchema = z53.discriminatedUnion("type", [
   IonicNextButtonFieldSchema,
   IonicPreviousButtonFieldSchema,
   IonicAddArrayItemButtonFieldSchema,
-  IonicRemoveArrayItemButtonFieldSchema
+  IonicRemoveArrayItemButtonFieldSchema,
+  IonicPrependArrayItemButtonFieldSchema,
+  IonicInsertArrayItemButtonFieldSchema,
+  IonicPopArrayItemButtonFieldSchema,
+  IonicShiftArrayItemButtonFieldSchema
 ]).superRefine(nullableValueRefine);
 
 // internal/dynamic-forms-zod/ionic/src/ionic-form-config.schema.ts
@@ -6652,8 +6842,12 @@ var NESTING_RULES = {
       "submit",
       "next",
       "previous",
-      "addArrayItem",
-      "removeArrayItem"
+      "add-array-item",
+      "prepend-array-item",
+      "insert-array-item",
+      "remove-array-item",
+      "pop-array-item",
+      "shift-array-item"
     ],
     forbidden: ["page"],
     message: "Pages cannot be nested inside other containers. ALL top-level fields must be pages if using multi-page mode."
@@ -6676,8 +6870,12 @@ var NESTING_RULES = {
       "submit",
       "next",
       "previous",
-      "addArrayItem",
-      "removeArrayItem"
+      "add-array-item",
+      "prepend-array-item",
+      "insert-array-item",
+      "remove-array-item",
+      "pop-array-item",
+      "shift-array-item"
     ],
     forbidden: ["page", "row", "hidden"],
     message: "Rows cannot contain pages, other rows, or hidden fields. Hidden fields should be at page or form level."
@@ -6700,8 +6898,12 @@ var NESTING_RULES = {
       "submit",
       "next",
       "previous",
-      "addArrayItem",
-      "removeArrayItem"
+      "add-array-item",
+      "prepend-array-item",
+      "insert-array-item",
+      "remove-array-item",
+      "pop-array-item",
+      "shift-array-item"
     ],
     forbidden: ["page", "group"],
     message: "Groups cannot contain pages or other groups (no nested groups)."
@@ -6725,8 +6927,12 @@ var NESTING_RULES = {
       "submit",
       "next",
       "previous",
-      "addArrayItem",
-      "removeArrayItem"
+      "add-array-item",
+      "prepend-array-item",
+      "insert-array-item",
+      "remove-array-item",
+      "pop-array-item",
+      "shift-array-item"
     ],
     forbidden: ["page", "array"],
     message: "Arrays cannot contain pages or other arrays (no nested arrays)."
@@ -6972,6 +7178,27 @@ function preValidateConfig(config) {
   });
   return errors;
 }
+var LEGACY_ARRAY_ACTION_TYPES = {
+  addArrayItem: "add-array-item",
+  prependArrayItem: "prepend-array-item",
+  insertArrayItem: "insert-array-item",
+  removeArrayItem: "remove-array-item",
+  popArrayItem: "pop-array-item",
+  shiftArrayItem: "shift-array-item"
+};
+function normalizeLegacyArrayActionTypes(value) {
+  if (Array.isArray(value)) {
+    return value.map(normalizeLegacyArrayActionTypes);
+  }
+  if (value && typeof value === "object") {
+    const out = {};
+    for (const [key, val] of Object.entries(value)) {
+      out[key] = key === "type" && typeof val === "string" && LEGACY_ARRAY_ACTION_TYPES[val] ? LEGACY_ARRAY_ACTION_TYPES[val] : normalizeLegacyArrayActionTypes(val);
+    }
+    return out;
+  }
+  return value;
+}
 function validateFormConfig(uiIntegration, config) {
   const schema = formConfigSchemas2[uiIntegration];
   if (!schema) {
@@ -6986,15 +7213,16 @@ function validateFormConfig(uiIntegration, config) {
       errorSummary: `Unknown UI integration: ${uiIntegration}`
     };
   }
-  const preErrors = preValidateConfig(config);
-  const result = schema.safeParse(config);
+  const normalizedConfig = normalizeLegacyArrayActionTypes(config);
+  const preErrors = preValidateConfig(normalizedConfig);
+  const result = schema.safeParse(normalizedConfig);
   if (result.success && preErrors.length === 0) {
     return {
       valid: true,
       data: result.data
     };
   }
-  const zodErrors = result.success ? [] : formatZodError(result.error, config);
+  const zodErrors = result.success ? [] : formatZodError(result.error, normalizedConfig);
   const allErrors = [...preErrors, ...zodErrors];
   return {
     valid: false,
@@ -7024,29 +7252,32 @@ ${UI_INTEGRATIONS.map((ui) => `- ${ui}`).join("\n")}
 ## Field Types
 ${fieldTypes.map((ft) => `- ${ft}`).join("\n")}
 
-## Tools (4 total - consolidated)
+## Tools (5 total - consolidated)
 
-**1. START HERE - One-shot reference:**
-\`ngforge_get_cheatsheet(uiIntegration?)\`
+**1. START HERE - Documentation lookup:**
+\`ngforge_lookup(topic, depth?, uiIntegration?)\`
+- topic="workflow" for the recommended tool-usage guide
 - Property placement rules, condition syntax, copy-paste patterns, common errors
-- Component API (template binding, event names)
-- **Use this first** - it has 90% of what you need in one call
+- depth="brief|full|schema" (default full); uiIntegration filters schema output
 
-**2. Validation:**
-\`ngforge_validate_form_config(uiIntegration, config)\`
+**2. Search:**
+\`ngforge_search(query)\`
+- Free-text keyword search across all topics and examples
+- Use when you don't know the exact topic name
+
+**3. Validation:**
+\`ngforge_validate(config, uiIntegration?)\`
 - Validates config against actual TypeScript types
 - Catches errors before runtime
 
-**3. Field info + schema:**
-\`ngforge_get_field_info(fieldType?, uiIntegration?, includeSchema?)\`
-- Properties, validators, and examples for a specific field type
-- Set includeSchema=true for JSON Schema (machine-readable)
-
-**4. Examples + deep explanations:**
-\`ngforge_get_example(pattern?, depth?)\`
+**4. Examples:**
+\`ngforge_examples(pattern, depth?)\`
 - Patterns: complete, derivation, conditional, multi-page, validation
-- depth="example" (default) = working code
-- depth="deep" = conceptual explanation + code + edge cases
+- depth controls how much detail (working code vs. deep explanation)
+
+**5. Scaffold:**
+\`ngforge_scaffold(fields?, pages?, arrays?, groups?, hidden?, uiIntegration?)\`
+- Generates a compilable FormConfig skeleton
 `
         }
       ]
@@ -7706,8 +7937,8 @@ interface SimplifiedArrayField {
 
 The simplified API is normalized into the full API at runtime:
 1. Each \`value\` element creates an item using the \`template\` structure
-2. An \`addArrayItem\` button is auto-generated after the array (unless \`addButton: false\`)
-3. A \`removeArrayItem\` button is added to each item (unless \`removeButton: false\`)
+2. An \`add-array-item\` button is auto-generated after the array (unless \`addButton: false\`)
+3. A \`remove-array-item\` button is added to each item (unless \`removeButton: false\`)
 
 ## Conditional Visibility
 
@@ -7921,6 +8152,7 @@ logic: [{ type: 'derivation', functionName: 'computeFromGroup', dependsOn: ['$gr
 \`\`\`
 Derivation is always defined ON the field that receives the computed value (self-targeting).
 \`dependsOn\` paths are absolute from the form root (e.g. \`'address.state'\`). Use \`'$self'\` for the field's own absolute path and \`'$group'\` for its nearest parent group/array \u2014 both useful in factory-built fields where ancestor keys aren't known at config time.
+**Scoping:** in derivation expressions, \`formValue\` is scoped to the parent group for group-nested fields and to the current item inside arrays, so siblings are referenced directly (e.g. \`formValue.firstName\` inside a \`person\` group). Use \`rootFormValue\` to reach fields outside the current scope.
 **Variables:** \`formValue\`, \`fieldValue\`, \`fieldState\`, \`formFieldState\`, \`externalData\` (see topic: expression-variables)
 **For deriving component properties** (minDate, options, label): use \`targetProperty\` (see topic \`property-derivation\`)`,
     full: `# Value Derivation (Computed Fields)
@@ -8282,7 +8514,8 @@ Wrong: Wrong property names
 
 | Variable | Type | Available In | Description |
 |----------|------|--------------|-------------|
-| \`formValue\` | object | Derivations, conditions, custom validators | Complete form values as nested object |
+| \`formValue\` | object | Derivations, conditions, custom validators | Form values as nested object. Scoped to the current array item in array contexts; in derivations additionally scoped to the parent group for group-nested fields. Conditions on group-nested fields see the root form value |
+| \`rootFormValue\` | object | Scoped contexts (array items, group-nested derivations) | The whole form value when \`formValue\` is scoped |
 | \`fieldValue\` | any | Custom validator expressions only | Current field's value |
 | \`fieldState\` | object | Derivations, conditions | Current field's state (touched, dirty, valid, etc.) |
 | \`formFieldState\` | object | Derivations, conditions | All fields' states keyed by field key |
@@ -9460,19 +9693,19 @@ const config = { fields: [...] } as const satisfies FormConfig;
 - Together they give you: type safety + exact type inference`
   },
   "array-buttons": {
-    brief: `**Add:** \`{ type: 'addArrayItem', key: 'add', label: 'Add', arrayKey: 'contacts' }\`
-**Remove:** \`{ type: 'removeArrayItem', key: 'remove', label: 'Remove' }\` (inside array template)
+    brief: `**Add:** \`{ type: 'add-array-item', key: 'add', label: 'Add', arrayKey: 'contacts' }\`
+**Remove:** \`{ type: 'remove-array-item', key: 'remove', label: 'Remove' }\` (inside array template)
 \u26A0\uFE0F arrayKey at FIELD level, NOT in props!`,
     full: `# Array Buttons (Add/Remove Items)
 
-**UI libraries provide \`addArrayItem\` and \`removeArrayItem\` button types.**
+**UI libraries provide \`add-array-item\` and \`remove-array-item\` button types.**
 
 ## Add Item Button
 
 \`\`\`typescript
 {
   key: 'addPhone',
-  type: 'addArrayItem',
+  type: 'add-array-item',
   label: 'Add Phone',
   arrayKey: 'phones',          // \u26A0\uFE0F AT FIELD LEVEL, NOT IN PROPS!
   props: {
@@ -9494,7 +9727,7 @@ const config = { fields: [...] } as const satisfies FormConfig;
       { key: 'number', type: 'input', label: 'Phone Number' },
       {
         key: 'removePhone',
-        type: 'removeArrayItem',
+        type: 'remove-array-item',
         label: 'Remove',
         // arrayKey not needed - inferred from parent array
         props: { color: 'warn' }
@@ -9509,13 +9742,13 @@ const config = { fields: [...] } as const satisfies FormConfig;
 \`\`\`typescript
 // WRONG - arrayKey in props
 {
-  type: 'addArrayItem',
+  type: 'add-array-item',
   props: { arrayKey: 'phones' }  // \u274C WRONG LOCATION
 }
 
 // CORRECT - arrayKey at field level
 {
-  type: 'addArrayItem',
+  type: 'add-array-item',
   arrayKey: 'phones',            // \u2705 CORRECT
   props: { color: 'primary' }
 }
@@ -9784,8 +10017,19 @@ var TOPIC_ALIASES = {
   valueof: "context-api",
   "add-array": "array-buttons",
   "remove-array": "array-buttons",
+  // Array-action field types: kebab-case canonical + camelCase legacy aliases
+  "add-array-item": "array-buttons",
+  "prepend-array-item": "array-buttons",
+  "insert-array-item": "array-buttons",
+  "remove-array-item": "array-buttons",
+  "pop-array-item": "array-buttons",
+  "shift-array-item": "array-buttons",
   addarrayitem: "array-buttons",
+  prependarrayitem: "array-buttons",
+  insertarrayitem: "array-buttons",
   removearrayitem: "array-buttons",
+  poparrayitem: "array-buttons",
+  shiftarrayitem: "array-buttons",
   "custom-validator": "custom-validators",
   customvalidator: "custom-validators",
   mistakes: "pitfalls",
@@ -10830,7 +11074,7 @@ For full control, use the \`fields\`-based API with explicit add/remove buttons:
     ]
   ]
 }
-// + separate addArrayItem button with arrayKey
+// + separate add-array-item button with arrayKey
 \`\`\``,
     explained: `# Array Fields - Complete Explanation
 
@@ -10902,7 +11146,7 @@ For full control, use \`fields\` with explicit item definitions and manual add/r
 // ADD button - place OUTSIDE the array
 {
   key: 'addContact',
-  type: 'addArrayItem',
+  type: 'add-array-item',
   label: 'Add Contact',
   arrayKey: 'contacts',  // \u26A0\uFE0F AT FIELD LEVEL!
 }
@@ -10914,7 +11158,7 @@ For full control, use \`fields\` with explicit item definitions and manual add/r
   fields: [
     [
       { key: 'name', type: 'input', label: 'Name' },
-      { key: 'remove', type: 'removeArrayItem', label: 'Remove' }
+      { key: 'remove', type: 'remove-array-item', label: 'Remove' }
     ]
   ]
 }
@@ -10948,8 +11192,8 @@ expression: '(formValue.items || []).reduce((sum, item) => sum + (item.price ||
 
 \u274C Putting \`arrayKey\` in props (full API):
 \`\`\`typescript
-{ type: 'addArrayItem', props: { arrayKey: 'x' } }  // WRONG
-{ type: 'addArrayItem', arrayKey: 'x' }             // CORRECT
+{ type: 'add-array-item', props: { arrayKey: 'x' } }  // WRONG
+{ type: 'add-array-item', arrayKey: 'x' }             // CORRECT
 \`\`\``
   },
   "minimal-simplified-array": {