Check List

# Brok UI: Check List (`check-list`)

A bullet list whose marker is a check glyph — plan features, comparison points, what-you-get rows — from a server array or item children, with a plain or chip marker, a tone, three sizes and an excluded state.

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

## Install

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

## Usage

```blade
<x-ui.check-list class="max-w-sm" :items="[
    __('Unlimited projects and collaborators'),
    __('Design tokens for light and dark'),
    __('Priority support with a one-day response'),
    __('Export to Blade, Livewire or plain HTML'),
]" />
```

## Props

- `items` (array, default `[]`) — Rows rendered on the server. A bare string is a row; an array row is `['label', 'included' => true, 'tone' => null, 'icon' => null, 'status' => null, 'statusLabel' => null]`. Combine with, or replace by, `<x-ui.check-list.item>` children in the default slot.
- `marker` ('plain'|'chip', default `plain`) — `plain` draws the bare glyph in the tone colour; `chip` sits it in a small tinted disc.
- `tone` ('primary'|'success'|'muted'|'destructive'|'foreground', default `primary`) — Marker colour by meaning. An item may override it with its own `tone`.
- `size` ('sm'|'md'|'lg', default `md`) — Type size and row gap: `sm` (text-sm, 8px), `md` (text-sm, 12px), `lg` (text-base, 16px).
- `icon` ('check'|'cross'|'dash'|'circle', default `check`) — The glyph every row draws unless it names its own. An excluded row swaps `check` for `dash` on its own.
- `layout` ('stack'|'row', default `stack`) — `stack` is one column; `row` lays the rows out as a wrapping line (trust points under a call to action, key results beside a case study).
- `included` (bool, default `true`) — Declared by @props in the registry Blade source.
- `status` (mixed|null, default `null`) — Declared by @props in the registry Blade source.
- `statusLabel` (mixed|null, default `null`) — Declared by @props in the registry Blade source.

## Use when

- Use to summarize, sequence, or present data so users can scan it quickly.
- A pricing tier, comparison column, hero or feature split lists what is included, one short point per row.
- A row must read as excluded (a feature the plan lacks) next to the included ones — pass `included => false`.

## Avoid when

- Do not add display-only ornament when the user needs actionable structure or exact comparison instead.
- The rows are label/value pairs — use `fact-list`.
- Each row is a task the visitor completes — use `todo-item` or `checkbox`.
- The list needs numbering or step semantics — use `stepper` or `timeline-steps`.

## Anti-patterns

- Adding display ornament without informational value

## Rules

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

{{--
    Check List — the bullet list whose marker is a check glyph: the features
    a plan includes, the points a comparison column makes, the "what you get"
    row under a hero. One `<ul>`, one marker treatment, one tone, instead of
    the five check paths and four icon treatments the blocks used to draw.

    Two sources, one markup:

      - `items` — a PHP array. A bare string is a row; an array row is
        `['label', 'included' => true, 'tone' => null, 'icon' => null,
        'status' => null, 'statusLabel' => null]`.
      - the default slot — `<x-ui.check-list.item>` children, for a row that
        carries more than a string (a badge, a tooltip, a translated label
        the block builds itself).

    `marker` sets the treatment: `plain` is the bare glyph in the tone colour,
    `chip` sits it in a small tinted disc. `tone` colours the marker by
    meaning (primary, success, muted, destructive). `size` scales the type
    and the row gap. `icon` picks the glyph (check, cross, dash); an excluded
    row (`included => false`) turns muted and swaps the check for a dash.
    A result row (`status` passed, failed or pending) takes its own glyph and
    tone; excluded and status rows say their state to screen readers.
    `layout="row"` lays the rows out as a wrapping line — the trust points
    under a call to action, the key results beside a case study.
--}}
@props([
    'items' => [],
    'marker' => 'plain',
    'tone' => 'primary',
    'size' => 'md',
    'icon' => 'check',
    'layout' => 'stack',
])

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

    $marker = array_key_exists($marker, $recipe['markers'] ?? []) ? $marker : 'plain';
    $tone = array_key_exists($tone, $recipe['tones'] ?? []) ? $tone : 'primary';
    $size = array_key_exists($size, $recipe['sizes'] ?? []) ? $size : 'md';
    $layout = array_key_exists($layout, $recipe['layouts'] ?? []) ? $layout : 'stack';
    $listClass = trim(($recipe['layouts'][$layout] ?? '').' '.($recipe['sizes'][$size]['list'] ?? '').($layout === 'stack' ? ' '.($recipe['sizes'][$size]['stack'] ?? '') : ''));

    // Normalise the array shape once so the loop stays a plain readout: a bare
    // string is a row, an array row may carry its own tone/icon/included flag.
    $rows = collect((array) $items)
        ->map(fn ($entry): array => is_array($entry)
            ? [
                'label' => (string) ($entry['label'] ?? $entry['text'] ?? ''),
                'included' => (bool) ($entry['included'] ?? true),
                'tone' => $entry['tone'] ?? null,
                'icon' => $entry['icon'] ?? null,
                'status' => $entry['status'] ?? null,
                'statusLabel' => $entry['statusLabel'] ?? null,
            ]
            : ['label' => (string) $entry, 'included' => true, 'tone' => null, 'icon' => null, 'status' => null, 'statusLabel' => null])
        ->values();
@endphp

<ul
    data-slot="check-list"
    data-marker="{{ $marker }}"
    data-tone="{{ $tone }}"
    data-size="{{ $size }}"
    data-layout="{{ $layout }}"
    role="list"
    {{ $attributes->merge(['class' => $listClass]) }}
>
    @foreach ($rows as $row)
        <x-ui.check-list.item
            :marker="$marker"
            :tone="$row['tone'] ?? ($row['status'] !== null ? null : ($row['included'] ? $tone : 'muted'))"
            :size="$size"
            :icon="$row['icon'] ?? $icon"
            :included="$row['included']"
            :status="$row['status']"
            :status-label="$row['statusLabel']"
        >{{ $row['label'] }}</x-ui.check-list.item>
    @endforeach

    {{ $slot }}
</ul>

@aware([
    'marker' => 'plain',
    'tone' => 'primary',
    'size' => 'md',
    'icon' => 'check',
])

{{-- `marker`, `size` and `icon` are inherited from the list through @aware and
     may also be set per row, so they are declared as props too: a prop
     declaration is what keeps an explicitly passed value from being stripped
     off the aware variable. `tone` stays off the prop list on purpose — reading
     it from the bag tells an explicit row tone apart from the inherited one. --}}
@props([
    'included' => true,
    'marker' => 'plain',
    'size' => 'md',
    'icon' => 'check',
    // A result row: passed, failed or pending. Sets the glyph and tone
    // (check/success, cross/destructive, circle/muted) and a screen-reader
    // word before the text, so the state is never only an icon or a colour.
    'status' => null,
    // Replaces the screen-reader word of a status or excluded row.
    'statusLabel' => null,
])

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

    $marker = array_key_exists((string) $marker, $recipe['markers'] ?? []) ? $marker : 'plain';
    $size = array_key_exists((string) $size, $recipe['sizes'] ?? []) ? $size : 'md';
    $icon = is_string($icon) && $icon !== '' ? $icon : 'check';
    $included = filter_var($included, FILTER_VALIDATE_BOOLEAN);

    // An excluded row reads as "not in this plan": muted marker, dash glyph,
    // muted text — unless the caller names a tone or glyph for it explicitly.
    $rowTone = $attributes->get('tone');
    $explicitTone = $rowTone !== null;
    $tone = $rowTone ?? ($tone ?? 'primary');
    $tone = array_key_exists((string) $tone, $recipe['tones'] ?? []) ? $tone : 'primary';
    $resolvedTone = $included || $explicitTone ? $tone : 'muted';
    $resolvedIcon = $included ? $icon : ($icon === 'check' ? 'dash' : $icon);

    // A status row picks its own glyph and tone unless the row names them.
    $statuses = [
        'passed' => ['icon' => 'check', 'tone' => 'success', 'label' => __('Passed')],
        'failed' => ['icon' => 'cross', 'tone' => 'destructive', 'label' => __('Failed')],
        'pending' => ['icon' => 'circle', 'tone' => 'muted', 'label' => __('Pending')],
    ];
    $status = is_string($status) && array_key_exists($status, $statuses) ? $status : null;
    if ($status !== null) {
        $resolvedTone = $explicitTone ? $tone : $statuses[$status]['tone'];
        $resolvedIcon = $icon !== 'check' ? $icon : $statuses[$status]['icon'];
    }

    // The words a screen reader hears before the text: the status, or "Not
    // included" on an excluded row, whose dash and muted colour are not read.
    $stateText = match (true) {
        filled($statusLabel) => (string) $statusLabel,
        $status !== null => $statuses[$status]['label'],
        ! $included => __('Not included'),
        default => null,
    };

    $glyphs = [
        'check' => '<path d="M20 6 9 17l-5-5" />',
        'cross' => '<path d="M18 6 6 18M6 6l12 12" />',
        'dash' => '<path d="M5 12h14" />',
        'circle' => '<circle cx="12" cy="12" r="8" />',
    ];
    $glyph = $glyphs[$resolvedIcon] ?? $glyphs['check'];

    $sizes = $recipe['sizes'][$size] ?? [];
    $toneClass = $recipe['tones'][$resolvedTone][$marker] ?? '';
    $markerClass = trim(($recipe['markers'][$marker] ?? '').' '.$toneClass.' '.($sizes[$marker === 'chip' ? 'chip-box' : 'glyph'] ?? ''));
    $svgClass = $marker === 'chip' ? ($sizes['chip-glyph'] ?? 'size-3') : 'size-full';
@endphp

<li
    data-slot="check-list-item"
    @if (! $included) data-included="false" @endif
    @if ($status !== null) data-status="{{ $status }}" @endif
    {{ $attributes->except('tone')->merge(['class' => trim(($recipe['item'] ?? '').' '.($sizes[$marker] ?? '').($included ? '' : ' '.($recipe['excluded'] ?? '')))]) }}
>
    <span data-slot="check-list-marker" class="{{ $markerClass }}" aria-hidden="true">
        <svg class="{{ $svgClass }}" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">{!! $glyph !!}</svg>
    </span>
    <span data-slot="check-list-text" class="{{ $recipe['text'] ?? 'min-w-0 flex-1' }}">@if ($stateText !== null)<span data-slot="check-list-state" class="sr-only">{{ __(':state:', ['state' => $stateText]) }} </span>@endif{{ $slot }}</span>
</li>