Merge pull request #122 from abap2UI5/claude/view-init-navigation-3nfffr

Clarify view re-display behavior on app navigation return

Author: oblomov-dev

docs/advanced/agent.md

@@ -55,14 +55,18 @@ ENDCLASS.
 IF client->check_on_init( ).            " first call
   " load data + render view
 ELSEIF client->check_on_navigated( ).   " returned from a called sub-app (nav_app_call), incl. built-in popup apps
-  " refresh state
+  " re-display the view - the sub-app's view is still on screen; state survived serialization, no data re-read needed
 ELSEIF client->check_on_event( `POST` ). " user fired event 'POST'
   " handle it
 ENDIF.
 ```
 
 → [Life Cycle](/cookbook/event_navigation/life_cycle)
 
+::: warning The #1 lifecycle bug: blank screen after navigation
+Always call `view_display( )` in the `check_on_navigated( )` branch. When a called sub-app took over the screen and returns via `nav_app_leave( )`, the browser still shows the sub-app's view — the framework does not restore the previous view automatically. All class attributes survived the roundtrip serialization, so no data re-read is needed — just render the view again. Skipping this leaves the user on a blank or stale screen after navigating back.
+:::
+
 #### 3. State lives in **public** class attributes
 
 Anything bound to the view must be `PUBLIC`. The framework serializes public attributes between roundtrips automatically — no session handling needed.
@@ -121,7 +125,7 @@ Complete worked example: see [Quickstart](/get_started/quickstart), [Hello World
 
 ## Canonical App Template
 
-For anything beyond ~50 lines in `main`, extract `on_init` and `on_event` first, then add helpers (`view_display`, `data_read`, `data_update`) only when needed. Class names lowercase, no `FINAL`, definition order `TYPES` → `DATA` → `METHODS`.
+For anything beyond ~50 lines in `main`, extract `on_init` and `on_event` first, then add helpers (`view_display`, `data_read`, `data_update`) only when needed. Class names lowercase, no `FINAL`, definition order `TYPES` → `DATA` → `METHODS`. In the `check_on_navigated( )` branch call `view_display( )` directly — the state survived serialization, only the view is gone from the browser.
 
 ```abap
 CLASS zcl_app_xxx DEFINITION PUBLIC.
@@ -135,7 +139,6 @@ CLASS zcl_app_xxx DEFINITION PUBLIC.
 
     METHODS on_init.        " first call: load data, render view
     METHODS on_event.       " user triggered an event
-    METHODS on_navigation.  " returned from a sub-app called via nav_app_call
     METHODS view_display.   " build and render the view
     METHODS data_read.      " SELECT
     METHODS data_update.    " INSERT / UPDATE / DELETE
@@ -153,7 +156,7 @@ CLASS zcl_app_xxx IMPLEMENTATION.
     IF client->check_on_init( ).
       on_init( ).
     ELSEIF client->check_on_navigated( ).
-      on_navigation( ).
+      view_display( ).
     ELSEIF client->check_on_event( ).
       on_event( ).
     ENDIF.
@@ -251,7 +254,7 @@ When an AI needs deeper information than this page provides:
 
 A prompt that gives an AI assistant enough context to produce a working app:
 
-> You are building an abap2UI5 app. Read <https://abap2ui5.github.io/docs/advanced/agent.html> first — it is the single source of truth for app-building (template, client API, lifecycle, view builder, deprecated controls, documentation map). For working examples, browse <https://github.com/abap2UI5/samples/tree/main/src> (250+ apps, one feature per app). Use `z2ui5_cl_util_xml` as the view builder. Look up any UI5 control at <https://ui5.sap.com/#/api> and translate the XML 1:1 to ABAP. Do not use any control listed in this page's "Deprecated UI5 Controls" section.
+> You are building an abap2UI5 app. Read <https://abap2ui5.github.io/docs/advanced/agent.html> first — it is the single source of truth for app-building (template, client API, lifecycle, view builder, deprecated controls, documentation map). For working examples, browse <https://github.com/abap2UI5/samples/tree/main/src> (250+ apps, one feature per app). Use `z2ui5_cl_util_xml` as the view builder. Look up any UI5 control at <https://ui5.sap.com/#/api> and translate the XML 1:1 to ABAP. Do not use any control listed in this page's "Deprecated UI5 Controls" section. Always call `view_display( )` in the `check_on_navigated( )` branch — otherwise the screen is blank after returning from a called sub-app.
 
 ## Hard Rules (Cheat Sheet)
 
@@ -260,6 +263,7 @@ A prompt that gives an AI assistant enough context to produce a working app:
 | Implement `z2ui5_if_app` with a single `main` method | The only entry point the framework calls |
 | Bound attributes must be `PUBLIC` | The framework binds via dynamic ASSIGN; `PROTECTED`/`PRIVATE` are silently ignored |
 | Use `IF` / `ELSEIF` with `check_on_init` / `check_on_event( 'NAME' )` / `check_on_navigated` | Canonical dispatcher pattern |
+| Always call `view_display( )` in the `check_on_navigated` branch | The browser still shows the called sub-app's view after `nav_app_leave( )` — without a re-display the screen stays blank |
 | Use `z2ui5_cl_util_xml` for AI-generated views | Maps 1:1 to UI5 SDK; no wrapper to learn |
 | Pass XML boolean attributes as string literals `'true'` / `'false'` | `abap_true` / `abap_false` produce invalid or empty attributes |
 | Use backtick string literals (`` ` ``), not single quotes | Project-wide convention enforced by abaplint |

docs/cookbook/event_navigation/navigation.md

@@ -32,10 +32,14 @@ To read data from the previous app, cast it like this:
     IF client->check_on_navigated( ).
         DATA(lo_called_app) = CAST z2ui5_cl_new_app( client->get_app_prev( ) ).
         client->message_box_display( `Input made in the previous app:` && lo_called_app->mv_input ).
+        view_display( ).
     ENDIF.
 
 ENDMETHOD.
 ```
+::: warning Re-display your view on return
+When the called app took over the screen with its own `view_display( )`, the browser still shows that view after `nav_app_leave( )` — the framework does not restore the previous view automatically. Call `view_display( )` again in the `check_on_navigated( )` branch. Your class attributes survived the roundtrip serialization, so no data re-read is needed — only the view must be rendered again. See [Life Cycle](/cookbook/event_navigation/life_cycle#returning-from-a-sub-app-hits-check_on_navigated-not-check_on_init).
+:::
 Called **with** an app instance, `nav_app_leave` works differently: it leaves the current app and starts the given one *without* pushing the current app onto the call stack — so there is nothing to return to. Use this to navigate forward while discarding the current app:
 ```abap
   METHOD z2ui5_if_app~main.

docs/public/llms.txt

@@ -0,0 +1,23 @@
+# abap2UI5
+
+> abap2UI5 is an open-source framework for building SAP UI5 apps purely in ABAP — no JavaScript, OData or RAP required. An app implements the interface `z2ui5_if_app` with a single `main( )` method; the framework calls it on every HTTP roundtrip.
+
+Key facts for AI assistants generating abap2UI5 apps:
+
+- The canonical AI briefing is https://abap2ui5.github.io/docs/advanced/agent.html — read it before generating any app code.
+- Dispatch inside `main( )` with `IF` / `ELSEIF` over `client->check_on_init( )`, `client->check_on_navigated( )` and `client->check_on_event( 'NAME' )`.
+- CRITICAL — most common bug: always call `view_display( )` in the `check_on_navigated( )` branch. After returning from a sub-app called via `nav_app_call( )`, the browser still shows the sub-app's view — the framework does not restore the previous view automatically. App state survives the roundtrip serialization, so no data re-read is needed; only the view must be rendered again. Skipping this leaves a blank screen after navigating back.
+- Build views as UI5 XML strings with `z2ui5_cl_util_xml` (1:1 translation of UI5 SDK XML, recommended for AI) or `z2ui5_cl_xml_view` (fluent API).
+- Attributes bound with `_bind` / `_bind_edit` must be PUBLIC; use backtick string literals.
+
+## Docs
+
+- [AI Agent Briefing](https://abap2ui5.github.io/docs/advanced/agent.html): single source of truth for app-building (template, client API, lifecycle, view builders, deprecated controls)
+- [Life Cycle](https://abap2ui5.github.io/docs/cookbook/event_navigation/life_cycle.html): lifecycle checks and pitfalls, including the blank-screen-after-navigation bug
+- [Navigation](https://abap2ui5.github.io/docs/cookbook/event_navigation/navigation.html): cross-app navigation and re-displaying the view on return
+- [Quickstart](https://abap2ui5.github.io/docs/get_started/quickstart.html): installation and first app
+
+## Examples
+
+- [Samples repository](https://github.com/abap2UI5/samples): 250+ working demo apps, one feature per app
+- [Framework repository](https://github.com/abap2UI5/abap2UI5): core framework, architecture documented in AGENTS.md