Long-form Article

<x-wirekit::reading-shell :previewMode="true" bookmarkKey="long-form-article-demo">
    <x-wirekit::prose>
        <header style="margin-bottom: 2rem;">
            <h1>The Long Title — Why composition beats configuration</h1>
            <x-wirekit::text variant="muted" as="p">By Author Name · Published 2026-04-30</x-wirekit::text>
            <x-wirekit::reading-meta :showRemaining="true" />
        </header>
        <article>
            <h2 id="lfa-intro">Introduction</h2>
            <p>Open with a strong hook. The reading-progress bar at the top of this iframe gives the reader an immediate sense of "how much is left" — the same pattern Medium and Substack use on every modern blog. Scroll this preview to watch the bar fill, the right-side spine track active sections, and the bookmark prompt arm itself for a return visit.</p>
            <p>The four primitives — progress bar, sidebar spine, bookmark prompt, time-to-read meta — compose into the canonical long-form layout. Each owns its own state; none of them communicate with the others. That keeps the composition robust to per-component overrides without tangling concerns.</p>
            <p>What you're reading right now is rendered inside an isolated iframe so the spine on the right scopes its TOC to this article only — not to the surrounding docs page. Try hovering or focusing the right edge to expand the spine and see the section labels. Click any tick to smooth-scroll to that heading.</p>
            <h2 id="lfa-context">Context</h2>
            <p>Build the case. The right-side reading-spine ticks each section with a tiny dash. h3 ticks render narrower than h2 ticks — visual depth at minified scale. Hover the spine to expand it into a fully-labeled vertical TOC; the active section is highlighted as you scroll.</p>
            <p>The spine uses an IntersectionObserver to detect which heading is currently in the viewport. When the active heading changes, the spine dispatches a <code>wirekit:reading-spine:section-changed</code> event you can listen to from your own Alpine or Livewire components — useful for syncing a deep-link or analytics ping without hand-coding the scroll math.</p>
            <p>The progress bar is a separate primitive but shares no state with the spine. It computes its own scroll percentage on every <code>scroll</code> event (rAF-throttled) and fills the bar from 0% to 100% as the reader works through the article. By default it sits 3px tall, pinned to the very top of the viewport.</p>
            <h3 id="lfa-context-history">Some Background</h3>
            <p>The reading-shell sugar wrapper composes all four primitives in a single tag. Density presets (<code>comfortable</code>, <code>compact</code>, <code>minimal</code>) flip per-primitive defaults; explicit toggles always win over the density baseline. The shell is the 80%-case sugar — power users who need finer control compose the primitives directly without the shell.</p>
            <p>You can mix shell-level density with per-primitive overrides. For example, <code>density="minimal" :spine="true"</code> shows the spine even though minimal-density would normally hide it. The override always wins; density is just a starting-point shape, not a lockout.</p>
            <h2 id="lfa-argument">The Argument</h2>
            <p>Make the point. The active section indicator slides smoothly between ticks as the reader scrolls. <code>prefers-reduced-motion: reduce</code> is honored end-to-end — every transition collapses to 0.01ms via a global media query, so motion-sensitive readers never see a slide animation.</p>
            <p>The smooth-scroll math accounts for the viewport-top offset (default 96px) so the destination heading lands just below the progress bar, not flush against it. Pass <code>offset="6rem"</code> on individual primitives or via the shell to change the value without overriding the visual positioning.</p>
            <p>Click any spine link to smooth-scroll to that heading. The URL hash updates via <code>history.replaceState()</code> rather than <code>pushState()</code> — back-button still goes to the previous page, not to the previous heading. Saves the user from a 12-press back-button repro to escape the article.</p>
            <h2 id="lfa-evidence">Evidence</h2>
            <p>Back up the argument. The bookmark saves scroll position to <code>localStorage</code> every second. On a return visit, after the reader has dwelled at least 30 seconds, a "Resume reading?" pill appears bottom-right with the saved offset. Click it to smooth-scroll back to where they left off.</p>
            <p>The bookmark key is developer-supplied — pass <code>bookmarkKey="post-@{{ $post->slug }}"</code> so each article has its own saved position. The dwell threshold (default 30s) and the storage interval (default 1s) are both tunable. Set <code>:minDwellSeconds="120"</code> for a stricter "only show on serious readers" trigger.</p>
            <p>If the reader has never visited before, no pill renders — bookmark only appears for return visits with non-zero saved offset. No noisy "Welcome back" prompts on first read.</p>
            <h2 id="lfa-conclusion">Conclusion</h2>
            <p>Wrap it up. Click any spine link to smooth-scroll to that heading; the URL hash updates without a full anchor jump. The four primitives compose into the canonical long-form layout — drop the shell wrapper, pass a bookmark key, and the rest is opinionated defaults. When you need finer control, decompose into the primitives directly: the shell covers the common case, and dropping to primitives covers everything else.</p>
            <p>The right time to reach for primitive composition is when you need a per-primitive prop the shell doesn't expose — a custom progress color, numbered spine ticks, a different bookmark dwell threshold. Otherwise, ship the shell.</p>
        </article>
    </x-wirekit::prose>
</x-wirekit::reading-shell>

<x-wirekit::reading-progress />
<x-wirekit::reading-spine />
<x-wirekit::reading-bookmark :previewMode="true" key="lfa-manual-demo" />
<x-wirekit::prose>
    <header style="margin-bottom: 2rem;">
        <h1>Article Title — Manual primitive composition</h1>
        <x-wirekit::reading-meta :showRemaining="true" />
    </header>
    <article>
        <h2 id="lfa-m-1">Section A</h2>
        <p>Same UX as the shell wrapper, with full per-component control. Each of the four primitives — progress, spine, bookmark, meta — sits as a sibling of the article body. The shell is sugar over this exact composition; once you need a prop the shell doesn't pass through, drop the shell and mount the primitives directly.</p>
        <p>This decomposed form is also the right shape when the article body lives inside a custom layout that the shell's div wrapper would interfere with — a flex/grid container, a Livewire component boundary, or a fully-custom typographic shell.</p>
        <h2 id="lfa-m-2">Section B</h2>
        <p>Useful when the article body sits inside a custom layout. The reading-spine still pins to the right viewport edge via <code>position: fixed</code>; the reading-progress still pins to the top. They don't care where they live in the DOM tree — they care about the page-level scroll context.</p>
        <p>That said, both components scope their heading-collection to the nearest matching ancestor (<code>main</code>, <code>article</code>) of their own DOM position. So if you place them inside one specific article, they pick up that article's headings rather than something elsewhere on the page.</p>
        <h2 id="lfa-m-3">Section C</h2>
        <p>The bookmark primitive carries its own <code>x-data</code> Alpine state and saves the scroll offset to <code>localStorage</code> under the developer-supplied <code>key</code>. <code>:previewMode="true"</code> is set here so the bookmark won't actually persist between iframe reloads — useful for documentation but never for production.</p>
        <p>Time-to-read estimation runs once on mount: it counts visible words inside the nearest <code>&lt;article&gt;</code>, divides by the configured words-per-minute (default 200), and renders the result. <code>:showRemaining="true"</code> updates the displayed value as the reader scrolls — the meta becomes a live "x minutes remaining" rather than a static "y minutes" estimate.</p>
        <h2 id="lfa-m-4">Section D</h2>
        <p>The decomposed form is approximately 5% of developers; the shell is the right answer for the other 95%. Reach for the manual form when you need a prop, slot, or layout that the shell doesn't accommodate. Otherwise the shell's defaults are the canonical pattern.</p>
        <p>One subtle benefit of manual composition: you can interleave OTHER WireKit components between the primitives — a banner above the progress bar, a sidebar nav alongside the spine, a comments section that the bookmark prompt politely sits above. The shell renders everything as direct children of one wrapper, which constrains layout flexibility.</p>
    </article>
</x-wirekit::prose>

{{-- Comfortable (default) — full chrome --}}
<x-wirekit::reading-shell bookmarkKey="post-{{ $post->slug }}">
    <article>...</article>
</x-wirekit::reading-shell>

{{-- Compact — denser display, spine always-visible at md+ --}}
<x-wirekit::reading-shell bookmarkKey="post-{{ $post->slug }}" density="compact">
    <article>...</article>
</x-wirekit::reading-shell>

{{-- Minimal — progress bar only --}}
<x-wirekit::reading-shell bookmarkKey="post-{{ $post->slug }}" density="minimal">
    <article>...</article>
</x-wirekit::reading-shell>

{{-- Custom: success-colored progress + numbered spine + tight bookmark + meta --}}
<x-wirekit::reading-progress variant="success" :milestones="true" />
<x-wirekit::reading-spine :levels="'2,3'" :numbered="true" :backToTop="true" />
<x-wirekit::reading-bookmark
    key="post-{{ $post->slug }}"
    :minDwellSeconds="120"
    :threshold="0.05"
/>
<x-wirekit::reading-meta :wpm="200" :showRemaining="true" />

<article>...</article>