From 7e07573026bccd4b489f4ba17f953145af1bf147 Mon Sep 17 00:00:00 2001 From: Orkuncakilkaya Date: Sat, 5 Sep 2026 14:41:10 +0300 Subject: [PATCH] fix(docs): restore the token cards on the generated site MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Clicking a keyword, type, builtin or namespace method in a code sample is supposed to open a summary card for it. The script that builds those cards never went away; its stylesheet did. The site redesign split item.css into base.css and docs.css and filed the card chrome — .hovercard, .hc-*, .tok, .kind-badge — under docs.css. Only the four reference page kinds link that file. The landing page links base.css and site.css, so a click there appended an unstyled, position:static div to the end of the document: built, filled with the right text, and invisible. The card chrome now sits in base.css beside the .t-* token colours it belongs with, which every page links. It is also position:fixed rather than absolute, matching the viewport coordinates positionCard() reads out of getBoundingClientRect() — absolute put the card an entire scroll offset away from its token on any reference page read past the fold. Co-Authored-By: Claude Opus 5 --- changes/docs-token-cards.md | 10 ++++++++ tools/docgen/assets/base.css | 47 ++++++++++++++++++++++++++++++++++++ tools/docgen/assets/docs.css | 38 ++--------------------------- 3 files changed, 59 insertions(+), 36 deletions(-) create mode 100644 changes/docs-token-cards.md diff --git a/changes/docs-token-cards.md b/changes/docs-token-cards.md new file mode 100644 index 00000000..9f9db53f --- /dev/null +++ b/changes/docs-token-cards.md @@ -0,0 +1,10 @@ +bump: patch +type: fix +**Token cards are back on the docs site.** Clicking a keyword, type, builtin or +namespace method in any code sample opens its summary card again. The card's +styling had been left behind in `docs.css` during the site redesign, so on the +landing page — which links only `base.css` and `site.css` — the card rendered +unstyled at the foot of the document instead of beside the token. It now lives +in `base.css` with the rest of the highlighter chrome, and is positioned +`fixed`, matching the viewport coordinates the script computes, so a card opened +on a scrolled reference page lands on its token rather than off it. diff --git a/tools/docgen/assets/base.css b/tools/docgen/assets/base.css index 186e6811..bd94c7f1 100644 --- a/tools/docgen/assets/base.css +++ b/tools/docgen/assets/base.css @@ -155,6 +155,53 @@ pre::-webkit-scrollbar-thumb { background: var(--rule-2); border-radius: 5px } .t-punc { color: var(--c-punc) } .t-arg { color: var(--c-arg) } +/* ---------- token cards ------------------------------------------------- * + * Every page runs the highlighter, so the card chrome lives here rather than + * in docs.css — the landing page links base.css and site.css only, and a card + * whose stylesheet never loaded renders as a static block at the end of the + * body instead of a panel beside the token that was clicked. + * ----------------------------------------------------------------------- */ + +.tok { cursor: help; border-bottom: 1px dotted var(--rule-2) } +a.tok { cursor: pointer } + +.hovercard { + /* the script positions this from getBoundingClientRect(), i.e. in viewport + coordinates, so the card must be fixed, not absolute */ + position: fixed; + z-index: 90; + max-width: min(360px, calc(100vw - 24px)); + background: var(--panel); + border: 1px solid var(--rule-2); + border-radius: var(--radius); + box-shadow: 0 8px 24px -12px rgba(0, 0, 0, .35); + padding: 11px 13px; + font-size: 13.5px; + cursor: pointer; +} +.hovercard:hover { border-color: var(--accent) } +.hc-top { display: flex; align-items: center; gap: 9px; margin-bottom: 6px } +.hc-name { font-family: var(--mono); font-size: 13.5px; color: var(--ink) } +.hc-sig { font-family: var(--mono); font-size: 12.5px; color: var(--muted); display: block; margin-bottom: 6px } +.hc-tip { color: var(--ink-2) } +.hc-foot { display: block; margin-top: 8px; font-size: 12px; color: var(--muted) } + +/* the kind badge is worn both by a card and by a reference page's title */ +.kind-badge { + font-family: var(--mono); + font-size: 11px; + letter-spacing: 0.06em; + text-transform: uppercase; + color: var(--muted); + border: 1px solid var(--rule-2); + border-radius: 3px; + padding: 2px 7px; + white-space: nowrap; +} +/* the accent is the only colour that distinguishes a kind, and only for the + two that are structural rather than callable */ +.kind-namespace, .kind-keyword { color: var(--accent); border-color: var(--accent) } + /* ---------- header ---------- */ header.nav { diff --git a/tools/docgen/assets/docs.css b/tools/docgen/assets/docs.css index d8368ed0..ca664822 100644 --- a/tools/docgen/assets/docs.css +++ b/tools/docgen/assets/docs.css @@ -32,21 +32,6 @@ main { padding: 34px 0 0 } word-break: break-word; } -.kind-badge { - font-family: var(--mono); - font-size: 11px; - letter-spacing: 0.06em; - text-transform: uppercase; - color: var(--muted); - border: 1px solid var(--rule-2); - border-radius: 3px; - padding: 2px 7px; - white-space: nowrap; -} -/* the accent is the only colour that distinguishes a kind, and only for the - two that are structural rather than callable */ -.kind-namespace, .kind-keyword { color: var(--accent); border-color: var(--accent) } - .sig { display: block; margin: 18px 0 0; @@ -213,27 +198,8 @@ main { padding: 34px 0 0 } .idx-item code { font-size: 13.5px; color: var(--c-fn) } .idx-item span { color: var(--muted); font-size: 13.5px } -/* ---------- hover cards + deep-link flash (from ludic-highlight.js) ------- */ - -.tok { cursor: help; border-bottom: 1px dotted var(--rule-2) } -a.tok { cursor: pointer } - -.hovercard { - position: absolute; - z-index: 90; - max-width: 360px; - background: var(--panel); - border: 1px solid var(--rule-2); - border-radius: var(--radius); - box-shadow: 0 8px 24px -12px rgba(0, 0, 0, .35); - padding: 11px 13px; - font-size: 13.5px; -} -.hc-top { display: flex; align-items: center; gap: 9px; margin-bottom: 6px } -.hc-name { font-family: var(--mono); font-size: 13.5px; color: var(--ink) } -.hc-sig { font-family: var(--mono); font-size: 12.5px; color: var(--muted); display: block; margin-bottom: 6px } -.hc-tip { color: var(--ink-2) } -.hc-foot { display: block; margin-top: 8px; font-size: 12px; color: var(--muted) } +/* ---------- deep-link flash (from ludic-highlight.js) -------------------- * + * The token cards themselves are styled in base.css, which every page links. */ :target { scroll-margin-top: calc(var(--hdr) + 16px) } .flash { animation: flash 1.1s ease-out }