API Reference Table

# Brok UI: API Reference Table (`api-reference-table`)

A documentation table listing a component's props with colour-coded type tokens, defaults, required markers and descriptions.

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

## Install

```bash
php artisan ui:add api-reference-table
```

## Usage

```blade
<x-ui.api-reference-table
    title="Button"
    :props="[
        ['name' => 'variant', 'type' => '\'default\' | \'outline\' | \'ghost\'', 'default' => 'default', 'description' => 'Visual style of the button.'],
        ['name' => 'size', 'type' => '\'sm\' | \'md\' | \'lg\'', 'default' => 'md', 'description' => 'Control height and padding.'],
        ['name' => 'disabled', 'type' => 'boolean', 'default' => 'false', 'description' => 'Prevent interaction and dim the control.'],
        ['name' => 'href', 'type' => 'string', 'required' => true, 'description' => 'Render as a link to this destination.'],
    ]"
/>
```

## Props

- `title` (mixed|null, default `null`)
- `props` (array, default `[]`)

## Use when

- Use for exact technical detail, code readability, diagnostics, and copyable reference material.
- Documenting a component's props with their types, defaults and required markers.
- Giving a reference table the same shape on every docs page.

## Avoid when

- Do not surface developer-specific patterns in end-user flows unless the task genuinely requires them.
- Presenting arbitrary tabular data; table is the general primitive.
- Documenting a single prop, where prose is shorter than a table.

## Anti-patterns

- Exposing developer tooling in end-user flows without a task need

## Rules

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

@props([
    'title' => null,
    'props' => [],
])

@php
    // Each prop is ['name' => string, 'type' => string, 'default' => ?string,
    // 'description' => ?string, 'required' => ?bool]. Type strings are colour-
    // coded by shape: a union (contains "|") reads as info, primitives as
    // primary, everything else as foreground — all via semantic tokens.
    $typeTone = function (string $type): string {
        $t = trim($type);
        if (str_contains($t, '|')) {
            return 'text-info';
        }
        if (preg_match('/^(string|number|boolean|bool|int|float|true|false|null)\b/i', $t)) {
            return 'text-primary';
        }
        return 'text-foreground';
    };
@endphp

<div
    data-slot="api-reference-table"
    {{ $attributes->merge(['class' => 'overflow-hidden rounded-lg border border-border bg-card text-foreground']) }}
>
    @if ($title !== null)
        <div class="border-b border-border bg-muted/40 px-4 py-2 text-sm font-semibold">
            <code class="font-mono">{{ $title }}</code>
        </div>
    @endif

    <div class="overflow-x-auto">
        <table class="w-full border-collapse text-sm">
            <thead>
                <tr class="border-b border-border bg-muted/20 text-start text-xs font-medium uppercase tracking-wide text-muted-foreground">
                    <th scope="col" class="px-4 py-2 text-start font-medium">{{ __('Prop') }}</th>
                    <th scope="col" class="px-4 py-2 text-start font-medium">{{ __('Type') }}</th>
                    <th scope="col" class="px-4 py-2 text-start font-medium">{{ __('Default') }}</th>
                    <th scope="col" class="px-4 py-2 text-start font-medium">{{ __('Description') }}</th>
                </tr>
            </thead>
            <tbody>
                @foreach ($props as $prop)
                    @php
                        $required = filter_var($prop['required'] ?? false, FILTER_VALIDATE_BOOLEAN);
                        $type = (string) ($prop['type'] ?? '');
                        $default = $prop['default'] ?? null;
                    @endphp
                    <tr class="border-b border-border align-top last:border-0">
                        <td class="whitespace-nowrap px-4 py-2">
                            <code class="font-mono font-medium text-foreground">{{ $prop['name'] ?? '' }}</code>@if ($required)<span class="ms-0.5 text-destructive" title="{{ __('Required') }}" aria-label="{{ __('Required') }}">*</span>@endif
                        </td>
                        <td class="px-4 py-2">
                            @if ($type !== '')
                                <code class="inline-block rounded bg-muted px-2 py-0.5 font-mono text-xs {{ $typeTone($type) }}">{{ $type }}</code>
                            @endif
                        </td>
                        <td class="whitespace-nowrap px-4 py-2">
                            <code class="font-mono text-xs text-muted-foreground">{{ $default !== null && $default !== '' ? $default : '—' }}</code>
                        </td>
                        <td class="px-4 py-2 text-muted-foreground">{{ $prop['description'] ?? '' }}</td>
                    </tr>
                @endforeach
            </tbody>
        </table>
    </div>
</div>