@svgrid/grid 1.0.0

package/src/sparkline.ts

@@ -0,0 +1,164 @@
+/**
+ * Sparkline geometry. Pure functions that turn an array of numbers into the
+ * SVG primitives a tiny in-cell chart needs - no DOM, so it is trivially
+ * unit-testable and the `<SvGrid>` render component just paints the result.
+ *
+ * Four chart types, mirroring the de-facto enterprise-grid set:
+ *   - `line`     a single polyline
+ *   - `area`     a polyline plus a filled area down to the baseline
+ *   - `bar`      one column per value, scaled from the dataset min..max
+ *   - `winloss`  fixed-height up/down bars (sign only), e.g. W/L streaks
+ */
+export type SparklineType = 'line' | 'area' | 'bar' | 'winloss'
+
+export type SparklineConfig = {
+  type?: SparklineType
+  /** Stroke (line/area) or positive fill (bar/winloss). */
+  color?: string
+  /** Fill for negative bars / losses. Defaults to a red. */
+  negativeColor?: string
+  width?: number
+  height?: number
+  /** Fix the value scale instead of deriving it from the row's own data. */
+  min?: number
+  max?: number
+  lineWidth?: number
+  /** Draw a dot on the last point (line/area). Default true. */
+  lastPoint?: boolean
+}
+
+export type SparklineBar = {
+  x: number
+  y: number
+  w: number
+  h: number
+  negative: boolean
+}
+
+export type SparklineGeometry = {
+  width: number
+  height: number
+  type: SparklineType
+  color: string
+  negativeColor: string
+  lineWidth: number
+  /** `line` / `area`: the polyline through every point. */
+  linePath: string
+  /** `area`: closed path filled down to the baseline. */
+  areaPath: string
+  /** `bar` / `winloss`: one rect per value. */
+  bars: SparklineBar[]
+  /** `line` / `area`: the final point, for the end-cap dot. */
+  lastPoint: { x: number; y: number } | null
+}
+
+const DEFAULTS = {
+  width: 88,
+  height: 22,
+  color: 'var(--sg-accent, #2563eb)',
+  negativeColor: '#ef4444',
+  lineWidth: 1.5,
+}
+
+/** Coerce loose cell values (arrays, comma strings) into a number array. */
+export function toSparklineValues(value: unknown): number[] {
+  if (Array.isArray(value)) {
+    return value.map((v) => Number(v)).filter((n) => Number.isFinite(n))
+  }
+  if (typeof value === 'string' && value.trim()) {
+    return value
+      .split(/[,\s]+/)
+      .map((v) => Number(v))
+      .filter((n) => Number.isFinite(n))
+  }
+  return []
+}
+
+export function buildSparkline(
+  values: number[],
+  cfg: SparklineConfig = {},
+): SparklineGeometry | null {
+  if (!values.length) return null
+
+  const width = cfg.width ?? DEFAULTS.width
+  const height = cfg.height ?? DEFAULTS.height
+  const type = cfg.type ?? 'line'
+  const color = cfg.color ?? DEFAULTS.color
+  const negativeColor = cfg.negativeColor ?? DEFAULTS.negativeColor
+  const lineWidth = cfg.lineWidth ?? DEFAULTS.lineWidth
+  const pad = Math.ceil(lineWidth) + 1
+  const innerW = Math.max(1, width - pad * 2)
+  const innerH = Math.max(1, height - pad * 2)
+
+  const base: Omit<
+    SparklineGeometry,
+    'linePath' | 'areaPath' | 'bars' | 'lastPoint'
+  > = { width, height, type, color, negativeColor, lineWidth }
+
+  if (type === 'winloss') {
+    const n = values.length
+    const gap = n > 1 ? Math.min(2, innerW / n / 3) : 0
+    const slot = innerW / n
+    const barW = Math.max(1, slot - gap)
+    const mid = height / 2
+    const h = innerH / 2
+    const bars: SparklineBar[] = values.map((v, i) => {
+      const x = pad + i * slot + (slot - barW) / 2
+      if (v > 0) return { x, y: mid - h, w: barW, h, negative: false }
+      if (v < 0) return { x, y: mid, w: barW, h, negative: true }
+      return { x, y: mid - 1, w: barW, h: 2, negative: false }
+    })
+    return { ...base, linePath: '', areaPath: '', bars, lastPoint: null }
+  }
+
+  const min = cfg.min ?? Math.min(...values)
+  const max = cfg.max ?? Math.max(...values)
+  const span = max - min || 1
+
+  if (type === 'bar') {
+    const n = values.length
+    const gap = n > 1 ? Math.min(2, innerW / n / 3) : 0
+    const slot = innerW / n
+    const barW = Math.max(1, slot - gap)
+    // Bars grow from a zero baseline when the data spans zero, else from min.
+    const baseVal = min < 0 && max > 0 ? 0 : min
+    const baseY = pad + innerH - ((baseVal - min) / span) * innerH
+    const bars: SparklineBar[] = values.map((v, i) => {
+      const x = pad + i * slot + (slot - barW) / 2
+      const vy = pad + innerH - ((v - min) / span) * innerH
+      const top = Math.min(vy, baseY)
+      const h = Math.max(1, Math.abs(vy - baseY))
+      return { x, y: top, w: barW, h, negative: v < baseVal }
+    })
+    return { ...base, linePath: '', areaPath: '', bars, lastPoint: null }
+  }
+
+  // line / area
+  const n = values.length
+  const stepX = n > 1 ? innerW / (n - 1) : 0
+  const pts = values.map((v, i) => ({
+    x: pad + i * stepX,
+    y: pad + innerH - ((v - min) / span) * innerH,
+  }))
+  const linePath = pts
+    .map((p, i) => `${i === 0 ? 'M' : 'L'}${round(p.x)},${round(p.y)}`)
+    .join(' ')
+  const first = pts[0]!
+  const last = pts[pts.length - 1]!
+  const baseY = pad + innerH
+  const areaPath =
+    type === 'area'
+      ? `${linePath} L${round(last.x)},${round(baseY)} L${round(first.x)},${round(baseY)} Z`
+      : ''
+  return {
+    ...base,
+    linePath,
+    areaPath,
+    bars: [],
+    lastPoint: cfg.lastPoint === false ? null : { x: last.x, y: last.y },
+  }
+}
+
+function round(n: number): number {
+  return Math.round(n * 100) / 100
+}

package/src/static-functions.ts

@@ -0,0 +1,11 @@
+export {
+  createCoreRowModel,
+  createExpandedRowModel,
+  createFilteredRowModel,
+  createGroupedRowModel,
+  createPaginatedRowModel,
+  createSortedRowModel,
+  filterFns,
+  sortFns,
+  tableFeatures,
+} from './core'

package/src/subscribe.test.ts

@@ -0,0 +1,103 @@
+/**
+ * Unit tests for the grid-store subscribe helper.
+ *
+ * The function attaches a selector to grid.store and shallow-compares each
+ * emitted state, updating the returned `current` getter only when the
+ * selection actually changed.
+ */
+import { describe, expect, it } from 'vitest'
+import { subscribeGrid, subscribeSvGrid } from './subscribe'
+
+type Listener = () => void
+
+/**
+ * Minimal hand-rolled stand-in for `grid.store` that mimics the TanStack
+ * Store shape `subscribeGrid` reads: `state` getter + `subscribe(listener)`
+ * + `setState(updater)` that fires the listeners.
+ */
+function makeFakeStore<T extends object>(initial: T) {
+  let state = initial
+  const listeners = new Set<Listener>()
+  const store = {
+    get state() {
+      return state
+    },
+    subscribe(listener: Listener) {
+      listeners.add(listener)
+      return () => listeners.delete(listener)
+    },
+    setState(updater: (prev: T) => T) {
+      state = updater(state)
+      for (const l of listeners) l()
+    },
+  }
+  return store
+}
+
+describe('subscribeGrid', () => {
+  it('starts with the current selected value', () => {
+    const store = makeFakeStore({ sorting: ['name'], rowSelection: { '0': true } })
+    const grid = { store } as any
+    const sub = subscribeGrid(grid, (s) => s.sorting)
+    expect(sub.current).toEqual(['name'])
+  })
+
+  it('updates the selected value when the store fires a change', () => {
+    const store = makeFakeStore({ sorting: ['name'] })
+    const grid = { store } as any
+    const sub = subscribeGrid(grid, (s) => s.sorting)
+    store.setState((prev) => ({ ...prev, sorting: ['age'] }))
+    expect(sub.current).toEqual(['age'])
+  })
+
+  it('keeps the previous reference when shallow-compare reports equal', () => {
+    const store = makeFakeStore<{ sel: Record<string, boolean> }>({ sel: { a: true } })
+    const grid = { store } as any
+    const sub = subscribeGrid(grid, (s) => s.sel)
+    const initial = sub.current
+    // A new object with the same key/value content - shallow-equal to the prev.
+    store.setState(() => ({ sel: { a: true } }))
+    expect(sub.current).toBe(initial)
+  })
+
+  it('replaces the reference when a key value changes', () => {
+    const store = makeFakeStore<{ sel: Record<string, boolean> }>({ sel: { a: true } })
+    const grid = { store } as any
+    const sub = subscribeGrid(grid, (s) => s.sel)
+    const initial = sub.current
+    store.setState(() => ({ sel: { a: false } }))
+    expect(sub.current).not.toBe(initial)
+    expect(sub.current).toEqual({ a: false })
+  })
+
+  it('treats a different key set as a change', () => {
+    const store = makeFakeStore<{ sel: Record<string, boolean> }>({ sel: { a: true } })
+    const grid = { store } as any
+    const sub = subscribeGrid(grid, (s) => s.sel)
+    store.setState(() => ({ sel: { a: true, b: true } }))
+    expect(sub.current).toEqual({ a: true, b: true })
+  })
+
+  it('treats primitive selections (numbers, strings) correctly', () => {
+    const store = makeFakeStore({ count: 1 })
+    const grid = { store } as any
+    const sub = subscribeGrid(grid, (s) => s.count)
+    expect(sub.current).toBe(1)
+    store.setState(() => ({ count: 1 }))
+    expect(sub.current).toBe(1)
+    store.setState(() => ({ count: 2 }))
+    expect(sub.current).toBe(2)
+  })
+
+  it('treats null and undefined as inequal to objects (early-return shallowCompare branch)', () => {
+    const store = makeFakeStore<{ sel: Record<string, boolean> | null }>({ sel: { a: true } })
+    const grid = { store } as any
+    const sub = subscribeGrid(grid, (s) => s.sel)
+    store.setState(() => ({ sel: null }))
+    expect(sub.current).toBeNull()
+  })
+
+  it('exports the subscribeSvGrid alias as the same function', () => {
+    expect(subscribeSvGrid).toBe(subscribeGrid)
+  })
+})

package/src/subscribe.ts

@@ -0,0 +1,38 @@
+import type { RowData, SvGrid, TableFeatures } from './core'
+
+const shallowCompare = (a: unknown, b: unknown) => {
+  if (Object.is(a, b)) return true
+  if (!a || !b || typeof a !== 'object' || typeof b !== 'object') return false
+  const aObj = a as Record<string, unknown>
+  const bObj = b as Record<string, unknown>
+  const aKeys = Object.keys(aObj)
+  const bKeys = Object.keys(bObj)
+  if (aKeys.length !== bKeys.length) return false
+  return aKeys.every((key) => Object.is(aObj[key], bObj[key]))
+}
+
+/**
+ * Fine-grained subscription to `table.store` using `useSelector` with shallow
+ * comparison. Call from `<script>` so the selector is contextually typed.
+ */
+export function subscribeGrid<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+  TSelected,
+>(
+  grid: SvGrid<TData>,
+  selector: (state: Record<string, any>) => TSelected,
+) {
+  let current = selector(grid.store.state)
+  grid.store.subscribe(() => {
+    const next = selector(grid.store.state)
+    if (!shallowCompare(current, next)) current = next
+  })
+  return {
+    get current() {
+      return current
+    },
+  }
+}
+
+export const subscribeSvGrid = subscribeGrid

package/src/sv-grid-scrollbar.ts

@@ -0,0 +1,347 @@
+type Orientation = 'horizontal' | 'vertical'
+
+const ARROW_SIZE = 16
+const HOLD_DELAY_MS = 280
+const HOLD_INTERVAL_MS = 50
+const SVG_NS = 'http://www.w3.org/2000/svg'
+
+/**
+ * Build the chevron icon as real DOM nodes so the component is compatible
+ * with strict Content Security Policies / Trusted Types (no innerHTML).
+ */
+function createChevronSvg(): SVGElement {
+  const svg = document.createElementNS(SVG_NS, 'svg')
+  svg.setAttribute('viewBox', '0 0 24 24')
+  svg.setAttribute('fill', 'none')
+  svg.setAttribute('stroke', 'currentColor')
+  svg.setAttribute('stroke-width', '3')
+  svg.setAttribute('stroke-linecap', 'round')
+  svg.setAttribute('stroke-linejoin', 'round')
+  const path = document.createElementNS(SVG_NS, 'path')
+  path.setAttribute('d', 'M6 9l6 6 6-6')
+  svg.appendChild(path)
+  return svg
+}
+
+/**
+ * Each visible part of the scrollbar reads from a CSS custom property so
+ * applications can theme it (e.g. a dark theme) without forking the
+ * component. The fallbacks are the original light-mode palette so existing
+ * embedders keep their look without changes.
+ */
+const STYLE_TEMPLATE = `
+  :host {
+    display: flex;
+    user-select: none;
+    background: var(--sg-scrollbar-bg, #eef2f8);
+    box-shadow: inset 0 0 0 1px var(--sg-scrollbar-border, rgba(15, 23, 42, 0.04));
+    /* Start hidden + non-interactive - viewport/content sizes are 0 until
+       after the first layout pass, so without this default the scrollbar
+       paints visible for one frame and then JS hides it on mount. That
+       flicker is what shows up as a "flashing horizontal scrollbar"
+       every time a demo first renders. updateGeometry() switches us to
+       opacity 1 the moment the grid genuinely has overflow. */
+    opacity: 0;
+    pointer-events: none;
+    transition: opacity 120ms ease;
+  }
+  :host([orientation="vertical"]) {
+    flex-direction: column;
+    width: ${ARROW_SIZE}px;
+  }
+  :host([orientation="horizontal"]) {
+    flex-direction: row;
+    height: ${ARROW_SIZE}px;
+  }
+  .arrow {
+    flex: none;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    width: ${ARROW_SIZE}px;
+    height: ${ARROW_SIZE}px;
+    margin: 0;
+    padding: 0;
+    border: 0;
+    border-radius: 3px;
+    background: transparent;
+    color: var(--sg-scrollbar-arrow, #64748b);
+    cursor: pointer;
+    transition: background-color 100ms ease, color 100ms ease;
+  }
+  .arrow:hover {
+    background: var(--sg-scrollbar-arrow-hover-bg, #dde4ee);
+    color: var(--sg-scrollbar-arrow-hover, #1f2937);
+  }
+  .arrow:active {
+    background: var(--sg-scrollbar-arrow-active-bg, #c7d1df);
+    color: var(--sg-scrollbar-arrow-active, #0f172a);
+  }
+  .arrow:disabled {
+    color: var(--sg-scrollbar-arrow-disabled, #cbd5e1);
+    cursor: default;
+  }
+  .arrow:disabled:hover {
+    background: transparent;
+  }
+  .arrow svg {
+    width: 10px;
+    height: 10px;
+    display: block;
+  }
+  :host([orientation="vertical"]) .arrow-start svg {
+    transform: rotate(180deg);
+  }
+  :host([orientation="horizontal"]) .arrow-start svg {
+    transform: rotate(90deg);
+  }
+  :host([orientation="horizontal"]) .arrow-end svg {
+    transform: rotate(-90deg);
+  }
+  .track {
+    position: relative;
+    flex: 1 1 0;
+    min-width: 0;
+    min-height: 0;
+  }
+  .thumb {
+    position: absolute;
+    border-radius: var(--sg-scrollbar-thumb-radius, 6px);
+    background: var(--sg-scrollbar-thumb, #b1bccd);
+    cursor: pointer;
+    transition: background-color 100ms ease;
+  }
+  .thumb:hover {
+    background: var(--sg-scrollbar-thumb-hover, #8693a7);
+  }
+  .thumb:active {
+    background: var(--sg-scrollbar-thumb-active, #64748b);
+  }
+  :host([orientation="vertical"]) .thumb {
+    left: 3px;
+    right: 3px;
+  }
+  :host([orientation="horizontal"]) .thumb {
+    top: 3px;
+    bottom: 3px;
+  }
+`
+
+class SvGridScrollbarElement extends HTMLElement {
+  static get observedAttributes() {
+    return ['orientation', 'viewport-size', 'content-size', 'value', 'step']
+  }
+
+  private track!: HTMLDivElement
+  private thumb!: HTMLDivElement
+  private startArrow!: HTMLButtonElement
+  private endArrow!: HTMLButtonElement
+  private dragging = false
+  private dragStart = 0
+  private valueStart = 0
+  private holdTimer: ReturnType<typeof setTimeout> | null = null
+  private resizeObserver: ResizeObserver | null = null
+
+  connectedCallback() {
+    if (this.shadowRoot) return
+    const shadow = this.attachShadow({ mode: 'open' })
+    const style = document.createElement('style')
+    style.textContent = STYLE_TEMPLATE
+
+    this.startArrow = this.createArrow('start')
+    this.endArrow = this.createArrow('end')
+    this.track = document.createElement('div')
+    this.track.className = 'track'
+    this.thumb = document.createElement('div')
+    this.thumb.className = 'thumb'
+    this.track.appendChild(this.thumb)
+
+    shadow.append(style, this.startArrow, this.track, this.endArrow)
+
+    this.thumb.addEventListener('pointerdown', this.onThumbPointerDown)
+    this.track.addEventListener('pointerdown', this.onTrackPointerDown)
+    this.startArrow.addEventListener('pointerdown', this.onArrowStartPointerDown)
+    this.endArrow.addEventListener('pointerdown', this.onArrowEndPointerDown)
+    for (const btn of [this.startArrow, this.endArrow]) {
+      btn.addEventListener('pointerup', this.stopHold)
+      btn.addEventListener('pointerleave', this.stopHold)
+      btn.addEventListener('pointercancel', this.stopHold)
+    }
+
+    this.resizeObserver = new ResizeObserver(() => this.render())
+    this.resizeObserver.observe(this)
+
+    this.render()
+  }
+
+  disconnectedCallback() {
+    this.stopHold()
+    this.resizeObserver?.disconnect()
+    this.resizeObserver = null
+    document.removeEventListener('pointermove', this.onPointerMove)
+    document.removeEventListener('pointerup', this.onPointerUp)
+  }
+
+  attributeChangedCallback() {
+    this.render()
+  }
+
+  private get orientation(): Orientation {
+    return this.getAttribute('orientation') === 'horizontal' ? 'horizontal' : 'vertical'
+  }
+
+  private get viewportSize() {
+    return Number(this.getAttribute('viewport-size') || '0')
+  }
+
+  private get contentSize() {
+    return Number(this.getAttribute('content-size') || '0')
+  }
+
+  private get value() {
+    return Number(this.getAttribute('value') || '0')
+  }
+
+  private get step() {
+    const raw = Number(this.getAttribute('step') || '40')
+    return raw > 0 ? raw : 40
+  }
+
+  private get maxValue() {
+    return Math.max(this.contentSize - this.viewportSize, 0)
+  }
+
+  /** Measured length of the track between the two arrows, in the active axis. */
+  private getTrackLength(): number {
+    const rect = this.track.getBoundingClientRect()
+    const measured = this.orientation === 'vertical' ? rect.height : rect.width
+    if (measured > 0) return measured
+    // Pre-layout fallback so the thumb still has a sensible size on first render.
+    return Math.max(this.viewportSize - ARROW_SIZE * 2, 1)
+  }
+
+  private computeThumbSize(trackLength: number): number {
+    if (this.contentSize <= 0 || this.viewportSize <= 0 || trackLength <= 0) return 0
+    const ratio = Math.min(this.viewportSize / this.contentSize, 1)
+    return Math.max(20, ratio * trackLength)
+  }
+
+  private createArrow(side: 'start' | 'end'): HTMLButtonElement {
+    const btn = document.createElement('button')
+    btn.type = 'button'
+    btn.className = `arrow arrow-${side}`
+    btn.setAttribute(
+      'aria-label',
+      side === 'start' ? 'Scroll back' : 'Scroll forward',
+    )
+    btn.appendChild(createChevronSvg())
+    return btn
+  }
+
+  private onArrowStartPointerDown = (event: PointerEvent) => {
+    event.preventDefault()
+    this.startHold(-1)
+  }
+
+  private onArrowEndPointerDown = (event: PointerEvent) => {
+    event.preventDefault()
+    this.startHold(1)
+  }
+
+  private startHold(direction: -1 | 1) {
+    this.stopHold()
+    const tick = () => this.emitScroll(this.value + direction * this.step)
+    tick()
+    this.holdTimer = setTimeout(() => {
+      this.holdTimer = setInterval(tick, HOLD_INTERVAL_MS)
+    }, HOLD_DELAY_MS)
+  }
+
+  private stopHold = () => {
+    if (this.holdTimer !== null) {
+      clearTimeout(this.holdTimer)
+      clearInterval(this.holdTimer)
+      this.holdTimer = null
+    }
+  }
+
+  private onThumbPointerDown = (event: PointerEvent) => {
+    event.preventDefault()
+    this.dragging = true
+    this.dragStart = this.orientation === 'vertical' ? event.clientY : event.clientX
+    this.valueStart = this.value
+    document.addEventListener('pointermove', this.onPointerMove)
+    document.addEventListener('pointerup', this.onPointerUp)
+  }
+
+  private onTrackPointerDown = (event: PointerEvent) => {
+    if (event.target === this.thumb) return
+    const rect = this.track.getBoundingClientRect()
+    const coord =
+      this.orientation === 'vertical' ? event.clientY - rect.top : event.clientX - rect.left
+    const trackSize = this.orientation === 'vertical' ? rect.height : rect.width
+    const thumbSize = this.computeThumbSize(trackSize)
+    const available = Math.max(trackSize - thumbSize, 1)
+    const offset = Math.min(Math.max(coord - thumbSize / 2, 0), available)
+    this.emitScroll((offset / available) * this.maxValue)
+  }
+
+  private onPointerMove = (event: PointerEvent) => {
+    if (!this.dragging) return
+    const current = this.orientation === 'vertical' ? event.clientY : event.clientX
+    const delta = current - this.dragStart
+    const rect = this.track.getBoundingClientRect()
+    const trackSize = this.orientation === 'vertical' ? rect.height : rect.width
+    const thumbSize = this.computeThumbSize(trackSize)
+    const available = Math.max(trackSize - thumbSize, 1)
+    this.emitScroll(this.valueStart + (delta / available) * this.maxValue)
+  }
+
+  private onPointerUp = () => {
+    this.dragging = false
+    document.removeEventListener('pointermove', this.onPointerMove)
+    document.removeEventListener('pointerup', this.onPointerUp)
+  }
+
+  private emitScroll(next: number) {
+    const bounded = Math.min(Math.max(next, 0), this.maxValue)
+    this.dispatchEvent(
+      new CustomEvent('scroll-change', {
+        detail: { value: bounded },
+        bubbles: true,
+        composed: true,
+      }),
+    )
+  }
+
+  private render() {
+    if (!this.shadowRoot) return
+    const viewport = this.viewportSize
+    const content = this.contentSize
+    const hidden = content <= viewport || viewport <= 0
+    this.style.opacity = hidden ? '0' : '1'
+    this.style.pointerEvents = hidden ? 'none' : 'auto'
+
+    const trackLength = this.getTrackLength()
+    const thumbSize = this.computeThumbSize(trackLength)
+    const maxValue = this.maxValue
+    const ratio = maxValue > 0 ? this.value / maxValue : 0
+    const offset = ratio * Math.max(trackLength - thumbSize, 0)
+
+    if (this.orientation === 'vertical') {
+      this.thumb.style.height = `${thumbSize}px`
+      this.thumb.style.transform = `translateY(${offset}px)`
+    } else {
+      this.thumb.style.width = `${thumbSize}px`
+      this.thumb.style.transform = `translateX(${offset}px)`
+    }
+    this.startArrow.disabled = hidden || this.value <= 0
+    this.endArrow.disabled = hidden || this.value >= maxValue
+  }
+}
+
+if (typeof window !== 'undefined' && !customElements.get('sv-grid-scrollbar')) {
+  customElements.define('sv-grid-scrollbar', SvGridScrollbarElement)
+}
+
+export {}