@svgrid/grid 1.0.0

package/src/createGrid.svelte.ts

@@ -0,0 +1,42 @@
+import { createSvGridCore } from './core'
+import type {
+  RowData,
+  SvGrid,
+  SvGridOptions,
+  TableFeatures,
+} from './core'
+
+export type SvelteGrid<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+  TSelected = {},
+> = SvGrid<TData> & {
+  readonly state: Readonly<TSelected>
+}
+
+export function createSvGrid<
+  TFeatures extends TableFeatures,
+  TData extends RowData,
+  TSelected = {},
+>(
+  gridOptions: SvGridOptions<TFeatures, TData>,
+  selector: (state: Record<string, any>) => TSelected = () => ({}) as TSelected,
+): SvelteGrid<TFeatures, TData, TSelected> {
+  const grid = createSvGridCore(gridOptions) as SvelteGrid<TFeatures, TData, TSelected>
+  let selected = $state(selector(grid.store.state))
+  grid.store.subscribe(() => {
+    selected = selector(grid.store.state)
+  })
+
+  Object.defineProperty(grid, 'state', {
+    get() {
+      return selected
+    },
+    configurable: true,
+    enumerable: true,
+  })
+
+  return grid
+}
+
+export const createGrid = createSvGrid

package/src/createGrid.test.ts

@@ -0,0 +1,10 @@
+import { describe, expect, it } from 'vitest'
+import { createGridState } from './index'
+
+describe('createGrid', () => {
+  it('createGridState updates controlled values', () => {
+    const [sorting, setSorting] = createGridState([{ id: 'age', desc: false }])
+    setSorting((prev) => prev.map((entry) => ({ ...entry, desc: true })))
+    expect(sorting()[0]?.desc).toBe(true)
+  })
+})

package/src/createGridState.svelte.ts

@@ -0,0 +1,17 @@
+import type { Updater } from './core'
+
+export function createGridState<TState>(
+  initialValue: TState,
+): [() => TState, (updater: Updater<TState>) => void] {
+  let value = $state(initialValue)
+
+  return [
+    () => value,
+    (updater: Updater<TState>) => {
+      if (updater instanceof Function) value = updater(value)
+      else value = updater
+    },
+  ]
+}
+
+export const createSvGridState = createGridState

package/src/editors/cell-editors.test.ts

@@ -0,0 +1,80 @@
+import { describe, expect, it } from 'vitest'
+import { parseEditorValue } from './cell-editors'
+
+describe('parseEditorValue - number', () => {
+  it('parses a valid string', () => {
+    expect(parseEditorValue('number', '42')).toBe(42)
+  })
+  it('parses a numeric value as-is', () => {
+    expect(parseEditorValue('number', 42)).toBe(42)
+  })
+  it('returns null for non-numeric input', () => {
+    expect(parseEditorValue('number', 'bad')).toBe(null)
+    expect(parseEditorValue('number', NaN)).toBe(null)
+  })
+  it('returns null for Infinity', () => {
+    expect(parseEditorValue('number', Infinity)).toBe(null)
+  })
+  it('handles empty string as null', () => {
+    expect(parseEditorValue('number', '')).toBe(0)
+  })
+})
+
+describe('parseEditorValue - date', () => {
+  it('returns an ISO string for a valid date', () => {
+    const result = parseEditorValue('date', '2026-01-01')
+    expect(typeof result).toBe('string')
+    expect(String(result)).toContain('2026-01-01')
+  })
+  it('returns null for an unparseable string', () => {
+    expect(parseEditorValue('date', 'not-a-date')).toBe(null)
+  })
+  it('accepts a Date object via its string form', () => {
+    const result = parseEditorValue('date', new Date('2026-05-30T00:00:00Z'))
+    expect(String(result)).toContain('2026-05-30')
+  })
+})
+
+describe('parseEditorValue - datetime', () => {
+  it('returns an ISO string for a valid datetime input', () => {
+    const result = parseEditorValue('datetime', '2026-01-01T10:30')
+    expect(typeof result).toBe('string')
+    expect(String(result)).toContain('2026-01-01')
+  })
+  it('returns null for invalid datetime input', () => {
+    expect(parseEditorValue('datetime', 'bogus')).toBe(null)
+  })
+})
+
+describe('parseEditorValue - checkbox', () => {
+  it('returns booleans as-is', () => {
+    expect(parseEditorValue('checkbox', true)).toBe(true)
+    expect(parseEditorValue('checkbox', false)).toBe(false)
+  })
+  it('parses "true"/"false" strings case-insensitively', () => {
+    expect(parseEditorValue('checkbox', 'true')).toBe(true)
+    expect(parseEditorValue('checkbox', 'TRUE')).toBe(true)
+    expect(parseEditorValue('checkbox', 'false')).toBe(false)
+    expect(parseEditorValue('checkbox', 'False')).toBe(false)
+  })
+  it('treats other strings as false', () => {
+    expect(parseEditorValue('checkbox', 'yes')).toBe(false)
+    expect(parseEditorValue('checkbox', '1')).toBe(false)
+    expect(parseEditorValue('checkbox', '')).toBe(false)
+  })
+  it('coerces numbers via String() (non-"true" → false)', () => {
+    expect(parseEditorValue('checkbox', 1)).toBe(false)
+    expect(parseEditorValue('checkbox', 0)).toBe(false)
+  })
+})
+
+describe('parseEditorValue - text (default)', () => {
+  it('returns the string form of a value', () => {
+    expect(parseEditorValue('text', 'hello')).toBe('hello')
+    expect(parseEditorValue('text', 42)).toBe('42')
+  })
+  it('coerces null/undefined to empty string', () => {
+    expect(parseEditorValue('text', null)).toBe('')
+    expect(parseEditorValue('text', undefined)).toBe('')
+  })
+})

package/src/editors/cell-editors.ts

@@ -0,0 +1,127 @@
+export type CellEditorType =
+  | 'text'
+  | 'number'
+  | 'date'
+  | 'datetime'
+  | 'time'
+  | 'password'
+  | 'checkbox'
+  | 'list'
+  | 'chips'
+  | 'select'
+  | 'rich-select'
+  | 'textarea'
+  | 'color'
+  | 'rating'
+
+/** Normalized option used by list/chips editors. The optional `color`
+ *  paints the chip - both in the in-cell readonly chips render and in
+ *  the dropdown trigger when `renderChipsInTrigger` is on. Any CSS
+ *  color works (hex, rgb, hsl, oklch, named); the chip uses a soft
+ *  tint built via `color-mix` so it sits well on both themes. */
+export type CellEditorOption = { value: string | number; label: string; color?: string }
+
+export type ParseEditorValueOptions = {
+  /** When true, list/chips return an array; otherwise a scalar. */
+  multiple?: boolean
+}
+
+/** Normalize the loose `editorOptions` ColumnDef prop into a uniform shape.
+ *  Dynamic (function) editorOptions are resolved before reaching here. */
+export function normalizeEditorOptions(
+  options:
+    | ReadonlyArray<
+        string | number | { value: string | number; label?: string; color?: string }
+      >
+    | undefined,
+): CellEditorOption[] {
+  if (!options || typeof options === 'function') return []
+  return options.map((opt) => {
+    if (typeof opt === 'string' || typeof opt === 'number') {
+      return { value: opt, label: String(opt) }
+    }
+    return {
+      value: opt.value,
+      label: opt.label ?? String(opt.value),
+      color: opt.color,
+    }
+  })
+}
+
+export function parseEditorValue(
+  type: CellEditorType,
+  value: unknown,
+  opts?: ParseEditorValueOptions,
+) {
+  if (type === 'number') {
+    const parsed = Number(value)
+    return Number.isFinite(parsed) ? parsed : null
+  }
+  if (type === 'rating') {
+    const parsed = Number(value)
+    if (!Number.isFinite(parsed)) return 0
+    return Math.max(0, Math.min(5, Math.round(parsed)))
+  }
+  if (type === 'color') {
+    const s = String(value ?? '').trim()
+    // Native <input type="color"> always returns "#rrggbb"; if anything
+    // else comes in (CSS name, rgb()), pass it through unchanged so the
+    // caller can keep whatever color string they had.
+    return s || '#000000'
+  }
+  if (type === 'date') {
+    const date = new Date(String(value))
+    return Number.isNaN(date.getTime()) ? null : date.toISOString()
+  }
+  if (type === 'datetime') {
+    const date = new Date(String(value))
+    return Number.isNaN(date.getTime()) ? null : date.toISOString()
+  }
+  if (type === 'time') {
+    // Native `<input type="time">` returns "HH:MM" (or "HH:MM:SS"). Accept
+    // anything that parses to that shape; reject malformed strings as
+    // `null` so consumers can distinguish "cleared" from "never set".
+    const s = String(value ?? '').trim()
+    if (!s) return null
+    const m = s.match(/^(\d{1,2}):(\d{2})(?::(\d{2}))?$/)
+    if (!m) return null
+    const h  = Math.max(0, Math.min(23, parseInt(m[1]!, 10)))
+    const mm = Math.max(0, Math.min(59, parseInt(m[2]!, 10)))
+    const ss = m[3] ? Math.max(0, Math.min(59, parseInt(m[3]!, 10))) : null
+    const HH = String(h).padStart(2, '0')
+    const MM = String(mm).padStart(2, '0')
+    return ss === null ? `${HH}:${MM}` : `${HH}:${MM}:${String(ss).padStart(2, '0')}`
+  }
+  if (type === 'password') {
+    // Password is just a string with masked rendering. Empty string is a
+    // legitimate value (user cleared the field); keep it instead of nulling.
+    return String(value ?? '')
+  }
+  if (type === 'checkbox') {
+    if (typeof value === 'boolean') return value
+    return String(value).toLowerCase() === 'true'
+  }
+  if (type === 'select' || type === 'rich-select') {
+    // Single-select: trust the editor's reported value; coerce nullish
+    // to `null` so consumers can disambiguate "user cleared" from "user
+    // never picked".
+    if (Array.isArray(value)) return value[0] ?? null
+    return value ?? null
+  }
+  if (type === 'textarea') {
+    return String(value ?? '')
+  }
+  if (type === 'list' || type === 'chips') {
+    // The editor manages the value shape: a scalar for single-select, an
+    // array for multi-select. Trust what the editor handed us, just coerce
+    // the shape so consumers can rely on the contract.
+    if (opts?.multiple) {
+      if (Array.isArray(value)) return value.slice()
+      if (value == null || value === '') return []
+      return [value]
+    }
+    if (Array.isArray(value)) return value[0] ?? null
+    return value ?? null
+  }
+  return String(value ?? '')
+}

package/src/fill-patterns.test.ts

@@ -0,0 +1,93 @@
+import { describe, expect, it } from 'vitest'
+import { buildFillPattern } from './fill-patterns'
+
+describe('buildFillPattern - numeric', () => {
+  it('extrapolates an arithmetic progression', () => {
+    expect(buildFillPattern([1, 2, 3], 3)).toEqual([4, 5, 6])
+    expect(buildFillPattern([10, 20, 30], 2)).toEqual([40, 50])
+    expect(buildFillPattern([100, 90, 80], 3)).toEqual([70, 60, 50])
+  })
+
+  it('repeats a single numeric value (Excel default)', () => {
+    expect(buildFillPattern([42], 4)).toEqual([42, 42, 42, 42])
+  })
+})
+
+describe('buildFillPattern - known sequences', () => {
+  it('extends days of the week with wrap', () => {
+    expect(buildFillPattern(['Monday', 'Tuesday'], 3)).toEqual([
+      'Wednesday',
+      'Thursday',
+      'Friday',
+    ])
+  })
+
+  it('preserves source casing', () => {
+    expect(buildFillPattern(['JAN', 'FEB'], 2)).toEqual(['MAR', 'APR'])
+    expect(buildFillPattern(['jan', 'feb'], 2)).toEqual(['mar', 'apr'])
+  })
+
+  it('extends quarters with wrap', () => {
+    expect(buildFillPattern(['Q3', 'Q4'], 3)).toEqual(['Q1', 'Q2', 'Q3'])
+  })
+})
+
+describe('buildFillPattern - chips / array values', () => {
+  it('cycles array values across target cells', () => {
+    const source = [['feature', 'editors']]
+    const result = buildFillPattern(source, 3)
+    expect(result).toEqual([
+      ['feature', 'editors'],
+      ['feature', 'editors'],
+      ['feature', 'editors'],
+    ])
+  })
+
+  it('returns INDEPENDENT copies of arrays so a later mutation to one filled cell does not bleed into siblings', () => {
+    const source = [['feature', 'editors']]
+    const result = buildFillPattern(source, 3) as string[][]
+    // Mutate one - siblings must not change.
+    result[0]!.push('bug')
+    expect(result[1]).toEqual(['feature', 'editors'])
+    expect(result[2]).toEqual(['feature', 'editors'])
+  })
+
+  it('cycles multi-cell array source', () => {
+    const source = [['a'], ['b'], ['c']]
+    const result = buildFillPattern(source, 4)
+    expect(result).toEqual([['a'], ['b'], ['c'], ['a']])
+  })
+})
+
+describe('buildFillPattern - prefix/number/suffix', () => {
+  it('extrapolates "Item N" series', () => {
+    expect(buildFillPattern(['Item 1', 'Item 2'], 3)).toEqual([
+      'Item 3',
+      'Item 4',
+      'Item 5',
+    ])
+  })
+
+  it('preserves zero-padding width', () => {
+    expect(buildFillPattern(['Run-001', 'Run-002'], 2)).toEqual([
+      'Run-003',
+      'Run-004',
+    ])
+  })
+})
+
+describe('buildFillPattern - fallback cycle', () => {
+  it('cycles plain string list when no sequence/progression detected', () => {
+    expect(buildFillPattern(['red', 'green', 'blue'], 5)).toEqual([
+      'red',
+      'green',
+      'blue',
+      'red',
+      'green',
+    ])
+  })
+
+  it('repeats a single non-numeric string', () => {
+    expect(buildFillPattern(['hello'], 3)).toEqual(['hello', 'hello', 'hello'])
+  })
+})

package/src/fill-patterns.ts

@@ -0,0 +1,229 @@
+/**
+ * Pattern detection + extrapolation for the cell-range fill handle.
+ *
+ * Recognized patterns, in priority order:
+ *
+ *   1. Known sequences (case-insensitive): days of the week (Monday /
+ *      Mon), months (January / Jan), quarters (Q1..Q4). When source
+ *      values match a sequence and form an arithmetic progression of
+ *      indices into it, we extrapolate by stepping through the sequence
+ *      with wrap-around. Output case is matched to the source - UPPER,
+ *      lower, or Title.
+ *
+ *   2. Prefix-number-suffix patterns: "Item 1", "Item 2" → "Item 3";
+ *      "2024-Q1", "2024-Q2" → "2024-Q3". The shared prefix + suffix is
+ *      preserved and the number is extrapolated.
+ *
+ *   3. Pure numeric arithmetic progression: 1, 2, 3 → 4, 5, 6; or
+ *      100, 200, 300 → 400, 500, 600.
+ *
+ *   4. Fallback: cycle the source values across the new cells.
+ *
+ * A single source value falls through to the cycle case (repeats), which
+ * matches Excel's default fill behavior.
+ */
+
+/** Lookup table for the named sequences we know how to extrapolate.
+ *  Add new ones (zodiac signs, planets, …) and the rest of the code
+ *  handles them automatically. */
+const KNOWN_SEQUENCES: ReadonlyArray<ReadonlyArray<string>> = [
+  // Days of the week, long
+  ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday'],
+  // Days of the week, short
+  ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'],
+  // Months, long
+  ['January', 'February', 'March', 'April', 'May', 'June',
+   'July', 'August', 'September', 'October', 'November', 'December'],
+  // Months, short
+  ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
+   'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'],
+  // Quarters
+  ['Q1', 'Q2', 'Q3', 'Q4'],
+]
+
+/** Determine the "case style" of a string and project it onto another. */
+function matchCase(target: string, sample: string): string {
+  if (!sample) return target
+  if (sample === sample.toUpperCase() && sample !== sample.toLowerCase()) {
+    return target.toUpperCase()
+  }
+  if (sample === sample.toLowerCase() && sample !== sample.toUpperCase()) {
+    return target.toLowerCase()
+  }
+  // Title case: first letter upper, rest lower.
+  const first = sample[0]
+  if (first && first === first.toUpperCase() && sample.slice(1) === sample.slice(1).toLowerCase()) {
+    return target[0]!.toUpperCase() + target.slice(1).toLowerCase()
+  }
+  return target
+}
+
+/** Find a known sequence (case-insensitively) that contains every source
+ *  value. Returns the sequence + each source's index inside it. */
+function findSequenceMatch(values: ReadonlyArray<string>): {
+  sequence: ReadonlyArray<string>
+  indices: number[]
+} | null {
+  const lowered = values.map((v) => v.toLowerCase())
+  outer: for (const sequence of KNOWN_SEQUENCES) {
+    const lowSeq = sequence.map((s) => s.toLowerCase())
+    const indices: number[] = []
+    for (const v of lowered) {
+      const idx = lowSeq.indexOf(v)
+      if (idx < 0) continue outer
+      indices.push(idx)
+    }
+    return { sequence, indices }
+  }
+  return null
+}
+
+/** Step a series of indices by `step` modulo the sequence length, then
+ *  return the canonical sequence entries with the source's case
+ *  projected onto them. */
+function extrapolateSequence(
+  match: { sequence: ReadonlyArray<string>; indices: number[] },
+  sourceValues: ReadonlyArray<string>,
+  step: number,
+  targetCount: number,
+): string[] {
+  const seqLen = match.sequence.length
+  const lastIdx = match.indices[match.indices.length - 1]!
+  const caseSample = sourceValues[sourceValues.length - 1]!
+  const out: string[] = []
+  for (let i = 0; i < targetCount; i += 1) {
+    const nextIdx = ((lastIdx + step * (i + 1)) % seqLen + seqLen) % seqLen
+    out.push(matchCase(match.sequence[nextIdx]!, caseSample))
+  }
+  return out
+}
+
+/** Split a value into a shared prefix, a numeric body, and a shared
+ *  suffix. Returns null if not all values fit a `prefix + number +
+ *  suffix` shape with the same prefix and suffix. */
+function findPrefixNumberSuffix(values: ReadonlyArray<string>):
+  | { prefix: string; suffix: string; numbers: number[]; numberFormat: { width: number; padChar: '0' | ' ' | '' } }
+  | null {
+  // Capture leading non-digit run, the digit run, and trailing run.
+  // We do NOT match a leading minus inside the digit group - that turns
+  // strings like "Run-001" into prefix="Run", numStr="-001", which both
+  // breaks zero-pad detection AND extrapolates downward instead of up.
+  // True numeric negatives are already handled by the arithmetic-progression
+  // branch above; strings get a literal `-` as part of the prefix.
+  const parts: Array<{ prefix: string; numStr: string; suffix: string }> = []
+  const pattern = /^(.*?)(\d+)(.*)$/
+  for (const v of values) {
+    const m = v.match(pattern)
+    if (!m) return null
+    parts.push({ prefix: m[1] ?? '', numStr: m[2] ?? '', suffix: m[3] ?? '' })
+  }
+  const prefix = parts[0]!.prefix
+  const suffix = parts[0]!.suffix
+  for (const p of parts) {
+    if (p.prefix !== prefix || p.suffix !== suffix) return null
+  }
+  // Detect zero-padding from the first numeric chunk so generated
+  // values match (e.g. "001", "002" → "003").
+  const firstNum = parts[0]!.numStr
+  const width = firstNum.length
+  const padChar: '0' | ' ' | '' =
+    firstNum.length > 1 && firstNum[0] === '0' && firstNum !== '0' ? '0' : ''
+  return {
+    prefix,
+    suffix,
+    numbers: parts.map((p) => Number(p.numStr)),
+    numberFormat: { width, padChar },
+  }
+}
+
+function formatPaddedNumber(
+  n: number,
+  format: { width: number; padChar: '0' | ' ' | '' },
+): string {
+  const raw = String(n)
+  if (!format.padChar || raw.length >= format.width) return raw
+  const padded = raw.padStart(format.width, format.padChar)
+  // padStart can over-pad if the number's sign character was included
+  // in the width; that's fine in practice for fill scenarios.
+  return padded
+}
+
+/** Detect a constant arithmetic step across an array. Returns the step
+ *  or null if values aren't equally spaced. */
+function arithmeticStep(nums: ReadonlyArray<number>): number | null {
+  if (nums.length < 2) return null
+  const step = nums[1]! - nums[0]!
+  for (let i = 2; i < nums.length; i += 1) {
+    if (nums[i]! - nums[i - 1]! !== step) return null
+  }
+  return step
+}
+
+/**
+ * Compute the values to write into `targetCount` new cells given the
+ * `sourceValues` already in the selection. See module header for the
+ * pattern-detection rules.
+ */
+export function buildFillPattern(
+  sourceValues: ReadonlyArray<unknown>,
+  targetCount: number,
+): unknown[] {
+  if (sourceValues.length === 0 || targetCount <= 0) return []
+
+  // -------- 1) Numeric arithmetic progression (2+ values) -----------
+  const nums = sourceValues.map((v) => Number(v))
+  const allNumericLike =
+    sourceValues.every((v) => v !== null && v !== '' && v !== undefined) &&
+    nums.every((n) => Number.isFinite(n))
+  if (allNumericLike && sourceValues.length >= 2) {
+    const step = arithmeticStep(nums)
+    if (step !== null) {
+      const last = nums[nums.length - 1]!
+      return Array.from({ length: targetCount }, (_, i) => last + step * (i + 1))
+    }
+  }
+
+  // -------- 2) Known string sequence (days / months / quarters) -----
+  const allStrings = sourceValues.every((v) => typeof v === 'string')
+  if (allStrings && sourceValues.length >= 1) {
+    const stringSources = sourceValues as string[]
+    const match = findSequenceMatch(stringSources)
+    if (match) {
+      const step = stringSources.length >= 2
+        ? arithmeticStep(match.indices) ?? 1
+        : 1
+      return extrapolateSequence(match, stringSources, step, targetCount)
+    }
+  }
+
+  // -------- 3) Prefix-number-suffix ("Item 1", "Item 2", …) ---------
+  if (allStrings && sourceValues.length >= 1) {
+    const stringSources = sourceValues as string[]
+    const split = findPrefixNumberSuffix(stringSources)
+    if (split) {
+      const step = split.numbers.length >= 2
+        ? arithmeticStep(split.numbers) ?? 1
+        : 1
+      const last = split.numbers[split.numbers.length - 1]!
+      return Array.from({ length: targetCount }, (_, i) => {
+        const next = last + step * (i + 1)
+        return split.prefix + formatPaddedNumber(next, split.numberFormat) + split.suffix
+      })
+    }
+  }
+
+  // -------- 4) Fallback: cycle the sources -------------------------
+  // Deep-clone arrays / plain objects so each filled cell gets an
+  // independent value - otherwise multi-value cells (chips columns
+  // store arrays) would all point at the SAME array, and editing one
+  // would silently mutate the others.
+  return Array.from({ length: targetCount }, (_, i) => cloneFillValue(sourceValues[i % sourceValues.length]))
+}
+
+function cloneFillValue(value: unknown): unknown {
+  if (Array.isArray(value)) return value.slice()
+  if (value && typeof value === 'object' && (value as object).constructor === Object) {
+    return { ...(value as Record<string, unknown>) }
+  }
+  return value
+}