/*
  hero-cycle-addon.css
  ---------------------------------------------------------------------
  Turns hero.css's single background image into several, crossfading
  on an endless loop behind the same title/subtitle/actions content.

  @keyframes plus a staggered animation-delay per layer drive the
  loop; a plain checkbox and :has() drive the pause control below - no
  JavaScript anywhere. Add class="hero--cycle" alongside .hero, then
  add the layer markup below inside it. --hero-image on .hero itself
  becomes unused in this mode (cleared below so the browser never
  fetches an image nothing shows), since the multi-layer background-
  image trick hero.css relies on (list of layers, painted front-to-
  back in one property) has no way to independently fade just ONE of
  its own layers over time - only real, separate elements can each
  run their own animation.

  Requires: css/reset.css, css/core.css, css/components/hero.css

  HTML STRUCTURE:
    <main id="hero" class="hero hero--cycle container" aria-labelledby="hero-title">
      <div class="hero__cycle-layers" aria-hidden="true">
        <div class="hero__cycle-layer" style="--i: 0; background-image: url('...')"></div>
        <div class="hero__cycle-layer" style="--i: 1; background-image: url('...')"></div>
        <div class="hero__cycle-layer" style="--i: 2; background-image: url('...')"></div>
        <div class="hero__cycle-layer" style="--i: 3; background-image: url('...')"></div>
      </div>
      <header class="hero__content stack">
        ...same content as a plain .hero...
      </header>
      <label class="hero-cycle-toggle">
        <input class="hero-cycle-pause" type="checkbox">
        Pause background motion
      </label>
    </main>

  aria-hidden="true" on the layer wrapper is correct here (not the
  focusable-but-hidden bug it would be on a link): these divs hold no
  interactive content, only decorative background-image, so hiding
  them from assistive tech loses nothing.

  PAUSE CONTROL, WITHOUT JAVASCRIPT:
    A plain checkbox, wrapped inside its own label rather than paired
    with a for/id - the wrapping is what lets this work with zero ids
    at all, which matters because :has() reacts to .hero-cycle-pause
    being :checked, not to any particular id. An earlier version used
    two <a href="#..."> links and :target instead; that had three real
    problems this version doesn't: the target id was hardcoded into
    the CSS selector, so a second Hero Cycle on the same page couldn't
    have its own independent one; clicking "Stop" changed the URL/
    browser-history for what is purely a local animation toggle, not
    navigation; and the focused "Stop" link would vanish the instant
    it became the :target (the CSS hides it once matched), handing
    focus somewhere unpredictable. A checkbox's checked state is local
    to the element, already the exact accessible signal a screen
    reader needs (no aria-pressed-style wrangling required), and nothing
    about checking it ever disappears out from under a user's focus.

  CHANGING THE IMAGE COUNT:
    --hero-cycle-count and each layer's own --i need to stay in sync
    with how many .hero__cycle-layer elements actually exist (0, 1, 2,
    3, ... in document order). Beyond that, the @keyframes below are
    shaped so each layer gets roughly 100 / --hero-cycle-count percent
    of the loop - since keyframe percentages can't reference a custom
    property, adding or removing an image also means recalculating
    the five percentages in @keyframes hero-cycle-fade so every image
    keeps an evenly-sized turn. The default below is tuned for 4.

  ACCESSIBILITY NOTE:
    WCAG 2.2.2 applies to this regardless of how decorative the
    motion is: automatically-started movement lasting more than five
    seconds, shown alongside other content, needs a pause/stop/hide
    mechanism - the checkbox above is that mechanism.
    prefers-reduced-motion below is a separate, additional
    consideration, not a substitute for it - it serves users who have
    set that preference in advance, not someone who simply wants this
    specific background to stop right now.
  ---------------------------------------------------------------------
*/

@layer tokens {
  :root {
    /* Lighter than hero.css's own --hero-overlay (70% mix) on
       purpose: that strength is tuned for ONE fixed photo, picked
       once and never competing with anything else. Several
       different photos crossfading need to actually read as
       different photos - the full 70% tint flattens them all
       toward the same near-black, which reads as one dim image
       fading into itself rather than a set of images. Still
       derived from --hero-shade like the original, so it stays
       theme-consistent and re-balances with it automatically. */
    --hero-cycle-overlay: color-mix(in oklab, var(--hero-shade) 25%, transparent);

    /* hero.css's own --hero-text-shadow is tuned to work WITH its
       70%-strength overlay doing most of the contrast work; the
       overlay above is deliberately much lighter, so the shadow
       needs to make up the difference on its own instead of relying
       on a dark backdrop that isn't there anymore. Stronger mix
       percentages (85%/70% vs the original 60%/45%) and a bit more
       spread on the soft layer, still derived from --hero-shade so
       it stays theme-consistent. */
    --hero-cycle-shadow-strong: color-mix(in oklab, var(--hero-shade) 85%, transparent);
    --hero-cycle-shadow-soft: color-mix(in oklab, var(--hero-shade) 70%, transparent);
    --hero-cycle-text-shadow:
      0 2px 6px var(--hero-cycle-shadow-strong),
      0 12px 34px var(--hero-cycle-shadow-soft);

    /* The subtitle needs a touch more than the title gets: it's
       smaller and lighter-weight, so the same shadow that reads
       clearly behind bold, large title text is proportionally less
       effective at anchoring thinner, smaller glyphs. A dedicated,
       slightly stronger pair rather than reusing the title's. */
    --hero-cycle-subtitle-shadow-strong: color-mix(in oklab, var(--hero-shade) 92%, transparent);
    --hero-cycle-subtitle-shadow-soft: color-mix(in oklab, var(--hero-shade) 80%, transparent);
    --hero-cycle-subtitle-shadow:
      0 2px 5px var(--hero-cycle-subtitle-shadow-strong),
      0 1px 10px var(--hero-cycle-subtitle-shadow-strong),
      0 12px 30px var(--hero-cycle-subtitle-shadow-soft);

    /* hero.css's --hero-muted (88% --hero-text, 12% --hero-shade)
       softens the subtitle relative to the title on purpose - a
       readable but visually quieter second voice. That was safe
       against the original 70%-strength overlay, which was doing
       most of the contrast work regardless of the text's own
       color. Against this variant's much lighter overlay, the
       subtitle's slightly darker color eats directly into its own
       contrast margin instead, with less backdrop to fall back on -
       stays legible but reads as harder to read than the title right
       next to it. Closer to full --hero-text here for that reason. */
    --hero-cycle-muted: color-mix(in oklab, var(--hero-text) 97%, var(--hero-shade));
  }
}

@layer components {
  .hero--cycle {
    --hero-cycle-count: 3;
    --hero-cycle-duration: 6s;
    position: relative;
    overflow: hidden;
    background-image: none;
  }

  .hero__cycle-layers {
    position: absolute;
    inset: 0;
    z-index: 0;
  }

  .hero__cycle-layer {
    position: absolute;
    inset: 0;
    background-size: cover;
    background-position: center;
    opacity: 0;
    animation: hero-cycle-fade calc(var(--hero-cycle-count) * var(--hero-cycle-duration)) infinite;
    /* Negative, not positive, and keyed to (count - i) rather than i
       alone - this isn't just a sign flip. A positive delay means the
       layer does nothing at all (sits at its static opacity: 0 above)
       until the delay elapses, then jumps straight into the
       keyframe's 0% value with no interpolation into that jump: the
       very FIRST time each layer takes its turn, the transition is
       "fade to blank, then the next image snaps in," not a crossfade
       - it only starts overlapping correctly from the SECOND lap
       onward, once every layer is already mid-loop. A negative delay
       has no waiting phase at all - the layer is treated as already
       mid-loop from the very first frame, so its own 95%->100% wrap-
       around fade-in lands during the PREVIOUS layer's 20%->25% fade-
       out on the very first cycle too. Using (count - i) rather than
       i keeps the layers in the correct forward order (0, 1, 2, 3 -
       using -i alone plays them 0, 3, 2, 1) while still getting that
       benefit. */
    animation-delay: calc((var(--hero-cycle-count) - var(--i)) * var(--hero-cycle-duration) * -1);
  }

  /* Calibrated for 4 layers: each owns a 25%-wide window of the
     total loop, with a genuine crossfade at either edge - verified by
     sampling both the outgoing and incoming layer's opacity through
     the middle of a transition, not just checking each layer's own
     start/end values in isolation. See CHANGING THE IMAGE COUNT above
     before adding or removing a layer. */
  @keyframes hero-cycle-fade {
    0%      { opacity: 1; }
    28.33%  { opacity: 1; }
    33.33%  { opacity: 0; }
    95%     { opacity: 0; }
    100%    { opacity: 1; }
  }

  /* Same idea as the tint hero.css paints as part of its own
     background-image list, at a lighter strength (--hero-cycle-
     overlay, see tokens above) - painted as a real layer here
     instead, since --hero-image itself is unused in cycle mode (see
     file header). */
  .hero--cycle::before {
    content: "";
    position: absolute;
    inset: 0;
    z-index: 1;
    background: var(--hero-cycle-overlay);
  }

  /* .hero__content already has position: static from hero.css - it
     only needs to sit above the layers/tint (both z-index: 0/1) here,
     not change layout. */
  .hero--cycle .hero__content {
    position: relative;
    z-index: 2;
  }

  /* Overrides hero.css's own text-shadow: var(--hero-text-shadow) -
     see --hero-cycle-text-shadow above for why this needs to be
     stronger here specifically. */
  .hero--cycle .hero__title {
    text-shadow: var(--hero-cycle-text-shadow);
  }

  /* Overrides hero.css's own color: var(--hero-muted) and text-
     shadow: var(--hero-text-shadow) - see --hero-cycle-muted and
     --hero-cycle-subtitle-shadow above for why the subtitle needs
     its own, slightly stronger treatment on both fronts here. */
  .hero--cycle .hero__subtitle {
    color: var(--hero-cycle-muted);
    text-shadow: var(--hero-cycle-subtitle-shadow);
  }

  /* Pause control. Styled like the subtitle (same color/shadow
     tokens), not like .carousel-autoplay-toggle's plain muted text:
     that control sits on a solid card background, this one sits
     directly on a photo and needs the same contrast treatment as the
     rest of this component's text to stay legible against any of the
     four images. */
  .hero-cycle-toggle {
    position: absolute;
    z-index: 2;
    inset-block-end: var(--space-4);
    inset-inline-end: var(--space-4);
    display: inline-flex;
    align-items: center;
    gap: var(--space-2);
    color: var(--hero-cycle-muted);
    text-shadow: var(--hero-cycle-subtitle-shadow);
    font-size: 0.85rem;
    cursor: pointer;
  }

  .hero-cycle-toggle:hover,
  .hero-cycle-toggle:focus-within {
    color: var(--hero-text);
  }

  .hero--cycle:has(.hero-cycle-pause:checked) .hero__cycle-layer {
    animation-play-state: paused;
  }

  /* This has to come AFTER the unconditional rules above, not before:
     at equal specificity (both are plain .hero-cycle-toggle/.hero__
     cycle-layer selectors), a later rule wins regardless of whether
     it sits inside a media query, so this block's display: none only
     actually overrides display: inline-flex above because it's
     written later in the file. Putting it earlier silently loses to
     source order the moment reduced motion is actually active - the
     one case this rule exists for. */
  @media (prefers-reduced-motion: reduce) {
    .hero__cycle-layer {
      animation: none;
      opacity: 0;
    }
    .hero__cycle-layer:first-of-type {
      opacity: 1;
    }

    /* Nothing to pause when reduced motion already means nothing is
       moving - same reasoning as the autoplay addon hiding its own
       toggle in this case. */
    .hero-cycle-toggle {
      display: none;
    }
  }
}
