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.

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.

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.

Frontend Architecture & Implementation

This document provides a technical guide for the frontend/ directory, focusing on Lit components, state management, and user authentication.

1. Component Architecture

The frontend is built as a Single Page Application (SPA) using Lit for web components.

• Main Entry: frontend/src/static/js/components/webstatus-app.ts handles routing and the overall page shell.
• Styling: Uses CSS-in-JS patterns specifically designed to support rich aesthetics and high-contrast dark modes.
• Reusable UI: Common components (headers, panels, charts) are located in static/js/components/.

2. Authentication & Identity Flow

The frontend manages user identity via Firebase Auth and GitHub OAuth.

1. Login: Triggered in the UI; Firebase Auth handles the OAuth handshake with GitHub. 2. Token Management: Upon successful login, Firebase provides a JWT. 3. API Requests: All authorized API calls (e.g., saving a search) attach this JWT as a Bearer token in the Authorization header. 4. User State: Personalization is driven by the backend GET /v1/users/me response, which is never cached.

3. Data Integration

• API Clients: Standardized Go/TS fetch wrappers communicate with the Backend API.
• Charts: Leverages charting libraries to visualize WPT and UMA metrics retrieved from the backend.
• Search Interaction: The search bar provides a UI for the complex ANTLR4-based grammar parsed on the backend.