Upgrading to 3.5
3.5 adds app layouts, apps in several languages, a title template, plurals and
the visitor’s light or dark choice. None of these need a change to an existing
app. Three things do: where a block’s position keys apply, the forms the app
icon may take, and, for apps on Foundation 2.0, the navbar’s sticky prop.
pwf validate reports the icon; the other two are visible on the page.
1. Position keys apply to the block wrapper
position, top, right, bottom, left, inset, zIndex and
alignSelf in a block’s style now apply to the element the renderer wraps
the block in, not to the block’s own root. A fixed or sticky block is now
positioned against the page, as its author meant, and not inside a wrapper
that ignored it.
One case changes how a page looks: a sticky block inside a row whose items
stretch (a two-column grid or stack, a sidebar beside the content). A
stretched wrapper is as tall as the row, so it has no room to stick. Give the
block alignSelf: "start":
{ "id": "toc", "type": "toc", "style": { "position": "sticky", "top": "1rem", "alignSelf": "start" } }A fixed navbar (position: "fixed") needs nothing more; a fixed navbar inside
a stretched row takes alignSelf: "start" too.
2. The app icon
brand.favicon in app/definitions/appearance.json is one of:
- a media file of the app,
media/<file>(served aspwpack/media/<file>); - a file of
public/(public/favicon.ico, or as served,favicon.ico); - an absolute
https://address.
Anything else is an error in pwf validate and pwf build
(FAVICON_INVALID): an http:// address (mixed content, which the browser
blocks), a file the app does not have, and the served form
pwpack/media/<file>, for which the message names the file to write instead,
media/<file>. Documents now link the icon with its type
(<link rel="icon" type="image/png">).
3. Foundation 2.0: the navbar has no sticky
Foundation 2.0 removes the navbar’s sticky prop. Make a navbar stay at the
top with its block style:
{ "id": "nav", "type": "navbar", "style": { "position": "sticky", "top": 0, "zIndex": 100 } }Inside a stretched row, add alignSelf: "start" (section 1).
4. Fonts are the app’s own files
The engine knows no font service: a family a theme names is loaded only from
the app’s own WOFF2 files, listed in the theme’s fonts
(media/fonts/<file>.woff2). A family named with no files is drawn in its
fallback, and pwf validate warns (FONT_FILES_MISSING). Migrate each family
once, for example from its Fontsource package:
pwf font add Inter --from npm:@fontsource/inter --weight 400 --weight 700--from also takes a local .woff2 file or folder, or an https:// address.
The command copies the files and their licence into media/fonts/, records
them in media/provenance.json and declares them in the theme; the build then
serves them hashed, preloads the body font and draws a metric-matched stand-in
until it arrives. A block can no longer declare a font origin, and
@pwfabric/contracts/webfonts (the old webfont allow-list) is removed. When a
font file’s metrics cannot be read, its stand-in is the plain local font and
pwf validate warns (FONT_METRICS_UNREADABLE): the text may move when the
font arrives.
Also new in 3.5
Nothing here needs a change; each is described in the specification.
- App layout:
app/layout.receipt.jsonwraps every page, its one{ "type": "pw:page" }slot holding the page; a page opts out with"layout": false. Its blocks stay mounted from page to page. - Apps in several languages:
localesanddefaultLocalein the plan,app/messages/<lang>.json, a receipt’spathper locale,t('<id>')in receipts, one document per page per locale,hreflangand one sitemap. - Title template:
titleTemplatein the plan ("%s · Acme Bakery"). - Plurals in messages:
{n, plural, one {# item} other {# items}}. - The visitor’s colour scheme:
context.colorSchemeandcontext.setColorSchemefor a light or dark switch. - A plan’s
public/files, scripts behind consent, headers and redirects. pwf validatenow refuses a pinned pack that is not cached (PIN_NOT_CACHED), aspwf builddoes, with the same fix:pwf add <id>@<version>.