No description
Find a file
Michał Kopeć 9277e344ec Let a service supply its own language control
scribe stores the language per USER, in its database - `PATCH /api/me`,
whose docstring says "the language choice follows the user, not the
browser". chrome's is a cookie, which is browser-local and therefore
strictly weaker for that case.

Adopting the shell would otherwise have quietly swapped a preference that
follows you to another machine for one that does not, and left two
switchers on the page disagreeing about the same setting.

`language_switcher=False` makes the shell stand down. Only the language
control: the theme toggle is unaffected, which the test pins, because
scribe's theme IS chrome's - the same localStorage key and the same three
values, so that one is a straight swap.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-10-04 20:50:41 +02:00
chrome Let a service supply its own language control 2026-10-04 20:50:41 +02:00
tests Let a service supply its own language control 2026-10-04 20:50:41 +02:00
.gitignore chrome: the shared shell, extracted from four copies 2026-10-04 12:34:13 +02:00
LICENSE-webawesome.md chrome: the shared shell, extracted from four copies 2026-10-04 12:34:13 +02:00
pyproject.toml Let a service supply its own language control 2026-10-04 20:50:41 +02:00
README.md Let a service supply its own language control 2026-10-04 20:50:41 +02:00
vendor-webawesome.sh chrome: the shared shell, extracted from four copies 2026-10-04 12:34:13 +02:00

chrome

The shared shell for the internal services: one page frame, one palette, one set of components, one implementation of the handful of things every service needs (config readers, proxy auth, /healthz, i18n, cache-busted assets).

It exists because the same stylesheet had been copied into four repositories and had started to drift — along with theme.js, the asset() helper and the error pages. A token change should be one commit here and a version bump there, not four hand-edits with one forgotten.

What's in it

Module Replaces
chrome.app.Chrome per-service app factory boilerplate, error pages, static mounts
chrome.config three near-identical _bool/_int/_list env readers
chrome.auth agent-bridge's Remote-User + proxy-key check
chrome.health four copies of /healthz
chrome.i18n homepage's pl/en machinery, which nothing else could reuse
chrome.assets two different cache-busting strategies, one of them broken in containers
templates/base.html four page shells
static/tokens.css four copies of the design tokens

UI components

Web Awesome (MIT, Fonticons) is vendored under chrome/static/wa/. The autoloader registers each <wa-*> element the first time it appears, so there is no per-component import list.

Components are styled inside a shadow root, which means a page rule cannot reach into one. That is the point: "this input is the wrong width" stops being a thing that can happen. Customise through --wa-* tokens and ::part().

Note that Combobox, Date Picker, File Input and the chart components are Web Awesome Pro, and are not vendored here. Use a native control or a different component.

Upgrading Web Awesome

./vendor-webawesome.sh 3.15.0   # then commit the diff

Plain curl and tar against the npm registry — no npm install, no node_modules, no lockfile, nothing for CI or a Containerfile to run. The script prunes type definitions and IDE metadata (~13M down to ~3.4M) and keeps only the en and pl translations.

Using it

from fastapi import FastAPI
from chrome.app import Chrome

app = FastAPI()
ui = Chrome(
    app,
    service="marketplace",
    version="0.2.0",
    title="Skills Marketplace",
    templates_dir=HERE / "templates",
    static_dir=HERE / "static",
    locales_dir=HERE / "locales",
)

@app.get("/")
def index(request: Request):
    return ui.render(request, "index.html", things=[...])

Templates {% extends "base.html" %} and fill content. Service templates and chrome's are both on the loader path, service first.

Depending on it

Pin a tag, not a branch:

dependencies = [
  "chrome @ git+https://git.wierzbowa.cloud/michal/chrome@v0.5.0",
]

For the edit loop, install it editable alongside the service: pip install -e ../chrome.

Theme convention

Pages use data-theme="light|dark|system" on <html>, which is what the services have always used. Web Awesome drives light/dark from a wa-light / wa-dark class instead; base.html and theme.js own that mapping, so no service or stylesheet needs to know about it.

Mounting under a prefix

A service whose reverse proxy forwards only certain path prefixes can move both static trees underneath one of them:

Chrome(app, ..., mount_prefix="/ui")

chrome's assets then live at /ui/chrome/... and the service's at /ui/static/..., Web Awesome's versioned path included. agent-bridge needs this: its design (D-0008) puts everything behind exactly two proxied prefixes, /ui and /api, so a third top-level path would be unreachable behind Caddy.

Per-request page context

Flask's context processors, with the app object taken out:

ui.page_context = lambda request: {"user": current_user(request)}

It runs on every render, because what it returns usually depends on who is asking. An explicit value passed at the render site wins over it.

Standing down the language switcher

Chrome(app, ..., language_switcher=False)

For a service that stores the choice per user rather than per browser. scribe keeps it in its database, so the language follows you to another machine; chrome's cookie does not. Two switchers disagreeing about one setting is worse than either alone.