Meters

# Brok UI: Liquid Chart (`chart-liquid`)

A liquid-fill gauge: an animated wavy waterline rises inside a ring to show a 0-100 value, with a centered percentage and optional caption. CSS-only, no JavaScript.

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

## Install

```bash
php artisan ui:add chart-liquid
```

## Usage

```blade
<div class="space-y-6">
    <div class="flex flex-wrap items-end justify-center gap-8">
        <x-ui.chart-liquid :value="68" variant="primary" :label="__('Storage')" :caption="__('Storage')" />
        <x-ui.chart-liquid :value="42" variant="success" :label="__('Memory')" :caption="__('Memory')" :height="160" />
        <x-ui.chart-liquid :value="91" variant="warning" :label="__('Quota')" :caption="__('Quota')" :height="160" />
    </div>

    <p class="text-sm text-muted-foreground">
        {{ __('A CSS-only liquid-fill gauge. Set the fill with `:value` (0-100), pick a token tone with `:variant` (primary, success, warning, destructive), and label it with `:label` (accessible) and `:caption` (visible). The waterline animates and freezes flat under reduced-motion.') }}
    </p>
</div>
```

## Props

- `value` (int, default `68`) — Fill level from 0 to 100; clamped into range.
- `variant` (success|warning|destructive, default `primary`) — Tone of the liquid and ring: primary, success, warning, or destructive.
- `label` (mixed|null, default `null`) — Accessible label for the figure; defaults to "Capacity".
- `caption` (mixed|null, default `null`) — Optional small caption rendered under the percentage.
- `height` (int, default `220`) — Rendered height in pixels; the SVG keeps a 1:1 viewBox.

## Use when

- Use when trend, distribution, flow, intensity, or relationship questions are easier to answer visually than in raw numbers.
- Showing a single 0-100 capacity or fill value with a distinctive, eye-catching visual, such as a storage or battery gauge.
- Wanting an animated, dependency-free SVG indicator with no JavaScript or chart library.

## 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 more conventional dial reading is expected; use gauge or circular-progress instead.
- The value is not a 0-100 fill amount, such as a trend over time; use chart instead.

## Anti-patterns

- Decorative charts without a meaningful question

## Rules

- Use the `<brok:chart-liquid>` tag (or `<x-ui.chart-liquid>`) 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/chart-liquid
- Registry JSON (files, props, contract): https://brokui.dev/r/open/chart-liquid.json

@props([
    // 0..100 fill level.
    'value' => 68,
    // primary | success | warning | destructive — maps to a token text class.
    'variant' => 'primary',
    // Accessible label for the figure (defaults to "Capacity").
    'label' => null,
    // Optional small caption rendered under the percentage.
    'caption' => null,
    // Rendered height in px (the SVG keeps a 1:1 viewBox).
    'height' => 220,
])

@php
    $styles = require base_path(config('ui.component_path', 'resources/views/components/ui').'/_styles.php');
    $variant = $styles['normalizeVariant']($variant);
    // ── Clamp + resolve copy ──────────────────────────────────────────────
    $value = max(0, min(100, (int) $value));
    $label ??= __('Capacity');

    // Fixed (non-spliced) variant → token class map. Full strings so the
    // Tailwind JIT can see every utility; never concatenate a variable in.
    $tone = match ($variant) {
        'success' => 'text-success',
        'warning' => 'text-warning',
        'destructive' => 'text-destructive',
        default => 'text-primary',
    };

    // ── Geometry (viewBox 0 0 200 200) ────────────────────────────────────
    $cx = 100;
    $cy = 100;
    $r = 90;                  // outer ring radius
    $top = $cy - $r;          // 10
    $innerH = 2 * $r;         // 180
    // Waterline: 0% → bottom of the circle, 100% → top of the circle.
    $waterline = $top + (1 - $value / 100) * $innerH;

    // Two wave bands, twice as wide as the circle so they can slide -50%
    // (one wavelength) seamlessly. Each is a path of two cosine humps that
    // tile horizontally, capped to a deep rectangle below.
    $waveW = 400;             // 2× viewBox width
    $amp = 6;                 // wave amplitude
    $bottomY = 200;

    $buildWave = static function (float $y, float $amplitude, float $phase) use ($waveW, $bottomY) {
        // Start at the left edge on the waterline, draw two full humps across
        // the doubled width using cubic segments, then close down the sides.
        $half = $waveW / 4;   // quarter wavelength control span
        $d = sprintf('M0 %.2f', $y);
        $x = 0.0;
        for ($i = 0; $i < 4; $i++) {
            $dir = ($i + ($phase > 0 ? 1 : 0)) % 2 === 0 ? -1 : 1;
            $cp = $x + $half / 2;
            $nx = $x + $half;
            $d .= sprintf(' Q%.2f %.2f %.2f %.2f', $cp, $y + $dir * $amplitude, $nx, $y);
            $x = $nx;
        }
        $d .= sprintf(' L%.2f %.2f L0 %.2f Z', $waveW, $bottomY, $bottomY);

        return $d;
    };

    $frontWave = $buildWave($waterline, $amp, 0);
    $backWave = $buildWave($waterline + 2, $amp * 0.7, 1);

    $H = max(120, (int) $height);
    $clipId = 'ui-liquid-clip-' . uniqid();
@endphp

{{-- Keyframes carry NO colour; reduced-motion users get a static fill. --}}
<style>
    @keyframes ui-chart-liquid-wave {
        from { transform: translateX(0); }
        to { transform: translateX(-200px); }
    }
    @media (prefers-reduced-motion: no-preference) {
        [data-slot="chart-liquid-wave"] {
            animation: ui-chart-liquid-wave linear infinite;
            transform-box: view-box;
        }
        [data-slot="chart-liquid-wave"][data-wave="front"] { animation-duration: 4s; }
        [data-slot="chart-liquid-wave"][data-wave="back"] { animation-duration: 6s; }
    }
</style>

<figure
    data-slot="chart-liquid"
    data-variant="{{ $variant }}"
    role="img"
    aria-label="{{ $label }}: {{ $value }}%"
    {{ $attributes->merge(['class' => 'inline-flex flex-col items-center gap-2']) }}
>
    <svg
        viewBox="0 0 200 200"
        width="{{ $H }}"
        height="{{ $H }}"
        preserveAspectRatio="xMidYMid meet"
        class="block h-auto max-w-full {{ $tone }}"
        aria-hidden="true"
    >
        <defs>
            <clipPath id="{{ $clipId }}">
                <circle cx="{{ $cx }}" cy="{{ $cy }}" r="{{ $r - 4 }}" />
            </clipPath>
        </defs>

        {{-- Faint track behind the liquid. --}}
        <circle
            cx="{{ $cx }}"
            cy="{{ $cy }}"
            r="{{ $r - 4 }}"
            fill="currentColor"
            class="opacity-[0.06]"
        />

        {{-- Liquid: both waves clipped to the inner circle. --}}
        <g clip-path="url(#{{ $clipId }})">
            <path
                data-slot="chart-liquid-wave"
                data-wave="back"
                d="{{ $backWave }}"
                fill="currentColor"
                class="opacity-30"
            />
            <path
                data-slot="chart-liquid-wave"
                data-wave="front"
                d="{{ $frontWave }}"
                fill="currentColor"
                class="opacity-70"
            />
        </g>

        {{-- Outer ring in the token colour. --}}
        <circle
            cx="{{ $cx }}"
            cy="{{ $cy }}"
            r="{{ $r }}"
            fill="none"
            stroke="currentColor"
            stroke-width="3"
            class="opacity-40"
        />

        {{-- Centered percentage. --}}
        <text
            x="{{ $cx }}"
            y="{{ $cy }}"
            text-anchor="middle"
            dominant-baseline="central"
            class="fill-foreground text-4xl font-bold tabular-nums"
        >{{ $value }}%</text>
    </svg>

    @if ($caption)
        <figcaption class="text-sm text-muted-foreground">{{ $caption }}</figcaption>
    @endif
</figure>