# Usage meter

How much of an allowance is used, as short meters with their values and when it starts again, in a toolbar or stacked.

A block: a ready-made arrangement of components, to copy into a project. Its own classes carry the `site-` prefix; rename it to your project's own. Status: experimental. Figma: the Figma file, https://www.figma.com/community/file/1688324308358870630. Built from: Icon, Meter, Toolbar, Divider, Button.

## Examples

### Usage

The toolbar layout: two allowances on one line, the first close to its limit, and when they start again.

```html
<div class="site-usage-meter site-usage-meter--layout-toolbar" role="group" aria-label="Usage">
  <i
    class="ph ph-lightning smbk-icon smbk-icon--size-sm site-usage-meter__icon"
    aria-hidden="true"
  ></i>
  <span class="site-usage-meter__item">
    <span class="site-usage-meter__label" aria-hidden="true">Week</span>
    <div class="smbk-meter smbk-meter--tone-warning smbk-progress site-usage-meter__meter">
      <div
        class="smbk-progress__track"
        role="meter"
        aria-valuemin="0"
        aria-valuemax="100"
        aria-valuenow="86"
        aria-valuetext="86% used, close to the limit"
        aria-label="Weekly allowance"
      >
        <span class="smbk-progress__fill" style="width:86%"></span>
      </div>
    </div>
    <span class="site-usage-meter__value" aria-hidden="true">86%</span>
  </span>
  <span class="site-usage-meter__item">
    <span class="site-usage-meter__label" aria-hidden="true">5-hour</span>
    <div class="smbk-meter smbk-meter--tone-series smbk-progress site-usage-meter__meter">
      <div
        class="smbk-progress__track"
        role="meter"
        aria-valuemin="0"
        aria-valuemax="100"
        aria-valuenow="12"
        aria-valuetext="12% used"
        aria-label="Five-hour allowance"
      >
        <span class="smbk-progress__fill" style="width:12%"></span>
      </div>
    </div>
    <span class="site-usage-meter__value" aria-hidden="true">12%</span>
  </span>
  <span class="site-usage-meter__meta">resets Mon 8:00 PM</span>
</div>
```

```tsx
import { Icon } from './design-system/components/icon/icon.js';
import { Meter } from './design-system/components/meter/meter.js';

<div className="site-usage-meter site-usage-meter--layout-toolbar" role="group" aria-label="Usage">
  <Icon className="site-usage-meter__icon" name="Lightning" size="sm" />
  <span className="site-usage-meter__item">
    <span className="site-usage-meter__label" aria-hidden="true">Week</span>
    <Meter className="site-usage-meter__meter" tone="warning" value={86} aria-label="Weekly allowance" aria-valuetext="86% used, close to the limit" />
    <span className="site-usage-meter__value" aria-hidden="true">86%</span>
  </span>
  <span className="site-usage-meter__item">
    <span className="site-usage-meter__label" aria-hidden="true">5-hour</span>
    <Meter className="site-usage-meter__meter" tone="series" value={12} aria-label="Five-hour allowance" aria-valuetext="12% used" />
    <span className="site-usage-meter__value" aria-hidden="true">12%</span>
  </span>
  <span className="site-usage-meter__meta">resets Mon 8:00 PM</span>
</div>
```

### Stacked

The stacked layout: the meter under its name and value, for a panel or a menu.

```html
<div
  class="site-usage-meter site-usage-meter--layout-stacked"
  role="group"
  aria-label="Usage, stacked"
>
  <span class="site-usage-meter__item">
    <span class="site-usage-meter__label" aria-hidden="true">Week</span>
    <div class="smbk-meter smbk-meter--tone-warning smbk-progress site-usage-meter__meter">
      <div
        class="smbk-progress__track"
        role="meter"
        aria-valuemin="0"
        aria-valuemax="100"
        aria-valuenow="86"
        aria-valuetext="86% used, close to the limit"
        aria-label="Weekly allowance"
      >
        <span class="smbk-progress__fill" style="width:86%"></span>
      </div>
    </div>
    <span class="site-usage-meter__value" aria-hidden="true">86%</span>
  </span>
  <span class="site-usage-meter__meta">resets Mon 8:00 PM</span>
</div>
```

```tsx
import { Meter } from './design-system/components/meter/meter.js';

<div className="site-usage-meter site-usage-meter--layout-stacked" role="group" aria-label="Usage, stacked">
  <span className="site-usage-meter__item">
    <span className="site-usage-meter__label" aria-hidden="true">Week</span>
    <Meter className="site-usage-meter__meter" tone="warning" value={86} aria-label="Weekly allowance" aria-valuetext="86% used, close to the limit" />
    <span className="site-usage-meter__value" aria-hidden="true">86%</span>
  </span>
  <span className="site-usage-meter__meta">resets Mon 8:00 PM</span>
</div>
```

### Stacked, two allowances

Stacked with two allowances, each under its own name and value.

```html
<div
  class="site-usage-meter site-usage-meter--layout-stacked"
  role="group"
  aria-label="Usage, two allowances"
>
  <span class="site-usage-meter__item">
    <span class="site-usage-meter__label" aria-hidden="true">Week</span>
    <div class="smbk-meter smbk-meter--tone-warning smbk-progress site-usage-meter__meter">
      <div
        class="smbk-progress__track"
        role="meter"
        aria-valuemin="0"
        aria-valuemax="100"
        aria-valuenow="86"
        aria-valuetext="86% used, close to the limit"
        aria-label="Weekly allowance"
      >
        <span class="smbk-progress__fill" style="width:86%"></span>
      </div>
    </div>
    <span class="site-usage-meter__value" aria-hidden="true">86%</span>
  </span>
  <span class="site-usage-meter__item">
    <span class="site-usage-meter__label" aria-hidden="true">5-hour</span>
    <div class="smbk-meter smbk-meter--tone-series smbk-progress site-usage-meter__meter">
      <div
        class="smbk-progress__track"
        role="meter"
        aria-valuemin="0"
        aria-valuemax="100"
        aria-valuenow="12"
        aria-valuetext="12% used"
        aria-label="Five-hour allowance"
      >
        <span class="smbk-progress__fill" style="width:12%"></span>
      </div>
    </div>
    <span class="site-usage-meter__value" aria-hidden="true">12%</span>
  </span>
  <span class="site-usage-meter__meta">resets Mon 8:00 PM</span>
</div>
```

```tsx
import { Meter } from './design-system/components/meter/meter.js';

<div className="site-usage-meter site-usage-meter--layout-stacked" role="group" aria-label="Usage, two allowances">
  <span className="site-usage-meter__item">
    <span className="site-usage-meter__label" aria-hidden="true">Week</span>
    <Meter className="site-usage-meter__meter" tone="warning" value={86} aria-label="Weekly allowance" aria-valuetext="86% used, close to the limit" />
    <span className="site-usage-meter__value" aria-hidden="true">86%</span>
  </span>
  <span className="site-usage-meter__item">
    <span className="site-usage-meter__label" aria-hidden="true">5-hour</span>
    <Meter className="site-usage-meter__meter" tone="series" value={12} aria-label="Five-hour allowance" aria-valuetext="12% used" />
    <span className="site-usage-meter__value" aria-hidden="true">12%</span>
  </span>
  <span className="site-usage-meter__meta">resets Mon 8:00 PM</span>
</div>
```

### In a toolbar

Inside a docked toolbar, between its title and its main action; nearly at the limit, in the danger color.

```html
<div
  role="toolbar"
  aria-label="Assistant"
  aria-orientation="horizontal"
  class="smbk-toolbar smbk-toolbar--placement-docked"
>
  <div class="smbk-toolbar__row">
    <div class="smbk-toolbar__context">
      <span class="smbk-toolbar__title">Assistant</span>
    </div>
    <div class="smbk-toolbar__tools">
      <span
        role="separator"
        aria-orientation="vertical"
        class="smbk-divider smbk-divider--orientation-vertical smbk-toolbar__divider"
      ></span>
      <div
        class="site-usage-meter site-usage-meter--layout-toolbar"
        role="group"
        aria-label="Usage, in a toolbar"
      >
        <i
          class="ph ph-lightning smbk-icon smbk-icon--size-sm site-usage-meter__icon"
          aria-hidden="true"
        ></i>
        <span class="site-usage-meter__item">
          <span class="site-usage-meter__label" aria-hidden="true">Week</span>
          <div class="smbk-meter smbk-meter--tone-danger smbk-progress site-usage-meter__meter">
            <div
              class="smbk-progress__track"
              role="meter"
              aria-valuemin="0"
              aria-valuemax="100"
              aria-valuenow="97"
              aria-valuetext="97% used, nearly at the limit"
              aria-label="Weekly allowance"
            >
              <span class="smbk-progress__fill" style="width:97%"></span>
            </div>
          </div>
          <span class="site-usage-meter__value" aria-hidden="true">97%</span>
        </span>
        <span class="site-usage-meter__meta">resets Mon 8:00 PM</span>
      </div>
    </div>
    <div class="smbk-toolbar__actions">
      <span
        role="separator"
        aria-orientation="vertical"
        class="smbk-divider smbk-divider--orientation-vertical smbk-toolbar__divider"
      ></span>
      <button type="button" class="smbk-btn smbk-btn--tone-brand smbk-btn--size-sm">
        <i class="ph ph-plus smbk-icon smbk-icon--size-md smbk-btn__icon" aria-hidden="true"></i>
        <span class="smbk-btn__label">New chat</span>
      </button>
    </div>
  </div>
</div>
```

```tsx
import { Toolbar, ToolbarContext, ToolbarTitle, ToolbarTools, ToolbarActions } from './design-system/components/toolbar/toolbar.js';
import { Icon } from './design-system/components/icon/icon.js';
import { Meter } from './design-system/components/meter/meter.js';
import { Button } from './design-system/components/button/button.js';

<Toolbar label="Assistant" placement="docked">
  <ToolbarContext>
    <ToolbarTitle>Assistant</ToolbarTitle>
  </ToolbarContext>
  <ToolbarTools>
    <div className="site-usage-meter site-usage-meter--layout-toolbar" role="group" aria-label="Usage, in a toolbar">
      <Icon className="site-usage-meter__icon" name="Lightning" size="sm" />
      <span className="site-usage-meter__item">
        <span className="site-usage-meter__label" aria-hidden="true">Week</span>
        <Meter className="site-usage-meter__meter" tone="danger" value={97} aria-label="Weekly allowance" aria-valuetext="97% used, nearly at the limit" />
        <span className="site-usage-meter__value" aria-hidden="true">97%</span>
      </span>
      <span className="site-usage-meter__meta">resets Mon 8:00 PM</span>
    </div>
  </ToolbarTools>
  <ToolbarActions>
    <Button tone="brand" size="sm" leadingIcon="Plus">New chat</Button>
  </ToolbarActions>
</Toolbar>
```

## Purpose

Shows how much of an allowance is used, such as a weekly and a five-hour limit, small enough for a toolbar: each allowance a short meter between its name and its value, then a line saying when it starts again.

## Anatomy

- The block, a group named for what it measures.
- An optional icon before the meters, in the toolbar layout.
- Each item: the name and the value in the small label style, and the bar, the Meter component, carrying the block's meter class beside its own. Its tone is the page's choice: the series color, or warning and danger as the allowance runs out.
- The line saying when it starts again, in the extra small body style and the subtlest text color.

## When to use

- In a toolbar or an app bar, the toolbar layout: one line as tall as a small control.
- In a panel, a menu or a popover, the stacked layout: each meter under its name and value.

## When not to use

- For how far along a task is. Use a progress bar.
- For a few places that are taken or free. Use a capacity meter.

## Behavior

The toolbar layout keeps every meter short and on one line; the stacked layout gives each meter the whole width. It takes no focus; to open details from it, put it inside a button.

## Accessibility

### What it does for you

- The block is a group.
- Each bar is a meter with a name and its value in words, such as "Weekly allowance, 86% used"; the drawn name and value are hidden from assistive technology, so they are not read twice.

### What you must do

- Name the group by its `aria-label`, such as "Usage".
- When the tone turns to warning or danger, say so in the value as well, such as "86% used, close to the limit".

### How to test

- With a screen reader, the group is read by its name, and each meter once, by its name and its value in words; near the limit, the value says so.

## Usage rules

### Do

- Name each allowance by its period.
- Say when it starts again.

### Don't

- Put more than two meters in a toolbar.
- Show the warning by color alone.

## Stylesheet

```css
/* site-usage-meter — Usage meter, a block: how much of an allowance is used, as short meters with their names and
 * values and a line saying when it starts again. Copy it into your project and rename site- to your project's own
 * prefix. Each bar is the Meter component, given this block's meter class beside its own. Two layouts: toolbar,
 * one line as tall as a small control, for a toolbar or a bar; stacked, a column for a panel or a menu. */

.site-usage-meter {
  display: flex;
  color: var(--smbk-color-text-default);
}

.site-usage-meter__item {
  display: grid;
  align-items: center;
}

.site-usage-meter__icon {
  flex: none;
  color: var(--smbk-color-icon-subtle);
}

.site-usage-meter__label {
  grid-area: label;
  color: var(--smbk-color-text-subtle);
}

.site-usage-meter__value {
  grid-area: value;
  color: var(--smbk-color-text-default);
  font-variant-numeric: tabular-nums;
}

.site-usage-meter__label,
.site-usage-meter__value {
  font-family: var(--smbk-typography-label-sm-font-family);
  font-size: var(--smbk-typography-label-sm-font-size);
  font-weight: var(--smbk-typography-label-sm-font-weight);
  line-height: var(--smbk-typography-label-sm-line-height);
  letter-spacing: var(--smbk-typography-label-sm-letter-spacing);
  white-space: nowrap;
}

.site-usage-meter__meter {
  grid-area: meter;
}

.site-usage-meter__meta {
  color: var(--smbk-color-text-subtlest);
  font-family: var(--smbk-typography-body-xs-font-family);
  font-size: var(--smbk-typography-body-xs-font-size);
  font-weight: var(--smbk-typography-body-xs-font-weight);
  line-height: var(--smbk-typography-body-xs-line-height);
  letter-spacing: var(--smbk-typography-body-xs-letter-spacing);
}

/* Toolbar: one line, as tall as a small control: the icon, each meter with its name before it and its value after,
   then when it starts again. */
.site-usage-meter--layout-toolbar {
  align-items: center;
  gap: var(--smbk-space-inline-lg);
  min-height: var(--smbk-size-control-sm);
  padding-inline: var(--smbk-space-inset-xs);
}

.site-usage-meter--layout-toolbar .site-usage-meter__item {
  grid-template-areas: 'label meter value';
  column-gap: var(--smbk-space-inline-sm);
}

.site-usage-meter--layout-toolbar .site-usage-meter__meter {
  width: var(--smbk-size-56);
}

.site-usage-meter--layout-toolbar .site-usage-meter__meta {
  white-space: nowrap;
}

/* Stacked: a column as wide as its space: each meter under its name and value, then when it starts again. */
.site-usage-meter--layout-stacked {
  flex-direction: column;
  gap: var(--smbk-space-stack-xs);
}

.site-usage-meter--layout-stacked .site-usage-meter__item {
  grid-template-areas: 'label value' 'meter meter';
  grid-template-columns: 1fr auto;
  row-gap: var(--smbk-space-stack-xs);
}

.site-usage-meter--layout-stacked .site-usage-meter__item + .site-usage-meter__item {
  margin-block-start: var(--smbk-space-stack-xs);
}
```