Grid-aware Websites Info Bar

This web component is designed to work with the Grid-aware Websites library. 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

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.

<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:

<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:

<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

<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

<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

<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

<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.

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:

   git clone https://github.com/thegreenwebfoundation/gaw-web-component.git
   cd gaw-web-component

2. Install dependencies:

   npm install

3. Start the development server:

   npm run dev

   This will allow you to preview changes made to the web component.

License

MIT License

Credits

Developed by The Green Web Foundation as part of their Grid-aware Web initiative.