@luziyang2026/dsh-question-nav 0.7.0 → 0.7.2

package/src/client/QuestionNavStrip.tsx

@@ -12,8 +12,13 @@
  * vertical cascade of question cards opens — the selected (center) card is the
  * focus (brand accent, elevated, full question text), the four neighbors are
  * narrower context cards clamped to fewer lines. Every card is clickable and
- * jumps to its question, exactly like clicking the dot; the rail auto-centers
- * the selected dot.
+ * jumps to its question, exactly like clicking the dot; the rail scrolls the
+ * selected dot into view only when it is clipped by the band's edges.
+ *
+ * Overflow is paged, not auto-scrolled: two small triangle buttons in the dot
+ * style sit above and below the dot queue (▲ / ▼), each click revealing five
+ * hidden dots. The native scrollbar stays hidden and the column fades at its
+ * edges as a pure visual cue — no hover auto-scroll.
  *
  * Data source: the host-folded `questionIndex` session projection (whole
  * history, persisted host-side, pushed live through session/projection
@@ -37,7 +42,7 @@ import type { QuestionEntry } from '../core/question-entry.ts'
 import { groupQuestionsByTurn, mergeLiveQuestions, type TurnDot } from '../core/turn-dots.ts'
 import type { AlignPreference } from '../core/align.ts'
 import type { JumpFailureCode } from '../core/jump.ts'
-import { EDGE_SCROLL_ZONE, FOCUS_RADIUS, edgeScrollSpeed, focusCardMetrics, focusScale, focusTier } from '../core/focus.ts'
+import { FOCUS_RADIUS, clampScrollTop, focusCardMetrics, focusScale, focusTier, minimalScrollIntoView, pageStep } from '../core/focus.ts'
 import { formatQuestionTime } from '../core/time.ts'
 import type { QuestionNavKey } from './locales.ts'
 import styles from './question-nav.module.css'
@@ -152,62 +157,31 @@ export function QuestionNavStrip(props: ComponentProps): React.JSX.Element | nul
   // Last focused dot key, so re-hovering the same dot after a gap re-centers it.
   const lastFocusedKeyRef = useRef<string | null>(null)
   // Whether the dot band overflows its 60% clamp (drives the edge-fade mask
-  // and the hover auto-scroll).
+  // and the ▲/▼ paging buttons).
   const [scrollable, setScrollable] = useState(false)
-  // Edge auto-scroll state: the fade zones at the band's top/bottom edges are
-  // scroll affordances — hovering them scrolls the band so the faded dots
-  // flow into the clear area. Speed follows how deep the pointer is inside
-  // the zone; a rAF loop applies it smoothly while it is non-zero.
-  const edgeScrollRef = useRef<{ speed: number; raf: number; last: number }>({ speed: 0, raf: 0, last: 0 })
-
-  const stopEdgeScroll = (): void => {
-    edgeScrollRef.current.speed = 0
-    if (edgeScrollRef.current.raf !== 0) {
-      cancelAnimationFrame(edgeScrollRef.current.raf)
-      edgeScrollRef.current.raf = 0
-    }
-  }
+  // Scroll offset of the band + its max offset: drives the ▲/▼ visibility
+  // (each direction hides once there is nothing more to reveal).
+  const [scrollPos, setScrollPos] = useState<{ top: number; max: number }>({ top: 0, max: 0 })
 
-  const edgeTick = (now: number): void => {
+  const syncScroll = (): void => {
     const list = listRef.current
-    const state = edgeScrollRef.current
-    state.raf = 0
-    if (list === null || state.speed === 0) return
-    const dt = Math.min(64, now - state.last) / 1000
-    state.last = now
-    const before = list.scrollTop
-    list.scrollTop = before + state.speed * dt
-    // Stop at the scroll bounds — there is nothing more to reveal.
-    const atTop = list.scrollTop <= 0 && state.speed < 0
-    const atBottom = list.scrollTop >= list.scrollHeight - list.clientHeight - 1 && state.speed > 0
-    if (atTop || atBottom) {
-      state.speed = 0
-      return
-    }
-    state.raf = requestAnimationFrame(edgeTick)
+    if (list === null) return
+    const max = Math.max(0, list.scrollHeight - list.clientHeight)
+    setScrollPos({ top: list.scrollTop, max })
   }
 
-  const onListMouseMove = (e: React.MouseEvent<HTMLDivElement>): void => {
+  // Page the band by one DOT_PAGE_ROWS click in the given direction.
+  const pageBy = (dir: 1 | -1): void => {
     const list = listRef.current
     if (list === null) return
-    const rect = list.getBoundingClientRect()
-    const y = e.clientY - rect.top
-    const depthTop = EDGE_SCROLL_ZONE - y
-    const depthBottom = y - (rect.height - EDGE_SCROLL_ZONE)
-    let speed = 0
-    if (depthTop > 0 && list.scrollTop > 0) {
-      speed = -edgeScrollSpeed(depthTop / EDGE_SCROLL_ZONE)
-    } else if (depthBottom > 0 && list.scrollTop < list.scrollHeight - list.clientHeight - 1) {
-      speed = edgeScrollSpeed(depthBottom / EDGE_SCROLL_ZONE)
-    }
-    const state = edgeScrollRef.current
-    state.speed = speed
-    if (speed !== 0 && state.raf === 0) {
-      state.last = performance.now()
-      state.raf = requestAnimationFrame(edgeTick)
-    }
+    const max = Math.max(0, list.scrollHeight - list.clientHeight)
+    list.scrollTop = clampScrollTop(list.scrollTop + dir * pageStep(), max)
+    syncScroll()
   }
 
+  const canPageUp = scrollable && scrollPos.top > 0
+  const canPageDown = scrollable && scrollPos.top < scrollPos.max
+
   // Focus persists briefly after leaving the rail, so the mouse can reach the
   // clickable cascade cards; entering a card cancels the clear, leaving
   // everything re-arms it.
@@ -383,9 +357,11 @@ export function QuestionNavStrip(props: ComponentProps): React.JSX.Element | nul
     }
   }, [visible, align])
 
-  // Keep the focused dot centered in the (≤60% tall, scrollable) band so its
-  // two neighbors on each side stay visible. Re-centers only when the focused
-  // key changes; scrolls instantly to avoid chasing a fast-moving hover.
+  // Keep the focused dot visible inside the (≤60% tall, scrollable) band:
+  // scroll only when the dot (plus room for its two magnified neighbors) is
+  // clipped by the band edges, and then only by the minimal amount — never
+  // re-center an already-visible dot, so browsing dot-by-dot doesn't shift
+  // the band under the pointer.
   useLayoutEffect(() => {
     const key = focus?.key ?? null
     if (lastFocusedKeyRef.current === key) return
@@ -395,18 +371,27 @@ export function QuestionNavStrip(props: ComponentProps): React.JSX.Element | nul
     if (list === null) return
     const target = list.querySelector<HTMLElement>('[data-question-nav-focused="true"]')
     if (target === null) return
-    const delta = target.offsetTop - list.offsetTop
-    const center = delta - (list.clientHeight - target.offsetHeight) / 2
-    list.scrollTop = Math.max(0, Math.min(center, list.scrollHeight - list.clientHeight))
+    const next = minimalScrollIntoView(
+      list.scrollTop,
+      list.clientHeight,
+      list.scrollHeight,
+      target.offsetTop - list.offsetTop,
+      target.offsetHeight,
+    )
+    if (next !== null) list.scrollTop = next
+    syncScroll()
   }, [focus])
 
-  // Detect band overflow: drives the edge-fade mask + hover auto-scroll.
+  // Detect band overflow: drives the edge-fade mask + the ▲/▼ paging buttons.
   // Re-checked when the dots change and whenever the band itself resizes
   // (the layout loop above clamps it to the conversation height).
   useLayoutEffect(() => {
     const list = listRef.current
     if (list === null) return
-    const check = (): void => setScrollable(list.scrollHeight > list.clientHeight + 1)
+    const check = (): void => {
+      setScrollable(list.scrollHeight > list.clientHeight + 1)
+      syncScroll()
+    }
     check()
     if (typeof ResizeObserver === 'undefined') return
     const observer = new ResizeObserver(check)
@@ -414,11 +399,10 @@ export function QuestionNavStrip(props: ComponentProps): React.JSX.Element | nul
     return () => observer.disconnect()
   }, [dots, align])
 
-  // Clear any pending timers and the edge auto-scroll on unmount.
+  // Clear any pending timers on unmount.
   useEffect(() => () => {
     if (hintTimerRef.current !== null) window.clearTimeout(hintTimerRef.current)
     if (clearFocusTimerRef.current !== null) window.clearTimeout(clearFocusTimerRef.current)
-    stopEdgeScroll()
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [])
 
@@ -460,43 +444,66 @@ export function QuestionNavStrip(props: ComponentProps): React.JSX.Element | nul
       className={align === 'right' ? `${styles.rail} ${styles.railRight}` : styles.rail}
       data-question-nav="rail"
     >
-      <div
-        ref={listRef}
-        className={scrollable ? `${styles.list} ${styles.listScrollable}` : styles.list}
-        onMouseMove={scrollable ? onListMouseMove : undefined}
-        onMouseLeave={() => {
-          stopEdgeScroll()
-          scheduleClearFocus()
-        }}
-      >
+      <div className={styles.queue}>
         {dots.length === 0 ? (
           <div className={styles.empty}>{t('strip.empty')}</div>
         ) : (
-          <div className={styles.dots}>
+          <>
             <span className={styles.count}>{dots.length}</span>
-            {dots.map((dot, index) => {
-              const isFocused = focus !== null && focus.key === dot.key
-              // Progressive magnification: selected largest, ±1 smaller, ±2
-              // smaller still, the rest base scale.
-              const tier = selectedIndex < 0 ? null : focusTier(index - selectedIndex)
-              const scale = jumpingKey === dot.key ? 1.6 : tier !== null ? focusScale(tier) : 1
-              const cls = [styles.dot]
-              if (isFocused) cls.push(styles.focused)
-              if (jumpingKey === dot.key) cls.push(styles.active)
-              return (
-                <button
-                  key={dot.key}
-                  className={cls.join(' ')}
-                  style={{ transform: `scale(${scale})` }}
-                  data-question-nav-focused={isFocused ? 'true' : undefined}
-                  data-question-nav-index={index}
-                  aria-label={dot.texts[0] ?? ''}
-                  onMouseEnter={(e) => openFocus(dot, e.currentTarget)}
-                  onClick={() => onJump(dot)}
-                />
-              )
-            })}
-          </div>
+            {scrollable ? (
+              <button
+                type="button"
+                className={`${styles.navBtn} ${styles.navUp}`}
+                aria-label={t('strip.up')}
+                style={{ visibility: canPageUp ? 'visible' : 'hidden' }}
+                onMouseEnter={cancelClearFocus}
+                onMouseLeave={scheduleClearFocus}
+                onClick={() => pageBy(-1)}
+              />
+            ) : null}
+            <div
+              ref={listRef}
+              className={scrollable ? `${styles.list} ${styles.listScrollable}` : styles.list}
+              onScroll={syncScroll}
+              onMouseLeave={scheduleClearFocus}
+            >
+              <div className={styles.dots}>
+                {dots.map((dot, index) => {
+                  const isFocused = focus !== null && focus.key === dot.key
+                  // Progressive magnification: selected largest, ±1 smaller, ±2
+                  // smaller still, the rest base scale.
+                  const tier = selectedIndex < 0 ? null : focusTier(index - selectedIndex)
+                  const scale = jumpingKey === dot.key ? 1.6 : tier !== null ? focusScale(tier) : 1
+                  const cls = [styles.dot]
+                  if (isFocused) cls.push(styles.focused)
+                  if (jumpingKey === dot.key) cls.push(styles.active)
+                  return (
+                    <button
+                      key={dot.key}
+                      className={cls.join(' ')}
+                      style={{ transform: `scale(${scale})` }}
+                      data-question-nav-focused={isFocused ? 'true' : undefined}
+                      data-question-nav-index={index}
+                      aria-label={dot.texts[0] ?? ''}
+                      onMouseEnter={(e) => openFocus(dot, e.currentTarget)}
+                      onClick={() => onJump(dot)}
+                    />
+                  )
+                })}
+              </div>
+            </div>
+            {scrollable ? (
+              <button
+                type="button"
+                className={`${styles.navBtn} ${styles.navDown}`}
+                aria-label={t('strip.down')}
+                style={{ visibility: canPageDown ? 'visible' : 'hidden' }}
+                onMouseEnter={cancelClearFocus}
+                onMouseLeave={scheduleClearFocus}
+                onClick={() => pageBy(1)}
+              />
+            ) : null}
+          </>
         )}
       </div>
       {hint !== null

package/src/client/locales.ts

@@ -4,6 +4,8 @@
  */
 export const zh = {
   'strip.empty': '本会话还没有提问',
+  'strip.up': '向上翻出 5 个提问圆点',
+  'strip.down': '向下翻出 5 个提问圆点',
   'jump.inactive': '聊天视图未激活',
   'jump.hidden': '目标无独立气泡，已定位到邻近内容',
   'jump.notfound': '目标未加载或不存在（可能已压缩）',
@@ -17,6 +19,8 @@ export const zh = {
 
 export const en = {
   'strip.empty': 'No questions in this session yet',
+  'strip.up': 'Reveal 5 question dots above',
+  'strip.down': 'Reveal 5 question dots below',
   'jump.inactive': 'Chat view is not active',
   'jump.hidden': 'No dedicated bubble; landed on nearby content',
   'jump.notfound': 'Target not loaded or missing (maybe compacted)',

package/src/client/question-nav.module.css

@@ -21,19 +21,34 @@
   left: auto;
 }
 
-/* Vertically center the dot column when it is short; when it is tall it is
-   clamped to at most 60% of the conversation height (auto margins center the
-   band) and scrolls from the top (auto margins collapse to 0 on overflow).
-   The band itself is interactive so wheel-scrolling works over the gaps too
-   (the rail above is pointer-events:none). The native scrollbar is always
-   hidden: this is a minimap scrolled by wheel/trackpad and by hovering the
-   fade zones, and overflow is signalled by the edge fade below. */
-.list {
+/* The paging queue: the fixed column (count + ▲, then the scrollable dot band,
+   then ▼) that replaces the edge-fade auto-scroll. Clamped to 60% of the
+   conversation height and vertically centered (auto margins); when the queue
+   overflows, only the middle dot band scrolls — the count and triangles stay
+   pinned. The wrapper stays pass-through; the band and triangles re-enable
+   pointer events. */
+.queue {
   flex: 0 1 auto;
   min-height: 0;
   max-height: 60%;
   margin: auto 0;
   width: 100%;
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 6px;
+  box-sizing: border-box;
+  pointer-events: none;
+}
+
+/* The middle dot band: the only scrollable part of the queue. Scrolls from the
+   top (overflow collapses the auto margins to 0). The native scrollbar is
+   always hidden: this is a minimap paged by the ▲/▼ buttons and by
+   wheel/trackpad, and overflow is signalled by the edge fade below. */
+.list {
+  flex: 1 1 auto;
+  min-height: 0;
+  width: 100%;
   overflow-y: auto;
   overflow-x: hidden;
   display: flex;
@@ -50,18 +65,12 @@
   display: none;
 }
 /* Overflowing band (applied from JS when scrollHeight > clientHeight): dots
-   fade out towards both edges, signalling "more beyond" without a scrollbar.
-   The fade zones double as hover auto-scroll areas (see QuestionNavStrip). */
+   fade out towards both edges — a pure visual cue for "more beyond" (the
+   paging triangles do the actual scrolling). */
 .listScrollable {
   -webkit-mask-image: linear-gradient(to bottom, transparent, black 22px, black calc(100% - 22px), transparent);
   mask-image: linear-gradient(to bottom, transparent, black 22px, black calc(100% - 22px), transparent);
 }
-.list > *:first-child {
-  margin-top: auto;
-}
-.list > *:last-child {
-  margin-bottom: auto;
-}
 
 .dot {
   flex: none;
@@ -97,7 +106,7 @@
   user-select: none;
 }
 
-/* The centered group: count + dot column, centered together (the list's auto
+/* The centered group: dot column, centered together (the list's auto
    margins center it when short; it scrolls as a unit when tall). */
 .dots {
   display: flex;
@@ -106,6 +115,46 @@
   gap: 6px;
 }
 
+/* Paging triangles (▲ above the dot queue, ▼ below), styled like the dots:
+   a plain triangle in the dot's quiet border color that lights up brand on
+   hover. Clicking pages the band by DOT_PAGE_ROWS dots. The triangle is a
+   pure CSS border triangle so it stays crisp at any DPI; the button box is a
+   slightly larger transparent hit target. */
+.navBtn {
+  flex: none;
+  pointer-events: auto;
+  width: 14px;
+  height: 12px;
+  padding: 0;
+  border: none;
+  background: transparent;
+  cursor: pointer;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+}
+.navBtn::before {
+  content: '';
+  display: block;
+  width: 0;
+  height: 0;
+  border-left: 5px solid transparent;
+  border-right: 5px solid transparent;
+  transition: border-color 120ms ease;
+}
+.navUp::before {
+  border-bottom: 7px solid var(--dsw-alias-border-l3);
+}
+.navDown::before {
+  border-top: 7px solid var(--dsw-alias-border-l3);
+}
+.navUp:hover::before {
+  border-bottom-color: var(--dsw-alias-brand-primary);
+}
+.navDown:hover::before {
+  border-top-color: var(--dsw-alias-brand-primary);
+}
+
 .empty {
   padding: 10px 4px;
   font-size: 11px;

package/src/core/focus.ts

@@ -75,22 +75,68 @@ export function magnificationWindow(total: number, selected: number, radius: num
   return out
 }
 
-/** Height (px) of the dot band's top/bottom fade zones, which double as hover
- *  auto-scroll areas (slightly larger than the 22px CSS mask fade). */
-export const EDGE_SCROLL_ZONE = 26
+/** Clearance (px) kept around the focused dot when scrolling it into view, so
+ *  its two magnified neighbors on each side stay inside the band's clear area
+ *  (2 dot rows ≈ 28px + the 22px fade zone). */
+export const FOCUS_NEIGHBOR_CLEARANCE = 50
 
-/** Edge auto-scroll speed range (px/s): MIN at the zone boundary, MAX at the
- *  very edge of the band. */
-export const EDGE_SCROLL_MIN_SPEED = 90
-export const EDGE_SCROLL_MAX_SPEED = 420
+/**
+ * Minimal "scroll into view" for the focused dot, in the spirit of
+ * scrollIntoView({ block: 'nearest' }): returns the scrollTop that brings the
+ * dot — plus `clearance` room for its magnified neighbors — inside the
+ * visible band with the smallest possible movement, or null when the dot is
+ * already fully visible. Unlike unconditional centering this never shifts the
+ * band while the user browses dot-by-dot: only a clipped dot is scrolled.
+ */
+export function minimalScrollIntoView(
+  scrollTop: number,
+  clientHeight: number,
+  scrollHeight: number,
+  dotTop: number,
+  dotHeight: number,
+  clearance: number = FOCUS_NEIGHBOR_CLEARANCE,
+): number | null {
+  const margin = Math.min(clearance, clientHeight / 4)
+  const viewTop = scrollTop + margin
+  const viewBottom = scrollTop + clientHeight - margin
+  if (dotTop >= viewTop && dotTop + dotHeight <= viewBottom) return null
+  const next = dotTop < viewTop
+    ? dotTop - margin
+    : dotTop + dotHeight + margin - clientHeight
+  return Math.max(0, Math.min(next, Math.max(0, scrollHeight - clientHeight)))
+}
 
 /**
- * Auto-scroll speed (px/s) for a pointer at `ratio` depth into an edge fade
- * zone (0 = at the zone boundary, 1 = at the band's very edge): eases
- * linearly from MIN to MAX so a shallow probe scrolls gently and pushing
- * into the edge moves fast. The sign (direction) is applied by the caller.
+ * Paging model for the dot band. Overflowing dots are not auto-scrolled by
+ * hovering the edges: instead the user pages them with two triangle buttons
+ * (▲ above the dot queue, ▼ below it), each click revealing `DOT_PAGE_ROWS`
+ * hidden dots. Pure arithmetic — no React, no DOM.
  */
-export function edgeScrollSpeed(ratio: number): number {
-  const r = Math.max(0, Math.min(1, ratio))
-  return EDGE_SCROLL_MIN_SPEED + (EDGE_SCROLL_MAX_SPEED - EDGE_SCROLL_MIN_SPEED) * r
+
+/** How many hidden dots one click of a paging triangle reveals. */
+export const DOT_PAGE_ROWS = 5
+
+/** Base dot diameter (px) and gap (px), matching the rail CSS — the paging
+ *  step is expressed in whole dot rows, so it tracks the visible geometry. */
+export const DOT_SIZE = 8
+export const DOT_GAP = 6
+
+/** Scroll step (px) for one paging click: `rows` whole dot rows. */
+export function pageStep(dotSize: number = DOT_SIZE, gap: number = DOT_GAP, rows: number = DOT_PAGE_ROWS): number {
+  return rows * (dotSize + gap)
+}
+
+/** Clamp a target scrollTop into the band's valid range (0..maxScroll). */
+export function clampScrollTop(target: number, maxScroll: number): number {
+  return Math.max(0, Math.min(target, Math.max(0, maxScroll)))
+}
+
+/** Whether hidden dots remain above the band (show ▲). */
+export function canScrollAbove(scrollTop: number): boolean {
+  return scrollTop > 0
+}
+
+/** Whether hidden dots remain below the band (show ▼). */
+export function canScrollBelow(scrollTop: number, maxScroll: number): boolean {
+  return scrollTop < maxScroll
 }