@svgrid/grid 1.0.2 → 1.1.0

package/src/row-resize.ts

@@ -0,0 +1,171 @@
+/**
+ * Row-resize Svelte action - drag the bottom edge of a row to grow /
+ * shrink it. Pair with a function-valued `rowHeight` prop so the grid
+ * reads per-row heights from a reactive store.
+ *
+ * The action is OFF until a consumer attaches it AND a row-header
+ * gutter cell exists in each row. A row-header cell is any TD with
+ * the `sv-row-gutter` class (typically the one rendering the row
+ * number 1, 2, 3, ...). Demos opt in by setting
+ * `cellClass: 'sv-row-gutter'` on the gutter column.
+ *
+ *   <script>
+ *     let heights = $state<Record<number, number>>({})
+ *     let resizeOn = $state(false)
+ *     const rowHeight = (i: number) => heights[i] ?? 32
+ *     function onResize(i: number, h: number) { heights = { ...heights, [i]: h } }
+ *   </script>
+ *
+ *   <div use:rowResize={{ onResize, disabled: !resizeOn }}>
+ *     <SvGrid columns={[{ field:'rn', cellClass:'sv-row-gutter', ... }, ...]}
+ *             rowHeight={rowHeight} ... />
+ *   </div>
+ *
+ * Visual: the strip sits along the bottom edge of the row-header
+ * cell, 5px tall, transparent by default, accent-tinted on hover -
+ * matching the column resize handle's look. Cursor is `row-resize`.
+ */
+
+const STRIP_CLASS = 'sv-grid-row-resize-handle'
+
+export type RowResizeOptions = {
+  /** Called when the user releases the drag with the final height. */
+  onResize: (rowIndex: number, height: number) => void
+  /** Optional callback fired during the drag (every pointermove). */
+  onResizeMove?: (rowIndex: number, height: number) => void
+  /** Min row height in px. Default 20. */
+  min?: number
+  /** Max row height in px. Default 320. */
+  max?: number
+  /** When true, the action removes its strips and ignores events. */
+  disabled?: boolean
+}
+
+type ActiveDrag = {
+  rowIndex: number
+  startY: number
+  startHeight: number
+  trEl: HTMLTableRowElement
+  strip: HTMLElement
+}
+
+export function rowResize(node: HTMLElement, opts: RowResizeOptions) {
+  let current = opts
+  let drag: ActiveDrag | null = null
+
+  function rowIndexOf(tr: HTMLTableRowElement): number {
+    const dataRow = tr.querySelector<HTMLElement>('[data-svgrid-row]')
+    const val = dataRow?.dataset.svgridRow
+    return val != null ? Number(val) : NaN
+  }
+
+  function onPointerMove(e: PointerEvent) {
+    if (!drag) return
+    const min = current.min ?? 20
+    const max = current.max ?? 320
+    const next = Math.max(min, Math.min(max, drag.startHeight + (e.clientY - drag.startY)))
+    drag.trEl.style.height = `${Math.round(next)}px`
+    current.onResizeMove?.(drag.rowIndex, Math.round(next))
+  }
+  function onPointerUp(e: PointerEvent) {
+    if (!drag) return
+    const min = current.min ?? 20
+    const max = current.max ?? 320
+    const next = Math.max(min, Math.min(max, drag.startHeight + (e.clientY - drag.startY)))
+    current.onResize(drag.rowIndex, Math.round(next))
+    drag.strip.classList.remove('is-resizing')
+    try { drag.trEl.releasePointerCapture(e.pointerId) } catch { /* ignore */ }
+    drag = null
+    window.removeEventListener('pointermove', onPointerMove)
+    window.removeEventListener('pointerup', onPointerUp)
+    document.body.style.cursor = ''
+  }
+
+  function onPointerDown(e: PointerEvent) {
+    if (current.disabled) return
+    const t = e.target as HTMLElement | null
+    if (!t?.classList.contains(STRIP_CLASS)) return
+    const tr = t.closest<HTMLTableRowElement>('tr.sv-grid-row')
+    if (!tr) return
+    const rowIndex = rowIndexOf(tr)
+    if (!Number.isFinite(rowIndex)) return
+    e.preventDefault()
+    e.stopPropagation()
+    t.classList.add('is-resizing')
+    drag = {
+      rowIndex,
+      startY: e.clientY,
+      startHeight: tr.getBoundingClientRect().height,
+      trEl: tr,
+      strip: t,
+    }
+    try { tr.setPointerCapture(e.pointerId) } catch { /* ignore */ }
+    document.body.style.cursor = 'row-resize'
+    window.addEventListener('pointermove', onPointerMove)
+    window.addEventListener('pointerup', onPointerUp)
+  }
+
+  /** Inject one strip into every row's gutter cell. When disabled or
+   *  when a row lacks a `.sv-row-gutter` cell, no strip is added. */
+  function decorate() {
+    if (current.disabled) {
+      removeAllStrips()
+      return
+    }
+    const rows = node.querySelectorAll<HTMLTableRowElement>('tr.sv-grid-row')
+    for (const tr of rows) {
+      if (tr.classList.contains('sv-grid-header-row')) continue
+      if (tr.classList.contains('sv-grid-row-spacer')) continue
+      const gutter = tr.querySelector<HTMLTableCellElement>(
+        '.sv-grid-cell.sv-row-gutter',
+      )
+      if (!gutter) continue
+      if (gutter.querySelector(`:scope > .${STRIP_CLASS}`)) continue
+      // Anchor the strip to the gutter cell + allow it to overflow
+      // downward into the row gap so the hit-area straddles the
+      // row boundary the way Excel does.
+      if (getComputedStyle(gutter).position === 'static') gutter.style.position = 'relative'
+      gutter.style.overflow = 'visible'
+      const strip = document.createElement('div')
+      strip.className = STRIP_CLASS
+      strip.setAttribute('role', 'separator')
+      strip.setAttribute('aria-orientation', 'horizontal')
+      strip.setAttribute('aria-label', 'Resize row')
+      // Inline the geometry + pointer-events so the strip works even
+      // before SvGrid.css is parsed; the hover tint still comes from
+      // the stylesheet. We keep the strip fully inside the gutter
+      // cell (no negative offset) to avoid stacking-context surprises
+      // with pinned / virtualised neighbour cells.
+      // 5px tall + sitting flush with the row bottom matches the
+      // column resize handle's 5px width.
+      strip.style.cssText =
+        'position:absolute;left:0;right:0;bottom:0;height:5px;' +
+        'cursor:row-resize;user-select:none;z-index:60;pointer-events:auto;'
+      gutter.appendChild(strip)
+    }
+  }
+  function removeAllStrips() {
+    node.querySelectorAll(`.${STRIP_CLASS}`).forEach((el) => el.remove())
+  }
+
+  node.addEventListener('pointerdown', onPointerDown, { capture: true })
+  const observer = new MutationObserver(() => decorate())
+  observer.observe(node, { childList: true, subtree: true })
+  decorate()
+
+  return {
+    update(next: RowResizeOptions) {
+      const wasDisabled = current.disabled
+      current = next
+      // Toggle: when going from enabled <-> disabled, repaint immediately.
+      if (wasDisabled !== current.disabled) decorate()
+    },
+    destroy() {
+      node.removeEventListener('pointerdown', onPointerDown, { capture: true })
+      window.removeEventListener('pointermove', onPointerMove)
+      window.removeEventListener('pointerup', onPointerUp)
+      observer.disconnect()
+      removeAllStrips()
+    },
+  }
+}

package/src/scroll-sync.test.ts

@@ -0,0 +1,330 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { createScrollSync } from './scroll-sync'
+
+// ---------------------------------------------------------------------------
+// Fake controller `ctx` for the scroll-sync handlers. As with the other
+// controller-slice tests, the handlers read/write everything through `ctx`,
+// so a hand-rolled stub drives every branch. Where the handler reads real DOM
+// geometry (tooltip placement, scroll offsets) we build genuine elements and
+// stub getBoundingClientRect / scroll metrics.
+// ---------------------------------------------------------------------------
+
+function makeCtx(overrides: Record<string, unknown> = {}) {
+  const ctx: any = {
+    tooltip: null,
+    tooltipTimer: null,
+    scrollSyncRaf: null,
+    scrollVersion: 0,
+    pendingScrollTop: 0,
+    pendingScrollLeft: 0,
+    rowVirtualizationEnabled: false,
+    columnVirtualizationEnabled: false,
+    scrollBottomArmed: true,
+    columnMenuFor: null,
+    operatorMenuFor: null,
+    closeMenus: vi.fn(),
+    domToLogicalRowOffset: (n: number) => n,
+    virtualizer: { setScrollOffset: vi.fn() },
+    columnVirtualizer: { setHorizontalOffset: vi.fn() },
+    props: {},
+    ...overrides,
+  }
+  return ctx
+}
+
+const syncFor = (overrides?: Record<string, unknown>) => {
+  const ctx = makeCtx(overrides)
+  return { ctx, ss: createScrollSync(ctx) }
+}
+
+describe('showTooltipFor / hideTooltip', () => {
+  beforeEach(() => {
+    vi.useFakeTimers()
+  })
+  afterEach(() => {
+    vi.useRealTimers()
+  })
+
+  function anchorEl(rect: Partial<DOMRect>) {
+    const el = document.createElement('div')
+    el.getBoundingClientRect = () =>
+      ({ left: 0, right: 0, top: 0, bottom: 0, width: 0, height: 0, x: 0, y: 0, ...rect }) as DOMRect
+    return el
+  }
+
+  it('does nothing when there is no text', () => {
+    const { ctx, ss } = syncFor()
+    ss.showTooltipFor(anchorEl({}), '')
+    expect(ctx.tooltipTimer).toBeNull()
+    vi.runAllTimers()
+    expect(ctx.tooltip).toBeNull()
+  })
+
+  it('schedules a tooltip after the debounce, positioned below the anchor', () => {
+    const { ctx, ss } = syncFor()
+    // Anchor near the top of a tall viewport -> tooltip appears below.
+    vi.stubGlobal('innerWidth', 1000)
+    vi.stubGlobal('innerHeight', 800)
+    const el = anchorEl({ left: 100, right: 140, top: 50, bottom: 70 })
+    ss.showTooltipFor(el, 'hello')
+    expect(ctx.tooltipTimer).not.toBeNull()
+    expect(ctx.tooltip).toBeNull() // not yet flushed
+    vi.advanceTimersByTime(250)
+    expect(ctx.tooltip).toEqual({
+      text: 'hello',
+      x: 106, // left + 6, within clamp range
+      y: 76, // bottom + 6 since "below"
+      below: true,
+    })
+  })
+
+  it('flips above the anchor when there is no room below', () => {
+    const { ctx, ss } = syncFor()
+    vi.stubGlobal('innerWidth', 1000)
+    vi.stubGlobal('innerHeight', 200)
+    // bottom + 64 is NOT < 200, so the tooltip renders above.
+    const el = anchorEl({ left: 100, right: 140, top: 150, bottom: 170 })
+    ss.showTooltipFor(el, 'world')
+    vi.advanceTimersByTime(250)
+    expect(ctx.tooltip.below).toBe(false)
+    expect(ctx.tooltip.y).toBe(144) // top - 6
+  })
+
+  it('clamps x so a wide tooltip stays inside the viewport', () => {
+    const { ctx, ss } = syncFor()
+    vi.stubGlobal('innerWidth', 300)
+    vi.stubGlobal('innerHeight', 800)
+    const el = anchorEl({ left: 280, right: 300, top: 10, bottom: 30 })
+    ss.showTooltipFor(el, 'edge')
+    vi.advanceTimersByTime(250)
+    // x clamped to vw - 290 = 10.
+    expect(ctx.tooltip.x).toBe(10)
+  })
+
+  it('clears a pending timer before scheduling a new tooltip', () => {
+    const { ctx, ss } = syncFor()
+    const clearSpy = vi.spyOn(window, 'clearTimeout')
+    const el = anchorEl({ left: 10, right: 30, top: 10, bottom: 30 })
+    ss.showTooltipFor(el, 'first')
+    ss.showTooltipFor(el, 'second')
+    expect(clearSpy).toHaveBeenCalled()
+    clearSpy.mockRestore()
+  })
+
+  it('hideTooltip clears the pending timer and the tooltip', () => {
+    const { ctx, ss } = syncFor()
+    const el = anchorEl({ left: 10, right: 30, top: 10, bottom: 30 })
+    ss.showTooltipFor(el, 'gone')
+    ctx.tooltip = { text: 'x', x: 0, y: 0, below: true }
+    ss.hideTooltip()
+    expect(ctx.tooltipTimer).toBeNull()
+    expect(ctx.tooltip).toBeNull()
+  })
+
+  it('hideTooltip is safe when no timer is pending', () => {
+    const { ctx, ss } = syncFor()
+    ctx.tooltip = { text: 'x', x: 0, y: 0, below: true }
+    ss.hideTooltip()
+    expect(ctx.tooltip).toBeNull()
+  })
+})
+
+describe('scheduleScrollSync / flushScheduledScrollSync', () => {
+  let rafCb: FrameRequestCallback | null = null
+  let rafCalls = 0
+  beforeEach(() => {
+    rafCb = null
+    rafCalls = 0
+    vi.stubGlobal('requestAnimationFrame', (cb: FrameRequestCallback) => {
+      rafCb = cb
+      rafCalls += 1
+      return 42
+    })
+  })
+  afterEach(() => {
+    vi.unstubAllGlobals()
+  })
+
+  it('records the pending offsets and schedules a single rAF', () => {
+    const { ctx, ss } = syncFor()
+    ss.scheduleScrollSync(120, 45)
+    expect(ctx.pendingScrollTop).toBe(120)
+    expect(ctx.pendingScrollLeft).toBe(45)
+    expect(ctx.scrollSyncRaf).toBe(42)
+    expect(rafCalls).toBe(1)
+  })
+
+  it('coalesces back-to-back calls into one frame (latest position wins)', () => {
+    const { ctx, ss } = syncFor()
+    ss.scheduleScrollSync(10, 0)
+    ss.scheduleScrollSync(200, 5) // raf already pending, must not re-schedule
+    expect(rafCalls).toBe(1)
+    expect(ctx.pendingScrollTop).toBe(200)
+    expect(ctx.pendingScrollLeft).toBe(5)
+  })
+
+  it('flush bumps scrollVersion and clears the raf handle', () => {
+    const { ctx, ss } = syncFor()
+    ss.scheduleScrollSync(50, 50)
+    rafCb?.(0)
+    expect(ctx.scrollVersion).toBe(1)
+    expect(ctx.scrollSyncRaf).toBeNull()
+  })
+
+  it('flush pushes the row offset through domToLogicalRowOffset when row virtualization is on', () => {
+    const setScrollOffset = vi.fn()
+    const { ss } = syncFor({
+      rowVirtualizationEnabled: true,
+      domToLogicalRowOffset: (n: number) => n * 2,
+      virtualizer: { setScrollOffset },
+    })
+    ss.scheduleScrollSync(30, 0)
+    rafCb?.(0)
+    expect(setScrollOffset).toHaveBeenCalledWith(60)
+  })
+
+  it('flush pushes the horizontal offset when column virtualization is on', () => {
+    const setHorizontalOffset = vi.fn()
+    const { ss } = syncFor({
+      columnVirtualizationEnabled: true,
+      columnVirtualizer: { setHorizontalOffset },
+    })
+    ss.scheduleScrollSync(0, 88)
+    rafCb?.(0)
+    expect(setHorizontalOffset).toHaveBeenCalledWith(88)
+  })
+
+  it('flush skips both virtualizers when neither is enabled', () => {
+    const { ctx, ss } = syncFor()
+    ss.scheduleScrollSync(5, 5)
+    rafCb?.(0)
+    expect(ctx.virtualizer.setScrollOffset).not.toHaveBeenCalled()
+    expect(ctx.columnVirtualizer.setHorizontalOffset).not.toHaveBeenCalled()
+  })
+})
+
+describe('onBodyScroll', () => {
+  let rafCb: FrameRequestCallback | null = null
+  beforeEach(() => {
+    rafCb = null
+    vi.stubGlobal('requestAnimationFrame', (cb: FrameRequestCallback) => {
+      rafCb = cb
+      return 7
+    })
+  })
+  afterEach(() => {
+    vi.unstubAllGlobals()
+  })
+
+  function scrollEvent(container: HTMLElement | null) {
+    return { currentTarget: container } as unknown as Event
+  }
+
+  function scroller(props: Partial<{
+    scrollTop: number
+    scrollLeft: number
+    scrollHeight: number
+    clientHeight: number
+  }>) {
+    const el = document.createElement('div')
+    Object.defineProperty(el, 'scrollTop', { value: props.scrollTop ?? 0, configurable: true })
+    Object.defineProperty(el, 'scrollLeft', { value: props.scrollLeft ?? 0, configurable: true })
+    Object.defineProperty(el, 'scrollHeight', { value: props.scrollHeight ?? 0, configurable: true })
+    Object.defineProperty(el, 'clientHeight', { value: props.clientHeight ?? 0, configurable: true })
+    return el
+  }
+
+  it('does nothing when there is no current target', () => {
+    const { ctx, ss } = syncFor()
+    ss.onBodyScroll(scrollEvent(null))
+    expect(ctx.pendingScrollTop).toBe(0)
+  })
+
+  it('records the container scroll offsets via scheduleScrollSync', () => {
+    const { ctx, ss } = syncFor()
+    const el = scroller({ scrollTop: 90, scrollLeft: 12 })
+    ss.onBodyScroll(scrollEvent(el))
+    expect(ctx.pendingScrollTop).toBe(90)
+    expect(ctx.pendingScrollLeft).toBe(12)
+    expect(ctx.scrollSyncRaf).toBe(7)
+  })
+
+  it('closes open column/operator menus on scroll', () => {
+    const closeMenus = vi.fn()
+    const { ss } = syncFor({ columnMenuFor: 'x', closeMenus })
+    ss.onBodyScroll(scrollEvent(scroller({})))
+    expect(closeMenus).toHaveBeenCalled()
+  })
+
+  it('closes menus when an operator menu is open', () => {
+    const closeMenus = vi.fn()
+    const { ss } = syncFor({ operatorMenuFor: 'op', closeMenus })
+    ss.onBodyScroll(scrollEvent(scroller({})))
+    expect(closeMenus).toHaveBeenCalled()
+  })
+
+  it('does not close menus when none are open', () => {
+    const closeMenus = vi.fn()
+    const { ss } = syncFor({ closeMenus })
+    ss.onBodyScroll(scrollEvent(scroller({})))
+    expect(closeMenus).not.toHaveBeenCalled()
+  })
+
+  it('fires onScrollBottomReached once when the scroll reaches the bottom', () => {
+    const onScrollBottomReached = vi.fn()
+    const { ctx, ss } = syncFor({
+      props: { onScrollBottomReached },
+      scrollBottomArmed: true,
+    })
+    // scrollTop + clientHeight >= scrollHeight - 32 -> at bottom.
+    const el = scroller({ scrollTop: 600, clientHeight: 400, scrollHeight: 1000 })
+    ss.onBodyScroll(scrollEvent(el))
+    expect(onScrollBottomReached).toHaveBeenCalledWith({
+      scrollTop: 600,
+      scrollHeight: 1000,
+      clientHeight: 400,
+    })
+    expect(ctx.scrollBottomArmed).toBe(false) // disarmed so it won't refire
+  })
+
+  it('does not refire onScrollBottomReached while still at the bottom (disarmed)', () => {
+    const onScrollBottomReached = vi.fn()
+    const { ss } = syncFor({
+      props: { onScrollBottomReached },
+      scrollBottomArmed: false,
+    })
+    const el = scroller({ scrollTop: 600, clientHeight: 400, scrollHeight: 1000 })
+    ss.onBodyScroll(scrollEvent(el))
+    expect(onScrollBottomReached).not.toHaveBeenCalled()
+  })
+
+  it('re-arms the trigger after scrolling away from the bottom', () => {
+    const onScrollBottomReached = vi.fn()
+    const { ctx, ss } = syncFor({
+      props: { onScrollBottomReached },
+      scrollBottomArmed: false,
+    })
+    // Not at bottom: scrollTop + clientHeight < scrollHeight - 32.
+    const el = scroller({ scrollTop: 100, clientHeight: 400, scrollHeight: 1000 })
+    ss.onBodyScroll(scrollEvent(el))
+    expect(ctx.scrollBottomArmed).toBe(true)
+    expect(onScrollBottomReached).not.toHaveBeenCalled()
+  })
+
+  it('skips the bottom-reached logic entirely when no callback is registered', () => {
+    const { ctx, ss } = syncFor({ scrollBottomArmed: true })
+    const el = scroller({ scrollTop: 600, clientHeight: 400, scrollHeight: 1000 })
+    ss.onBodyScroll(scrollEvent(el))
+    // Armed flag is untouched when there is no callback.
+    expect(ctx.scrollBottomArmed).toBe(true)
+  })
+})
+
+describe('createScrollSync wiring', () => {
+  it('exposes the documented handler surface', () => {
+    const { ss } = syncFor()
+    expect(Object.keys(ss).sort()).toEqual(
+      ['flushScheduledScrollSync', 'hideTooltip', 'onBodyScroll', 'scheduleScrollSync', 'showTooltipFor'],
+    )
+  })
+})