/*
 * Handbook documentation shell - shared by every long-form document page.
 *
 * Renders /faq, /trail-book-valuation/methodology, /terms-and-conditions and
 * /privacy-policy: a sticky, generated contents rail beside a reading column
 * carrying a breadcrumb, a documentation heading scale and a documentation
 * body scale.
 *
 * This file owns the shell and nothing else. The FAQ's search control, its
 * results panel, its in-answer chips and its mobile search button stay in
 * faq_page.css, which layers on top of this one; the methodology page's tables,
 * formula boxes and grade badges stay in trail_book_valuation_methodology.css.
 *
 * DELIBERATELY ABSENT: body copy, lists, <mark>, <code>, images and call-outs
 * get no rules here. They keep the style.css and callouts.css treatment they
 * have today, which is what makes "the document renders identically" a
 * structural guarantee rather than a re-derivation.
 *
 * Conventions:
 *  - Transitions always name explicit properties (never broad transitions).
 *  - Every custom control owns :focus, :active and :focus-visible.
 *  - Rail links restate the body-link reset at ID weight, because style.css
 *    matches `a:not(...)` at (0,1,1) and would otherwise give them the green
 *    underline shadow meant for links inside the document.
 */

/* ------------------------------------------------------------------ */
/* Page shell                                                          */
/* ------------------------------------------------------------------ */

/* Replaces Bootstrap's .container. The width is stepped rather than fixed:
   the composition grows with the display so a 27" monitor does not show a
   narrow strip floating in the middle of the canvas, but the reading measure
   stops growing well before a line becomes tiring to track. See the
   breakpoint steps at the foot of this file.
   Written at ID weight because style.css sets `#main-content { max-width: 95% }`
   plus responsive overrides, all of which outrank a bare class selector. */
#main-content.handbook-page {
    width: 100%;
    max-width: 1180px;
    margin: 0 auto;
    padding: 2.5rem 1.25rem 5rem;
}

/* One column until the script reports the contents rail is populated, so a
   visitor without JavaScript reads a full-width document rather than a page
   with a permanently empty gutter. */
.handbook-shell {
    display: grid;
    grid-template-columns: minmax(0, 1fr);
    align-items: start;
}

/* `minmax(0, 1fr)` rather than `1fr`: a grid item's automatic minimum size is
   its content's min-content width, so a wide table inside the reading column
   would otherwise widen the track and scroll the whole document sideways
   instead of scrolling inside its own container. */
.handbook-shell.is-ready {
    grid-template-columns: 15rem minmax(0, 1fr);
    gap: 2.5rem;
}

.handbook-shell:not(.is-ready) .handbook-main {
    margin-left: auto;
    margin-right: auto;
}

/*
 * `position: sticky` makes this element a stacking context, and its z-index
 * of `auto` would leave that context painting in tree order against the
 * positioned boxes that come after it. `.entry-content > ul > li::before`
 * (style.css) is `position: absolute`, so every bullet in the document would
 * paint over the FAQ's search results panel. An explicit z-index lifts the
 * whole rail above the document; the app navigation sits at 1000 and stays
 * above it.
 */
.handbook-nav {
    display: none;
    position: sticky;
    /* Clears the same gap the retired bootstrap-toc rail used (42px). */
    top: 2.5rem;
    z-index: 30;
    min-width: 0;
}

.handbook-shell.is-ready .handbook-nav {
    display: block;
}

/* The reading column, not `.entry-content`, owns the measure on these pages:
   see the `.entry-content` override below. `min-width: 0` keeps a wide
   screenshot, code block or table from forcing the grid column open - the
   same automatic-minimum-size trap `minmax(0, 1fr)` closes on the track.

   The 880px cap never binds in production - the grid column already resolves
   to 820px, or 880px at the widest step - but it does bind in the
   /prototype-faq-layouts and /prototype-document-pages Production panels,
   whose container is not `#main-content.handbook-page`. Without it those
   panels would render the document wider than the page they exist to
   reproduce. */
.handbook-main {
    min-width: 0;
    /*
     * `width: 100%` rather than `auto`, and it is load-bearing. Both the
     * no-JS rule above and the below-1024px block give this element
     * `margin-left/right: auto` so the measure stays centred once the 880px
     * cap binds. An `auto` width plus an auto margin turns off a grid item's
     * stretch behaviour and sizes it to fit-content instead, and fit-content
     * floors at the content's min-content width - which on the methodology
     * page is a five-column table, so the reading column resolved to 834px
     * inside a 346px track on a phone and scrolled the whole document
     * sideways. A definite percentage resolves against the track, keeps the
     * cap and lets the auto margins do only the centring they were added for.
     */
    width: 100%;
    max-width: 880px;
}

/*
 * style.css caps `.entry-content` at 740px and centres it with `margin: auto`.
 * Both fight the shell here: the cap freezes the measure at one width no
 * matter how much room the display has, and the centring floats the document
 * away from the breadcrumb, title and lede, which are aligned to the column.
 * Handing the measure to `.handbook-main` keeps one left edge and lets the
 * copy breathe on a large display. The 20px side padding and 50px bottom
 * margin are the ones style.css already applies.
 */
#main-content.handbook-page .entry-content {
    max-width: none;
    margin-left: 0;
    margin-right: 0;
}

/* ------------------------------------------------------------------ */
/* Wide blocks                                                         */
/* ------------------------------------------------------------------ */

/*
 * A five-column grading table does not read inside a prose measure. A
 * `.handbook-wide` wrapper breaks its content symmetrically out of
 * `.entry-content`'s own 20px side padding, so the block uses the reading
 * column's full width and stays inside the shell.
 *
 * Symmetric is the binding constraint, not a preference. `.handbook-main` is
 * the second grid column, so its right edge already IS the shell's content
 * edge at every breakpoint step; growing further right would push the
 * document sideways, which is the one thing this treatment must never do.
 *
 * The inner scroller is what keeps the promise on a phone: below the table's
 * min-width floor the table scrolls inside this box rather than widening it.
 */
.handbook-wide {
    /* Belt and braces with the grid track's `minmax(0, 1fr)`: an
       `overflow-x: auto` child propagates its content's minimum width to its
       ancestors unless a min-width floor stops it here. */
    min-width: 0;
    max-width: none;
}

.handbook-main .handbook-wide {
    margin-left: -20px;
    margin-right: -20px;
}

/*
 * A wide block nested inside a call-out, a bordered card or an accordion keeps
 * its container's padding: pulling it through the box it belongs to would
 * break that box's border. The modifier is authored on the wrapper rather than
 * derived from a descendant selector, so a reader of the template can see
 * which treatment a given table gets.
 */
.handbook-main .handbook-wide--inset {
    margin-left: 0;
    margin-right: 0;
}

.handbook-wide__scroller {
    min-width: 0;
    max-width: 100%;
    overflow-x: auto;
    overscroll-behavior-x: contain;
    -webkit-overflow-scrolling: touch;
}

/* ------------------------------------------------------------------ */
/* Contents list                                                       */
/* ------------------------------------------------------------------ */

/*
 * Only the list scrolls, never `.handbook-nav` itself: the FAQ's search
 * results panel is an absolutely positioned child of the rail, and a scroll
 * container on the rail would clip it. Keeping the overflow here leaves the
 * search control pinned and lets a fully expanded group of thirteen run past
 * the fold on a short display without stranding the entries below it.
 *
 * The subtle scrollbar matches the shared treatment in methodology_modal.css.
 */
.handbook-nav__disclosure {
    min-width: 0;
    max-height: calc(100vh - 9rem);
    overflow-y: auto;
    overscroll-behavior: contain;
    -webkit-overflow-scrolling: touch;
    scrollbar-width: thin;
    scrollbar-color: #e2e8f0 transparent;
}

.handbook-nav__disclosure::-webkit-scrollbar {
    width: 8px;
}

.handbook-nav__disclosure::-webkit-scrollbar-track {
    background: transparent;
}

.handbook-nav__disclosure::-webkit-scrollbar-thumb {
    border-radius: 999px;
    border: 2px solid transparent;
    background: #e2e8f0;
    background-clip: content-box;
}

.handbook-nav__disclosure:hover::-webkit-scrollbar-thumb,
.handbook-nav__disclosure:focus-within::-webkit-scrollbar-thumb {
    background: #cbd5e1;
    background-clip: content-box;
}

.handbook-nav__summary {
    display: none;
}

/* The sprite only exists so the script can clone icon markup out of it. */
.handbook-nav__sprite {
    display: none;
}

.handbook-nav__list {
    display: flex;
    flex-direction: column;
}

/* A page with no authored groups renders one flat list, so the row rhythm the
   `.handbook-nav__group-items` container supplies has to come from the list
   itself. handbook_page.js adds this modifier only when it emitted no group
   caption, which is why /faq's spacing is untouched. */
.handbook-nav__list--flat {
    gap: 0.1rem;
}

.handbook-nav__link {
    display: flex;
    align-items: center;
    gap: 0.5rem;
    padding: 0.4rem 0.6rem;
    border-radius: 0.5rem;
    font-family: var(--tailwind-font);
    font-size: 0.8125rem;
    line-height: 1.35;
    transition: background-color 180ms ease, color 180ms ease;
}

/* Wins the remaining width so a long label wraps rather than shunting the
   chevron off the rail. */
.handbook-nav__label {
    flex: 1 1 auto;
    min-width: 0;
}

.handbook-nav__link .handbook-nav__icon {
    flex: 0 0 auto;
    width: 1rem;
    height: 1rem;
    transition: color 180ms ease;
}

/* ------------------------------------------------------------------ */
/* Rail groups                                                         */
/* ------------------------------------------------------------------ */

/*
 * Groups are captions, not controls: a static uppercase label above the
 * entries that belong to it, with real air between one group and the next.
 * They are authored on the headings (`data-handbook-nav-group`) rather than
 * derived, and they are optional. /faq authors them because only three of its
 * ten h2s own h3 children - deriving sections from the document alone would
 * leave the other seven without a home. The three document pages are the
 * opposite shape, so they carry no groups and the rail renders one ungrouped
 * list.
 */
.handbook-nav__group {
    margin-bottom: 1.35rem;
}

.handbook-nav__group:last-child {
    margin-bottom: 0;
}

.handbook-nav__group-label {
    margin: 0 0 0.4rem;
    padding-left: 0.6rem;
    font-family: var(--tailwind-font);
    font-size: 0.6875rem;
    font-weight: 700;
    letter-spacing: 0.1em;
    text-transform: uppercase;
    color: #0f172a;
}

.handbook-nav__group-items {
    display: flex;
    flex-direction: column;
    gap: 0.1rem;
}

/* ------------------------------------------------------------------ */
/* Collapsible entries                                                 */
/* ------------------------------------------------------------------ */

/*
 * Thirteen of the FAQ's twenty-one h3s live under a single h2, and thirty-nine
 * of the Terms page's sub-clauses hang off twelve clauses, so listing every
 * heading opens the rail on a wall. An entry that owns children carries a
 * chevron instead, and handbook_page.js opens the one the reader is in.
 */
.handbook-nav__section {
    display: flex;
    flex-direction: column;
    gap: 0.1rem;
}

.handbook-nav__entryrow {
    display: flex;
    align-items: center;
    gap: 0.15rem;
}

.handbook-nav__entryrow .handbook-nav__entry {
    flex: 1 1 auto;
    min-width: 0;
}

.handbook-nav__toggle {
    flex: 0 0 auto;
    display: inline-flex;
    align-items: center;
    justify-content: center;
    width: 1.5rem;
    height: 1.5rem;
    padding: 0;
    border: 0;
    border-radius: 0.375rem;
    background: transparent;
    color: #cbd5e1;
    cursor: pointer;
    -webkit-appearance: none;
    appearance: none;
    transition: background-color 180ms ease, color 180ms ease;
}

.handbook-nav__toggle:hover {
    background: #f1f5f9;
    color: #0f172a;
}

.handbook-nav__chevron {
    width: 0.75rem;
    height: 0.75rem;
    transition: transform 180ms ease;
}

.handbook-nav__toggle[aria-expanded="true"] .handbook-nav__chevron {
    transform: rotate(90deg);
}

.handbook-nav__children {
    display: flex;
    flex-direction: column;
    gap: 0.1rem;
}

/* A flex container beats the user agent's `[hidden] { display: none }`, so
   the collapsed state has to be restated at this weight. */
.handbook-nav__children[hidden] {
    display: none;
}

/* Children hang off a hairline that runs under the parent entry's icon, so
   the indent lines up with the thing they belong to. */
.handbook-nav__item {
    margin-left: 1.1rem;
    padding-left: 0.9rem;
    border-left: 1px solid #e5e7eb;
    border-top-left-radius: 0;
    border-bottom-left-radius: 0;
    font-size: 0.78125rem;
}

.handbook-nav__link:hover {
    background: #f1f5f9;
}

.handbook-nav__link.is-current {
    background: #ecfdf5;
    font-weight: 600;
}

.handbook-nav__item.is-current {
    border-left-color: #059669;
}

/* Restate the body-link reset at ID weight: style.css's global `a:not(...)`
   rule would otherwise paint the green underline shadow on every rail link. */
#main-content .handbook-nav__link,
#main-content .handbook-nav__link:hover {
    text-decoration: none;
    box-shadow: none;
}

/* Two tones only: an entry is a destination, a child is a step inside one. */
#main-content .handbook-nav__link {
    color: #64748b;
}

#main-content .handbook-nav__entry {
    color: #334155;
}

#main-content .handbook-nav__link:hover {
    color: #0f172a;
}

#main-content .handbook-nav__link.is-current {
    color: #047857;
}

/* The icon is the quiet part of the row until the row is the reader's. */
.handbook-nav__link .handbook-nav__icon {
    color: #cbd5e1;
}

.handbook-nav__link:hover .handbook-nav__icon {
    color: #94a3b8;
}

.handbook-nav__link.is-current .handbook-nav__icon {
    color: #059669;
}

/* ------------------------------------------------------------------ */
/* Shared focus contract                                               */
/* ------------------------------------------------------------------ */

.handbook-nav__link:focus,
.handbook-nav__link:active,
.handbook-nav__summary:focus,
.handbook-nav__summary:active,
.handbook-nav__toggle:focus,
.handbook-nav__toggle:active {
    outline: 2px solid transparent;
    outline-offset: 2px;
    box-shadow: none;
}

.handbook-nav__link:focus-visible,
.handbook-nav__summary:focus-visible,
.handbook-nav__toggle:focus-visible {
    outline: 2px solid #059669;
    outline-offset: 2px;
    box-shadow: none;
}

/* ------------------------------------------------------------------ */
/* Reading column chrome                                               */
/* ------------------------------------------------------------------ */

/* The 20px side padding matches .entry-content's own padding so the header
   block and the document share one left edge. */
.handbook-crumbs,
.handbook-title,
.handbook-lede {
    padding-left: 20px;
    padding-right: 20px;
}

.handbook-crumbs {
    display: flex;
    align-items: center;
    gap: 0.35rem;
    margin-bottom: 0.8rem;
    font-family: var(--tailwind-font);
    font-size: 0.75rem;
    color: #94a3b8;
}

.handbook-crumb__sep {
    width: 0.75rem;
    height: 0.75rem;
    color: #cbd5e1;
}

.handbook-crumb--current {
    color: #475569;
    font-weight: 500;
}

/* The rule closes the header block, so the first call-out below reads as the
   start of the document rather than as more of the title. It is carried on the
   margin rather than the shared 20px padding so it lines up exactly with the
   hairlines above each h2, which sit inside `.entry-content`'s own padding. */
.handbook-lede {
    margin: 0 20px;
    padding: 0 0 1.75rem;
    border-bottom: 1px solid #f1f5f9;
    font-family: var(--tailwind-font);
    font-size: 1.0625rem;
    line-height: 1.6;
    color: #64748b;
}

/* ------------------------------------------------------------------ */
/* Heading scale                                                       */
/* ------------------------------------------------------------------ */

/*
 * Scoped to `#main-content .handbook-main` so these outrank the bare element
 * rules in style.css (h1 46px / h2 40px / h3 36px / h4 32px in the trackmytrail
 * face, each carrying a negative left margin). Body copy keeps the
 * trackmytrail face; only the headings move to Inter.
 *
 * `text-align: left` is load-bearing, not decoration. style.css centres
 * `#main-content > h1` and `#main-content h2` at (1,0,1) and only escapes that
 * through `#main-content .faq-content h2`. Restating the alignment here at
 * (1,1,1) is what lets every handbook page drop `.faq-content` from its
 * reading column - a class that means three different things on the
 * methodology page alone.
 *
 * `.handbook-main` rather than `.handbook-content`: /prototype-faq-layouts and
 * /prototype-document-pages load this stylesheet to style their Production
 * panels, and their design-history panels reproduce the retired Bootstrap
 * documents, which carry `.faq-content`. Scoping by `.handbook-main` keeps
 * those reproductions on the old heading scale they exist to show.
 */
#main-content .handbook-main h1,
#main-content .handbook-main h2,
#main-content .handbook-main h3,
#main-content .handbook-main h4 {
    font-family: var(--tailwind-font);
    font-weight: 600;
    letter-spacing: -0.015em;
    max-width: none;
    text-align: left;
}

/* A hairline above each h2 does the section separation the gallery got from
   per-answer wrappers, which these documents deliberately do not have. */
#main-content .handbook-main h2 {
    margin: 3.25rem 0 0;
    padding-top: 2.25rem;
    border-top: 1px solid #f1f5f9;
    font-size: 24px;
    line-height: 1.3;
}

#main-content .handbook-main .entry-content h2:first-of-type {
    margin-top: 1.5rem;
    padding-top: 0;
    border-top: 0;
}

/* Thirteen aggregator answers run back to back under one h2, so an h3 needs
   more air above it than the 8px `.entry-content h3 + p` leaves below it, or
   the sub-sections read as one continuous block. */
#main-content .handbook-main h3 {
    margin: 3rem 0 0;
    font-size: 20px;
    line-height: 1.35;
}

#main-content .handbook-main h4 {
    margin: 2rem 0 0;
    font-size: 16px;
    line-height: 1.4;
}

/* Class-based so a gallery Production panel, which uses an h2 to avoid a
   second h1 on that page, gets the same title treatment as production's h1. */
#main-content .handbook-main .handbook-title {
    margin: 0 0 0.65rem;
    padding-top: 0;
    border-top: 0;
    font-size: 36px;
    line-height: 1.15;
}

/* ------------------------------------------------------------------ */
/* Wide displays                                                       */
/* ------------------------------------------------------------------ */

/*
 * The shell grows in steps rather than filling the viewport. Each step widens
 * the rail, the gutter and, through `minmax(0, 1fr)`, the reading column:
 *
 *   base       15rem rail + 2.5rem gutter, container 1180px -> ~780px measure
 *   >= 1280px  16rem rail + 4rem   gutter, container 1180px -> ~780px measure
 *   >= 1600px  17rem rail + 5rem   gutter, container 1272px -> ~840px measure
 *
 * It stops there on purpose. 840px is about 70 characters at the body size,
 * which is the top of the comfortable range; spending more of a very wide
 * display on the measure would make the document harder to read, not easier.
 */
@media (min-width: 1280px) {
    .handbook-shell.is-ready {
        grid-template-columns: 16rem minmax(0, 1fr);
        gap: 4rem;
    }
}

@media (min-width: 1600px) {
    #main-content.handbook-page {
        max-width: 1272px;
        padding-top: 3.25rem;
    }

    .handbook-shell.is-ready {
        grid-template-columns: 17rem minmax(0, 1fr);
        gap: 5rem;
    }
}

/* ------------------------------------------------------------------ */
/* Below 1024px                                                        */
/* ------------------------------------------------------------------ */

@media (max-width: 1023px) {
    #main-content.handbook-page {
        max-width: 95vw;
        padding: 1rem 0.75rem 2.5rem;
    }

    #main-content .handbook-main .handbook-title {
        font-size: 28px;
    }

    .handbook-shell.is-ready {
        grid-template-columns: minmax(0, 1fr);
        gap: 1.5rem;
    }

    /* A collapsed contents list, so the first section is not pushed below 62
       links on the Terms page. */
    .handbook-nav {
        position: static;
        padding-bottom: 1.25rem;
        border-bottom: 1px solid #e5e7eb;
    }

    /* The rail is not sticky here, so the list has the whole page to grow
       into and must not carry its own scroll container. */
    .handbook-nav__disclosure {
        max-height: none;
        overflow-y: visible;
    }

    .handbook-main {
        margin-left: auto;
        margin-right: auto;
    }

    /* list-item keeps the native disclosure triangle, which `display: block`
       removes in Chromium. */
    .handbook-nav__summary {
        display: list-item;
        padding: 0.45rem 0.6rem;
        border: 1px solid #e5e7eb;
        border-radius: 0.6rem;
        background: #ffffff;
        font-family: var(--tailwind-font);
        font-size: 0.8125rem;
        font-weight: 600;
        color: #0f172a;
        cursor: pointer;
        list-style-position: inside;
    }

    .handbook-nav__list {
        margin-top: 0.5rem;
    }
}

/* ------------------------------------------------------------------ */
/* Documentation body size                                             */
/* ------------------------------------------------------------------ */

/*
 * The document inherits `body { font-size: 20px }` (style.css), which reads
 * large next to the Inter documentation heading scale (h1 36 / h2 24 / h3 20
 * / h4 16). Drop the reading column to 18px, scoped to
 * `#main-content.handbook-page` so the shared `.entry-content` class keeps 20px
 * everywhere else it is used - /contact and the demo pages.
 *
 * The child combinator is deliberate: only paragraphs and list items that are
 * direct children of `.entry-content` or the FAQ's protected-content wrapper
 * move. Call-out copy sits under
 * `.tailwind-scope .call-out-content`, which sizes itself at 0.9em, and
 * `<code>` / `<mark>` size independently - all must stay put.
 *
 * 31px line-height holds the ~1.72 ratio the 20px page had at 35px; 26px holds
 * the standalone-paragraph rhythm proportionally (was 29px at 20px). The tight
 * heading-to-paragraph spacing (8px after an h2, 6px after an h3/h4) is
 * restated here so the ID-weight font-size rule does not inherit the looser
 * 26px in its place.
 */
#main-content.handbook-page .entry-content > p,
#main-content.handbook-page .entry-content > [data-faq-sensitive-content] > p {
    font-size: 18px;
    line-height: 31px;
    margin-top: 26px;
}

#main-content.handbook-page .entry-content h2 + p {
    margin-top: 8px;
}

#main-content.handbook-page .entry-content h3 + p,
#main-content.handbook-page .entry-content h4 + p {
    margin-top: 6px;
}

#main-content.handbook-page .entry-content > ol > li,
#main-content.handbook-page .entry-content > ul > li,
#main-content.handbook-page .entry-content > [data-faq-sensitive-content] > ol > li,
#main-content.handbook-page .entry-content > [data-faq-sensitive-content] > ul > li {
    font-size: 18px;
}

/* The custom bullet is sized off its own font-size; shrink it in step with the
   18px text so it stays optically balanced. Horizontal placement is untouched:
   the marker's `width` and negative `margin-left` are both 4.875em and cancel
   regardless of the font-size, so only the glyph size changes. */
#main-content.handbook-page .entry-content > ul > li::before,
#main-content.handbook-page .entry-content > [data-faq-sensitive-content] > ul > li::before {
    font-size: 15px;
}

/* ------------------------------------------------------------------ */
/* Deep-link breathing room                                            */
/* ------------------------------------------------------------------ */

/*
 * handbook_page.js re-applies the URL hash on load with scrollIntoView(), and
 * native fragment navigation lands the target heading flush against the
 * viewport top, which reads as if the page is cut off above it.
 * scroll-margin-top is honoured by both native fragment scrolling and
 * scrollIntoView(), so the on-load re-apply, rail clicks, search selections
 * and the FAQ's in-answer chips all land the same way. The larger phone offset
 * clears the 52px sticky app header shown to signed-in users on mobile.
 */
#main-content .handbook-main h2,
#main-content .handbook-main h3,
#main-content .handbook-main h4 {
    scroll-margin-top: 2rem;
}

@media (max-width: 768px) {
    #main-content .handbook-main h2,
    #main-content .handbook-main h3,
    #main-content .handbook-main h4 {
        scroll-margin-top: 4.5rem;
    }
}