Document XML/fluent-API mapping and generic view builder

Rename Expert, More to Beyond Basics

Author: claude

docs/.vitepress/config.mjs

@@ -226,7 +226,7 @@ export default defineConfig({
             ],
           },
           {
-            text: "Expert, More",
+            text: "Beyond Basics",
             link: "/cookbook/expert_more/lock",
             collapsed: true,
             items: [

docs/cookbook/view/definition.md

@@ -52,5 +52,45 @@ Combining controls in a way that violates these rules can lead to broken renderi
 The ABAP compiler cannot catch these mistakes — they are pure UI5 concerns and must be verified against the SDK documentation.
 :::
 
+## Mapping UI5 XML ↔ ABAP Fluent API
+
+`Z2UI5_CL_XML_VIEW` is a hand-curated wrapper around UI5 controls. It does not cover every UI5 control, and the naming is not always a strict 1:1 mapping of the UI5 SDK:
+
+- Control names follow snake_case of the UI5 control class — `sap.m.MultiComboBox` becomes `->multi_combo_box( )`, `sap.m.Text` becomes `->text( )`.
+- Properties are passed as named parameters in snake_case (`enabled`, `placeholder`, `selected_key`).
+- Aggregations are exposed as methods named after the aggregation itself (`->items( )`, `->content( )`, `->custom_data( )`) — not as `add_item( )` / `add_content( )`. Calling the aggregation method returns the parent builder so you can chain children inside it.
+- Coverage is incomplete and occasionally inconsistent: some controls or properties are missing, some method signatures don't match the SDK exactly. When in doubt, check the source of `Z2UI5_CL_XML_VIEW` or fall back to the generic builder below.
+
+### The Fully Generic Builder
+
+Every fluent helper ultimately produces an XML element. The lowest-level method `_generic( name = ... ns = ... )` lets you emit **any** XML element with **any** attributes, regardless of whether `Z2UI5_CL_XML_VIEW` knows the control:
+
+```abap
+  DATA(view) = z2ui5_cl_xml_view=>factory( ).
+
+  view->_generic( name = `Page` ns = `sap.m`
+    )->_generic( name = `MultiComboBox` ns = `sap.m`
+        t_prop = VALUE #(
+          ( n = `selectedKeys` v = `{/keys}` )
+          ( n = `placeholder`  v = `Pick one` )
+        )
+      )->_generic( name = `items` ns = `sap.m`
+        )->_generic( name = `core:Item` ns = `sap.ui.core`
+            t_prop = VALUE #(
+              ( n = `key`  v = `{key}` )
+              ( n = `text` v = `{text}` )
+            ) ).
+
+  client->view_display( view->stringify( ) ).
+```
+
+This maps **1:1** to the UI5 XML/SDK API — control names, property names, and aggregation names are written exactly as they appear in the [UI5 SDK](https://sapui5.hana.ondemand.com), in their original camelCase. There is no abstraction layer guessing what to call things.
+
+::: tip Recommended for AI-assisted Development
+For AI-assisted coding, prefer the generic builder. It removes the need for the model to know the abap2UI5 naming conventions or guess which controls and properties are wrapped — the SDK documentation can be used directly. The fluent API in `Z2UI5_CL_XML_VIEW` is convenient for humans but its inconsistencies and incomplete coverage make it a poor target for code generation.
+:::
+
+The rest of this documentation uses the higher-level fluent API (`->page( )`, `->button( )`, `->multi_combo_box( )`) because it reads better in examples. Both styles can be mixed freely in the same view.
+
 #### Next Steps
 This produces a static view. The next section walks through binding and sharing data between the view and the app logic.