@svgrid/grid 1.2.34 → 2.0.1

package/src/ui-tier3.test.ts

@@ -0,0 +1,139 @@
+/**
+ * Component tests for the Tier-3 batch: SvRichText, SvCarousel, SvTour.
+ * (execCommand-driven formatting is a no-op in jsdom, so RichText tests cover
+ * structure + value/onChange, not the rendered rich output.)
+ */
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { mount, unmount, flushSync } from 'svelte'
+import SvRichText from './SvRichText.svelte'
+import SvCarousel from './SvCarousel.svelte'
+import SvTour from './SvTour.svelte'
+
+function mountOn(Comp: any, props: Record<string, unknown>) {
+  const target = document.createElement('div')
+  document.body.appendChild(target)
+  const app = mount(Comp, { target, props: props as any })
+  flushSync()
+  return { target, destroy: () => { unmount(app); target.remove() } }
+}
+
+afterEach(() => { document.body.innerHTML = '' })
+
+describe('SvRichText', () => {
+  it('renders a toolbar and an editable region seeded from value', () => {
+    const { target, destroy } = mountOn(SvRichText, { value: '<p>Hello</p>' })
+    try {
+      expect(target.querySelector('.sv-rt__toolbar')).not.toBeNull()
+      expect(target.querySelectorAll('.sv-rt__btn').length).toBeGreaterThan(6)
+      const body = target.querySelector<HTMLElement>('.sv-rt__body')!
+      expect(body.getAttribute('contenteditable')).toBe('true')
+      expect(body.innerHTML).toBe('<p>Hello</p>')
+    } finally { destroy() }
+  })
+
+  it('emits onChange on input', () => {
+    const onChange = vi.fn()
+    const { target, destroy } = mountOn(SvRichText, { value: '', onChange })
+    try {
+      const body = target.querySelector<HTMLElement>('.sv-rt__body')!
+      body.innerHTML = '<b>hi</b>'
+      body.dispatchEvent(new Event('input', { bubbles: true }))
+      expect(onChange).toHaveBeenCalledWith('<b>hi</b>')
+    } finally { destroy() }
+  })
+
+  it('readonly hides the toolbar and disables editing', () => {
+    const { target, destroy } = mountOn(SvRichText, { value: 'x', readonly: true })
+    try {
+      expect(target.querySelector('.sv-rt__toolbar')).toBeNull()
+      expect(target.querySelector('.sv-rt__body')!.getAttribute('contenteditable')).toBe('false')
+    } finally { destroy() }
+  })
+
+  it('honours a custom tools list', () => {
+    const { target, destroy } = mountOn(SvRichText, { value: '', tools: ['bold', 'italic'] })
+    try {
+      expect(target.querySelectorAll('.sv-rt__btn')).toHaveLength(2)
+    } finally { destroy() }
+  })
+})
+
+describe('SvCarousel', () => {
+  const slideProps = { count: 3, slide: undefined as any }
+  // Provide a minimal slide snippet via a wrapper is awkward; render count-only.
+
+  it('renders one slide element per count with arrows + dots', () => {
+    const { target, destroy } = mountOn(SvCarousel, { ...slideProps })
+    try {
+      expect(target.querySelectorAll('.sv-carousel__slide')).toHaveLength(3)
+      expect(target.querySelectorAll('.sv-carousel__dot')).toHaveLength(3)
+      expect(target.querySelector('.sv-carousel__arrow.is-next')).not.toBeNull()
+    } finally { destroy() }
+  })
+
+  it('next advances the active dot (with loop wrap)', () => {
+    const { target, destroy } = mountOn(SvCarousel, { count: 3, current: 0 })
+    try {
+      target.querySelector<HTMLButtonElement>('.sv-carousel__arrow.is-next')!.click()
+      flushSync()
+      const active = [...target.querySelectorAll('.sv-carousel__dot')].findIndex((d) => d.classList.contains('is-active'))
+      expect(active).toBe(1)
+    } finally { destroy() }
+  })
+
+  it('clicking a dot jumps to that slide', () => {
+    const { target, destroy } = mountOn(SvCarousel, { count: 4, current: 0 })
+    try {
+      target.querySelectorAll<HTMLButtonElement>('.sv-carousel__dot')[2]!.click()
+      flushSync()
+      expect(target.querySelectorAll('.sv-carousel__dot')[2]!.classList.contains('is-active')).toBe(true)
+    } finally { destroy() }
+  })
+})
+
+describe('SvTour', () => {
+  const steps = [
+    { title: 'Welcome', content: 'Intro.' },
+    { title: 'Step two', content: 'More.' },
+    { title: 'Done', content: 'Finish.' },
+  ]
+
+  it('shows the first step with a counter and Next', () => {
+    const { destroy } = mountOn(SvTour, { open: true, steps })
+    try {
+      expect(document.body.querySelector('.sv-tour__title')!.textContent).toBe('Welcome')
+      expect(document.body.querySelector('.sv-tour__count')!.textContent).toBe('1 / 3')
+      expect(document.body.querySelector('.sv-tour__back')).toBeNull() // no Back on step 1
+    } finally { destroy() }
+  })
+
+  it('Next advances, Back returns, Done finishes', () => {
+    const onFinish = vi.fn()
+    const { destroy } = mountOn(SvTour, { open: true, steps, onFinish })
+    try {
+      document.body.querySelector<HTMLButtonElement>('.sv-tour__next')!.click()
+      flushSync()
+      expect(document.body.querySelector('.sv-tour__title')!.textContent).toBe('Step two')
+      document.body.querySelector<HTMLButtonElement>('.sv-tour__back')!.click()
+      flushSync()
+      expect(document.body.querySelector('.sv-tour__title')!.textContent).toBe('Welcome')
+      // to the end
+      document.body.querySelector<HTMLButtonElement>('.sv-tour__next')!.click(); flushSync()
+      document.body.querySelector<HTMLButtonElement>('.sv-tour__next')!.click(); flushSync()
+      document.body.querySelector<HTMLButtonElement>('.sv-tour__next')!.click(); flushSync() // Done
+      expect(onFinish).toHaveBeenCalled()
+      expect(document.body.querySelector('.sv-tour__pop')).toBeNull()
+    } finally { destroy() }
+  })
+
+  it('Skip fires onSkip and closes', () => {
+    const onSkip = vi.fn()
+    const { destroy } = mountOn(SvTour, { open: true, steps, onSkip })
+    try {
+      document.body.querySelector<HTMLButtonElement>('.sv-tour__skip')!.click()
+      flushSync()
+      expect(onSkip).toHaveBeenCalled()
+      expect(document.body.querySelector('.sv-tour__pop')).toBeNull()
+    } finally { destroy() }
+  })
+})

package/src/validators.test.ts

@@ -0,0 +1,58 @@
+/**
+ * Tests for the declarative validation-rule library: each builder skips empty
+ * values (except required), enforces its constraint, honors a custom message,
+ * and cross-field compare reads sibling values. runRules returns the first error.
+ */
+import { describe, expect, it } from 'vitest'
+import { rules, runRules, isEmptyValue } from './validators'
+
+describe('validators', () => {
+  it('required flags empty values only', () => {
+    const r = rules.required()
+    expect(r('')).toBeTruthy()
+    expect(r(null)).toBeTruthy()
+    expect(r([])).toBeTruthy()
+    expect(r('x')).toBeNull()
+    expect(isEmptyValue([])).toBe(true)
+  })
+
+  it('format rules pass when empty, fail on bad input', () => {
+    expect(rules.email()('')).toBeNull()
+    expect(rules.email()('nope')).toBeTruthy()
+    expect(rules.email()('a@b.co')).toBeNull()
+    expect(rules.url()('example.com')).toBeNull()
+    expect(rules.pattern(/^\d+$/)('12a')).toBeTruthy()
+    expect(rules.zipCode()('90210')).toBeNull()
+  })
+
+  it('numeric ranges + lengths', () => {
+    expect(rules.min(10)(5)).toBeTruthy()
+    expect(rules.max(10)(11)).toBeTruthy()
+    expect(rules.range(1, 5)(3)).toBeNull()
+    expect(rules.range(1, 5)(9)).toBeTruthy()
+    expect(rules.minLength(3)('ab')).toBeTruthy()
+    expect(rules.stringLength(2, 4)('abc')).toBeNull()
+    expect(rules.integer()(3.5)).toBeTruthy()
+    expect(rules.oneOf(['a', 'b'])('c')).toBeTruthy()
+  })
+
+  it('compare reads a sibling field', () => {
+    const r = rules.compare('password')
+    expect(r('x', { password: 'x' })).toBeNull()
+    expect(r('y', { password: 'x' })).toBeTruthy()
+    expect(rules.compare('age', '>')(20, { age: 18 })).toBeNull()
+  })
+
+  it('custom message overrides the default', () => {
+    expect(rules.required({ message: 'Pick one' })('')).toBe('Pick one')
+    expect(rules.min(5, { message: 'too small' })(1)).toBe('too small')
+  })
+
+  it('runRules returns the first failing message in order', () => {
+    const list = [rules.required(), rules.minLength(4), rules.pattern(/[A-Z]/, { message: 'needs a capital' })]
+    expect(runRules('', list)).toBe('This field is required')
+    expect(runRules('ab', list)).toContain('at least 4')
+    expect(runRules('abcd', list)).toBe('needs a capital')
+    expect(runRules('Abcd', list)).toBeNull()
+  })
+})

package/src/validators.ts

@@ -0,0 +1,105 @@
+/**
+ * validators - a declarative, framework-free validation-rule library for SvForm
+ * (and any editor). Each rule builder returns a `Validator`: a pure function
+ * `(value, allValues?) => errorMessage | null`. Compose them per field; the form
+ * runs them in order and shows the first failure. Parity: Smart `smart.validator`
+ * (required / email / pattern / min / max / range / stringLength / compare ...).
+ *
+ * ```ts
+ * import { rules } from '@svgrid/grid'
+ * const field = { name: 'email', label: 'Email', rules: [rules.required(), rules.email()] }
+ * ```
+ */
+export type Validator = (value: any, values?: Record<string, any>) => string | null | undefined
+export type RuleOptions = { message?: string }
+export type CompareOp = '==' | '===' | '!=' | '<' | '<=' | '>' | '>='
+
+const EMAIL_RE = /^[^@\s]+@[^@\s]+\.[^@\s]+$/
+const URL_RE = /^(https?:\/\/)?([\w-]+\.)+[\w-]{2,}(\/\S*)?$/i
+const ZIP_RE = /^\d{5}(-\d{4})?$/
+
+/** Empty for validation purposes: null/undefined, '', or an empty array. */
+export function isEmptyValue(v: any): boolean {
+  return v == null || v === '' || (Array.isArray(v) && v.length === 0)
+}
+
+function compareOk(a: any, b: any, op: CompareOp): boolean {
+  switch (op) {
+    case '==': return a == b // eslint-disable-line eqeqeq
+    case '===': return a === b
+    case '!=': return a != b // eslint-disable-line eqeqeq
+    case '<': return Number(a) < Number(b)
+    case '<=': return Number(a) <= Number(b)
+    case '>': return Number(a) > Number(b)
+    case '>=': return Number(a) >= Number(b)
+  }
+}
+
+/** The declarative rule builders. Every builder skips empty values (except
+ *  `required`) so optional fields validate format only when filled. */
+export const rules = {
+  required: (o?: RuleOptions): Validator => (v) =>
+    isEmptyValue(v) ? o?.message ?? 'This field is required' : null,
+
+  email: (o?: RuleOptions): Validator => (v) =>
+    isEmptyValue(v) || EMAIL_RE.test(String(v)) ? null : o?.message ?? 'Enter a valid email address',
+
+  url: (o?: RuleOptions): Validator => (v) =>
+    isEmptyValue(v) || URL_RE.test(String(v)) ? null : o?.message ?? 'Enter a valid URL',
+
+  zipCode: (o?: RuleOptions): Validator => (v) =>
+    isEmptyValue(v) || ZIP_RE.test(String(v)) ? null : o?.message ?? 'Enter a valid ZIP code',
+
+  pattern: (re: RegExp, o?: RuleOptions): Validator => (v) =>
+    isEmptyValue(v) || re.test(String(v)) ? null : o?.message ?? 'Invalid format',
+
+  numeric: (o?: RuleOptions): Validator => (v) =>
+    isEmptyValue(v) || !isNaN(Number(v)) ? null : o?.message ?? 'Must be a number',
+
+  integer: (o?: RuleOptions): Validator => (v) =>
+    isEmptyValue(v) || Number.isInteger(Number(v)) ? null : o?.message ?? 'Must be a whole number',
+
+  min: (n: number, o?: RuleOptions): Validator => (v) =>
+    isEmptyValue(v) || Number(v) >= n ? null : o?.message ?? `Must be at least ${n}`,
+
+  max: (n: number, o?: RuleOptions): Validator => (v) =>
+    isEmptyValue(v) || Number(v) <= n ? null : o?.message ?? `Must be at most ${n}`,
+
+  range: (lo: number, hi: number, o?: RuleOptions): Validator => (v) =>
+    isEmptyValue(v) || (Number(v) >= lo && Number(v) <= hi) ? null : o?.message ?? `Must be between ${lo} and ${hi}`,
+
+  minLength: (n: number, o?: RuleOptions): Validator => (v) =>
+    isEmptyValue(v) || String(v).length >= n ? null : o?.message ?? `Must be at least ${n} characters`,
+
+  maxLength: (n: number, o?: RuleOptions): Validator => (v) =>
+    isEmptyValue(v) || String(v).length <= n ? null : o?.message ?? `Must be at most ${n} characters`,
+
+  stringLength: (lo: number, hi: number, o?: RuleOptions): Validator => (v) =>
+    isEmptyValue(v) || (String(v).length >= lo && String(v).length <= hi)
+      ? null
+      : o?.message ?? `Must be ${lo}-${hi} characters`,
+
+  oneOf: (allowed: ReadonlyArray<string | number>, o?: RuleOptions): Validator => (v) =>
+    isEmptyValue(v) || allowed.includes(v) ? null : o?.message ?? 'Invalid choice',
+
+  /** Compare against another field's value (cross-field): e.g. confirm password. */
+  compare: (otherField: string, op: CompareOp = '===', o?: RuleOptions): Validator => (v, values) =>
+    compareOk(v, values?.[otherField], op) ? null : o?.message ?? 'Values do not match',
+
+  /** Wrap an arbitrary predicate/function as a rule. */
+  custom: (fn: Validator): Validator => fn,
+}
+
+/** Run a list of rules against a value; return the first error message, or null. */
+export function runRules(
+  value: any,
+  ruleList: ReadonlyArray<Validator> | undefined,
+  values?: Record<string, any>,
+): string | null {
+  if (!ruleList) return null
+  for (const rule of ruleList) {
+    const err = rule(value, values)
+    if (err) return err
+  }
+  return null
+}

package/src/virtual.test.ts

@@ -0,0 +1,72 @@
+/**
+ * Tests for the fixed-row windowing helper and SvListBox `virtual` mode: a huge
+ * option set renders only a small window (plus spacer rows), and itemTemplate
+ * customizes the row.
+ */
+import { describe, expect, it } from 'vitest'
+import { mount, unmount, flushSync, createRawSnippet } from 'svelte'
+import SvListBox from './SvListBox.svelte'
+import { virtualRange, scrollToIndex } from './virtual'
+
+describe('virtualRange', () => {
+  it('returns the visible window + spacer heights for a fixed-row list', () => {
+    const r = virtualRange({ scrollTop: 0, viewportHeight: 320, rowHeight: 32, count: 1000, overscan: 2 })
+    expect(r.start).toBe(0)
+    expect(r.totalHeight).toBe(32000)
+    expect(r.padTop).toBe(0)
+    // ~10 visible + 2 overscan.
+    expect(r.end).toBeLessThanOrEqual(14)
+    expect(r.padBottom).toBe((1000 - r.end) * 32)
+  })
+  it('scrolls the window when scrolled down', () => {
+    const r = virtualRange({ scrollTop: 3200, viewportHeight: 320, rowHeight: 32, count: 1000, overscan: 2 })
+    expect(r.start).toBe(98) // floor(3200/32)=100, minus overscan 2
+    expect(r.padTop).toBe(98 * 32)
+  })
+  it('handles empty + zero-height gracefully', () => {
+    expect(virtualRange({ scrollTop: 0, viewportHeight: 100, rowHeight: 32, count: 0 })).toMatchObject({ start: 0, end: 0, totalHeight: 0 })
+    expect(virtualRange({ scrollTop: 0, viewportHeight: 100, rowHeight: 0, count: 5 }).totalHeight).toBe(0)
+  })
+})
+
+describe('scrollToIndex', () => {
+  it('scrolls up to an item above and down to an item below the viewport', () => {
+    expect(scrollToIndex(2, 320, 320, 32)).toBe(64)          // item 2 above -> its top
+    expect(scrollToIndex(20, 0, 320, 32)).toBe(20 * 32 + 32 - 320) // item 20 below -> bottom-align
+    expect(scrollToIndex(5, 100, 320, 32)).toBe(100)         // already visible -> unchanged
+  })
+})
+
+describe('SvListBox virtual', () => {
+  it('renders only a small window of a huge list', () => {
+    const options = Array.from({ length: 5000 }, (_, i) => ({ value: i, label: `Item ${i}` }))
+    const target = document.createElement('div')
+    document.body.appendChild(target)
+    const app = mount(SvListBox, { target, props: { options, virtual: true } as any })
+    flushSync()
+    try {
+      const rendered = target.querySelectorAll('.sv-listbox__opt').length
+      expect(rendered).toBeGreaterThan(0)
+      expect(rendered).toBeLessThan(60) // nowhere near 5000
+      // A fixed-height sizer keeps the scrollbar honest.
+      const sizer = target.querySelector<HTMLElement>('.sv-listbox__sizer')!
+      expect(sizer).not.toBeNull()
+      expect(sizer.style.height).toBe(`${5000 * 32}px`)
+    } finally { unmount(app); target.remove() }
+  })
+
+  it('renders a custom itemTemplate per option', () => {
+    const options = [{ value: 'a', label: 'Apple' }, { value: 'b', label: 'Banana' }]
+    const itemTemplate = createRawSnippet((opt: () => { label: string }) => ({
+      render: () => `<span class="tpl">${opt().label.toUpperCase()}</span>`,
+    }))
+    const target = document.createElement('div')
+    document.body.appendChild(target)
+    const app = mount(SvListBox, { target, props: { options, itemTemplate } as any })
+    flushSync()
+    try {
+      const tpls = [...target.querySelectorAll('.tpl')].map((n) => n.textContent)
+      expect(tpls).toEqual(['APPLE', 'BANANA'])
+    } finally { unmount(app); target.remove() }
+  })
+})

package/src/virtual.ts

@@ -0,0 +1,67 @@
+/**
+ * virtual - a tiny, framework-free fixed-row windowing helper shared by the
+ * selection controls so their option lists scale to tens of thousands of rows
+ * without rendering them all. The renderer measures the viewport + tracks
+ * scrollTop (DOM concerns) and passes them in; this returns the slice to render
+ * plus the top/bottom spacer heights that keep the scrollbar honest.
+ */
+export type VirtualRange = {
+  /** First item index to render (inclusive). */
+  start: number
+  /** Last item index to render (exclusive). */
+  end: number
+  /** Spacer height above the rendered slice (px). */
+  padTop: number
+  /** Spacer height below the rendered slice (px). */
+  padBottom: number
+  /** Total scrollable height of all rows (px). */
+  totalHeight: number
+}
+
+export type VirtualParams = {
+  scrollTop: number
+  viewportHeight: number
+  rowHeight: number
+  count: number
+  /** Extra rows rendered above/below the viewport to avoid blank flashes. */
+  overscan?: number
+}
+
+/** Compute the visible window for a fixed-row-height list (pure). */
+export function virtualRange(params: VirtualParams): VirtualRange {
+  const { scrollTop, viewportHeight, rowHeight, count } = params
+  const overscan = params.overscan ?? 6
+  const total = Math.max(0, count) * Math.max(0, rowHeight)
+  if (rowHeight <= 0 || count <= 0) {
+    return { start: 0, end: Math.max(0, count), padTop: 0, padBottom: 0, totalHeight: total }
+  }
+  const first = Math.floor(Math.max(0, scrollTop) / rowHeight)
+  const start = Math.max(0, first - overscan)
+  const visible = Math.max(1, Math.ceil(Math.max(0, viewportHeight) / rowHeight))
+  const end = Math.min(count, first + visible + overscan)
+  return {
+    start,
+    end,
+    padTop: start * rowHeight,
+    padBottom: Math.max(0, (count - end) * rowHeight),
+    totalHeight: total,
+  }
+}
+
+/**
+ * The scrollTop that brings item `index` fully into a fixed-row viewport,
+ * scrolling the least amount (returns the current scrollTop if already visible).
+ * Pure - the renderer applies it to the element.
+ */
+export function scrollToIndex(
+  index: number,
+  scrollTop: number,
+  viewportHeight: number,
+  rowHeight: number,
+): number {
+  const top = index * rowHeight
+  const bottom = top + rowHeight
+  if (top < scrollTop) return top
+  if (bottom > scrollTop + viewportHeight) return bottom - viewportHeight
+  return scrollTop
+}