@svgrid/grid 1.2.33 → 2.0.0

package/src/SvTreeSelect.svelte

@@ -0,0 +1,222 @@
+<script lang="ts" module>
+  export type { TreeSelectNode } from './ui-app.types'
+</script>
+
+<script lang="ts">
+  /**
+   * SvTreeSelect - a single-select dropdown that shows an indented, collapsible
+   * tree in its panel (pick a node from a hierarchy). The open / position /
+   * dismiss / roving / keyboard / ARIA mechanics come from the shared
+   * `createPopoverSelect` core (with ArrowLeft/Right handled via onExtraKey for
+   * expand/collapse); this component adds the tree flattening + rendering. Covers
+   * the "cascader / tree select" pattern without depending on SvTree.
+   */
+  import type { TreeSelectNode } from './ui-app.types'
+  import SvField from './SvField.svelte'
+  import { editorAria, nextEditorId, type SvEditorProps } from './editor-contract'
+  import { portalToBody, popIn } from './popover'
+  import { createPopoverSelect } from './createPopoverSelect.svelte'
+  import { flattenVisible, findNodePath } from './tree-select'
+
+  type Props = Pick<
+    SvEditorProps,
+    'disabled' | 'label' | 'hint' | 'error' | 'required' | 'invalid' | 'size' | 'id' | 'name' | 'dir' | 'ariaLabel'
+  > & {
+    nodes: ReadonlyArray<TreeSelectNode>
+    value?: string | number | null
+    onChange?: (value: string | number) => void
+    onCommit?: (value: string | number) => void
+    onCancel?: () => void
+    placeholder?: string
+    showPath?: boolean
+    expandedIds?: ReadonlyArray<string | number>
+  }
+
+  let {
+    nodes,
+    value = $bindable<string | number | null>(null),
+    onChange,
+    onCommit,
+    onCancel,
+    placeholder = 'Select…',
+    showPath = false,
+    expandedIds = [],
+    disabled = false,
+    label,
+    hint,
+    error,
+    required = false,
+    invalid = false,
+    size = 'md',
+    id,
+    name,
+    dir,
+    ariaLabel,
+  }: Props = $props()
+
+  const autoId = nextEditorId('sv-ts')
+  const uid = $derived(id ?? autoId)
+
+  let expanded = $state(new Set<string | number>(expandedIds))
+  let triggerEl = $state<HTMLButtonElement | null>(null)
+  let panelEl = $state<HTMLDivElement | null>(null)
+  let treeEl = $state<HTMLUListElement | null>(null)
+
+  const rows = $derived(flattenVisible(nodes, expanded))
+  const selectedPath = $derived(value == null ? null : findNodePath(nodes, value))
+  const triggerText = $derived(
+    !selectedPath
+      ? ''
+      : showPath
+        ? selectedPath.map((n) => n.label).join(' / ')
+        : selectedPath[selectedPath.length - 1]!.label,
+  )
+
+  function setExpanded(v: string | number, on: boolean) {
+    const next = new Set(expanded)
+    on ? next.add(v) : next.delete(v)
+    expanded = next
+  }
+  function toggleExpand(v: string | number) {
+    setExpanded(v, !expanded.has(v))
+  }
+  function pick(node: TreeSelectNode) {
+    if (node.disabled) return
+    value = node.value // enables bind:value
+    onChange?.(node.value)
+    ts.closePanel()
+  }
+  function onRowClick(row: { node: TreeSelectNode; hasChildren: boolean }) {
+    if (row.hasChildren) toggleExpand(row.node.value)
+    else pick(row.node)
+  }
+
+  const ts = createPopoverSelect({
+    itemCount: () => rows.length,
+    disabled: (i) => !!rows[i]?.node.disabled,
+    onSelect: (i) => { const row = rows[i]; if (row) onRowClick(row) },
+    getTrigger: () => triggerEl,
+    getPanel: () => panelEl,
+    getInitialFocus: () => treeEl,
+    closeOnSelect: () => false, // onRowClick handles pick + close (branches stay open)
+    initialActive: () => Math.max(0, rows.findIndex((r) => r.node.value === value)),
+    minWidth: () => 220,
+    estimatedHeight: () => 300,
+    onExtraKey: (e, act) => {
+      const row = rows[act]
+      if (e.key === 'ArrowRight') {
+        e.preventDefault()
+        if (row?.hasChildren && !row.expanded) setExpanded(row.node.value, true)
+        return true
+      }
+      if (e.key === 'ArrowLeft') {
+        e.preventDefault()
+        if (row?.hasChildren && row.expanded) setExpanded(row.node.value, false)
+        return true
+      }
+      return false
+    },
+    idPrefix: 'sv-ts',
+  })
+</script>
+
+<SvField id={uid} {label} {hint} {error} {required} {dir}>
+  <div class="sv-ts sv-ts--{size}" class:is-disabled={disabled}>
+    <button
+      bind:this={triggerEl}
+      type="button"
+      class="sv-ts__trigger"
+      class:is-invalid={invalid}
+      {disabled}
+      onclick={() => ts.toggle()}
+      {...ts.triggerProps()}
+      {...editorAria({ id: uid, invalid, required, error, hint, ariaLabel })}
+    >
+      <span class="sv-ts__value" class:is-placeholder={!triggerText}>{triggerText || placeholder}</span>
+      <span class="sv-ts__arrow" aria-hidden="true">▾</span>
+    </button>
+    {#if name}<input type="hidden" {name} value={value ?? ''} />{/if}
+  </div>
+</SvField>
+
+{#if ts.open}
+  <div
+    bind:this={panelEl}
+    class="sv-ts__panel"
+    dir={dir}
+    use:portalToBody
+    use:popIn={{ up: ts.rect.openUpward }}
+    style:position="fixed"
+    style:top={`${ts.rect.top}px`}
+    style:left={`${ts.rect.left}px`}
+    style:min-width={`${ts.rect.width}px`}
+  >
+    <ul
+      bind:this={treeEl}
+      id={ts.panelId}
+      class="sv-ts__tree"
+      role="tree"
+      aria-label={label ?? ariaLabel ?? 'Tree'}
+      aria-activedescendant={ts.activeDescendant()}
+      tabindex="0"
+      onkeydown={ts.onPanelKeydown}
+    >
+      {#each rows as row, i (row.node.value)}
+        <li
+          class="sv-ts__row"
+          class:is-active={ts.isActive(i)}
+          class:is-selected={row.node.value === value}
+          class:is-disabled={row.node.disabled}
+          role="treeitem"
+          aria-selected={row.node.value === value}
+          aria-expanded={row.hasChildren ? row.expanded : undefined}
+          style:padding-inline-start={`${8 + row.depth * 16}px`}
+          onclick={() => onRowClick(row)}
+          {...ts.itemProps(i)}
+        >
+          {#if row.hasChildren}
+            <span class="sv-ts__chev" class:is-open={row.expanded} aria-hidden="true">▸</span>
+          {:else}
+            <span class="sv-ts__chev sv-ts__chev--leaf" aria-hidden="true"></span>
+          {/if}
+          <span class="sv-ts__label">{row.node.label}</span>
+        </li>
+      {/each}
+    </ul>
+  </div>
+{/if}
+
+<style>
+  .sv-ts { --_accent: var(--sg-accent, #2563eb); display: inline-flex; width: 240px; }
+  .sv-ts.is-disabled { opacity: 0.6; }
+  .sv-ts__trigger {
+    flex: 1; min-width: 0; display: flex; align-items: center; gap: 6px; text-align: start;
+    background: var(--sg-input-bg, #fff); color: var(--sg-fg, #0f172a);
+    border: 1px solid var(--sg-input-border, var(--sg-border, #cbd5e1)); border-radius: var(--sg-radius, 8px);
+    font: inherit; cursor: pointer; padding: 0 9px;
+  }
+  .sv-ts--sm .sv-ts__trigger { height: 28px; font-size: 12px; }
+  .sv-ts--md .sv-ts__trigger { height: 34px; font-size: 13px; }
+  .sv-ts--lg .sv-ts__trigger { height: 40px; font-size: 15px; }
+  .sv-ts__trigger:focus-visible { outline: none; border-color: var(--_accent); box-shadow: 0 0 0 2px color-mix(in srgb, var(--_accent) 22%, transparent); }
+  .sv-ts__trigger.is-invalid { border-color: var(--sg-danger, #dc2626); }
+  .sv-ts__value { flex: 1; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+  .sv-ts__value.is-placeholder { color: var(--sg-muted, #94a3b8); }
+  .sv-ts__arrow { color: var(--sg-muted, #64748b); font-size: 10px; }
+
+  :global(.sv-ts__panel) {
+    z-index: 2147483646; max-height: 320px; max-width: 92vw; overflow: hidden;
+    background: var(--sg-bg, #fff); color: var(--sg-fg, #0f172a);
+    border: 1px solid var(--sg-border, #e2e8f0); border-radius: 10px;
+    box-shadow: 0 16px 48px -12px rgba(15, 23, 42, 0.35); font-size: 13px;
+  }
+  :global(.sv-ts__tree) { list-style: none; margin: 0; padding: 4px; overflow: auto; max-height: 320px; outline: none; }
+  :global(.sv-ts__row) { display: flex; align-items: center; gap: 4px; padding: 6px 8px; border-radius: 6px; cursor: pointer; }
+  :global(.sv-ts__row.is-active) { background: var(--sg-row-hover-bg, #f1f5f9); }
+  :global(.sv-ts__row.is-selected) { color: var(--sg-accent, #2563eb); font-weight: 600; }
+  :global(.sv-ts__row.is-disabled) { opacity: 0.5; cursor: not-allowed; }
+  :global(.sv-ts__chev) { width: 14px; flex: none; color: var(--sg-muted, #64748b); transition: transform 0.12s; font-size: 10px; }
+  :global(.sv-ts__chev.is-open) { transform: rotate(90deg); }
+  :global(.sv-ts__chev--leaf) { visibility: hidden; }
+  :global(.sv-ts__label) { flex: 1; white-space: nowrap; }
+</style>

package/src/SvTreeSelect.test.ts

@@ -0,0 +1,87 @@
+/**
+ * Component tests for SvTreeSelect: trigger label/path, portalled tree panel,
+ * expand-on-parent-click, select-on-leaf-click (emits + closes).
+ */
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { mount, unmount, flushSync } from 'svelte'
+import SvTreeSelect from './SvTreeSelect.svelte'
+import type { TreeSelectNode } from './ui-app.types'
+
+const tree: TreeSelectNode[] = [
+  { value: 'asia', label: 'Asia', children: [
+    { value: 'jp', label: 'Japan' },
+    { value: 'cn', label: 'China' },
+  ] },
+  { value: 'eu', label: 'Europe', children: [{ value: 'fr', label: 'France' }] },
+]
+
+function mountTs(props: Record<string, unknown>) {
+  const target = document.createElement('div')
+  document.body.appendChild(target)
+  const app = mount(SvTreeSelect, { target, props: { nodes: tree, ...props } as any })
+  flushSync()
+  return { target, destroy: () => { unmount(app); target.remove() } }
+}
+
+const panelRows = () => document.body.querySelectorAll<HTMLElement>('.sv-ts__row')
+const rowLabels = () =>
+  [...panelRows()].map((r) => r.querySelector('.sv-ts__label')!.textContent!.trim())
+
+afterEach(() => { document.body.innerHTML = '' })
+
+describe('SvTreeSelect', () => {
+  it('shows the placeholder when nothing is selected', () => {
+    const { target, destroy } = mountTs({ value: null, placeholder: 'Pick a place' })
+    try {
+      expect(target.querySelector('.sv-ts__value')!.textContent).toBe('Pick a place')
+    } finally { destroy() }
+  })
+
+  it('shows the selected node label (or path)', () => {
+    const path = mountTs({ value: 'jp', expandedIds: ['asia'], showPath: true })
+    try {
+      expect(path.target.querySelector('.sv-ts__value')!.textContent).toBe('Asia / Japan')
+    } finally { path.destroy() }
+
+    const leaf = mountTs({ value: 'jp' })
+    try {
+      expect(leaf.target.querySelector('.sv-ts__value')!.textContent).toBe('Japan')
+    } finally { leaf.destroy() }
+  })
+
+  it('opens a portalled tree showing only roots initially', () => {
+    const { target, destroy } = mountTs({ value: null })
+    try {
+      target.querySelector<HTMLButtonElement>('.sv-ts__trigger')!.click()
+      flushSync()
+      expect(rowLabels()).toEqual(['Asia', 'Europe'])
+    } finally { destroy() }
+  })
+
+  it('clicking a parent expands it without selecting', () => {
+    const onChange = vi.fn()
+    const { target, destroy } = mountTs({ value: null, onChange })
+    try {
+      target.querySelector<HTMLButtonElement>('.sv-ts__trigger')!.click()
+      flushSync()
+      panelRows()[0]!.click() // Asia
+      flushSync()
+      expect(rowLabels()).toEqual(['Asia', 'Japan', 'China', 'Europe'])
+      expect(onChange).not.toHaveBeenCalled()
+    } finally { destroy() }
+  })
+
+  it('clicking a leaf emits its value and closes', () => {
+    const onChange = vi.fn()
+    const { target, destroy } = mountTs({ value: null, expandedIds: ['asia'], onChange })
+    try {
+      target.querySelector<HTMLButtonElement>('.sv-ts__trigger')!.click()
+      flushSync()
+      const china = [...panelRows()].find((r) => r.textContent!.includes('China'))!
+      china.click()
+      flushSync()
+      expect(onChange).toHaveBeenCalledWith('cn')
+      expect(document.body.querySelector('.sv-ts__panel')).toBeNull()
+    } finally { destroy() }
+  })
+})

package/src/a11y/dismissable.test.ts

@@ -0,0 +1,95 @@
+import { afterEach, describe, expect, it } from 'vitest'
+import { createDismissableLayer, dismissableDepth } from './dismissable'
+
+function panel(): HTMLElement {
+  const el = document.createElement('div')
+  document.body.appendChild(el)
+  return el
+}
+
+afterEach(() => {
+  document.body.innerHTML = ''
+})
+
+describe('createDismissableLayer', () => {
+  it('dismisses on Escape when topmost', () => {
+    const el = panel()
+    let reason: string | null = null
+    const layer = createDismissableLayer({ element: () => el, onDismiss: (r) => (reason = r) })
+    layer.activate()
+    document.dispatchEvent(new KeyboardEvent('keydown', { key: 'Escape', bubbles: true }))
+    expect(reason).toBe('escape')
+    layer.release()
+  })
+
+  it('dismisses on outside pointerdown but not inside', () => {
+    const el = panel()
+    const inside = document.createElement('button')
+    el.appendChild(inside)
+    let reason: string | null = null
+    const layer = createDismissableLayer({ element: () => el, onDismiss: (r) => (reason = r) })
+    layer.activate()
+
+    inside.dispatchEvent(new MouseEvent('pointerdown', { bubbles: true }))
+    expect(reason).toBeNull()
+
+    document.body.dispatchEvent(new MouseEvent('pointerdown', { bubbles: true }))
+    expect(reason).toBe('outside')
+    layer.release()
+  })
+
+  it('treats a pointerdown in ANY of multiple elements as inside', () => {
+    const panelEl = panel()
+    const trigger = panel()
+    let reason: string | null = null
+    const layer = createDismissableLayer({
+      element: () => [panelEl, trigger],
+      onDismiss: (r) => (reason = r),
+    })
+    layer.activate()
+
+    trigger.dispatchEvent(new MouseEvent('pointerdown', { bubbles: true }))
+    expect(reason).toBeNull() // trigger counts as inside
+
+    document.body.dispatchEvent(new MouseEvent('pointerdown', { bubbles: true }))
+    expect(reason).toBe('outside')
+    layer.release()
+  })
+
+  it('only the top layer responds to Escape', () => {
+    const a = panel()
+    const b = panel()
+    const hits: string[] = []
+    const layerA = createDismissableLayer({ element: () => a, onDismiss: () => hits.push('a') })
+    const layerB = createDismissableLayer({ element: () => b, onDismiss: () => hits.push('b') })
+    layerA.activate()
+    layerB.activate()
+    expect(dismissableDepth()).toBe(2)
+
+    document.dispatchEvent(new KeyboardEvent('keydown', { key: 'Escape', bubbles: true }))
+    expect(hits).toEqual(['b']) // only the topmost
+
+    layerB.release()
+    document.dispatchEvent(new KeyboardEvent('keydown', { key: 'Escape', bubbles: true }))
+    expect(hits).toEqual(['b', 'a']) // now a is on top
+
+    layerA.release()
+    expect(dismissableDepth()).toBe(0)
+  })
+
+  it('respects closeOnEscape / closeOnOutside flags', () => {
+    const el = panel()
+    let count = 0
+    const layer = createDismissableLayer({
+      element: () => el,
+      onDismiss: () => count++,
+      closeOnEscape: false,
+      closeOnOutside: false,
+    })
+    layer.activate()
+    document.dispatchEvent(new KeyboardEvent('keydown', { key: 'Escape', bubbles: true }))
+    document.body.dispatchEvent(new MouseEvent('pointerdown', { bubbles: true }))
+    expect(count).toBe(0)
+    layer.release()
+  })
+})

package/src/a11y/dismissable.ts

@@ -0,0 +1,94 @@
+/**
+ * dismissable-layer - a global stack of dismissable overlays (dropdowns,
+ * popovers, dialogs). Escape and outside-pointer dismiss only the TOP layer, so
+ * a menu opened inside a dialog closes the menu first and the dialog second -
+ * the ordering users expect from nested overlays. One set of document listeners
+ * is shared by every layer instead of each component wiring its own.
+ */
+type Reason = 'escape' | 'outside'
+
+/** One element, several elements, or a getter of either. A pointerdown counts
+ *  as "inside" when it lands in ANY of them (e.g. a popover's panel AND its
+ *  trigger, so clicking the trigger doesn't immediately re-dismiss). */
+export type DismissTarget = HTMLElement | null | ReadonlyArray<HTMLElement | null>
+
+type Layer = {
+  element: () => DismissTarget
+  onDismiss: (reason: Reason) => void
+  closeOnEscape: boolean
+  closeOnOutside: boolean
+}
+
+function containsTarget(target: DismissTarget, node: Node | null): boolean {
+  if (!node) return false
+  const els = Array.isArray(target) ? target : [target as HTMLElement | null]
+  return els.some((el) => el != null && el.contains(node))
+}
+
+const stack: Layer[] = []
+let wired = false
+
+function ensureWired() {
+  if (wired || typeof document === 'undefined') return
+  wired = true
+  document.addEventListener(
+    'keydown',
+    (e) => {
+      if (e.key !== 'Escape') return
+      const top = stack[stack.length - 1]
+      if (top?.closeOnEscape) {
+        e.stopPropagation()
+        top.onDismiss('escape')
+      }
+    },
+    true,
+  )
+  document.addEventListener(
+    'pointerdown',
+    (e) => {
+      const top = stack[stack.length - 1]
+      if (!top?.closeOnOutside) return
+      if (!containsTarget(top.element(), e.target as Node)) top.onDismiss('outside')
+    },
+    true,
+  )
+}
+
+export type DismissableOptions = {
+  /** The panel element(s); a pointerdown outside ALL of them dismisses the layer.
+   *  Pass multiple (e.g. panel + trigger) so clicking the trigger doesn't
+   *  immediately re-dismiss what it just opened. */
+  element: () => DismissTarget
+  onDismiss: (reason: Reason) => void
+  /** Dismiss on Escape when topmost. Default true. */
+  closeOnEscape?: boolean
+  /** Dismiss on outside pointerdown when topmost. Default true. */
+  closeOnOutside?: boolean
+}
+
+export type DismissableLayer = { activate: () => void; release: () => void }
+
+/** Register a dismissable layer. Inert until `activate()`. */
+export function createDismissableLayer(options: DismissableOptions): DismissableLayer {
+  const layer: Layer = {
+    element: options.element,
+    onDismiss: options.onDismiss,
+    closeOnEscape: options.closeOnEscape ?? true,
+    closeOnOutside: options.closeOnOutside ?? true,
+  }
+  return {
+    activate() {
+      ensureWired()
+      if (!stack.includes(layer)) stack.push(layer)
+    },
+    release() {
+      const i = stack.indexOf(layer)
+      if (i >= 0) stack.splice(i, 1)
+    },
+  }
+}
+
+/** Test/introspection helper: current number of active layers. */
+export function dismissableDepth(): number {
+  return stack.length
+}

package/src/a11y/focus-trap.test.ts

@@ -0,0 +1,110 @@
+import { afterEach, describe, expect, it } from 'vitest'
+import { createFocusTrap, getFocusable } from './focus-trap'
+
+function build(html: string): HTMLElement {
+  const host = document.createElement('div')
+  host.innerHTML = html
+  document.body.appendChild(host)
+  return host
+}
+
+afterEach(() => {
+  document.body.innerHTML = ''
+})
+
+describe('getFocusable', () => {
+  it('collects Tab-focusable elements in DOM order', () => {
+    const host = build(`
+      <a href="#">a</a>
+      <button>b</button>
+      <input />
+      <div tabindex="0">d</div>
+    `)
+    const f = getFocusable(host)
+    expect(f.map((el) => el.tagName.toLowerCase())).toEqual(['a', 'button', 'input', 'div'])
+  })
+
+  it('excludes disabled, tabindex=-1, hidden and aria-hidden elements', () => {
+    const host = build(`
+      <button disabled>disabled</button>
+      <button tabindex="-1">programmatic</button>
+      <button hidden>hidden</button>
+      <button aria-hidden="true">aria</button>
+      <button style="display:none">display-none</button>
+      <button>real</button>
+    `)
+    const f = getFocusable(host)
+    expect(f).toHaveLength(1)
+    expect(f[0]!.textContent).toBe('real')
+  })
+})
+
+describe('createFocusTrap', () => {
+  it('moves focus to the first focusable on activate', async () => {
+    const host = build(`<button>first</button><button>second</button>`)
+    const trap = createFocusTrap(host)
+    trap.activate()
+    await Promise.resolve()
+    expect(document.activeElement?.textContent).toBe('first')
+    trap.release()
+  })
+
+  it('honours an explicit initialFocus element', async () => {
+    const host = build(`<button>first</button><button id="target">second</button>`)
+    const target = host.querySelector<HTMLElement>('#target')!
+    const trap = createFocusTrap(host, { initialFocus: target })
+    trap.activate()
+    await Promise.resolve()
+    expect(document.activeElement).toBe(target)
+    trap.release()
+  })
+
+  it('wraps Tab from the last element back to the first', async () => {
+    const host = build(`<button>first</button><button>last</button>`)
+    const first = host.children[0] as HTMLElement
+    const last = host.children[1] as HTMLElement
+    const trap = createFocusTrap(host)
+    trap.activate()
+    await Promise.resolve()
+    last.focus()
+    document.dispatchEvent(new KeyboardEvent('keydown', { key: 'Tab', bubbles: true }))
+    expect(document.activeElement).toBe(first)
+    trap.release()
+  })
+
+  it('wraps Shift+Tab from the first element to the last', async () => {
+    const host = build(`<button>first</button><button>last</button>`)
+    const first = host.children[0] as HTMLElement
+    const last = host.children[1] as HTMLElement
+    const trap = createFocusTrap(host)
+    trap.activate()
+    await Promise.resolve()
+    first.focus()
+    document.dispatchEvent(new KeyboardEvent('keydown', { key: 'Tab', shiftKey: true, bubbles: true }))
+    expect(document.activeElement).toBe(last)
+    trap.release()
+  })
+
+  it('restores focus to the previously-focused element on release', async () => {
+    const outside = build(`<button id="opener">opener</button>`).querySelector<HTMLElement>('#opener')!
+    outside.focus()
+    const host = build(`<button>inner</button>`)
+    const trap = createFocusTrap(host)
+    trap.activate()
+    await Promise.resolve()
+    expect(document.activeElement?.textContent).toBe('inner')
+    trap.release()
+    expect(document.activeElement).toBe(outside)
+  })
+
+  it('calls onEscape when Escape is pressed while active', async () => {
+    const host = build(`<button>x</button>`)
+    let escaped = false
+    const trap = createFocusTrap(host, { onEscape: () => (escaped = true) })
+    trap.activate()
+    await Promise.resolve()
+    document.dispatchEvent(new KeyboardEvent('keydown', { key: 'Escape', bubbles: true }))
+    expect(escaped).toBe(true)
+    trap.release()
+  })
+})