@nexxtmove/ui 1.32.0 → 1.34.0

package/src/components/organisms/PickerPanel/PickerPanel.vue

@@ -0,0 +1,267 @@
+<script setup lang="ts">
+import { computed, nextTick, onMounted, ref, useTemplateRef } from 'vue'
+import { useResizeObserver } from '@vueuse/core'
+import NexxtPickerPreview from '../../atoms/PickerPreview/PickerPreview.vue'
+import NexxtInputField from '../../molecules/InputField/InputField.vue'
+import NexxtPickerList, {
+  type NexxtPickerGroupData,
+  type NexxtPickerItemData,
+} from '../../molecules/PickerList/PickerList.vue'
+
+interface NexxtPickerPanelProps {
+  /** All items; the search field filters them. */
+  items: NexxtPickerItemData[]
+  /** Groups in display order. Ungrouped items come first. */
+  groups?: NexxtPickerGroupData[]
+  /** Render the search field. Without it the listbox takes focus on mount. */
+  searchable?: boolean
+  /** Placeholder of the search field. */
+  searchPlaceholder?: string
+  /** Accessible name of the search field. Required for an accessible name; the placeholder is only a fallback. */
+  searchLabel?: string
+  /** Accessible name of the panel (`role="group"`). Required for an accessible name. */
+  ariaLabel?: string
+  /** Accessible name of the listbox. Required for an accessible name. */
+  listLabel?: string
+  /** Panel width; a number is in pixels. The columns never shrink with it. */
+  width?: number | string
+  /** Panel height; a number is in pixels. Clamped to `calc(100dvh - 5rem)`, and only the list gives way. */
+  height?: number | string
+  /** Below this height of the column row (the panel minus the header), in pixels, the preview column is left out and the list takes the full width. */
+  hidePreviewBelow?: number
+  /** Whether group headings fold their group. */
+  collapsible?: boolean
+  /** 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 in the preview frame while nothing is highlighted; the `preview-empty` slot replaces it. */
+  previewEmptyText?: string
+  /** Text announced 500ms after the search changes, e.g. `(n) => \`${n} resultaten\``. */
+  resultsAnnouncement?: (count: number) => string
+}
+
+defineOptions({ name: 'NexxtPickerPanel' })
+
+const props = withDefaults(defineProps<NexxtPickerPanelProps>(), {
+  groups: () => [],
+  searchable: true,
+  width: 640,
+  height: 420,
+  hidePreviewBelow: 340,
+  collapsible: true,
+})
+
+/** Id of the highlighted item; the list keeps it on a visible item. Drives the preview. */
+const highlighted = defineModel<string | null>('highlighted', { default: null })
+
+/** The search term. Bind it to reset or prefill the search; unbound, the panel keeps its own. */
+const search = defineModel<string>('search', { default: '' })
+
+const emit = defineEmits<{
+  /** Enter, Space or a click on an enabled item. The panel never closes itself. */
+  select: [item: NexxtPickerItemData]
+  /** The highlighted item changed; `null` when nothing is visible. */
+  highlight: [item: NexxtPickerItemData | null]
+  /**
+   * Escape in an empty search field, or in the listbox. A surrounding `NexxtFloatingPanel`
+   * closes on the same key, so keep the handler idempotent.
+   */
+  close: []
+}>()
+
+defineSlots<{
+  /** Above both columns, e.g. `NexxtTabs`. */
+  header?(): unknown
+  /** Content of the preview frame for the highlighted item. */
+  preview?(props: { item: NexxtPickerItemData }): unknown
+  /** Replaces `previewEmptyText` in the preview frame. */
+  'preview-empty'?(): unknown
+  /** Content of an option. */
+  item?(props: { item: NexxtPickerItemData; highlighted: boolean }): unknown
+  /** Replaces the content of the empty search state. */
+  empty?(props: { search: string; clear: () => void }): unknown
+}>()
+
+const inputField = useTemplateRef<InstanceType<typeof NexxtInputField>>('inputField')
+const list = useTemplateRef<InstanceType<typeof NexxtPickerList>>('list')
+const row = useTemplateRef<HTMLElement>('row')
+
+const PAGE_SIZE = 8
+
+const toLength = (value: number | string) => (typeof value === 'number' ? `${value}px` : value)
+
+const panelStyle = computed(() => {
+  const height = `min(${toLength(props.height)}, calc(100dvh - 5rem))`
+  return { width: toLength(props.width), height, maxHeight: height }
+})
+
+// Layout height of the column row. Not `getBoundingClientRect()`: a FloatingPanel scales its
+// content in, which would read 5% short. 0 means unknown (jsdom, a hidden tab): show the preview.
+const rowHeight = ref(0)
+
+useResizeObserver(row, ([entry]) => {
+  rowHeight.value =
+    entry.borderBoxSize?.[0]?.blockSize ?? (entry.target as HTMLElement).offsetHeight
+})
+
+const showPreview = computed(
+  () => rowHeight.value === 0 || rowHeight.value >= props.hidePreviewBelow,
+)
+
+const highlightedItem = computed(
+  () => props.items.find((item) => item.id === highlighted.value) ?? null,
+)
+
+/** Focuses the search field, or the listbox when the panel is not searchable. */
+const focus = () => {
+  if (props.searchable) inputField.value?.inputEl?.focus({ preventScroll: true })
+  else list.value?.focus()
+}
+
+onMounted(async () => {
+  // Measured before the first paint, so the preview never flashes in and out
+  if (row.value) rowHeight.value = row.value.offsetHeight
+
+  // One tick for the list's template ref to land, so the field already carries
+  // `aria-controls` and `aria-activedescendant` when it receives focus. `preventScroll`: a
+  // FloatingPanel is still in its enter transition here.
+  await nextTick()
+  focus()
+})
+
+const onSearchKeydown = (event: KeyboardEvent) => {
+  if (event.isComposing) return
+
+  switch (event.key) {
+    case 'ArrowDown':
+      list.value?.move(1)
+      break
+    case 'ArrowUp':
+      list.value?.move(-1)
+      break
+    case 'PageDown':
+      list.value?.move(PAGE_SIZE)
+      break
+    case 'PageUp':
+      list.value?.move(-PAGE_SIZE)
+      break
+    case 'Enter':
+      // Always prevented: the field may sit in a form
+      list.value?.selectHighlighted()
+      break
+    case 'Escape':
+      if (search.value === '') {
+        // Left to propagate: a surrounding FloatingPanel closes on it too
+        emit('close')
+        return
+      }
+      search.value = ''
+      // A FloatingPanel listens on `document` and would close on the first press already
+      event.stopPropagation()
+      break
+    // Home, End, ← and → stay cursor keys in a text field
+    default:
+      return
+  }
+
+  event.preventDefault()
+}
+
+// Focus moves in the same handler, before the clear button leaves the DOM with the empty state
+const onClear = () => {
+  search.value = ''
+  focus()
+}
+
+defineExpose({ focus })
+
+const COLUMN_CLASSES = {
+  withPreview: 'flex w-66 shrink-0 flex-col border-r border-gray-200',
+  full: 'flex w-full flex-col',
+}
+</script>
+
+<template>
+  <div
+    role="group"
+    :aria-label="ariaLabel"
+    class="flex flex-col overflow-hidden"
+    :style="panelStyle"
+  >
+    <div v-if="$slots.header" class="shrink-0 border-b border-gray-200 p-3">
+      <slot name="header" />
+    </div>
+
+    <div ref="row" class="flex min-h-0 flex-1">
+      <div :class="showPreview ? COLUMN_CLASSES.withPreview : COLUMN_CLASSES.full">
+        <!-- `text-gray-700` colours the magnifying glass; the input sets its own text colour.
+             `[&_input]:min-w-0` lifts the input's own `min-w-60` inside the panel only; with it
+             the field overflows the 240px column and a long term loses its caret. -->
+        <div v-if="searchable" class="shrink-0 border-b border-gray-200 p-3 text-gray-700">
+          <NexxtInputField
+            ref="inputField"
+            v-model="search"
+            type="text"
+            role="combobox"
+            aria-expanded="true"
+            aria-autocomplete="list"
+            autocomplete="off"
+            spellcheck="false"
+            left-icon="magnifying-glass"
+            class="w-full [&_input]:min-w-0"
+            :placeholder="searchPlaceholder"
+            :aria-label="searchLabel"
+            :aria-controls="list?.listboxId"
+            :aria-activedescendant="list?.activeDescendantId"
+            @keydown="onSearchKeydown"
+          />
+        </div>
+
+        <NexxtPickerList
+          ref="list"
+          v-model:highlighted="highlighted"
+          class="min-h-0 flex-1"
+          :items="items"
+          :groups="groups"
+          :search="search"
+          :collapsible="collapsible"
+          :aria-label="listLabel"
+          :empty-title="emptyTitle"
+          :empty-description="emptyDescription"
+          :clear-label="clearLabel"
+          :results-announcement="resultsAnnouncement"
+          @select="emit('select', $event)"
+          @highlight="emit('highlight', $event)"
+          @close="emit('close')"
+          @clear="onClear"
+        >
+          <template v-if="$slots.item" #item="scope">
+            <slot name="item" v-bind="scope" />
+          </template>
+          <template v-if="$slots.empty" #empty="scope">
+            <slot name="empty" v-bind="scope" />
+          </template>
+        </NexxtPickerList>
+      </div>
+
+      <div v-if="showPreview" class="min-w-0 flex-1 overflow-hidden p-4">
+        <NexxtPickerPreview
+          :content-key="highlighted ?? undefined"
+          :title="highlightedItem?.label"
+          :description="highlightedItem?.description"
+          :empty-text="previewEmptyText"
+        >
+          <template v-if="highlightedItem && $slots.preview" #default>
+            <slot name="preview" :item="highlightedItem" />
+          </template>
+          <template v-if="$slots['preview-empty']" #empty>
+            <slot name="preview-empty" />
+          </template>
+        </NexxtPickerPreview>
+      </div>
+    </div>
+  </div>
+</template>

package/src/components.json

@@ -9,6 +9,8 @@
   "NexxtFloatingPanel": "components/atoms/FloatingPanel/FloatingPanel.vue",
   "NexxtIcon": "components/atoms/Icon/Icon.vue",
   "NexxtLoader": "components/atoms/Loader/Loader.vue",
+  "NexxtPickerItem": "components/atoms/PickerItem/PickerItem.vue",
+  "NexxtPickerPreview": "components/atoms/PickerPreview/PickerPreview.vue",
   "NexxtPresenceIndicator": "components/atoms/PresenceIndicator/PresenceIndicator.vue",
   "NexxtPropertyListing": "components/atoms/PropertyListing/PropertyListing.vue",
   "NexxtSelectableOption": "components/atoms/SelectableOption/SelectableOption.vue",
@@ -30,6 +32,8 @@
   "NexxtPageMockup": "components/molecules/PageMockup/PageMockup.vue",
   "NexxtPageTypeTile": "components/molecules/PageTypeTile/PageTypeTile.vue",
   "NexxtPagination": "components/molecules/Pagination/Pagination.vue",
+  "NexxtPickerGroup": "components/molecules/PickerGroup/PickerGroup.vue",
+  "NexxtPickerList": "components/molecules/PickerList/PickerList.vue",
   "NexxtPlaceholderInput": "components/molecules/PlaceholderInput/PlaceholderInput.vue",
   "NexxtPropertyCard": "components/molecules/PropertyCard/PropertyCard.vue",
   "NexxtSelect": "components/molecules/Select/Select.vue",
@@ -57,6 +61,7 @@
   "NexxtDropdownButton": "components/organisms/DropdownButton/DropdownButton.vue",
   "NexxtHeader": "components/organisms/Header/Header.vue",
   "NexxtModal": "components/organisms/Modal/Modal.vue",
+  "NexxtPickerPanel": "components/organisms/PickerPanel/PickerPanel.vue",
   "NexxtProgressBar": "components/organisms/ProgressBar/ProgressBar.vue",
   "NexxtReferenceCard": "components/organisms/ReferenceCard/ReferenceCard.vue",
   "NexxtSocialMediaTemplate": "components/organisms/SocialMediaTemplate/SocialMediaTemplate.vue",

package/src/index.ts

@@ -18,6 +18,10 @@ export type {
   NexxtPageCardSlots,
 } from './components/molecules/PageCard/PageCard.vue'
 export type { NexxtPageMockupType } from './components/molecules/PageMockup/PageMockup.vue'
+export type {
+  NexxtPickerGroupData,
+  NexxtPickerItemData,
+} from './components/molecules/PickerList/PickerList.vue'
 export type {
   NexxtTreeNode,
   NexxtTreeProps,
@@ -57,6 +61,7 @@ export type {
   EditorHeadingTypeMessages,
   EditorHeadingTypeValue,
 } from './components/editor/molecules/EditorHeadingType/EditorHeadingType.vue'
+export { EDITOR_RADIUS_STEPS } from './components/editor/molecules/EditorRadius/EditorRadius.vue'
 export type {
   EditorRadiusMessages,
   EditorRadiusValue,
@@ -126,6 +131,11 @@ export { default as NexxtPageContainer } from './components/molecules/PageContai
 export { default as NexxtPageMockup } from './components/molecules/PageMockup/PageMockup.vue'
 export { default as NexxtPageTypeTile } from './components/molecules/PageTypeTile/PageTypeTile.vue'
 export { default as NexxtPagination } from './components/molecules/Pagination/Pagination.vue'
+export { default as NexxtPickerGroup } from './components/molecules/PickerGroup/PickerGroup.vue'
+export { default as NexxtPickerItem } from './components/atoms/PickerItem/PickerItem.vue'
+export { default as NexxtPickerList } from './components/molecules/PickerList/PickerList.vue'
+export { default as NexxtPickerPanel } from './components/organisms/PickerPanel/PickerPanel.vue'
+export { default as NexxtPickerPreview } from './components/atoms/PickerPreview/PickerPreview.vue'
 export { default as NexxtPlaceholderInput } from './components/molecules/PlaceholderInput/PlaceholderInput.vue'
 export { default as NexxtPresenceIndicator } from './components/atoms/PresenceIndicator/PresenceIndicator.vue'
 export { default as NexxtProgressBar } from './components/organisms/ProgressBar/ProgressBar.vue'