@nexxtmove/ui 1.33.0 → 1.35.0

package/src/components/molecules/PickerList/PickerList.vue

@@ -0,0 +1,649 @@
+<script setup lang="ts">
+import { computed, nextTick, onBeforeUnmount, ref, useId, useTemplateRef, watch } from 'vue'
+import { usePreferredReducedMotion } from '@vueuse/core'
+import NexxtButton from '../../atoms/Button/Button.vue'
+import NexxtIcon, { type NexxtIconName } from '../../atoms/Icon/Icon.vue'
+import NexxtPickerItem from '../../atoms/PickerItem/PickerItem.vue'
+import NexxtPickerGroup from '../PickerGroup/PickerGroup.vue'
+
+export interface NexxtPickerItemData {
+  /** Stable id; also the base of the option's DOM id that `aria-activedescendant` points at. */
+  id: string
+  /** Visible label and accessible name of the option; searched and matched by type-ahead. */
+  label: string
+  /** Icon in front of the label, also passed to the `preview` slot. */
+  icon: NexxtIconName
+  /** Id of a group in `groups`. Missing, or not in `groups`: ungrouped, rendered at the top. */
+  group?: string
+  /** Extra search terms (synonyms, old names). Matched, never shown. */
+  keywords?: string[]
+  /** One line, shown in the preview and read out as the option's description. */
+  description?: string
+  /**
+   * Reachable with the arrows, type-ahead and the pointer, but never selected. Give a
+   * `description` that names the reason.
+   */
+  disabled?: boolean
+}
+
+export interface NexxtPickerGroupData {
+  /** Stable id; items join the group through their `group` field. */
+  id: string
+  /** Heading of the group, and the accessible name of its `role="group"`. */
+  label: string
+  /** Initial state, default `true`. After that the list keeps its own open/closed state. */
+  defaultOpen?: boolean
+}
+
+interface NexxtPickerListProps {
+  /** All items; `search` filters them. */
+  items: NexxtPickerItemData[]
+  /** Groups in display order. Ungrouped items come first. */
+  groups?: NexxtPickerGroupData[]
+  /** Search term from outside; the list renders no field of its own. Trimmed before matching. */
+  search?: string
+  /** Whether group headings fold their group. While searching every group is open regardless. */
+  collapsible?: boolean
+  /** Accessible name of the listbox. Required for an accessible name. */
+  ariaLabel?: string
+  /** Heading of the empty state, shown when the search has no results. */
+  emptyTitle?: string
+  /** Line under the empty heading. A function receives the trimmed search term. */
+  emptyDescription?: string | ((search: string) => string)
+  /** Label of the button in the empty state that clears the search. Without it there is no button. */
+  clearLabel?: string
+  /**
+   * Text announced in a polite live region 500ms after the search changes, e.g.
+   * `(n) => \`${n} resultaten\``. Without it the region stays empty.
+   */
+  resultsAnnouncement?: (count: number) => string
+}
+
+interface Section {
+  group: NexxtPickerGroupData
+  items: NexxtPickerItemData[]
+  open: boolean
+}
+
+/** `fold`: moved by a keyboard fold that animates; scrolled by `anchorFold` instead. */
+type HighlightSource = 'keyboard' | 'pointer' | 'fold' | 'other'
+
+defineOptions({ name: 'NexxtPickerList' })
+
+const props = withDefaults(defineProps<NexxtPickerListProps>(), {
+  groups: () => [],
+  search: '',
+  collapsible: true,
+})
+
+/**
+ * Id of the highlighted item. The list owns the effective value: an id that is not visible, or
+ * `null` while items are visible, is replaced by the first enabled visible item right away.
+ */
+const highlighted = defineModel<string | null>('highlighted', { default: null })
+
+const emit = defineEmits<{
+  /** Enter, Space or a click on an enabled item. */
+  select: [item: NexxtPickerItemData]
+  /** The highlighted item changed; `null` when nothing is visible. */
+  highlight: [item: NexxtPickerItemData | null]
+  /** Escape while the listbox has focus. */
+  close: []
+  /**
+   * The clear button of the empty state was pressed. Clear `search` in response; the button leaves
+   * the DOM with the empty state, so move focus yourself, e.g. back to the search field.
+   */
+  clear: []
+}>()
+
+defineSlots<{
+  /** Content of an option; the option element and its aria stay the list's own. */
+  item?(props: { item: NexxtPickerItemData; highlighted: boolean }): unknown
+  /** Replaces the content of the empty state. */
+  empty?(props: { search: string; clear: () => void }): unknown
+}>()
+
+const PAGE_SIZE = 8
+const TYPEAHEAD_RESET_MS = 800
+const ANNOUNCE_DELAY_MS = 500
+
+const listboxId = `${useId()}-listbox`
+// Encoded so an id with a space in it never reads as two id references
+const optionId = (id: string) => `${listboxId}-opt-${encodeURIComponent(id)}`
+
+const listbox = useTemplateRef<HTMLElement>('listbox')
+
+const preferredMotion = usePreferredReducedMotion()
+const reduced = computed(() => preferredMotion.value === 'reduce')
+
+// ─── Filtering ────────────────────────────────────────────────────────────────
+
+const normalize = (value: string) =>
+  value.normalize('NFD').replace(/\p{M}/gu, '').toLocaleLowerCase()
+
+const trimmedSearch = computed(() => props.search.trim())
+const query = computed(() => normalize(trimmedSearch.value))
+const searching = computed(() => query.value !== '')
+
+const matches = (item: NexxtPickerItemData) =>
+  !searching.value ||
+  normalize(item.label).includes(query.value) ||
+  !!item.keywords?.some((keyword) => normalize(keyword).includes(query.value))
+
+const matched = computed(() => props.items.filter(matches))
+
+const groupIds = computed(() => new Set(props.groups.map((group) => group.id)))
+
+const ungrouped = computed(() =>
+  matched.value.filter((item) => !item.group || !groupIds.value.has(item.group)),
+)
+
+// Only the groups a user toggled are recorded; the others follow their `defaultOpen`. New groups
+// therefore start at their default and existing ones keep their state.
+const openState = ref<Record<string, boolean>>({})
+
+const isOpen = (group: NexxtPickerGroupData) =>
+  openState.value[group.id] ?? group.defaultOpen ?? true
+
+// Searching renders every group open without touching `openState`, so clearing the search
+// brings the previous state back
+const canFold = computed(() => props.collapsible && !searching.value)
+
+/** Groups with at least one match; a group without any does not render at all. */
+const sections = computed<Section[]>(() =>
+  props.groups
+    .map((group) => ({
+      group,
+      items: matched.value.filter((item) => item.group === group.id),
+      open: !canFold.value || isOpen(group),
+    }))
+    .filter((section) => section.items.length > 0),
+)
+
+/** What arrows, type-ahead and the fallback work on, in display order. Never read off the DOM. */
+const visibleItems = computed(() => [
+  ...ungrouped.value,
+  ...sections.value.flatMap((section) => (section.open ? section.items : [])),
+])
+
+/** Anything rendered inside the listbox, closed group headings included. */
+const hasContent = computed(() => ungrouped.value.length > 0 || sections.value.length > 0)
+const showEmpty = computed(() => searching.value && visibleItems.value.length === 0)
+
+// ─── Highlight ────────────────────────────────────────────────────────────────
+
+const itemById = (id: string | null) =>
+  id === null ? null : (visibleItems.value.find((item) => item.id === id) ?? null)
+
+const fallbackId = computed(
+  () => (visibleItems.value.find((item) => !item.disabled) ?? visibleItems.value[0])?.id ?? null,
+)
+
+const effectiveId = computed(() =>
+  itemById(highlighted.value) ? highlighted.value : fallbackId.value,
+)
+
+const activeDescendantId = computed(() =>
+  effectiveId.value === null ? undefined : optionId(effectiveId.value),
+)
+
+// What moved the highlight last. A hover must not scroll the list away under the pointer.
+let source: HighlightSource = 'other'
+
+const setHighlight = (id: string | null, from: HighlightSource) => {
+  // any other highlight request supersedes a scroll still waiting for a fold to settle
+  if (from !== 'fold') foldTarget = null
+  if (id === effectiveId.value) return
+  source = from
+  highlighted.value = id
+}
+
+// The model always shows what is highlighted: a consumer setting `null` on a non-empty list
+// gets the fallback back
+watch(
+  [highlighted, effectiveId],
+  ([value, effective]) => {
+    if (value !== effective) highlighted.value = effective
+  },
+  { immediate: true },
+)
+
+watch(
+  effectiveId,
+  async (id) => {
+    emit('highlight', itemById(id))
+
+    const from = source
+    source = 'other'
+    if (from === 'pointer' || from === 'fold') return
+
+    await nextTick()
+    scrollToItem(id)
+  },
+  { immediate: true },
+)
+
+// A new search moves every row even when the highlight stays the same item: clearing a search
+// that found an item far down puts it back at its full-list position, out of view. So every
+// search change brings the highlight into view once the rows are rendered, whatever moved it
+// last: this scroll follows the search, not the pointer.
+watch(
+  () => props.search,
+  async () => {
+    await nextTick()
+    scrollToItem(effectiveId.value)
+  },
+)
+
+// ─── Scrolling ────────────────────────────────────────────────────────────────
+
+/**
+ * Brings an option into view inside the listbox only, `block: 'nearest'`. By hand rather than
+ * with `scrollIntoView`, which also scrolls every scrollable ancestor, the page included. The
+ * first option of a group brings its heading along.
+ */
+const scrollToItem = (id: string | null) => {
+  const option = id === null ? null : listbox.value?.ownerDocument.getElementById(optionId(id))
+  if (!option) return
+
+  const firstOfGroup = sections.value.some((section) => section.items[0]?.id === id)
+  scrollIntoRange((firstOfGroup && option.closest('[role="group"]')) || option, option)
+}
+
+/** Scrolls the listbox just enough to show from the top of `top` to the bottom of `bottom`. */
+const scrollIntoRange = (top: Element, bottom: Element) => {
+  const box = listbox.value
+  if (!box) return
+
+  // `FloatingPanel` scales its content in; rects are scaled, `scrollTop` is not
+  const boxRect = box.getBoundingClientRect()
+  const scale = box.offsetHeight ? boxRect.height / box.offsetHeight : 1
+  const offset = (rect: DOMRect, edge: 'top' | 'bottom') =>
+    (rect[edge] - boxRect.top) / scale + box.scrollTop
+
+  const style = getComputedStyle(box)
+  const start = offset(top.getBoundingClientRect(), 'top') - (parseFloat(style.paddingTop) || 0)
+  const end =
+    offset(bottom.getBoundingClientRect(), 'bottom') + (parseFloat(style.paddingBottom) || 0)
+
+  if (start < box.scrollTop) box.scrollTop = start
+  else if (end > box.scrollTop + box.clientHeight) box.scrollTop = end - box.clientHeight
+}
+
+/**
+ * An animated fold moves everything below the group for 120–160ms, so a highlight past it cannot
+ * be scrolled to until the rows have settled: measured earlier, it ends up above the view. The
+ * group's heading does not move, and the highlight lands right under it. So the heading is
+ * brought into view first, the content folds under it, and once the grid rows have finished the
+ * highlight itself is checked. Under reduced motion nothing animates and the normal scroll runs.
+ */
+let foldTarget: string | null = null
+
+const groupElement = (groupId: string) => {
+  const index = sections.value.findIndex((section) => section.group.id === groupId)
+  return listbox.value?.querySelectorAll(':scope > [role="group"]')[index] ?? null
+}
+
+const anchorFold = async (groupId: string, targetId: string) => {
+  foldTarget = targetId
+  await nextTick()
+
+  const group = groupElement(groupId)
+  const heading = group?.querySelector(':scope > [role="presentation"]')
+  if (group && heading) scrollIntoRange(group, heading)
+}
+
+// The fold wrapper is the only element under a group that animates its grid rows
+const onTransitionEnd = (event: TransitionEvent) => {
+  if (!foldTarget || event.propertyName !== 'grid-template-rows') return
+  if ((event.target as Element).parentElement?.getAttribute('role') !== 'group') return
+
+  scrollToItem(foldTarget)
+  foldTarget = null
+}
+
+// ─── Pointer ──────────────────────────────────────────────────────────────────
+
+// Chromium sends a synthetic mouse move after a scroll. Without this guard, the option under a
+// resting cursor would take the highlight from the keyboard after every scrolled arrow press.
+let lastPointer: { x: number; y: number } | null = null
+let pointerMoved = false
+
+const onPointerMove = (event: PointerEvent) => {
+  pointerMoved =
+    lastPointer !== null && (lastPointer.x !== event.clientX || lastPointer.y !== event.clientY)
+  lastPointer = { x: event.clientX, y: event.clientY }
+}
+
+const onItemPointer = (item: NexxtPickerItemData) => {
+  if (pointerMoved) setHighlight(item.id, 'pointer')
+}
+
+// ─── Folding ──────────────────────────────────────────────────────────────────
+
+const setOpen = (groupId: string, open: boolean) => {
+  openState.value = { ...openState.value, [groupId]: open }
+}
+
+/**
+ * Closes a group. When it holds the highlight, the highlight moves first — to the first item of
+ * the next open group, else the last item before it — or the fallback would jump to the top.
+ */
+const collapse = (groupId: string, from: HighlightSource) => {
+  const index = sections.value.findIndex((section) => section.group.id === groupId)
+  const current = itemById(effectiveId.value)
+
+  if (index >= 0 && current?.group === groupId) {
+    const after = sections.value.slice(index + 1).find((section) => section.open)
+    const before = sections.value
+      .slice(0, index)
+      .reverse()
+      .find((section) => section.open)
+    const target = after?.items[0] ?? before?.items.at(-1) ?? ungrouped.value.at(-1) ?? null
+    // Rows above the folding group keep their place, so only a target after it has to wait
+    const settles = !!target && target === after?.items[0] && from === 'keyboard' && !reduced.value
+
+    setHighlight(target?.id ?? null, settles ? 'fold' : from)
+    setOpen(groupId, false)
+    if (settles && target) anchorFold(groupId, target.id)
+    return
+  }
+
+  setOpen(groupId, false)
+}
+
+/** Opens a group and highlights its first item. */
+const expand = (section: Section, from: HighlightSource) => {
+  setOpen(section.group.id, true)
+  const first = section.items[0]
+  if (!first) return
+
+  const settles = from === 'keyboard' && !reduced.value
+  setHighlight(first.id, settles ? 'fold' : from)
+  if (settles) anchorFold(section.group.id, first.id)
+}
+
+const onGroupToggle = (section: Section, open: boolean) => {
+  // a click never scrolls, not even one that was still pending from an earlier keyboard fold
+  foldTarget = null
+  if (open) setOpen(section.group.id, true)
+  else collapse(section.group.id, 'pointer')
+}
+
+/**
+ * The next closed group after the highlighted item's group, else the closest one before it.
+ * Without this a folded group could not be reached from the keyboard at all.
+ */
+const nextClosedSection = () => {
+  const current = itemById(effectiveId.value)
+  const index = current?.group
+    ? sections.value.findIndex((section) => section.group.id === current.group)
+    : -1
+
+  return (
+    sections.value.slice(index + 1).find((section) => !section.open) ??
+    sections.value
+      .slice(0, Math.max(index, 0))
+      .reverse()
+      .find((section) => !section.open)
+  )
+}
+
+// ─── Keyboard ─────────────────────────────────────────────────────────────────
+
+/** Moves the highlight by `delta` visible items; stops at either end, never wraps. */
+const move = (delta: number) => {
+  const list = visibleItems.value
+
+  if (list.length === 0) {
+    // Every group is folded: ↓ opens the first one
+    const closed = canFold.value && delta > 0 ? sections.value.find((s) => !s.open) : undefined
+    if (closed) expand(closed, 'keyboard')
+    return
+  }
+
+  const index = list.findIndex((item) => item.id === effectiveId.value)
+  const next = Math.min(Math.max(index + delta, 0), list.length - 1)
+  setHighlight(list[next].id, 'keyboard')
+}
+
+/** Highlights the first visible item. */
+const highlightFirst = () => {
+  const first = visibleItems.value[0]
+  if (first) setHighlight(first.id, 'keyboard')
+}
+
+/** Highlights the last visible item. */
+const highlightLast = () => {
+  const last = visibleItems.value.at(-1)
+  if (last) setHighlight(last.id, 'keyboard')
+}
+
+/** Emits `select` for the highlighted item; does nothing when there is none or it is disabled. */
+const selectHighlighted = () => {
+  const item = itemById(effectiveId.value)
+  if (item && !item.disabled) emit('select', item)
+}
+
+let typeahead = ''
+let typeaheadTimer: ReturnType<typeof setTimeout> | undefined
+
+const onTypeahead = (key: string) => {
+  clearTimeout(typeaheadTimer)
+  typeahead += normalize(key)
+  typeaheadTimer = setTimeout(() => (typeahead = ''), TYPEAHEAD_RESET_MS)
+
+  const match = visibleItems.value.find((item) => normalize(item.label).startsWith(typeahead))
+  if (match) setHighlight(match.id, 'keyboard')
+}
+
+const isPrintable = (event: KeyboardEvent) =>
+  [...event.key].length === 1 && !event.ctrlKey && !event.metaKey && !event.altKey
+
+const onKeydown = (event: KeyboardEvent) => {
+  if (event.isComposing) return
+
+  switch (event.key) {
+    case 'ArrowDown':
+      move(1)
+      break
+    case 'ArrowUp':
+      move(-1)
+      break
+    case 'PageDown':
+      move(PAGE_SIZE)
+      break
+    case 'PageUp':
+      move(-PAGE_SIZE)
+      break
+    case 'Home':
+      highlightFirst()
+      break
+    case 'End':
+      highlightLast()
+      break
+    case 'Enter':
+    case ' ':
+      selectHighlighted()
+      break
+    case 'ArrowLeft': {
+      const group = itemById(effectiveId.value)?.group
+      if (!canFold.value || !group || !groupIds.value.has(group)) return
+      collapse(group, 'keyboard')
+      break
+    }
+    case 'ArrowRight': {
+      if (!canFold.value) return
+      const closed = nextClosedSection()
+      if (!closed) return
+      expand(closed, 'keyboard')
+      break
+    }
+    case 'Escape':
+      // No stopPropagation: a surrounding FloatingPanel closes on the same key
+      emit('close')
+      break
+    default:
+      if (!isPrintable(event)) return
+      onTypeahead(event.key)
+  }
+
+  event.preventDefault()
+}
+
+/** Focuses the listbox without scrolling any ancestor. */
+const focus = () => {
+  listbox.value?.focus({ preventScroll: true })
+}
+
+// ─── Empty state and announcement ─────────────────────────────────────────────
+
+const emptyDescriptionText = computed(() =>
+  typeof props.emptyDescription === 'function'
+    ? props.emptyDescription(trimmedSearch.value)
+    : props.emptyDescription,
+)
+
+const clear = () => emit('clear')
+
+const announcement = ref('')
+let announceTimer: ReturnType<typeof setTimeout> | undefined
+
+// Only after the search changed, debounced, so intermediate states while typing stay silent
+watch(
+  () => props.search,
+  () => {
+    clearTimeout(announceTimer)
+    announceTimer = setTimeout(() => {
+      announcement.value = props.resultsAnnouncement?.(visibleItems.value.length) ?? ''
+    }, ANNOUNCE_DELAY_MS)
+  },
+)
+
+onBeforeUnmount(() => {
+  clearTimeout(announceTimer)
+  clearTimeout(typeaheadTimer)
+})
+
+const leaveNow = (_el: Element, done: () => void) => done()
+
+const itemProps = (item: NexxtPickerItemData) => ({
+  id: optionId(item.id),
+  label: item.label,
+  icon: item.icon,
+  description: item.description,
+  disabled: item.disabled,
+  highlighted: item.id === effectiveId.value,
+})
+
+const LISTBOX_CLASSES = {
+  base: 'group/listbox min-h-0 overflow-y-auto overscroll-contain scrollbar-thin focus-visible:outline-2 focus-visible:-outline-offset-2 focus-visible:outline-cornflower-blue-500',
+  filled: 'flex flex-1 flex-col gap-0.5 p-2',
+}
+
+const EMPTY_CLASSES = {
+  default: 'flex flex-1 flex-col items-center justify-center gap-1 px-4 py-8 text-center',
+  custom: 'flex flex-1 flex-col',
+}
+
+const listboxClass = computed(() => [
+  LISTBOX_CLASSES.base,
+  hasContent.value && LISTBOX_CLASSES.filled,
+])
+
+defineExpose({
+  focus,
+  move,
+  highlightFirst,
+  highlightLast,
+  selectHighlighted,
+  /** DOM id of the listbox, for `aria-controls` on a field that drives it. */
+  listboxId,
+  /** DOM id of the highlighted option, for `aria-activedescendant` on a field that drives it. */
+  activeDescendantId,
+})
+</script>
+
+<template>
+  <div class="flex min-h-0 flex-col">
+    <!-- A tab stop while there is something to walk through; with zero results the tab order
+         goes straight to the clear button. It stays in the DOM, so `aria-controls` stays valid. -->
+    <div
+      :id="listboxId"
+      ref="listbox"
+      role="listbox"
+      :tabindex="hasContent ? 0 : -1"
+      :aria-label="ariaLabel"
+      :aria-activedescendant="activeDescendantId"
+      :class="listboxClass"
+      @keydown="onKeydown"
+      @focus="scrollToItem(effectiveId)"
+      @pointermove.capture="onPointerMove"
+      @transitionend="onTransitionEnd"
+    >
+      <NexxtPickerItem
+        v-for="item in ungrouped"
+        :key="item.id"
+        v-bind="itemProps(item)"
+        @select="emit('select', item)"
+        @highlight="onItemPointer(item)"
+      >
+        <template v-if="$slots.item" #default>
+          <slot name="item" :item="item" :highlighted="item.id === effectiveId" />
+        </template>
+      </NexxtPickerItem>
+
+      <!-- Keyed apart while searching: entering or leaving a search remounts the groups instead of
+           changing their `open`, so the fold does not animate. Filtering never animates; only a
+           click or ←/→ does. -->
+      <NexxtPickerGroup
+        v-for="section in sections"
+        :key="searching ? `search:${section.group.id}` : section.group.id"
+        :label="section.group.label"
+        :open="section.open"
+        :collapsible="canFold"
+        @update:open="onGroupToggle(section, $event)"
+      >
+        <NexxtPickerItem
+          v-for="item in section.items"
+          :key="item.id"
+          v-bind="itemProps(item)"
+          @select="emit('select', item)"
+          @highlight="onItemPointer(item)"
+        >
+          <template v-if="$slots.item" #default>
+            <slot name="item" :item="item" :highlighted="item.id === effectiveId" />
+          </template>
+        </NexxtPickerItem>
+      </NexxtPickerGroup>
+    </div>
+
+    <Transition
+      :css="!reduced"
+      enter-active-class="transition-opacity duration-120 ease-out motion-reduce:transition-none"
+      enter-from-class="opacity-0"
+      @leave="leaveNow"
+    >
+      <div v-if="showEmpty" :class="$slots.empty ? EMPTY_CLASSES.custom : EMPTY_CLASSES.default">
+        <slot name="empty" :search="trimmedSearch" :clear="clear">
+          <NexxtIcon
+            name="magnifying-glass"
+            aria-hidden="true"
+            class="mb-1 text-2xl text-gray-400"
+          />
+          <p v-if="emptyTitle" class="small-semibold text-gray-900">{{ emptyTitle }}</p>
+          <p v-if="emptyDescriptionText" class="extra-small-normal text-gray-700">
+            {{ emptyDescriptionText }}
+          </p>
+          <div v-if="clearLabel" class="mt-3">
+            <NexxtButton variant="link" @click="clear">{{ clearLabel }}</NexxtButton>
+          </div>
+        </slot>
+      </div>
+    </Transition>
+
+    <div role="status" aria-live="polite" aria-atomic="true" class="sr-only">
+      {{ announcement }}
+    </div>
+  </div>
+</template>