Stop drawing an errored field twice when it takes focus

Focusing a field that already had an error painted two rings at once:
the notched outline stayed in the error colour and the gradient focus
ring went on top of it in the brand's violet-to-cyan. Two rings, two
colours, one field -- and on the textarea at two different radii, which
is what made it visible enough to report.

The ring itself is worth keeping; it is how focus reads everywhere else.
It just has to agree with the state it decorates, so while the field is
invalid it is built from the warn colour. The result is one red
indication that brightens on focus, and valid fields keep the brand
gradient.

Verified in both themes: an errored focused field's ring and outline are
both the warn colour, a valid focused one still gets the brand gradient.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

.dockerignore

@@ -11,6 +11,9 @@ tmp
 .claude
 docs
 landing-e2e
+
+# tools/ IS needed: the build stage copies docker-install-deps.sh from it.
+# The mock API servers in there are dev-only but too small to be worth excluding.
 **/*.spec.ts
 test-output
 .env

.env.example

@@ -1,10 +1,21 @@
-# Base URL of the Pireon API, without a trailing slash. Read on the server
-# only: the browser never talks to the API directly.
+# Copy to `.env`. Compose reads it on its own — for the runtime settings below
+# and for the build-time token. `.env` is gitignored; this file is not.
+
+# Base URL of the Pireon API, without a trailing slash. Read on the server only:
+# the browser never talks to the API directly.
 PIREON_API_URL=https://landing-api.pireon.dev/api
 
-# Host port the container is published on.
+# Only used if you uncomment `ports` in docker-compose.yml. By default the
+# container is not published on the host at all: the reverse proxy reaches it
+# over the compose network as `landing:3000`, and publishing a host port only
+# invites a collision with whatever else is on that number.
 LANDING_PORT=3000
 
-# Only needed to *build* the image: `@pi/ui` comes from the private Nexus.
-# Not read at runtime, and never baked into a layer — see Dockerfile.
+# Needed only to *build* the image: `@pi/ui` comes from the private Nexus.
+# Locally this is the value already sitting in ~/.npmrc:
+#
+#   grep nexus.pireon.dev ~/.npmrc
+#
+# Never baked into a layer — it is mounted as a BuildKit secret. An empty value
+# fails the build immediately with an explanation rather than a Nexus 401.
 NEXUS_TOKEN=

.gitignore

@@ -46,3 +46,13 @@ Thumbs.db
 
 .nx/polygraph
 .angular
+
+# Secrets. `.env` holds NEXUS_TOKEN, which compose reads at build time, so it
+# must never be committed — `.env.example` is the one that is.
+.env
+.env.*
+!.env.example
+
+# A per-machine npmrc would carry a Nexus token; the committed one at the repo
+# root deliberately holds none.
+.npmrc.local

Dockerfile

@@ -19,14 +19,12 @@ COPY package.json package-lock.json .npmrc ./
 
 # `@pi/ui` comes from the private Nexus, so the install needs a token — passed
 # as a BuildKit secret rather than a build ARG, which would be readable forever
-# in the image history. The npmrc it lands in is written and removed inside one
-# layer, so it leaves no trace even in this discarded stage.
+# in the image history. The script checks the secret actually holds something
+# before spending four minutes finding out from Nexus.
+COPY tools/docker-install-deps.sh ./tools/
+
 RUN --mount=type=secret,id=nexus_token,required=true \
-    sh -eu -c '\
-      printf "//nexus.pireon.dev/repository/npm-releases/:_authToken=%s\n" \
-        "$(cat /run/secrets/nexus_token)" > /tmp/npmrc; \
-      NPM_CONFIG_USERCONFIG=/tmp/npmrc npm ci --no-audit --no-fund; \
-      rm -f /tmp/npmrc'
+    sh tools/docker-install-deps.sh
 
 COPY nx.json tsconfig.base.json eslint.config.mjs ./
 COPY landing ./landing

README.md

@@ -18,10 +18,25 @@ npm run e2e        # Playwright end-to-end tests
 ## Deploying
 
 ```sh
-NEXUS_TOKEN=… docker compose build
+cp .env.example .env      # then fill in NEXUS_TOKEN
+docker compose build
 docker compose up -d
 ```
 
+Compose reads `.env` on its own, for the build token as well as the runtime
+settings. `.env` is gitignored; `.env.example` is the one that is committed. If
+you would rather not keep the token on disk:
+
+```sh
+NEXUS_TOKEN=… docker compose build
+```
+
+An empty or missing token fails the build in under a second with a message
+saying so. That check is there because the mount's own `required=true` only
+asserts the secret was *declared* — an empty one passes it and then surfaces a
+minute later as a Nexus 401 that reads like a credentials problem when it is
+really a forgotten variable.
+
 Two stages. The build one runs Nx and the Angular compiler over the whole
 workspace and is thrown away; only `dist/landing/analog` crosses into the
 runtime image, because Nitro vendors its own dependencies into that output —
@@ -56,15 +71,20 @@ API were in maintenance. `core/api.ts` gives each call an 8-second budget, which
 is what stands between a slow upstream and a hung render.
 
 The container runs with a read-only filesystem and `no-new-privileges`, with a
-tmpfs at `/tmp` for Nitro's scratch space. Put a reverse proxy in front for TLS
-and let it pass response headers through untouched: the app answers 503 with
+tmpfs at `/tmp` for Nitro's scratch space. The container publishes no host port: the reverse proxy reaches it over the
+compose network as `landing:3000`, and binding a host port only invites a
+collision with whatever else is on that number. `docker-compose.yml` carries a
+commented `ports` block for when you do want one.
+
+Put that proxy in front for TLS and let it pass response headers through
+untouched: the app answers 503 with
 `Retry-After` during maintenance and 404 for addresses it does not serve, and
 both matter to crawlers and CDNs.
 
 | Variable | Where | Default |
 | --- | --- | --- |
 | `PIREON_API_URL` | runtime | `https://landing-api.pireon.dev/api` |
-| `LANDING_PORT` | runtime, host side | `3000` |
+| `LANDING_PORT` | only if you publish a host port | `3000` |
 | `NEXUS_TOKEN` | **build only** | — |
 
 Copy `.env.example` to `.env`; compose reads it.

docker-compose.yml

@@ -24,8 +24,20 @@ services:
         - nexus_token
     image: pireon/landing:latest
     restart: unless-stopped
-    ports:
-      - '${LANDING_PORT:-3000}:3000'
+    # No `ports`. Publishing on the host collides with whatever else is using
+    # that number on the machine, and in production the only thing that needs
+    # to reach this is the reverse proxy — which does so over the compose
+    # network, by service name, on the port below.
+    #
+    #   proxy_pass http://landing:3000;
+    #
+    # To reach it from the host anyway (a quick check, or a deployment with no
+    # proxy in front), uncomment this and set LANDING_PORT to a free port:
+    #
+    # ports:
+    #   - '${LANDING_PORT:-3000}:3000'
+    expose:
+      - '3000'
     environment:
       # Where the public API lives. The only setting the app actually reads.
       PIREON_API_URL: ${PIREON_API_URL:-https://landing-api.pireon.dev/api}

landing-e2e/playwright.config.mts

@@ -12,6 +12,19 @@ const here = dirname(fileURLToPath(import.meta.url));
 const workspaceRoot = resolve(here, '..');
 const baseURL = process.env['BASE_URL'] || 'http://localhost:4200';
 
+/**
+ * The dev server is started on whatever port `BASE_URL` names, rather than
+ * always 4200.
+ *
+ * `reuseExistingServer` means Playwright will happily adopt whatever is already
+ * listening there — and if that is a different project's dev server, every test
+ * fails with "element(s) not found" while the real cause is that the page under
+ * test was never served. Set BASE_URL to move both halves at once:
+ *
+ *   BASE_URL=http://localhost:4280 npx nx e2e landing-e2e
+ */
+const port = new URL(baseURL).port || '4200';
+
 export default defineConfig({
   testDir: './src',
   outputDir: resolve(workspaceRoot, 'dist/.playwright/landing-e2e/test-output'),
@@ -25,7 +38,7 @@ export default defineConfig({
     trace: 'on-first-retry',
   },
   webServer: {
-    command: 'npx nx run landing:serve',
+    command: `npx nx run landing:serve --port=${port}`,
     url: baseURL,
     reuseExistingServer: true,
     timeout: 180_000,

landing/src/app/core/copy.ts

@@ -78,6 +78,7 @@ export interface Copy {
     email: string;
     organisation: string;
     hours: string;
+    hoursHint: string;
     message: string;
     messageHint: string;
     consent: string;
@@ -167,6 +168,7 @@ const es: Copy = {
     email: 'Correo',
     organisation: 'Organización',
     hours: 'Horas por semana',
+    hoursHint: 'Por ejemplo, 4',
     message: 'Mensaje',
     messageHint: 'Mínimo 20 caracteres.',
     consent: 'Acepto que guardéis mis datos para responderme.',
@@ -264,6 +266,7 @@ const en: Copy = {
     email: 'E-mail',
     organisation: 'Organisation',
     hours: 'Hours per week',
+    hoursHint: 'For example, 4',
     message: 'Message',
     messageHint: 'At least 20 characters.',
     consent: 'I agree to have my details stored so you can reply.',
@@ -361,6 +364,7 @@ const ca: Copy = {
     email: 'Correu',
     organisation: 'Organització',
     hours: 'Hores per setmana',
+    hoursHint: 'Per exemple, 4',
     message: 'Missatge',
     messageHint: 'Mínim 20 caràcters.',
     consent: 'Accepto que deseu les meves dades per respondre’m.',

landing/src/app/ui/contact-form.scss

@@ -1,7 +1,14 @@
+// The gap has to beat the distance from a field to its own error message,
+// which Material renders flush underneath it — 0px. At 1.25rem the message
+// ended up 6px from the *next* field's label and 0px from its own field, so
+// "Falta el nombre" read as the caption of "HORAS POR SEMANA" rather than of
+// the field above it. The three lines have to group with the field they belong
+// to, which means the space between rows must be visibly larger than the space
+// inside one.
 .landing-form {
   display: flex;
   flex-direction: column;
-  gap: 1.25rem;
+  gap: 2rem;
 }
 
 .landing-form__kind {
@@ -28,3 +35,112 @@
   margin: 0;
   color: var(--pi-color-warn, #d64545);
 }
+
+// The hours field sits inside an @if, and that is what breaks its label.
+//
+// Angular Material measures an outlined field's floating label once, on init,
+// and writes the result to the element as an inline
+// `transform: var(--mat-mdc-form-field-label-transform, translateY(-50%) …)`.
+// A field created inside a conditional block is measured before it has any
+// geometry, so the value it keeps is the unfloated one: the label ends up 5px
+// above the wrapper instead of 18, straddling the 2px outline and struck
+// through by it.
+//
+// `@pi/ui` already publishes the right geometry for every other field
+// (`translateY(-3rem) scale(1)`, a 48px label box), and that rule matches this
+// one too — it simply loses to the inline style. `!important` is what beats an
+// inline declaration, and it is restating the library's own values, not
+// inventing new ones.
+:host ::ng-deep .pi-field.pi-form-field__number {
+  .mdc-notched-outline .mdc-floating-label {
+    height: var(--pi-spacing-xxxx-large) !important;
+  }
+
+  .mdc-text-field:not(.mat-form-field-no-animations) .mdc-floating-label {
+    transform: translateY(-3rem) scale(1) !important;
+  }
+}
+
+// Two things the library gets wrong once a field is in a real state.
+//
+// 1. The label changes shape when you focus it. `@pi/ui` applies the theme's
+//    label typography under `:not(.mdc-text-field--focused)`, so text-transform,
+//    letter-spacing and weight all fall away the moment the field takes focus:
+//    "MENSAJE *" becomes "Mensaje *" in a lighter face, and the label visibly
+//    reflows under the cursor. Restated here without that guard. Colour is
+//    deliberately left alone — Material tints the label on focus, and that part
+//    is wanted.
+//
+// 2. The focus ring is a stadium on the textarea. Both the notched outline and
+//    the gradient ring take their radius from `--pi-theme-field-radius`, which
+//    the `alternative` shell sets to 999px. That is right for a 48px-tall input
+//    and wrong for a 112px-tall textarea: the two shapes stop coinciding and
+//    the field is drawn twice, once in the error colour and once in the
+//    gradient, offset from each other. A fixed radius makes them agree again.
+:host ::ng-deep {
+  .pi-field .mdc-text-field:not(.mdc-text-field--disabled) .mdc-floating-label {
+    text-transform: var(--pi-theme-field-label-transform, none);
+    letter-spacing: var(--pi-theme-field-label-letter-spacing, normal);
+    font-weight: var(--pi-theme-field-label-weight, inherit);
+  }
+
+  .pi-field.pi-form-field__textarea {
+    --pi-theme-field-radius: 1.25rem;
+  }
+}
+
+// Error states, which move the form around and read wrong.
+//
+// 1. Submitting an incomplete form shoved everything below it downwards.
+//    Material's subscript strip is 10px tall while a field is valid and 24px
+//    once it carries a message, so every errored field grew the form by 14px at
+//    once — the fields under the cursor jumped out from under it. Reserving the
+//    taller height up front costs 14px of whitespace and buys a form that does
+//    not move.
+//
+// 2. `pi-checkbox` renders its message as an inline span straight after the
+//    label, so it ran on as part of the sentence: "Acepto que guardéis mis
+//    datos para responderme. Hace falta tu consentimiento". It belongs on its
+//    own line, like every other field's message.
+:host ::ng-deep {
+  .pi-field .mat-mdc-form-field-subscript-wrapper {
+    min-height: 1.5rem;
+  }
+
+  // Its own line, in space reserved for it. Left in flow it would push the
+  // submit button 25px down at the exact moment you press it — the same jump
+  // the reserved subscript above removes for the fields.
+  .pi-checkbox {
+    position: relative;
+    padding-bottom: 1.25rem;
+  }
+
+  // Nothing in the library styles this class, so the message inherited the
+  // body colour and read as ordinary text next to four red ones.
+  .pi-checkbox__error {
+    display: block;
+    position: absolute;
+    left: 0;
+    bottom: 0;
+    color: var(--pi-color-warn);
+    // `mat-error` renders the other four at 12px; this one inherited 15px.
+    font-size: var(--pi-font-size-x-small, 0.75rem);
+  }
+}
+
+// Focusing a field that already has an error drew it twice: the notched
+// outline stays in the error colour, and the gradient focus ring is painted on
+// top of it in the brand's violet-to-cyan. Two rings, two colours, one field —
+// and on the textarea, at two different radii, which is what made it obvious.
+//
+// The ring is worth keeping: it is how focus reads on every other field. It
+// just has to agree with the state it is decorating, so while the field is
+// invalid the ring is built from the warn colour instead of the brand one. The
+// field ends up with a single red indication that still brightens on focus.
+:host ::ng-deep .pi-field .mat-form-field-invalid {
+  --pi-theme-field-focus-gradient: linear-gradient(
+    120deg,
+    var(--pi-color-warn),
+    var(--pi-color-warn-200, var(--pi-color-warn))
+  );
+}

landing/src/app/ui/contact-form.ts

@@ -115,7 +115,17 @@ type Kind = 'contribute' | 'request';
               <pi-label [isRequired]="true">{{ copy().form.organisation }}</pi-label>
             </pi-text-field>
           } @else {
-            <pi-number-field [formField]="contact.hours_per_week">
+            <!--
+              The placeholder is not decoration. Without one, Material leaves
+              this label in its unfloated position and writes an inline
+              translateY(-50%) that drops the text straight onto the outline's
+              top border, struck through by it. Every other field here has a
+              placeholder, which is why this was the only one that looked wrong.
+            -->
+            <pi-number-field
+              [formField]="contact.hours_per_week"
+              [placeholder]="copy().form.hoursHint"
+            >
               <pi-label>{{ copy().form.hours }}</pi-label>
             </pi-number-field>
           }

tools/docker-install-deps.sh

@@ -0,0 +1,52 @@
+#!/bin/sh
+# Installs the workspace's dependencies inside the image.
+#
+# Split out of the Dockerfile so a failure prints this file's own message
+# instead of BuildKit echoing a twenty-line inline shell twice.
+set -eu
+
+TOKEN_FILE=/run/secrets/nexus_token
+NEXUS_PATH=//nexus.pireon.dev/repository/npm-releases/
+
+# `required=true` on the mount only asserts the secret was declared, not that it
+# holds anything. An empty one sails past it and surfaces four hundred packages
+# later as a Nexus 401 that reads like a credentials problem.
+if [ ! -s "$TOKEN_FILE" ]; then
+  cat >&2 <<'MSG'
+
+ERROR: the nexus_token build secret is empty.
+
+@pi/ui is published to the private Nexus, so the install needs a token.
+
+  compose:  NEXUS_TOKEN=... docker compose build
+            or put NEXUS_TOKEN in .env, which compose reads on its own
+  docker:   docker build --secret id=nexus_token,env=NEXUS_TOKEN .
+
+Locally the value is the one already in ~/.npmrc:
+
+  grep nexus.pireon.dev ~/.npmrc
+
+MSG
+  exit 1
+fi
+
+# Written and removed inside a single layer, so it leaves no trace even in this
+# stage — which is discarded anyway.
+NPMRC=/tmp/npmrc
+printf '%s:_authToken=%s\n' "$NEXUS_PATH" "$(cat "$TOKEN_FILE")" > "$NPMRC"
+
+if NPM_CONFIG_USERCONFIG="$NPMRC" npm ci --no-audit --no-fund; then
+  rm -f "$NPMRC"
+else
+  status=$?
+  rm -f "$NPMRC"
+
+  if [ "$status" -ne 0 ]; then
+    echo "" >&2
+    echo "npm ci failed. If the error above is a 401 from nexus.pireon.dev," >&2
+    echo "the token was present but is not valid for npm-releases." >&2
+    echo "" >&2
+  fi
+
+  exit "$status"
+fi