@greenweb/gaw-info-bar

> [!WARNING] > This web component is still being actively developed. It is currently not suitable for production use. # Grid-aware Websites Info Bar This web component is designed to work with the [Grid-aware Websites library](https://github.com/thegreenwebfoundation/grid-aware-websites). It aims to provide website users with contextual information about their local energy grid and enables customization options for grid-aware website designs. ## Features - Display contextual information about the user's local energy grid - Show different states based on grid carbon intensity (low, moderate, high, or unknown) - Allow users to opt-out of automatically applying grid-aware website designs - Enable users to manually switch between different design modes ## Installation ### Via npm ```bash npm install @greenweb/gaw-info-bar ``` ### Import from a CDN Add the component to your project's HTML using a `script` tag using a code CDN. ```html <script type="module" src="https://esm.sh/@greenweb/gaw-info-bar"></script> ``` ### Add manually to a project Add the component to a project manually. To do this: 1. Copy the `dist/gaw-info-bar.js` file to your project. 2. In your project's HTML add the following script tag: ```html <script type="module" src="path/to/gaw-info-bar.js"></script> ``` ## Usage Add the component to your HTML and configure it with appropriate data attributes: ```html <gaw-info-bar data-gaw-level="low" data-gaw-location="US" data-learn-more-link="https://example.com/grid-aware" data-popover-text="Custom information about grid-aware design" data-views="default, low, moderate, high" data-default-view="default" > </gaw-info-bar> ``` ### Attributes | Attribute | Description | Values | Default | | ---------------------------- | ----------------------------------------------------- | ------------------------------------------------------ | ----------------------------------------- | | `data-gaw-level` | Current carbon intensity level | `"low"`, `"moderate"`, `"high"` | `undefined` (shows as "Data unavailable") | | `data-gaw-location` | Location code | Alpha-2 country code or valid Electricity Maps Zone ID | `undefined` (shows as "Location unknown") | | `data-ignore-cookie` | Name of the cookie used to store user preference | Any valid cookie name | `"gaw-ignore"` | | `data-ignore-cookie-max-age` | Max age for the ignore cookie | Valid cookie max-age in milliseconds | `"84600"` | | `data-learn-more-link` | URL for the "Learn more" link in the info popover | Any valid URL | `"#"` | | `data-popover-text` | Custom text to display in the info popover | Any string | Default explanatory text | | `data-views` | Comma-separated list of design modes | String of comma-separated values | `"low,moderate,high"` | | `data-default-view` | Default design mode when user switches to manual mode | One of the values from `data-views` | `"low"` | ## Grid Intensity Levels The component displays different states based on the specified grid intensity level: ### Low Intensity ```html <gaw-info-bar data-gaw-level="low" data-gaw-location="TW"></gaw-info-bar> ``` Shows a green indicator with message "Your local grid: Cleaner than average." ### Moderate Intensity ```html <gaw-info-bar data-gaw-level="moderate" data-gaw-location="TW"></gaw-info-bar> ``` Shows an orange indicator with message "Your local grid: Around average emissions." ### High Intensity ```html <gaw-info-bar data-gaw-level="high" data-gaw-location="TW"></gaw-info-bar> ``` Shows a red indicator with message "Your local grid: Dirtier than average." ### Unknown Intensity ```html <gaw-info-bar data-gaw-location="TW"></gaw-info-bar> ``` Shows a gray indicator with message "Your local grid: Data unavailable." ## Location Support The component supports displaying user-friendly location names for: - Regular country codes (e.g., "TW" for Taiwan) - Regions (e.g., "AU-NSW" for New South Wales, Australia) - Complex regions (e.g., "US-CENT-SPA" displays as "USA - Central") These location identifiers align with the zones supported by the [Electricity Maps API](https://portal.electricitymaps.com/docs/getting-started#geographical-coverage). ## User Controls The component provides users with two types of controls: 1. **Auto/Manual Toggle**: Allows users to switch between automatic grid-aware design (based on actual grid intensity) and manual selection. 2. **Manual Mode Buttons**: When auto mode is disabled, users can select between design modes specified in the `data-views` attribute. By default, these are low, moderate, and high grid intensity design modes. 3. **Information Popover**: An information button that displays a popover with explanatory text about the grid-aware design and a "Learn more" link. These settings are stored in cookies to persist user preferences across page loads: - `gaw-ignore`: Stores whether the user has opted out of automatic grid-aware design - `gaw-user-opt-in`: Stores the user's preference for auto/manual mode - `gaw-manual-view`: Stores the user's manually selected grid intensity level The component also supports an expandable design that shows/hides additional controls when the user clicks on the expand button. ## Browser Support This component is built using standard web components and supports all modern browsers. ## Development ### Prerequisites - Node.js and npm ### Setup 1. Clone the repository: ```bash git clone https://github.com/thegreenwebfoundation/gaw-web-component.git cd gaw-web-component ``` 2. Install dependencies: ```bash npm install ``` 3. Start the development server: ```bash npm run dev ``` This will allow you to preview changes made to the web component. ## License [MIT License](LICENSE) ## Credits Developed by [The Green Web Foundation](https://www.thegreenwebfoundation.org/) as part of their Grid-aware Web initiative.