Prose

# Brok UI: Prose (`prose`)

A readable long-form content primitive with bounded line length and resilient wrapping for long words and URLs.

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

## Install

```bash
php artisan ui:add prose
```

## Usage

```blade
<x-ui.prose>
    <h3 class="text-xl font-semibold">{{ __('Readable by default') }}</h3>
    <p class="mt-3 text-muted-foreground">{{ __('Long-form content stays within a comfortable measure and wraps resiliently, including unusuallylongunbrokencontentthatwouldotherwiseoverflowitscontainer.example.') }}</p>
</x-ui.prose>
```

## Props

- `size` (md|sm|lg, default `md`) — Reading measure and base text size: sm (narrower, smaller text), md (default prose width), or lg (wider, larger text).
- `centered` (bool, default `true`) — Centers the bounded-width block horizontally within its parent.
- `as` (string, default `article`) — HTML tag to render: article, div, section, or main.
- `variant` (default|rich, default `default`) — default styles only plain lists in descendant HTML; rich also styles bare descendant headings (h1-h4), paragraphs, task lists, links, inline code, scrollable code blocks, blockquotes, tables, rules and images for rendered Markdown or saved editor HTML.

## Use when

- Use to structure hierarchy, spacing, and responsiveness so content is easier to scan and navigate.
- Rendering long-form text content, such as an article, changelog entry, or rich description, at a readable measure.
- Needing long words and URLs to wrap instead of overflowing their container.

## Avoid when

- Do not let layout primitives substitute for semantics, headings, or interaction rules users still need.
- Laying out short UI copy like labels or button text; prose's bounded width and relaxed leading are for reading passages.
- The content is a structured layout of components rather than flowing text; use stack or grid.

## Anti-patterns

- Using visual layout as a substitute for semantic structure

## Rules

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

@props([
    'size' => 'md',
    'centered' => true,
    'as' => 'article',
    'variant' => 'default',
])

@php
    $styles = require base_path(config('ui.component_path', 'resources/views/components/ui').'/_styles.php');
    $variant = $styles['normalizeVariant']($variant);
    $isRich = $variant === 'rich';
    $allowedTags = ['article', 'div', 'section', 'main'];
    $tag = in_array($as, $allowedTags, true) ? $as : 'article';
    $sizes = [
        'sm' => 'max-w-xl text-sm',
        'md' => 'max-w-prose text-base',
        'lg' => 'max-w-3xl text-lg',
    ];
    $sizeKey = array_key_exists($size, $sizes) ? $size : 'md';

    // List styles for rich text (editor or Markdown HTML) that has no classes
    // of its own. Every rule is wrapped in :where(), so it has no specificity:
    // a class on the list or item (`list-none`, `ps-0`) still wins. Nesting is
    // matched by depth without overlap (the rules never compete, so their
    // order in the stylesheet does not matter): disc, circle, then square
    // bullets; decimal, then lower-alpha numbers. A top-level list gets space
    // from its siblings only, so a list at the start or end adds no gap.
    // variant="rich" skips these and $blocks: it styles every element in
    // ui.css instead.
    $lists = implode(' ', [
        '[:where(&_ul:not(&_li_ul))]:list-disc',
        '[:where(&_li_ul:not(&_li_li_ul))]:list-[circle]',
        '[:where(&_li_li_ul)]:list-[square]',
        '[:where(&_ol:not(&_li_ol))]:list-decimal',
        '[:where(&_li_ol)]:list-[lower-alpha]',
        '[:where(&_:is(ul,ol))]:ps-6',
        '[:where(&_:is(ul,ol):not(&_li_:is(ul,ol)):not(:first-child))]:mt-4',
        '[:where(&_:is(ul,ol):not(&_li_:is(ul,ol)):not(:last-child))]:mb-4',
        '[:where(&_li_:is(ul,ol))]:my-1',
        '[:where(&_li)]:ps-1',
        '[:where(&_li+li)]:mt-1',
        '[:where(&_li>p)]:my-0',
        'marker:text-muted-foreground',
    ]);

    // Block styles for the rest of rich text, with the same zero specificity:
    // headings sized in em from the prose size, paragraph rhythm, links (an
    // editor mention keeps its chip), inline code and code blocks on the
    // muted surface, a quiet blockquote, and tables with hairline rows that
    // scroll sideways when wide. Neutral tokens only, so dark mode follows.
    $blocks = implode(' ', [
        '[:where(&_h1)]:text-[1.5em]',
        '[:where(&_h2)]:text-[1.25em]',
        '[:where(&_h3)]:text-[1.125em]',
        '[:where(&_h4)]:text-[1em]',
        '[:where(&_:is(h1,h2,h3,h4))]:font-semibold',
        '[:where(&_:is(h1,h2))]:tracking-tight',
        '[:where(&_:is(h1,h2,h3,h4))]:leading-snug',
        '[:where(&_:is(h1,h2,h3,h4))]:text-foreground',
        '[:where(&_:is(h1,h2):not(:first-child))]:mt-8',
        '[:where(&_:is(h3,h4):not(:first-child))]:mt-6',
        '[:where(&_:is(h1,h2,h3,h4))]:mb-2',
        '[:where(&_p:not(&_li_p):not(:first-child))]:mt-3',
        '[:where(&_p:not(&_li_p):not(:last-child))]:mb-3',
        '[:where(&_:is(blockquote,pre,table):not(:first-child))]:mt-4',
        '[:where(&_:is(blockquote,pre,table):not(:last-child))]:mb-4',
        '[:where(&_a:not([data-type=mention]))]:text-link',
        '[:where(&_a:not([data-type=mention]))]:underline',
        '[:where(&_a:not([data-type=mention]))]:underline-offset-2',
        '[:where(&_:is(strong,b))]:font-semibold',
        '[:where(&_:not(pre)>code)]:rounded-sm',
        '[:where(&_:not(pre)>code)]:bg-muted',
        '[:where(&_:not(pre)>code)]:px-1',
        '[:where(&_:not(pre)>code)]:py-0.5',
        '[:where(&_:not(pre)>code)]:font-mono',
        '[:where(&_:not(pre)>code)]:text-[0.875em]',
        '[:where(&_pre)]:overflow-x-auto',
        '[:where(&_pre)]:rounded-md',
        '[:where(&_pre)]:border',
        '[:where(&_pre)]:border-border',
        '[:where(&_pre)]:bg-muted',
        '[:where(&_pre)]:px-4',
        '[:where(&_pre)]:py-3',
        '[:where(&_pre)]:font-mono',
        '[:where(&_pre)]:text-[0.875em]',
        '[:where(&_pre)]:leading-relaxed',
        '[:where(&_pre)]:text-foreground',
        '[:where(&_pre_code)]:bg-transparent',
        '[:where(&_pre_code)]:p-0',
        '[:where(&_blockquote)]:border-s-2',
        '[:where(&_blockquote)]:border-border',
        '[:where(&_blockquote)]:ps-4',
        '[:where(&_blockquote)]:text-muted-foreground',
        '[:where(&_table)]:block',
        '[:where(&_table)]:max-w-full',
        '[:where(&_table)]:overflow-x-auto',
        '[:where(&_table)]:border-collapse',
        '[:where(&_table)]:text-[0.9375em]',
        '[:where(&_th)]:text-start',
        '[:where(&_th)]:align-bottom',
        '[:where(&_th)]:font-medium',
        '[:where(&_:is(th,td))]:border-b',
        '[:where(&_:is(th,td))]:border-border',
        '[:where(&_:is(th,td))]:py-2',
        '[:where(&_:is(th,td))]:pe-4',
        '[:where(&_td)]:align-top',
        '[:where(&_hr)]:my-6',
        '[:where(&_hr)]:border-border',
        '[:where(&_img)]:h-auto',
        '[:where(&_img)]:max-w-full',
    ]);
@endphp

<{{ $tag }}
    data-slot="prose"
    data-size="{{ $sizeKey }}"
    @if ($isRich) data-variant="rich" @endif
    data-ui-text
    {{ $attributes->merge(['class' => trim('w-full min-w-0 break-words text-pretty leading-relaxed text-foreground '.$sizes[$sizeKey].' '.($isRich ? '' : $lists.' '.$blocks).' '.($centered ? 'mx-auto' : ''))]) }}
>{{ $slot }}</{{ $tag }}>