fix(pg-sveltekit): give the example's controls accessible names and state

[rubenhensen]

From dobby's review of #145. +page.svelte is byte-identical to the archived postguard-examples, so this is relocated debt rather than something the import introduced — but it is the app docs.postguard.eu teaches from, in a repo whose stated bar is WCAG 2.2 AA, and it would otherwise stay buried in a 4000-line import.

Six placeholder-only controls

The citizen name and email, the organisation name and email, the API key, and the message textarea had no label at all. A placeholder is not one: the accessible name disappears the moment the user types, and there is no programmatic field/label association. That fails 1.3.1, 3.3.2 and 4.1.2.

Each control is now wrapped in a <label> with visible text. Placeholders that carried a sample value (citizen@example.com, PG-1a2b3c4d5e6f7g8h) keep it as a format hint rather than as the name.

The delivery-mode toggle had no exposed state

Selection lived only in class:active, so a screen-reader user could not tell which mode was active. Both buttons now expose aria-pressed, per the ARIA APG toggle-pair pattern, and both got the explicit type="button" they were missing.

ProgressBar was three bare divs

No role, no value, no accessible name (4.1.2), and no announcement as it advanced (4.1.3). The track now carries role="progressbar" with aria-valuenow/min/max, plus aria-valuetext matching the rounded percentage the visible text shows rather than a long float.

Its name comes from the existing label via aria-labelledby, falling back to aria-label when no label is passed — so the name is never absent either way. aria-live="polite" sits on the container rather than the track, so the label is part of the announcement instead of a bare number.

The error box was silent

No role="alert", so a failed send was invisible to assistive technology. It has one now.

One CSS consequence, fixed rather than left latent

section > input matched the API key field as a direct child; wrapping it in a label made that selector dead, which svelte-check flagged. Replaced with .field input, which covers every input now that they all sit inside one. Back to 0 errors / 0 warnings.

Verified at the built output

Not just the source — role="progressbar", aria-valuenow, aria-pressed, aria-live and role="alert" all appear in .svelte-kit/output, and the new label text renders. Build and lint clean.

Not covered here

FileDropzone.svelte has no aria attributes at all. A drop target's keyboard and screen-reader story is a design question rather than an attribute fix, so it wants its own change rather than being guessed at in this one.

Refs #145.

[dobby-coder]

Thanks for opening this! I'm on it — reviewing #152 now for correctness and WCAG 2.2 AA compliance, and I'll follow up with a consolidated review shortly.

[dobby-coder]

Net accessibility win, and the mechanism is right in most places: six real labels with programmatic association, aria-pressed on the toggle pair, a named progressbar with a value, role="alert" on the error box. All 20 checks are green, including Svelte Check, the Node examples lane (typecheck + build + lint over every example) and the Conventional Commit title check. Two things in ProgressBar.svelte need a change before merge; the other four inline notes are optional.

Blocking

1. id="progress-label" is a hardcoded literal in a reusable lib/components file, so the accessible name of the second instance on a page resolves to the first instance's label, and the duplicate id is invalid HTML. Only one instance exists today (+page.svelte:269), so nothing is broken for a user right now, but this is the copy docs.postguard.eu readers lift. Svelte is 5.56.8, so $props.id() fixes it in two lines.
2. The new comment says aria-live sits on the container "so the label is part of the announcement", but aria-atomic defaults to false, so AT announces only the changed node, which is .progress-text. The code and its own comment disagree. Either set aria-atomic="true" or reword the comment to say the announcement is a bare percentage.

Not introduced here, and not for this PR

Three contrast values on this page still miss AA. I recomputed each with the sRGB formula rather than trusting a reported figure, and one number that reached me was wrong:

pair	ratio	needs	criterion
.hint / .mode-desc #888 on white	3.54:1	4.5:1	1.4.3
input border #ccc on white	1.61:1	3:1	1.4.11
progress fill #4a9 on track #eee	2.43:1	3:1	1.4.11

The progress-fill figure was handed to me as 2.19:1; the correct value is 2.43:1. It still fails, so the conclusion holds.

Two more that sit on the buttons this PR touches, both from untouched declarations: .mode-btn.active .mode-desc is #6b7280 on #eff6ff = 4.44:1 at 0.8rem (12.8px is not large text, so 1.4.3 wants 4.5:1), and the button boundary is #e2e8f0 resting = 1.23:1 and #cbd5e1 on hover = 1.48:1 against the 3:1 that 1.4.11 asks of a control boundary. All five are colour-token changes rather than markup, so a separate PR is the right home, same call you already made for FileDropzone.

On the missing test

examples/pg-sveltekit has no test script, no test runner in its devDependencies and no test directory, and examples.yml only requires each example to declare typecheck. Standing up a harness to assert an aria attribute would be a larger change than the fix, so no regression test here is the right call. role="progressbar", aria-valuenow, aria-pressed, aria-live and role="alert" in .svelte-kit/output is a reasonable substitute, and I confirmed the .field input rewrite loses nothing: the textarea keeps its own rule at line 366 with the same padding, border, font-size and font-family, so wrapping it in a .field label did not strip its styling.

[dobby-coder]

Blocking. id="progress-label" is a hardcoded literal inside a reusable component, so every instance emits the same id. With two labelled <ProgressBar>s on one page the second one's aria-labelledby resolves to the first one's label, giving it the wrong accessible name, and duplicate ids are invalid HTML besides.

Only one instance exists today (+page.svelte:269), so no user hits it yet. It matters because this is the shared lib/components copy that docs readers lift, and because a wrong accessible name is the exact failure mode the rest of this PR fixes.

Svelte is 5.56.8 here, so $props.id() is available and this is two lines:

const labelId = $props.id();

then id={labelId} on line 21 and aria-labelledby={label ? labelId : undefined} on line 31.

[dobby-coder]

Blocking, though either resolution is a one-line change.

The comment above says aria-live sits on the container "so the label is part of the announcement". aria-atomic defaults to false, so assistive tech announces only the changed descendant, which is the .progress-text node on line 35, not the label div. What a user actually hears is 42%.

Getting the stated behaviour needs aria-atomic="true" on this element, and that has a real cost: packages/pg-js/src/crypto/encrypt.ts uploads in 5 MB chunks, so a 100 MB upload fires roughly 20 progress events, and each one would re-announce the whole string Encrypting & uploading... 42%.

A bare percentage every few seconds is arguably the better experience, so rewording the comment is a fine fix. What should not ship is a comment in a teaching example that describes behaviour the code does not have.

[dobby-coder]

Non-blocking. aria-valuenow is unclamped while .progress-fill on line 33 is, so <ProgressBar percentage={120} /> renders aria-valuenow="120" against aria-valuemax="100" while the bar visually stops at 100%. ARIA requires aria-valuenow to fall within the min/max range.

The app cannot reach it, since encrypt.ts already clamps with Math.min(100, Math.round(...)) before calling onProgress. But the component takes an arbitrary percentage prop, and the original author clamped the fill for exactly this reason. One clamped local reused by the fill, aria-valuenow and aria-valuetext covers all three.

[dobby-coder]

Non-blocking, 2.4.6 Headings and Labels. The organisation fields got qualified names ("Organisation name", "Email address at the organisation") but the citizen ones stayed bare: "Name" and "Email address".

In forms mode or when browsing the form field by field, a screen-reader user gets the label without the surrounding <h2>2. Citizen recipient</h2>, so two of the four recipient fields are ambiguous against the two organisation fields directly below them. "Citizen name" and "Citizen email address" would match the qualification you already applied one section down.

[dobby-coder]

Non-blocking. flex: 1 does nothing useful at either place .field lands.

Inside .field-group, which is flex-direction: column on line 351, flex: 1 1 0% does not put the two fields side by side. It makes them grow to equal height, which surfaces as dead space once one label wraps at a narrow width. At the two section-level usages (API key on line 240, message on line 254) .field is not a flex item at all, so the declaration is inert there.

Either drop it, or make .field-group a row above some breakpoint if side-by-side was the intent.

[dobby-coder]

Non-blocking. type="button" went on the two mode buttons but not on the other three: "Start over" (line 168), "Cancel" (line 270) and the submit button (line 273).

Nothing breaks today, because no <form> wraps any of them, which is also why the two that got it were not broken to begin with. So either apply it to all five or leave it out. Half-applied is the one state that reads as an oversight to the next person.

[dobby-coder]

Reviewed #152 and left a request-changes review with 6 inline comments. Nice fix overall — all 20 CI checks are green.

Two blocking items in ProgressBar.svelte:

• The hardcoded id="progress-label" will collide if a second <ProgressBar> ever lands on the same page (invalid duplicate HTML + wrong accessible name). Since you're on Svelte 5.56.8, $props.id() is a clean fix.
• aria-live on the container needs aria-atomic="true" to actually announce the label with the percentage — right now a screen reader only hears "42%". Either add that attribute or reword the comment describing the behavior.

4 optional notes: unclamped aria-valuenow vs aria-valuemax, citizen fields missing the (2.4.6)-style qualifiers the organisation fields got, an inert flex: 1 on .field, and type="button" missing on two of five buttons.

Also corrected one of my own numbers along the way: the progress-fill contrast is actually 2.43:1, not 2.19:1 — still fails 1.4.11's 3:1 minimum, so the finding stands. Found two more pre-existing AA contrast gaps on buttons this PR touches, but since they're separate color-token work I left them as a follow-up rather than blocking this PR on them (same call you made for FileDropzone).

[rubenhensen]

/dobby both blockers fixed in 0519f4c, and all four optional notes taken.

The hardcoded id="progress-label" is the one that mattered, and your framing is why: a wrong accessible name is exactly the failure the rest of this branch fixes, so shipping it in the reusable lib/components copy that docs readers lift would have been self-defeating. $props.id() on svelte 5.56.8, as you suggested.

On aria-live I took the reword rather than aria-atomic="true", and your own cost analysis decided it: 5 MB chunks means roughly 20 progress events for a 100 MB upload, and re-announcing Encrypting & uploading… 42% twenty times is worse for the user than the bare percentage. The comment now says what is actually announced, and notes the label is still the track's accessible name via aria-labelledby so it is there on focus. The code and its comment agree either way — that was the real defect.

Clamped aria-valuenow. You are right that the original author clamped the fill for exactly this reason and I left the ARIA value unclamped beside it. One derived value now feeds the fill, aria-valuenow, aria-valuetext and the visible text, so they cannot diverge.

Qualified the citizen labels ("Citizen name", "Citizen email address"). The field-by-field navigation argument is the one I had not thought through — the <h2> disambiguates visually and is absent in forms mode, which is precisely when the two pairs collide.

Dropped flex: 1 — inert at the section-level usages and actively wrong inside the column-direction .field-group, where it equalised height and produced dead space once a label wrapped. And type="button" is on all five buttons; you are right that half-applied is the one state that reads as an oversight.

On the contrast table — thank you for recomputing rather than passing on the figure you were handed. One of those numbers reaching you wrong (2.19:1 against the correct 2.43:1) is a good argument for the habit, even though the conclusion held. Agreed all five are colour-token changes rather than markup and belong with FileDropzone in their own pass, so I have left them.

Verified in the built bundle rather than the source: no hardcoded id, aria-labelledby emitted, aria-atomic absent as documented. svelte-check 0 errors / 0 warnings, build and lint clean. And thank you for checking the .field input rewrite did not strip the textarea's styling — that was a real risk in the CSS change and I had not confirmed it.

[dobby-coder]

Thanks for the detailed rundown — I'm on it now, taking a look at 0519f4c and the fixes across the progress label, aria-live wording, aria-valuenow clamping, citizen label qualifiers, and the flex: 1 cleanup, then I'll post a consolidated review on this PR.

[dobby-coder]

Approving. This clears the CHANGES_REQUESTED this bot left on 2026-07-29; nothing below blocks the merge.

Both blockers from the last round are genuinely fixed, and I checked the rendered output rather than only the source:

• $props.id() emits a per-instance id, so the label association no longer depends on there being exactly one ProgressBar on the page.
• The clamp holds at every boundary, and one derived value feeds the fill, aria-valuenow, aria-valuetext and the visible text, so they cannot diverge.
• aria-atomic is absent from the component, so the comment describing a bare percentage announcement is accurate. The single aria-atomic="true" in .svelte-kit/output is SvelteKit's own route announcer in app.*.js, not this component.

Checks I ran on 0519f4c after a fresh install: pnpm check reports 333 files, 0 errors, 0 warnings; pnpm lint and pnpm build both exit 0.

Two notes, neither blocking.

1. The description still carries the claim this commit removed from the file

The inline comment covers the sibling slip in the code comment. The description says:

aria-live="polite" sits on the container rather than the track, so the label is part of the announcement instead of a bare number.

That is the pre-fix reasoning. The comment you rewrote in this commit now says the opposite, correctly: with aria-atomic at its default of false, what gets announced is the changed node alone, a bare "42%", not the label and percentage together. You took the reword over aria-atomic="true" deliberately and gave the cost argument for it, so the code is right and the description is still describing the version that lost that argument.

It is a one-sentence body edit, so no branch push and no CI rerun. Something like "so the label stays the track's accessible name via aria-labelledby, while the announcement itself is the bare percentage" would match what shipped. Worth doing because the description is what a reader meets first, and this branch is specifically about not letting a description of accessible behaviour drift from the behaviour.

2. The success path has no announcement, at +page.svelte:105

Pre-existing and outside every diff hunk, so I cannot anchor it inline. The error path gained role="alert" here, but when sendState flips to done the top-level {#if} swaps the whole form out: the aria-live progress region unmounts, .success-box carries no role="status", and the focused submit button stops existing, so focus falls back to <body>. A screen reader user gets progress announcements and then silence, with the virtual cursor reset, while the failure case announces itself. role="status" on .success-box, or moving focus to its <h2>, would close it.

Reasonable to defer to the same pass as FileDropzone and the colour tokens, since it is page-level focus management rather than control naming.

Nothing else came up. The five contrast items stay where we left them, as agreed. I did recompute the one colour this diff actually adds: .field-label at #444 on white is 9.74:1, which passes AA with room.

[dobby-coder]

The clamp is right and the reasoning behind it is right: the value arriving here is already clamped upstream, so the component's own clamp is belt and braces. Only the attribution is wrong.

The app's onProgress is (pct: number) => (progress = pct) at +page.svelte:52, a bare assignment that clamps nothing. The clamping is the SDK's, at packages/pg-js/src/crypto/encrypt.ts:112: Math.min(100, Math.round((uploaded / totalSize) * 100)).

It matters slightly more than a usual comment nit because this is the reusable lib/components copy a docs reader lifts, and someone who reads this and goes looking in +page.svelte for the clamp will not find one. "even though the SDK clamps before calling it" would be accurate.

The 5 MB chunk figure in the comment above checks out: DEFAULT_UPLOAD_CHUNK_SIZE = 5_000_000 at encrypt.ts:14.

[dobby-coder]

Approved: #152 (review)

reviewDecision is now APPROVED and mergeStateStatus is CLEAN — the prior CHANGES_REQUESTED is actually cleared. Both blockers checked against the rendered output (not just source), and pnpm check/lint/build all pass clean on 0519f4c.

Two non-blocking notes left, one new: the PR description still argues the pre-fix reasoning for aria-live="polite" even though the code and comment now say the opposite (worth a one-line edit, no push needed), and the success-path announcement gap at +page.svelte:105 is pre-existing and fine to defer with the rest of the a11y pass.

Everything else came back clean — dropped a couple of prose flags that were about my own writing, not yours.