webstatus-frontend

# webstatus-frontend This skill provides architectural guidance and conventions for the `frontend/` directory in `webstatus.dev`. ## Architecture & Technology - **Framework**: Built with **TypeScript**, **Lit**, and **Web Components**. - **UI Library**: Utilizes **Shoelace** component library. - **State Management**: Uses **Lit Context** for dependency injection and state management via a service container pattern (`<webstatus-services-container>`). - **API Interaction**: Communicates with the Go backend using TypeScript types generated from the OpenAPI specification (`make node-openapi`). ## Architecture For a technical breakdown of the Lit component hierarchy, frontend identity flows, and theming patterns, see [references/architecture.md](references/architecture.md). ## Guidelines (Do's and Don'ts) - **DO** cross-reference all TypeScript and CSS against the official Google TypeScript/HTML/CSS Style Guides. If you are unsure about a specific style rule, DO NOT assume; you MUST ask the user for clarification. - **DO** create new UI elements as custom elements extending Lit's `LitElement`. - **DO** leverage Shoelace components for common UI patterns. - **DON'T** introduce other UI frameworks like React or Vue. - **DO** use Lit Context to access shared services. - **DON'T** create new global state management solutions. - **DON'T** render the full page layout (header, sidebar, etc.) inside a page component. Page components should focus on route-specific content; `webstatus-app` provides the shell. - **DON'T** add generic class names to `shared-css.ts`. **DO** leverage Shadow DOM encapsulation and use composition with slots for reusable layout patterns. - **DO** write unit tests for all component logic. - **DO** place application-wide service providers within `WebstatusServicesContainer` to ensure a stable context hierarchy. - **DO** use specialized child components (the "Context Bridge" pattern) to consume global context if high-level components (like `WebstatusHeader`) don't reliably subscribe to context changes due to slotting or complex rendering lifecycles. - **DO** use Shoelace semantic CSS variables (e.g., `--sl-color-neutral-0`) for themeable properties to ensure cross-browser inheritance (Firefox/WebKit) without relying on unsupported selectors like `:host-context`. - **DON'T** directly use Shoelace variables (starting with `--sl-`) in component stylesheets. **DO** use custom variables defined in `_theme-css.ts` (e.g., `--color-background`, `--table-padding`) that act as a project-specific abstraction layer. - **DO** type `routerContext` cleanly as `createContext<Router | undefined>('router')` without referencing `AnyObject` (`Router<AnyObject, AnyObject>`), as `@vaadin/router` v2.0+ removed `AnyObject`. - **DON'T** use `// @ts-ignore` to silence TypeScript warnings around decorated Lit properties (`@provide({context: routerContext})`). Properly type the property/context so it passes `tsc --noEmit` without `@typescript-eslint/ban-ts-comment` warnings. - **DON'T** add redundant `as Type[]` assertions (`@typescript-eslint/no-unnecessary-type-assertion`) when assigning API data from `openapi-fetch` client helpers that already infer the paginated return type. ## Testing & Linting - **Test Execution**: `npm run test -w frontend`. - **Linting**: Run `make node-lint` to run ESLint and Prettier for the frontend code, or `make lint-fix` to attempt auto-fixing. `make style-lint` is also available for CSS. - **ES Module Testing**: When testing components that use ES module exports directly (e.g. Firebase Auth), use a helper property (e.g. `credentialGetter`) that can be overridden with a Sinon stub. - **Typing**: Use generic arguments for `querySelector` in tests (e.g. `querySelector<HTMLSlotElement>(...)`) for type safety. ## Theming & Inheritance - **Global Classes**: The `WebstatusThemeService` toggles the `.sl-theme-dark` class on the `document.documentElement`. - **Inheritance**: Shoelace variables (e.g., `--sl-color-neutral-0`) automatically switch values based on the root class. Our custom theme variables in `_theme-css.ts` should derive from these semantic Shoelace variables to inherit fixed values across Shadow DOM boundaries consistently. - **Abstraction Layer**: Components should exclusively use custom variables from `_theme-css.ts`. Mapping these to Shoelace variables should only happen in the central theme file. This ensures that a library or color palette change can be managed in one place. - **Avoid Unsupported Selectors**: Do not use `:host-context` for theme overrides as it lacks support in Firefox and WebKit. Use root-inherited variables instead. ## Debugging Frontend Tests If a frontend unit test is timing out or failing mysteriously, Web Test Runner's console output is often unhelpful. - **Watch Mode**: Instruct the user to run `npm run test:watch -w frontend` in their own terminal. - **Visual Debugging**: Ask the user to open the provided localhost URL (e.g., `http://localhost:8000/`) in their web browser and inspect the developer console/DOM to see where the test is getting stuck. - **DON'T** arbitrarily increase the timeout in `web-test-runner.config.mjs` to fix timeout issues. Address the root cause of the hang instead. ## Documentation Updates When making significant architectural changes to the frontend or introducing new state management patterns: - Trigger the "Updating the Knowledge Base" prompt in `GEMINI.md`. - Update `docs/ARCHITECTURE.md` if the system boundaries change. - Update these very skills files if you introduce new established patterns.