client-conventions

# Artemis client conventions Use `reference/migration-recipes.md` for migration examples. Check changes with `pnpm run lint` and `pnpm run prettier:check`. Prefer standalone components. ## Signals are mandatory for new code Use `input()` / `input.required()`, `output()`, `viewChild()` / `viewChild.required()`, `viewChildren()`, `signal()`, `computed()`, `effect()`, and `inject()` for dependency injection. The legacy decorators `@Input`, `@Output`, `@ViewChild`, `@ViewChildren`, `@ContentChild`, and `@ContentChildren` are banned throughout the application, including co-located specs and test helpers. `localRules/enforce-signal-apis` (`rules/enforce-signal-apis.mjs`) enforces this under `src/main/webapp/app/` and `src/test/javascript/`. Use signal APIs when changing an existing component; there is no unmigrated-module exception. A `computed()`, `linkedSignal()`, `effect()` or `afterRenderEffect()` must read a signal, or it never re-runs; a value that reads none is a constant and belongs in a plain `readonly` field (`@angular-eslint/reactive-context-must-read-signal`). Read a signal with `()` when checking its value; `@angular-eslint/no-uncalled-signals` catches accidental checks of the signal function. Keep Angular lifecycle hooks synchronous. Delegate work that awaits to a separate async method (`@angular-eslint/no-async-lifecycle-method`). Do not repeat a declaration in a component's metadata arrays (`@angular-eslint/no-duplicates-in-metadata-arrays`). ## Injection and services Declare every `inject()` field before any other class member (`@angular-eslint/inject-at-top`). Fields initialize in declaration order, so a getter called from an earlier initializer would read `undefined` from a service declared further down. Declare an application-wide service with `@Service()`, not `@Injectable({ providedIn: 'root' })` (`@angular-eslint/prefer-service-decorator`, autofixable). `@Service()` rejects constructor injection and cannot share a class with another Angular decorator. The rule still reports a `@Pipe` that is also injected as a service, and its autofix then breaks `ng build` with NG1006 (Vitest compiles JIT and does not notice), so keep `@Injectable` on such a pipe with a justified line-level disable and do not autofix it. Other provider metadata also keeps `@Injectable`. ## Checking access before a request Ask `AccountService` before sending a request that needs more than a signed-in user, above all one the client sends on its own (on sign-in, on page init, from the navbar): a refused request shows a 403 alert on the current page. Use its high-level methods such as `hasEditorAccess()` rather than `hasAnyAuthorityDirect(IS_AT_LEAST_EDITOR)`, which counts an administrator whose session the server does not grant the administrator rights. When no method fits, add one to `AccountService` and `MockAccountService` instead of combining authorities, module features and passkey state in the caller. ## `ngOnChanges` is banned Use `computed()` or `effect()`. Enforced at error level by `localRules/prefer-signal-reactivity-over-ngonchanges` (`rules/prefer-signal-reactivity-over-ngonchanges.mjs`) across `src/main/webapp/app`, `packages/tum-aet-ui/src/lib`, and `src/test/javascript`, including specs and undecorated base classes. This is a consistency ban, not a correctness fix. Angular does call inherited `ngOnChanges` hooks and does fire them for signal inputs, so existing uses are not dead code. A genuinely unavoidable case, meaning you need `SimpleChanges.previousValue` or `isFirstChange()`, or ordering before child initialisation, needs a detailed comment and a justified line-level `eslint-disable-next-line`. `ngOnInit` and `ngOnDestroy` are unaffected. ## Template control flow Use `@if`, `@for`, `@switch`. Never `*ngIf`, `*ngFor`, `*ngSwitch`. Every `@switch` has a `@default` (`@angular-eslint/template/require-switch-default`). Use `@default never;` when the cases cover the whole union or enum, so the strict template check reports a missing case, and an empty `@default {}` otherwise. Both render nothing for an unmatched value. Bind styles with `[style.prop]`, `[style.prop.unit]` or `[style]`, never `[ngStyle]` (`@angular-eslint/template/prefer-style-binding`); a constant is a static `style` attribute. Never bind `outerHTML` (`@angular-eslint/template/no-outerhtml`). Do not use `$any()` in templates (`@angular-eslint/template/no-any`). Prefer a typed template reference for DOM input values and a typed component method for library event payloads. ## Images and keyboard order Use `NgOptimizedImage` with `ngSrc` for images with known intrinsic dimensions or a positioned, sized container for `fill`. Mark an image `priority` only when it is expected to be the largest visible image on initial load. For arbitrary user images that must retain their intrinsic layout, keep native `src` and use appropriate loading and decoding hints. Give every `<img>` a useful, localized text alternative, or `alt=""` when the image is decorative or already described next to it (`@angular-eslint/template/alt-text`). Keep keyboard focus in DOM order; do not use a positive `tabindex` to reorder controls (`@angular-eslint/template/no-positive-tabindex`). Move markup when the DOM order is wrong. ## Redirecting from guards and resolvers A guard returns or emits `router.createUrlTree(...)`, or `new RedirectCommand(urlTree, options)` when it needs `replaceUrl`, `skipLocationChange` or `state`. This also applies inside RxJS and promise callbacks: return the redirect rather than throw it. The guards in one `canActivate` array run together, and the first emitted result that is not `true`, in array order, wins. A returned or emitted redirect waits for every guard ahead of it to return `true`; a thrown `RedirectCommand` bypasses that ordering and can redirect before an earlier authority check rejects the route. A resolver returns or emits a `RedirectCommand`; a `UrlTree` returned from a resolver becomes route data and does not redirect. Inside a resolver's RxJS operator or promise callback, it can throw the `RedirectCommand` instead. The router cancels the running navigation with a redirect that keeps its `replaceUrl` and `skipLocationChange`, and alerts shown before the throw still appear. Never call `router.navigate()` or `navigateByUrl()` in a guard or resolver. It cancels the running navigation on the spot and starts a new one, so the original `replaceUrl` and `skipLocationChange` are lost (Back then redirects forward again), a caller awaiting the original navigation receives `false`, and the navigation still happens when another guard rejects the route. A `return false` or `EMPTY` after the call changes nothing. `localRules/no-navigation-in-guard-or-resolver` (`rules/no-navigation-in-guard-or-resolver.mjs`) enforces this at error level under `src/main/webapp`. It follows the guard into nested callbacks, into methods of its own class reached through `this`, and into functions of the same file. It is file-local and does not resolve types, so it misses navigation in an injected service the guard calls, a `Router` from a base-class field, `const router = this.router` or `injector.get(Router)`, namespace imports, static helper calls and route objects without a marker key such as `path`. Moving the call into a service silences the rule without fixing anything. A `catchError` after a thrown redirect must rethrow what it does not handle. In specs, use the real router (`TestBed.inject(Router)`, no `MockRouter`) and assert the result: `router.serializeUrl(result as UrlTree)` for a returned redirect, or an `error` callback that receives a `RedirectCommand` for a thrown one. Do not assert a `navigate` spy. For guard combinations and browser history, route with `provideRouter(...)` and `provideLocationMocks()` as in `src/main/webapp/app/localci/shared/localci-guard.spec.ts`. ## Form labels Associate each visible form label with its native input using a matching `for` and `id`, or wrap the input in the label. For a custom control, connect the label to the input inside the component, not its host element. Use a heading or `span` for informational text that does not label a control; give groups of controls an accessible group name. The `@angular-eslint/template/label-has-associated-control` rule checks the label association, not the element choice or group names, in TUM AET UI and the client template areas listed in `eslint.config.mjs`. ## Copying objects In production `src/main/webapp/app/**/*.ts`, use the wrappers in `src/main/webapp/app/foundation/util/deep-clone.util.ts`: - `deepClone(x)` detaches nested state while preserving supported prototypes. - `cloneWith(x, { a, b })` deep-clones the source and applies overrides by reference. - `hydrate(new Course(), dto)` gives a parsed DTO its prototype. `rules/prefer-deep-clone.mjs` bans object spread, `Object.assign` and `structuredClone` in that scope, even for plain objects; specs are exempt. `eslint.config.mjs` also restricts direct lodash cloning imports. Array spread and object rest remain allowed. Shallow copies share nested state; `structuredClone` loses custom prototypes such as `dayjs`. Do not clone merely to notify a signal if nested identity must survive. For that case and the child-input identity boundary, read the cloning section of `reference/migration-recipes.md`. `packages/tum-aet-ui` is outside these application rules and must not import `app/` utilities. Choose copying behavior appropriate to the package's data and identity requirements. ## Styling Use TUM AET UI components (`@tumaet/ui-angular`) and Tailwind v4 utilities. Do not add Bootstrap or ng-bootstrap in new work. Colours use semantic tokens. Use TUM AET UI component variants, or `text-state-danger`, `text-state-success`, `text-state-warning`, `text-state-info` for plain markup. Never `--p-<color>-N` primitives, never `text-red-500`, never `text-danger`, never the superseded arbitrary `text-(--danger)` form. `localRules/no-raw-tailwind-color-palette` enforces the palette part across `src/main/webapp/app/**/*.html` and `packages/tum-aet-ui/src/lib/**/*.html`. **The Bootstrap ban is only partly enforced**: `localRules/no-bootstrap-classes` covers the migrated directories listed in `eslint.config.mjs`. The convention applies throughout the client even where lint does not enforce it. Add newly migrated directories to that list. Never hand-write PrimeNG root classes such as `class="p-button"` or `class="p-inputtext"`. Render the real PrimeNG component so its styles load deterministically. Enforced by `localRules/no-primeng-component-classes`. PrimeNG itself is a transitional fallback, used only when a TUM AET UI gap cannot reasonably be closed in the same change. Explain the contained fallback in the pull request. If TUM AET UI lacks a reusable capability, add or evolve a package component around native HTML, Angular Aria (`@angular/aria`, for composite widgets such as menus and tabs), or stable Angular CDK primitives, and keep Artemis-specific composition in the application. See `documentation/docs/developer/guidelines/tum-aet-ui-kit.mdx`. ## Other rules worth knowing Prefer `undefined` over `null`. Aim for full type safety; `localRules/no-as-any-cast` and `localRules/no-as-unknown-cast` block the usual escape hatches. Filenames are kebab-case. Full guidance: `documentation/docs/developer/guidelines/client-development.mdx`.