Plugin settings page (M5 part 3a-2)

[txoof-bot]

Part of #238 (the last piece of part 3a, with #251 and #252). Merge order (top-down): merge this PR first, into 238-settings-form (#252); then merge #252 into main. No conflicts that way.

What changed

The plugin settings page: /plugins/<n>/settings?id=<id>.

• Layout as agreed (2026-10-08):
  • The plugin's name comes first.
  • Then "Settings of this plugin", then "When and how it is shown" (display time, refresh, layout, level).
  • The other shared settings are folded under More settings. It opens by itself when one of them has an error or a value that is not the default.
  • A folded Technical information part has the id, type, storage folder and the place in the config file.
• Each field: help text, (required) where needed, the setting's key, the limits for numbers, and "Default: …".
  • A secret (an API key) is a password field that never shows the saved value. Leave it empty to keep it.
  • A setting the form can't show (a group of settings) is shown as written in the file, to be changed there. If it holds a secret, it is shown only as "set".
• Save writes only what changed and applies it at once (3a-1). It comes back with "Saved." If any value has an error, nothing is saved, and each error is shown next to its field with what was typed (a typed secret is never shown again).
• Active Plugins has a Settings link for each plugin. The "type them into the config file" notes are gone.
• Plugin Library: after Add, the new plugin's settings page opens: "Added. Fill in its settings here, then Save."
• Setting helpers:
  • paperpi.plugin.setting(..., helper="location") names a helper for a setting.
  • paperpi.web.helpers.HELPERS holds a function per name that adds HTML under the field. A name it doesn't know adds nothing, so the plain field still works.
  • The list is empty now; the first helper (location) comes in 3c.
• Docs: README web section, docs/writing-plugins.md (which field each setting type gets; helper=), docs/decisions/web-interface.md, the address table in app.py.

Choices made without asking:

• Numbers are plain text fields, not the browser's number field. The phone number keypad is offered only for numbers that can't be below 0, because many phone keypads have no minus key (latitude in Rio is negative).
• A choice whose value in the file is not one of the choices shows "(not one of the choices: …)" instead of quietly picking the first choice.
• "Saved." is also shown when nothing changed.

Follow-up (not in this PR): some shared help texts were written for the config file ("see Layouts above", "leave it out to use…") and read a little oddly on the page. A later PR can give the page its own short wording.

Area

web (src/paperpi/web/: app.py, forms.py, helpers.py, plugins.py, templates, style.css), core (plugin.py: setting(helper=), helper_of), docs.

Tests

New tests/test_web_settings.py: link from Active Plugins, groups and folding, saving and applying, errors shown again with nothing saved, check boxes on and off, add → settings page, changed meanwhile, unknown type, out-of-range place, a value not in the choices, secrets never on the page, a list to tick, a read-only setting, the hand-edits note, the helper hook.

• uv run pytest passes (1394 on the Pi, -n auto)
• uv run ruff check . passes
• Hardware tests run on the Pi (only if display or driver code changed): not needed

Images

No screenshot yet: there is no browser on the Pi in this session. The page's HTML is checked by the tests. I can add a screenshot from another device if you want one.

Review

• Review agents' comments answered: 2 local reviews (code + tests, security + docs) before the first push; all findings fixed in the second commit, except two small ones:
  • The page reads the file twice per view.
  • A plugin of an unknown type still gets a Settings link, which shows the list with a clear message.

Only txoof approves and merges this PR.

🤖 Generated with Claude Code