@svgrid/grid 2.1.22 → 2.1.23

package/src/createPagination.test.ts

@@ -0,0 +1,65 @@
+import { describe, expect, it, vi } from 'vitest'
+import { createPagination } from './createPagination'
+
+function make(over: Partial<{ page: number; pageCount: number; disabled: boolean }> = {}) {
+  let page = over.page ?? 5
+  const onChange = vi.fn((p: number) => (page = p))
+  const pg = createPagination({
+    page: () => page,
+    pageCount: () => over.pageCount ?? 20,
+    onChange,
+    disabled: () => over.disabled ?? false,
+  })
+  return { pg, onChange, getPage: () => page }
+}
+
+describe('createPagination', () => {
+  it('builds the page/ellipsis sequence around the current page', () => {
+    const { pg } = make({ page: 10, pageCount: 20 })
+    expect(pg.items[0]).toBe(1)
+    expect(pg.items).toContain(10)
+    expect(pg.items.some((i) => i === 'ellipsis-left')).toBe(true)
+    expect(pg.items.some((i) => i === 'ellipsis-right')).toBe(true)
+    expect(pg.items.at(-1)).toBe(20)
+  })
+
+  it('clamps navigation to [1, pageCount] and only fires on a real change', () => {
+    const { pg, onChange } = make({ page: 1, pageCount: 20 })
+    pg.prev() // already at 1 -> clamped, no change
+    expect(onChange).not.toHaveBeenCalled()
+    pg.next()
+    expect(onChange).toHaveBeenLastCalledWith(2)
+    pg.last()
+    expect(onChange).toHaveBeenLastCalledWith(20)
+  })
+
+  it('go() clamps out-of-range targets', () => {
+    const { pg, onChange } = make({ page: 5, pageCount: 20 })
+    pg.go(999)
+    expect(onChange).toHaveBeenLastCalledWith(20)
+    pg.go(-3)
+    expect(onChange).toHaveBeenLastCalledWith(1)
+  })
+
+  it('canPrev/canNext reflect the edges', () => {
+    expect(make({ page: 1, pageCount: 20 }).pg.canPrev()).toBe(false)
+    expect(make({ page: 1, pageCount: 20 }).pg.canNext()).toBe(true)
+    expect(make({ page: 20, pageCount: 20 }).pg.canNext()).toBe(false)
+  })
+
+  it('is inert while disabled', () => {
+    const { pg, onChange } = make({ page: 5, pageCount: 20, disabled: true })
+    pg.next()
+    expect(onChange).not.toHaveBeenCalled()
+    expect(pg.canPrev()).toBe(false)
+    expect(pg.canNext()).toBe(false)
+    expect(pg.pageButtonProps(3).disabled).toBe(true)
+  })
+
+  it('marks the active page in prop-getters', () => {
+    const { pg } = make({ page: 5, pageCount: 20 })
+    expect(pg.isActive(5)).toBe(true)
+    expect(pg.pageButtonProps(5)['aria-current']).toBe('page')
+    expect(pg.pageButtonProps(6)['aria-current']).toBeUndefined()
+  })
+})

package/src/createPagination.ts

@@ -0,0 +1,84 @@
+/**
+ * createPagination - the HEADLESS core behind <SvPagination>: the page/ellipsis
+ * sequence (via the pure `paginationRange`) plus navigation (first/prev/next/last
+ * with clamping) and prop-getters you spread onto your own markup. Pure getters,
+ * no runes - so it is directly unit-testable and framework-free.
+ *
+ * ```svelte
+ * <script lang="ts">
+ *   import { createPagination } from '@svgrid/grid'
+ *   const pg = createPagination({ page: () => page, pageCount: () => 20, onChange: (p) => (page = p) })
+ * </script>
+ * <nav {...pg.navProps()}>
+ *   <button {...pg.prevProps()}>‹</button>
+ *   {#each pg.items as it}
+ *     {#if typeof it === 'number'}<button {...pg.pageButtonProps(it)}>{it}</button>{:else}…{/if}
+ *   {/each}
+ *   <button {...pg.nextProps()}>›</button>
+ * </nav>
+ * ```
+ */
+import { paginationRange, type PaginationItem } from './paginate'
+
+export type PaginationConfig = {
+  /** 1-based current page. */
+  page: () => number
+  pageCount: () => number
+  onChange?: (page: number) => void
+  siblingCount?: () => number
+  boundaryCount?: () => number
+  disabled?: () => boolean
+}
+
+export function createPagination(config: PaginationConfig) {
+  const page = () => config.page()
+  const pageCount = () => config.pageCount()
+  const disabled = () => config.disabled?.() ?? false
+
+  function go(p: number) {
+    if (disabled()) return
+    const next = Math.min(Math.max(p, 1), pageCount())
+    if (next !== page()) config.onChange?.(next)
+  }
+  const first = () => go(1)
+  const prev = () => go(page() - 1)
+  const next = () => go(page() + 1)
+  const last = () => go(pageCount())
+  const canPrev = () => !disabled() && page() > 1
+  const canNext = () => !disabled() && page() < pageCount()
+
+  return {
+    /** The page/ellipsis sequence to render, recomputed from the live inputs. */
+    get items(): PaginationItem[] {
+      return paginationRange({
+        page: page(),
+        pageCount: pageCount(),
+        siblingCount: config.siblingCount?.() ?? 1,
+        boundaryCount: config.boundaryCount?.() ?? 1,
+      })
+    },
+    go,
+    first,
+    prev,
+    next,
+    last,
+    canPrev,
+    canNext,
+    isActive: (p: number) => p === page(),
+    /** Spread onto the `<nav>` wrapper. */
+    navProps: (ariaLabel = 'Pagination') => ({ 'aria-label': ariaLabel }),
+    /** Spread onto a numbered page button. */
+    pageButtonProps: (p: number) => ({
+      'aria-current': (p === page() ? 'page' : undefined) as 'page' | undefined,
+      'aria-label': `Page ${p}`,
+      disabled: disabled(),
+      onclick: () => go(p),
+    }),
+    firstProps: () => ({ 'aria-label': 'First page', disabled: !canPrev(), onclick: first }),
+    prevProps: () => ({ 'aria-label': 'Previous page', disabled: !canPrev(), onclick: prev }),
+    nextProps: () => ({ 'aria-label': 'Next page', disabled: !canNext(), onclick: next }),
+    lastProps: () => ({ 'aria-label': 'Last page', disabled: !canNext(), onclick: last }),
+  }
+}
+
+export type Pagination = ReturnType<typeof createPagination>

package/src/createPopoverSelect.svelte.ts

@@ -14,6 +14,7 @@
  */
 import { anchoredRect, type AnchoredRect } from './popover'
 import { createDismissableLayer } from './a11y/dismissable'
+import { enabledIndices as enabledIndicesOf, wrapMove } from './list-nav'
 
 let uidSeq = 0
 
@@ -54,16 +55,13 @@ export function createPopoverSelect(config: PopoverSelectConfig) {
 
   let open = $state(false)
   let active = $state(0)
-  let rect = $state<AnchoredRect>({ top: 0, left: 0, width: 0, openUpward: false })
+  let rect = $state<AnchoredRect>({ top: 0, left: 0, width: 0, openUpward: false, maxHeight: 0, availHeight: 0 })
 
   const count = () => config.itemCount()
   const isDisabled = (i: number) => config.disabled?.(i) ?? false
 
   function enabledIndices(): number[] {
-    const out: number[] = []
-    const n = count()
-    for (let i = 0; i < n; i++) if (!isDisabled(i)) out.push(i)
-    return out
+    return enabledIndicesOf(count(), isDisabled)
   }
   function clampActive(i: number): number {
     const n = count()
@@ -88,10 +86,8 @@ export function createPopoverSelect(config: PopoverSelectConfig) {
   }
 
   function move(delta: number) {
-    const list = enabledIndices()
-    if (!list.length) return
-    const pos = list.indexOf(active)
-    active = list[(pos + delta + list.length) % list.length] ?? list[0]!
+    const next = wrapMove(enabledIndices(), active, delta)
+    if (next >= 0) active = next
   }
   function first() { active = enabledIndices()[0] ?? 0 }
   function last() { active = enabledIndices().at(-1) ?? 0 }

package/src/createStepper.test.ts

@@ -0,0 +1,62 @@
+import { describe, expect, it, vi } from 'vitest'
+import { createStepper } from './createStepper'
+
+function make(over: Partial<{ current: number; count: number; linear: boolean }> = {}) {
+  let current = over.current ?? 2
+  const onChange = vi.fn((i: number) => (current = i))
+  const st = createStepper({
+    count: () => over.count ?? 5,
+    current: () => current,
+    onChange,
+    linear: () => over.linear ?? true,
+  })
+  return { st, onChange }
+}
+
+describe('createStepper', () => {
+  it('reports per-step status relative to the current step', () => {
+    const { st } = make({ current: 2 })
+    expect(st.statusOf(0)).toBe('complete')
+    expect(st.statusOf(1)).toBe('complete')
+    expect(st.statusOf(2)).toBe('active')
+    expect(st.statusOf(3)).toBe('upcoming')
+  })
+
+  it('in linear mode only reached steps are clickable', () => {
+    const { st } = make({ current: 2, linear: true })
+    expect(st.clickable(1)).toBe(true) // complete
+    expect(st.clickable(2)).toBe(true) // active
+    expect(st.clickable(3)).toBe(false) // upcoming
+  })
+
+  it('in free mode every step is clickable', () => {
+    const { st } = make({ current: 2, linear: false })
+    expect(st.clickable(4)).toBe(true)
+  })
+
+  it('go() navigates only to clickable, different steps', () => {
+    const { st, onChange } = make({ current: 2, linear: true })
+    st.go(4) // upcoming, blocked in linear mode
+    expect(onChange).not.toHaveBeenCalled()
+    st.go(0) // reached
+    expect(onChange).toHaveBeenLastCalledWith(0)
+    st.go(2) // same as current
+    expect(onChange).toHaveBeenCalledTimes(1)
+  })
+
+  it('prev/next step through (relative to current)', () => {
+    const fwd = make({ current: 2, linear: false })
+    fwd.st.next()
+    expect(fwd.onChange).toHaveBeenLastCalledWith(3)
+    const back = make({ current: 2, linear: false })
+    back.st.prev()
+    expect(back.onChange).toHaveBeenLastCalledWith(1)
+  })
+
+  it('stepButtonProps marks the active step and disables unreachable ones', () => {
+    const { st } = make({ current: 2, linear: true })
+    expect(st.stepButtonProps(2)['aria-current']).toBe('step')
+    expect(st.stepButtonProps(0)['aria-current']).toBeUndefined()
+    expect(st.stepButtonProps(3).disabled).toBe(true)
+  })
+})

package/src/createStepper.ts

@@ -0,0 +1,61 @@
+/**
+ * createStepper - the HEADLESS core behind <SvStepper>: per-step status
+ * (complete / active / upcoming), the linear-vs-free clickability rule, and
+ * navigation, as pure getters + prop-getters. No runes, framework-free, directly
+ * unit-testable.
+ *
+ * ```svelte
+ * <script lang="ts">
+ *   import { createStepper } from '@svgrid/grid'
+ *   const st = createStepper({ count: () => steps.length, current: () => i, onChange: (n) => (i = n) })
+ * </script>
+ * <ol>
+ *   {#each steps as step, idx}
+ *     <li class="is-{st.statusOf(idx)}">
+ *       <button {...st.stepButtonProps(idx)}>{step.label}</button>
+ *     </li>
+ *   {/each}
+ * </ol>
+ * ```
+ */
+export type StepStatus = 'complete' | 'active' | 'upcoming'
+
+export type StepperConfig = {
+  count: () => number
+  /** 0-based index of the active step. */
+  current: () => number
+  onChange?: (index: number) => void
+  /** Only allow navigating to already-reached steps. Default true. */
+  linear?: () => boolean
+}
+
+export function createStepper(config: StepperConfig) {
+  const current = () => config.current()
+  const linear = () => config.linear?.() ?? true
+
+  const statusOf = (i: number): StepStatus =>
+    i < current() ? 'complete' : i === current() ? 'active' : 'upcoming'
+  const clickable = (i: number) => (linear() ? i <= current() : true)
+  const go = (i: number) => {
+    if (clickable(i) && i !== current()) config.onChange?.(i)
+  }
+  const next = () => go(current() + 1)
+  const prev = () => go(current() - 1)
+
+  return {
+    statusOf,
+    clickable,
+    go,
+    next,
+    prev,
+    isActive: (i: number) => i === current(),
+    /** Spread onto a step's button. */
+    stepButtonProps: (i: number) => ({
+      'aria-current': (statusOf(i) === 'active' ? 'step' : undefined) as 'step' | undefined,
+      disabled: !clickable(i),
+      onclick: () => go(i),
+    }),
+  }
+}
+
+export type Stepper = ReturnType<typeof createStepper>

package/src/createTooltip.svelte.ts

@@ -0,0 +1,86 @@
+/**
+ * createTooltip - the HEADLESS core behind <SvTooltip>: the hover/focus open
+ * state machine with a show delay, Escape-to-hide, and the `aria-describedby` /
+ * `role="tooltip"` wiring - as prop-getters you spread onto your own anchor and
+ * tooltip elements. No styles, no positioning (that is a DOM concern the renderer
+ * owns), like `createListbox`.
+ *
+ * ```svelte
+ * <script lang="ts">
+ *   import { createTooltip } from '@svgrid/grid'
+ *   const tip = createTooltip({ text: () => label })
+ * </script>
+ * <span {...tip.anchorProps()}>{@render children?.()}</span>
+ * {#if tip.open}
+ *   <div {...tip.tooltipProps()}>{label}</div>
+ * {/if}
+ * ```
+ */
+import { nextEditorId } from './editor-contract'
+
+export type TooltipConfig = {
+  /** The tooltip text; the tooltip never opens when it is empty. */
+  text?: () => string | undefined
+  /** Suppress the tooltip entirely. */
+  disabled?: () => boolean
+  /** Show delay in ms after hover/focus. Default 300. */
+  delay?: () => number
+}
+
+export type TooltipAnchorProps = {
+  'aria-describedby': string | undefined
+  onpointerenter: () => void
+  onpointerleave: () => void
+  onfocusin: () => void
+  onfocusout: () => void
+}
+
+export type TooltipProps = {
+  id: string
+  role: 'tooltip'
+}
+
+export function createTooltip(config: TooltipConfig = {}) {
+  const id = nextEditorId('sv-tip')
+  let open = $state(false)
+  let showTimer: ReturnType<typeof setTimeout> | undefined
+
+  function show() {
+    if ((config.disabled?.() ?? false) || !(config.text?.() ?? '')) return
+    clearTimeout(showTimer)
+    showTimer = setTimeout(() => { open = true }, config.delay?.() ?? 300)
+  }
+  function hide() {
+    clearTimeout(showTimer)
+    open = false
+  }
+
+  // Escape hides the tooltip while it is open (WAI-ARIA tooltip pattern).
+  $effect(() => {
+    if (!open) return
+    const onKey = (e: KeyboardEvent) => { if (e.key === 'Escape') hide() }
+    document.addEventListener('keydown', onKey)
+    return () => document.removeEventListener('keydown', onKey)
+  })
+
+  return {
+    get open() { return open },
+    /** Stable id of the tooltip element (for `aria-describedby` + the tip's id). */
+    tipId: id,
+    show,
+    hide,
+    /** Spread onto the anchor/trigger wrapper. Also mirror `tipId` onto the real
+     *  focusable child's `aria-describedby` so AT announces it on focus. */
+    anchorProps: (): TooltipAnchorProps => ({
+      'aria-describedby': open ? id : undefined,
+      onpointerenter: show,
+      onpointerleave: hide,
+      onfocusin: show,
+      onfocusout: hide,
+    }),
+    /** Spread onto the tooltip element. */
+    tooltipProps: (): TooltipProps => ({ id, role: 'tooltip' }),
+  }
+}
+
+export type Tooltip = ReturnType<typeof createTooltip>

package/src/datetime/timezone.test.ts

@@ -0,0 +1,69 @@
+import { describe, it, expect } from 'vitest'
+import { zoneParts, zoneOffsetMs, toZonedLocal, fromZonedLocal, instantFromWallClock, normalizeTimeZone } from './timezone'
+
+const H = 3_600_000
+
+describe('timezone utils', () => {
+  // 2026-07-01 12:00 UTC (summer): NY = EDT (-4), Kolkata = +5:30, London = BST (+1)
+  const summer = new Date('2026-07-01T12:00:00Z')
+  // 2026-01-01 12:00 UTC (winter): NY = EST (-5), London = GMT (0)
+  const winter = new Date('2026-01-01T12:00:00Z')
+
+  it('zoneParts gives wall-clock in the target zone', () => {
+    expect(zoneParts(summer, 'America/New_York')).toMatchObject({ hour: 8, minute: 0 })
+    expect(zoneParts(summer, 'Asia/Kolkata')).toMatchObject({ hour: 17, minute: 30 })
+    expect(zoneParts(summer, 'Europe/London')).toMatchObject({ hour: 13, minute: 0 })
+    expect(zoneParts(winter, 'America/New_York')).toMatchObject({ hour: 7 })
+  })
+
+  it('zoneOffsetMs is DST-aware', () => {
+    expect(zoneOffsetMs(summer, 'America/New_York')).toBe(-4 * H)
+    expect(zoneOffsetMs(winter, 'America/New_York')).toBe(-5 * H)
+    expect(zoneOffsetMs(summer, 'Asia/Kolkata')).toBe(5.5 * H)
+    expect(zoneOffsetMs(winter, 'Europe/London')).toBe(0)
+  })
+
+  it('toZonedLocal exposes the zone wall-clock via local getters', () => {
+    const z = toZonedLocal(summer, 'Asia/Kolkata')
+    expect(z.getHours()).toBe(17)
+    expect(z.getMinutes()).toBe(30)
+  })
+
+  it('fromZonedLocal round-trips back to the same instant', () => {
+    for (const tz of ['America/New_York', 'Asia/Kolkata', 'Europe/London', 'Australia/Sydney']) {
+      for (const inst of [summer, winter]) {
+        const back = fromZonedLocal(toZonedLocal(inst, tz), tz)
+        expect(back.getTime()).toBe(Math.floor(inst.getTime() / 1000) * 1000)
+      }
+    }
+  })
+
+  it('instantFromWallClock maps a zone wall-clock to the right instant', () => {
+    // 09:00 in New York on 2026-07-01 (EDT -4) === 13:00 UTC.
+    const inst = instantFromWallClock(2026, 7, 1, 9, 0, 0, 'America/New_York')
+    expect(inst.toISOString()).toBe('2026-07-01T13:00:00.000Z')
+    // 09:00 in Kolkata (+5:30) === 03:30 UTC.
+    expect(instantFromWallClock(2026, 7, 1, 9, 0, 0, 'Asia/Kolkata').toISOString()).toBe('2026-07-01T03:30:00.000Z')
+  })
+
+  it('handles the DST spring-forward edge without drifting', () => {
+    // US spring-forward 2026-03-08: 02:00 EST -> 03:00 EDT. 09:00 that day is EDT (-4).
+    const inst = instantFromWallClock(2026, 3, 8, 9, 0, 0, 'America/New_York')
+    expect(inst.toISOString()).toBe('2026-03-08T13:00:00.000Z')
+    // The round trip is stable for a post-transition instant.
+    const back = fromZonedLocal(toZonedLocal(inst, 'America/New_York'), 'America/New_York')
+    expect(back.getTime()).toBe(inst.getTime())
+  })
+
+  it('undefined zone is the identity (browser local)', () => {
+    expect(toZonedLocal(summer, undefined)).toBe(summer)
+    expect(fromZonedLocal(summer, undefined)).toBe(summer)
+    expect(zoneOffsetMs(summer, undefined)).toBe(-summer.getTimezoneOffset() * 60_000)
+  })
+
+  it('normalizeTimeZone rejects bad ids', () => {
+    expect(normalizeTimeZone('America/New_York')).toBe('America/New_York')
+    expect(normalizeTimeZone('Not/AZone')).toBeUndefined()
+    expect(normalizeTimeZone(undefined)).toBeUndefined()
+  })
+})

package/src/datetime/timezone.ts

@@ -0,0 +1,134 @@
+/**
+ * Pure, framework-free IANA-timezone helpers, built on `Intl` (no date library).
+ *
+ * The scheduler renders in a chosen `timeZone` via a "pseudo-local" trick:
+ * {@link toZonedLocal} turns an absolute instant into a Date whose *local*
+ * wall-clock equals the wall-clock in `timeZone`, so all the existing
+ * local-based date math (startOfDay, minuteOfDay, layout) runs unchanged; then
+ * {@link fromZonedLocal} converts a user edit back to a real instant. When
+ * `timeZone` is undefined every function is the identity on the browser's zone.
+ *
+ * These functions are DST-aware and take no ambient "now" (safe for the model /
+ * headless contexts that forbid `Date.now()`).
+ */
+
+export type ZoneParts = {
+  year: number
+  month: number // 1-12
+  day: number
+  hour: number // 0-23
+  minute: number
+  second: number
+}
+
+const fmtCache = new Map<string, Intl.DateTimeFormat>()
+function partsFormat(timeZone: string): Intl.DateTimeFormat {
+  let f = fmtCache.get(timeZone)
+  if (!f) {
+    f = new Intl.DateTimeFormat('en-US', {
+      timeZone,
+      hourCycle: 'h23',
+      year: 'numeric',
+      month: '2-digit',
+      day: '2-digit',
+      hour: '2-digit',
+      minute: '2-digit',
+      second: '2-digit',
+    })
+    fmtCache.set(timeZone, f)
+  }
+  return f
+}
+
+/** The wall-clock parts of `instant` in `timeZone` (browser-local if undefined). */
+export function zoneParts(instant: Date, timeZone?: string): ZoneParts {
+  if (!timeZone) {
+    return {
+      year: instant.getFullYear(),
+      month: instant.getMonth() + 1,
+      day: instant.getDate(),
+      hour: instant.getHours(),
+      minute: instant.getMinutes(),
+      second: instant.getSeconds(),
+    }
+  }
+  const map: Record<string, number> = {}
+  for (const p of partsFormat(timeZone).formatToParts(instant)) {
+    if (p.type !== 'literal') map[p.type] = Number(p.value)
+  }
+  let hour = map.hour ?? 0
+  if (hour === 24) hour = 0 // some engines emit '24' for midnight under h23
+  return { year: map.year!, month: map.month!, day: map.day!, hour, minute: map.minute ?? 0, second: map.second ?? 0 }
+}
+
+/** Milliseconds `timeZone` is ahead of UTC at `instant` (DST-aware; negative west of UTC). */
+export function zoneOffsetMs(instant: Date, timeZone?: string): number {
+  if (!timeZone) return -instant.getTimezoneOffset() * 60_000
+  const p = zoneParts(instant, timeZone)
+  const asUtc = Date.UTC(p.year, p.month - 1, p.day, p.hour, p.minute, p.second)
+  // `asUtc` reads the wall-clock as if it were UTC; its distance from the real
+  // instant (truncated to whole seconds, matching the parts' resolution) is the offset.
+  return asUtc - Math.floor(instant.getTime() / 1000) * 1000
+}
+
+/** An instant -> a Date whose LOCAL fields equal its wall-clock in `timeZone`. */
+export function toZonedLocal(instant: Date, timeZone?: string): Date {
+  if (!timeZone) return instant
+  const p = zoneParts(instant, timeZone)
+  return new Date(p.year, p.month - 1, p.day, p.hour, p.minute, p.second, instant.getMilliseconds())
+}
+
+/** The instant whose wall-clock in `timeZone` is the given Y-M-D H:M:S. */
+export function instantFromWallClock(
+  year: number,
+  month: number, // 1-12
+  day: number,
+  hour: number,
+  minute: number,
+  second = 0,
+  timeZone?: string,
+  ms = 0,
+): Date {
+  if (!timeZone) return new Date(year, month - 1, day, hour, minute, second, ms)
+  const wallUtc = Date.UTC(year, month - 1, day, hour, minute, second, ms)
+  // Assume the wall-clock is UTC, subtract the offset there, then correct once
+  // in case the candidate instant lands on the other side of a DST transition.
+  const off1 = zoneOffsetMs(new Date(wallUtc), timeZone)
+  let inst = new Date(wallUtc - off1)
+  const off2 = zoneOffsetMs(inst, timeZone)
+  if (off2 !== off1) inst = new Date(wallUtc - off2)
+  return inst
+}
+
+/** Inverse of {@link toZonedLocal}: a pseudo-local Date -> the real instant. */
+export function fromZonedLocal(pseudo: Date, timeZone?: string): Date {
+  if (!timeZone) return pseudo
+  return instantFromWallClock(
+    pseudo.getFullYear(),
+    pseudo.getMonth() + 1,
+    pseudo.getDate(),
+    pseudo.getHours(),
+    pseudo.getMinutes(),
+    pseudo.getSeconds(),
+    timeZone,
+    pseudo.getMilliseconds(),
+  )
+}
+
+/** Short zone name at `instant`, e.g. "EDT" / "GMT+5:30" - for a ruler header. */
+export function zoneAbbr(instant: Date, timeZone?: string): string {
+  if (!timeZone) return ''
+  const parts = new Intl.DateTimeFormat('en-US', { timeZone, hour: '2-digit', timeZoneName: 'short' }).formatToParts(instant)
+  return parts.find((p) => p.type === 'timeZoneName')?.value ?? ''
+}
+
+/** Validate an IANA zone id; returns it if usable, else undefined (falls back to local). */
+export function normalizeTimeZone(timeZone?: string): string | undefined {
+  if (!timeZone) return undefined
+  try {
+    new Intl.DateTimeFormat('en-US', { timeZone })
+    return timeZone
+  } catch {
+    return undefined
+  }
+}

package/src/dock-context.ts

@@ -0,0 +1,47 @@
+/**
+ * Shared context for <SvDockLayout> and its recursive <DockNodeView>. Carries
+ * the pane-content snippet and the handful of callbacks the tree view needs, so
+ * the recursive renderer reaches them without prop-drilling through every level.
+ */
+import type { Snippet } from 'svelte'
+import type { DockPane, DockTabs, DockZone } from './dock-model'
+
+export type DockContext = {
+  /** Renders a pane's content. Called as `{@render pane(dockPane)}`. */
+  pane: Snippet<[DockPane]>
+  /**
+   * Optional stack-header controls for a leaf (maximize / auto-hide / pop-out /
+   * float), rendered once per leaf at the right of its tab strip.
+   */
+  leafActions?: Snippet<[DockTabs]>
+  /** Make tab `index` active in the given leaf. */
+  activate: (tabsId: string, index: number) => void
+  /** Close (remove) a pane. */
+  close: (paneId: string) => void
+  /** Start dragging a pane's tab to re-dock it. */
+  beginDrag: (event: PointerEvent, paneId: string, tabsId: string) => void
+  /** Commit new size weights for a group after a splitter drag. */
+  resize: (groupId: string, sizes: number[]) => void
+  /** Minimum pane size (px) along the split axis. */
+  minSize: () => number
+  /**
+   * The leaf the pointer is over while dragging, for the dock guide. `zone` is
+   * the guide chip under the pointer (drop docks there) or `null` (over the leaf
+   * but off the guide - the drop will float). `centerOnly` shows just the centre
+   * chip (floating windows accept tabs only).
+   */
+  dropTarget: () => { tabsId: string; zone: DockZone | null; centerOnly?: boolean } | null
+  /** The live tab-reorder target, for the insertion-line indicator. */
+  reorderTarget?: () => { tabsId: string; index: number } | null
+  /** Which side of each leaf the tab strip sits on. Default `'top'`. */
+  headerPosition?: () => 'top' | 'bottom' | 'left' | 'right'
+  /** The id of the currently focused leaf, for the active-panel highlight. */
+  focusedLeaf?: () => string | null
+  /** Keep inactive tabs mounted (hidden) so their content state persists. */
+  keepAlive?: () => boolean
+  /** For a single-pane leaf, suppress the redundant tab button (e.g. an auto-hide fly-out,
+   *  where the edge strip already names the panel). Leaf actions still render. */
+  hideSingleTab?: () => boolean
+}
+
+export const DOCK_CONTEXT = Symbol('svgrid-dock')