feat: 第一个可以用的 ink 组件抽象 (#158)

packages/@ant/ink/src/components/ScrollBox.tsx

@@ -0,0 +1,257 @@
+import React, {
+  type PropsWithChildren,
+  type Ref,
+  useImperativeHandle,
+  useRef,
+  useState,
+} from 'react'
+import type { Except } from 'type-fest'
+import type { DOMElement } from '../core/dom.js'
+import { markDirty, scheduleRenderFrom } from '../core/dom.js'
+import { markCommitStart } from '../core/reconciler.js'
+import type { Styles } from '../core/styles.js'
+import Box from './Box.js'
+
+export type ScrollBoxHandle = {
+  scrollTo: (y: number) => void
+  scrollBy: (dy: number) => void
+  /**
+   * Scroll so `el`'s top is at the viewport top (plus `offset`). Unlike
+   * scrollTo which bakes a number that's stale by the time the throttled
+   * render fires, this defers the position read to render time —
+   * render-node-to-output reads `el.yogaNode.getComputedTop()` in the
+   * SAME Yoga pass that computes scrollHeight. Deterministic. One-shot.
+   */
+  scrollToElement: (el: DOMElement, offset?: number) => void
+  scrollToBottom: () => void
+  getScrollTop: () => number
+  getPendingDelta: () => number
+  getScrollHeight: () => number
+  /**
+   * Like getScrollHeight, but reads Yoga directly instead of the cached
+   * value written by render-node-to-output (throttled, up to 16ms stale).
+   * Use when you need a fresh value in useLayoutEffect after a React commit
+   * that grew content. Slightly more expensive (native Yoga call).
+   */
+  getFreshScrollHeight: () => number
+  getViewportHeight: () => number
+  /**
+   * Absolute screen-buffer row of the first visible content line (inside
+   * padding). Used for drag-to-scroll edge detection.
+   */
+  getViewportTop: () => number
+  /**
+   * True when scroll is pinned to the bottom. Set by scrollToBottom, the
+   * initial stickyScroll attribute, and by the renderer when positional
+   * follow fires (scrollTop at prevMax, content grows). Cleared by
+   * scrollTo/scrollBy. Stable signal for "at bottom" that doesn't depend on
+   * layout values (unlike scrollTop+viewportH >= scrollHeight).
+   */
+  isSticky: () => boolean
+  /**
+   * Subscribe to imperative scroll changes (scrollTo/scrollBy/scrollToBottom).
+   * Does NOT fire for stickyScroll updates done by the Ink renderer — those
+   * happen during Ink's render phase after React has committed. Callers that
+   * care about the sticky case should treat "at bottom" as a fallback.
+   */
+  subscribe: (listener: () => void) => () => void
+  /**
+   * Set the render-time scrollTop clamp to the currently-mounted children's
+   * coverage span. Called by useVirtualScroll after computing its range;
+   * render-node-to-output clamps scrollTop to [min, max] so burst scrollTo
+   * calls that race past React's async re-render show the edge of mounted
+   * content instead of blank spacer. Pass undefined to disable (sticky,
+   * cold start).
+   */
+  setClampBounds: (min: number | undefined, max: number | undefined) => void
+}
+
+export type ScrollBoxProps = Except<
+  Styles,
+  'textWrap' | 'overflow' | 'overflowX' | 'overflowY'
+> & {
+  ref?: Ref<ScrollBoxHandle>
+  /**
+   * When true, automatically pins scroll position to the bottom when content
+   * grows. Unset manually via scrollTo/scrollBy to break the stickiness.
+   */
+  stickyScroll?: boolean
+}
+
+/**
+ * A Box with `overflow: scroll` and an imperative scroll API.
+ *
+ * Children are laid out at their full Yoga-computed height inside a
+ * constrained container. At render time, only children intersecting the
+ * visible window (scrollTop..scrollTop+height) are rendered (viewport
+ * culling). Content is translated by -scrollTop and clipped to the box bounds.
+ *
+ * Works best inside a fullscreen (constrained-height root) Ink tree.
+ */
+function ScrollBox({
+  children,
+  ref,
+  stickyScroll,
+  ...style
+}: PropsWithChildren<ScrollBoxProps>): React.ReactNode {
+  const domRef = useRef<DOMElement>(null)
+  // scrollTo/scrollBy bypass React: they mutate scrollTop on the DOM node,
+  // mark it dirty, and call the root's throttled scheduleRender directly.
+  // The Ink renderer reads scrollTop from the node — no React state needed,
+  // no reconciler overhead per wheel event. The microtask defer coalesces
+  // multiple scrollBy calls in one input batch (discreteUpdates) into one
+  // render — otherwise scheduleRender's leading edge fires on the FIRST
+  // event before subsequent events mutate scrollTop. scrollToBottom still
+  // forces a React render: sticky is attribute-observed, no DOM-only path.
+  const [, forceRender] = useState(0)
+  const listenersRef = useRef(new Set<() => void>())
+  const renderQueuedRef = useRef(false)
+
+  const notify = () => {
+    for (const l of listenersRef.current) l()
+  }
+
+  function scrollMutated(el: DOMElement): void {
+    // Signal background intervals (IDE poll, LSP poll, GCS fetch, orphan
+    // check) to skip their next tick — they compete for the event loop and
+    // contributed to 1402ms max frame gaps during scroll drain.
+    // noop — injected by business layer via onScrollActivity callback
+    markDirty(el)
+    markCommitStart()
+    notify()
+    if (renderQueuedRef.current) return
+    renderQueuedRef.current = true
+    queueMicrotask(() => {
+      renderQueuedRef.current = false
+      scheduleRenderFrom(el)
+    })
+  }
+
+  useImperativeHandle(
+    ref,
+    (): ScrollBoxHandle => ({
+      scrollTo(y: number) {
+        const el = domRef.current
+        if (!el) return
+        // Explicit false overrides the DOM attribute so manual scroll
+        // breaks stickiness. Render code checks ?? precedence.
+        el.stickyScroll = false
+        el.pendingScrollDelta = undefined
+        el.scrollAnchor = undefined
+        el.scrollTop = Math.max(0, Math.floor(y))
+        scrollMutated(el)
+      },
+      scrollToElement(el: DOMElement, offset = 0) {
+        const box = domRef.current
+        if (!box) return
+        box.stickyScroll = false
+        box.pendingScrollDelta = undefined
+        box.scrollAnchor = { el, offset }
+        scrollMutated(box)
+      },
+      scrollBy(dy: number) {
+        const el = domRef.current
+        if (!el) return
+        el.stickyScroll = false
+        // Wheel input cancels any in-flight anchor seek — user override.
+        el.scrollAnchor = undefined
+        // Accumulate in pendingScrollDelta; renderer drains it at a capped
+        // rate so fast flicks show intermediate frames. Pure accumulator:
+        // scroll-up followed by scroll-down naturally cancels.
+        el.pendingScrollDelta = (el.pendingScrollDelta ?? 0) + Math.floor(dy)
+        scrollMutated(el)
+      },
+      scrollToBottom() {
+        const el = domRef.current
+        if (!el) return
+        el.pendingScrollDelta = undefined
+        el.stickyScroll = true
+        markDirty(el)
+        notify()
+        forceRender(n => n + 1)
+      },
+      getScrollTop() {
+        return domRef.current?.scrollTop ?? 0
+      },
+      getPendingDelta() {
+        // Accumulated-but-not-yet-drained delta. useVirtualScroll needs
+        // this to mount the union [committed, committed+pending] range —
+        // otherwise intermediate drain frames find no children (blank).
+        return domRef.current?.pendingScrollDelta ?? 0
+      },
+      getScrollHeight() {
+        return domRef.current?.scrollHeight ?? 0
+      },
+      getFreshScrollHeight() {
+        const content = domRef.current?.childNodes[0] as DOMElement | undefined
+        return (
+          content?.yogaNode?.getComputedHeight() ??
+          domRef.current?.scrollHeight ??
+          0
+        )
+      },
+      getViewportHeight() {
+        return domRef.current?.scrollViewportHeight ?? 0
+      },
+      getViewportTop() {
+        return domRef.current?.scrollViewportTop ?? 0
+      },
+      isSticky() {
+        const el = domRef.current
+        if (!el) return false
+        return el.stickyScroll ?? Boolean(el.attributes['stickyScroll'])
+      },
+      subscribe(listener: () => void) {
+        listenersRef.current.add(listener)
+        return () => listenersRef.current.delete(listener)
+      },
+      setClampBounds(min, max) {
+        const el = domRef.current
+        if (!el) return
+        el.scrollClampMin = min
+        el.scrollClampMax = max
+      },
+    }),
+    // notify/scrollMutated are inline (no useCallback) but only close over
+    // refs + imports — stable. Empty deps avoids rebuilding the handle on
+    // every render (which re-registers the ref = churn).
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [],
+  )
+
+  // Structure: outer viewport (overflow:scroll, constrained height) >
+  // inner content (flexGrow:1, flexShrink:0 — fills at least the viewport
+  // but grows beyond it for tall content). flexGrow:1 lets children use
+  // spacers to pin elements to the bottom of the scroll area. Yoga's
+  // Overflow.Scroll prevents the viewport from growing to fit the content.
+  // The renderer computes scrollHeight from the content box and culls
+  // content's children based on scrollTop.
+  //
+  // stickyScroll is passed as a DOM attribute (via ink-box directly) so it's
+  // available on the first render — ref callbacks fire after the initial
+  // commit, which is too late for the first frame.
+  return (
+    <ink-box
+      ref={el => {
+        domRef.current = el
+        if (el) el.scrollTop ??= 0
+      }}
+      style={{
+        flexWrap: 'nowrap',
+        flexDirection: style.flexDirection ?? 'row',
+        flexGrow: style.flexGrow ?? 0,
+        flexShrink: style.flexShrink ?? 1,
+        ...style,
+        overflowX: 'scroll',
+        overflowY: 'scroll',
+      }}
+      {...(stickyScroll ? { stickyScroll: true } : {})}
+    >
+      <Box flexDirection="column" flexGrow={1} flexShrink={0} width="100%">
+        {children}
+      </Box>
+    </ink-box>
+  )
+}
+
+export default ScrollBox