Charts

# Brok UI: Chart Tooltip (`chart-tooltip`)

The one tooltip surface every chart shares: a popover with an optional title and swatch/label/value rows, positioned by the SVG charts with Alpine and rendered by the ApexCharts wrapper's custom tooltip.

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

## Install

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

## Usage

```blade
<div class="flex flex-wrap items-start justify-center gap-8">
    <x-ui.chart-tooltip
        :title="__('March')"
        :items="[
            ['label' => __('Revenue'), 'value' => '$48.2k', 'color' => 'chart-1'],
            ['label' => __('Costs'), 'value' => '$21.7k', 'color' => 'chart-2'],
        ]"
    />
    <x-ui.chart-tooltip :items="[['label' => __('Organic → Signups'), 'value' => '35']]" />
</div>
```

## Props

- `title` (mixed|null, default `null`) — Optional heading, such as a category or date, shown above the rows.
- `items` (array, default `[]`) — Rows to render: each an object with label, value, and an optional color (a chart-N token or class).

## Use when

- Use when trend, distribution, flow, intensity, or relationship questions are easier to answer visually than in raw numbers.
- Building a custom SVG chart (sankey, venn, network, and so on) that needs the same pointer tooltip surface every other chart uses.
- Overriding ApexCharts' default tooltip via its tooltip.custom hook while keeping the token-themed look consistent.

## 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.
- ApexCharts' built-in tooltip already covers the need; only override it when custom rows or a title are required.
- A persistent, non-pointer-following key to the chart's colours; use chart-legend instead.

## Anti-patterns

- Decorative charts without a meaningful question

## Rules

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

@props([
    // Optional heading (a category, a date) above the rows.
    'title' => null,
    // Rows: each ['label' => string, 'value' => string, 'color' => 'chart-1'|token class|null].
    // Leave empty and use the slot for Alpine-bound content (`x-text`).
    'items' => [],
])

@php
    // Swatch colours are fixed utilities (JIT-visible): the neutral chart hues
    // plus the status tokens, shared with chart-legend and partition-bar.
    // Anything else is used as a class as-is.
    $styles = require base_path(config('ui.component_path', 'resources/views/components/ui').'/_styles.php');
    $swatches = $styles['chart']['swatches'];
@endphp

{{-- The one tooltip surface every chart shares — the SVG charts position it
     with Alpine, the ApexCharts wrapper renders the same markup from its
     `tooltip.custom` hook. Keep the classes here and there in step. --}}
<div
    data-slot="chart-tooltip"
    role="presentation"
    {{ $attributes->merge(['class' => 'pointer-events-none z-10 min-w-32 rounded-md border border-border bg-popover px-3 py-2 text-xs text-popover-foreground shadow-md']) }}
>
    @if ($title !== null)
        <p data-slot="chart-tooltip-title" class="mb-1 font-medium text-muted-foreground">{{ $title }}</p>
    @endif
    @foreach ($items as $item)
        <div data-slot="chart-tooltip-row" class="flex items-center justify-between gap-4">
            <span class="flex items-center gap-2">
                @if (! empty($item['color']))
                    <span aria-hidden="true" class="size-2 shrink-0 rounded-full {{ $swatches[$item['color']] ?? $item['color'] }}"></span>
                @endif
                <span class="text-muted-foreground">{{ $item['label'] ?? '' }}</span>
            </span>
            <span class="font-medium tabular-nums">{{ $item['value'] ?? '' }}</span>
        </div>
    @endforeach
    {{ $slot }}
</div>