@svgrid/grid 1.2.34 → 2.0.1

package/src/builtin-editors.grid.test.ts

@@ -0,0 +1,85 @@
+/**
+ * End-to-end: after registerBuiltinEditors(), a column with editorType 'duration'
+ * mounts SvDurationInput in the editing cell (proving the built-in registration +
+ * the SvGrid registry wiring together).
+ */
+import { afterEach, describe, expect, it } from 'vitest'
+import { mount, unmount } from 'svelte'
+import SvGrid from './SvGrid.svelte'
+import {
+  registerBuiltinEditors,
+  unregisterCellEditor,
+  registeredCellEditorTypes,
+  createCoreRowModel,
+  createFilteredRowModel,
+  createPaginatedRowModel,
+  createSortedRowModel,
+  sortFns,
+  tableFeatures,
+  columnFilteringFeature,
+  rowSortingFeature,
+} from './index'
+import type { ColumnDef, SvGridApi } from './index'
+
+type Row = { id: number; task: string; estimate: number }
+
+const features = tableFeatures({ columnFilteringFeature, rowSortingFeature })
+const rows: Row[] = [
+  { id: 1, task: 'Design', estimate: 90 },
+  { id: 2, task: 'Build', estimate: 240 },
+]
+const cols: ColumnDef<typeof features, Row>[] = [
+  { field: 'task', header: 'Task', width: 200, editorType: 'text' },
+  { field: 'estimate', header: 'Estimate', width: 160, editorType: 'duration' },
+]
+
+const tick = () => new Promise<void>((r) => queueMicrotask(r))
+
+function mountGrid() {
+  return new Promise<{ api: SvGridApi<typeof features, Row>; target: HTMLElement; destroy: () => void }>(
+    (res) => {
+      const target = document.createElement('div')
+      document.body.appendChild(target)
+      const app = mount(SvGrid, {
+        target,
+        props: {
+          data: rows,
+          columns: cols,
+          features,
+          _rowModels: {
+            coreRowModel: createCoreRowModel(),
+            filteredRowModel: createFilteredRowModel(),
+            sortedRowModel: createSortedRowModel(sortFns),
+            paginatedRowModel: createPaginatedRowModel(),
+          },
+          rowHeight: 36,
+          containerHeight: 300,
+          virtualization: false,
+          enableInlineEditing: true,
+          onApiReady(api: SvGridApi<typeof features, Row>) {
+            res({ api, target, destroy: () => { unmount(app); target.remove() } })
+          },
+        } as any,
+      })
+    },
+  )
+}
+
+afterEach(() => {
+  for (const t of registeredCellEditorTypes()) unregisterCellEditor(t)
+})
+
+describe('registerBuiltinEditors in SvGrid', () => {
+  it("mounts SvDurationInput for an editorType 'duration' cell", async () => {
+    registerBuiltinEditors()
+    const { api, target, destroy } = await mountGrid()
+    try {
+      api.startEditing(0, 'estimate')
+      await tick()
+      await tick()
+      expect(target.querySelector('.sv-dur')).not.toBeNull()
+    } finally {
+      destroy()
+    }
+  })
+})

package/src/builtin-editors.test.ts

@@ -0,0 +1,58 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { registerBuiltinEditors } from './builtin-editors'
+import {
+  getCellEditor,
+  hasCellEditor,
+  unregisterCellEditor,
+  registeredCellEditorTypes,
+  resolveEditorProps,
+  type CellEditorContext,
+} from './editor-registry'
+
+function ctx(overrides: Partial<CellEditorContext> = {}): CellEditorContext {
+  return {
+    value: null,
+    rowId: 'r1',
+    columnId: 'c1',
+    onChange: () => {},
+    onCommit: () => {},
+    onCancel: () => {},
+    ...overrides,
+  }
+}
+
+afterEach(() => {
+  for (const t of registeredCellEditorTypes()) unregisterCellEditor(t)
+})
+
+describe('registerBuiltinEditors', () => {
+  it('registers the config-free editor types', () => {
+    const types = registerBuiltinEditors()
+    expect(types).toEqual(['otp', 'duration'])
+    expect(hasCellEditor('otp')).toBe(true)
+    expect(hasCellEditor('duration')).toBe(true)
+  })
+
+  it("maps the OTP editor's onComplete to commit", () => {
+    registerBuiltinEditors()
+    const onCommit = vi.fn(), onChange = vi.fn()
+    const props = resolveEditorProps(getCellEditor('otp')!, ctx({ value: '12', onChange, onCommit }))
+    expect(props.value).toBe('12')
+    expect(props.autofocus).toBe(true)
+    ;(props.onComplete as (v: string) => void)('123456')
+    expect(onCommit).toHaveBeenCalledWith('123456')
+    ;(props.onChange as (v: string) => void)('1')
+    expect(onChange).toHaveBeenCalledWith('1')
+  })
+
+  it('maps the duration editor commit/cancel through the context', () => {
+    registerBuiltinEditors()
+    const onCommit = vi.fn(), onCancel = vi.fn()
+    const props = resolveEditorProps(getCellEditor('duration')!, ctx({ value: 90, onCommit, onCancel }))
+    expect(props.value).toBe(90)
+    ;(props.onCommit as (v: number | null) => void)(120)
+    expect(onCommit).toHaveBeenCalledWith(120)
+    ;(props.onCancel as () => void)()
+    expect(onCancel).toHaveBeenCalled()
+  })
+})

package/src/builtin-editors.ts

@@ -0,0 +1,56 @@
+/**
+ * builtin-editors - opt-in registration of the configuration-free UI-kit editors
+ * as grid cell editors, so a column can use `editorType: 'otp'` or
+ * `editorType: 'duration'` out of the box. Call `registerBuiltinEditors()` once
+ * near your app root.
+ *
+ * It is opt-in (rather than automatic) so the editor components tree-shake away
+ * when you don't use them. Option / structured editors (SvMultiSelect,
+ * SvTreeSelect, SvGridSelect) need their `options` / `nodes` / `columns`, so
+ * register those yourself with a props mapping:
+ *
+ * ```ts
+ * import { registerCellEditor, SvMultiSelect } from '@svgrid/grid'
+ * registerCellEditor('tags', {
+ *   component: SvMultiSelect,
+ *   props: (ctx) => ({
+ *     options: TAG_OPTIONS,
+ *     value: ctx.value,
+ *     onChange: ctx.onChange,        // update the in-progress value
+ *     onCommit: () => ctx.onCommit(),// e.g. the panel's Done button
+ *   }),
+ * })
+ * ```
+ */
+import { registerCellEditor } from './editor-registry'
+import SvOtpInput from './SvOtpInput.svelte'
+import SvDurationInput from './SvDurationInput.svelte'
+
+/**
+ * Register the config-free UI-kit editors (`otp`, `duration`) as grid cell
+ * editors. Idempotent. Returns the list of type names it registered.
+ */
+export function registerBuiltinEditors(): string[] {
+  registerCellEditor('otp', {
+    component: SvOtpInput,
+    autoOpen: false,
+    props: (ctx) => ({
+      value: (ctx.value ?? '') as string,
+      autofocus: true,
+      onChange: (v: string) => ctx.onChange(v),
+      // The code is complete -> commit + stop editing.
+      onComplete: (v: string) => ctx.onCommit(v),
+    }),
+  })
+  registerCellEditor('duration', {
+    component: SvDurationInput,
+    props: (ctx) => ({
+      value: (ctx.value ?? null) as number | null,
+      autofocus: true,
+      onChange: (v: number | null) => ctx.onChange(v),
+      onCommit: (v: number | null) => ctx.onCommit(v),
+      onCancel: () => ctx.onCancel(),
+    }),
+  })
+  return ['otp', 'duration']
+}

package/src/columns.ts

@@ -143,8 +143,9 @@ export function createColumns<
   }
 
   function isColumnPinned(columnId: string): "left" | "right" | null {
-    if (ctx.columnPinning.left.includes(columnId)) return "left";
-    if (ctx.columnPinning.right.includes(columnId)) return "right";
+    const pinning = ctx.effectivePinning ?? ctx.columnPinning;
+    if (pinning.left.includes(columnId)) return "left";
+    if (pinning.right.includes(columnId)) return "right";
     return null;
   }
 

package/src/core.ts

@@ -205,6 +205,12 @@ export type ColumnDef<TFeatures extends TableFeatures, TData extends RowData> =
    * this from the first data row for columns that declare neither.
    */
   cellDataType?: 'text' | 'number' | 'boolean' | 'date' | 'dateString'
+  /**
+   * Hide this column when the grid's `responsive` mode is on and the grid is
+   * narrower than this many pixels - drop low-priority columns on small
+   * screens. No effect unless the grid has `responsive` set.
+   */
+  hideBelow?: number
   /**
    * For a column INSIDE a collapsible column group: `'open'` shows this column
    * only while the group is expanded, `'closed'` only while collapsed. Omit to
@@ -237,6 +243,10 @@ export type ColumnDef<TFeatures extends TableFeatures, TData extends RowData> =
     | 'textarea'     // multi-line editor; Tab or Ctrl+Enter commits, plain Enter inserts a newline
     | 'color'        // native <input type="color"> swatch
     | 'rating'       // 5-star rating control
+    // Any other string names a CUSTOM editor registered via `registerCellEditor`
+    // (or `registerBuiltinEditors`). `(string & {})` keeps the literals above
+    // autocompleting while allowing arbitrary custom type names.
+    | (string & {})
   /**
    * Custom in-cell editor. Receives the cell context PLUS a `commit(value)`
    * and `cancel()` helper. Use when none of the built-in `editorType`s fit;

package/src/countries.ts

@@ -68,4 +68,29 @@ export const COUNTRIES: Country[] = [
   { code: 'MX', name: 'Mexico', dial: '+52' },
 ]
 
+/**
+ * Expected national (post-dial-code) significant-digit count per country, as an
+ * exact length or an inclusive [min, max] range. A pragmatic length-based check
+ * (not full libphonenumber). Countries without an entry accept any non-empty
+ * number.
+ */
+export const PHONE_NATIONAL_LENGTHS: Record<string, number | [number, number]> = {
+  US: 10, CA: 10, GB: 10, IE: 9, FR: 9, DE: [10, 11], ES: 9, IT: [9, 10], NL: 9, BE: [8, 9],
+  CH: 9, AT: [10, 12], SE: [7, 9], NO: 8, DK: 8, FI: [9, 10], PL: 9, PT: 9, GR: 10, CZ: 9,
+  RU: 10, TR: 10, IL: 9, AE: 9, SA: 9, IN: 10, PK: 10, CN: 11, HK: 8, JP: 10, KR: [9, 10],
+  SG: 8, MY: [9, 10], TH: 9, ID: [9, 11], PH: 10, VN: 9, AU: 9, NZ: [8, 10], ZA: 9, NG: 10,
+  EG: 10, KE: 9, MA: 9, BR: 11, AR: 10, CL: 9, CO: 10, MX: 10,
+}
+
+/**
+ * Whether `nationalDigits` is a plausible national number for `code` (length
+ * check). Unknown countries pass on any non-empty input. Pure.
+ */
+export function phoneDigitsValid(code: string, nationalDigits: string): boolean {
+  const n = (nationalDigits.match(/\d/g) ?? []).length
+  const rule = PHONE_NATIONAL_LENGTHS[code.toUpperCase()]
+  if (rule == null) return n > 0
+  return typeof rule === 'number' ? n === rule : n >= rule[0] && n <= rule[1]
+}
+
 export const COUNTRY_BY_CODE = new Map(COUNTRIES.map((c) => [c.code, c]))

package/src/createAccordion.svelte.ts

@@ -0,0 +1,126 @@
+/**
+ * createAccordion - the HEADLESS core behind <SvAccordion>: a WAI-ARIA accordion
+ * (collapsible sections) with single- or multiple-expand, roving header focus
+ * (Up/Down/Home/End) and full ARIA, exposed as **prop-getters** you spread onto
+ * YOUR OWN markup. No styles, no DOM. Parity: Smart `smart-accordion`.
+ *
+ * ```svelte
+ * <script lang="ts">
+ *   import { createAccordion } from '@svgrid/grid'
+ *   let expanded = $state<string[]>(['a'])
+ *   const acc = createAccordion({ items: () => items, expanded: () => expanded, onChange: (ids) => (expanded = ids) })
+ * </script>
+ * {#each items as it, i (it.id)}
+ *   <h3><button {...acc.headerProps(i)}>{it.label}</button></h3>
+ *   {#if acc.isExpanded(it.id)}<div {...acc.panelProps(i)}>...</div>{/if}
+ * {/each}
+ * ```
+ *
+ * The styled <SvAccordion> is one renderer over this core. DOM focus movement is
+ * a render concern: the component watches `focusTick`/`focusIndex` and calls
+ * `.focus()` itself.
+ */
+export type AccordionItem = { id: string; label: string; disabled?: boolean }
+/** `single` keeps at most one panel open; `multiple` allows any number. */
+export type AccordionExpandMode = 'single' | 'multiple'
+
+/** Reactive inputs are passed as getters so the core tracks live prop changes. */
+export type AccordionConfig = {
+  items: () => ReadonlyArray<AccordionItem>
+  /** Expanded item ids (controlled). */
+  expanded: () => string[]
+  onChange?: (expandedIds: string[]) => void
+  expandMode?: () => AccordionExpandMode
+  disabled?: () => boolean
+  dir?: () => 'ltr' | 'rtl' | 'auto' | undefined
+}
+
+let uid = 0
+
+export function createAccordion(config: AccordionConfig) {
+  const id = `sv-acc-${uid++}`
+  const items = () => config.items()
+  const expandMode = () => config.expandMode?.() ?? 'single'
+  const disabled = () => config.disabled?.() ?? false
+
+  const expandedSet = $derived(new Set(config.expanded()))
+  const enabledIdx = $derived(items().map((it, i) => (it.disabled ? -1 : i)).filter((i) => i >= 0))
+
+  let focusIndex = $state(0)
+  let focusTick = $state(0)
+  const requestFocus = (i: number) => { focusIndex = i; focusTick++ }
+
+  const headerId = (i: number) => `${id}-h-${i}`
+  const panelId = (i: number) => `${id}-p-${i}`
+  const isExpanded = (itemId: string) => expandedSet.has(itemId)
+
+  function toggle(i: number) {
+    const it = items()[i]
+    if (!it || it.disabled || disabled()) return
+    const open = expandedSet.has(it.id)
+    if (expandMode() === 'single') {
+      config.onChange?.(open ? [] : [it.id])
+    } else {
+      const next = new Set(expandedSet)
+      open ? next.delete(it.id) : next.add(it.id)
+      config.onChange?.([...next])
+    }
+  }
+
+  function move(delta: number) {
+    if (!enabledIdx.length) return
+    const pos = enabledIdx.indexOf(focusIndex)
+    const base = pos < 0 ? 0 : pos
+    const next = enabledIdx[(base + delta + enabledIdx.length) % enabledIdx.length]
+    if (next != null) requestFocus(next)
+  }
+
+  function onHeaderKeydown(e: KeyboardEvent, i: number) {
+    if (disabled()) return
+    switch (e.key) {
+      case 'ArrowDown': e.preventDefault(); move(1); break
+      case 'ArrowUp': e.preventDefault(); move(-1); break
+      case 'Home': e.preventDefault(); requestFocus(enabledIdx[0] ?? 0); break
+      case 'End': e.preventDefault(); requestFocus(enabledIdx.at(-1) ?? 0); break
+      case 'Enter':
+      case ' ': e.preventDefault(); toggle(i); break
+    }
+  }
+
+  return {
+    /** Header index that should hold DOM focus after the latest keyboard move. */
+    get focusIndex() { return focusIndex },
+    /** Monotonic counter; changes only on keyboard navigation. */
+    get focusTick() { return focusTick },
+    /** Currently-expanded item ids. */
+    get expandedIds() { return [...expandedSet] },
+    isExpanded,
+    toggle,
+    /** Spread onto the accordion root container. */
+    rootProps: () => ({
+      'data-orientation': 'vertical' as const,
+    }),
+    /** Spread onto the header <button> at `index`. */
+    headerProps: (index: number) => {
+      const it = items()[index]
+      return {
+        type: 'button' as const,
+        id: headerId(index),
+        'data-idx': index,
+        'aria-expanded': it ? isExpanded(it.id) : false,
+        'aria-controls': panelId(index),
+        disabled: disabled() || it?.disabled || undefined,
+        onclick: () => toggle(index),
+        onkeydown: (e: KeyboardEvent) => onHeaderKeydown(e, index),
+      }
+    },
+    /** Spread onto the panel/region element at `index`. */
+    panelProps: (index: number) => ({
+      role: 'region' as const,
+      id: panelId(index),
+      'aria-labelledby': headerId(index),
+    }),
+  }
+}
+
+export type Accordion = ReturnType<typeof createAccordion>

package/src/createAutocomplete.svelte.ts

@@ -20,6 +20,7 @@
  * ```
  */
 import { filterOptions, type ListOption } from './list-option'
+import { editorAria, type EditorAriaState } from './editor-contract'
 
 /** Reactive inputs are passed as getters so the core tracks live prop changes. */
 export type AutocompleteConfig = {
@@ -32,11 +33,26 @@ export type AutocompleteConfig = {
   ariaLabel?: () => string | undefined
   /** DOM focus hook provided by the renderer; the core never touches the DOM. */
   focusInput?: () => void
+  // Editor contract (ARIA + validation) - folded into inputProps().
+  id?: () => string | undefined
+  invalid?: () => boolean
+  required?: () => boolean
+  error?: () => string | undefined
+  hint?: () => string | undefined
 }
 
 export function createAutocomplete(config: AutocompleteConfig) {
   const minChars = () => config.minChars?.() ?? 1
 
+  const ariaState = (): EditorAriaState => ({
+    id: config.id?.(),
+    invalid: config.invalid?.(),
+    required: config.required?.(),
+    error: config.error?.(),
+    hint: config.hint?.(),
+    ariaLabel: config.ariaLabel?.(),
+  })
+
   let open = $state(false)
   let active = $state(0)
 
@@ -75,10 +91,11 @@ export function createAutocomplete(config: AutocompleteConfig) {
     onKeydown,
     /** Spread onto the text <input>. */
     inputProps: () => ({
+      id: config.id?.(),
       role: 'combobox' as const,
       'aria-expanded': open,
       'aria-autocomplete': 'list' as const,
-      'aria-label': config.ariaLabel?.(),
+      ...editorAria(ariaState()),
       value: config.value(),
       disabled: config.disabled?.() ?? false,
       oninput: onInput,

package/src/createButtonGroup.svelte.ts

@@ -0,0 +1,166 @@
+/**
+ * createButtonGroup - the HEADLESS core behind <SvButtonGroup>: a segmented
+ * button bar with single- or multi-select (or plain action buttons), roving
+ * tabindex + full keyboard, exposed as **prop-getters** you spread onto YOUR OWN
+ * markup. No styles, no DOM. Parity: Smart `smart-button-group`.
+ *
+ * ```svelte
+ * <script lang="ts">
+ *   import { createButtonGroup } from '@svgrid/grid'
+ *   let value = $state<string | null>('day')
+ *   const g = createButtonGroup({ items: () => items, value: () => value, onChange: (v) => (value = v) })
+ * </script>
+ * <div {...g.rootProps()}>
+ *   {#each items as it, i (it.value)}<button {...g.buttonProps(i)}>{it.label}</button>{/each}
+ * </div>
+ * ```
+ *
+ * The styled <SvButtonGroup> is one renderer over this core.
+ */
+import { editorAria, type EditorAriaState } from './editor-contract'
+
+export type ButtonGroupItem = { value: string | number; label?: string; disabled?: boolean }
+/** `single` = radio semantics; `multiple` = toggle set; `none` = action buttons. */
+export type ButtonGroupMode = 'single' | 'multiple' | 'none'
+export type ButtonGroupValue = string | number | Array<string | number> | null
+
+/** Reactive inputs are passed as getters so the core tracks live prop changes. */
+export type ButtonGroupConfig = {
+  items: () => ReadonlyArray<ButtonGroupItem>
+  value: () => ButtonGroupValue
+  onChange?: (value: string | number | Array<string | number>) => void
+  mode?: () => ButtonGroupMode
+  disabled?: () => boolean
+  orientation?: () => 'horizontal' | 'vertical'
+  /** Under `'rtl'` the horizontal Left/Right arrow direction flips. */
+  dir?: () => 'ltr' | 'rtl' | 'auto' | undefined
+  // Editor contract (ARIA + validation) - folded into rootProps().
+  id?: () => string | undefined
+  invalid?: () => boolean
+  required?: () => boolean
+  error?: () => string | undefined
+  hint?: () => string | undefined
+  ariaLabel?: () => string | undefined
+}
+
+/** Normalize the value to an array (pure). */
+export function toGroupArray(value: ButtonGroupValue): Array<string | number> {
+  if (value == null) return []
+  return Array.isArray(value) ? [...value] : [value]
+}
+
+export function createButtonGroup(config: ButtonGroupConfig) {
+  const items = () => config.items()
+  const mode = () => config.mode?.() ?? 'single'
+  const disabled = () => config.disabled?.() ?? false
+  const isVert = () => (config.orientation?.() ?? 'horizontal') === 'vertical'
+  const rtl = () => config.dir?.() === 'rtl'
+
+  const selected = $derived(toGroupArray(config.value()))
+  const enabledIdx = $derived(items().map((it, i) => (it.disabled ? -1 : i)).filter((i) => i >= 0))
+
+  const isSelected = (v: string | number) => selected.includes(v)
+  const selectedIdx = $derived(items().findIndex((it) => isSelected(it.value)))
+
+  // Focus cursor. In single (radio) mode moving the cursor also selects, so the
+  // roving-tabindex target follows the selection; multiple/none keep their own
+  // cursor in `active`.
+  let active = $state(0)
+  $effect(() => {
+    const it = items()[active]
+    if (!it || it.disabled) active = enabledIdx[0] ?? 0
+  })
+  const cursor = $derived(
+    mode() === 'single' ? (selectedIdx >= 0 ? selectedIdx : enabledIdx[0] ?? 0) : active,
+  )
+
+  function pick(i: number) {
+    const it = items()[i]
+    if (!it || it.disabled || disabled()) return
+    active = i
+    if (mode() === 'none') { config.onChange?.(it.value); return }
+    if (mode() === 'multiple') {
+      const set = new Set(selected)
+      set.has(it.value) ? set.delete(it.value) : set.add(it.value)
+      config.onChange?.([...set])
+    } else {
+      config.onChange?.(it.value)
+    }
+  }
+
+  function goto(i: number) {
+    // Radio semantics select on move; toggle/action only move focus.
+    if (mode() === 'single') pick(i)
+    else active = i
+  }
+  function move(delta: number) {
+    if (!enabledIdx.length) return
+    const pos = enabledIdx.indexOf(cursor)
+    const next = enabledIdx[(pos + delta + enabledIdx.length) % enabledIdx.length]
+    if (next != null) goto(next)
+  }
+
+  function onKeydown(e: KeyboardEvent) {
+    if (disabled()) return
+    const horiz = !isVert()
+    const rtlH = horiz && rtl()
+    const fwd = horiz ? (rtlH ? 'ArrowLeft' : 'ArrowRight') : 'ArrowDown'
+    const back = horiz ? (rtlH ? 'ArrowRight' : 'ArrowLeft') : 'ArrowUp'
+    if (e.key === fwd) { e.preventDefault(); move(1) }
+    else if (e.key === back) { e.preventDefault(); move(-1) }
+    else if (e.key === 'Home') { e.preventDefault(); goto(enabledIdx[0] ?? 0) }
+    else if (e.key === 'End') { e.preventDefault(); goto(enabledIdx.at(-1) ?? 0) }
+    else if (e.key === ' ' || e.key === 'Enter') { e.preventDefault(); pick(cursor) }
+  }
+
+  const ariaState = (): EditorAriaState => ({
+    id: config.id?.(),
+    invalid: config.invalid?.(),
+    required: config.required?.(),
+    error: config.error?.(),
+    hint: config.hint?.(),
+    ariaLabel: config.ariaLabel?.(),
+  })
+
+  const groupRole = () => (mode() === 'single' ? 'radiogroup' : 'group')
+
+  return {
+    /** Roving-focus target index (follows the selection in single mode). */
+    get activeIndex() { return cursor },
+    /** Selected values as an array (single mode -> 0 or 1 entry). */
+    get selectedValues() { return selected },
+    isSelected,
+    isActive: (i: number) => i === cursor,
+    pick,
+    move,
+    onKeydown,
+    /** Spread onto the group container element. */
+    rootProps: () => ({
+      role: groupRole(),
+      id: config.id?.(),
+      'aria-orientation': isVert() ? ('vertical' as const) : ('horizontal' as const),
+      ...editorAria(ariaState()),
+      onkeydown: onKeydown,
+    }),
+    /** Spread onto the button element at `index`. */
+    buttonProps: (index: number) => {
+      const it = items()[index]
+      const on = it ? isSelected(it.value) : false
+      const single = mode() === 'single'
+      return {
+        type: 'button' as const,
+        role: single ? ('radio' as const) : undefined,
+        'data-idx': index,
+        'aria-checked': single ? on : undefined,
+        'aria-pressed': mode() === 'multiple' ? on : undefined,
+        'data-selected': on ? '' : undefined,
+        disabled: disabled() || it?.disabled || undefined,
+        // Roving tabindex: only the cursor (selection in single mode) is tabbable.
+        tabindex: mode() === 'none' ? 0 : index === cursor ? 0 : -1,
+        onclick: () => pick(index),
+      }
+    },
+  }
+}
+
+export type ButtonGroup = ReturnType<typeof createButtonGroup>

package/src/createCalendar.svelte.ts

@@ -48,6 +48,7 @@ import {
   type SelectionState,
 } from './datetime/date-selection'
 import { isDisabledDay, isImportant, type RestrictOptions } from './datetime/date-restrict'
+import { matchesRecurrence, type RecurrenceRule } from './recurrence'
 
 export type DisplayMode = 'month' | 'year' | 'decade'
 export type CalendarNameFormat = 'narrow' | 'short' | 'long'
@@ -82,6 +83,8 @@ export type CalendarDayState = {
   outside: boolean
   focused: boolean
   preview: boolean
+  /** Matches one of the `recurrence` rules (repeat pattern). */
+  recurring: boolean
 }
 
 /** Reactive inputs are passed as getters so the core tracks live prop changes;
@@ -105,6 +108,8 @@ export type CalendarConfig = {
   dayNameFormat?: () => CalendarNameFormat
   monthNameFormat?: () => CalendarNameFormat
   dateTooltip?: () => ((date: Date) => string | null | undefined) | undefined
+  /** Repeat pattern(s) - matching days get `dayState().recurring = true`. */
+  recurrence?: () => RecurrenceRule | ReadonlyArray<RecurrenceRule> | null
 }
 
 const defaultLocale = () => (typeof navigator !== 'undefined' ? navigator.language : 'en-US')
@@ -216,6 +221,7 @@ export function createCalendar(config: CalendarConfig) {
       outside: !isSameMonth(d, panelMonth),
       focused: isSameDay(d, focusDate),
       preview: inPreview(d),
+      recurring: matchesRecurrence(d, config.recurrence?.() ?? null),
     }
   }