Show Postulo's state as an icon before the instance address in the popup footer #9

New issue

Closed

opened 2026-09-30 15:19:46 +00:00 by tiagoagueda · 0 comments

tiagoagueda commented

2026-09-30 15:19:46 +00:00

Owner

The popup's footer holds the instance address, #server, a muted 12 px link that ends in an ellipsis when long (.server in src/style.css), hidden until an address and a token are both set (src/popup.js:53-60), then the settings gear (src/popup.html:66-77). The suggestion asks for an icon before the address: a green tick when Postulo is online, orange when it is unresponsive (“<1s”), a red X when it is offline but not in testing mode, and grey in testing mode, the orange and grey shapes left open.

The suggestion's “offline”, for red, is the code's unreachable: no answer within 20 s, a network error, a 5xx. Its “testing mode” is the code's offline, the testing switch. The connection state and its check belong to #4; this issue adds the response time, and the footer.

What the extension should do

When the popup opens, it shows the stored state at once, then times one check, the same as #4's (/healthz, as recommended there), and updates the icon when the answer comes or 1 s passes without one. Nothing measures response time today; request() in src/lib/api.js only gives up after 20 s. No check in testing, when not set up, or without the host permission.
What the popup learns goes into the same record, with how long the answer took, so the toolbar follows it. A popup closed before the answer writes nothing; the next background check decides.
The four states the suggestion names:
- Online: answered within 1 s. Green (--ok), a tick.
- Slow, the suggestion's “unresponsive”: see the first decision. Orange, a clock or an hourglass.
- Unreachable: nothing within 20 s, a network error, a 5xx, /healthz answering 503. Red (--error), an X.
- Testing: the switch is on. Grey (--muted), a flask or a pause sign.
Never colour alone (the extension's rule, src/style.css:450): each state has its own shape, and is named in words to a screen reader and in a title, for example “Postulo answers”, “Postulo is slow to answer”, “Postulo cannot be reached”, “The testing switch is on”. Icons inlined from lucide-static v1.41.0, as the gear is; the shapes are suggestions.
A new colour. src/style.css has --ok, --error, --muted and --brand, each with a dark variant, and no orange or amber. A --warn token is new, light and dark, its contrast against --paper checked in both (3:1 at least, the floor for an icon).
One record, two places: the footer and the toolbar icon (#4) cannot disagree. With both issues' recommendations, the toolbar icon is in colour exactly when the footer is green or orange.

Decisions for this repository

What “unresponsive (<1s)” means. Proposed reading: orange when Postulo answered but took longer than 1 s, or has not answered after 1 s while the 20 s timeout runs; green when it answered within 1 s; red when nothing came within 20 s. The alternative: orange whenever there is no answer within 1 s, the check cut there (AbortSignal.timeout). Both draw the line at 1 s; under the alternative, a Postulo that hangs stays orange and never turns red. Recommended: the first. A timing may include setting up the connection, so a first check can read slower than the next.
States the suggestion does not name.
- Not set up: there is no address to stand before, and the popup's top note already says so. Recommended: no icon, as today. The alternative: the grey icon, and “Not set up” where the address goes.
- Host permission missing and token refused (401 or 403): Postulo may be up, but nothing reaches it, or is accepted, until the settings are fixed. Recommended: red, with shapes of their own (a lock, a key), titled with the existing noPermission and tokenRefused. The alternative: both show the red X, told apart only by the title.
Timing the background's check too, or only the popup's. Recommended: both, so what the footer shows first is recent.

The browser behaviour here is documented (Chrome, MDN), not tried in a real browser.

Needs from the server

Nothing: /healthz exists, is public and is not throttled. Not filed on postulo/postulo.

Documents and translations

PRIVACY.md: the GET /healthz row #4 adds must also say it is made each time the popup opens.
test/i18n.test.mjs requires every new key in all 40 _locales at once, with identical placeholders: each state's name costs 40 translations in the same commit. It also fails on a key the code never names literally, so no key is built from a state's name.

Done when

Under the reading chosen, here the first: a Postulo answering quickly shows a green tick named in words; answering after more than 1 s (behind a proxy made to wait), orange, still orange once the answer comes; refusing the connection, red at once; never answering, orange after 1 s, red after 20 s.
With the testing switch on, grey, and no request reaches Postulo.
Permission missing and token refused show as decided, each with its reason in words.
The toolbar icon and the footer agree in every case.
A screen reader says the state in words; the orange passes its contrast check in both themes.
A pure function from record and timing to footer state is tested with node --test.

From the list of extension improvements of 2026-09-30.

The popup's footer holds the instance address, `#server`, a muted 12 px link that ends in an ellipsis when long (`.server` in `src/style.css`), hidden until an address and a token are both set (`src/popup.js:53-60`), then the settings gear (`src/popup.html:66-77`). The suggestion asks for an icon before the address: a green tick when Postulo is online, orange when it is unresponsive (“<1s”), a red X when it is offline but not in testing mode, and grey in testing mode, the orange and grey shapes left open. The suggestion's “offline”, for red, is the code's `unreachable`: no answer within 20 s, a network error, a 5xx. Its “testing mode” is the code's `offline`, the testing switch. The connection state and its check belong to #4; this issue adds the response time, and the footer. ## What the extension should do 1. When the popup opens, it shows the stored state at once, then times one check, the same as #4's (`/healthz`, as recommended there), and updates the icon when the answer comes or 1 s passes without one. Nothing measures response time today; `request()` in `src/lib/api.js` only gives up after 20 s. No check in testing, when not set up, or without the host permission. 2. What the popup learns goes into the same record, with how long the answer took, so the toolbar follows it. A popup closed before the answer writes nothing; the next background check decides. 3. The four states the suggestion names: - **Online**: answered within 1 s. Green (`--ok`), a tick. - **Slow**, the suggestion's “unresponsive”: see the first decision. Orange, a clock or an hourglass. - **Unreachable**: nothing within 20 s, a network error, a 5xx, `/healthz` answering 503. Red (`--error`), an X. - **Testing**: the switch is on. Grey (`--muted`), a flask or a pause sign. 4. **Never colour alone** (the extension's rule, `src/style.css:450`): each state has its own shape, and is named in words to a screen reader and in a `title`, for example “Postulo answers”, “Postulo is slow to answer”, “Postulo cannot be reached”, “The testing switch is on”. Icons inlined from lucide-static v1.41.0, as the gear is; the shapes are suggestions. 5. **A new colour.** `src/style.css` has `--ok`, `--error`, `--muted` and `--brand`, each with a dark variant, and no orange or amber. A `--warn` token is new, light and dark, its contrast against `--paper` checked in both (3:1 at least, the floor for an icon). 6. **One record, two places**: the footer and the toolbar icon (#4) cannot disagree. With both issues' recommendations, the toolbar icon is in colour exactly when the footer is green or orange. ## Decisions for this repository - **What “unresponsive (<1s)” means.** Proposed reading: orange when Postulo answered but took longer than 1 s, or has not answered after 1 s while the 20 s timeout runs; green when it answered within 1 s; red when nothing came within 20 s. The alternative: orange whenever there is no answer within 1 s, the check cut there (`AbortSignal.timeout`). Both draw the line at 1 s; under the alternative, a Postulo that hangs stays orange and never turns red. **Recommended:** the first. A timing may include setting up the connection, so a first check can read slower than the next. - **States the suggestion does not name.** - *Not set up*: there is no address to stand before, and the popup's top note already says so. **Recommended:** no icon, as today. The alternative: the grey icon, and “Not set up” where the address goes. - *Host permission missing* and *token refused* (401 or 403): Postulo may be up, but nothing reaches it, or is accepted, until the settings are fixed. **Recommended:** red, with shapes of their own (a lock, a key), titled with the existing `noPermission` and `tokenRefused`. The alternative: both show the red X, told apart only by the title. - **Timing the background's check too**, or only the popup's. **Recommended:** both, so what the footer shows first is recent. The browser behaviour here is documented (Chrome, MDN), not tried in a real browser. ## Needs from the server Nothing: `/healthz` exists, is public and is not throttled. Not filed on postulo/postulo. ## Documents and translations - `PRIVACY.md`: the `GET /healthz` row #4 adds must also say it is made each time the popup opens. - `test/i18n.test.mjs` requires every new key in all 40 `_locales` at once, with identical placeholders: each state's name costs 40 translations in the same commit. It also fails on a key the code never names literally, so no key is built from a state's name. ## Done when - Under the reading chosen, here the first: a Postulo answering quickly shows a green tick named in words; answering after more than 1 s (behind a proxy made to wait), orange, still orange once the answer comes; refusing the connection, red at once; never answering, orange after 1 s, red after 20 s. - With the testing switch on, grey, and no request reaches Postulo. - Permission missing and token refused show as decided, each with its reason in words. - The toolbar icon and the footer agree in every case. - A screen reader says the state in words; the orange passes its contrast check in both themes. - A pure function from record and timing to footer state is tested with `node --test`. From the list of extension improvements of 2026-09-30.

tiagoagueda added the

enhancement

label

2026-09-30 15:19:46 +00:00

tiagoagueda referenced this issue from Postulo/postulo-firefox

2026-09-30 15:19:47 +00:00

Make the grey icon and the review badge visible in Firefox and Firefox for Android, and settle the data declaration their requests affect #3

tiagoagueda referenced this issue from Postulo/postulo-thunderbird

2026-10-01 07:21:57 +00:00

Show Postulo's state as an icon before the instance address in the popup footer #6

tiagoagueda referenced this issue from a commit

2026-10-04 16:23:09 +00:00