Skip to content

docs: document submit-state events, optimistic(), and view transitions on the client-router page #579

Description

@vivek7405

Problem

Two client-router behaviours are documented in agent-docs/advanced.md and AGENTS.md but entirely absent from the docs site:

  1. Form submission-state events and the optimistic-UI helper (Add form submission-state events and an optimistic-UI mutation helper #246): webjs:submit-start / webjs:submit-end events, the in-flight form aria-busy, and optimistic(signal, value, action). The docs site client-router page documents only webjs:frame-busy (frame-nav busy state), not form submission state, and the word "optimistic" appears on the site only as an unrelated loading-skeleton mention.
  2. View Transitions on partial swaps and permanent-element preservation (View transitions on partial swaps and permanent-element preservation #250): the <meta name="view-transition"> opt-in and data-webjs-permanent. A grep for view.transition|startViewTransition|data-webjs-permanent across docs/app/docs/** returns nothing.

Implementation notes (for the implementing agent)

  • Where to edit: docs/app/docs/client-router/page.ts (add a forms/submission-state subsection and a view-transitions subsection).
  • What to document for Add form submission-state events and an optimistic-UI mutation helper #246: the webjs:submit-start / webjs:submit-end events with their detail shapes ({form,url} and {form,url,ok}), the in-flight aria-busy on the submitting form, and optimistic(signal, value, action) (set immediately, run the action, roll back on error or { success: false }).
  • What to document for View transitions on partial swaps and permanent-element preservation #250: the <meta name="view-transition" content="same-origin"> opt-in (applies to marker, frame, and full-body swaps with a feature-detected fallback) and data-webjs-permanent plus its required id to persist a live element across swaps.
  • Source of truth to copy from: agent-docs/advanced.md (around L456 to L504 for submit events / optimistic, around L628 to L694 for view transitions), AGENTS.md around L183 and L306, packages/cli/templates/AGENTS.md around L907 to L916.

Acceptance criteria

  • Client-router docs page documents webjs:submit-start / webjs:submit-end, form aria-busy, and optimistic().
  • Client-router docs page documents the View Transitions opt-in and data-webjs-permanent.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

documentationImprovements or additions to documentation

Type

No type

Projects

  • Status
    Done

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions