release: WRNexusJS 0.8.0

.publish/csr/README.md

@@ -1,5 +1,34 @@
 # @wrnexus/csr
 
+## Navigation state preservation
+
+Pages can opt into restoration across client navigation:
+
+```wrn
+page Users {
+  navigation {
+    preserve = ["filters", "pagination", "scroll", "tabs", "expanded"]
+  }
+}
+```
+
+Form-like categories restore named inputs, selects, and textareas. Password,
+file, hidden, CSRF/token/secret/credential fields, and elements marked
+`data-no-preserve` are never saved. For tab, expanded, or component UI state,
+mark stable elements with `data-wrn-preserve="key"`; their value and ARIA
+selected/expanded state are restored. State is scoped to pathname plus query.
+
+## Typed server actions
+
+`createActionClient<Input, Output>(route, name)` supports programmatic calls.
+Schema-backed WRN actions also export `__wrnexusActionClients`, whose input and
+output are inferred automatically. Enhanced forms expose
+`data-wrn-action-state="pending|success|error"` and dispatch bubbling
+`wrnexus:action:optimistic`, `:pending`, `:success`, and `:error` events.
+Success details contain returned data and invalidated cache tags; error details
+contain field errors. Without JavaScript, the same form posts to its page and
+receives a 303 redirect or accessible validation response.
+
 > The browser-side client runtime for WrNexus — generic, self-contained JS that hydrates server-rendered pages with reactivity, client-side navigation, and realtime rooms.
 
 Part of the **WrNexus** framework — an SSR-first, Bun-native full-stack web framework.
@@ -49,16 +78,21 @@ getRealtimeRuntime(): string   // → REALTIME_RUNTIME
 
 Applied to any subtree containing `data-scope`. Expressions are parsed by a tiny eval-free evaluator, so a strict CSP with no `unsafe-eval` works.
 
-| Directive                                                | Purpose                                                                 |
-| -------------------------------------------------------- | ----------------------------------------------------------------------- |
-| `data-scope="count: 0, name: 'x'"`                       | Declare reactive state on a subtree                                     |
-| `data-on-<event>="count++"`                              | Run a statement in scope on a DOM event                                 |
-| `data-text="expr"`                                       | Bind an element's `textContent` to an expression                        |
-| `data-show="expr"`                                       | Toggle visibility (`display`) on truthiness                             |
-| `data-for="item in list"` (opt. index and `key item.id`) | Per-item rendering; stable keys preserve DOM identity during reorder    |
-| `data-key="item.id"`                                     | Alternative key declaration for `data-for` templates                    |
-| `{{expr}}` or `{expr}`                                   | Interpolation inside text nodes and attribute values                    |
-| `data-wrnexus-csr="id"`                                  | Target for a generated CSR fetch binding (fetches `/__wrnexus/csr?...`) |
+| Directive                          | Purpose                                              |
+| ---------------------------------- | ---------------------------------------------------- |
+| `data-scope="count: 0, name: 'x'"` | Declare reactive state on a subtree                  |
+| `data-on-<event>="count++"`        | Run a statement in scope on a DOM event              |
+| `data-text="expr"`                 | Bind an element's `textContent` to an expression     |
+| `data-show="expr"`                 | Toggle visibility while preserving interactive state |
+
+Compiled conditional rendering and dynamic component cases omit inactive elements from the live
+DOM. `data-show` is a visibility directive for stateful controls and keeps its element mounted.
+Neither mechanism is authorization: never place secrets in client-rendered branches. Authorize on
+the server and return only data the current request may access.
+| `data-for="item in list"` (opt. index and `key item.id`) | Per-item rendering; stable keys preserve DOM identity during reorder |
+| `data-key="item.id"` | Alternative key declaration for `data-for` templates |
+| `{{expr}}` or `{expr}` | Interpolation inside text nodes and attribute values |
+| `data-wrnexus-csr="id"` | Target for a generated CSR fetch binding (fetches `/__wrnexus/csr?...`) |
 
 Supported expression features: literals, identifiers, member access (`a.b`, `a[b]`), function/method calls, arrays, objects, arithmetic, comparison, equality, logical (`&& ||`), unary (`! - +`), and ternary. Statements support `++`/`--`, assignment operators (`= += -= *= /= %=`), and bare expression/method calls. Rendering is dependency-tracked: a signal change only re-runs the renderers that actually read it.