Section Heading

# Brok UI: Section Heading (`section-heading`)

A marketing section heading — an optional overline, a balanced title and a supporting subtitle, left- or centre-aligned and optionally laid over a photographic background with a token gradient scrim.

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

## Install

```bash
php artisan ui:add section-heading
```

## Usage

```blade
<div class="w-full">
    <x-ui.section-heading
        align="center"
        overline="Small steps, big change"
        title="Wellness that works for you"
        subtitle="Discover mindful habits and eco-friendly products that inspire a healthier, more balanced lifestyle."
    />
</div>
```

## Props

- `align` (start|center, default `start`) — Horizontal alignment of the overline/title/subtitle column.
- `overline` (string|null, default `null`) — Eyebrow text; omitted when empty.
- `overlineStyle` (mono|label|badge|editorial, default `label`) — Eyebrow treatment: `mono` monospace tracked caps, `label` (default) `text-sm font-semibold uppercase tracking-wide text-primary`, `badge` renders `<x-ui.badge variant="secondary">`, `editorial` `font-body` wide-tracked caps.
- `size` (md|lg, default `md`) — Title scale: `md` (default) `text-3xl sm:text-4xl` matches the dominant block h2; `lg` `text-4xl sm:text-5xl` for a hero-weight lede.
- `width` (sm|md, default `sm`) — Content-column max width: `sm` (default) `max-w-2xl`, the dominant block heading column; `md` `max-w-3xl`.
- `title` (string|null, default `null`) — Title text; the default slot wins when both are given. No title and an empty slot render no heading element.
- `subtitle` (string|null, default `null`) — Supporting copy; omitted when empty.
- `image` (string|null, default `null`) — Background photo URL; adds a token gradient scrim and switches the wrapper to an inset surface.
- `as` (h1|h2|h3, default `h2`) — Rendered heading tag.

## Use when

- Use to structure hierarchy, spacing, and responsiveness so content is easier to scan and navigate.
- Leading a marketing section with an overline, title and subtitle.
- The heading needs to match the block's own rhythm rather than ship demo copy.

## Avoid when

- Do not let layout primitives substitute for semantics, headings, or interaction rules users still need.
- The heading is a page or card title, not a marketing section lede; use `<h2>`/`<x-ui.card>` heading slots directly.

## Anti-patterns

- Using visual layout as a substitute for semantic structure

## Rules

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

@props([
    'align' => 'start',
    'overline' => null,
    'overlineStyle' => 'label',
    'size' => 'md',
    'width' => 'sm',
    'title' => null,
    'subtitle' => null,
    'image' => null,
    'as' => 'h2',
])

@php
    // A marketing section heading: an optional overline (eyebrow), a balanced
    // title and a supporting subtitle, left- or centre-aligned, optionally laid
    // over a photographic background. Title/subtitle accept either props or the
    // default slot (slot wins, so it can carry inline markup). Neither has demo
    // copy: a heading with no title and an empty slot renders nothing.
    $isCenter = $align === 'center';
    $tag = in_array($as, ['h1', 'h2', 'h3'], true) ? $as : 'h2';
    $hasImage = filled($image);
    $hasTitle = trim($slot) !== '' || filled($title);

    $overlineStyles = [
        'mono' => 'font-mono text-xs font-medium uppercase tracking-[0.2em] text-muted-foreground',
        'label' => 'text-sm font-semibold uppercase tracking-wide text-primary',
        'editorial' => 'font-body text-sm uppercase tracking-[0.3em] text-muted-foreground',
    ];
    $overlineStyleKey = array_key_exists($overlineStyle, $overlineStyles) || $overlineStyle === 'badge' ? $overlineStyle : 'label';

    $titleSizes = [
        'md' => 'text-balance text-3xl font-bold tracking-tight text-foreground sm:text-4xl',
        'lg' => 'text-balance text-4xl font-bold tracking-tight text-foreground sm:text-5xl',
    ];
    $sizeKey = array_key_exists($size, $titleSizes) ? $size : 'md';

    $widths = [
        'sm' => 'max-w-2xl',
        'md' => 'max-w-3xl',
    ];
    $widthKey = array_key_exists($width, $widths) ? $width : 'sm';

    $wrapperClasses = $hasImage
        ? 'relative isolate overflow-hidden rounded-lg border border-border px-6 py-16 sm:px-10 sm:py-24'
        : '';

    $contentClasses = trim(
        'flex '.$widths[$widthKey].' flex-col gap-4 '
        .($isCenter ? 'mx-auto items-center text-center' : 'items-start text-start')
        .($hasImage ? ' relative z-10' : '')
    );
@endphp

<div
    data-slot="section-heading"
    data-align="{{ $align }}"
    @if ($hasImage) data-surface="image" @endif
    {{ $attributes->merge(['class' => trim($wrapperClasses.' text-foreground')]) }}
>
    @if ($hasImage)
        <img src="{{ $image }}" alt="" aria-hidden="true" class="pointer-events-none absolute inset-0 -z-10 size-full object-cover" />
        <div class="pointer-events-none absolute inset-0 -z-10 bg-gradient-to-t from-background via-background/70 to-background/40" aria-hidden="true"></div>
    @endif

    <div class="{{ $contentClasses }}">
        @if (filled($overline))
            @if ($overlineStyleKey === 'badge')
                <x-ui.badge variant="secondary">{{ __($overline) }}</x-ui.badge>
            @else
                <p data-slot="section-heading-overline" class="{{ $overlineStyles[$overlineStyleKey] }}">
                    {{ __($overline) }}
                </p>
            @endif
        @endif

        @if ($hasTitle)
            <{{ $tag }} data-slot="section-heading-title" class="{{ $titleSizes[$sizeKey] }}">
                {{ trim($slot) !== '' ? $slot : __($title) }}
            </{{ $tag }}>
        @endif

        @if (filled($subtitle))
            <p data-slot="section-heading-subtitle" class="text-pretty text-lg text-muted-foreground">
                {{ __($subtitle) }}
            </p>
        @endif
    </div>
</div>