@svgrid/grid 1.2.22 → 1.2.24

package/src/createTree.svelte.ts

@@ -0,0 +1,216 @@
+/**
+ * createTree - the HEADLESS core behind <SvTree>, in the same spirit as
+ * `createSvGrid` for the grid: a runes-based state machine (expand/collapse,
+ * single-select highlight, cascading tri-state checkboxes, full keyboard) with
+ * **prop-getters** you spread onto YOUR OWN markup. The visible tree is
+ * flattened into `rows` so roving-focus keyboard nav stays a flat index walk.
+ *
+ * ```svelte
+ * <script lang="ts">
+ *   import { createTree } from '@svgrid/grid'
+ *   let selected = $state<string | null>(null)
+ *   const tree = createTree({ nodes: () => nodes, selected: () => selected, onSelect: (id) => (selected = id) })
+ * </script>
+ * <div {...tree.treeProps()}>
+ *   {#each tree.rows as row (row.node.id)}
+ *     <div {...tree.itemProps(row)}>{row.node.label}</div>
+ *   {/each}
+ * </div>
+ * ```
+ *
+ * The styled <SvTree> is just one renderer over this core. The cascade math
+ * (`treeDescendantIds`, `treeCheckState`) is exported as pure functions.
+ */
+export type TreeNode = {
+  id: string
+  label: string
+  children?: TreeNode[]
+  disabled?: boolean
+}
+
+export type CheckState = 'checked' | 'indeterminate' | 'unchecked'
+
+/** A single visible (flattened) tree row. */
+export type TreeRow = {
+  node: TreeNode
+  depth: number
+  hasChildren: boolean
+  open: boolean
+  parentId: string | null
+  index: number
+}
+
+/** All descendant ids of `node` (pure, depth-first). */
+export function treeDescendantIds(node: TreeNode): string[] {
+  const ids: string[] = []
+  const walk = (n: TreeNode) => { for (const c of n.children ?? []) { ids.push(c.id); walk(c) } }
+  walk(node)
+  return ids
+}
+
+/** Tri-state check status of `node` given the set of checked ids (pure). */
+export function treeCheckState(node: TreeNode, checked: ReadonlySet<string>): CheckState {
+  if (!node.children?.length) return checked.has(node.id) ? 'checked' : 'unchecked'
+  const desc = treeDescendantIds(node)
+  const on = desc.filter((id) => checked.has(id)).length
+  if (on === 0 && !checked.has(node.id)) return 'unchecked'
+  if (on === desc.length) return 'checked'
+  return 'indeterminate'
+}
+
+function findNode(list: ReadonlyArray<TreeNode>, id: string): TreeNode | null {
+  for (const n of list) {
+    if (n.id === id) return n
+    if (n.children) { const f = findNode(n.children, id); if (f) return f }
+  }
+  return null
+}
+
+/** Reactive inputs are passed as getters so the core tracks live prop changes. */
+export type TreeConfig = {
+  nodes: () => ReadonlyArray<TreeNode>
+  selected?: () => string | null
+  onSelect?: (id: string) => void
+  /** Seed the internally-managed expanded set (read once). */
+  expandedIds?: () => string[] | undefined
+  onToggle?: (id: string, expanded: boolean) => void
+  checkable?: () => boolean
+  checked?: () => string[]
+  onCheck?: (ids: string[]) => void
+  ariaLabel?: () => string | undefined
+}
+
+export function createTree(config: TreeConfig) {
+  const nodes = () => config.nodes()
+  const checkable = () => config.checkable?.() ?? false
+  const selected = () => config.selected?.() ?? null
+
+  // Internal expanded set, seeded from the prop once (then self-managed).
+  let expanded = $state<Set<string>>(new Set())
+  let seeded = false
+  $effect(() => {
+    if (!seeded) { seeded = true; const ids = config.expandedIds?.(); if (ids) expanded = new Set(ids) }
+  })
+
+  const rows = $derived.by<TreeRow[]>(() => {
+    const out: TreeRow[] = []
+    const walk = (list: ReadonlyArray<TreeNode>, depth: number, parentId: string | null) => {
+      for (const node of list) {
+        const hasChildren = !!node.children?.length
+        const open = expanded.has(node.id)
+        out.push({ node, depth, hasChildren, open, parentId, index: out.length })
+        if (hasChildren && open) walk(node.children!, depth + 1, node.id)
+      }
+    }
+    walk(nodes(), 0, null)
+    return out
+  })
+
+  let active = $state(0)
+  $effect(() => { if (active >= rows.length) active = Math.max(0, rows.length - 1) })
+
+  const checkedSet = $derived(new Set(config.checked?.() ?? []))
+
+  // Roving focus target; `focusTick` bumps only on keyboard moves.
+  let focusTick = $state(0)
+  function setActive(i: number, focus = false) { active = i; if (focus) focusTick++ }
+
+  const checkStateOf = (node: TreeNode): CheckState => treeCheckState(node, checkedSet)
+  const isExpanded = (id: string) => expanded.has(id)
+  const isSelected = (id: string) => id === selected()
+
+  function toggleExpand(node: TreeNode) {
+    if (!node.children?.length) return
+    const next = new Set(expanded)
+    const willOpen = !next.has(node.id)
+    willOpen ? next.add(node.id) : next.delete(node.id)
+    expanded = next
+    config.onToggle?.(node.id, willOpen)
+  }
+  const toggle = (id: string) => { const n = findNode(nodes(), id); if (n) toggleExpand(n) }
+
+  function select(node: TreeNode) {
+    if (node.disabled) return
+    config.onSelect?.(node.id)
+  }
+  const selectId = (id: string) => { const n = findNode(nodes(), id); if (n) select(n) }
+
+  function toggleCheck(node: TreeNode) {
+    if (node.disabled) return
+    const next = new Set(checkedSet)
+    const ids = [node.id, ...treeDescendantIds(node)]
+    const currentlyOn = checkStateOf(node) === 'checked'
+    for (const id of ids) currentlyOn ? next.delete(id) : next.add(id)
+    config.onCheck?.([...next])
+  }
+
+  function onKeydown(e: KeyboardEvent) {
+    const item = rows[active]
+    if (!item) return
+    switch (e.key) {
+      case 'ArrowDown': e.preventDefault(); setActive(Math.min(active + 1, rows.length - 1), true); break
+      case 'ArrowUp': e.preventDefault(); setActive(Math.max(active - 1, 0), true); break
+      case 'ArrowRight':
+        e.preventDefault()
+        if (item.hasChildren && !item.open) toggleExpand(item.node)
+        else if (item.hasChildren && item.open) setActive(Math.min(active + 1, rows.length - 1), true)
+        break
+      case 'ArrowLeft':
+        e.preventDefault()
+        if (item.hasChildren && item.open) toggleExpand(item.node)
+        else if (item.parentId) { const pi = rows.findIndex((r) => r.node.id === item.parentId); if (pi >= 0) setActive(pi, true) }
+        break
+      case 'Enter': e.preventDefault(); select(item.node); break
+      case ' ': e.preventDefault(); checkable() ? toggleCheck(item.node) : select(item.node); break
+      case 'Home': e.preventDefault(); setActive(0, true); break
+      case 'End': e.preventDefault(); setActive(rows.length - 1, true); break
+    }
+  }
+
+  return {
+    /** Internally-managed set of expanded node ids. */
+    get expanded() { return expanded },
+    /** Selected node id (single-select highlight). */
+    get selected() { return selected() },
+    /** Flattened list of visible rows. */
+    get rows() { return rows },
+    /** Roving-focus row index. */
+    get activeIndex() { return active },
+    /** Monotonic counter; changes only on keyboard navigation. */
+    get focusTick() { return focusTick },
+    isExpanded,
+    isSelected,
+    checkStateOf,
+    toggle,
+    toggleExpand,
+    select: selectId,
+    toggleCheck,
+    setActive,
+    onKeydown,
+    /** Spread onto the tree container element. */
+    treeProps: () => ({
+      role: 'tree' as const,
+      'aria-label': config.ariaLabel?.(),
+      'aria-multiselectable': checkable(),
+    }),
+    /** Spread onto the treeitem element for a flattened `row`. */
+    itemProps: (row: TreeRow) => {
+      const cs = checkable() ? checkStateOf(row.node) : 'unchecked'
+      const ariaChecked: 'true' | 'mixed' | 'false' | undefined =
+        checkable() ? (cs === 'checked' ? 'true' : cs === 'indeterminate' ? 'mixed' : 'false') : undefined
+      return {
+        role: 'treeitem' as const,
+        'aria-level': row.depth + 1,
+        'aria-selected': row.node.id === selected(),
+        'aria-expanded': row.hasChildren ? row.open : undefined,
+        'aria-checked': ariaChecked,
+        'data-row': row.index,
+        tabindex: row.index === active ? 0 : -1,
+        onclick: () => { setActive(row.index); select(row.node) },
+        onkeydown: onKeydown,
+      }
+    },
+  }
+}
+
+export type Tree = ReturnType<typeof createTree>

package/src/datetime/date-core.test.ts

@@ -0,0 +1,217 @@
+/**
+ * Unit tests for date-core math. These are written to be *discriminating*: each
+ * asserts a value that a plausible mutation (off-by-one, wrong operator, dropped
+ * clamp) would break - not just "does not throw".
+ */
+import { describe, expect, it } from 'vitest'
+import {
+  toDate,
+  startOfDay,
+  startOfMonth,
+  endOfMonth,
+  daysInMonth,
+  startOfWeek,
+  isSameDay,
+  isSameMonth,
+  compareDay,
+  addDays,
+  addMonths,
+  addYears,
+  clampDate,
+  isoWeek,
+  decadeRange,
+  centuryRange,
+  monthMatrix,
+  weekdayOrder,
+  withTime,
+  snapMinute,
+} from './date-core'
+
+describe('toDate', () => {
+  it('passes through valid Date/number/string and clones Dates', () => {
+    const d = new Date(2026, 5, 15)
+    const out = toDate(d)!
+    expect(out.getTime()).toBe(d.getTime())
+    expect(out).not.toBe(d) // clone, not same ref
+    expect(toDate(d.getTime())!.getTime()).toBe(d.getTime())
+    expect(toDate('2026-06-15T00:00:00')!.getFullYear()).toBe(2026)
+  })
+  it('returns null for null/undefined/invalid', () => {
+    expect(toDate(null)).toBeNull()
+    expect(toDate(undefined)).toBeNull()
+    expect(toDate('not-a-date')).toBeNull()
+    expect(toDate(NaN)).toBeNull()
+  })
+})
+
+describe('startOfDay / month boundaries', () => {
+  it('strips time to local midnight', () => {
+    const d = startOfDay(new Date(2026, 2, 9, 13, 45, 30, 500))
+    expect([d.getHours(), d.getMinutes(), d.getSeconds(), d.getMilliseconds()]).toEqual([0, 0, 0, 0])
+    expect(d.getDate()).toBe(9)
+  })
+  it('startOfMonth / endOfMonth / daysInMonth', () => {
+    const mid = new Date(2026, 1, 14) // Feb 2026 (28 days)
+    expect(startOfMonth(mid).getDate()).toBe(1)
+    expect(endOfMonth(mid).getDate()).toBe(28)
+    expect(daysInMonth(mid)).toBe(28)
+    expect(daysInMonth(new Date(2024, 1, 1))).toBe(29) // leap year
+    expect(daysInMonth(new Date(2026, 0, 1))).toBe(31)
+  })
+})
+
+describe('startOfWeek', () => {
+  it('honors firstDayOfWeek=0 (Sunday)', () => {
+    // 2026-06-15 is a Monday.
+    const s = startOfWeek(new Date(2026, 5, 15), 0)
+    expect(s.getDay()).toBe(0)
+    expect(s.getDate()).toBe(14) // the Sunday before
+  })
+  it('honors firstDayOfWeek=1 (Monday)', () => {
+    const s = startOfWeek(new Date(2026, 5, 15), 1)
+    expect(s.getDay()).toBe(1)
+    expect(s.getDate()).toBe(15) // Monday itself
+  })
+  it('wraps correctly when day < firstDayOfWeek', () => {
+    // Sunday 2026-06-14 with week starting Monday -> previous Monday (Jun 8)
+    const s = startOfWeek(new Date(2026, 5, 14), 1)
+    expect(s.getDate()).toBe(8)
+  })
+})
+
+describe('sameness + comparison', () => {
+  it('isSameDay ignores time, isSameMonth ignores day', () => {
+    expect(isSameDay(new Date(2026, 5, 15, 9), new Date(2026, 5, 15, 23))).toBe(true)
+    expect(isSameDay(new Date(2026, 5, 15), new Date(2026, 5, 16))).toBe(false)
+    expect(isSameDay(null, new Date())).toBe(false)
+    expect(isSameMonth(new Date(2026, 5, 1), new Date(2026, 5, 30))).toBe(true)
+    expect(isSameMonth(new Date(2026, 5, 30), new Date(2026, 6, 1))).toBe(false)
+  })
+  it('compareDay returns -1/0/1 by day', () => {
+    expect(compareDay(new Date(2026, 5, 15, 23), new Date(2026, 5, 15, 1))).toBe(0)
+    expect(compareDay(new Date(2026, 5, 14), new Date(2026, 5, 15))).toBe(-1)
+    expect(compareDay(new Date(2026, 5, 16), new Date(2026, 5, 15))).toBe(1)
+  })
+})
+
+describe('addDays / addMonths / addYears clamping', () => {
+  it('addDays crosses month boundary', () => {
+    expect(addDays(new Date(2026, 0, 31), 1).getMonth()).toBe(1) // -> Feb 1
+    expect(addDays(new Date(2026, 5, 15), -20).getMonth()).toBe(4) // -> May
+  })
+  it('addMonths clamps day-of-month (Jan 31 + 1mo = Feb 28)', () => {
+    const r = addMonths(new Date(2026, 0, 31), 1)
+    expect(r.getMonth()).toBe(1)
+    expect(r.getDate()).toBe(28) // NOT March 3
+  })
+  it('addMonths preserves time-of-day', () => {
+    const r = addMonths(new Date(2026, 0, 15, 8, 30), 2)
+    expect([r.getHours(), r.getMinutes()]).toEqual([8, 30])
+    expect(r.getMonth()).toBe(2)
+  })
+  it('addYears clamps Feb 29 -> Feb 28 on non-leap target', () => {
+    const r = addYears(new Date(2024, 1, 29), 1)
+    expect(r.getFullYear()).toBe(2025)
+    expect(r.getMonth()).toBe(1)
+    expect(r.getDate()).toBe(28)
+  })
+})
+
+describe('clampDate', () => {
+  const min = new Date(2026, 0, 1)
+  const max = new Date(2026, 11, 31)
+  it('clamps below min and above max, passes through inside', () => {
+    expect(clampDate(new Date(2025, 5, 1), min, max).getTime()).toBe(min.getTime())
+    expect(clampDate(new Date(2027, 5, 1), min, max).getTime()).toBe(max.getTime())
+    const inside = new Date(2026, 5, 1)
+    expect(clampDate(inside, min, max).getTime()).toBe(inside.getTime())
+  })
+  it('treats null bounds as open', () => {
+    const d = new Date(1000, 0, 1)
+    expect(clampDate(d, null, null).getTime()).toBe(d.getTime())
+  })
+})
+
+describe('isoWeek', () => {
+  it('matches known ISO week numbers', () => {
+    // 2026-01-01 is a Thursday -> ISO week 1.
+    expect(isoWeek(new Date(2026, 0, 1))).toBe(1)
+    // 2026-06-15 (Mon) -> ISO week 25.
+    expect(isoWeek(new Date(2026, 5, 15))).toBe(25)
+    // 2027-01-01 is a Friday -> belongs to ISO week 53 of 2026.
+    expect(isoWeek(new Date(2027, 0, 1))).toBe(53)
+    // 2024-12-30 (Mon) -> ISO week 1 of 2025.
+    expect(isoWeek(new Date(2024, 11, 30))).toBe(1)
+  })
+})
+
+describe('decadeRange / centuryRange', () => {
+  it('decade block anchors to the base-10 start', () => {
+    expect(decadeRange(2026)).toEqual({ start: 2020, end: 2029 })
+    expect(decadeRange(2020)).toEqual({ start: 2020, end: 2029 })
+    expect(decadeRange(2019)).toEqual({ start: 2010, end: 2019 })
+  })
+  it('century block anchors to the base-100 start', () => {
+    expect(centuryRange(2026)).toEqual({ start: 2000, end: 2099 })
+    expect(centuryRange(1999)).toEqual({ start: 1900, end: 1999 })
+  })
+})
+
+describe('monthMatrix', () => {
+  it('produces weeks x 7 cells starting on firstDayOfWeek', () => {
+    const m = monthMatrix(new Date(2026, 5, 15), 0, 6) // June 2026, Sunday-first
+    expect(m.length).toBe(6)
+    expect(m.every((row) => row.length === 7)).toBe(true)
+    // Every first cell of a row is the configured first weekday.
+    expect(m.every((row) => row[0]!.date.getDay() === 0)).toBe(true)
+    // June 1 2026 is a Monday, so the grid starts on Sunday May 31.
+    expect(m[0]![0]!.date.getMonth()).toBe(4)
+    expect(m[0]![0]!.date.getDate()).toBe(31)
+    expect(m[0]![0]!.inMonth).toBe(false)
+    expect(m[0]![1]!.inMonth).toBe(true) // June 1
+    expect(m[0]![1]!.date.getDate()).toBe(1)
+  })
+  it('honors firstDayOfWeek=1 (Monday-first grid)', () => {
+    const m = monthMatrix(new Date(2026, 5, 15), 1, 6)
+    expect(m.every((row) => row[0]!.date.getDay() === 1)).toBe(true)
+    // June 1 2026 is Monday, so the first cell IS June 1.
+    expect(m[0]![0]!.date.getDate()).toBe(1)
+    expect(m[0]![0]!.inMonth).toBe(true)
+  })
+  it('tags cells with an ISO week number', () => {
+    const m = monthMatrix(new Date(2026, 0, 1), 1, 6)
+    expect(m[0]![0]!.week).toBe(isoWeek(m[0]![0]!.date))
+  })
+})
+
+describe('weekdayOrder', () => {
+  it('rotates the 0-6 sequence by firstDayOfWeek', () => {
+    expect(weekdayOrder(0)).toEqual([0, 1, 2, 3, 4, 5, 6])
+    expect(weekdayOrder(1)).toEqual([1, 2, 3, 4, 5, 6, 0])
+    expect(weekdayOrder(6)).toEqual([6, 0, 1, 2, 3, 4, 5])
+  })
+})
+
+describe('withTime', () => {
+  it('grafts time-of-day onto a calendar day', () => {
+    const day = new Date(2026, 5, 15)
+    const time = new Date(2000, 0, 1, 14, 25, 9, 123)
+    const r = withTime(day, time)
+    expect([r.getFullYear(), r.getMonth(), r.getDate()]).toEqual([2026, 5, 15])
+    expect([r.getHours(), r.getMinutes(), r.getSeconds(), r.getMilliseconds()]).toEqual([14, 25, 9, 123])
+  })
+})
+
+describe('snapMinute', () => {
+  it('snaps down to the nearest interval multiple', () => {
+    expect(snapMinute(0, 15)).toBe(0)
+    expect(snapMinute(14, 15)).toBe(0)
+    expect(snapMinute(15, 15)).toBe(15)
+    expect(snapMinute(59, 15)).toBe(45)
+    expect(snapMinute(37, 5)).toBe(35)
+  })
+  it('interval < 1 behaves as 1 (no snapping)', () => {
+    expect(snapMinute(37, 0)).toBe(37)
+    expect(snapMinute(37, 1)).toBe(37)
+  })
+})

package/src/datetime/date-core.ts

@@ -0,0 +1,204 @@
+/**
+ * date-core - framework-free date math shared by SvCalendar, SvTimePicker and
+ * SvDateTimePicker. No Svelte, no DOM: pure functions over the native `Date`
+ * so it is trivially unit- and mutation-testable and reusable standalone.
+ *
+ * Conventions:
+ * - A "day" is compared by local calendar date (year/month/date), ignoring the
+ *   time-of-day, unless a helper says otherwise.
+ * - `firstDayOfWeek` is 0-6 (0 = Sunday), matching `Date.getDay()` and Smart's
+ *   `firstDayOfWeek`.
+ */
+
+export type DateLike = Date | number | string
+
+/** Coerce a Date | epoch-ms | parseable string to a Date, or null if invalid. */
+export function toDate(value: DateLike | null | undefined): Date | null {
+  if (value == null) return null
+  const d = value instanceof Date ? new Date(value.getTime()) : new Date(value)
+  return isNaN(d.getTime()) ? null : d
+}
+
+/** A new Date at local midnight of the same calendar day (time stripped). */
+export function startOfDay(d: Date): Date {
+  return new Date(d.getFullYear(), d.getMonth(), d.getDate())
+}
+
+/** First day (midnight) of the month `d` falls in. */
+export function startOfMonth(d: Date): Date {
+  return new Date(d.getFullYear(), d.getMonth(), 1)
+}
+
+/** Last day (midnight) of the month `d` falls in. */
+export function endOfMonth(d: Date): Date {
+  return new Date(d.getFullYear(), d.getMonth() + 1, 0)
+}
+
+/** Number of days in the month `d` falls in. */
+export function daysInMonth(d: Date): number {
+  return endOfMonth(d).getDate()
+}
+
+/**
+ * Start of the week containing `d`, honoring `firstDayOfWeek` (0-6). Returns a
+ * local-midnight Date on or before `d`.
+ */
+export function startOfWeek(d: Date, firstDayOfWeek = 0): Date {
+  const start = startOfDay(d)
+  const diff = (start.getDay() - firstDayOfWeek + 7) % 7
+  start.setDate(start.getDate() - diff)
+  return start
+}
+
+/** True when both dates are the same local calendar day. */
+export function isSameDay(a: Date | null, b: Date | null): boolean {
+  if (!a || !b) return false
+  return (
+    a.getFullYear() === b.getFullYear() &&
+    a.getMonth() === b.getMonth() &&
+    a.getDate() === b.getDate()
+  )
+}
+
+/** True when both dates are in the same year+month. */
+export function isSameMonth(a: Date | null, b: Date | null): boolean {
+  if (!a || !b) return false
+  return a.getFullYear() === b.getFullYear() && a.getMonth() === b.getMonth()
+}
+
+/** -1 / 0 / 1 comparison by calendar day (time-of-day ignored). */
+export function compareDay(a: Date, b: Date): number {
+  const av = startOfDay(a).getTime()
+  const bv = startOfDay(b).getTime()
+  return av < bv ? -1 : av > bv ? 1 : 0
+}
+
+/** Add `n` days (can be negative), returning a new Date. */
+export function addDays(d: Date, n: number): Date {
+  const r = new Date(d.getTime())
+  r.setDate(r.getDate() + n)
+  return r
+}
+
+/**
+ * Add `n` calendar months, clamping the day-of-month so 31 Jan + 1 month = 28/29
+ * Feb rather than spilling into March (matches how calendars paginate).
+ */
+export function addMonths(d: Date, n: number): Date {
+  const day = d.getDate()
+  const r = new Date(d.getFullYear(), d.getMonth() + n, 1, d.getHours(), d.getMinutes(), d.getSeconds(), d.getMilliseconds())
+  r.setDate(Math.min(day, daysInMonth(r)))
+  return r
+}
+
+/** Add `n` years, clamping Feb-29 to Feb-28 on non-leap targets. */
+export function addYears(d: Date, n: number): Date {
+  return addMonths(d, n * 12)
+}
+
+/** Clamp `d` to the inclusive [min, max] range (either bound may be null). */
+export function clampDate(d: Date, min: Date | null, max: Date | null): Date {
+  if (min && d.getTime() < min.getTime()) return new Date(min.getTime())
+  if (max && d.getTime() > max.getTime()) return new Date(max.getTime())
+  return d
+}
+
+/**
+ * ISO 8601 week number (1-53) for `d`. Week 1 is the week containing the first
+ * Thursday of the year; weeks start Monday. Independent of `firstDayOfWeek`,
+ * matching Smart's `weekNumbers` column which is always ISO.
+ */
+export function isoWeek(d: Date): number {
+  // Shift to the Thursday of this week, then count weeks from Jan 1.
+  const date = startOfDay(d)
+  const day = (date.getDay() + 6) % 7 // Mon=0..Sun=6
+  date.setDate(date.getDate() - day + 3) // Thursday of this week
+  const firstThursday = new Date(date.getFullYear(), 0, 4)
+  const firstDay = (firstThursday.getDay() + 6) % 7
+  firstThursday.setDate(firstThursday.getDate() - firstDay + 3)
+  const diffMs = date.getTime() - firstThursday.getTime()
+  return 1 + Math.round(diffMs / (7 * 24 * 3600 * 1000))
+}
+
+/**
+ * The [start, end] years of the decade block that `year` belongs to, as Smart
+ * renders it: a 12-cell page running from the decade start minus 1 to plus 10
+ * (one leading + one trailing year for context). We expose the canonical
+ * decade [Y0, Y0+9] and let the view pad.
+ */
+export function decadeRange(year: number): { start: number; end: number } {
+  const start = Math.floor(year / 10) * 10
+  return { start, end: start + 9 }
+}
+
+/** The [start, end] years of the century block (100-year) `year` belongs to. */
+export function centuryRange(year: number): { start: number; end: number } {
+  const start = Math.floor(year / 100) * 100
+  return { start, end: start + 99 }
+}
+
+export type MonthMatrixCell = {
+  date: Date
+  /** In the displayed month (vs. leading/trailing days of adjacent months). */
+  inMonth: boolean
+  /** ISO week number of the row this cell sits in. */
+  week: number
+}
+
+/**
+ * Build a month grid of `weeks` rows x 7 columns starting at `firstDayOfWeek`,
+ * padded with the trailing days of the previous month and leading days of the
+ * next so every row is full. `weeks` defaults to 6 (the max any month needs),
+ * matching Smart's fixed-height calendar.
+ */
+export function monthMatrix(
+  monthDate: Date,
+  firstDayOfWeek = 0,
+  weeks = 6,
+): MonthMatrixCell[][] {
+  const first = startOfMonth(monthDate)
+  const gridStart = startOfWeek(first, firstDayOfWeek)
+  const rows: MonthMatrixCell[][] = []
+  let cursor = gridStart
+  for (let r = 0; r < weeks; r++) {
+    const row: MonthMatrixCell[] = []
+    const weekNo = isoWeek(cursor)
+    for (let c = 0; c < 7; c++) {
+      row.push({
+        date: cursor,
+        inMonth: cursor.getMonth() === first.getMonth() && cursor.getFullYear() === first.getFullYear(),
+        week: weekNo,
+      })
+      cursor = addDays(cursor, 1)
+    }
+    rows.push(row)
+  }
+  return rows
+}
+
+/**
+ * Ordered weekday indexes (0-6) for a header row starting at `firstDayOfWeek`.
+ * e.g. firstDayOfWeek=1 -> [1,2,3,4,5,6,0].
+ */
+export function weekdayOrder(firstDayOfWeek = 0): number[] {
+  return Array.from({ length: 7 }, (_, i) => (firstDayOfWeek + i) % 7)
+}
+
+/** Merge a calendar day with a time-of-day taken from `time`, returning a new Date. */
+export function withTime(day: Date, time: Date): Date {
+  return new Date(
+    day.getFullYear(),
+    day.getMonth(),
+    day.getDate(),
+    time.getHours(),
+    time.getMinutes(),
+    time.getSeconds(),
+    time.getMilliseconds(),
+  )
+}
+
+/** Snap a minute value to the nearest lower multiple of `interval` (>=1). */
+export function snapMinute(minute: number, interval: number): number {
+  const step = Math.max(1, Math.floor(interval))
+  return Math.floor(minute / step) * step
+}