Fact List

# Brok UI: Fact List (`fact-list`)

A key/value readout — label on the start side, value on the end side, a hairline between rows — from a server array or an Alpine-bound expression, with per-row tone and mono.

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

## Install

```bash
php artisan ui:add fact-list
```

## Usage

```blade
<x-ui.fact-list class="w-80" :facts="[
    ['label' => __('Subtotal'), 'value' => '€118.50'],
    ['label' => __('Shipping'), 'value' => '€10.00'],
    ['label' => __('Total'), 'value' => '€128.50'],
    ['label' => __('Outstanding'), 'value' => '€128.50', 'tone' => 'attention'],
    ['label' => __('Payment reference'), 'value' => 'tr_7GkQ2p', 'mono' => true],
]" />
```

## Props

- `facts` (array, default `[]`) — [['label','value','tone' => null,'mono' => false,'type' => 'text','variant' => null,'key' => null]] — `k`/`v` accepted as aliases. `type` is text|badge|tags|paragraph|attachment|link|time; `variant` picks the badge recipe for badge/tags. An attachment value is a list of ['name', 'size', 'href', 'download'] files: the link downloads (download attribute, the file's own name); a download string names the saved file, false opens the link instead. A `link` row adds `href` (http, https, mailto, tel or relative only; anything else renders the value as plain text) and `external` (new tab, external-link glyph, screen-reader note). A `time` row takes an instant as `value` and `mode` datetime|date|time|relative (`relative => true` is short for relative). `key` names the row for its `fact-<key>` slot and is exposed as data-key. Ignored when `bind` is set.
- `bind` (string|null, default `null`) — An Alpine expression evaluating to the rows array in the surrounding scope, e.g. `drawer.money.rows`. Rows are rendered client-side with the same tone map.
- `size` (sm|md|lg, default `md`) — Row rhythm and type size: `md` (text-sm, 8px rows) for a record sheet, `sm` (text-xs, 4px rows) for a dense drawer, `lg` (text-sm, 16px rows) for a description list.
- `layout` (row|grid, default `row`) — `row` keeps label and value on one line with the value at the end; `grid` is the description-list look, a label column with the value beside it, start-aligned, stacking on a narrow screen.

## Use when

- Use to summarize, sequence, or present data so users can scan it quickly.
- A record sheet, quick-view drawer or summary panel needs to state a handful of facts as label/value pairs.
- The rows come from a payload already in Alpine scope (a drawer fed by the table row) and must swap subject without a round trip — use `bind`.
- A description list (applicant details, an account overview) with badges, tag sets, a paragraph or attachments in the value column — use `layout="grid"` with typed facts.

## Avoid when

- Do not add display-only ornament when the user needs actionable structure or exact comparison instead.
- The data is tabular with more than two columns — use `table` or `admin-table`.
- Each value needs its own control or action — compose `list-panel` rows instead.

## Anti-patterns

- Adding display ornament without informational value

## Rules

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

{{--
    Fact List — a key/value readout, the shape every record sheet, quick
    view, and summary panel reaches for: a label on the start side, the
    value on the end side, one hairline between rows.

    Two sources, one markup:

      - `facts` — a PHP array rendered on the server. The default.
      - `bind`  — an Alpine expression naming an array in the surrounding
        scope (`drawer.money.rows`). The rows then come from the payload that
        arrived with a table row, so a quick view can swap subject without a
        round trip. The expression is passed as a plain string on purpose:
        `@js()` inside a component attribute is not compiled, and the caller
        owns the scope the expression evaluates in.

    Each row is `['label', 'value', 'tone' => null, 'mono' => false, 'type' => 'text']`
    (`k`/`v` are accepted as aliases, the shape the Noord-C read models emit).
    `tone` colours the value by meaning (attention/negative/positive), never
    by sign; `mono` sets a code, SKU, or identifier in the mono face at a
    slightly smaller size so it lines up with the tabular figures around it.

    `type` says what the value is: `text` (default), `badge` (a status word in
    a badge; `variant` picks the badge recipe, `tone` its meaning), `tags`
    (an array of words as outline badges), `paragraph` (a sentence or two,
    set with relaxed leading), `attachment` (an array of
    `['name', 'size', 'href']` files, each with a download action), `link`
    (`href` plus the visible `value`; only http, https, mailto, tel and
    relative URLs become a link, anything else renders as plain text;
    `external` opens a new tab with an external-link glyph and a
    screen-reader note) or `time` (a `<time datetime>` through relative-time;
    `mode` is datetime (default), date, time or relative, and
    `'relative' => true` is short for mode relative).

    Escape hatch: give a row a `key` and pass a named slot `fact-<key>`
    (`<x-slot:fact-status>…</x-slot:fact-status>`) to render any markup as
    that row's value. The row, label and `<dd>` stay the component's, so a
    consumer never hand-rolls a row.

    `layout` picks the shape: `row` (default) keeps label and value on one
    line, the value at the end; `grid` is the description-list look, a label
    column with the value beside it, start-aligned, stacking on a narrow
    screen. Bound rows (`bind`) render as text.

    Wrapping: the label keeps its words whole and takes at most 40% of the
    row; the value takes the rest and may break anywhere, so a URL or a long
    reference wraps inside the column instead of squeezing the label to one
    letter per line.
--}}
@props([
    'facts' => [],
    'bind' => null,
    'size' => 'md',
    'layout' => 'row',
])

@php
    $styles = require base_path(config('ui.component_path', 'resources/views/components/ui').'/_styles.php');
    $recipe = $styles['fact-list'] ?? [];

    $sizeKey = array_key_exists($size, $recipe['sizes'] ?? []) ? $size : 'md';
    $layoutKey = array_key_exists($layout, $recipe['layouts'] ?? []) ? $layout : 'row';
    $shape = $recipe['layouts'][$layoutKey] ?? ['row' => '', 'label' => 'max-w-[40%] shrink-0', 'value' => 'flex-1 text-end'];
    $rowClass = trim(($recipe['row'] ?? '').' '.($recipe['sizes'][$sizeKey] ?? '').' '.$shape['row']);
    $labelClass = trim('text-muted-foreground '.$shape['label']);
    $valueClass = trim('min-w-0 font-medium wrap-anywhere '.$shape['value']);
    $tones = $recipe['tones'] ?? [];
    $types = ['text', 'badge', 'tags', 'paragraph', 'attachment', 'link', 'time'];
    // Named `fact-<key>` slots, read from the component's slot bag so a key
    // never collides with a prop variable. `<x-slot:fact-due-date>` arrives
    // camel-cased, `<x-slot name="fact-due-date">` keeps its dashes.
    $rowSlots = $__laravel_slots ?? [];
    $rowSlot = static function (?string $key) use ($rowSlots) {
        if ($key === null || $key === '') {
            return null;
        }
        $slot = $rowSlots['fact-'.$key] ?? $rowSlots[\Illuminate\Support\Str::camel('fact-'.$key)] ?? null;

        return $slot !== null && trim((string) $slot) !== '' ? $slot : null;
    };
    // A link row becomes a real link, so refuse script-capable schemes.
    // Browsers drop tabs and newlines inside a URL, so judge the scheme without them.
    $safeHref = static function (mixed $href): ?string {
        $href = is_scalar($href) ? trim((string) $href) : '';
        $probe = (string) preg_replace('/[\x00-\x20\x7f]+/', '', $href);
        $scheme = preg_match('/^([a-z][a-z0-9+.-]*):/i', $probe, $match) === 1 ? strtolower($match[1]) : null;

        return $href !== '' && ($scheme === null || in_array($scheme, ['http', 'https', 'mailto', 'tel'], true)) ? $href : null;
    };
    $timeModes = ['datetime', 'date', 'time', 'relative'];

    // Normalise the server-side shape once so the loop below stays a plain
    // readout: `k`/`v` are what the read models emit, `label`/`value` what a
    // Blade author writes by hand.
    $rows = collect((array) $facts)
        ->filter(fn ($entry) => is_array($entry))
        ->map(fn (array $fact): array => [
            'label' => $fact['label'] ?? $fact['k'] ?? '',
            'value' => $fact['value'] ?? $fact['v'] ?? '',
            'tone' => $fact['tone'] ?? null,
            'mono' => (bool) ($fact['mono'] ?? false),
            'type' => in_array($fact['type'] ?? 'text', $types, true) ? ($fact['type'] ?? 'text') : 'text',
            'variant' => $fact['variant'] ?? $fact['badgeVariant'] ?? null,
            'key' => isset($fact['key']) && is_scalar($fact['key']) ? (string) $fact['key'] : null,
            'href' => ($fact['type'] ?? null) === 'link' ? $safeHref($fact['href'] ?? null) : null,
            'external' => (bool) ($fact['external'] ?? false),
            'mode' => ($fact['relative'] ?? false) === true
                ? 'relative'
                : (in_array($fact['mode'] ?? 'datetime', $timeModes, true) ? ($fact['mode'] ?? 'datetime') : 'datetime'),
        ])
        ->values();

    // The JS side reads the same tone map, so a bound row and a server row
    // cannot resolve the same tone to two different classes.
    $toneJson = json_encode($tones, JSON_HEX_TAG | JSON_HEX_APOS | JSON_HEX_AMP | JSON_HEX_QUOT);
@endphp

<dl
    data-slot="fact-list"
    data-size="{{ $sizeKey }}"
    data-layout="{{ $layoutKey }}"
    {{ $attributes->merge(['class' => 'divide-y divide-border']) }}
>
    @if ($bind !== null)
        <template x-for="fact in ({{ $bind }})" :key="fact.k ?? fact.label">
            <div data-slot="fact-list-row" class="{{ $rowClass }}">
                <dt data-slot="fact-list-label" class="{{ $labelClass }}" x-text="fact.k ?? fact.label"></dt>
                <dd
                    data-slot="fact-list-value"
                    class="{{ $valueClass }}"
                    :class="[
                        ({{ $toneJson }})[fact.tone] ?? '',
                        fact.mono ? 'font-mono text-xs' : 'tabular-nums',
                    ]"
                    x-text="fact.v ?? fact.value"
                ></dd>
            </div>
        </template>
    @else
        @foreach ($rows as $fact)
            @php $custom = $rowSlot($fact['key']); @endphp
            <div data-slot="fact-list-row" class="{{ $rowClass }}"@if ($fact['key'] !== null) data-key="{{ $fact['key'] }}"@endif>
                <dt data-slot="fact-list-label" class="{{ $labelClass }}">{{ $fact['label'] }}</dt>
                @if ($custom !== null)
                    <dd data-slot="fact-list-value" data-type="slot" class="{{ $valueClass }}">{{ $custom }}</dd>
                @else
                <dd
                    data-slot="fact-list-value"
                    data-type="{{ $fact['type'] }}"
                    @if ($fact['tone'] !== null) data-tone="{{ $fact['tone'] }}" @endif
                    @class([
                        $valueClass,
                        $tones[$fact['tone']] ?? '' => $fact['tone'] !== null && $fact['type'] === 'text',
                        'font-mono text-xs' => $fact['mono'] && $fact['type'] === 'text',
                        'tabular-nums' => (! $fact['mono'] && $fact['type'] === 'text') || $fact['type'] === 'time',
                        'font-normal leading-relaxed text-foreground' => $fact['type'] === 'paragraph',
                        'font-normal' => in_array($fact['type'], ['badge', 'tags', 'attachment'], true),
                    ])
                >
                    @if ($fact['type'] === 'badge')
                        <x-ui.badge :variant="$fact['variant'] ?? 'secondary'" :tone="$fact['tone']">{{ $fact['value'] }}</x-ui.badge>
                    @elseif ($fact['type'] === 'tags')
                        <ul role="list" class="flex flex-wrap gap-2" aria-label="{{ $fact['label'] }}">
                            @foreach ((array) $fact['value'] as $tag)
                                <li><x-ui.badge :variant="$fact['variant'] ?? 'outline'" size="sm">{{ $tag }}</x-ui.badge></li>
                            @endforeach
                        </ul>
                    @elseif ($fact['type'] === 'attachment')
                        <ul role="list" class="space-y-2">
                            @foreach ((array) $fact['value'] as $file)
                                <li data-slot="fact-list-attachment" class="flex items-center justify-between gap-4 rounded-md border border-border p-2">
                                    <span class="flex min-w-0 items-center gap-2">
                                        <svg class="size-4 shrink-0 text-muted-foreground" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">
                                            <path d="m21.44 11.05-9.19 9.19a6 6 0 0 1-8.49-8.49l8.57-8.57A4 4 0 1 1 18 8.84l-8.59 8.57a2 2 0 0 1-2.83-2.83l8.49-8.48" />
                                        </svg>
                                        <span class="truncate text-foreground">{{ $file['name'] ?? '' }}</span>
                                        @if (! empty($file['size']))
                                            <span class="shrink-0 text-xs text-muted-foreground">{{ $file['size'] }}</span>
                                        @endif
                                    </span>
                                    {{-- download: '' keeps the file's own name, a string names the saved file, false opens the link instead. --}}
                                    <x-ui.button variant="ghost" size="sm" :href="$file['href'] ?? null" :download="filled($file['href'] ?? null) && ($file['download'] ?? '') !== false ? (string) ($file['download'] ?? '') : null" class="shrink-0" :aria-label="__('Download :file', ['file' => $file['name'] ?? ''])">
                                        <svg class="size-4" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">
                                            <path d="M21 15v4a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2v-4" /><polyline points="7 10 12 15 17 10" /><line x1="12" y1="15" x2="12" y2="3" />
                                        </svg>
                                    </x-ui.button>
                                </li>
                            @endforeach
                        </ul>
                    @elseif ($fact['type'] === 'link' && $fact['href'] !== null)
                        <a
                            data-slot="fact-list-link"
                            href="{{ $fact['href'] }}"
                            @if ($fact['external']) target="_blank" rel="noopener noreferrer" @endif
                            class="rounded-sm text-foreground underline decoration-border underline-offset-4 transition-colors hover:decoration-foreground focus-visible:outline-none focus-visible:ring-[length:var(--ring-width)] focus-visible:ring-ring"
                        >{{ filled($fact['value']) ? $fact['value'] : $fact['href'] }}@if ($fact['external'])<x-ui.icon name="external-link" size="xs" class="ms-1 inline-block align-middle text-muted-foreground" /><span class="sr-only"> {{ __('(opens in a new tab)') }}</span>@endif</a>
                    @elseif ($fact['type'] === 'time')
                        <x-ui.relative-time :datetime="$fact['value']" :mode="$fact['mode']" class="!text-inherit" />
                    @else
                        {{ $fact['value'] }}
                    @endif
                </dd>
                @endif
            </div>
        @endforeach
    @endif
</dl>