@waveso/docs 0.9.0 → 0.9.1

package/CHANGELOG.md

@@ -1,5 +1,72 @@
 # @waveso/docs
 
+## 0.9.1
+
+### Patch Changes
+
+- 80d3db4: The sidebar's handle and the search shortcut stop competing with the page.
+
+  **The handle is 16 × 56 and faded.** It was 20 × 80 at full strength — a solid
+  slab beside the reading column, for a control nobody looks at while reading. It
+  now sits at 40% until a pointer or a caret reaches it, the same treatment as the
+  tree's markers.
+
+  ⚠️ BOTH MARKS FADE, NOT THE PILL ALONE. Fading `::before` by itself leaves crisp
+  dots on a washed-out slab, which reads louder than the solid grip it replaced.
+
+  ⚠️ AND NOT ON THE `<button>`, which would take the focus ring down with it —
+  `opacity` applies to the whole element, outline included, so a keyboard reader
+  would get a 40% indicator on the control they had just moved to. It is on the
+  two pseudo-elements, and `:focus-visible` restores both.
+
+  ⚠️ THE TAP TARGET IS UNCHANGED BY ANY OF IT. The button is the whole strip and
+  runs the height of the column; the pill is paint. At 16px plus 4px of padding a
+  side the strip is 24px wide — WCAG 2.5.8's minimum to the pixel, and a test now
+  says so, because the next narrowing is the one that fails it.
+
+  ⚠️ THE DOTS DO NOT SCALE WITH THE PILL. They are `box-shadow` offsets on one
+  element, so they span 18px whatever the pill does. Found by shortening it to
+  16px tall and watching the outer two render outside it.
+
+  **`⌘K` is levelled with `Search`.** Equal `font-size` in two families is not
+  equal type: the label is `ui-sans-serif` and the badge `ui-monospace`, which
+  draws 0.7292px of cap per px. `1.012em` is what puts the `K`'s cap on the `S`'s.
+
+  ⚠️ AND THE SYMBOL IS `1.369em`, THE MEASURED INK RATIO — NOT A HAIR MORE. At
+  `1.45em` the `⌘` stood 6% above the cap line, and the badge read as _bigger
+  type_ than the label: 88 device px of ink against the word's 85, its top three
+  higher, its centre 1.5 out. Same letter height, louder cluster. At the ratio,
+  `Search` and `⌘K` measure 85 and 85 and share a centre to the device pixel.
+
+  ⚠️ AND `line-height: 0` ON THE SYMBOL, WHICH IS WHAT MADE THE TWO CENTRE. A line
+  box is as tall as the tallest inline box in it, so the 20.5px glyph made the
+  `<kbd>` 20.55px against the label's 17 — and flex centres them by their _boxes_,
+  so the `K` rode 1.9px high inside a box the symbol had stretched.
+
+  Also fixed: the focus-indicator test looked its selectors up with `indexOf`, so
+  `…:focus-visible` matched inside `…:focus-visible::before` — a different rule,
+  about pseudo-elements, with no business declaring an outline. It reported the
+  trigger as having no focus indicator while the trigger's own rule sat further
+  down the file declaring one.
+
+- 27f63ec: Sidebar separators keep the case their author wrote them in.
+
+  ⚠️ `text-transform: uppercase` ON A STRING THIS PACKAGE DOES NOT OWN. A
+  separator's text comes from a consumer's `meta.json` — `"---Reference---"` —
+  and restyling it is this package rewriting words in a language it cannot read.
+  Portuguese `Referência` shipped as `REFERÊNCIA`. Turkish trades its dotted and
+  dotless `i` for each other under a naive uppercase. No CJK script has a case to
+  transform at all, so those authors got the `letter-spacing` and none of the
+  effect it existed to rescue.
+
+  The string was already a prop. Its shape was not, and there was no way to turn
+  this off short of overriding the rule.
+
+  Reading as a divider rather than as another row is done by size, weight and a
+  subtle colour — none of which touch a character. `letter-spacing` goes with the
+  caps: it is there to make uppercase legible, and on sentence case it only reads
+  as loose.
+
 ## 0.9.0
 
 ### Minor Changes

package/dist/styles.css

@@ -153,7 +153,7 @@
      * of padding on every side — so setting this is the whole of resizing the
      * control, and the hit area grows with it rather than being a second number
      * to keep in step. */
-    --wave-docs-trigger-width: 1.25rem;
+    --wave-docs-trigger-width: 1rem;
     --wave-docs-toc-width: 15rem;
 
     /*
@@ -1768,14 +1768,28 @@
     margin-block: 1rem 0.25rem;
   }
 
+  /*
+   * ⚠️ NO `text-transform: uppercase`, AND IT USED TO HAVE ONE.
+   *
+   * A separator's text is authored — `"---Reference---"` in someone's
+   * `meta.json` — so uppercasing it is this package rewriting words it does not
+   * own, in a language it cannot read. Portuguese `Referência` came out as
+   * `REFERÊNCIA`; Turkish loses the dotted and dotless `i` to each other, and
+   * no CJK script has a case to transform at all, so those authors got the
+   * `letter-spacing` and none of the effect it was there to rescue. And it
+   * could not be turned off — the string is a prop, but its shape was ours.
+   *
+   * The job the caps were doing — read as a divider, not as a row — is already
+   * done by the size, the weight and the subtle colour, none of which touch a
+   * single character. `letter-spacing` went with them: it exists to make caps
+   * legible, and on sentence case it only reads as loose.
+   */
   .wave-docs-sidebar__separator {
     display: block;
     padding-inline: 0.5rem;
     color: var(--wave-docs-fg-subtle);
     font-size: 0.75rem;
     font-weight: 650;
-    letter-spacing: 0.06em;
-    text-transform: uppercase;
   }
 
   @media (prefers-reduced-motion: no-preference) {
@@ -2607,7 +2621,12 @@
   .wave-docs-layout__sidebar-trigger::before {
     content: '';
     width: var(--wave-docs-trigger-width);
-    height: 5rem;
+    /*
+     * 16 x 56 — a 3.5:1 grip. It was 20 x 80, which at the old width read as a
+     * slab; narrowing it made the length obvious. The floor is 18px, the span
+     * of the three dots, and nothing here scales with the pill: see `::after`.
+     */
+    height: 3.5rem;
     border-radius: var(--wave-docs-radius-sm);
     background-color: var(--wave-docs-border-strong);
   }
@@ -2631,11 +2650,46 @@
     translate: -50% -50%;
     border-radius: 50%;
     background: currentcolor;
+    /*
+     * ⚠️ THE DOTS DO NOT SCALE WITH THE PILL. They are `box-shadow` offsets on
+     * one element, so ±7px is 18px of ink whatever `--wave-docs-trigger-width`
+     * or the pill's height happen to be. Shorten the pill below 18px and the
+     * outer two sit outside it, top and bottom — measured, not guessed.
+     */
     box-shadow:
       0 -7px 0 currentcolor,
       0 7px 0 currentcolor;
   }
 
+  /*
+   * Faded at rest, full strength under a pointer or a caret — the same
+   * treatment as the tree's markers, and for the same reason: this is a handle,
+   * not a thing to look at while reading.
+   *
+   * ⚠️ BOTH MARKS, NOT THE PILL ALONE. Fading `::before` by itself leaves the
+   * dots at full strength on a washed-out slab, which reads louder than the
+   * solid grip it replaced — the opposite of the point.
+   *
+   * ⚠️ AND NOT ON THE BUTTON ITSELF, which would take the focus ring down with
+   * it: `opacity` applies to the whole element, outline included, so a keyboard
+   * reader would get a 40% indicator on a control they had just moved to.
+   *
+   * ⚠️ THE TAP TARGET IS UNTOUCHED BY ANY OF THIS. The `<button>` is the entire
+   * strip and runs the height of the column; the pill is paint. Its 80px was
+   * only ever ink, which is why 32px costs nothing a finger can feel.
+   */
+  .wave-docs-layout__sidebar-trigger::before,
+  .wave-docs-layout__sidebar-trigger::after {
+    opacity: 0.4;
+  }
+
+  .wave-docs-layout__sidebar-trigger:hover::before,
+  .wave-docs-layout__sidebar-trigger:hover::after,
+  .wave-docs-layout__sidebar-trigger:focus-visible::before,
+  .wave-docs-layout__sidebar-trigger:focus-visible::after {
+    opacity: 1;
+  }
+
   /*
    * ⚠️ THE STRIP'S HOVER LIGHTS THE BUTTON TOO, AND THAT IS WHAT MAKES IT ONE
    * CONTROL. Hovering 44px of strip while the button inside it stays grey reads
@@ -2667,7 +2721,8 @@
        */
       transition:
         background-color 120ms ease-out,
-        color 120ms ease-out;
+        color 120ms ease-out,
+        opacity 120ms ease-out;
     }
   }
 
@@ -2945,20 +3000,64 @@
     border-radius: var(--wave-docs-radius-sm);
   }
 
+  /*
+   * ⚠️ THE LABEL'S SIZE, AND IT IS THE CAPS THAT HAD TO MATCH — NOT THE NUMBER.
+   *
+   * `Search` is `ui-sans-serif` and this is `ui-monospace`, and the same
+   * `font-size` in two families does not give you the same letter. Measured at
+   * 14px: the label's `S` carries 10.33px of ink and the mono `K` carries
+   * 10.21px. A tenth of a pixel — invisible until you look, and then it is the
+   * only thing you can see.
+   *
+   * `1.012em` is that tenth. Mono here draws 0.7292px of cap per px of
+   * `font-size`, so 10.33px of cap needs 14.17px, which is 1.012 x the 14px it
+   * sits beside. `em` rather than a `rem` constant so it tracks the label if
+   * the trigger's size ever moves.
+   *
+   * ⚠️ IT IS A MEASURED CONSTANT AND IT BELONGS TO THESE TWO FAMILIES. Change
+   * `--wave-docs-font-mono` or `--wave-docs-font-sans` and it is wrong — not
+   * broken, just quietly a tenth of a pixel out again. Re-measure the caps, do
+   * not re-derive from the declaration.
+   *
+   * Not in the shared rule above: the footer's caps sit in a 12px footer and
+   * belong at 12px. This is the only `<kbd>` standing beside body-sized text.
+   */
+  .wave-docs-search-trigger-kbd {
+    font-size: 1.012em;
+  }
+
   /*
    * ⚠️ THE SYMBOL IS SCALED AND THE WORD IS NOT — which is why this is a
    * separate element rather than one string in the `<kbd>`.
    *
-   * Measured in the shipped mono stack at 12px: `⌘` has 6.39px of ink against
-   * `K`'s 8.75px, so at a shared size it sits a third short of the letter next
-   * to it. `1.35em` is that ratio, and it makes the two read as one mark.
+   * Measured in the shipped mono stack: `⌘` carries 6.39px of ink per 8.75px of
+   * `K`, so at a shared `font-size` it sits a third short of the letter next to
+   * it. `1.369em` is exactly that ratio, and it makes the two the same height.
+   *
+   * ⚠️ NOT A HAIR TALLER, WHICH IS WHERE THIS FIRST LANDED. `1.45em` gave the
+   * symbol 6% on the `K` — invisible at 12px, and at this size 0.6px of ink
+   * standing above the cap line. It made the whole badge read as *bigger type*
+   * than the label beside it: measured against the word `Search`, 88 device px
+   * of ink against 85, its top three device px higher and its centre 1.5 out.
+   * Same letter height, louder cluster. The eye compares the clusters.
    *
    * `Ctrl` gets none of it: it is a word set in the same face as the `K`, and
    * scaling it would make the hint shout.
    */
   .wave-docs-search-trigger-mod[data-symbol] {
-    font-size: 1.45em;
-    line-height: 1;
+    font-size: 1.369em;
+    /*
+     * ⚠️ `0`, NOT `1` — THIS GLYPH MUST NOT SIZE THE LINE IT SITS ON. A line
+     * box is as tall as the tallest inline box in it, so at `line-height: 1`
+     * this 20.5px symbol made the `<kbd>` 20.55px tall against the label's 17,
+     * and the two were centred as flex items by their *boxes*. Same cap height,
+     * 1.9px apart on screen — measured off an 8x render, invisible in the CSS.
+     *
+     * At `0` the symbol contributes no height, the `<kbd>` keeps the line box
+     * its own font gives it, and the `K` centres with the `S` beside it. The
+     * glyph still paints in full: `line-height` bounds the line, not the ink.
+     */
+    line-height: 0;
     /*
      * ⚠️ AND IT HAS TO BE MOVED DOWN, WHICH `font-size` ALONE WILL NEVER DO.
      *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@waveso/docs",
-  "version": "0.9.0",
+  "version": "0.9.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": [