Files
Calendar_Frontend/docs/gotchas.md
T
PaddyandClaude Opus 5.5 61e0393f01
Test and deploy / test (pull_request) Successful in 2m18s
Test and deploy / deploy (pull_request) Skipped
Support the read-only calendar role, show "Vorstand", fix link buttons
- Read-only role: /admin/me's permissions decide via canEditCalendar
  (lib/permissions.ts, mirrors the API's canWrite: only `access` writes).
  Read-only accounts see everything but get no "Neuer Termin", no "+", no
  "Veröffentlichen"; an event opens as "Termin ansehen" with locked fields.
  A "Nur lesen" badge in the header explains why. The API refuses their
  writes regardless.
- The management calendar is labelled "Vorstand"; the slug stays
  `management` for the API, URLs and iCal links.
- The subscription dialog's Apple/Google links are plain anchors styled with
  buttonVariants instead of Base UI Buttons rendering an <a>, which warned in
  dev and would have given them role="button".

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-08 22:15:31 +01:00

6.1 KiB

Gotchas

Things that turned out differently than expected, so the same wrong assumption isn't made twice. Collected during the rewrite (September 2026); the progress log in rewrite-plan.md has the context for each.

The API

  • PUT replaces the whole event. Missing fields fall back to status: 'PUBLIC' and repeatFrequency: ''. Always send the full EventPayload, even to change one field.
  • "0 rows were updated" comes back as HTTP 200. api.updateEvent turns that body into an error.
  • The API returns raw DB values. wholeDay is 0/1 (observed), and a deleted event's latest version is a row with every field null except status: 'DELETED'. parseApiEvent handles both.
  • GET /admin/me answers 200 for accounts without the calendar permission. Only apps says so.
  • The admin feed ignores includes_calendars; the public/iCal feeds follow it. So an event can appear in a calendar's subscription although it belongs to another calendar.
  • PRIVATE is in the status enum but nothing uses it. The app shows it read-only and keeps it.
  • The iCal times depend on the API process's time zone (formatted with local getHours(), labelled Europe/Berlin). Inferred from the code; not checked on the server.
  • Only the admin DB pool reads DB_PORT. A local calendar test database has to listen on 3306.

Time

  • Historical DST. Until 1995 German summer time ended in September, so 1994-10-02T22:00Z is 23:00 on 2 October in Berlin, not midnight on the 3rd. The date code gets it right; hand-written test data easily doesn't.
  • DST edges in forms. A nonexistent spring time (02:30) becomes 03:30 CEST; an ambiguous autumn time resolves to the second occurrence (CET). Pinned in lib/dates.test.ts.

Next.js / hosting

  • Standalone output doesn't serve .next/static by itself. Without the copy, CSS and JS are 404s. The postbuild script copies it into .next/standalone/.next/static; there is no public/ folder to copy (the favicon lives in app/). Verified by running .next/standalone/server.js.
  • NEXT_PUBLIC_* values are inlined at build time. They must be set when npm run build runs, not only when the server starts; lib/env.ts fails the build if they're missing.
  • The build prerenders / by calling the API. If the build machine can't reach it, the build still succeeds and the events section appears after the first revalidation (≤ 5 min).
  • With revalidate, a short API outage doesn't blank the landing page's events in a running server - Next keeps serving the cached fetch.
  • The dev server must run on port 4200. That's the origin the API and the admin app trust; another port breaks sign-out and the return redirect.
  • Dev runs React strict mode, so every calendar is fetched twice on load in development.
  • A leftover Angular node_modules makes npm install fail on a vite peer conflict.
  • npm 11 blocks install scripts by default (sharp, unrs-resolver didn't run theirs). Lint and build work without them; the app doesn't use next/image.
  • Vitest 5 needs @types/node ≥ 22; the config is vitest.config.mts because package.json has no "type": "module".

Deploy (Gitea Actions)

  • ~ in an rsync -e string is not your $HOME. rsync passes it to ssh without a shell, and ssh expands ~ from the passwd entry. In a job container those can differ, so a key written to $HOME/.ssh isn't found and known_hosts is read from somewhere else. The workflow uses absolute paths (SSH_DIR) and UserKnownHostsFile. Found in a local dry run.
  • The deploy target is Plesk's own subdomain folder (calendar.nachklang.art/), so rsync --delete must exclude what Plesk or Passenger keep there (tmp/, .well-known/). The first deploy replaces the Angular build - back it up first, and switch Plesk to the Node app right after the run, because the folder no longer works as a static site.
  • Plesk's chrooted SSH shell is broken on this server: bash segfaults in the chroot copy under /var/www/vhosts/nachklang.art, so sessions close right after login (and the command of an ssh host 'cmd' never runs, exit 255). The deploy user uses plain /bin/bash instead.
  • SSH is on port 42069, not 22 (22 is closed); the deploy user is plesk-nachklang, not nachklang.
  • Disable the Jenkins job before merging to master, or it runs ng build on the next push.

shadcn / Base UI

  • npx shadcn add imports cn from the npm package cn and adds it (plus next-themes for the toaster). This repo uses @/lib/utils like feedback, and toasts are light-only - fix both after every shadcn add.
  • Generated components have English labels ("Close"); translated to "Schließen" in dialog.tsx and sheet.tsx.
  • Base UI, not Radix: toggles expose aria-pressed (not data-state=on), triggers take a render prop (not asChild), menu radio items stay open unless closeOnClick is set.
  • A link that looks like a button is a plain <a className={buttonVariants(…)}>, not <Button render={<a …/>}>. Through Base UI's Button it warns in dev ("expected a native ", shown as Next's "2 issues" badge) and, with nativeButton={false}, gets role="button" - screen readers then announce a link as a button.
  • Base UI Select ignores synthetic click()s; automated tests need real pointer or keyboard input.
  • Closed dialogs stay in the DOM with data-closed until their exit animation ends - in a hidden tab that never happens. Query [data-open] when checking what's open.
  • In a hidden tab matchMedia change events don't fire either, so a resize there doesn't switch the sheet between bottom and side. It works in a visible window.

CSS

  • Responsive rules inside a capped panel need container queries, not viewport breakpoints (the edit sheet's footer labels use @container / @md:).
  • An implicit grid column grows to its longest unbreakable content (a URL) and defeats truncate; use grid-cols-[minmax(0,1fr)].
  • break-all splits ordinary words mid-word ("App-s"); only use it on text without spaces.