@ng-forge/dynamic-form-mcp 0.8.0-next.4 → 0.8.0-next.5

package/bin/ng-forge-mcp.js

@@ -333,17 +333,20 @@ var FIELD_TYPES = [
       fields: {
         name: "fields",
         type: "RowAllowedChildren[]",
-        description: "Child fields to render horizontally. Allowed: groups, arrays, VALUE fields (input, select, etc). NOT ALLOWED: pages, rows, hidden fields",
+        description: "Child fields to render horizontally. Allowed: groups, arrays, containers, nested rows, hidden fields, and value fields (input, select, etc). NOT ALLOWED: pages",
         required: true
       }
     },
     validationSupported: false,
     source: "core",
-    allowedIn: ["top-level", "page", "group", "array"],
-    notAllowedIn: ["row"],
+    allowedIn: ["top-level", "page", "group", "array", "row", "container"],
+    notAllowedIn: [],
     canContain: [
       "group",
       "array",
+      "container",
+      "row",
+      "hidden",
       "input",
       "textarea",
       "select",
@@ -359,7 +362,7 @@ var FIELD_TYPES = [
       "next",
       "previous"
     ],
-    cannotContain: ["page", "row", "hidden"],
+    cannotContain: ["page"],
     example: `{
   key: 'nameRow',
   type: 'row',
@@ -371,9 +374,7 @@ var FIELD_TYPES = [
   ]
 }
 // NOT ALLOWED in rows:
-// - type: 'hidden' (hidden fields cannot be inside rows)
-// - type: 'page' (pages are top-level only)
-// - type: 'row' (no nested rows)`,
+// - type: 'page' (pages are top-level only)`,
     minimalExample: `{ key: 'row1', type: 'row', fields: [...] }`
   },
   {
@@ -6933,10 +6934,8 @@ Included in form value but not rendered.
 
 Use \`col\` (1-12) on child fields for grid width. Row is purely for layout. Supports only \`hidden\` logic type for conditional visibility.
 
-**Allowed children:** groups, arrays, value fields (input, select, checkbox, etc.)
-**NOT allowed:** \`hidden\` fields, \`page\` containers, nested \`row\` containers
-
-\u26A0\uFE0F **Common mistake:** Putting hidden fields inside rows - hidden fields should be at page or form level, not in rows.`
+**Allowed children:** groups, arrays, containers, nested rows, hidden fields, value fields (input, select, checkbox, etc.)
+**NOT allowed:** \`page\` containers`
   },
   array: {
     brief: `**Two APIs available:**
@@ -7352,8 +7351,15 @@ logic: [{ type: 'derivation', expression: '...', stopOnUserOverride: true, reEng
 
 // HTTP derivation (server-driven values)
 logic: [{ type: 'derivation', source: 'http', http: { url: '/api/rate', queryParams: { from: 'formValue.currency' } }, responseExpression: 'response.rate', dependsOn: ['currency'] }]
+
+// Self-dependency token: $self resolves to the field's own absolute path at collection time
+logic: [{ type: 'derivation', functionName: 'uppercase', dependsOn: ['$self'] }]
+
+// Parent-container token: $group resolves to the field's nearest parent group/array path
+logic: [{ type: 'derivation', functionName: 'computeFromGroup', dependsOn: ['$group'] }]
 \`\`\`
 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.
 **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)
@@ -7417,6 +7423,98 @@ Derivations are always defined ON the field that receives the computed value (se
 }
 \`\`\`
 
+## \`dependsOn\` Path Resolution
+
+\`dependsOn\` paths are **absolute from the form root**, dotted notation. A field nested under a group has the group's key in its path:
+
+\`\`\`typescript
+{
+  type: 'group', key: 'address',
+  fields: [
+    { key: 'state', type: 'input', logic: [{
+      type: 'derivation',
+      functionName: 'uppercaseState',
+      dependsOn: ['address.state']  // absolute path from root
+    }]}
+  ]
+}
+\`\`\`
+
+Layout containers (\`page\`, \`row\`, \`container\`) do **not** contribute to the path \u2014 only \`group\` fields do. Array fields use the \`'arrayKey.$.fieldKey'\` placeholder convention.
+
+### \`$self\` token
+
+Use \`'$self'\` in \`dependsOn\` to refer to the field's own absolute path. Useful for self-derivations on fields built by factory helpers, where the ancestor group keys aren't known at config-authoring time:
+
+\`\`\`typescript
+{
+  type: 'group', key: 'address',
+  fields: [
+    { key: 'state', type: 'input', logic: [{
+      type: 'derivation',
+      functionName: 'uppercaseState',
+      dependsOn: ['$self']  // resolves to 'address.state' at collection time
+    }]}
+  ]
+}
+\`\`\`
+
+\`$self\` works alongside other absolute deps and inside arrays (resolves to the array placeholder form, e.g. \`'items.$.name'\`).
+
+### \`$group\` token
+
+Use \`'$group'\` in \`dependsOn\` to refer to the field's **nearest parent container** (group or array). The derivation fires whenever any sibling under the same parent changes \u2014 handy when you don't want to enumerate each sibling explicitly:
+
+\`\`\`typescript
+{
+  type: 'group', key: 'address',
+  fields: [
+    { key: 'country', type: 'input' },
+    { key: 'state', type: 'input', logic: [{
+      type: 'derivation',
+      functionName: 'pickStateFromCountry',
+      dependsOn: ['$group']  // resolves to 'address' at collection time
+    }]}
+  ]
+}
+\`\`\`
+
+Resolution rules:
+- Inside group(s) only \u2192 the dotted ancestor group path (\`'address'\` or \`'org.address'\`).
+- Directly inside an array \u2192 the array key (\`'items'\`). Fires on any item change.
+- Inside group(s) inside an array \u2192 \`'items.$.address'\` form.
+- At form root \u2192 throws \`DynamicFormError\` (no parent container exists).
+
+### Token prefix substitution
+
+Both \`$self\` and \`$group\` accept a dotted suffix that is appended to the resolved path:
+
+\`\`\`typescript
+dependsOn: ['$group.country']  // resolves to 'address.country' inside group 'address'
+dependsOn: ['$group.contact.email']  // multi-segment suffix supported
+dependsOn: ['$self.flag']  // resolves to '<fieldKey>.flag' (object-valued fields)
+\`\`\`
+
+Use this to target a specific sibling without naming the parent group key \u2014 handy in factory-built field shapes.
+
+### \`groupValue\` in evaluation context
+
+Custom derivation functions and expressions receive a \`groupValue\` on the \`EvaluationContext\` that mirrors the \`$group\` token at evaluation time:
+
+\`\`\`typescript
+deriveStateFromCountry: (ctx) => {
+  const country = ctx.groupValue?.country;  // no need to know the parent key
+  return country === 'usa' ? 'NY' : '';
+}
+\`\`\`
+
+Population rules:
+- Inside a group: the parent group's value object.
+- Inside nested groups: the innermost parent group's value.
+- Directly inside an array item (no inner group): the array item itself (same as \`formValue\` in array context).
+- Inside a group inside an array item: the inner group's value within the item.
+- Field at form root: \`undefined\`.
+
 ## HTTP Derivation (Server-Driven Values)
 
 Fetch derived values from an HTTP endpoint. Requires \`dependsOn\` (explicit) and \`responseExpression\`.
@@ -8221,7 +8319,7 @@ provideDynamicForm({
 | page | NO | hidden only | Nav buttons INSIDE |
 | group | NO | hidden only | Creates nested object |
 | array | NO | hidden only | Two APIs: \`template\`+\`value\` (simplified) or \`fields\` (full) |
-| row | NO | hidden only | Layout only, no hidden fields |`,
+| row | NO | hidden only | Layout only |`,
     full: `# Container Rules
 
 | Container | Label? | Logic? | Allowed Children | Notes |
@@ -8229,17 +8327,16 @@ provideDynamicForm({
 | page | NO | YES (hidden only) | rows, groups, arrays, leaf fields, buttons | Nav buttons go INSIDE |
 | group | NO | YES (hidden only) | rows, leaf fields (NOT pages, groups) | Creates nested object |
 | array | NO | YES (hidden only) | rows, groups, leaf fields (NOT pages, arrays) | Two APIs: \`template\`+\`value\` (simplified) or \`fields\` (full) |
-| row | NO | YES (hidden only) | groups, arrays, leaf fields (NOT hidden, pages, rows) | Layout only |
+| row | NO | YES (hidden only) | groups, arrays, containers, nested rows, hidden fields, leaf fields (NOT pages) | Layout only |
 
 **CRITICAL:**
 - All containers (page, group, row, array) support only the \`hidden\` logic type for conditional visibility.
 - For other logic types (disabled, required, readonly, derivation), apply them to child fields instead.
-- Hidden fields cannot be inside rows - place them at page/form level.
 - Pages cannot be nested - ALL top-level fields must be pages if using multi-page mode.`
   },
   "field-placement": {
     brief: `**Multi-page:** ALL root fields must be pages. Hidden fields go INSIDE first page.
-**Rows:** NO hidden fields, NO nested rows, NO pages
+**Rows:** NO pages
 **Groups:** NO nested groups, NO pages`,
     full: `# Field Placement Rules
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ng-forge/dynamic-form-mcp",
-  "version": "0.8.0-next.4",
+  "version": "0.8.0-next.5",
   "description": "MCP server for ng-forge dynamic forms - AI-assisted form schema generation",
   "type": "module",
   "license": "MIT",
@@ -51,11 +51,11 @@
     "zod": "^3.25.76"
   },
   "devDependencies": {
-    "@ng-forge/dynamic-forms": "^0.8.0-next.4",
-    "@ng-forge/dynamic-forms-bootstrap": "^0.8.0-next.4",
-    "@ng-forge/dynamic-forms-ionic": "^0.8.0-next.4",
-    "@ng-forge/dynamic-forms-material": "^0.8.0-next.4",
-    "@ng-forge/dynamic-forms-primeng": "^0.8.0-next.4",
+    "@ng-forge/dynamic-forms": "^0.8.0-next.5",
+    "@ng-forge/dynamic-forms-bootstrap": "^0.8.0-next.5",
+    "@ng-forge/dynamic-forms-ionic": "^0.8.0-next.5",
+    "@ng-forge/dynamic-forms-material": "^0.8.0-next.5",
+    "@ng-forge/dynamic-forms-primeng": "^0.8.0-next.5",
     "tsx": "^4.19.0"
   }
 }

package/src/index.js

@@ -331,17 +331,20 @@ var FIELD_TYPES = [
       fields: {
         name: "fields",
         type: "RowAllowedChildren[]",
-        description: "Child fields to render horizontally. Allowed: groups, arrays, VALUE fields (input, select, etc). NOT ALLOWED: pages, rows, hidden fields",
+        description: "Child fields to render horizontally. Allowed: groups, arrays, containers, nested rows, hidden fields, and value fields (input, select, etc). NOT ALLOWED: pages",
         required: true
       }
     },
     validationSupported: false,
     source: "core",
-    allowedIn: ["top-level", "page", "group", "array"],
-    notAllowedIn: ["row"],
+    allowedIn: ["top-level", "page", "group", "array", "row", "container"],
+    notAllowedIn: [],
     canContain: [
       "group",
       "array",
+      "container",
+      "row",
+      "hidden",
       "input",
       "textarea",
       "select",
@@ -357,7 +360,7 @@ var FIELD_TYPES = [
       "next",
       "previous"
     ],
-    cannotContain: ["page", "row", "hidden"],
+    cannotContain: ["page"],
     example: `{
   key: 'nameRow',
   type: 'row',
@@ -369,9 +372,7 @@ var FIELD_TYPES = [
   ]
 }
 // NOT ALLOWED in rows:
-// - type: 'hidden' (hidden fields cannot be inside rows)
-// - type: 'page' (pages are top-level only)
-// - type: 'row' (no nested rows)`,
+// - type: 'page' (pages are top-level only)`,
     minimalExample: `{ key: 'row1', type: 'row', fields: [...] }`
   },
   {
@@ -6982,10 +6983,8 @@ Included in form value but not rendered.
 
 Use \`col\` (1-12) on child fields for grid width. Row is purely for layout. Supports only \`hidden\` logic type for conditional visibility.
 
-**Allowed children:** groups, arrays, value fields (input, select, checkbox, etc.)
-**NOT allowed:** \`hidden\` fields, \`page\` containers, nested \`row\` containers
-
-\u26A0\uFE0F **Common mistake:** Putting hidden fields inside rows - hidden fields should be at page or form level, not in rows.`
+**Allowed children:** groups, arrays, containers, nested rows, hidden fields, value fields (input, select, checkbox, etc.)
+**NOT allowed:** \`page\` containers`
   },
   array: {
     brief: `**Two APIs available:**
@@ -7401,8 +7400,15 @@ logic: [{ type: 'derivation', expression: '...', stopOnUserOverride: true, reEng
 
 // HTTP derivation (server-driven values)
 logic: [{ type: 'derivation', source: 'http', http: { url: '/api/rate', queryParams: { from: 'formValue.currency' } }, responseExpression: 'response.rate', dependsOn: ['currency'] }]
+
+// Self-dependency token: $self resolves to the field's own absolute path at collection time
+logic: [{ type: 'derivation', functionName: 'uppercase', dependsOn: ['$self'] }]
+
+// Parent-container token: $group resolves to the field's nearest parent group/array path
+logic: [{ type: 'derivation', functionName: 'computeFromGroup', dependsOn: ['$group'] }]
 \`\`\`
 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.
 **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)
@@ -7466,6 +7472,98 @@ Derivations are always defined ON the field that receives the computed value (se
 }
 \`\`\`
 
+## \`dependsOn\` Path Resolution
+
+\`dependsOn\` paths are **absolute from the form root**, dotted notation. A field nested under a group has the group's key in its path:
+
+\`\`\`typescript
+{
+  type: 'group', key: 'address',
+  fields: [
+    { key: 'state', type: 'input', logic: [{
+      type: 'derivation',
+      functionName: 'uppercaseState',
+      dependsOn: ['address.state']  // absolute path from root
+    }]}
+  ]
+}
+\`\`\`
+
+Layout containers (\`page\`, \`row\`, \`container\`) do **not** contribute to the path \u2014 only \`group\` fields do. Array fields use the \`'arrayKey.$.fieldKey'\` placeholder convention.
+
+### \`$self\` token
+
+Use \`'$self'\` in \`dependsOn\` to refer to the field's own absolute path. Useful for self-derivations on fields built by factory helpers, where the ancestor group keys aren't known at config-authoring time:
+
+\`\`\`typescript
+{
+  type: 'group', key: 'address',
+  fields: [
+    { key: 'state', type: 'input', logic: [{
+      type: 'derivation',
+      functionName: 'uppercaseState',
+      dependsOn: ['$self']  // resolves to 'address.state' at collection time
+    }]}
+  ]
+}
+\`\`\`
+
+\`$self\` works alongside other absolute deps and inside arrays (resolves to the array placeholder form, e.g. \`'items.$.name'\`).
+
+### \`$group\` token
+
+Use \`'$group'\` in \`dependsOn\` to refer to the field's **nearest parent container** (group or array). The derivation fires whenever any sibling under the same parent changes \u2014 handy when you don't want to enumerate each sibling explicitly:
+
+\`\`\`typescript
+{
+  type: 'group', key: 'address',
+  fields: [
+    { key: 'country', type: 'input' },
+    { key: 'state', type: 'input', logic: [{
+      type: 'derivation',
+      functionName: 'pickStateFromCountry',
+      dependsOn: ['$group']  // resolves to 'address' at collection time
+    }]}
+  ]
+}
+\`\`\`
+
+Resolution rules:
+- Inside group(s) only \u2192 the dotted ancestor group path (\`'address'\` or \`'org.address'\`).
+- Directly inside an array \u2192 the array key (\`'items'\`). Fires on any item change.
+- Inside group(s) inside an array \u2192 \`'items.$.address'\` form.
+- At form root \u2192 throws \`DynamicFormError\` (no parent container exists).
+
+### Token prefix substitution
+
+Both \`$self\` and \`$group\` accept a dotted suffix that is appended to the resolved path:
+
+\`\`\`typescript
+dependsOn: ['$group.country']  // resolves to 'address.country' inside group 'address'
+dependsOn: ['$group.contact.email']  // multi-segment suffix supported
+dependsOn: ['$self.flag']  // resolves to '<fieldKey>.flag' (object-valued fields)
+\`\`\`
+
+Use this to target a specific sibling without naming the parent group key \u2014 handy in factory-built field shapes.
+
+### \`groupValue\` in evaluation context
+
+Custom derivation functions and expressions receive a \`groupValue\` on the \`EvaluationContext\` that mirrors the \`$group\` token at evaluation time:
+
+\`\`\`typescript
+deriveStateFromCountry: (ctx) => {
+  const country = ctx.groupValue?.country;  // no need to know the parent key
+  return country === 'usa' ? 'NY' : '';
+}
+\`\`\`
+
+Population rules:
+- Inside a group: the parent group's value object.
+- Inside nested groups: the innermost parent group's value.
+- Directly inside an array item (no inner group): the array item itself (same as \`formValue\` in array context).
+- Inside a group inside an array item: the inner group's value within the item.
+- Field at form root: \`undefined\`.
+
 ## HTTP Derivation (Server-Driven Values)
 
 Fetch derived values from an HTTP endpoint. Requires \`dependsOn\` (explicit) and \`responseExpression\`.
@@ -8270,7 +8368,7 @@ provideDynamicForm({
 | page | NO | hidden only | Nav buttons INSIDE |
 | group | NO | hidden only | Creates nested object |
 | array | NO | hidden only | Two APIs: \`template\`+\`value\` (simplified) or \`fields\` (full) |
-| row | NO | hidden only | Layout only, no hidden fields |`,
+| row | NO | hidden only | Layout only |`,
     full: `# Container Rules
 
 | Container | Label? | Logic? | Allowed Children | Notes |
@@ -8278,17 +8376,16 @@ provideDynamicForm({
 | page | NO | YES (hidden only) | rows, groups, arrays, leaf fields, buttons | Nav buttons go INSIDE |
 | group | NO | YES (hidden only) | rows, leaf fields (NOT pages, groups) | Creates nested object |
 | array | NO | YES (hidden only) | rows, groups, leaf fields (NOT pages, arrays) | Two APIs: \`template\`+\`value\` (simplified) or \`fields\` (full) |
-| row | NO | YES (hidden only) | groups, arrays, leaf fields (NOT hidden, pages, rows) | Layout only |
+| row | NO | YES (hidden only) | groups, arrays, containers, nested rows, hidden fields, leaf fields (NOT pages) | Layout only |
 
 **CRITICAL:**
 - All containers (page, group, row, array) support only the \`hidden\` logic type for conditional visibility.
 - For other logic types (disabled, required, readonly, derivation), apply them to child fields instead.
-- Hidden fields cannot be inside rows - place them at page/form level.
 - Pages cannot be nested - ALL top-level fields must be pages if using multi-page mode.`
   },
   "field-placement": {
     brief: `**Multi-page:** ALL root fields must be pages. Hidden fields go INSIDE first page.
-**Rows:** NO hidden fields, NO nested rows, NO pages
+**Rows:** NO pages
 **Groups:** NO nested groups, NO pages`,
     full: `# Field Placement Rules
 

package/src/registry/field-types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"field-types.d.ts","sourceRoot":"","sources":["../../../../../packages/dynamic-form-mcp/src/registry/field-types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD,eAAO,MAAM,WAAW,EAAE,aAAa,EAqqBtC,CAAC"}
+{"version":3,"file":"field-types.d.ts","sourceRoot":"","sources":["../../../../../packages/dynamic-form-mcp/src/registry/field-types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD,eAAO,MAAM,WAAW,EAAE,aAAa,EAsqBtC,CAAC"}

package/src/tools/data/lookup-topics.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"lookup-topics.d.ts","sourceRoot":"","sources":["../../../../../../packages/dynamic-form-mcp/src/tools/data/lookup-topics.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;GAEG;AACH,eAAO,MAAM,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAq5ElE,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,kBAAkB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAiDrD,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CA4IhD,CAAC"}
+{"version":3,"file":"lookup-topics.d.ts","sourceRoot":"","sources":["../../../../../../packages/dynamic-form-mcp/src/tools/data/lookup-topics.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;GAEG;AACH,eAAO,MAAM,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAq/ElE,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,kBAAkB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAiDrD,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CA4IhD,CAAC"}