@nexxtmove/ui 1.46.0 → 1.48.0

package/src/components/organisms/IconPicker/IconPicker.vue

@@ -0,0 +1,621 @@
+<script lang="ts">
+/** One icon in the catalogue the consumer hands in. */
+export interface NexxtIconPickerIcon {
+  /** Identity: stored on the model and handed to `iconClass`. */
+  name: string
+  /** Shown in the trigger and the footer, read out as the cell's name, searched. */
+  label: string
+  /** Extra search words, e.g. `home` for a house. */
+  terms: string[]
+  /** The ids of the styles the icon exists in; only these are ever drawn or written. */
+  styles: string[]
+}
+
+/** A category in the rail. */
+export interface NexxtIconPickerCategory {
+  /** Identity of the category, unique within `categories`. */
+  id: string
+  /** Text of the rail item; the rail sorts on it. */
+  label: string
+  /** Names of the icons in the category; a name the catalogue does not know is skipped. */
+  icons: string[]
+}
+
+/** The section above "all icons", e.g. the icons already on the page. */
+export interface NexxtIconPickerPinned {
+  /** Heading of the section, e.g. `'Op deze pagina'`. */
+  label: string
+  /** Icon names. The current icon always leads the section; two rows at most. */
+  icons: string[]
+}
+
+/** A style the icons can be drawn in, with the classes that draw it. */
+export interface NexxtIconPickerStyle {
+  /** Identity: what `NexxtIconPickerIcon.styles` lists and the model stores. */
+  id: string
+  /** Shown behind the icon's label in the trigger, e.g. `'Light'`. */
+  label: string
+  /** The classes that draw a glyph in this style, next to the class from `iconClass`. */
+  classes: readonly string[]
+}
+
+/** What the picker reads and writes. */
+export interface NexxtIconPickerValue {
+  /** An icon `name`. */
+  icon: string
+  /** A style `id`. */
+  style: string
+}
+
+/** Overridable copy. Every key is optional and merged per key with the Dutch defaults. */
+export interface NexxtIconPickerMessages {
+  /** In the trigger while there is no value. Defaults to `'Kies een icoon'`. */
+  placeholder?: string
+  /** Placeholder of the search field. Defaults to `'Zoek in het Engels, bijv. house'`. */
+  searchPlaceholder?: string
+  /** Accessible name of the search field. Defaults to `'Icoon zoeken'`. */
+  searchLabel?: string
+  /** Accessible name of the category rail. Defaults to `'Categorieën'`. */
+  categoriesLabel?: string
+  /** The first rail item, and the heading of the full list under a pinned section. Defaults to `'Alle iconen'`. */
+  allIcons?: string
+  /** Read out as the description of the current icon. Defaults to `'Huidige keuze'`. */
+  current?: string
+  /** Heading of the empty search state. Defaults to `'Geen iconen gevonden'`. */
+  emptyTitle?: string
+  /** Line under the empty heading; receives the trimmed search term. */
+  emptyDescription?: (search: string) => string
+  /** Button in the empty state that clears the search. Defaults to `'Zoekopdracht wissen'`. */
+  clearSearch?: string
+  /** Notice under the grid when the catalogue could not be loaded. */
+  catalogueError?: string
+  /** Button in that notice. Defaults to `'Opnieuw proberen'`. */
+  retry?: string
+  /** Announced 500ms after a search or a category change; receives the number of icons. */
+  results?: (count: number) => string
+}
+
+export interface NexxtIconPickerProps {
+  /** The catalogue. The component fetches nothing itself: load it on `@open`. */
+  icons: NexxtIconPickerIcon[]
+  /** The categories of the rail, after "Alle iconen"; sorted on label in `sortLocale`. */
+  categories: NexxtIconPickerCategory[]
+  /**
+   * A section above "Alle iconen" while there is no search and no category, e.g. the icons
+   * already on the page. The current icon always leads it; two rows at most. Not shown when it
+   * would be empty.
+   */
+  pinned?: NexxtIconPickerPinned
+  /**
+   * The styles, in the order of preference: a cell shows its icon in the current style when the
+   * icon has it, otherwise in the first of these it has, and choosing it writes that style.
+   */
+  styles: NexxtIconPickerStyle[]
+  /**
+   * State of fetching the catalogue. `loading` shows skeletons while `icons` is empty; `error`
+   * shows a notice with a retry button. Without a catalogue the current icon stays the one
+   * choosable cell; a search typed meanwhile applies once the catalogue is in.
+   */
+  catalogueStatus?: 'loading' | 'ready' | 'error'
+  /**
+   * The class that picks an icon's glyph, next to the classes of its style. The component knows no
+   * icon set: for Font Awesome it returns the class of the named glyph.
+   */
+  iconClass: (name: string) => string
+  /**
+   * Visible label above the trigger, for a form. Give this or `ariaLabel`: without either the
+   * trigger has no name for the field, and a development build warns in the console.
+   */
+  label?: string
+  /**
+   * Accessible name when there is no visible label, as in the editor. The trigger reads it
+   * followed by the icon and its style: "Symbool, Star, Light". Give this or `label`.
+   */
+  ariaLabel?: string
+  /**
+   * Copy of the trigger and the panel. Merged per key with the Dutch defaults, so overriding one
+   * key keeps the others. Copy is never translated inside the component.
+   */
+  messages?: NexxtIconPickerMessages
+  /**
+   * Where the panel opens. `left` is for a picker in a side panel: the panel opens beside it, top
+   * aligned, and below it (right aligned) when the room on the left is less than the panel plus
+   * an 8px viewport margin.
+   */
+  side?: 'bottom' | 'left'
+  /** Distance between trigger and panel when it opens to the left, e.g. to clear a panel edge. */
+  sideOffset?: number
+  /** Locale the rail and the grid sort their labels in. */
+  sortLocale?: string
+}
+
+const DEFAULT_MESSAGES = {
+  placeholder: 'Kies een icoon',
+  searchPlaceholder: 'Zoek in het Engels, bijv. house',
+  searchLabel: 'Icoon zoeken',
+  categoriesLabel: 'Categorieën',
+  allIcons: 'Alle iconen',
+  current: 'Huidige keuze',
+  emptyTitle: 'Geen iconen gevonden',
+  emptyDescription: (search: string) =>
+    `Niets voor ‘${search}’. Zoeken werkt alleen met Engelse woorden.`,
+  clearSearch: 'Zoekopdracht wissen',
+  catalogueError: 'De iconen konden niet worden geladen. Je huidige icoon blijft kiesbaar.',
+  retry: 'Opnieuw proberen',
+  results: (count: number) => (count === 1 ? '1 icoon' : `${count} iconen`),
+} satisfies Required<NexxtIconPickerMessages>
+
+/** The rail's 192px plus a grid that gives six cells of about 51px. */
+const PANEL_WIDTH = 576
+const PANEL_HEIGHT = 520
+const VIEWPORT_MARGIN = 8
+/** The surface's 1px border, both sides. */
+const SURFACE_BORDER = 2
+/** Below the trigger, as when there is no room beside it. */
+const BOTTOM_OFFSET = 8
+
+/** No-break spaces: the label and the style are separate flex items, a plain space would collapse. */
+const DETAIL_PREFIX = ' · '
+
+const TRIGGER_CLASSES =
+  'group flex h-10 w-full min-w-0 cursor-pointer items-center gap-2 rounded-lg bg-white px-3 text-left font-sans ring ring-gray-200 transition-colors ease-out focus:ring-cornflower-blue-500 focus:outline-none motion-reduce:transition-none'
+
+const CHEVRON_CLASSES = {
+  base: 'shrink-0 text-gray-700 transition-transform duration-200 motion-reduce:transition-none',
+  open: 'rotate-180',
+}
+</script>
+
+<script lang="ts" setup>
+import { computed, ref, useId, useTemplateRef, watch, watchEffect } from 'vue'
+import { useElementBounding, useEventListener } from '@vueuse/core'
+import NexxtButton from '../../atoms/Button/Button.vue'
+import NexxtFloatingPanel from '../../atoms/FloatingPanel/FloatingPanel.vue'
+import NexxtIcon from '../../atoms/Icon/Icon.vue'
+import NexxtInputField from '../../molecules/InputField/InputField.vue'
+import NexxtIconPickerGrid from './_IconPickerGrid.vue'
+import NexxtIconPickerRail from './_IconPickerRail.vue'
+import { DEFAULT_SORT_LOCALE } from './iconPickerHelpers'
+import { useIconPickerCatalogue } from './useIconPickerCatalogue'
+import { useIconPickerNavigation } from './useIconPickerNavigation'
+
+defineOptions({ name: 'NexxtIconPicker' })
+
+const {
+  icons,
+  categories,
+  pinned,
+  styles,
+  catalogueStatus = 'ready',
+  iconClass,
+  label,
+  ariaLabel,
+  messages,
+  side = 'bottom',
+  sideOffset = 8,
+  sortLocale = DEFAULT_SORT_LOCALE,
+} = defineProps<NexxtIconPickerProps>()
+
+/** The chosen icon and style. Only a choice writes the model; moving the highlight never does. */
+const model = defineModel<NexxtIconPickerValue | null>({ default: null })
+
+const emit = defineEmits<{
+  /** The panel opens: the moment to start fetching the catalogue, lazily. */
+  open: []
+  /** The panel closed, by a choice, Escape, a click outside or focus leaving it. */
+  close: []
+  /** "Opnieuw proberen" in the error state. Fetch again and set `catalogueStatus` to `loading`. */
+  retry: []
+}>()
+
+const copy = computed(() => ({ ...DEFAULT_MESSAGES, ...messages }))
+
+const baseId = useId()
+const triggerId = `${baseId}-trigger`
+const labelId = `${baseId}-label`
+const valueId = `${baseId}-value`
+const gridId = `${baseId}-grid`
+const panelId = `${baseId}-panel`
+const currentDescriptionId = `${baseId}-current`
+const cellIdPrefix = `${baseId}-cell`
+
+const root = useTemplateRef<HTMLElement>('root')
+const trigger = useTemplateRef<HTMLButtonElement>('trigger')
+const floating = useTemplateRef<InstanceType<typeof NexxtFloatingPanel>>('floating')
+const searchField = useTemplateRef<InstanceType<typeof NexxtInputField>>('searchField')
+const grid = useTemplateRef<InstanceType<typeof NexxtIconPickerGrid>>('grid')
+
+const isOpen = ref(false)
+const search = ref('')
+/** The category on show; `null` is "all icons". */
+const category = ref<string | null>(null)
+
+const term = computed(() => search.value.trim())
+
+// ─── Catalogue ────────────────────────────────────────────────────────────────
+
+const {
+  shownCategories,
+  activeCategory,
+  catalogueEmpty,
+  currentIcon,
+  currentStyle,
+  rows,
+  iconRows,
+  iconCount,
+  currentPosition,
+  rowLength,
+  iconAt,
+  styleOf,
+  glyphClass,
+} = useIconPickerCatalogue({
+  icons: () => icons,
+  categories: () => categories,
+  pinned: () => pinned,
+  styles: () => styles,
+  iconClass: () => iconClass,
+  sortLocale: () => sortLocale,
+  allIconsLabel: () => copy.value.allIcons,
+  model,
+  term,
+  category,
+})
+
+const loading = computed(() => catalogueStatus === 'loading')
+const failed = computed(() => catalogueStatus === 'error')
+const showSkeletons = computed(() => loading.value && catalogueEmpty.value)
+
+const showEmpty = computed(
+  () => !catalogueEmpty.value && term.value !== '' && iconRows.value.length === 0,
+)
+/** Error without a current icon leaves nothing to show: no grid, and nothing for the field to control. */
+const showGrid = computed(() => !showSkeletons.value && iconRows.value.length > 0)
+const hasGrid = computed(() => showSkeletons.value || showGrid.value)
+
+// ─── Rail ─────────────────────────────────────────────────────────────────────
+
+const tabs = computed(() => [
+  { id: null, label: copy.value.allIcons },
+  ...shownCategories.value.map(({ id, label: text }) => ({ id, label: text })),
+])
+
+const tabId = (index: number) => `${baseId}-tab-${index}`
+
+const activeTabIndex = computed(() =>
+  Math.max(
+    0,
+    tabs.value.findIndex((tab) => tab.id === (activeCategory.value?.id ?? null)),
+  ),
+)
+
+const activeTabId = computed(() => tabId(activeTabIndex.value))
+
+// ─── Trigger ──────────────────────────────────────────────────────────────────
+
+const triggerGlyph = computed(() =>
+  currentIcon.value ? glyphClass(currentIcon.value, model.value?.style) : null,
+)
+
+const triggerText = computed(() => currentIcon.value?.label ?? copy.value.placeholder)
+
+// "Symbool, Star, Light": the name, then what is on show, as the trigger reads it. A visible
+// label wins, so the name matches what a sighted user reads (WCAG 2.5.3)
+const triggerAriaLabel = computed(() => {
+  if (label || !ariaLabel) return undefined
+  return [ariaLabel, triggerText.value, currentStyle.value?.label].filter(Boolean).join(', ')
+})
+
+const triggerLabelledby = computed(() => (label ? `${labelId} ${valueId}` : undefined))
+
+const panelLabel = computed(() => label ?? ariaLabel)
+
+const valueClass = computed(() => [
+  'flex min-w-0 flex-1 items-center small-normal',
+  currentIcon.value ? 'text-gray-900' : 'text-gray-700',
+])
+
+const chevronClass = computed(() => [CHEVRON_CLASSES.base, isOpen.value && CHEVRON_CLASSES.open])
+
+// A trigger without either has no name for the field. `process.env.NODE_ENV` stays in the library
+// build, so the consumer's bundler decides whether this runs (as in NexxtFontPicker)
+if (process.env.NODE_ENV !== 'production') {
+  watchEffect(() => {
+    if (!label && !ariaLabel) {
+      console.warn('[NexxtIconPicker] Pass `label` or `ariaLabel`: the trigger has no name.')
+    }
+  })
+}
+
+// ─── Placement ────────────────────────────────────────────────────────────────
+
+const { left: triggerLeft } = useElementBounding(trigger)
+
+/**
+ * Decided here rather than by FloatingPanel's `flip()`, which would flip `left` to the right of a
+ * side panel: beside the trigger where the panel fits with its viewport margin, below it otherwise.
+ */
+const placement = computed(() => {
+  if (side !== 'left') return 'bottom-start'
+  return triggerLeft.value - sideOffset >= PANEL_WIDTH + VIEWPORT_MARGIN
+    ? 'left-start'
+    : 'bottom-end'
+})
+
+const offsetDistance = computed(() =>
+  placement.value === 'left-start' ? sideOffset : BOTTOM_OFFSET,
+)
+
+// The surface's border is drawn around the content, so the content is that much smaller
+const panelStyle = (availableHeight: number | null) => ({
+  width: `min(${PANEL_WIDTH - SURFACE_BORDER}px, calc(100vw - ${2 * VIEWPORT_MARGIN + SURFACE_BORDER}px))`,
+  height: `min(${PANEL_HEIGHT - SURFACE_BORDER}px, ${availableHeight ?? PANEL_HEIGHT}px)`,
+})
+
+// ─── Panel ────────────────────────────────────────────────────────────────────
+
+const focusSearch = () => searchField.value?.focus()
+
+// Focus goes back to the trigger first, before the element that has it leaves the DOM
+const closeToTrigger = () => {
+  trigger.value?.focus()
+  floating.value?.close()
+}
+
+const choose = (icon: NexxtIconPickerIcon) => {
+  const style = styleOf(icon)
+  if (style && (icon.name !== model.value?.icon || style !== model.value?.style)) {
+    model.value = { icon: icon.name, style }
+  }
+  closeToTrigger()
+}
+
+// Typing searches the whole catalogue
+watch(term, (value) => {
+  if (value) category.value = null
+})
+
+const navigation = useIconPickerNavigation({
+  iconRows,
+  currentPosition,
+  iconCount,
+  catalogueEmpty,
+  iconAt,
+  rowLength,
+  search,
+  term,
+  category,
+  isOpen,
+  grid: () => grid.value,
+  focusSearch,
+  choose,
+  results: () => copy.value.results,
+})
+
+const { highlight, highlightedIcon, gridFocused, announcement } = navigation
+
+const onOpen = () => {
+  navigation.open(() => {
+    isOpen.value = true
+    search.value = ''
+    category.value = null
+  })
+  emit('open')
+}
+
+const onClose = () => {
+  isOpen.value = false
+  navigation.close()
+  emit('close')
+}
+
+const onTriggerKeydown = (event: KeyboardEvent) => {
+  if (event.key !== 'ArrowDown' || isOpen.value) return
+  event.preventDefault()
+  floating.value?.open()
+}
+
+/**
+ * Tab from the grid (the last stop) closes the panel and focus goes on to the control after the
+ * trigger, as if the panel were not there: it is no dialog, so there is no focus trap. The focus
+ * guards of the teleported panel sit inside `floatingRef`, so Tab off the last stop lands on one
+ * first (no close) and the step after it closes. A `null` target is a press on something that
+ * takes no focus: FloatingPanel's own outside click handles that.
+ */
+const onFocusOut = (event: FocusEvent) => {
+  const next = event.relatedTarget
+  if (!(next instanceof Node)) return
+  if (root.value?.contains(next) || floating.value?.floatingRef?.contains(next)) return
+  floating.value?.close()
+}
+
+useEventListener(() => (isOpen.value ? floating.value?.floatingRef : null), 'focusout', onFocusOut)
+
+const clearSearch = () => {
+  search.value = ''
+  focusSearch()
+}
+
+const selectCategory = (id: string | null) => {
+  search.value = ''
+  category.value = id
+}
+
+// The panel's content mounts a tick after it opens
+watch(searchField, (field) => field?.focus())
+
+// The chosen category emptied (a reloaded catalogue, categories that changed): back to "all icons",
+// so the state matches the rail and no empty tab panel is left
+watch(activeCategory, (active) => {
+  if (!active && category.value !== null) category.value = null
+})
+</script>
+
+<template>
+  <div ref="root" class="flex w-full min-w-0 flex-col" @focusout="onFocusOut">
+    <label v-if="label" :id="labelId" :for="triggerId" class="mb-1 small-normal text-gray-700">
+      {{ label }}
+    </label>
+
+    <!-- Teleported: a side panel scrolls, and would clip a panel inside it -->
+    <NexxtFloatingPanel
+      ref="floating"
+      class="w-full"
+      :placement="placement"
+      :offset-distance="offsetDistance"
+      surface
+      fit-height
+      teleport
+      @open="onOpen"
+      @close="onClose"
+    >
+      <template #trigger="{ toggle }">
+        <!--
+          `grid`, not `dialog`: the panel is no dialog, and what is picked from is the grid. The
+          accessible name is the field, the icon and its style: "Symbool, Star, Light".
+        -->
+        <button
+          :id="triggerId"
+          ref="trigger"
+          type="button"
+          aria-haspopup="grid"
+          :aria-expanded="isOpen"
+          :aria-label="triggerAriaLabel"
+          :aria-labelledby="triggerLabelledby"
+          :class="TRIGGER_CLASSES"
+          @click="toggle"
+          @keydown="onTriggerKeydown"
+        >
+          <span
+            class="flex size-7 shrink-0 items-center justify-center rounded-md bg-gray-50"
+            aria-hidden="true"
+          >
+            <i v-if="triggerGlyph" :class="[triggerGlyph, 'text-base text-gray-900']" />
+          </span>
+
+          <span :id="valueId" :class="valueClass">
+            <span class="min-w-0 truncate">{{ triggerText }}</span>
+            <span v-if="currentStyle" class="shrink-0 text-gray-700">
+              {{ DETAIL_PREFIX }}{{ currentStyle.label }}
+            </span>
+          </span>
+
+          <NexxtIcon name="chevron-down" aria-hidden="true" :class="chevronClass" />
+        </button>
+      </template>
+
+      <template #content="{ availableHeight }">
+        <div
+          role="group"
+          :aria-label="panelLabel"
+          class="flex flex-col"
+          :style="panelStyle(availableHeight)"
+        >
+          <div class="shrink-0 border-b border-gray-200 p-3">
+            <NexxtInputField
+              ref="searchField"
+              v-model="search"
+              class="w-full"
+              left-icon="magnifying-glass"
+              autocomplete="off"
+              :placeholder="copy.searchPlaceholder"
+              :aria-label="copy.searchLabel"
+              :aria-controls="hasGrid ? gridId : undefined"
+              @keydown="navigation.onSearchKeydown"
+            />
+          </div>
+
+          <div class="flex min-h-0 flex-1">
+            <NexxtIconPickerRail
+              :tabs="tabs"
+              :active-index="activeTabIndex"
+              :label="copy.categoriesLabel"
+              :panel-id="panelId"
+              :tab-id="tabId"
+              :loading="showSkeletons"
+              @select="selectCategory"
+            />
+
+            <div
+              :id="panelId"
+              role="tabpanel"
+              :aria-labelledby="activeTabId"
+              class="flex min-h-0 min-w-0 flex-1 flex-col"
+            >
+              <div
+                v-if="showEmpty"
+                class="flex min-h-0 flex-1 flex-col items-center justify-center gap-1 p-6 text-center"
+              >
+                <NexxtIcon
+                  name="magnifying-glass"
+                  aria-hidden="true"
+                  class="mb-2 text-4xl text-gray-400"
+                />
+                <p class="small-semibold text-gray-900">{{ copy.emptyTitle }}</p>
+                <p class="small-normal text-gray-700">{{ copy.emptyDescription(term) }}</p>
+                <NexxtButton variant="link" @click="clearSearch">{{
+                  copy.clearSearch
+                }}</NexxtButton>
+              </div>
+
+              <NexxtIconPickerGrid
+                v-else-if="hasGrid"
+                ref="grid"
+                :rows="rows"
+                :skeleton="showSkeletons"
+                :grid-id="gridId"
+                :labelledby="activeTabId"
+                :cell-id-prefix="cellIdPrefix"
+                :current-description-id="currentDescriptionId"
+                :highlight="highlight"
+                :focused="gridFocused"
+                :selected="currentPosition"
+                :glyph-class="glyphClass"
+                @focus="navigation.onGridFocus"
+                @blur="navigation.onGridBlur"
+                @keydown="navigation.onGridKeydown"
+                @hover="navigation.onCellHover"
+                @choose="choose"
+              />
+
+              <!-- Outside the grid, so it is no cell; after it in the tab order -->
+              <div
+                v-if="failed"
+                role="status"
+                class="flex shrink-0 items-start gap-2 border-t border-gray-200 px-3 py-2.5"
+              >
+                <NexxtIcon
+                  name="circle-exclamation"
+                  aria-hidden="true"
+                  class="mt-0.5 shrink-0 text-gray-700"
+                />
+                <!-- NexxtButton is a 40px flex box, so it gets a line of its own under the text -->
+                <div class="flex min-w-0 flex-col items-start">
+                  <p class="extra-small-normal text-gray-800">{{ copy.catalogueError }}</p>
+                  <NexxtButton variant="link" @click="emit('retry')">{{ copy.retry }}</NexxtButton>
+                </div>
+              </div>
+            </div>
+          </div>
+
+          <!-- What the highlight is on, large; screen readers hear it on the cell itself -->
+          <div
+            class="flex h-11 shrink-0 items-center gap-3 border-t border-gray-200 px-3"
+            aria-hidden="true"
+          >
+            <template v-if="highlightedIcon">
+              <i :class="[glyphClass(highlightedIcon), 'text-2xl text-gray-900']" />
+              <span class="truncate small-semibold text-gray-900">{{ highlightedIcon.label }}</span>
+              <span class="truncate extra-small-normal-mono text-gray-700">{{
+                highlightedIcon.name
+              }}</span>
+            </template>
+          </div>
+
+          <span :id="currentDescriptionId" hidden>{{ copy.current }}</span>
+
+          <div class="sr-only" aria-live="polite">{{ announcement }}</div>
+        </div>
+      </template>
+    </NexxtFloatingPanel>
+  </div>
+</template>