@svgrid/grid 2.1.22 → 2.2.0

package/src/createOverlay.svelte.ts

@@ -0,0 +1,101 @@
+/**
+ * createOverlay - the HEADLESS core behind the dialog-type overlays (<SvModal>,
+ * <SvDrawer>): the open -> (focus-trap + scroll-lock + Escape/backdrop dismissal)
+ * -> restore lifecycle, wired to the shared a11y primitives so nested overlays
+ * close top-first via the layer stack. Owns no markup and no styles - the
+ * component renders the backdrop/panel and spreads `dialogProps()` for the ARIA.
+ *
+ * ```svelte
+ * <script lang="ts">
+ *   import { createOverlay } from '@svgrid/grid'
+ *   let dialogEl = $state<HTMLElement | null>(null)
+ *   const overlay = createOverlay({
+ *     open: () => open,
+ *     getDialog: () => dialogEl,
+ *     onClose: () => (open = false),
+ *   })
+ * </script>
+ * {#if open}
+ *   <div class="backdrop">
+ *     <div bind:this={dialogEl} {...overlay.dialogProps({ labelledBy: titleId })}>…</div>
+ *   </div>
+ * {/if}
+ * ```
+ */
+import { createFocusTrap } from './a11y/focus-trap'
+import { lockScroll } from './a11y/scroll-lock'
+import { createDismissableLayer } from './a11y/dismissable'
+
+export type OverlayConfig = {
+  /** Whether the overlay is currently open. */
+  open: () => boolean
+  /** The dialog panel element (component owns `bind:this`, passes a getter). */
+  getDialog: () => HTMLElement | null
+  /** Close the overlay (set your `open` state false + notify). */
+  onClose: () => void
+  /** Allow Escape to close. Default true. */
+  closeOnEsc?: () => boolean
+  /** Allow an outside/backdrop click to close. Default true. */
+  closeOnBackdrop?: () => boolean
+  /** Run once each time the overlay opens - reset transient state (drag, resize,
+   *  swipe offset) before the trap/lock/layer are wired. */
+  onOpen?: () => void
+  /** Trap focus inside the dialog while open. Default true. */
+  trapFocus?: () => boolean
+  /** Lock body scroll while open. Default true. */
+  scrollLock?: () => boolean
+  /** Element to focus first when the dialog opens (e.g. a search input).
+   *  Defaults to the trap's first focusable. */
+  initialFocus?: () => HTMLElement | null
+}
+
+export type DialogProps = {
+  role: 'dialog'
+  'aria-modal': 'true'
+  'aria-labelledby': string | undefined
+  'aria-label': string | undefined
+  tabindex: -1
+}
+
+export function createOverlay(config: OverlayConfig) {
+  // While open: reset transient state, then hand focus, scroll-lock and
+  // Escape/backdrop dismissal to the shared primitives (one tested
+  // implementation; nested overlays close top-first via the layer stack).
+  $effect(() => {
+    if (!config.open() || !config.getDialog()) return
+    config.onOpen?.()
+    const el = config.getDialog()!
+    const trap = (config.trapFocus?.() ?? true)
+      ? createFocusTrap(el, config.initialFocus ? { initialFocus: config.initialFocus } : undefined)
+      : null
+    trap?.activate()
+    const unlockScroll = (config.scrollLock?.() ?? true) ? lockScroll() : null
+    const layer = createDismissableLayer({
+      element: () => config.getDialog(),
+      onDismiss: (reason) => {
+        const allow = reason === 'escape' ? (config.closeOnEsc?.() ?? true) : (config.closeOnBackdrop?.() ?? true)
+        if (allow) config.onClose()
+      },
+    })
+    layer.activate()
+    return () => {
+      layer.release()
+      unlockScroll?.()
+      trap?.release()
+    }
+  })
+
+  return {
+    /** Spread onto the dialog panel element. Pass `labelledBy` (an id, when there
+     *  is a visible title) or `label` (an accessible name when there isn't). */
+    dialogProps: (opts?: { labelledBy?: string; label?: string }): DialogProps => ({
+      role: 'dialog',
+      'aria-modal': 'true',
+      'aria-labelledby': opts?.labelledBy,
+      'aria-label': opts?.label,
+      tabindex: -1,
+    }),
+  }
+}
+
+export type Overlay = ReturnType<typeof createOverlay>

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>