Reading

{{-- The CSS variable on the shell wrapper cascades to the inner spine so
     it renders narrow enough to fit alongside the article in this iframe;
     the article below reserves matching padding-right. --}}
<x-wirekit::reading-shell :previewMode="true" bookmarkKey="reading-quick-start-demo" style="--reading-spine-width-expanded: 10rem;">
    <x-wirekit::prose>
        <article class="wk-reading-content" style="padding: 1rem; --reading-content-spine-gutter: 11rem;">
            <h2 id="r-quickstart-intro">Introduction</h2>
            <p>The shell renders a progress bar, a sidebar TOC, and a bookmark prompt with sensible defaults — drop your article body inside, pass a bookmark key, and the rest is opinionated defaults. The progress bar pins to the very top of this iframe; the spine sits at the right edge; the bookmark arms itself once you've dwelled long enough.</p>
            <p>Scroll this preview to see all three primitives respond. The bar fills, the spine highlights the active heading, and after 30 seconds of dwell, the bookmark prompt appears bottom-right (only on a return visit — first visit shows nothing).</p>
            <p>The shell wrapper is the 80% case: pass a bookmark key, accept the comfortable density default. For finer control, decompose into primitives and mount each one directly.</p>
            <h2 id="r-quickstart-body">Body</h2>
            <p>Each primitive in the family carries its own Alpine state; nothing communicates between them. That makes the composition robust to changes in any one of them — opt out per-toggle (<code>:spine="false"</code>) or pick a density preset (<code>density="compact"</code>) without breaking the others.</p>
            <p>The four primitives the shell composes by default: reading-progress (the bar), reading-spine (the sidebar TOC), reading-bookmark (the dwell-triggered prompt), reading-meta (time-to-read estimate, off by default). The minimap and TOC primitives are toggleable but disabled in the comfortable density preset — opt in via <code>:minimap="true"</code> / <code>:toc="true"</code>.</p>
            <p>The density preset (<code>comfortable</code>, <code>compact</code>, <code>minimal</code>) flips per-primitive defaults. <code>compact</code> uses a thinner progress bar and forces the spine to always-md expanded. <code>minimal</code> shows only the progress bar.</p>
            <h2 id="r-quickstart-end">Conclusion</h2>
            <p>For per-primitive customization beyond what toggles + density cover, compose primitives directly. The shell covers the common case; dropping to primitives covers the rest, with no "shell-with-overrides" half-step in between.</p>
            <p>The shell's div wrapper is the only structural element it adds. If your layout needs the article body to live inside a flex/grid container or a Livewire boundary, the shell's wrapper might interfere — that's the canonical signal to drop the shell and mount primitives directly.</p>
            <p>Click any spine link to smooth-scroll to that heading. Click anywhere else to return reading. The bookmark saves your offset every second; on a real return visit (after 30s+ dwell time), it'll prompt you to resume.</p>
        </article>
    </x-wirekit::prose>
</x-wirekit::reading-shell>

<x-wirekit::reading-progress />
<x-wirekit::prose>
    <article style="padding: 1rem;">
        <h2>Watch the bar fill as the page scrolls</h2>
        <p>The reading-progress bar pins to the very top of the iframe (its <code>position: fixed</code> anchors to the iframe's viewport, not the outer page). Scroll inside this preview frame — the bar's fill grows from 0% to 100% as the scroll position moves from 0 to the bottom.</p>
        <p>The fill animation uses <code>transform: scaleX</code> — a compositor-only property, so the bar fills smoothly even on low-powered devices without triggering layout or paint. Under <code>prefers-reduced-motion: reduce</code> the transition collapses to 1ms; the value still updates on scroll, only the interpolation is removed.</p>
        <p>Default height is 3px (<code>height="md"</code>). Pass <code>height="sm"</code> for a 2px hairline or <code>height="lg"</code> for a 5px chunky bar. The color is the accent token by default; pass <code>intent="success"</code> / <code>intent="warning"</code> / <code>intent="danger"</code> for semantic states.</p>
        <p>The bar starts hidden until the reader has scrolled past <code>showAfter</code> pixels (default 0). Set a higher value (e.g. <code>:showAfter="100"</code>) if you want the bar to appear only after the reader has committed to reading past the article header.</p>
        <p>Pass <code>:milestones="true"</code> to fire <code>wirekit:reading-progress:milestone</code> events at 25%, 50%, 75%, and 100%. Useful for analytics or for triggering a "you're halfway through" prompt where it makes sense.</p>
        <p>The progress bar lives in its own DOM node and never interferes with the document flow — even when nested inside other components, it takes itself out of layout via <code>position: fixed</code> the moment it mounts.</p>
        <p>If your page has a fixed header above the article, set <code>position="bottom"</code> to pin the bar to the viewport bottom instead. Both positions share the same Alpine state machine; only the rendered DOM differs.</p>
        <p>For embedded contexts like browser extensions or iframes-within-iframes where the bar should match surrounding text color, pass <code>intent="auto"</code>. The fill resolves to <code>currentColor</code>, so the bar inherits whatever color the surrounding context provides.</p>
        <p>Keep scrolling — the more text you scroll past, the more visible the bar's fill becomes. By the end of this preview block the bar should be at or near 100%.</p>
        <p>The progress bar is the lightest of the reading-* primitives — pure CSS plus a single rAF-throttled scroll listener. No IntersectionObserver, no localStorage, no DOM scanning of headings.</p>
    </article>
</x-wirekit::prose>

<x-wirekit::reading-progress indicator="dot" />
<x-wirekit::prose>
    <article style="padding: 1rem;">
        <h2>Watch the dot fill as the page scrolls</h2>
        <p>Scroll inside this preview frame and the dot's stroke fills clockwise as the scroll position progresses from 0 to the bottom. Same Alpine state machine as the bar variant; only the rendered DOM differs. The dot pins to the bottom-right of the iframe via <code>position: fixed</code> and renders as a circular SVG with a stroke that fills as the reader progresses.</p>
        <p>The fill animation uses <code>stroke-dasharray</code> on the SVG circle — also a compositor-only property, GPU-accelerated. The dot doesn't take itself out of layout (it sits in its own fixed-position container), so it never interferes with the article flow below.</p>
        <p>Use the dot variant when a horizontal bar would interfere with your layout — for example, if you already have a fixed top nav or a persistent CTA at the top. The dot is also less visually heavy than the bar; some product surfaces want the indicator to be discoverable but not prominent.</p>
        <p>Hover the dot to see the percentage tooltip (the percentage is also exposed via the dot's <code>aria-label</code> for screen readers). On touch, the tooltip is suppressed; the percentage is still available via assistive tech.</p>
        <p>Pass <code>position="bottom-left"</code> / <code>position="top-left"</code> / <code>position="top-right"</code> to relocate the dot. The default <code>bottom-right</code> follows the convention every messaging app and chat surface uses for "your status indicator".</p>
        <p>The dot variant carries the same <code>intent</code> prop as the bar (<code>primary</code>, <code>neutral</code>, <code>success</code>, <code>warning</code>, <code>danger</code>, <code>info</code>, <code>auto</code>) — the color token threading is identical.</p>
        <p>Both indicators (bar and dot) ship a <code>@media print { display: none !important }</code> rule via the <code>.wk-reading-progress</code> marker class. Print-friendly; the article body prints clean without progress chrome on every page.</p>
        <p>If you need both indicators simultaneously (a bar for "where am I" plus a dot for ambient feedback), mount two <code>&lt;x-wirekit::reading-progress&gt;</code> tags side by side. Both share scroll state via the same plugin; neither knows about the other.</p>
        <p>Keep scrolling to see the dot fill. The stroke completes as the reader hits the bottom of the article.</p>
    </article>
</x-wirekit::prose>

{{-- The CSS-variable override narrows the expanded spine width so it fits
     the iframe gutter; the article below reserves matching padding-right. --}}
<x-wirekit::reading-spine style="--reading-spine-width-expanded: 10rem;" />
<x-wirekit::prose>
    {{-- .wk-reading-content reserves a responsive inline-end gutter for the
         fixed-position spine — full width below md (spine hidden), an 11rem
         gutter at md+ (matching this preview's 10rem expanded spine + 1rem
         offset via the --reading-content-spine-gutter override). --}}
    <article class="wk-reading-content" style="padding: 1rem; --reading-spine-width-expanded: 10rem; --reading-content-spine-gutter: 11rem;">
        <h2 id="rs-default-overview">Overview</h2>
        <p>The reading-spine is a fixed-position sidebar TOC at the right edge of the iframe. It auto-builds from the headings inside the nearest <code>&lt;article&gt;</code> or <code>&lt;main&gt;</code> ancestor, renders one tick per heading, and tracks the active section as you scroll.</p>
        <p>Hover or focus the spine to expand the labels — collapsed it's just a thin column of ticks; expanded it shows full heading text. The expand-on-hover keeps horizontal space minimal until the reader actually wants to navigate.</p>
        <h3 id="rs-default-ticks">Tick widths</h3>
        <p>Tick width encodes heading level: h2 ticks render wider than h3 ticks, which render wider than h4 ticks. This visual hierarchy survives at minified scale — the reader can tell nesting depth at a glance even before expanding.</p>
        <p>Levels included default to <code>levels="2,3"</code> (h2 + h3). Pass <code>levels="2"</code> for h2-only (flat outline), or <code>levels="2,3,4"</code> for deeper hierarchies. The value is a plain comma-separated list — no inner quotes, which would be read as part of a level and cast to 0. Six levels (h1-h6) are valid; the plugin filters anything outside that range.</p>
        <h2 id="rs-default-active">Active section detection</h2>
        <p>The active heading is the LAST heading whose top is at or above the offset line (default 96px), measured from the top of whatever scrolls — the page, or the region your shell scrolls in. This handles tall sections cleanly — a section longer than the viewport becomes "active" as the reader scrolls past its first paragraph rather than waiting for the next heading to enter the viewport.</p>
        <p>Every scroll re-evaluates against live <code>getBoundingClientRect()</code>, at most once a frame, to find the currently-active item. A click holds its section until you scroll yourself, so the mark does not walk through every section the jump passes.</p>
        <h3 id="rs-default-scroll">Smooth scroll on click</h3>
        <p>Click any tick → smooth-scroll to that heading. The URL hash updates via <code>history.replaceState()</code>, not <code>pushState()</code> — back-button still goes to the previous page rather than the previous heading. Saves the user from a multi-press back-button repro to escape the article.</p>
        <p>Smooth scrolling is gated by <code>prefers-reduced-motion: reduce</code> — when the OS preference is set, the scroll happens instantly. Same gate applies to the active-state color transitions on the ticks.</p>
        <h2 id="rs-default-events">Section-changed events</h2>
        <p>The spine dispatches <code>wirekit:reading-spine:section-changed</code> with details <code>{ index, id, text, level }</code> when the active heading changes. Listen with <code>x-on:wirekit:reading-spine:section-changed.window</code> to update the browser tab title, fire analytics on section view, or sync state with a deeper component.</p>
        <p>The dispatch is debounced 80ms — rapid scrolling doesn't fire 30 events for transient pass-throughs; only the heading the reader actually paused on triggers a callback.</p>
        <h3 id="rs-default-mobile">Mobile behavior</h3>
        <p>The spine is hidden on viewports under <code>md</code> (768px) by default — hover doesn't exist on touch and the fixed sidebar would crowd a narrow viewport. Pass <code>hideBelow="none"</code> to show the spine even on mobile, useful for the collapsed-tick "I'm in section X" indicator without the expand interaction.</p>
        <p>Filter slot: pass any input as the <code>filter</code> slot, two-way bind via <code>x-model="filter"</code>. Items hide when their text doesn't match (case-insensitive substring). Useful for very long outlines (e.g. API reference pages with 40+ sections).</p>
    </article>
</x-wirekit::prose>

<x-wirekit::grid cols="1" template="md:[minmax(0,1fr)_14.375rem]" gap="lg" style="padding: 1rem;">
    <x-wirekit::prose>
        <article id="rs-rail-article">
            <h2 id="rs-rail-why">Why a rail</h2>
            <p>The line runs through every entry. Where a section steps in, the line bends with it, inside the gap between two titles, so it never crosses one.</p>
            <p>The band on the line marks where you are. It slides to the next section as you scroll, and to the section a click goes to.</p>
            <h3 id="rs-rail-titles">Titles that are longer than the column is wide wrap onto a second line</h3>
            <p>Nothing is cut off with an ellipsis. A wrapped title takes two lines, and its stretch of the line is two lines long.</p>
            <p>The line is measured from the links themselves, so a font that loads late or a column that changes width redraws it.</p>
            <h3 id="rs-rail-sticky">Sticky in its column</h3>
            <p>From the <code>md</code> breakpoint the rail sticks to the top of its column and scrolls on its own when it is taller than the window.</p>
            <p>Below <code>md</code> it is hidden, like the default spine. Pass <code>hide-below="none"</code> to show it there as a disclosure above the article.</p>
            <h2 id="rs-rail-using">Using it</h2>
            <p>Place it in a grid column of its own. It needs no position, edge or boundary, and none of those props applies to it.</p>
            <p>Numbering, the filter slot, back-to-top and the section-changed event work as on the default spine.</p>
            <h3 id="rs-rail-theming">Theming the line</h3>
            <p>Seven tokens name the line's color, the band's color, both widths, the indent per level, the gap before a title and the band's duration.</p>
            <p>A theme that sets the border width to zero keeps both lines: each width has a floor.</p>
            <h2 id="rs-rail-reference">Reference</h2>
            <p>The props table below lists <code>layout</code>, and the token table at the end of the page lists the rail's tokens.</p>
            <p>The band moves in one transition of a clip, so nothing is drawn while it slides, and reduced motion stills it.</p>
        </article>
    </x-wirekit::prose>
    <x-wirekit::reading-spine layout="rail" target="#rs-rail-article" />
</x-wirekit::grid>

<main>
    <x-wirekit::reading-toc flush />
    <article>
        <x-wirekit::prose>
            <section id="rd-hero" style="padding-block: 3rem; padding-inline: var(--padding-wk-x-sm);">
                <h2>Hero</h2>
                <p>Marketing landing page section one — a brief outline of what the page covers. The TOC strip pinned to the top of this iframe is sticky; scroll down and watch the active link follow you as each heading comes up to the strip.</p>
                <p>The strip auto-scans <code>&lt;main&gt;</code> for <code>&lt;h2&gt;</code> elements (default <code>levels="2"</code>) and renders one link per heading. No prop wiring required for the common case — drop the tag inside <code>&lt;main&gt;</code>, the rest is automatic.</p>
                <p>Each link has <code>aria-current="location"</code> when active. The color comes from <code>--reading-toc-color-active</code> (the accent token by default). Idle state uses <code>--reading-toc-color-idle</code> (text-muted by default). Both transition over 150ms unless reduced-motion is set.</p>
            </section>
            <section id="rd-features" style="padding-block: 3rem; padding-inline: var(--padding-wk-x-sm);">
                <h2>Features</h2>
                <p>The bullet-pointed pitch. Each feature gets a paragraph or two, all under the same h2. The active link flips as soon as this heading comes up to the line just below the strip, the same line a jump stands it on.</p>
                <p>Click the "Hero" link in the strip to smooth-scroll back. The smooth-scroll math accounts for the strip's offset so the destination heading lands just below the strip, not under it. URL hash updates via <code>replaceState</code> — back-button still goes to the previous page, not to the previous anchor.</p>
                <p>Per-link max-width truncation defaults to 24ch (<code>--reading-toc-link-max-width</code>). A long heading like "How to manage your team's billing settings" gets truncated to keep the strip from overflowing horizontally on narrow viewports.</p>
            </section>
            <section id="rd-pricing" style="padding-block: 3rem; padding-inline: var(--padding-wk-x-sm);">
                <h2>Pricing</h2>
                <p>Three tiers, each with a card. Anchor links from the TOC strip jump straight to this section. The strip stays visible all the way down the page (it's <code>position: sticky; top: 0</code> by default).</p>
                <p>If your page has a fixed nav above the article, pass <code>offset="4rem"</code> on the strip to push the sticky position down by your nav's height. The same value moves the sticky position, the line a jump stands a heading on, and the line that decides the active section — three concerns, one offset value.</p>
                <p>The list is wrapped in <code>overflow-x-auto</code> so a strip with 6+ items still scrolls cleanly without breaking the page layout. On mobile (under sm by default), the strip is hidden entirely — pass <code>hideBelow="none"</code> to show it on mobile if your design accommodates it.</p>
            </section>
            <section id="rd-faq" style="padding-block: 3rem; padding-inline: var(--padding-wk-x-sm);">
                <h2>FAQ</h2>
                <p>Accordion of common questions. Last anchor in the strip. The strip stays visible here too — the reader can jump back to any earlier section without scrolling all the way up.</p>
                <p>For pages with more than 5-6 anchored sections, switch to the vertical reading-spine instead. The horizontal strip overflows fast at viewport widths under 1024px, even with per-link truncation. The spine's collapsed-tick mode is the right shape for dense vertical TOCs at narrow widths.</p>
                <p>The two primitives (<code>reading-toc</code> and <code>reading-spine</code>) share the same data-collection model — both auto-build from headings via the same Alpine plugin pattern, both track the active section as the page scrolls. Only the rendered shape differs.</p>
            </section>
        </x-wirekit::prose>
    </article>
</main>

<x-wirekit::reading-minimap
    hideBelow="none"
    mode="rendered"
    renderTarget="article"
    width="48px"
    :show-bookmarks="false"
    :auto-fade-idle="false"
/>
<x-wirekit::prose>
    <article style="padding: 1rem 4rem 1rem 1rem;">
        <h2 id="rmr-overview">Rendered mode</h2>
        <p>Scroll inside this preview to see how the minimap paints an abstract content-texture map of the article body. Every paragraph, heading, code block, and image becomes a small colored rectangle on a canvas — the minimap convention of code editors, not a literal scaled-down clone.</p>
        <p>The canvas is painted by walking every text-bearing node in the source via <code>TreeWalker</code>, getting per-rendered-line rects via <code>Range.getClientRects()</code>, and drawing each as a rectangle at minimap scale. Visual elements (img, figure, svg, video, canvas) are drawn in a second pass at their natural bounding box.</p>

        <h3 id="rmr-when">When to choose rendered over stripes</h3>
        <p>Pick rendered-mode when the visual rhythm of the page is part of the navigation cue — long-form articles with figures, code blocks, and varied section lengths. Pick the default stripe mode when raw density (one tick per item) reads clearer.</p>
        <p>For very long articles (over 5 000 source DOM nodes) rendered-mode falls back automatically to stripes — the canvas-build pass is O(text nodes) and the budget keeps the cold-start cost bounded above that threshold.</p>

        <h3 id="rmr-theme">Theme awareness</h3>
        <p>Each element type tints with its own color: h1 through h6 each get a distinct alpha tier (h1 darkest, h6 lightest); <code>pre</code>/<code>code</code> blocks tint indigo; tables tint rose; blockquotes tint slate-bolder; images tint amber; any <code>[class*="wk-"]</code> WireKit component tints emerald; prose and default tint slate-muted.</p>
        <p>All 13 colors override via CSS custom properties on the minimap root (<code>--reading-minimap-color-h1</code> through <code>--reading-minimap-color-default</code>). The component reads each token via <code>getComputedStyle</code> at paint time, so per-theme overrides apply automatically — no JS-side branching needed.</p>

        <h2 id="rmr-perf">Performance characteristics</h2>
        <p>The minimap mounts lazily — the canvas isn't constructed until the wrapper enters the viewport. A <code>MutationObserver</code> on the source target rebuilds the canvas on meaningful content changes, debounced 250 ms.</p>
        <p>Scroll tracking runs at one <code>requestAnimationFrame</code> tick per scroll event — compositor-only transforms, no layout thrash. Reduced-motion users get an instant snap-update instead of the rAF loop.</p>
        <p>Keep scrolling — the more text you scroll past, the further down the minimap your viewport-overlay rectangle moves.</p>
    </article>
</x-wirekit::prose>

<x-wirekit::reading-minimap hideBelow="none" itemSelector="h2, h3, p" />
<x-wirekit::prose>
    <article style="padding: 1rem 5rem 1rem 1rem;">
        <h2 id="rm-overview">Overview</h2>
        <p>Each heading and paragraph in this article is rendered as a 1-2px stripe at the right edge of the iframe — that's the reading-minimap. Scroll inside this preview frame to watch the translucent viewport-overlay rectangle move down the column as the page scrolls.</p>
        <p>The minimap sits at <code>position: fixed</code> against the iframe's viewport, so it stays pinned regardless of where the reader is in the article. Width defaults to 60px; the stripes inside are right-aligned and tinted with the accent token.</p>
        <h3 id="rm-stripes">Stripe density</h3>
        <p>Stripe count equals the number of items the <code>itemSelector</code> picks up — by default <code>'a, h2, h3, [data-minimap-item]'</code>. This preview overrides to <code>'h2, h3, p'</code> so every paragraph renders as its own stripe; on a real article this gives a paragraph-level density overview.</p>
        <p>Stripes thicker than 1px encode heading level (h2 thicker than h3, etc.). Paragraph stripes are 1px hairlines so the visual hierarchy survives at this scale.</p>
        <h2 id="rm-viewport">Viewport overlay</h2>
        <p>The translucent rectangle on top of the stripe column tracks the host's visible region. Its top + height come from <code>scrollY / scrollHeight</code> and <code>clientHeight / scrollHeight</code> respectively, so the rectangle's vertical position + size always represent "where am I, and how much is in view".</p>
        <p>Drag the rectangle to pan the host scroll position proportionally. Click any stripe to smooth-scroll the host so the matching item lands centered in the viewport.</p>
        <h3 id="rm-mobile">Mobile behavior</h3>
        <p>The minimap defaults to <code>hideBelow="lg"</code> (hidden under 1024px viewport) because a stripe column at narrow widths competes with the article body for horizontal space. This preview overrides to <code>"none"</code> so the minimap is visible inside the iframe regardless of width.</p>
        <p>For mobile-friendly density overviews, prefer the reading-spine — its collapsed-tick mode works at narrow widths.</p>
        <h2 id="rm-end">Closing</h2>
        <p>The minimap is the densest of the reading-* primitives, but every primitive in the family follows the same contract: scroll-driven, measured at most once a frame, theme-aware via family-prefixed CSS variables.</p>
        <p>Keep scrolling — the viewport overlay continues to move down as the article ends. By the bottom, the rectangle should sit at the lower portion of the stripe column.</p>
    </article>
</x-wirekit::prose>

<x-wirekit::reading-minimap hideBelow="none" itemSelector="h2, h3, p" itemStyle="block" />
<x-wirekit::prose>
    <article style="padding: 1rem 5rem 1rem 1rem;">
        <h2>Block-style stripes</h2>
        <p>Each item renders as a soft gray rectangle whose height tracks the source paragraph's natural height — the minimap reads as a content-texture rather than a sparse list of lines.</p>
        <p>Use this variant when the article has wildly different section lengths and the per-section visual weight is itself a navigation cue. The classic line-mode stays the default for dense link-lists or sidebars where vertical real estate is tight.</p>
        <h3>Theming</h3>
        <p>Three new tokens drive the block visuals: <code>--reading-minimap-block-bg</code> (background, defaults to a 25%-alpha mix of the idle stripe color), <code>--reading-minimap-block-radius</code> (corner radius, 2px), and <code>--reading-minimap-block-gap</code> (inter-block gap, 2px).</p>
        <p>Override any of them at <code>:root</code> for theme-wide changes. The viewport-overlay rectangle and click-to-scroll mechanics behave the same as the line variant.</p>
        <h2>When it shines</h2>
        <p>Long-form articles where some sections are a single paragraph and others span several screens of content. The block-mode visualization echoes that rhythm so the reader sees the article's pacing at a glance.</p>
        <p>For pure link-lists, marketing landing pages, or any density where every item is roughly the same height, stick with the default line mode — it's more compact and reads cleaner.</p>
        <h3>Scroll to test the active marker</h3>
        <p>Scroll this preview downward. The darker block in the minimap column moves with you — it always represents the section whose heading is currently above the viewport-center line. The Alpine controller picks the active index by walking the items collection on every <code>scroll</code> event (rAF-throttled) and selecting the last item whose absolute top has passed the center.</p>
        <p>This "where am I" cue is the most-used affordance of the minimap. Click any block to jump straight to that section — the smooth-scroll math centers the heading in the viewport. With <code>prefers-reduced-motion: reduce</code> the scroll is instant.</p>
        <p>The active-detection works against any scroll container, not just the window. Pass <code>:target="'.article'"</code> on the minimap and it measures the scroll of the named container instead of the window's. Useful for split-pane layouts where the article body is its own scroll context.</p>
        <h2>Composition with the rest of the family</h2>
        <p>The minimap pairs cleanly with <code>&lt;x-wirekit::reading-progress&gt;</code> at the top of the page and <code>&lt;x-wirekit::reading-spine&gt;</code> on the inboard edge of the article. All three primitives share the same item-collection contract — pass identical <code>itemSelector</code> values and the active marker stays in sync across all three displays.</p>
        <p>Reading-bookmark plays well too: when the developer returns to the article, the saved scroll offset restores; the minimap's active marker syncs to whichever block corresponds to that restored position. No coordination needed between the primitives — they each subscribe to the same scroll source and resolve independently.</p>
        <p>The reading-shell wrapper composes all of them in one tag with sane defaults. Pass <code>:minimap="true"</code> on the shell and the block-mode minimap appears on the right edge with no further wiring.</p>
        <h3>Density tuning</h3>
        <p>Reduce <code>--reading-minimap-block-gap</code> to <code>0</code> for a continuous bar (no inter-block whitespace) — useful when the article has many short paragraphs and the gap noise would dominate the texture. Increase it to <code>4px</code> for a more "card-stack" feel.</p>
        <p>The block-radius token (<code>--reading-minimap-block-radius</code>) accepts any CSS length. A value of <code>9999px</code> turns each block into a pill — works well for sidebars where the minimap doubles as a scroll-handle. Zero gives sharp rectangles for the most "data-density" appearance.</p>
        <p>The background token (<code>--reading-minimap-block-bg</code>) is the only color control specific to block mode. The idle stripe color, active color, and viewport-overlay tokens are shared with line mode — so a theme override carries across the two variants without duplicating.</p>
        <h2>Performance characteristics</h2>
        <p>One DOM node per matched item — the same as line mode. The proportional-height calculation runs once on init (and again on resize via ResizeObserver), so the steady-state cost is identical to line mode. There's no per-frame layout work beyond what the line variant already does.</p>
        <p>For very long articles (1000+ matched items), the block-mode column becomes visually dense to the point of unreadability — the per-item height averages below 1 px and the texture blurs to a solid bar. The minimap auto-falls-back to line mode beyond <code>5000</code> matched items as a hard guard, but developers should manually opt into line mode much earlier (around 100-200 items) for legibility.</p>
        <p>The fallback threshold is configurable via the <code>RENDERED_MAX_TAGS</code> constant in the JS plugin, but the practical advice is: if your article has more than ~200 paragraphs, line mode reads better. Block-mode shines in the 10-100 item range.</p>
        <h3>Where line mode wins instead</h3>
        <p>Sidebar TOCs, link-lists with consistent item height, dashboard widget rows — anything where the per-item visual weight is uniform and irrelevant to navigation. Line mode renders as crisp horizontal hairlines that read like a scrollbar's tick marks.</p>
        <p>Block mode amplifies natural-height variance; line mode collapses it. Pick by content shape: variable paragraph lengths → blocks; uniform list items → lines.</p>
        <h2>Closing</h2>
        <p>Keep scrolling all the way to the bottom — the active marker eventually lands on this very paragraph. By then the viewport-overlay rectangle should sit at the lower end of the minimap column, confirming you've reached the article's end.</p>
    </article>
</x-wirekit::prose>

<style>
.docs-themed-minimap-demo {
    --reading-minimap-color-idle: color-mix(in srgb, #6366f1 25%, transparent);
    --reading-minimap-color-active: #6366f1;
    --reading-minimap-block-bg: color-mix(in srgb, #6366f1 18%, transparent);
    --reading-minimap-block-radius: 4px;
    --reading-minimap-block-gap: 3px;
    --reading-minimap-viewport-bg: color-mix(in oklab, #6366f1 18%, transparent);
    --reading-minimap-viewport-border: 1.5px solid color-mix(in oklab, #6366f1 65%, transparent);
    --reading-minimap-width: 72px;
}
.docs-themed-minimap-demo .wk-reading-minimap {
    border: 1px solid color-mix(in srgb, #6366f1 30%, transparent);
    border-radius: 8px;
    padding: 4px;
    background: color-mix(in srgb, #6366f1 4%, transparent);
}
</style>
<div class="docs-themed-minimap-demo">
<x-wirekit::reading-minimap hideBelow="none" itemSelector="h2, h3, p" itemStyle="block" width="72px" />
<x-wirekit::prose>
    <article style="padding: 1rem 5.5rem 1rem 1rem; overflow-wrap: anywhere;">
        <h2>Custom-themed minimap</h2>
        <p>Token overrides give the minimap an entirely different look without touching the component itself. This preview wraps the minimap in a scope (<code>.docs-themed-minimap-demo</code>) and overrides six tokens: idle/active stripe color, block background, block radius + gap, viewport overlay bg/border. Plus a wrapper border and soft tint on the column itself.</p>
        <p>Scroll inside this preview — the translucent rectangle in the minimap column tracks your visible region. Its top + height come from <code>scrollY / scrollHeight</code> and <code>clientHeight / scrollHeight</code> respectively, so the rectangle's vertical position + size always represent "where am I, and how much is in view". Drag the rectangle to pan the host scroll position proportionally.</p>
        <p>The minimap suppresses the viewport-overlay rectangle entirely when the article fits in the viewport without scrolling — a "you are here" affordance is meaningless when everything is already visible. As soon as the article exceeds the viewport (like this one does), the overlay appears and tracks scroll.</p>
        <h3>Pattern</h3>
        <p>The minimap is fully token-driven. Override colors, spacing, radii, geometry — anything declared in <code>:root</code> can be overridden at any descendant level. The component never hardcodes a color or sizing value; everything flows through CSS variables.</p>
        <p>This makes the minimap easy to brand: pick one or two accent colors from your design system, override the idle / active / overlay tokens, done. The component logic stays untouched.</p>
        <p>Every token has a single declaration source (this preview's <code>&lt;style&gt;</code> block), and the cascade does the rest. No JavaScript-side branching for theming; the component reads the CSS-resolved value at render time.</p>
        <p>The token approach scales to dark-mode automatically: declare a separate set under <code>.dark</code> and the same minimap re-themes when the theme toggle flips. No JS-side reactive subscriptions, no component remount — just CSS cascade resolution.</p>
        <h3>Block-style heights</h3>
        <p>This preview also uses <code>itemStyle="block"</code> — each stripe renders as a soft rectangle whose height tracks the source paragraph's natural height. The minimap reads as a content-texture rather than a sparse list of lines, which works well for articles with wildly different section lengths.</p>
        <p>Three additional tokens drive the block visuals: <code>--reading-minimap-block-bg</code> (background, defaults to a 25%-alpha mix of the idle stripe color), <code>--reading-minimap-block-radius</code> (corner radius, 2px), and <code>--reading-minimap-block-gap</code> (inter-block gap, 2px). Override any of them at <code>:root</code> for theme-wide changes.</p>
        <p>The block height is computed from the source element's natural rendered height, normalized against the article's total scrollHeight. A 200-word paragraph renders as a taller block than a 30-word callout — the minimap mirrors the visual rhythm of the source page.</p>
        <p>For dense link-lists or sidebars where every item is roughly the same height, switch back to <code>itemStyle="line"</code> (the default). The line variant renders cleaner at high density where rhythm doesn't matter, only hierarchy.</p>
        <h2>Composability</h2>
        <p>The same approach scales: drop a different override block for a "danger" article (red accent), a "promo" landing page (gradient overlay), an "archived" notice (muted everything). Each style lives in CSS, not PHP.</p>
        <p>For developers using personalization scopes (Level 3 customization), the same tokens are addressable per scope via <code>WireKit::scope('brand-blue', ['reading-minimap' =&gt; ['classes' =&gt; [...]]])</code>. The scope wrapper acts like a localized theme — anything inside the scope picks up the overrides, anything outside stays on the default token chain.</p>
        <p>This composes cleanly with the four extension props (<code>hoverPreview</code>, <code>showBookmarks</code>, <code>headingAnchors</code>, <code>autoFade</code>): opt in to whichever extensions fit the page, the theme tokens apply to all of them.</p>
        <p>Mixing modes within a single page works too: drop one minimap with <code>mode="stripes"</code> at one breakpoint and another with <code>mode="rendered"</code> at a different breakpoint via media queries. The two share zero state — purely visual variants of the same primitive.</p>
        <h3>Real-world recipes</h3>
        <p>The recipes directory ships three pre-composed minimap examples: <code>/blueprints/recipes/long-form-article</code> (default stripes + bookmark), <code>/blueprints/recipes/documentation-reader</code> (compact block-mode + heading-anchors), and <code>/blueprints/recipes/marketing-landing-toc</code> (which uses reading-toc instead, but pairs well with a minimap on long pages).</p>
        <p>Each recipe is a single Blade file you can copy into your own app. No build step beyond Composer; no JavaScript wiring beyond the WireKit script tag.</p>
        <p>The recipes are intentionally minimal — they show the canonical composition pattern (minimap + bookmark + spine) for each use case, leaving theming and content to the developer. The /blueprints/recipes/ pages on docs.wirekit.app render the recipes as live previews so you see exactly what the output looks like.</p>
        <h2>Performance characteristics</h2>
        <p>The stripe column renders one DOM node per matched item (default selector matches a, h2, h3, [data-minimap-item]). On a typical article (3-10 sections, 20-60 paragraphs), that's a sub-100-node footprint — well within the budget of any reasonable browser. The scroll handler is rAF-throttled so position updates never exceed one per frame.</p>
        <p>Click + drag-pan on the viewport overlay uses pointer events (PointerEvent API) for mouse and pen. A finger does not drag the overlay: the drag works like a scrollbar thumb, and on a touch screen a swipe means moving the content, so the overlay lets the browser scroll natively and a tap on a stripe still jumps to its section.</p>
        <p>The active item is the last heading at or above the middle of the visible part, measured at most once a frame while the page scrolls — the minimap stays in sync with the reader's progress without any work between frames.</p>
        <p>The component does not poll. Every update is either a frame after a scroll (the viewport overlay and the active item) or a ResizeObserver entry (the layout after a size change); an IntersectionObserver only defers drawing the rendered canvas until the minimap first comes into view. Idle-state CPU usage is effectively zero.</p>
        <h3>Memory budget</h3>
        <p>Stripes-mode mounts one <code>&lt;li&gt;</code> per matched item plus the wrapper + overlay. Block-mode is identical. Rendered-mode adds a canvas element sized to the minimap dimensions — sub-MB memory at typical widths.</p>
        <p>The hover-preview extension (<code>hoverPreview="true"</code>) lazily mounts a sandboxed iframe-srcdoc on first pointermove, sanitized via the same OWASP-vector-blocking pass the rendered-mode preview used. Sub-100 KB DOM in the popover; no script execution surface (sanitizer strips all attack vectors before parse).</p>
        <h2>When to reach for rendered mode instead</h2>
        <p>If the article has a visually distinct rhythm — long sections alternating with short callouts, image-heavy figures, code blocks every few paragraphs — the <code>mode="rendered"</code> canvas variant gives a more recognizable thumbnail than the abstract stripes. Drop <code>mode="rendered"</code> on the same component to opt in.</p>
        <p>For dense link-lists or sidebars where every item is roughly the same height, stripes-mode with <code>itemStyle="line"</code> reads cleaner — the rhythm doesn't matter, the hierarchy does.</p>
        <p>The two modes share the same Alpine state (items collection, active-index tracking, viewport-overlay math). Only the rendered visual differs. Switching <code>mode</code> at runtime is supported — the component re-renders without a remount.</p>
        <h3>Closing</h3>
        <p>The minimap is the densest of the reading-* primitives but follows the same family contract: scroll-driven, measured at most once a frame, theme-aware via family-prefixed CSS variables. The token surface is intentionally wide so developer brands can re-skin without forking.</p>
        <p>Keep scrolling to the end of this preview — the viewport overlay rectangle continues to track your position all the way down. By the bottom, the rectangle should sit at the lower portion of the minimap column.</p>
    </article>
</x-wirekit::prose>
</div>

<x-wirekit::reading-minimap
    hideBelow="none"
    itemSelector="h2, h3, p"
    :heading-anchors="true"
    :show-bookmarks="false"
    :auto-fade-idle="false"
/>
<x-wirekit::prose>
    <article style="padding: 1rem 5.5rem 1rem 1rem;">
        <h2 id="rha-install">Install the package</h2>
        <p>Require the package with Composer, then run the install command. It publishes the configuration file and tells you which step to take next, so a first run leaves nothing half set up.</p>
        <p>The command is safe to run twice. It checks what is already in place and only adds what is missing.</p>

        <h3 id="rha-configure">Publish the configuration</h3>
        <p>The configuration file lists every option with its default and a short explanation. Change only what you need: anything you leave out keeps its default when the package updates.</p>
        <p>Values that differ between environments belong in your environment file rather than in the published one, so a deploy never overwrites them.</p>

        <h2 id="rha-first-page">Build your first page</h2>
        <p>Start from a layout component and fill its slots. A page needs a heading, a short introduction and one clear action. Everything else can come later.</p>
        <p>Look at the page at phone width before you add more. Most layout problems are cheaper to notice with three components on the page than with thirty.</p>

        <h3 id="rha-layout">Choose a layout</h3>
        <p>A sidebar layout suits pages people return to and move around in. A centered column suits pages people read once from top to bottom, like this one.</p>
        <p>Both collapse to a single column on a phone, so the choice is about how the page is used on a wide screen.</p>

        <h3 id="rha-navigation">Add navigation</h3>
        <p>Link the sections of a long page from a table of contents, a spine or this minimap. The anchors beside the minimap are links like any other, so a keyboard reaches them and a screen reader announces them.</p>
        <p>Keep the headings short. The anchor labels repeat them, and a long heading ends in an ellipsis once the label runs out of room.</p>

        <h2 id="rha-deploy">Deploy</h2>
        <p>Build the assets, run the migrations and clear the caches, in that order. A deploy script that does all three keeps the steps from drifting apart between machines.</p>
        <p>Keep scrolling: the viewport rectangle on the minimap follows you down the page, and the anchor for each section stays one click away.</p>
    </article>
</x-wirekit::prose>

<div
    x-data="{
        init() {
            // Seed a fake prior bookmark BEFORE the child reading-bookmark
            // component's init() reads localStorage. Alpine guarantees
            // PARENT init() runs before CHILD init() (DOM-tree order),
            // so wrapping the bookmark in this parent x-data eliminates
            // the race that two sibling x-data blocks would expose. The
            // earlier sibling-pattern with x-init on an empty div was
            // unreliable — Alpine's walk order between siblings is not
            // guaranteed by the spec, and bookmark could mount + read
            // before the seed write fired.
            try {
                localStorage.setItem('reading-bookmark-demo', JSON.stringify({
                    top: 600,
                    dwell: 90,
                    t: Date.now() - 5 * 60 * 1000,
                }));
            } catch (_) { /* private mode — ignore */ }
        }
    }"
>
    <x-wirekit::reading-bookmark key="reading-bookmark-demo" :minDwellSeconds="0" />
    <x-wirekit::prose>
        <article style="padding: 1rem 1rem 6rem; min-height: 800px;">
            <h2>Resume reading?</h2>
        <p>The pill in the bottom-right of this iframe is the resume-reading affordance. It surfaces when localStorage already holds a prior bookmark (saved on a previous visit, after the reader dwelled long enough and scrolled past the threshold). Click <strong>Resume</strong> to scroll the iframe to the saved position; click <strong>×</strong> to dismiss the pill while keeping the bookmark for the next visit.</p>
        <p>This preview seeds a fake prior bookmark on mount via inline Alpine — the real component reads it back on init and shows the pill. On a real article you would not need the seed: the bookmark writes itself as the reader scrolls, and reads itself on the next visit.</p>
        <p>The component clears the bookmark when the reader scrolls back to the top — at that point they are starting over, not resuming. It also reacts to cross-tab <code>storage</code> events, so dismissing the pill in one tab hides it in every other open tab on the same article.</p>
        <p>Scroll inside this iframe to write a fresh bookmark on top of the seeded one (the seed updates with each scroll past the 10% threshold). Reload the iframe to see the pill reappear with the latest position.</p>
        <h2>Filler — keep scrolling</h2>
        <p>Cross-device sync is intentionally out of scope. The localStorage write is per-origin per-key; if you want a cross-device "resume on phone where I left off on desktop" experience, build a server-side bookmark via Eloquent (a column on the user-article pivot table) and listen for the same scroll events the primitive emits.</p>
        <p>A polite live region beside the pill (<code>role="status"</code>, <code>aria-live="polite"</code>) announces the resume offer when it appears, so assistive technology hears it without interrupting the current reading. The pill itself carries no role: it is the visible half of that announcement.</p>
        <p>The Resume button uses the accent fill; the dismiss button is icon-only with an <code>aria-label</code>. Both are keyboard-focusable and respect the same focus-ring tokens every other interactive WireKit primitive uses.</p>
        </article>
    </x-wirekit::prose>
</div>

<x-wirekit::reading-meta :showRemaining="true" />

{{-- 1. The contained reading surface establishes a positioning context
      (position: relative) AND a scrolling container (overflow-y: auto)
      with a defined height — both required for `position: sticky` to
      anchor correctly. Without these, the sticky strategy degrades
      to static and the bar disappears. --}}
<div role="region" aria-label="Contained reading surface" tabindex="0" class="wk-focus-ring" style="position: relative; max-height: 18rem; overflow-y: auto; border: 1px solid var(--color-wk-border); border-radius: var(--radius-wk-md); padding: 0; background: var(--color-wk-bg-elevated);">
    {{-- 2. boundary="container" makes the bar use position: sticky and
          anchor to the nearest positioned ancestor — the wrapper above. --}}
    <x-wirekit::reading-progress boundary="container" height="md" intent="primary" />

    <article style="padding: 1.25rem 1.5rem;">
        <h3 style="margin: 0 0 0.5rem 0;">Containment demo</h3>
        <p style="margin: 0 0 0.75rem 0;">Scroll inside THIS card and the bar fills as the local scroll progresses — it never escapes to the outer page viewport.</p>
        <p style="margin: 0 0 0.75rem 0;">Each paragraph extends the scrollable area inside the card. Keep scrolling and the bar saturates.</p>
        <p style="margin: 0 0 0.75rem 0;">A modal body, sidebar pane, preview frame, or Livewire panel are all valid container surfaces — anything with <code>position: relative</code> + a scroll-mechanism works.</p>
        <p style="margin: 0 0 0.75rem 0;">Without <code>boundary="container"</code>, the bar would pin to the OUTER viewport instead of this card, breaking the contained-reading metaphor.</p>
        <p style="margin: 0 0 0.75rem 0;">More body text so the wrapper actually scrolls and you can see the fill react.</p>
        <p style="margin: 0;">End of body.</p>
    </article>
</div>