In build.reference, the foreach Binding behavior comes from ForEachBinding. However, the foreach Binding documentation describes the callback behavior provided by TemplateForEachBindingHandler used in build.knockout, resulting the documented API and the actual runtime behavior in the reference build to not fully match.
Problematic behavior
ForEachBinding is only partially compatible with the callback API described for the foreach Binding:
afterRender is not supported by ForEachBindingbeforeMove is not supported by ForEachBindingafterMove is not supported by ForEachBindingafterAdd exists in ForEachBinding, but uses a different callback contract than TemplateForEachBindingHandlerbeforeRemove exists in ForEachBinding, but also uses a different callback contract than TemplateForEachBindingHandler
Expected behavior
The behavior of foreach in build.reference should be aligned with one of these expectations:
ForEachBinding should support the same documented callback API as TemplateForEachBindingHandler, or- the
foreach Binding documentation should clearly distinguish between the callback behavior of ForEachBinding and TemplateForEachBindingHandler
Why this is a problem
This creates a silent compatibility gap between the documented foreach API and the actual behavior of ForEachBinding in the reference build. Rendering may still work, but lifecycle hooks such as afterRender do not run, and callbacks such as afterAdd and beforeRemove are invoked with a different signature than the one described in the documentation.
Suggested clarification
Please clarify whether the different callback behavior of ForEachBinding is intentional. If it is intentional, the documentation should explicitly document the differences from TemplateForEachBindingHandler. If it is not intentional, ForEachBinding should be brought closer to the documented foreach callback behavior.
In build.reference, the
foreachBinding behavior comes fromForEachBinding. However, theforeachBinding documentation describes the callback behavior provided byTemplateForEachBindingHandlerused in build.knockout, resulting the documented API and the actual runtime behavior in the reference build to not fully match.Problematic behavior
ForEachBindingis only partially compatible with the callback API described for theforeachBinding:afterRenderis not supported byForEachBindingbeforeMoveis not supported byForEachBindingafterMoveis not supported byForEachBindingafterAddexists inForEachBinding, but uses a different callback contract thanTemplateForEachBindingHandlerbeforeRemoveexists inForEachBinding, but also uses a different callback contract thanTemplateForEachBindingHandlerExpected behavior
The behavior of
foreachin build.reference should be aligned with one of these expectations:ForEachBindingshould support the same documented callback API asTemplateForEachBindingHandler, orforeachBinding documentation should clearly distinguish between the callback behavior ofForEachBindingandTemplateForEachBindingHandlerWhy this is a problem
This creates a silent compatibility gap between the documented
foreachAPI and the actual behavior ofForEachBindingin the reference build. Rendering may still work, but lifecycle hooks such asafterRenderdo not run, and callbacks such asafterAddandbeforeRemoveare invoked with a different signature than the one described in the documentation.Suggested clarification
Please clarify whether the different callback behavior of
ForEachBindingis intentional. If it is intentional, the documentation should explicitly document the differences fromTemplateForEachBindingHandler. If it is not intentional,ForEachBindingshould be brought closer to the documentedforeachcallback behavior.