Table of Contents

# Brok UI: Table of Contents (`table-of-contents`)

In-page navigation built from a target container's headings (or explicit items), with IntersectionObserver active-highlight, smooth scroll and aria-current.

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

## Install

```bash
php artisan ui:add table-of-contents
```

## Usage

```blade
<div class="grid gap-8 md:grid-cols-[1fr_220px]">
    <article id="toc-demo" class="space-y-4">
        <section>
            <h2 id="getting-started" class="text-xl font-semibold text-foreground">{{ __('Getting started') }}</h2>
            <p class="text-muted-foreground">{{ __('Install the package and register the service provider. Scroll the page to watch the active section update in the navigation beside this content.') }}</p>
        </section>

        <section>
            <h3 id="requirements" class="text-lg font-medium text-foreground">{{ __('Requirements') }}</h3>
            <p class="text-muted-foreground">{{ __('You will need a recent PHP runtime and a compatible Laravel application before continuing with the setup steps.') }}</p>
        </section>

        <section>
            <h2 id="configuration" class="text-xl font-semibold text-foreground">{{ __('Configuration') }}</h2>
            <p class="text-muted-foreground">{{ __('Publish the configuration file and adjust the defaults to match your environment. Each option is documented inline for clarity.') }}</p>
        </section>

        <section>
            <h3 id="environment" class="text-lg font-medium text-foreground">{{ __('Environment variables') }}</h3>
            <p class="text-muted-foreground">{{ __('Sensitive values belong in your environment file rather than committed configuration so they never leak into source control.') }}</p>
        </section>

        <section>
            <h2 id="usage" class="text-xl font-semibold text-foreground">{{ __('Usage') }}</h2>
            <p class="text-muted-foreground">{{ __('Drop the component into any Blade view and it will smooth-scroll to each section while highlighting the heading currently in view.') }}</p>
        </section>
    </article>

    <x-ui.table-of-contents target="#toc-demo" class="md:sticky md:top-4 md:self-start" />
</div>
```

## Props

- `target` (mixed|null, default `null`) — CSS selector for the container whose headings are collected; ignored when items is supplied explicitly.
- `selector` (string, default `h2, h3`) — CSS selector used to find headings inside the target container.
- `items` (array, default `[]`) — Explicit list of { label, href } entries, used instead of deriving items from headings.
- `title` (mixed|null, default `null`) — Heading shown above the list.
- `label` (mixed|null, default `null`) — Accessible label for the navigation landmark when no visible title is shown.
- `variant` (list|rail, default `list`) — Visual layout: list (vertical) or another supported rail style.
- `root` (mixed|null, default `null`) — CSS selector for the IntersectionObserver's scrolling root, when it is not the viewport.
- `offset` (int, default `0`) — Pixel offset applied to the active-section detection, to account for a sticky header.

## Use when

- Use to orient users and help them move across pages, sections, or commands.
- Giving readers a jump list of the current page's headings, with the active section highlighted as they scroll.
- Building a long-form article, docs, or guide page that benefits from an on-this-page rail.

## Avoid when

- Do not hide primary wayfinding in novelty interactions or deep nested structures if straightforward navigation would be clearer.
- The page is short enough to scan without a jump list.
- The list should be a fixed, hand-authored set of links unrelated to the page's own headings; use navigation-menu or sidebar instead.

## Anti-patterns

- Hiding primary wayfinding in novelty interactions

## Rules

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

@props([
    'target' => null,
    'selector' => 'h2, h3',
    'items' => [],
    'title' => null,
    // Accessible name of the <nav>.
    'label' => null,
    // list (default): plain rows, the active one in foreground weight.
    // rail: a hairline down the start edge with the active row marked on it,
    // and a small uppercase title — the "On this page" rail of a docs page.
    'variant' => 'list',
    // The sections' scroll container: null observes the viewport, a selector
    // names the element, 'auto' finds the nearest scrollable ancestor of the
    // first heading (a list inside a scrolling panel).
    'root' => null,
    // Pixels trimmed from the top of the active band, for a fixed header.
    'offset' => 0,
])


@php
    // Accept a string, a backed enum or a Stringable for `variant`.
    $styles = require base_path(config('ui.component_path', 'resources/views/components/ui').'/_styles.php');
    $variant = $styles['normalizeVariant']($variant);
@endphp
{{--
    Table of Contents (spec §16B).
    A navigation list of in-page headings. Headings are either scanned from the
    `target` container at runtime or passed explicitly via `:items`. Explicit
    items are rendered on the server, so the links exist (and deep links resolve)
    before Alpine boots; scanned items render client-side. An item may carry a
    `meta` string (a date, a count) shown after its label. The active section is
    tracked with an IntersectionObserver (the last section wins once the page is
    scrolled to its end) and reflected with `aria-current="location"`; links
    smooth-scroll (motion-reduce safe), update the URL hash and hand focus to
    the heading so the next Tab continues into the section.
--}}
@php
    $variant = in_array($variant, ['list', 'rail'], true) ? $variant : 'list';
    $rail = $variant === 'rail';
    $indent = $rail
        ? static fn (int $level): string => $level <= 2 ? 'ps-3' : ($level === 3 ? 'ps-6' : 'ps-9')
        : static fn (int $level): string => $level <= 2 ? 'ps-0' : ($level === 3 ? 'ps-4' : 'ps-8');
    $indentBinding = $rail
        ? "{ 'ps-3': item.level <= 2, 'ps-6': item.level === 3, 'ps-9': item.level >= 4 }"
        : "{ 'ps-0': item.level <= 2, 'ps-4': item.level === 3, 'ps-8': item.level >= 4 }";
    $ring = 'focus-visible:outline-none focus-visible:ring-[length:var(--ring-width)] focus-visible:ring-ring focus-visible:ring-offset-[length:var(--ring-offset-width)] focus-visible:ring-offset-background';
    $linkClass = $rail
        ? '-ms-px flex items-baseline justify-between gap-2 border-s border-transparent py-1 pe-2 text-sm transition-colors hover:border-foreground/40 hover:text-foreground motion-reduce:transition-none '.$ring
        : 'flex items-baseline justify-between gap-2 py-1 text-sm transition-colors hover:text-foreground motion-reduce:transition-none '.$ring;
    $activeClass = $rail ? 'border-foreground font-medium text-foreground' : 'font-medium text-foreground';
    $idleClass = $rail ? 'border-transparent text-muted-foreground' : 'text-muted-foreground';
    $titleClass = $rail
        ? 'mb-2 px-3 text-2xs font-semibold uppercase tracking-wider text-muted-foreground'
        : 'mb-2 text-sm font-medium text-foreground';
    $listClass = $rail ? 'space-y-0.5 border-s border-border' : 'space-y-1';
    // scroll-spy renders this component under its own name; the browser
    // keeps only the first of two identical attributes, so read the override
    // out of the bag and print exactly one.
    $slotName = (string) ($attributes->get('data-slot') ?: 'table-of-contents');
@endphp
<nav
    data-slot="{{ $slotName }}"
    data-variant="{{ $variant }}"
    aria-label="{{ $label ?? __('Table of contents') }}"
    x-data="uiTableOfContents({ target: @js($target), selector: @js($selector), items: @js($items), root: @js($root), offset: @js((int) $offset) })"
    {{ $attributes->except('data-slot')->merge(['class' => 'text-sm text-muted-foreground']) }}
>
    @if ($title !== false)
        <p data-slot="table-of-contents-title" class="{{ $titleClass }}">
            {{ $title ?? __('On this page') }}
        </p>
    @endif

    <ol data-slot="table-of-contents-list" class="{{ $listClass }}">
        @if ($items !== [])
            @foreach ($items as $item)
                <li data-slot="table-of-contents-item" @if (! $rail) class="{{ $indent((int) ($item['level'] ?? 2)) }}" @endif>
                    <a
                        href="#{{ $item['id'] }}"
                        @click.prevent="scrollTo(@js($item['id']))"
                        :aria-current="active === @js($item['id']) ? 'location' : null"
                        :class="active === @js($item['id']) ? @js($activeClass) : @js($idleClass)"
                        class="{{ $linkClass }} {{ $rail ? $indent((int) ($item['level'] ?? 2)) : '' }}"
                    >
                        <span class="min-w-0 truncate">{{ $item['label'] }}</span>
                        @if (! empty($item['meta']))
                            <span class="shrink-0 font-mono text-xs">{{ $item['meta'] }}</span>
                        @endif
                    </a>
                </li>
            @endforeach
        @else
            <template x-for="item in items" :key="item.id">
                <li data-slot="table-of-contents-item" @if (! $rail) :class="{{ $indentBinding }}" @endif>
                    <a
                        :href="'#' + item.id"
                        @click.prevent="scrollTo(item.id)"
                        :aria-current="active === item.id ? 'location' : null"
                        :class="[active === item.id ? @js($activeClass) : @js($idleClass), {{ $rail ? $indentBinding : '{}' }}]"
                        class="{{ $linkClass }}"
                    >
                        <span class="min-w-0 truncate" x-text="item.label"></span>
                        <span class="shrink-0 font-mono text-xs" x-show="item.meta" x-text="item.meta"></span>
                    </a>
                </li>
            </template>
        @endif
    </ol>
</nav>

/**
 * Table of Contents behavior (spec §16B).
 *
 * Builds a navigation list from the headings inside a `target` container (or
 * the whole document) matching `selector`, unless an explicit `items` array is
 * supplied. Each scanned heading is given a stable id (slugified from its text)
 * when it lacks one. An IntersectionObserver highlights the topmost heading in
 * view as `active`. The observer runs against the viewport by default; `root`
 * names the sections' scroll container instead (a selector, or 'auto' for the
 * nearest scrollable ancestor of the first heading) so a list inside a
 * scrolling panel tracks that panel, and `offset` (px) trims the top of the
 * active band for a fixed header. The end of the scroll area marks the last
 * heading (a short last section never reaches the band). `scrollTo`
 * smooth-scrolls to a section, honoring prefers-reduced-motion. Listeners are
 * torn down on destroy.
 */
document.addEventListener('alpine:init', () => {
    window.Alpine.data('uiTableOfContents', (config = {}) => ({
        items: config.items ?? [],
        active: null,
        target: config.target ?? null,
        selector: config.selector ?? 'h2, h3',
        root: config.root ?? null,
        offset: config.offset ?? 0,
        _observer: null,
        _headings: [],
        _scroller: null,
        _onScroll: null,

        init() {
            const root = this.target ? document.querySelector(this.target) : document;

            if (!root) {
                return;
            }

            // Seed items from the DOM only when none were provided explicitly.
            if (!this.items.length) {
                const headings = Array.from(root.querySelectorAll(this.selector));

                this.items = headings.map((el) => {
                    if (!el.id) {
                        // Disambiguate duplicate headings: append -2, -3, … so
                        // getElementById later resolves the right one, not the first.
                        const base = this.slugify(el.textContent || '');
                        let id = base;
                        let n = 2;
                        while (document.getElementById(id)) {
                            id = `${base}-${n++}`;
                        }
                        el.id = id;
                    }

                    return {
                        id: el.id,
                        label: (el.textContent || '').trim(),
                        level: Number(el.tagName.replace(/\D/g, '')) || 2,
                    };
                });
            }

            // Resolve the heading elements we will observe (works for both
            // scanned and explicit items, as long as the ids exist in the DOM).
            this._headings = this.items
                .map((item) => document.getElementById(item.id))
                .filter(Boolean);

            if (!this._headings.length) {
                return;
            }

            const rootEl = this.resolveRoot(this._headings[0]);

            this._observer = new IntersectionObserver(
                (entries) => {
                    const visible = entries
                        .filter((entry) => entry.isIntersecting)
                        .sort((a, b) => a.boundingClientRect.top - b.boundingClientRect.top);

                    if (visible.length) {
                        this.active = visible[0].target.id;
                    }
                },
                { root: rootEl, rootMargin: `-${this.offset}px 0px -70% 0px`, threshold: 0 }
            );

            this._headings.forEach((el) => this._observer.observe(el));

            // A short last section never reaches the observer's top band, so the
            // end of the scroll area marks the last heading instead.
            this._scroller = rootEl ?? window;
            this._onScroll = () => {
                const el = rootEl ?? document.documentElement;
                const top = rootEl ? rootEl.scrollTop : window.scrollY;
                const height = rootEl ? rootEl.clientHeight : window.innerHeight;
                if (top + height >= el.scrollHeight - 2) {
                    this.active = this._headings[this._headings.length - 1].id;
                }
            };
            this._scroller.addEventListener('scroll', this._onScroll, { passive: true });

            // Default to the hash, else the first heading, until the observer reports.
            const hash = decodeURIComponent(location.hash.slice(1));
            if (this.active === null && this.items.length) {
                this.active = this.items.some((item) => item.id === hash) ? hash : this.items[0].id;
            }
        },

        /**
         * The observer's root: null for the viewport (default), the element a
         * selector names, or — for 'auto' — the nearest ancestor of the first
         * heading that scrolls vertically. Judged by overflow alone: the
         * component may initialise while its stage is still hidden (a docs
         * tab, a collapsed panel), when scrollHeight and clientHeight are 0.
         */
        resolveRoot(first) {
            if (!this.root) {
                return null;
            }
            if (this.root !== 'auto') {
                return document.querySelector(this.root);
            }
            for (let node = first?.parentElement; node && node !== document.body; node = node.parentElement) {
                const { overflowY } = getComputedStyle(node);
                if (overflowY === 'auto' || overflowY === 'scroll') {
                    return node;
                }
            }
            return null;
        },

        scrollTo(id) {
            const el = document.getElementById(id);

            if (!el) {
                return;
            }

            // A CSS `scroll-behavior: auto` under reduced motion does not override
            // a JS scrollIntoView({ behavior: 'smooth' }) argument.
            const reduce = window.matchMedia('(prefers-reduced-motion: reduce)').matches;
            el.scrollIntoView({ behavior: reduce ? 'auto' : 'smooth', block: 'start' });
            this.active = id;
            history.replaceState(null, '', `#${id}`);
            // The prevented click cancelled the browser's focus move too: put focus
            // on the heading so the next Tab continues into the section.
            if (!el.hasAttribute('tabindex')) el.setAttribute('tabindex', '-1');
            el.focus({ preventScroll: true });
        },

        slugify(text) {
            return text
                .toString()
                .trim()
                .toLowerCase()
                .replace(/[^\w\s-]/g, '')
                .replace(/[\s_]+/g, '-')
                .replace(/-+/g, '-')
                .replace(/^-+|-+$/g, '');
        },

        destroy() {
            if (this._observer) {
                this._observer.disconnect();
                this._observer = null;
            }
            if (this._scroller && this._onScroll) {
                this._scroller.removeEventListener('scroll', this._onScroll);
                this._onScroll = null;
                this._scroller = null;
            }
        },
    }));
});