Repository navigation
docs(session): Session Forms V1 - #46
Open
AndrewKirkovski wants to merge 18 commits into
Open
AndrewKirkovski wants to merge 18 commits into
AndrewKirkovski wants to merge 18 commits into
Conversation
- Framework page: enabling the ask_user trait, the form definition and its limits, the answer message and self-contained answer record, read_form and the form index (including pending answers), late answers, one form per turn, answer admission, and security notes. - Frontend page: the question card, the wippy-form and wippy-form-answers components, the artifact state HTTP API and artifactState client, Host version requirements, accessibility notes and known gaps.
…d answer re-dating The framework page didn't mention that form answers are never steered into a running turn (unlike typed input, which follows the session's own steering trait), that the user's session plugin starts a stopped session holding an unadmitted answer both at plugin start and on each periodic scan, that the same plugin start settles stale "running" sessions with no live process back to idle, or that an admitted answer's message row is re-dated to the moment of admission while the artifact-state API's submitted_at keeps the original acceptance time. Brings the page in line with the Session README and the plugin/message-handler source.
…narration The frontend page had drifted from the shipped code: a form artifact that exists but isn't a session form returns 400 not_a_form, not 404; the question card also reloads on the Host's @REconnect event and the browser's online event; and field errors render as role="alert" elements linked by aria-describedby, not aria-describedby "instead of" a role. The accessibility section now also covers the roving tabindex on a single-selection group, that Escape in a note or Other box keeps the typed draft, and where focus goes after a full submission. Also removes process narration and local decision ids ("D27", "tried and reverted", "no longer fabricates" / "now rethrows", "shipped without an explicit product decision") in favor of stating current behavior and defaults directly.
…havior An enforced Stop (the session plugin cancels/terminates a session that outlives the 10s deadline) now admits that turn's pending answers with no new turn, matching an honored Stop; the framework page described only the honored-Stop case. Also fix the plugin-recovery paragraph: "reads as interrupted" only applies to an answer already admitted before the process disappeared, not to one still pending, which is unaffected by the status settling and simply gets a turn on the next start. Add a rollback section: removing the ask_user trait is config-only and leaves open and answered forms readable; downgrading the Session module below the release that shipped forms is a separate, riskier action that can leave a consumer's own forms-related registry entries unresolved at boot (confirmed against a demo fixture; the trait-only case was not tested).
State the actual Host requirement: no release up to and including 1.0.60 exports artifactState, so the requirement is the first Web Host release after 1.0.60 that includes Session Forms (version not assigned yet), with the npm @wippy-fe/proxy peer tracking the same release. Record a confirmed gap in the old-Host fallback: the component checks for an artifact id before it checks for Host capability, and no real old Host sets one without the other, so "needs a newer Web Host" is unreachable in practice — an old Host (tested against the published 1.0.59) always shows "This form cannot be submitted here." instead, with no crash, no mock data, and the chat sentence still readable. A fix is in progress but not in this release yet. Add a Diagnostics section: what each card-state value means, the two load-failure log lines and their one-per-tag dedup, and what @REconnect is for.
… the consumer sign-in requirement The old-Host fallback is fixed for new forms. On a Web Host without the artifactState export the card shows the questions with disabled options, no submit control and card-state "unsupported". The notice says the form needs a newer Web Host and that an answer already sent is in the chat. When the Host passes state "idle" it says the form was answered. This replaces the confirmed-gap text that said the notice was unreachable. The condition table now lists the checks in the order the component runs them. A bundle that failed to load is not retried in the page, because the browser keeps a failed script load for the life of the page, so the diagnostics now say to reload. The framework page gets a Compatibility section covering old Hosts, unknown form versions, a missing bundle, and the userspace/users 0.1.9 requirement for sign-in on runtime v0.3.43a.
…Web Host 1.0.61, plain-writing pass Remove test and observation narration from the rollback and old-Host sections, require Web Host 1.0.61 or later, correct the trait prompt summary and the late flag (always present in the record), drop the unrelated userspace/users sign-in note, and apply the plain-writing rules (no dashes, no decorative bold, shorter lists) to both pages.
… results The admission section is now two sentences and a table, and the compatibility and limits sections are gone because the frontend page and the tool table already hold those facts. The read_form table shows the real result shape of each status, and the option description limit is stated. The text no longer mentions dismissing forms or a fallback fields form.
…ost source The Host requirement table now holds the whole pre-1.0.61 behavior, and repeated notes on the carrier element, reconnect and accessibility are gone. The GET example has a real field, the POST section states the request_id and answers rules, and the 404 and permission checks live here. The isArtifactStateError paragraph now matches the Host source, where the class overrides Symbol.hasInstance to check the same brand.
… across bundles The Web Host removed the Symbol.hasInstance override from ArtifactStateError. The frontend page now says to use isArtifactStateError(error), also $W.isArtifactStateError in an iframe page, because each proxy bundle carries its own copy of the class. It also notes that malformed 422 entries are left out of errors and formErrors, that a registration timeout is logged once per card while a script error is logged once per tag, and the submit example reads form_version from the loaded state.
…on forms The wippy-form component no longer has a density prop or host attribute and dispatches only the shared base events. List those, and point to card-state for reacting to a submission.
Session Forms ship in Web Host 1.0.64; releases 1.0.61 to 1.0.63 do not export artifactState.
This branch has not been deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
This pull request documents Session Forms V1 (EE2-2461). It adds a framework page for the
wippy.session.forms:ask_usertrait and a frontend page for the question card and theartifactStateclient, and it adds both pages to the site navigation inen/manifest.json.Changes
en/framework/session-forms.mdexplains the trait, the form contract, the state API, and an upgrade section with the breaking changes inwippy/session0.7.0.en/frontend/micro-frontends/session-forms.mdexplains the question card, theartifactStateclient in iframe pages and web components, and the Host version it needs.Merge timing
Please merge after Web Host 1.0.65 is tagged and
wippy/session0.7.0 is published. The pages name those versions, and a comment on the frontend page asks to confirm them at that time.Verification
scripts/check-markdown-links.mjsandscripts/check-frontend-docs.mjspass.