Partition Bar

# Brok UI: Partition Bar (`partition-bar`)

A horizontal bar that visualises segments of a whole with proportional widths, variants and text alignment. Supports an opt-in nested mode for overlapping subsets of one total, with an explicit unknown state.

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

## Install

```bash
php artisan ui:add partition-bar
```

## Usage

```blade
<div class="flex w-full max-w-lg flex-col gap-6">
    <x-ui.partition-bar
        size="xs"
        :segments="[
            ['label' => __('Compute'), 'value' => '48%', 'num' => 48],
            ['label' => __('Storage'), 'value' => '32%', 'num' => 32],
            ['label' => __('Bandwidth'), 'value' => '20%', 'num' => 20],
        ]"
    />

    <x-ui.partition-bar
        :segments="[
            ['label' => __('Compute'), 'value' => '$1,240', 'num' => 48],
            ['label' => __('Storage'), 'value' => '$820', 'num' => 32],
            ['label' => __('Bandwidth'), 'value' => '$510', 'num' => 20],
        ]"
    />
</div>
```

## Props

- `gap` (int, default `1`) — Gap between segments in Tailwind spacing units (1 = 0.25rem); ignored in nested mode.
- `size` (md|xs|sm|lg, default `md`) — sm/md/lg carry labels inside each segment; xs renders a thin track whose labels live in the legend below it.
- `segments` (mixed|null, default `null`) — Data-driven alternative to slotted segments: a list of {label, value, num, variant} objects; num falls back to the numeric value when omitted.
- `legend` (mixed|null, default `null`) — Renders a colour-dot/label/value legend under the bar; defaults on for the xs track, which has no room for inline labels.
- `nested` (bool, default `false`) — Draws segments as overlapping subsets of one shared total instead of side-by-side proportional siblings.
- `total` (mixed|null, default `null`) — Nested mode only: the common denominator every segment's value is a fraction of.
- `label` (mixed|null, default `null`) — Nested mode only: an accessible group label summarising the whole bar, read before each segment's own value.
- `variant` (default|secondary|destructive|outline|muted|chart-1|chart-2|chart-3|chart-4|chart-5, default `default`) — Documented catalog control used by the preview workbench.
- `num` (int, default `0`) — Declared by @props in the registry Blade source.
- `alignment` (string, default `center`) — Declared by @props in the registry Blade source.
- `value` (mixed|null, default `null`) — Declared by @props in the registry Blade source.
- `unknown` (bool, default `false`) — Declared by @props in the registry Blade source.

## Use when

- Use when trend, distribution, flow, intensity, or relationship questions are easier to answer visually than in raw numbers.
- Breaking a whole into proportional, side-by-side shares, such as a storage or budget breakdown.
- Showing nested/overlapping subsets of one total (shipped within picked within allocated) via nested mode.

## 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 parts don't sum to a meaningful whole; use chart's bar type for unrelated comparisons instead.
- Only one value against a range is needed, not a breakdown into parts; use gauge or circular-progress instead.

## Anti-patterns

- Decorative charts without a meaningful question

## Rules

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

@props([
    'gap' => 1,
    // sm | md | lg carry their labels inside each segment; xs is a thin track
    // whose labels live in the legend below it.
    'size' => 'md',
    // Data-driven alternative to slotted segments: each ['label' => string,
    // 'value' => number|string (display), 'num' => number (share), 'variant' => string].
    // When `num` is omitted the numeric `value` is used as the share.
    'segments' => null,
    // Render a legend (colour dot, label, value) under the bar — the default for
    // the xs track, since it has no room for inline labels.
    'legend' => null,
    // Opt-in: draw segments as overlapping subsets of one shared `total`
    // (e.g. shipped ⊆ picked ⊆ allocated ⊆ ordered) instead of side-by-side
    // proportional siblings. `total` is the common denominator every nested
    // segment's `value` prop is a fraction of.
    'nested' => false,
    'total' => null,
    // Nested mode only: an accessible group label summarising the whole bar
    // (e.g. "Allocation progress"), read before each segment's own value.
    'label' => null,
])

@php
    $styles = require base_path(config('ui.component_path', 'resources/views/components/ui').'/_styles.php');

    // Sizes drive the bar height + base type scale; segments stretch to fill.
    $sizes = [
        'xs' => 'h-2 text-xs',
        'sm' => 'h-7 text-xs',
        'md' => 'h-9 text-sm',
        'lg' => 'h-11 text-sm',
    ];
    $size = array_key_exists($size, $sizes) ? $size : 'md';
    $track = $size === 'xs';
    $legend = $legend === null ? $track : filter_var($legend, FILTER_VALIDATE_BOOLEAN);

    // `gap` is expressed in Tailwind spacing units (1 = 0.25rem) to match the
    // reference API; emit it as an inline gap so any value works without a
    // pre-generated utility class. A thin track reads as one bar, so its gap
    // is a hairline. Meaningless in nested mode — overlapping segments share
    // one track, so it is omitted there rather than adding dead space.
    $gapRem = $track ? 0.125 : ((float) $gap) * 0.25;

    // Legend swatch per variant (kept in step with the segment fills). The
    // chart-N hues come from the recipe shared with chart-tooltip/chart-legend;
    // the variant-specific overrides below take precedence over any overlap.
    $swatches = array_merge($styles['chart']['swatches'], [
        'default' => 'bg-primary',
        'secondary' => 'bg-secondary',
        'destructive' => 'bg-destructive',
        'outline' => 'border border-border bg-background',
        'muted' => 'bg-muted',
    ]);

    $rows = [];
    if (is_array($segments)) {
        $chart = $styles['chart']['palette'];
        foreach (array_values($segments) as $i => $seg) {
            $rows[] = [
                'label' => $seg['label'] ?? '',
                'value' => $seg['value'] ?? null,
                'num' => (float) ($seg['num'] ?? (is_numeric($seg['value'] ?? null) ? $seg['value'] : 1)),
                'variant' => $seg['variant'] ?? $chart[$i % count($chart)],
            ];
        }
    }
@endphp

<div
    data-slot="partition-bar"
    data-size="{{ $size }}"
    {{ $attributes->merge(['class' => 'w-full '.($legend ? 'flex flex-col gap-2' : '')]) }}
>
    <div
        data-slot="partition-bar-track"
        @if ($nested)
            data-nested="true"
            @if ($label !== null) role="group" aria-label="{{ $label }}" @endif
            style="position:relative;"
        @else
            style="display:flex; align-items:stretch; gap:{{ $gapRem }}rem;"
        @endif
        @class([
            'w-full',
            $sizes[$size],
            'overflow-hidden rounded-full' => $track,
        ])
    >
        @if ($rows !== [])
            @foreach ($rows as $row)
                <x-ui.partition-bar.segment :num="$row['num']" :variant="$row['variant']" alignment="left" :title="$track ? trim($row['label'].' '.$row['value']) : null">
                    @unless ($track)
                        {{-- Data-driven cells read label and value on one line. --}}
                        <span class="flex w-full items-baseline justify-between gap-2">
                            <x-ui.partition-bar.title class="w-auto">{{ $row['label'] }}</x-ui.partition-bar.title>
                            @if ($row['value'] !== null)
                                <x-ui.partition-bar.value class="w-auto opacity-70">{{ $row['value'] }}</x-ui.partition-bar.value>
                            @endif
                        </span>
                    @endunless
                </x-ui.partition-bar.segment>
            @endforeach
        @else
            {{ $slot }}
        @endif
    </div>

    @if ($legend && $rows !== [])
        <dl data-slot="partition-bar-legend" class="flex flex-wrap gap-x-4 gap-y-1 text-xs">
            @foreach ($rows as $row)
                <div class="flex items-center gap-2">
                    <dt class="flex items-center gap-2">
                        <span aria-hidden="true" class="size-2 shrink-0 rounded-full {{ $swatches[$row['variant']] ?? $swatches['default'] }}"></span>
                        <span class="text-muted-foreground">{{ $row['label'] }}</span>
                    </dt>
                    @if ($row['value'] !== null)
                        <dd class="font-medium tabular-nums text-foreground">{{ $row['value'] }}</dd>
                    @endif
                </div>
            @endforeach
        </dl>
    @endif
</div>

@aware([
    'nested' => false,
    'total' => null,
    'size' => 'md',
])

@props([
    'num' => 0,
    'variant' => 'default',
    'alignment' => 'center',
    // Nested mode only (ignored otherwise): this segment's raw quantity out of
    // the parent bar's `total`, whether that quantity is not known at all, and
    // the accessible name read for it (nested segments overlap, so there is no
    // room left for visible title/value text — see the nested branch below).
    'value' => null,
    'unknown' => false,
    'label' => null,
])

@php
    $styles = require base_path(config('ui.component_path', 'resources/views/components/ui').'/_styles.php');
    $variant = $styles['normalizeVariant']($variant);
    $track = $size === 'xs';
    $variants = [
        'default' => 'bg-primary text-primary-foreground',
        'secondary' => 'bg-secondary text-secondary-foreground',
        'destructive' => 'bg-destructive text-destructive-foreground',
        'outline' => 'border border-border bg-background text-foreground',
        'muted' => 'bg-muted text-muted-foreground',
        // Neutral chart hues for a breakdown with no status meaning. In a
        // labelled cell the hue is a tint with foreground text (white on amber
        // would not pass); in the thin track it is the solid hue.
        'chart-1' => $track ? 'bg-chart-1' : 'bg-chart-1/15 text-foreground',
        'chart-2' => $track ? 'bg-chart-2' : 'bg-chart-2/15 text-foreground',
        'chart-3' => $track ? 'bg-chart-3' : 'bg-chart-3/15 text-foreground',
        'chart-4' => $track ? 'bg-chart-4' : 'bg-chart-4/15 text-foreground',
        'chart-5' => $track ? 'bg-chart-5' : 'bg-chart-5/15 text-foreground',
    ];
    // A tinted cell carries a solid accent bar on its start edge so the hue
    // still reads at a glance.
    $accents = [
        'chart-1' => 'border-chart-1', 'chart-2' => 'border-chart-2', 'chart-3' => 'border-chart-3',
        'chart-4' => 'border-chart-4', 'chart-5' => 'border-chart-5',
    ];

    $aligns = [
        'left' => 'items-start text-left',
        'center' => 'items-center text-center',
        'right' => 'items-end text-right',
    ];

    // Inside an xs track the segments are bare fills (the parent clips the
    // track to a pill); otherwise each is a rounded labelled cell.
    $classes = 'min-w-0 overflow-hidden '
        .($track ? 'h-full transition-[flex] duration-300 motion-reduce:transition-none ' : 'flex h-full flex-col justify-center rounded-md px-3 leading-tight ')
        .($variants[$variant] ?? $variants['default']).' '
        .($track ? '' : ($aligns[$alignment] ?? $aligns['center']))
        .(! $track && isset($accents[$variant]) ? ' border-s-[3px] '.$accents[$variant] : '');
@endphp

@if ($nested)
    @php
        // Border token used for the "unknown" outline below — same family as
        // the solid fill so a muted/destructive/etc. unknown segment still
        // reads as belonging to that variant.
        $borderVariants = [
            'default' => 'border-primary',
            'secondary' => 'border-secondary',
            'destructive' => 'border-destructive',
            'outline' => 'border-border',
            'muted' => 'border-muted-foreground',
            'chart-1' => 'border-chart-1',
            'chart-2' => 'border-chart-2',
            'chart-3' => 'border-chart-3',
            'chart-4' => 'border-chart-4',
            'chart-5' => 'border-chart-5',
        ];

        // Never divide by zero, and never let a blank/zero total quietly
        // render every known segment full-width — the same guard a hand-rolled
        // version of this would need (`max(1, $ordered)`).
        $scale = max(1, (float) $total);
        $rawValue = is_numeric($value) ? (float) $value : 0.0;

        // A subset that reports more than its own total is a data error, not a
        // layout crash: the drawn width clamps at 100% (never overflows the
        // track) but `data-overflow` keeps the bad input inspectable in
        // devtools/tests instead of silently hiding it.
        $overflow = ! $unknown && $rawValue > $scale;
        $fraction = $scale > 0 ? min(1, $rawValue / $scale) : 0;
        $width = round($fraction * 100, 2);

        // "Unknown" is not zero and must not be drawn as a proportional fill —
        // any width we picked for it would state a fact ("it is about this
        // much") that the caller told us we do not have. It renders instead as
        // a fixed-width dashed/hatched marker: constant regardless of `total`,
        // so it never looks like a measurement. Equal-width known segments
        // (or an unknown marker landing on top of one) simply show whichever
        // was rendered last — compose nested segments widest-first so the
        // narrower, more advanced ones sit visibly on top, exactly as the
        // shared denominator implies.
        $ariaLabel = $unknown
            ? ($label !== null ? __(':label: unknown', ['label' => $label]) : __('Unknown'))
            : ($label !== null
                ? __(':label: :value of :total', ['label' => $label, 'value' => (int) $rawValue, 'total' => (int) $scale])
                : __(':value of :total', ['value' => (int) $rawValue, 'total' => (int) $scale]));
    @endphp
    <div
        data-slot="partition-bar-segment"
        data-variant="{{ $variant }}"
        data-state="{{ $unknown ? 'unknown' : 'known' }}"
        @if ($overflow) data-overflow="true" @endif
        role="img"
        aria-label="{{ $ariaLabel }}"
        {{ $attributes->merge([
            'class' => $unknown
                ? 'absolute inset-y-0 start-0 w-3 rounded-md border-2 border-dashed bg-transparent '.($borderVariants[$variant] ?? $borderVariants['default'])
                : 'absolute inset-y-0 start-0 h-full rounded-md '.($variants[$variant] ?? $variants['default']),
        ]) }}
        @unless ($unknown) style="width: {{ $width }}%;" @endunless
    ></div>
@else
    <div
        data-slot="partition-bar-segment"
        data-variant="{{ $variant }}"
        style="flex:{{ (float) $num }} 1 0%;"
        {{ $attributes->merge(['class' => $classes]) }}
    >
        {{ $slot }}
    </div>
@endif