@luziyang2026/dsh-question-nav 0.7.2 → 0.7.4

package/src/client/settings.ts

@@ -1,13 +1,14 @@
 /**
  * Browser mirror of the `question-nav` settings namespace: reads the rail
- * anchor edge from the settings scope (`ctx.settingsScope.bind`) and routes
- * the user's choice back through `scope.set`. The namespace itself is
- * registered by the host half (src/settings.ts).
+ * anchor edge and the ▲/▼ page size from the settings scope
+ * (`ctx.settingsScope.bind`) and routes the user's choices back through
+ * `scope.set`. The namespace itself is registered by the host half
+ * (src/settings.ts).
  *
  * The settings surface is optional and may apply after this plugin, so the
- * controller starts unbound and degrades to the default alignment until
- * {@link attach} binds the scope (called from a fiber that injects
- * `settingsScope`). The plugin keeps working everywhere it already did.
+ * controller starts unbound and degrades to the defaults until {@link attach}
+ * binds the scope (called from a fiber that injects `settingsScope`). The
+ * plugin keeps working everywhere it already did.
  *
  * @module dsh-question-nav/client/settings
  */
@@ -17,12 +18,21 @@ import {
   ALIGN_FIELD, ALIGN_OPTIONS, DEFAULT_ALIGN, QUESTION_NAV_SETTINGS_NS,
   type AlignPreference,
 } from '../core/align.ts'
+import {
+  DEFAULT_PAGE_SIZE, PAGE_SIZE_FIELD, PAGE_SIZE_OPTIONS,
+  type PageSize,
+} from '../core/page-size.ts'
 
-/** Narrow a raw section to the anchor field. */
+/** Narrow a raw section value to the anchor field. */
 function isAlignPreference(value: unknown): value is AlignPreference {
   return ALIGN_OPTIONS.some((option) => option === value)
 }
 
+/** Narrow a raw section value to the page-size field. */
+function isPageSize(value: unknown): value is PageSize {
+  return (PAGE_SIZE_OPTIONS as readonly unknown[]).includes(value)
+}
+
 /** The minimal face of the settings scope service this controller needs.
  * Kept structural (bind only) so the controller stays decoupled from the
  * full service and is unit-testable with a stub binder. */
@@ -30,15 +40,18 @@ export interface SettingsScopeBinderLike {
   bind<T>(spec: SettingsScopeSpec<T>): SettingsScope<T>
 }
 
-/** Wire section this plugin owns (the Host schema's `align` field). */
+/** Wire section this plugin owns (the Host schema's fields). */
 interface QuestionNavSection {
   align?: unknown
+  pageSize?: unknown
 }
 
-/** Snapshot consumed by the strip and the settings row. */
+/** Snapshot consumed by the strip and the settings rows. */
 export interface QuestionNavSettingsState {
   /** Last accepted anchor edge (default while the scope is absent/loading). */
   align: AlignPreference
+  /** Last accepted page size (default while the scope is absent/loading). */
+  pageSize: PageSize
   /** Whether the user layer overrides the composition default. */
   overridden: boolean
 }
@@ -48,7 +61,7 @@ export class QuestionNavSettingsController {
   private scope: SettingsScope<QuestionNavSection> | undefined
   private readonly listeners = new Set<() => void>()
   private unsubscribe: () => void = () => {}
-  private state: QuestionNavSettingsState = { align: DEFAULT_ALIGN, overridden: false }
+  private state: QuestionNavSettingsState = { align: DEFAULT_ALIGN, pageSize: DEFAULT_PAGE_SIZE, overridden: false }
 
   /**
    * Bind the namespace scope once the settings surface is present. Called
@@ -64,19 +77,23 @@ export class QuestionNavSettingsController {
     this.unsubscribe = this.scope.subscribe(() => {
       if (this.scope === undefined) return
       const next = this.derive(this.scope.getSnapshot())
-      if (next.align === this.state.align && next.overridden === this.state.overridden) return
+      if (next.align === this.state.align && next.pageSize === this.state.pageSize
+        && next.overridden === this.state.overridden) return
       this.state = next
       for (const listener of this.listeners) listener()
     })
   }
 
   private derive(snapshot: SettingsScopeSnapshot<QuestionNavSection>): QuestionNavSettingsState {
-    const user = snapshot.user as { align?: unknown } | undefined
+    const user = snapshot.user as QuestionNavSection | undefined
     return {
       align: snapshot.status === 'ready' && isAlignPreference(snapshot.value?.align)
         ? snapshot.value.align
         : DEFAULT_ALIGN,
-      overridden: user !== undefined && user.align !== undefined,
+      pageSize: snapshot.status === 'ready' && isPageSize(snapshot.value?.pageSize)
+        ? snapshot.value.pageSize
+        : DEFAULT_PAGE_SIZE,
+      overridden: user !== undefined && (user.align !== undefined || user.pageSize !== undefined),
     }
   }
 
@@ -102,4 +119,10 @@ export class QuestionNavSettingsController {
     if (this.scope === undefined) return
     void this.scope.set(ALIGN_FIELD, align)
   }
+
+  /** Route the user's page-size choice to the Host document. */
+  setPageSize(pageSize: PageSize): void {
+    if (this.scope === undefined) return
+    void this.scope.set(PAGE_SIZE_FIELD, pageSize)
+  }
 }

package/src/core/focus.ts

@@ -75,42 +75,11 @@ export function magnificationWindow(total: number, selected: number, radius: num
   return out
 }
 
-/** 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
-
-/**
- * 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)))
-}
-
 /**
  * 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.
+ * hovering the edges or hovering a clipped dot: 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.
  */
 
 /** How many hidden dots one click of a paging triangle reveals. */

package/src/core/page-size.ts

@@ -0,0 +1,20 @@
+/**
+ * Page-size constants for the ▲/▼ paging buttons, shared by the host schema
+ * and the browser settings scope. Pure data: no DSH imports, so the client
+ * bundle may inline this module (a Host import here would leak into the
+ * browser half).
+ *
+ * @module dsh-question-nav/page-size
+ */
+
+/** Selectable page sizes: how many hidden dots one ▲/▼ click reveals. */
+export const PAGE_SIZE_OPTIONS = [3, 5, 8, 10] as const
+
+/** Page-size preference (dots revealed per paging-button click). */
+export type PageSize = typeof PAGE_SIZE_OPTIONS[number]
+
+/** Default page size when the user-settings document has no override. */
+export const DEFAULT_PAGE_SIZE: PageSize = 5
+
+/** Field carrying the selected page size. */
+export const PAGE_SIZE_FIELD = 'pageSize'

package/src/settings.ts

@@ -1,9 +1,10 @@
 /**
  * Host-side durable settings for the question-nav plugin, registered into the
- * DSH user-settings document. Currently one field: which edge of the
- * conversation column the rail anchors to (`align`). The browser half reads
- * the same namespace through the settings scope (`ctx.settingsScope.bind`)
- * and routes the user's choice back through `scope.set`.
+ * DSH user-settings document. Two fields: which edge of the conversation
+ * column the rail anchors to (`align`) and how many hidden dots one ▲/▼
+ * paging-button click reveals (`pageSize`). The browser half reads the same
+ * namespace through the settings scope (`ctx.settingsScope.bind`) and routes
+ * the user's choice back through `scope.set`.
  *
  * @module dsh-question-nav/settings
  */
@@ -14,16 +15,23 @@ import {
   ALIGN_FIELD, ALIGN_OPTIONS, DEFAULT_ALIGN, QUESTION_NAV_SETTINGS_NS,
   type AlignPreference,
 } from './core/align.ts'
+import {
+  DEFAULT_PAGE_SIZE, PAGE_SIZE_FIELD, PAGE_SIZE_OPTIONS,
+  type PageSize,
+} from './core/page-size.ts'
 
 /** Durable settings section shared by the Host schema and the browser scope. */
 export interface QuestionNavSettings {
   /** Anchor edge of the rail. */
   align: AlignPreference
+  /** Dots revealed per ▲/▼ paging-button click. */
+  pageSize: PageSize
 }
 
 /** Durable settings schema; also the wire envelope the browser scope validates against. */
 export const QuestionNavSettingsSchema: z<QuestionNavSettings> = z.object({
   [ALIGN_FIELD]: z.union([...ALIGN_OPTIONS]).default(DEFAULT_ALIGN),
+  [PAGE_SIZE_FIELD]: z.union([...PAGE_SIZE_OPTIONS]).default(DEFAULT_PAGE_SIZE),
 })
 
 /** The settings namespace this plugin owns, branded for the Host registry.