@waveso/docs 0.7.0 → 0.7.1

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # @waveso/docs
 
+## 0.7.1
+
+### Patch Changes
+
+- 43af6e9: The back-to-top link appears when there is something to go back to.
+
+  It sat at the foot of the table of contents on every page, including at the top
+  of one, offering to return a reader to where they already were. It now fades in
+  between 25dvh and 35dvh of scroll and fades back out on the way up.
+
+  No JavaScript was added to do it. The reveal is a scroll-driven animation, so
+  scroll position alone drives it — no listener, no state, no re-render per
+  frame, and correct before the component has hydrated. `DocsToc` is the smallest
+  client component this package ships and it has not grown by a byte.
+
+  `visibility` moves with the fade, so the link leaves the tab order while it is
+  invisible rather than sitting there as a focus target nobody can see — and it
+  rejoins only once it is legible, not at the first pixel of the fade.
+
+  Where the timeline cannot run the link is simply always present, exactly as it
+  was: Firefox has not shipped scroll-driven animations, a page too short to
+  scroll leaves the timeline inactive, and so does a host that scrolls an inner
+  pane rather than the document. Nothing hides a control on the strength of a
+  feature the engine did not run.
+
 ## 0.7.0
 
 ### Minor Changes

package/README.md

@@ -212,7 +212,7 @@ Every component takes data as props, and every module that imports from `next/*`
 | `SkipLink` | `react/skip-link` | Targets `docs.Page`'s `<main>`; `DOCS_CONTENT_ID` is that id. `docs.Layout` renders one |
 | `createMarkdownComponents` | `react/markdown-components` | The element → component map. `defaultMarkdownComponents` is the unwired one |
 
-`DocsToc`'s `rootMargin` is the `IntersectionObserver` margin that decides how far above the viewport a heading counts as current; the default keeps the highlight on the section you are reading rather than the one about to arrive. `topLabel` is the back-to-top link at the end.
+`DocsToc`'s `rootMargin` is the `IntersectionObserver` margin that decides how far above the viewport a heading counts as current; the default keeps the highlight on the section you are reading rather than the one about to arrive. `topLabel` is the back-to-top link at the end — it fades in once the reader is about a third of a screen down and fades out again on the way back, on a scroll timeline rather than a scroll listener, so the component ships no extra bytes to do it. Where that timeline cannot run — an engine without scroll-driven animations, a page too short to scroll, or a host that scrolls an inner pane rather than the document — the link is simply always there.
 
 The two components the adapter injects take a little more than an `<a>` and an `<img>`. `DocsLinkProps` adds `prefetch` — passed straight to `next/link`, where `false` disables the hover and viewport paths both, so it is a stronger switch in the App Router than the name suggests. `DocsImageProps` carries `src`, `alt`, `width` and `height` — the four `next/image` refuses to render without — and adds `sizes`, `loading`, `decoding` and `fetchPriority`, forwarded to it; markdown carries none of them, so they come from your `imageResolver` or from a `components` override. `decoding` defaults to `async`, and `loading` to `lazy` — except on an image the author marked `eager`, which is usually the page's largest element.
 

package/dist/styles.css

@@ -1725,6 +1725,89 @@
     color: var(--wave-docs-fg);
   }
 
+  /*
+   * ⚠️ IT ONLY APPEARS ONCE THERE IS SOMETHING TO GO BACK TO, AND NOTHING IN
+   * JAVASCRIPT DECIDES THAT.
+   *
+   * A scroll-driven animation, so scroll position alone drives it: no listener,
+   * no state, no re-render on every frame of a scroll, and it is right before
+   * hydration rather than after it. `toc` is the smallest client component this
+   * package ships — 900 bytes, and its budget note exists to keep it that way —
+   * so the alternative was to grow the one bundle that should never grow, in
+   * order to recompute a number the compositor already has.
+   *
+   * ⚠️ `root`, NOT `nearest`. Above 80rem `.wave-docs-layout__toc` is itself a
+   * scroll container (`overflow-y: auto`, so a long column of headings scrolls
+   * in place), and `nearest` resolves to it. The animation would then track how
+   * far the reader had scrolled the *table of contents*, which on almost every
+   * page never scrolls at all — an inactive timeline, and a link that never
+   * appears. Same shape as the `nearest`/`self` trap on the table shadow above,
+   * arrived at from the opposite direction.
+   *
+   * ⚠️ AND THE RULE ABOVE IS THE FALLBACK, WHICH IS WHY NOTHING HERE OVERRIDES
+   * IT. Three cases collapse into one: Firefox does not match this `@supports`
+   * yet; a page too short to scroll leaves the timeline inactive; and so does a
+   * host that scrolls an inner pane rather than the document. In all three the
+   * link is simply always present, exactly as it was before this block existed.
+   * Nothing hides a control on the strength of a feature the engine did not run.
+   *
+   * `dvh` rather than `px`: the link is redundant while the top of the document
+   * is still on screen, and "still on screen" is a fraction of the viewport
+   * rather than a constant. On a 900px window it fades in between 225px and
+   * 315px of scroll. `dvh` because this sheet uses no `vh` anywhere, and the
+   * reason it does not — the retracted mobile URL bar — costs nothing here: the
+   * column this link lives in is `display: none` below 80rem.
+   *
+   * No `prefers-reduced-motion` gate, deliberately. That setting is about things
+   * that move under a reader who did not ask them to; this is opacity, and the
+   * reader's own scrolling is its clock.
+   */
+  @supports (animation-timeline: scroll()) {
+    .wave-docs-toc__top {
+      animation-timeline: scroll(root block);
+      animation-timing-function: linear;
+      animation-fill-mode: both;
+      animation-name: wave-docs-toc-top-reveal;
+      animation-range: 25dvh 35dvh;
+    }
+  }
+
+  /*
+   * ⚠️ `visibility` KEEPS A LINK NOBODY CAN SEE OUT OF THE TAB ORDER, AND THE
+   * MIDDLE FRAME IS WHAT DECIDES WHEN IT REJOINS.
+   *
+   * `opacity` alone leaves a fully focusable, fully clickable link sitting
+   * invisibly at the foot of the rail: Tab reaches it and the focus ring is
+   * drawn around nothing.
+   *
+   * `visibility` interpolates as a step with one exception — across an interval
+   * where *either* endpoint is `visible` it is `visible` the whole way. Two
+   * frames would therefore flip it one pixel past the threshold and hand the
+   * link back to the tab order at an opacity of almost zero, which is the same
+   * defect a frame later. Two adjacent `hidden` frames have no `visible`
+   * endpoint between them, the exception does not apply, and the step lands at
+   * 60% — where the link is legible.
+   *
+   * That middle frame sits exactly on the linear ramp, so it changes the fade
+   * by nothing at all. Being the second `hidden` is its whole job.
+   */
+  @keyframes wave-docs-toc-top-reveal {
+    0% {
+      opacity: 0;
+      visibility: hidden;
+    }
+
+    60% {
+      opacity: 0.6;
+      visibility: hidden;
+    }
+
+    100% {
+      opacity: 1;
+      visibility: visible;
+    }
+  }
+
   .wave-docs-sidebar__external {
     /* Baseline-ish against the label, and never a flex item that grows. */
     margin-inline-start: 0.25rem;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@waveso/docs",
-  "version": "0.7.0",
+  "version": "0.7.1",
   "description": "Zero parser bytes in the browser: markdown docs for Next.js, built to hast in Node and rendered as your components",
   "type": "module",
   "sideEffects": [