Chart Card

# Brok UI: Chart Card (`chart-card`)

The card shell every chart and diagram sits in — a title or KPI value, a description, an optional actions slot and an auto-toned trend badge over a content well for the visualisation.

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

## Install

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

## Usage

```blade
<x-ui.chart-card
    heading="Revenue"
    subheading="This year vs. last year"
    trend="+12.5%"
>
    <x-ui.chart
        type="area"
        :height="260"
        :series="[
            ['name' => __('This year'), 'data' => [18, 22, 21, 28, 31, 30, 35, 39]],
            ['name' => __('Last year'), 'data' => [14, 16, 18, 19, 24, 22, 27, 29]],
        ]"
        :options="[
            'stroke' => ['curve' => 'smooth', 'width' => 2],
            'fill' => ['type' => 'gradient', 'gradient' => ['opacityFrom' => 0.4, 'opacityTo' => 0.05, 'stops' => [0, 90, 100]]],
            'legend' => ['position' => 'bottom'],
            'xaxis' => ['categories' => ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug']],
        ]"
        label="{{ __('Revenue, this year against last year') }}"
    />
</x-ui.chart-card>
```

## Props

- `heading` (string|null, default `null`) — Card title, or the small KPI label when `value` is set. Translated with __().
- `subheading` (string|null, default `null`) — Supporting description under the heading. Translated with __().
- `value` (string|null, default `null`) — Headline KPI value. When set, the heading renders as a muted label above it instead of a card title.
- `trend` (string|null, default `null`) — Delta label shown as a badge at the end of the header. Blank or null hides the badge.
- `trendVariant` (auto|success|destructive|neutral|secondary|warning|info|outline, default `auto`) — Tone of the trend badge. 'auto' reads the sign off the trend label (a leading - or − is destructive, anything else success); 'neutral' maps to the secondary badge.
- `actions` (mixed|null, default `null`) — Declared by @props in the shipped Blade source.

## Use when

- Use when trend, distribution, flow, intensity, or relationship questions are easier to answer visually than in raw numbers.
- Framing any chart, gauge or diagram in a dashboard card with a title, a description and a delta badge.
- Showing a headline KPI value above the chart instead of a card title.
- Putting a range selector, menu or link beside the trend badge in a chart's header.

## 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.
- The surface carries no visualisation; compose card directly.
- A number needs no chart beside it; use stat.

## Anti-patterns

- Decorative charts without a meaningful question

## Rules

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

{{-- The one card shell every chart and diagram sits in: a header carrying a
     title (or a KPI label and value), a description, an optional actions slot
     and a trend badge, over a content well that holds the visualisation. --}}
@props([
    'heading' => null,
    'subheading' => null,
    'value' => null,
    'trend' => null,
    'trendVariant' => 'auto',
    'actions' => null,
])

@php
    $trendText = trim((string) $trend);

    // "auto" reads the sign off the label itself, so a card can hand through a
    // delta string without also computing its tone. Both the ASCII hyphen and
    // the typographic minus count as negative.
    $isNegative = $trendText !== '' && (str_starts_with($trendText, '-') || str_starts_with($trendText, '−'));

    $badgeVariant = match ($trendVariant) {
        'auto' => $isNegative ? 'destructive' : 'success',
        'neutral' => 'secondary',
        default => $trendVariant,
    };

    // A block built on this shell passes its own data-slot; the card primitive
    // prints exactly one, so read the override here and forward it.
    $slotName = (string) ($attributes->get('data-slot') ?: 'chart-card');

    $hasActions = $actions !== null && ! $actions->isEmpty();
    $hasHeader = $heading || $subheading || $value !== null || $trendText !== '' || $hasActions;
@endphp

<x-ui.card :data-slot="$slotName" {{ $attributes->except('data-slot')->merge(['class' => 'w-full']) }}>
    @if ($hasHeader)
        <x-ui.card.header>
            <div class="flex items-start justify-between gap-4">
                <div class="flex min-w-0 flex-col gap-2">
                    @if ($value !== null)
                        @if ($heading)
                            <span class="text-sm font-medium text-muted-foreground">{{ __($heading) }}</span>
                        @endif
                        <span class="text-2xl font-bold tracking-tight text-foreground">{{ $value }}</span>
                    @elseif ($heading)
                        <x-ui.card.title>{{ __($heading) }}</x-ui.card.title>
                    @endif

                    @if ($subheading)
                        <x-ui.card.description>{{ __($subheading) }}</x-ui.card.description>
                    @endif
                </div>

                @if ($hasActions || $trendText !== '')
                    <div class="flex shrink-0 items-center gap-2">
                        {{ $actions }}

                        @if ($trendText !== '')
                            <x-ui.badge :variant="$badgeVariant">{{ __($trendText) }}</x-ui.badge>
                        @endif
                    </div>
                @endif
            </div>
        </x-ui.card.header>
    @endif

    <x-ui.card.content>
        {{ $slot }}
    </x-ui.card.content>
</x-ui.card>