Meters

# Brok UI: Usage Meter (`usage-meter`)

A labelled horizontal usage bar built on the progress primitive, with a threshold tone that warns as the value approaches its total.

Brok UI is a Laravel Blade component registry. Installed components are plain Blade files the app owns.

## Install

```bash
php artisan ui:add usage-meter
```

## Usage

```blade
<div class="mx-auto flex w-full max-w-sm flex-col gap-4">
    <x-ui.usage-meter :used="3200" :total="8000" label="Storage" />
    <x-ui.usage-meter :used="7600" :total="8000" label="Storage" />
</div>
```

## Props

- `used` (int, default `340`) — Amount currently used.
- `total` (int, default `512`) — Total capacity used is measured against.
- `label` (string, default `Usage`) — Label shown above the bar and used as the accessible name for the underlying progress bar.

## Use when

- Use when trend, distribution, flow, intensity, or relationship questions are easier to answer visually than in raw numbers.
- Showing a used/total quantity as a horizontal bar in a card, sidebar or settings panel, such as storage or API-call quota.
- Wanting the fill's tone to step from success to warning to destructive automatically as usage approaches its ceiling.

## Avoid when

- Do not use a chart when users mainly need exact lookup or when a single metric would be clearer as text or a stat.
- A compact radial dial fits the layout better; use usage-gauge instead.
- The value has no meaningful ceiling to warn against; use progress directly instead.

## Anti-patterns

- Decorative charts without a meaningful question

## Rules

- Use the `<brok:usage-meter>` tag (or `<x-ui.usage-meter>`) in Blade; do not rewrite the component.
- Prefer the documented props and variants over utility-class overrides; when a utility must win, use the `!` important modifier.
- Use semantic design tokens (`bg-primary`, `text-muted-foreground`), never raw colour utilities.
- Keep the `data-slot` attributes; they are the styling and test hooks.

## Links

- Docs: https://brokui.dev/docs/components/usage-meter
- Registry JSON (files, props, contract): https://brokui.dev/r/open/usage-meter.json

@props([
    'used' => 340,
    'total' => 512,
    'label' => 'Usage',
])

@php
    $styles = require base_path(config('ui.component_path', 'resources/views/components/ui').'/_styles.php');

    $used = max(0, (int) $used);
    $total = max(1, (int) $total);
    $ratio = min(1, $used / $total);

    // Resolve a threshold tone from the fill ratio (first matching floor wins).
    $tone = 'success';
    foreach ($styles['usage-meter']['thresholds'] as $candidate => $floor) {
        if ($ratio >= $floor) {
            $tone = $candidate;
            break;
        }
    }
@endphp

{{--
    Usage meter — a labelled horizontal fill bar built on <x-ui.progress>. The
    progress primitive owns the bar geometry and ARIA; we feed it the used/total
    pair and a threshold `tone` so the fill calmly tracks success → warning →
    destructive as the value approaches the ceiling. A tabular readout sits above.
--}}
<div
    data-slot="usage-meter"
    {{ $attributes->merge(['class' => 'rounded-md border border-border bg-card p-3 text-foreground']) }}
>
    {{-- In a narrow cell the count drops to its own line whole (never "74,000 /" + "100,000"),
         still aligned to the end; the label wraps between words only. --}}
    <div class="mb-2 flex flex-wrap items-baseline justify-between gap-x-2">
        <span class="min-w-0 text-sm text-muted-foreground">{{ __($label) }}</span>
        <span class="ms-auto whitespace-nowrap text-sm tabular-nums">
            <span class="font-medium">{{ number_format($used) }}</span>
            <span class="text-muted-foreground"> / {{ number_format($total) }}</span>
        </span>
    </div>

    <x-ui.progress :value="$used" :max="$total" :tone="$tone" :aria-label="__($label)" />
</div>