@waveso/docs 0.7.1 → 0.9.0

package/dist/styles.css

@@ -1575,6 +1575,71 @@
     font-weight: 600;
   }
 
+  /*
+   * The row is `justify-content: space-between`, so the label has to claim the
+   * space or the icon and the text end up at opposite edges with a hole between
+   * them. `min-width: 0` because a long title in a 240px column must be allowed
+   * to shrink; without it the flex base is the text's min-content width and the
+   * row overflows instead of wrapping.
+   */
+  .wave-docs-sidebar__label,
+  .wave-docs-sidebar__group-title {
+    flex: 1 1 auto;
+    min-width: 0;
+  }
+
+  /*
+   * The type marker: a folder on a group, a page on a page.
+   *
+   * ⚠️ THE BOX IS DECLARED HERE, NOT LEFT TO THE SVG'S OWN WIDTH, because one
+   * of these has no SVG in it. An external link carries its mark at the far end
+   * of the row and needs no second one, so it gets an empty box — and an empty
+   * `<span>` with no size is a column where three labels start 24px left of
+   * every other label. Ragged is the defect this feature exists to remove.
+   */
+  .wave-docs-sidebar__icon {
+    flex: none;
+    inline-size: 1rem;
+    block-size: 1rem;
+    /*
+     * ⚠️ `inherit` AND `opacity`, NOT A COLOUR OF ITS OWN. A fixed grey put a
+     * bold group title next to a marker several steps lighter than it and a
+     * muted page title next to one barely lighter, so the column read as two
+     * different treatments. Fading whatever the row already is keeps one
+     * relationship at every weight — and it is the reason the active row's
+     * marker turns accent-blue with its label rather than staying grey.
+     */
+    color: inherit;
+    opacity: 0.4;
+  }
+
+  /*
+   * A host's own icon, in the column's box.
+   *
+   * `grid` rather than `block`: the component inside is theirs and may be any
+   * size, and a grid with `place-items: center` centres it in our 1rem square
+   * without needing it to fill one. `> *` caps it at the box so an icon
+   * authored at 24 does not push the row taller than every other row.
+   */
+  span.wave-docs-sidebar__icon {
+    display: grid;
+    place-items: center;
+  }
+
+  .wave-docs-sidebar__icon > * {
+    max-inline-size: 100%;
+    max-block-size: 100%;
+  }
+
+  /* Full strength the moment the row is the reader's own or under their
+   * pointer. A current page whose marker stayed faded reads as
+   * half-highlighted. */
+  .wave-docs-sidebar__link:hover .wave-docs-sidebar__icon,
+  .wave-docs-sidebar__group-button:hover .wave-docs-sidebar__icon,
+  .wave-docs-sidebar__link[aria-current='page'] .wave-docs-sidebar__icon {
+    opacity: 1;
+  }
+
   .wave-docs-sidebar__list:not([data-depth='0']) {
     margin-inline-start: 0.5rem;
     padding-inline-start: 0.5rem;
@@ -1646,11 +1711,55 @@
     color: var(--wave-docs-fg);
   }
 
+  /*
+   * The chevron points at the label it belongs to, not away from it.
+   *
+   * `.wave-docs-sidebar__group-header` is `justify-content: space-between`, so
+   * this sits flush against the navigation's inline end with the label at the
+   * other side of the row. The icon is Lucide's `chevron-right`, and unrotated
+   * it therefore aimed at the panel's border — at nothing. Worse than nothing,
+   * in fact: a chevron at the *trailing* edge of a row is the platform idiom
+   * for "this takes you somewhere else", so it read as navigation on a control
+   * that only opens a list in place.
+   *
+   * ⚠️ AND THAT IS WHY THERE IS A MIRROR RULE. `rotate` is physical — `180deg`
+   * is left in every writing mode — while everything else positioning this row
+   * is logical, so the header mirrors under `dir="rtl"` and a lone physical
+   * rotation does not. Mirrored, the chevron moves to the inline start with the
+   * label to its right, and 180deg would then point it out of the panel on the
+   * other side. `0deg` is what "at the label" means there.
+   *
+   * ⚠️ `[dir='rtl']`, AND NOT `:dir(rtl)`, WHICH IS THE SELECTOR FOR THIS JOB
+   * AND DOES NOT SURVIVE THE BUILD. Next compiles this sheet with lightningcss,
+   * which downlevels `:dir(rtl)` into a hardcoded list of right-to-left
+   * *languages*:
+   *
+   *   .wave-docs-sidebar__chevron:is(:lang(ae), :lang(ar), … :lang(yi))
+   *
+   * Direction is not language. Measured on the site with `<html dir="rtl"
+   * lang="en">`: `:dir(rtl)` matched the element, the rule was nowhere in the
+   * served stylesheet, and the chevron kept pointing out of the panel. It fails
+   * the other way too — `lang="ar" dir="ltr"` gets the mirror it did not ask
+   * for. The attribute selector is plain CSS 2.1, so no pipeline has an opinion
+   * about it, and it is what `rtl:` compiles to in every design system that
+   * ships one.
+   */
   .wave-docs-sidebar__chevron {
     flex: none;
     color: var(--wave-docs-fg-subtle);
+    rotate: 180deg;
   }
 
+  [dir='rtl'] .wave-docs-sidebar__chevron {
+    rotate: 0deg;
+  }
+
+  /*
+   * Open is down in both directions, so this needs no mirror — and it must
+   * come last, because the mirror above matches with the same specificity
+   * (0,2,0 either way) and would otherwise hold a mirrored open group pointing
+   * sideways.
+   */
   .wave-docs-sidebar__chevron[data-open] {
     rotate: 90deg;
   }
@@ -1673,6 +1782,35 @@
     .wave-docs-sidebar__chevron {
       transition: rotate 150ms ease-out;
     }
+
+    /*
+     * The row and its marker ease together, and the row is half of it.
+     *
+     * ⚠️ THE LINKS HAD NO TRANSITION AT ALL — the TOC's did, which is why this
+     * looked like an oversight only in the sidebar. Fading the marker alone
+     * would have been worse than fading nothing: the glyph would drift up to
+     * full strength while the surface under it snapped, so the two halves of
+     * one hover would visibly disagree.
+     *
+     * `background-color`, not `background`: the shorthand includes
+     * `background-image`, and naming it here would put this rule in the way of
+     * any consumer who paints one.
+     */
+    .wave-docs-sidebar__link,
+    .wave-docs-sidebar__group-button,
+    .wave-docs-sidebar__group-toggle {
+      transition:
+        background-color 150ms ease-out,
+        color 150ms ease-out;
+    }
+
+    /* `color` as well as `opacity`: the marker inherits its row's colour, and
+     * on the current page that is a jump from muted grey to accent blue. */
+    .wave-docs-sidebar__icon {
+      transition:
+        opacity 150ms ease-out,
+        color 150ms ease-out;
+    }
   }
 }
 
@@ -2685,14 +2823,30 @@
  * ------------------------------------------------------------------------ */
 
 @layer components {
+  /*
+   * ⚠️ THE INLINE PADDING AND THE GAP ARE THE NAVIGATION'S, NOT THIS BUTTON'S,
+   * AND THE `- 1px` IS THE WHOLE REASON THEY LOOK THE SAME.
+   *
+   * The trigger sits directly above the tree, so its magnifier is the first
+   * thing in the same column as every folder and page marker below it, and its
+   * label starts the same column as every title. Both were off — measured at
+   * 1280px, the glyph by 3px and the label by 11px — because this button was
+   * spaced as a standalone control: 10px of padding against the rows' 8px, and
+   * a 16px gap against their 8px.
+   *
+   * The rows carry no border and this does, so matching `0.5rem` outright would
+   * leave the glyph 1px out. `calc(0.5rem - 1px)` puts the *content* edge where
+   * theirs is, which is the edge a reader sees. Block padding is untouched: it
+   * sets this control's height, and nothing below it is the same height.
+   */
   .wave-docs-search-trigger {
     display: flex;
     align-items: center;
     justify-content: space-between;
-    gap: 1rem;
+    gap: 0.5rem;
     width: 100%;
     max-width: 20rem;
-    padding: 0.4375rem 0.625rem;
+    padding: 0.4375rem calc(0.5rem - 1px);
     border: 1px solid var(--wave-docs-border);
     border-radius: var(--wave-docs-radius);
     background: var(--wave-docs-bg-subtle);
@@ -2733,14 +2887,26 @@
     outline-offset: 2px;
   }
 
-  /* The label is the flexible half of the trigger; the shortcut hint beside it
-   * must never be the thing that gets squeezed out at narrow widths. */
+  /* The label is the flexible half of the trigger; neither the magnifier before
+   * it nor the shortcut hint after it may be the thing squeezed out at narrow
+   * widths. `flex: 1 1 auto` because the row is `space-between` and three
+   * items would otherwise centre the middle one, leaving a gap on both sides of
+   * a short label. */
   .wave-docs-search-trigger-label {
+    flex: 1 1 auto;
+    min-width: 0;
     overflow: hidden;
     text-overflow: ellipsis;
     white-space: nowrap;
   }
 
+  /* Quieter than the words either side of it, in the trigger and in the dialog
+   * alike — it is a category marker, not a control. */
+  .wave-docs-search-glyph {
+    flex: none;
+    color: var(--wave-docs-fg-subtle);
+  }
+
   /*
    * ⚠️ HIDDEN WHERE THE SHORTCUT CANNOT BE PRESSED, WHICH IS NOT A WIDTH
    * QUESTION. `⌘K` is an instruction, and on a phone or a tablet it is one the
@@ -2753,16 +2919,61 @@
     }
   }
 
-  .wave-docs-search-trigger-kbd {
+  .wave-docs-search-trigger-kbd,
+  .wave-docs-search-kbd {
     flex: none;
-    padding: 0.05rem 0.35rem;
-    border: 1px solid var(--wave-docs-border-strong);
-    border-radius: var(--wave-docs-radius-sm);
     color: var(--wave-docs-fg-subtle);
     font-family: var(--wave-docs-font-mono);
     font-size: 0.75rem;
   }
 
+  /*
+   * The footer's caps are drawn as keys; the trigger's shortcut is not.
+   *
+   * They were one rule, and the trigger's read as a chip on a surface that is
+   * already a chip — a bordered box inside a bordered box, sharing its fill,
+   * for a hint nobody clicks. The footer's caps sit on the flat bottom of the
+   * dialog and are the only thing there that has to look pressable.
+   *
+   * No `background` was ever set on either: the trigger's own
+   * `--wave-docs-bg-subtle` showed through, which is what made the border read
+   * as a filled shape. Removing the border is what removes the shape.
+   */
+  .wave-docs-search-kbd {
+    padding: 0.05rem 0.35rem;
+    border: 1px solid var(--wave-docs-border-strong);
+    border-radius: var(--wave-docs-radius-sm);
+  }
+
+  /*
+   * ⚠️ 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.
+   *
+   * `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;
+    /*
+     * ⚠️ AND IT HAS TO BE MOVED DOWN, WHICH `font-size` ALONE WILL NEVER DO.
+     *
+     * `⌘` is drawn around the font's mathematical axis, not standing on the
+     * baseline like a capital. Measured at this size: its ink runs from 11.24px
+     * above the baseline to 1.98px *above* it — a centre 6.61px up — while the
+     * `K` beside it runs 8.75px to 0, centred 4.38px up. Aligned by baseline,
+     * as inline text is, the symbol therefore floats 2.24px high.
+     *
+     * `-0.13em` of this element's own 17.4px is 2.26px, which puts the two ink
+     * centres within a rounding error of each other.
+     */
+    vertical-align: -0.13em;
+  }
+
   .wave-docs-search-backdrop {
     position: fixed;
     inset: 0;
@@ -2851,21 +3062,94 @@
     color: var(--wave-docs-fg-subtle);
   }
 
-  .wave-docs-search-close {
+  /*
+   * The keyboard footer.
+   *
+   * ⚠️ `flex: none`, BECAUSE THE LIST ABOVE IT IS `flex: 1 1 auto`. The dialog
+   * is a column with a ceiling, and the results are what takes the slack and
+   * scrolls; without this the footer is a second growable item and the two
+   * share the overflow — a footer that drifts down the dialog as results
+   * arrive, and a list that never quite reaches it.
+   */
+  .wave-docs-search-footer {
     flex: none;
-    padding: 0.3125rem 0.625rem;
-    border: 1px solid var(--wave-docs-border);
+    display: flex;
+    align-items: center;
+    gap: 1rem;
+    padding: 0.5rem 0.75rem;
+    border-block-start: 1px solid var(--wave-docs-border);
+    color: var(--wave-docs-fg-subtle);
+    font-size: 0.75rem;
+  }
+
+  .wave-docs-search-hint,
+  .wave-docs-search-close {
+    display: inline-flex;
+    align-items: center;
+    gap: 0.375rem;
+  }
+
+  /*
+   * ⚠️ A NEGATIVE MARGIN, BECAUSE `gap` CANNOT VARY PER PAIR. `↑` and `↓` are
+   * one instruction and read as one object; the gap that separates a cap from
+   * the word beside it is too wide between two caps that belong together. A
+   * flex container has a single gap, so the only ways to tighten one pair are
+   * an extra wrapper element or this — and a wrapper on every hint is markup
+   * bought for spacing.
+   *
+   * `-0.25rem` against the `0.375rem` above leaves `0.125rem` between them.
+   */
+  .wave-docs-search-kbd + .wave-docs-search-kbd {
+    margin-inline-start: -0.25rem;
+  }
+
+  /*
+   * The only cap holding a word rather than a glyph, and three letters at the
+   * arrows' size made it the loudest thing in the footer. `line-height` pins
+   * the box so it still sits at the same height as the caps beside it —
+   * without it the smaller text shrinks the content box and the cap rides
+   * high in a row of taller ones.
+   */
+  .wave-docs-search-close .wave-docs-search-kbd {
+    font-size: 0.625rem;
+    /* Solved, not guessed: the cap is 3.6px of border and padding plus its own
+     * line box, and the 12px caps beside it measure 17.6px. 10px x 1.4 = 14,
+     * and 14 + 3.6 is 17.6 — all four exactly the same height. */
+    line-height: 1.4;
+  }
+
+  /*
+   * ⚠️ HIDDEN WHERE THE KEY CANNOT BE PRESSED — the same query, and the same
+   * reason, as the trigger's `⌘K`. An instruction to press an arrow key is one
+   * a reader on a phone cannot follow, and a 10-inch tablet at 1024px would
+   * keep it under any width rule.
+   *
+   * The Close button beside them is deliberately NOT in here. It is the only
+   * pointer dismiss affordance in the dialog, and on exactly the devices this
+   * query names there is no Esc to fall back to.
+   */
+  @media (hover: none) and (pointer: coarse) {
+    .wave-docs-search-hint {
+      display: none;
+    }
+  }
+
+  /* Pushed to the far end, away from the two hints — the difference between a
+   * control and a caption, said with position. */
+  .wave-docs-search-close {
+    margin-inline-start: auto;
+    padding: 0.125rem 0.25rem;
+    border: 0;
     border-radius: var(--wave-docs-radius-sm);
     background: none;
     color: var(--wave-docs-fg-muted);
     font: inherit;
-    font-size: 0.8125rem;
+    font-size: 0.75rem;
     cursor: pointer;
   }
 
   .wave-docs-search-close:hover {
     color: var(--wave-docs-fg);
-    border-color: var(--wave-docs-border-strong);
   }
 
   /*

package/dist/types.d.ts

@@ -59,6 +59,20 @@ interface DocFrontmatter {
    * Lower sorts first; pages without an order sort last, alphabetically.
    */
   order?: number | undefined;
+  /**
+   * Sidebar marker for this page, as a name the *consumer* resolves.
+   *
+   * A name and not a component, because frontmatter is data: it is authored by
+   * whoever writes the page, in YAML, and cannot carry a React element. The
+   * host maps the name to their own icon via `DocsSidebar`'s `icons` prop, so
+   * the art belongs to whichever site is rendering — which is the only shape
+   * that serves a package mounted inside someone else's application.
+   *
+   * An unmapped name falls back to the default page marker rather than
+   * rendering nothing: a typo in one file should not knock a hole in the
+   * column.
+   */
+  icon?: string | undefined;
   /**
    * Calls to action, and the opt-in for the page's hero.
    *
@@ -122,6 +136,8 @@ interface DocNavPage {
   title: string;
   href: string;
   slug: string;
+  /** Marker name from the page's frontmatter. See {@link DocFrontmatter.icon}. */
+  icon?: string | undefined;
 }
 /**
  * A directory. `href` is present when the directory has an `index.md`, in
@@ -132,6 +148,8 @@ interface DocNavGroup {
   title: string;
   href?: string | undefined;
   children: DocNavNode[];
+  /** Marker name from the directory's `meta.json`. */
+  icon?: string | undefined;
 }
 /** A non-interactive heading between groups, from `"---Label---"` in meta.json. */
 interface DocNavSeparator {
@@ -144,6 +162,8 @@ interface DocNavLink {
   title: string;
   href: string;
   external: boolean;
+  /** Marker name from the `meta.json` entry that declared this link. */
+  icon?: string | undefined;
 }
 type DocNavNode = DocNavPage | DocNavGroup | DocNavSeparator | DocNavLink;
 /**
@@ -164,10 +184,17 @@ type DocNavNode = DocNavPage | DocNavGroup | DocNavSeparator | DocNavLink;
 interface DocsMeta {
   /** Directory title, shown as the group heading. Defaults to the dirname. */
   title?: string | undefined;
+  /**
+   * Sidebar marker for this directory, as a name the consumer resolves. See
+   * {@link DocFrontmatter.icon} — the same contract, declared where the
+   * directory is described rather than where a page is.
+   */
+  icon?: string | undefined;
   /** Ordered entries. Omit to sort by frontmatter `order`, then alphabetically. */
   pages?: Array<string | {
     title: string;
     href: string;
+    icon?: string | undefined;
   }> | undefined;
 }
 /**

package/package.json

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