Fluid Navigation

Fluid Navigation: Dynamic Evolution of the AriaML Document

Fluid Navigation

Dynamic Evolution of the AriaML Document

In the AriaML standard, navigation is not necessarily a page replacement, but can be a fluid mutation. The root document <aria-ml> is persistent, while its internal content (slots) evolves dynamically through fragment injection, orchestrated by a secure transition cycle.

1. The Fragment as a Mutation Vector

An AriaML fragment is a partial extension of the document allowing for the update of one or several parts of the document.

Fragment Architecture

A fragment must integrate its own security logic to force the restoration of the root document if it is accessed out of context.

<meta http-equiv="refresh" content="0;url=./">
<style>aria-ml .aria-ml-fallback {display: none;}</style>
<div class="aria-ml-fallback">Loading document...</div>

<aria-ml-fragment>
    <script type="application/ld+json" nav-slot="WebPage">
    [{
        "@context": "[https://ariaml.org/ns#](https://ariaml.org/ns#)",
        "@type": "WebPage",
        "name": "title"
    }]
    </script>

    <main nav-slot="main">
        <h1>Injected Content</h1>
        <p nav-cache="unique-key">This node will be persisted in memory.</p>
    </main>
</aria-ml-fragment>

2. The SPA Navigation Cycle

A. Negotiation and Request

  1. Interception: The browser identifies navigation intentions (<a> or <form>) where the target (target attribute) is _slots (default value of the target attribute in AriaML).
  2. Initial Lock: Upon intention, the root document (<html>) is marked aria-busy="true" and inert to signify transit.
  3. NavCache Header: The request includes the Nav-Cache header listing the keys already known by the client to allow the server to optimize its response.

B. Asymmetric Locking Strategy

The standard distinguishes between two types of mutations after receiving the response:

Mutation Type Locking Target (aria-busy/inert) Locking Duration
Full Replacement (<aria-ml>) Global root (documentElement) Until the end of the transition.
Partial Update (<aria-ml-fragment>) Target slots only Until the end of the mutation.

Note: In the case of a partial update, the global root is released immediately to allow interaction with the rest of the page (menus, header) while the slots are mutating.

3. NodeCache System (Nav-Cache)

The NavCache ensures the persistence of DOM nodes between views, independently of the history stack.

  • Registration: Elements carrying the nav-cache attribute are memorized by the user agent as soon as they are inserted into the DOM.
  • Restoration:
    • If the container is a slot, its node is preserved. The node's content is moved from the cache to the new slot.
    • Otherwise, the empty node sent by the server is replaced by the actual node stored in memory.
  • Persistence: The cache survives even if the element is detached from the DOM (e.g., pagination, filters).

4. Transitions and Visual Feedback

The AriaML standard recommends the progressive use of the View Transitions API. If transitions are not supported or are disabled by the user (prefers-reduced-motion), a direct update is performed without breaking the navigation cycle.

5. Form Management and Extended Verbs

AriaML lifts the historical limitations of HTML regarding submission methods in a non-normative way:

  • Methods: Native support for GET, POST, PUT, PATCH, DELETE verbs.
  • Scope: The use of extended verbs is restricted to URLs belonging to the navigationBaseUrl.
  • Server Logic: It is the developer's responsibility to correctly interpret the verb: The server must adapt the processing and response based on the received verb.
  • JSON Encoding: enctype="application/json" allows the transmission of a single JSON object. Files are serialized into Base64 (Data URI) within it.

6. Security and Integrity

CSRF Token

The security token is dynamically extracted from the JSON-LD csrfToken property. Its transmission is strictly limited to the navigationBaseUrl perimeter:

  1. In the X-CSRF-TOKEN header for mutation requests (fetch).
  2. In a field named _token for all form submissions.

Perimeter Locking

The navigationBaseUrl defines the trust zone. Any navigation exiting this origin unloads the AriaML context to return to a classic navigation mode. This ensures that the fragment's slot structure and the document remain consistent, and prevents an external domain from taking control of the document.

7. Automatic Focus Management and Accessibility

After each mutation, focus is reassigned to ensure continuity of experience:

  1. Priority to the element carrying the autofocus attribute in the new content.
  2. Failing that, focus moves to the first impacted slot.
  3. As a last resort, the <aria-ml> root receives the focus.

Next: How to implement AriaML on the server side?