- 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>
93 lines
6.1 KiB
Markdown
93 lines
6.1 KiB
Markdown
# 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](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
|
|
<button>", 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.
|