Skip to content

docs: add contract testing guide, service worker, error handling, and accessibility docs - #594

Merged
codebestia merged 4 commits into
codebestia:devfrom
G-ELM:feat/implement-tasks
Aug 30, 2026
Merged

docs: add contract testing guide, service worker, error handling, and accessibility docs#594
codebestia merged 4 commits into
codebestia:devfrom
G-ELM:feat/implement-tasks

Conversation

@G-ELM

@G-ELM G-ELM commented Aug 30, 2026

Copy link
Copy Markdown
Contributor

Summary

Adds four documentation files closing gaps across the Soroban contracts and the web
frontend:

  • contracts/docs/testing.md — the standard Soroban test scaffolding (Env::default(),
    Address::generate), the three levels of auth mocking (mock_all_auths,
    mock_all_auths_allowing_non_root_auth, and asserting real auth via env.auths() /
    mock_auths) and the risk of blanket mocking hiding a missing require_auth(), testing
    expiry via the virtual ledger clock, the proposalsgroup_treasury cross-contract
    test setup, and the test_snapshots/ directory (generated by cargo test, committed,
    Prettier-ignored).

  • apps/web/docs/concepts-service-worker.mdsw.js registration/update lifecycle
    (skipWaiting + clients.claim), the content-free push handler (cross-linked to the
    backend push docs), click-to-route behaviour that focuses an existing tab instead of
    opening a duplicate, and a plain statement of what does and does not work offline today.

  • apps/web/docs/concepts-error-handling.md — the toast API vs. inline error state,
    mapping backend error responses (REST schema error format, per-endpoint docs) to
    user-facing messages, the hard rule that decryption failures always render as
    UnavailableMessagePlaceholder rather than a generic crash, and current send-failure /
    offline behaviour including known gaps (silent socket errors, no automatic retry or
    offline queue).

  • apps/web/docs/accessibility.md — states the WCAG 2.1 AA target and that it's
    currently checked manually; documents keyboard navigation through the conversation list
    and composer, contrasts Modal's full focus-trap/restore implementation against the
    safety-number panel's current gap, the aria-live approach for incoming messages that
    announces without stealing focus, a colour-contrast risk in low-opacity text utilities,
    and a pre-merge checklist for new interactive components.

All four are registered in docs/README.md. Several docs call out real, currently-existing
gaps (missing toast on send failure, un-trapped safety panel focus, no automated a11y
tooling) rather than describing aspirational behaviour, so the docs stay accurate.

Test plan

  • Docs-only change; no code behavior modified. Reviewed for accuracy against the
    current implementation of sw.js, useToast.ts, Modal.tsx,
    ConversationListSidebar.tsx, MessageThread.tsx, and the three contracts' test
    suites.

Closes #577
Closes #578
Closes #574
Closes #575

G-ELM added 4 commits August 30, 2026 23:47
Documents the standard Soroban test scaffolding, the three levels of
auth mocking and the risk of blanket mock_all_auths() hiding a missing
require_auth(), how to test expiry via the virtual ledger clock, and
the proposals -> group_treasury cross-contract test setup.
Documents sw.js registration/update lifecycle via skipWaiting +
clients.claim, the content-free push handler, click-to-route focusing
an existing tab instead of opening a duplicate, and what does and does
not work offline today (no precaching, no fetch interception, no
background sync).
Documents the toast API vs inline error state, maps backend error
responses (REST schema error format, per-endpoint docs) onto
user-facing messages, states the hard rule that decryption failures
render as UnavailableMessagePlaceholder rather than a generic crash,
and covers current send-failure/offline behaviour including known
gaps (silent socket errors, no send retry or offline queue).
States the WCAG 2.1 AA target and that conformance is currently
checked manually (no automated a11y tooling in the repo yet).
Documents keyboard navigation for the conversation list and composer,
contrasts Modal's full focus-trap/restore implementation against the
safety-number panel's current gap, explains the aria-live approach for
incoming messages without stealing focus, flags the low-opacity text
contrast risk, and gives a pre-merge checklist.

Also registers all four new docs (contract testing, service worker,
error handling, accessibility) in the documentation index.
@drips-wave

drips-wave Bot commented Aug 30, 2026

Copy link
Copy Markdown

@G-ELM Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits

@codebestia
codebestia merged commit 344f1a9 into codebestia:dev Aug 30, 2026
8 of 9 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants