npm - @nexxtmove/ui - Versions diffs - 1.32.0 → 1.34.0 - Mend

@nexxtmove/ui 1.32.0 → 1.34.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (21) hide show

package/dist/components/atoms/FloatingPanel/FloatingPanel.vue.d.ts +48 -7
package/dist/components/atoms/PickerItem/PickerItem.vue.d.ts +40 -0
package/dist/components/atoms/PickerPreview/PickerPreview.vue.d.ts +29 -0
package/dist/components/editor/molecules/EditorRadius/EditorRadius.vue.d.ts +4 -4
package/dist/components/molecules/PickerGroup/PickerGroup.vue.d.ts +32 -0
package/dist/components/molecules/PickerList/PickerList.vue.d.ts +107 -0
package/dist/components/organisms/ColorPicker/ColorPicker.vue.d.ts +1 -1
package/dist/components/organisms/PickerPanel/PickerPanel.vue.d.ts +93 -0
package/dist/index.d.ts +7 -0
package/dist/index.js +2368 -1643
package/dist/nuxt.js +5 -0
package/package.json +1 -1
package/src/components/atoms/FloatingPanel/FloatingPanel.vue +280 -20
package/src/components/atoms/PickerItem/PickerItem.vue +113 -0
package/src/components/atoms/PickerPreview/PickerPreview.vue +99 -0
package/src/components/editor/molecules/EditorRadius/EditorRadius.vue +6 -6
package/src/components/molecules/PickerGroup/PickerGroup.vue +107 -0
package/src/components/molecules/PickerList/PickerList.vue +649 -0
package/src/components/organisms/PickerPanel/PickerPanel.vue +267 -0
package/src/components.json +5 -0
package/src/index.ts +10 -0

package/dist/nuxt.js CHANGED Viewed

@@ -12,6 +12,8 @@ var s = {
 	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",
@@ -33,6 +35,8 @@ var s = {
 	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",
@@ -60,6 +64,7 @@ var s = {
 	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/package.json CHANGED Viewed

@@ -1,7 +1,7 @@
 {
   "name": "@nexxtmove/ui",
   "type": "module",
-  "version": "1.32.0",
+  "version": "1.34.0",
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",

package/src/components/atoms/FloatingPanel/FloatingPanel.vue CHANGED Viewed

@@ -1,5 +1,18 @@
 <script lang="ts" setup>
-import { ref, useTemplateRef, computed, watch, nextTick, onMounted, onUnmounted } from 'vue'
+import {
+  ref,
+  useTemplateRef,
+  computed,
+  watch,
+  nextTick,
+  onMounted,
+  onUnmounted,
+  h,
+  readonly,
+  Teleport,
+  type FunctionalComponent,
+} from 'vue'
+import { usePreferredReducedMotion } from '@vueuse/core'
 import { useFloating, autoUpdate, flip, shift, offset, size } from '@floating-ui/vue'
 import type { Placement } from '@floating-ui/vue'
@@ -10,10 +23,93 @@ export interface NexxtFloatingPanelProps {
   offsetDistance?: number
   /** Stretch the panel to at least the trigger's width. */
   matchWidth?: boolean
-  /** Wrap the content slot in the shared panel surface (rounded, bordered, white, shadowed). */
-  surface?: boolean
+  /**
+   * Wrap the content slot in the shared panel surface. `true` is the surface for small
+   * dropdowns (gray-200 border, `shadow-sm`). `'raised'` is for large panels over a white page,
+   * such as a picker: heavier border and `shadow-lg`, so the panel reads as a layer above the
+   * page instead of part of it.
+   */
+  // `boolean` must come first: Vue then casts the bare attribute `surface` to `true`. With
+  // `String` first it becomes `''`, which is falsy, and the surface silently disappears.
+  surface?: boolean | 'raised'
+  /**
+   * Limit the content to the room on the roomiest side of the trigger (top or bottom), minus the
+   * offset and an 8px viewport margin. The value reaches the content as the `availableHeight`
+   * slot prop and as the CSS variable `--floating-panel-available-height` on the positioning
+   * element. The panel sets no height itself: the content decides how to use it. Follows
+   * scroll and resize while open.
+   */
+  fitHeight?: boolean
+  /**
+   * Render the panel at the end of `<body>` instead of next to the trigger, so it is no longer in
+   * the stacking context of the trigger's ancestors (a sibling with the same z-index can paint
+   * over a non-teleported panel). Keyboard order stays as if the panel followed the trigger.
+   * Costs: the panel no longer inherits font, colour or CSS variables from around the trigger,
+   * and DOM events from the panel no longer bubble through the trigger's ancestors.
+   * Ignored inside a `role="dialog"` (e.g. `NexxtModal`): Reka makes everything outside the
+   * dialog `pointer-events: none` and traps focus inside it. The panel stays in place there;
+   * `position: fixed` already escapes the dialog's overflow. Whether the panel was actually
+   * teleported is the `teleported` slot prop of `#content`, and `teleported` on the instance.
+   *
+   * Keyboard order is kept by invisible focus guards: one at the end of the trigger wrapper, and
+   * one at the start and end of the panel. A consumer that closes on `focusout` therefore sees
+   * focus land on a guard first and on its real target right after; check `relatedTarget` against
+   * the panel and the trigger, not against a list of expected elements. Listen on the exposed
+   * `floatingRef`, not on the slot content: the guards sit outside the content, so the final step
+   * out of the panel is a `focusout` of a guard that the content never sees. Focus inside the panel
+   * goes back to the trigger when it closes. Known limitation: with two teleported panels open at
+   * once, Tab from one can end up in the other.
+   */
+  teleport?: boolean
 }
+type GuardEdge = 'bridge' | 'start' | 'end'
+// Mirrors shift({ padding: 8 }), so the panel keeps the same gap to every viewport edge.
+const VIEWPORT_MARGIN = 8
+// The surface wrapper's `border`, top plus bottom.
+const SURFACE_BORDER = 2
+const SURFACE_CLASSES = {
+  default: 'overflow-hidden rounded-xl border border-gray-200 bg-white shadow-sm',
+  raised: 'overflow-hidden rounded-xl border border-gray-300 bg-white shadow-lg',
+}
+const TABBABLE =
+  'a[href], button:not([disabled]), input:not([disabled]):not([type="hidden"]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex="-1"])'
+// Reka puts `role="dialog"` on its content but no `aria-modal`, so match on the role.
+const DIALOG = '[role="dialog"], [role="alertdialog"]'
+/*
+ * Renders its single slot child in place, or teleported when `to` is set. Returning the child
+ * itself (not an array, not a disabled <Teleport>) keeps the non-teleported DOM byte-identical:
+ * a disabled Teleport still leaves `teleport start/end` anchors next to the trigger.
+ */
+const MaybeTeleport: FunctionalComponent<{ to?: string }> = (props, { slots }) =>
+  props.to ? h(Teleport, { to: props.to }, slots.default?.() ?? []) : slots.default?.()[0]
+MaybeTeleport.props = ['to']
+/*
+ * An invisible tab stop that hands focus on, used only while teleported. Inactive it renders an
+ * empty fragment rather than a `v-if` comment, so the default DOM gains no node that shows in
+ * the markup. No `aria-hidden`: on a focusable element that is the axe rule `aria-hidden-focus`.
+ */
+const FocusGuard: FunctionalComponent<
+  { edge: GuardEdge; active: boolean },
+  { enter: [event: FocusEvent] }
+> = (props, { emit }) =>
+  props.active
+    ? h('span', {
+        tabindex: 0,
+        'data-focus-guard': props.edge,
+        class: 'pointer-events-none fixed opacity-0',
+        onFocus: (event: FocusEvent) => emit('enter', event),
+      })
+    : []
+FocusGuard.props = ['edge', 'active']
+FocusGuard.emits = ['enter']
 defineOptions({ name: 'NexxtFloatingPanel' })
 const props = withDefaults(defineProps<NexxtFloatingPanelProps>(), {
@@ -21,6 +117,8 @@ const props = withDefaults(defineProps<NexxtFloatingPanelProps>(), {
   offsetDistance: 8,
   matchWidth: false,
   surface: false,
+  fitHeight: false,
+  teleport: false,
 })
 const emit = defineEmits<{
@@ -36,6 +134,24 @@ const isLeaving = ref(false)
 const isReady = ref(false)
 const triggerRef = useTemplateRef('triggerRef')
 const floatingRef = useTemplateRef('floatingRef')
+/**
+ * Whether the current (or last) open cycle rendered the panel in `<body>`: `teleport` was set and
+ * the trigger is not inside a `role="dialog"`. Decided once per open cycle in open(), since
+ * flipping it while open would remount the panel.
+ */
+const teleported = ref(false)
+const availableHeight = ref<number | null>(null)
+const preferredMotion = usePreferredReducedMotion()
+// `motion-reduce:transition-none` alone leaves Vue reading the duration off the leaving
+// element, so a closed panel would linger; without CSS mode it goes in the same patch.
+const reduced = computed(() => preferredMotion.value === 'reduce')
+const surfaceClass = computed(
+  () => SURFACE_CLASSES[props.surface === 'raised' ? 'raised' : 'default'],
+)
+const slotAvailableHeight = computed(() => (props.fitHeight ? availableHeight.value : null))
+const bridgeActive = computed(() => teleported.value && isOpen.value)
 const middleware = computed(() => [
   offset(props.offsetDistance),
@@ -50,6 +166,29 @@ const middleware = computed(() => [
         }),
       ]
     : []),
+  // A separate size() so the matchWidth path stays exactly as it was. It measures the roomiest
+  // side, not the side flip() picked: the first pass runs on an empty panel, which always fits
+  // the preferred side, and sizing to that side would stop the content from ever flipping.
+  ...(props.fitHeight
+    ? [
+        size({
+          apply: ({ elements, placement }) => {
+            const rect = elements.reference.getBoundingClientRect()
+            const viewport = document.documentElement.clientHeight
+            const side = placement.split('-')[0]
+            const room =
+              side === 'top' || side === 'bottom'
+                ? Math.max(rect.top, viewport - rect.bottom) -
+                  props.offsetDistance -
+                  VIEWPORT_MARGIN
+                : viewport - 2 * VIEWPORT_MARGIN
+            const height = Math.max(0, Math.floor(room - (props.surface ? SURFACE_BORDER : 0)))
+            elements.floating.style.setProperty('--floating-panel-available-height', `${height}px`)
+            availableHeight.value = height
+          },
+        }),
+      ]
+    : []),
 ])
 const {
@@ -68,6 +207,7 @@ const {
 })
 const open = async () => {
+  teleported.value = props.teleport && !triggerRef.value?.closest(DIALOG)
   isReady.value = false
   isOpen.value = true
   emit('open')
@@ -81,6 +221,13 @@ const open = async () => {
 const close = () => {
   if (!isOpen.value) return
+  // Teleported, focus inside the panel would drop to <body> when it goes, and the next Tab would
+  // start at the top of the page. Hand it back to the trigger first, before the emit, so a
+  // consumer that moves focus in @close still has the last word. A click outside still wins: this
+  // runs on mousedown, and the click's own focus change comes after it.
+  if (teleported.value && floatingRef.value?.contains(document.activeElement)) {
+    lastTabbableInTrigger()?.focus({ preventScroll: true })
+  }
   // Only keep the container alive if content was actually shown (isPositioned),
   // otherwise there is no leave transition to wait for.
   if (isPositioned.value) isLeaving.value = true
@@ -100,6 +247,92 @@ const handleKeydown = (event: KeyboardEvent) => {
   if (event.key === 'Escape' && isOpen.value) close()
 }
+// Capture phase, unlike Escape: an element that stops Tab from propagating would otherwise switch
+// the skip off and bring the loop back. Escape stays in the bubble phase on purpose, so content
+// (the picker) can stop it to keep the panel open.
+const handleTabCapture = (event: KeyboardEvent) => {
+  if (event.key === 'Tab' && !event.shiftKey && bridgeActive.value) skipPanelOnTab()
+}
+/*
+ * Focus guards, only while teleported. They make Tab and Shift+Tab walk the page as if the panel
+ * still followed the trigger: the bridge (last in the trigger) leads into the panel, the start
+ * guard back to the trigger, and the end guard on to whatever follows the trigger.
+ */
+const tabbablesIn = (root: ParentNode | null | undefined) =>
+  root
+    ? Array.from(root.querySelectorAll<HTMLElement>(TABBABLE)).filter(
+        (el) => !el.hasAttribute('data-focus-guard') && (el.checkVisibility?.() ?? true),
+      )
+    : []
+const follows = (reference: Node, node: Node) =>
+  (reference.compareDocumentPosition(node) & Node.DOCUMENT_POSITION_FOLLOWING) !== 0
+const firstTabbableAfterTrigger = () => {
+  const trigger = triggerRef.value
+  if (!trigger) return undefined
+  return tabbablesIn(document).find(
+    (el) => follows(trigger, el) && !trigger.contains(el) && !floatingRef.value?.contains(el),
+  )
+}
+const lastTabbableInTrigger = () => tabbablesIn(triggerRef.value).at(-1)
+const onBridgeEnter = (event: FocusEvent) => {
+  const from = event.relatedTarget
+  const trigger = triggerRef.value
+  // Shift+Tab from the element after the trigger lands on the bridge as well, since it is the
+  // last tab stop of the trigger: that is a step back into the panel, onto its last tab stop.
+  const backward =
+    from instanceof Node &&
+    !!trigger &&
+    follows(trigger, from) &&
+    !trigger.contains(from) &&
+    !floatingRef.value?.contains(from)
+  const panel = tabbablesIn(floatingRef.value)
+  const target = backward
+    ? (panel.at(-1) ?? lastTabbableInTrigger())
+    : (panel[0] ?? firstTabbableAfterTrigger())
+  target?.focus()
+}
+const onStartEnter = () => lastTabbableInTrigger()?.focus()
+const onEndEnter = (event: FocusEvent) => {
+  const panel = floatingRef.value
+  const from = event.relatedTarget
+  // Shift+Tab from outside the panel (the browser UI, or anything after it in <body>) lands here
+  // first: step back to the tab stop before the panel, as if it were not there.
+  if (panel && !(from instanceof Node && panel.contains(from))) {
+    const before = tabbablesIn(document).filter((el) => follows(el, panel) && !panel.contains(el))
+    before.at(-1)?.focus()
+    return
+  }
+  ;(firstTabbableAfterTrigger() ?? tabbablesIn(triggerRef.value)[0])?.focus()
+}
+/*
+ * In the page the teleported panel sits at the end of <body>, so Tab from the last tab stop before
+ * it would walk into the panel (and from there back via the guards: a loop, with the browser UI
+ * out of reach). For that one keypress the panel is made inert, so the browser's own Tab skips it
+ * and moves on to whatever follows, or out of the document. Only the bridge leads into the panel.
+ */
+const skipPanelOnTab = () => {
+  const panel = floatingRef.value
+  const active = document.activeElement
+  if (!panel || !(active instanceof HTMLElement) || panel.contains(active)) return
+  const stops = Array.from(document.querySelectorAll<HTMLElement>(TABBABLE)).filter(
+    (el) => el.checkVisibility?.() ?? true,
+  )
+  const index = stops.indexOf(active)
+  const next = index === -1 ? undefined : stops[index + 1]
+  if (!next || !panel.contains(next)) return
+  panel.inert = true
+  // the default action of this keydown has run by the time a task gets its turn
+  setTimeout(() => (panel.inert = false))
+}
 const transitionClasses = computed(() => {
   const placement = computedPlacement.value
   const [side, align] = placement.split('-') as [string, string | undefined]
@@ -127,8 +360,8 @@ const transitionClasses = computed(() => {
   const origin = originMap[align ? `${side}-${align}` : side] ?? 'origin-top'
   const translate = translates[side] ?? '-translate-y-2'
   return {
-    enterActiveClass: `transition-all duration-200 ease-out ${origin}`,
-    leaveActiveClass: `transition-all duration-150 ease-in ${origin}`,
+    enterActiveClass: `transition-all duration-200 ease-out motion-reduce:transition-none ${origin}`,
+    leaveActiveClass: `transition-all duration-150 ease-in motion-reduce:transition-none ${origin}`,
     enterFromClass: `opacity-0 scale-95 ${translate}`,
     leaveToClass: `opacity-0 scale-95 ${translate}`,
     enterToClass: 'opacity-100 scale-100 translate-x-0 translate-y-0',
@@ -140,22 +373,33 @@ watch(isPositioned, (val) => {
   if (val && isOpen.value) isReady.value = true
 })
-defineExpose({ isOpen, open, close, toggle, triggerRef, floatingRef })
+defineExpose({
+  isOpen,
+  open,
+  close,
+  toggle,
+  triggerRef,
+  floatingRef,
+  teleported: readonly(teleported),
+})
 onMounted(() => {
   document.addEventListener('mousedown', handleMousedown)
   document.addEventListener('keydown', handleKeydown)
+  document.addEventListener('keydown', handleTabCapture, true)
 })
 onUnmounted(() => {
   document.removeEventListener('mousedown', handleMousedown)
   document.removeEventListener('keydown', handleKeydown)
+  document.removeEventListener('keydown', handleTabCapture, true)
 })
 </script>
 <template>
   <span ref="triggerRef" v-bind="$attrs" class="inline-flex">
     <slot name="trigger" :is-open="isOpen" :toggle="toggle" :open="open" :close="close" />
+    <FocusGuard edge="bridge" :active="bridgeActive" @enter="onBridgeEnter" />
   </span>
   <!--
     floatingRef is the pure positioning container. It mounts immediately when
@@ -165,15 +409,17 @@ onUnmounted(() => {
     strategy:'fixed' means position:fixed is used, so this escapes any overflow
     clipping without needing a body teleport.
   -->
-  <div v-if="isOpen || isLeaving" ref="floatingRef" class="z-50" :style="floatingStyles">
-    <!--
+  <MaybeTeleport v-if="isOpen || isLeaving" :to="teleported ? 'body' : undefined">
+    <div ref="floatingRef" class="z-50" :style="floatingStyles">
+      <FocusGuard edge="start" :active="teleported" @enter="onStartEnter" />
+      <!--
       Content only renders once isPositioned is true, meaning floatingRef is
       already at the correct position. The enter transition therefore always
       originates from the trigger — never from the page origin.
     -->
-    <Transition v-bind="transitionClasses" @after-leave="isLeaving = false">
-      <div v-if="isOpen && isReady">
-        <!--
+      <Transition :css="!reduced" v-bind="transitionClasses" @after-leave="isLeaving = false">
+        <div v-if="isOpen && isReady">
+          <!--
           FloatingPanel is a positioning primitive: by default it adds no surface
           of its own and the content slot renders bare, exactly as before. The
           surface wrapper is an extra element that only exists when opted into,
@@ -190,14 +436,28 @@ onUnmounted(() => {
           strategy 'fixed', and overflow on an ancestor does not clip a fixed
           descendant unless that ancestor also establishes a containing block.
         -->
-        <div
-          v-if="surface"
-          class="overflow-hidden rounded-xl border border-gray-200 bg-white shadow-sm"
-        >
-          <slot name="content" :is-open="isOpen" :close="close" :toggle="toggle" />
+          <div v-if="surface" :class="surfaceClass">
+            <slot
+              name="content"
+              :is-open="isOpen"
+              :close="close"
+              :toggle="toggle"
+              :available-height="slotAvailableHeight"
+              :teleported="teleported"
+            />
+          </div>
+          <slot
+            v-else
+            name="content"
+            :is-open="isOpen"
+            :close="close"
+            :toggle="toggle"
+            :available-height="slotAvailableHeight"
+            :teleported="teleported"
+          />
         </div>
-        <slot v-else name="content" :is-open="isOpen" :close="close" :toggle="toggle" />
-      </div>
-    </Transition>
-  </div>
+      </Transition>
+      <FocusGuard edge="end" :active="teleported" @enter="onEndEnter" />
+    </div>
+  </MaybeTeleport>
 </template>

package/src/components/atoms/PickerItem/PickerItem.vue ADDED Viewed

@@ -0,0 +1,113 @@
+<script setup lang="ts">
+import { computed } from 'vue'
+import NexxtIcon, { type NexxtIconName } from '../Icon/Icon.vue'
+interface NexxtPickerItemProps {
+  /** DOM id of the option; the listbox points `aria-activedescendant` at it. `NexxtPickerList` generates it. */
+  id: string
+  /** Visible label, and the accessible name of the option. */
+  label: string
+  /** Icon in front of the label. */
+  icon?: NexxtIconName
+  /**
+   * Whether this is the active option. Tints the row; inside a focused listbox named
+   * `group/listbox` it also gets a ring. Outside such a listbox the item never shows a ring.
+   */
+  highlighted?: boolean
+  /**
+   * The option stays reachable with the keyboard and the pointer, but never emits `select`.
+   * Give a `description` that names the reason: a disabled option without one is a dead end.
+   */
+  disabled?: boolean
+  /** One line of extra context. Not shown; screen readers get it through `aria-describedby`. */
+  description?: string
+}
+defineOptions({ name: 'NexxtPickerItem' })
+const {
+  id,
+  label,
+  icon,
+  highlighted = false,
+  disabled = false,
+  description,
+} = defineProps<NexxtPickerItemProps>()
+const emit = defineEmits<{
+  /** Clicked. Never emitted while `disabled`. */
+  select: []
+  /** The pointer moved over the option; emitted while `disabled` too. */
+  highlight: []
+}>()
+defineSlots<{
+  /** Replaces icon and label. The option element, its id and its aria stay the item's own. */
+  default?(): unknown
+}>()
+// The highlighted branch comes first and carries no `hover:` tint, so hovering a highlighted
+// row never repaints it. `cursor-*` lives per branch to keep each string free of conflicts.
+// `shrink-0`: an ungrouped option sits directly in the scrolling flex column of the listbox,
+// which would otherwise squeeze it below `h-9` as soon as the list overflows.
+const OPTION_CLASSES = {
+  base: 'flex h-9 shrink-0 items-center gap-2.5 rounded-lg px-2 transition-colors duration-100 ease-out select-none motion-reduce:transition-none',
+  default: 'cursor-pointer hover:bg-gray-50 active:bg-cornflower-blue-100',
+  highlighted:
+    'cursor-pointer bg-cornflower-blue-50 active:bg-cornflower-blue-100 group-focus-visible/listbox:inset-ring-2 group-focus-visible/listbox:inset-ring-cornflower-blue-600',
+  disabled: 'cursor-not-allowed opacity-60',
+  disabledHighlighted:
+    'cursor-not-allowed bg-cornflower-blue-50 opacity-60 group-focus-visible/listbox:inset-ring-2 group-focus-visible/listbox:inset-ring-cornflower-blue-600',
+}
+const ICON_CLASSES = {
+  base: 'flex size-5 shrink-0 items-center justify-center transition-colors duration-100 ease-out motion-reduce:transition-none',
+  default: 'text-gray-700',
+  highlighted: 'text-cornflower-blue-700',
+}
+const state = computed(() => {
+  if (disabled) return highlighted ? 'disabledHighlighted' : 'disabled'
+  return highlighted ? 'highlighted' : 'default'
+})
+const optionClass = computed(() => [OPTION_CLASSES.base, OPTION_CLASSES[state.value]])
+const iconClass = computed(() => [
+  ICON_CLASSES.base,
+  highlighted ? ICON_CLASSES.highlighted : ICON_CLASSES.default,
+])
+const descriptionId = computed(() => (description ? `${id}-desc` : undefined))
+// The option also prevents the mousedown default: that keeps DOM focus where it was (the search
+// field), since the listbox around the option is focusable and would take it on every click.
+// Noted here, not in the template: a comment before the root makes the template multi-root.
+const onClick = () => {
+  if (!disabled) emit('select')
+}
+</script>
+<template>
+  <div
+    :id="id"
+    role="option"
+    :aria-selected="highlighted"
+    :aria-disabled="disabled ? 'true' : undefined"
+    :aria-describedby="descriptionId"
+    :class="optionClass"
+    @click="onClick"
+    @pointermove="emit('highlight')"
+    @mousedown.prevent
+  >
+    <slot>
+      <span v-if="icon" :class="iconClass">
+        <!-- Icon.vue does not hide the `<i>`; its `::before` glyph would leak into the name -->
+        <NexxtIcon :name="icon" aria-hidden="true" />
+      </span>
+      <!-- One weight in every state: the tint and the icon colour carry the highlight, so the
+           label never widens or reflows when the highlight moves onto it -->
+      <span class="min-w-0 flex-1 truncate small-normal text-gray-900">{{ label }}</span>
+    </slot>
+    <span v-if="description" :id="descriptionId" hidden>{{ description }}</span>
+  </div>
+</template>

package/src/components/atoms/PickerPreview/PickerPreview.vue ADDED Viewed

@@ -0,0 +1,99 @@
+<script setup lang="ts">
+import { computed, ref, watch } from 'vue'
+import { usePreferredReducedMotion } from '@vueuse/core'
+interface NexxtPickerPreviewProps {
+  /** Heading under the frame. Without it and without default-slot content the preview is empty. */
+  title?: string
+  /** Explanation under the title, clamped to two lines. */
+  description?: string
+  /** Centred in the frame while the preview is empty; the `empty` slot replaces it. */
+  emptyText?: string
+  /**
+   * Identifies what the preview shows. When it changes, the new content fades in (90ms) and the
+   * old content is gone at once: no crossfade. A change within 150ms of the previous one, as with
+   * a held arrow key, swaps without a fade. Without a key the content swaps without a fade.
+   */
+  contentKey?: string | number
+}
+defineOptions({ name: 'NexxtPickerPreview' })
+const { title, description, emptyText, contentKey } = defineProps<NexxtPickerPreviewProps>()
+defineSlots<{
+  /** Content of the 16:10 frame, e.g. an illustration or a screenshot. */
+  default?(): unknown
+  /** Replaces `emptyText` in the frame while the preview is empty. */
+  empty?(): unknown
+}>()
+const preferredMotion = usePreferredReducedMotion()
+// `motion-reduce:transition-none` alone leaves Vue reading a duration off the element; turning
+// the CSS mode off makes it swap synchronously instead
+const reduced = computed(() => preferredMotion.value === 'reduce')
+/** Swaps closer together than this skip the fade; each fade would restart at 0 and flicker. */
+const RAPID_SWAP_MS = 150
+let lastSwap = Number.NEGATIVE_INFINITY
+const rapid = ref(false)
+// `pre`, so the Transition already sees the new CSS mode in the patch that swaps the content
+watch(
+  () => contentKey,
+  () => {
+    const now = Date.now()
+    rapid.value = now - lastSwap < RAPID_SWAP_MS
+    lastSwap = now
+  },
+  { flush: 'pre' },
+)
+const fade = computed(() => !reduced.value && !rapid.value)
+/**
+ * Removes the outgoing content in the same patch. A leave hook that takes `done` counts as an
+ * explicit callback, so Vue waits for no transition; without it, the old content would stay next
+ * to the new one for a frame.
+ */
+const leaveNow = (_el: Element, done: () => void) => done()
+const FRAME_CLASSES =
+  'grid aspect-16/10 w-full shrink-0 place-items-center overflow-hidden rounded-xl border border-gray-200 bg-gray-50'
+const FADE_CLASSES = 'transition-opacity duration-90 ease-out motion-reduce:transition-none'
+</script>
+<template>
+  <div aria-hidden="true" class="flex flex-col gap-3">
+    <div :class="FRAME_CLASSES">
+      <Transition
+        v-if="$slots.default"
+        :css="fade"
+        :enter-active-class="FADE_CLASSES"
+        enter-from-class="opacity-0"
+        @leave="leaveNow"
+      >
+        <div :key="contentKey" class="size-full">
+          <slot />
+        </div>
+      </Transition>
+      <slot v-else-if="!title" name="empty">
+        <p v-if="emptyText" class="px-4 text-center small-normal text-gray-700">{{ emptyText }}</p>
+      </slot>
+    </div>
+    <Transition
+      v-if="title"
+      :css="fade"
+      :enter-active-class="FADE_CLASSES"
+      enter-from-class="opacity-0"
+      @leave="leaveNow"
+    >
+      <div :key="contentKey" class="flex flex-col gap-1">
+        <p class="truncate body-semibold text-gray-900">{{ title }}</p>
+        <p v-if="description" class="line-clamp-2 small-normal text-gray-700">{{ description }}</p>
+      </div>
+    </Transition>
+  </div>
+</template>