@nexxtmove/ui 1.47.0 → 1.48.0

package/src/components/organisms/IconPicker/useIconPickerCatalogue.ts

@@ -0,0 +1,238 @@
+import { computed, toValue, type MaybeRefOrGetter, type Ref } from 'vue'
+import type {
+  NexxtIconPickerCategory,
+  NexxtIconPickerIcon,
+  NexxtIconPickerPinned,
+  NexxtIconPickerStyle,
+  NexxtIconPickerValue,
+} from './IconPicker.vue'
+import {
+  iconLabelFromName,
+  iconSearchIndex,
+  iconStyleFor,
+  searchIcons,
+  sortIconsByLabel,
+} from './iconPickerHelpers'
+
+/**
+ * Six columns with a 12px gap (`gap-3`) scan more easily than eight close together. `grid-cols-6`
+ * in `_IconPickerGrid.vue` is the same number: change both together.
+ */
+export const COLUMNS = 6
+/** Two rows. */
+const PINNED_MAX = 2 * COLUMNS
+
+/**
+ * On every glyph `<i>`. Font Awesome centres its `::before` with `text-align` in a fixed 1.25em
+ * box, which stops working once the box is a flex container (Font Awesome's display variable set
+ * to `inline-flex`, as in Storybook); centring it as a flex box as well holds in both, as
+ * NexxtIcon does. `leading-none` keeps the line box at the glyph's own height.
+ */
+const GLYPH_CLASSES = 'items-center justify-center leading-none'
+
+/** A line of the grid: a section heading, or up to `COLUMNS` icons. */
+export type GridRow =
+  | { kind: 'heading'; key: string; label: string }
+  | { kind: 'icons'; key: string; icons: NexxtIconPickerIcon[] }
+
+/** A cell, by its index in the rows and its column. */
+export interface GridPosition {
+  row: number
+  col: number
+}
+
+/** A rail item; `null` is "all icons". */
+export interface RailTab {
+  id: string | null
+  label: string
+}
+
+const toRows = (list: NexxtIconPickerIcon[], section: string): GridRow[] =>
+  Array.from({ length: Math.ceil(list.length / COLUMNS) }, (_, index) => ({
+    kind: 'icons' as const,
+    key: `${section}-${index}`,
+    icons: list.slice(index * COLUMNS, (index + 1) * COLUMNS),
+  }))
+
+const isKnown = (icon: NexxtIconPickerIcon | undefined): icon is NexxtIconPickerIcon => !!icon
+
+interface IconPickerCatalogueOptions {
+  icons: MaybeRefOrGetter<NexxtIconPickerIcon[]>
+  categories: MaybeRefOrGetter<NexxtIconPickerCategory[]>
+  pinned: MaybeRefOrGetter<NexxtIconPickerPinned | undefined>
+  styles: MaybeRefOrGetter<NexxtIconPickerStyle[]>
+  /** A getter, never the function itself: `toValue` would call that without a name. */
+  iconClass: () => (name: string) => string
+  sortLocale: MaybeRefOrGetter<string>
+  /** Heading of the full list under a pinned section. */
+  allIconsLabel: MaybeRefOrGetter<string>
+  model: Ref<NexxtIconPickerValue | null>
+  /** The trimmed search. */
+  term: Ref<string>
+  /** The chosen category; `null` is "all icons". */
+  category: Ref<string | null>
+}
+
+/**
+ * What the picker shows, derived from the catalogue, the model, the search and the category: the
+ * rail's categories, the grid's rows and where the current icon is in them, and the classes that
+ * draw a glyph. No DOM, no focus: that is `useIconPickerNavigation` and the parts.
+ */
+export const useIconPickerCatalogue = (options: IconPickerCatalogueOptions) => {
+  const { model, term, category } = options
+
+  const iconsByName = computed(
+    () => new Map(toValue(options.icons).map((icon) => [icon.name, icon])),
+  )
+  const searchIndex = computed(() =>
+    iconSearchIndex(toValue(options.icons), toValue(options.sortLocale)),
+  )
+  const sortedIcons = computed(() => searchIndex.value.map((entry) => entry.icon))
+
+  /**
+   * The categories the rail shows, sorted, each with the icons of it the catalogue knows. One
+   * without any is left out: while the catalogue loads that is all of them, and the skeletons
+   * stand in.
+   */
+  const shownCategories = computed(() => {
+    const { compare } = new Intl.Collator(toValue(options.sortLocale))
+    return toValue(options.categories)
+      .map(({ id, label, icons: names }) => ({
+        id,
+        label,
+        icons: names.map((name) => iconsByName.value.get(name)).filter(isKnown),
+      }))
+      .filter((entry) => entry.icons.length > 0)
+      .sort((a, b) => compare(a.label, b.label))
+  })
+
+  const styleOrder = computed(() => toValue(options.styles).map((style) => style.id))
+  const stylesById = computed(
+    () => new Map(toValue(options.styles).map((style) => [style.id, style])),
+  )
+
+  const catalogueEmpty = computed(() => toValue(options.icons).length === 0)
+
+  /** The current icon, also while the catalogue that would describe it is not in. */
+  const currentIcon = computed<NexxtIconPickerIcon | null>(() => {
+    if (!model.value) return null
+    const { icon, style } = model.value
+    return (
+      iconsByName.value.get(icon) ?? {
+        name: icon,
+        label: iconLabelFromName(icon),
+        terms: [],
+        styles: [style],
+      }
+    )
+  })
+
+  /** The style of the trigger: the stored one. */
+  const currentStyle = computed(() =>
+    model.value ? (stylesById.value.get(model.value.style) ?? null) : null,
+  )
+
+  /** The category on show: the chosen one while the rail still has it, "all icons" otherwise. */
+  const activeCategory = computed(
+    () => shownCategories.value.find(({ id }) => id === category.value) ?? null,
+  )
+
+  /** The current icon first, then the pinned ones the catalogue knows, two rows at most. */
+  const pinnedIcons = computed(() => {
+    const pinned = toValue(options.pinned)
+    if (!pinned) return []
+    const current = currentIcon.value
+    const others = pinned.icons
+      .filter((name) => name !== current?.name)
+      .map((name) => iconsByName.value.get(name))
+      .filter(isKnown)
+    return [...(current ? [current] : []), ...others].slice(0, PINNED_MAX)
+  })
+
+  const rows = computed<GridRow[]>(() => {
+    // No catalogue (it failed, or is on its way behind the skeletons): the current icon stays
+    // choosable
+    if (catalogueEmpty.value) return toRows(currentIcon.value ? [currentIcon.value] : [], 'current')
+
+    if (term.value) return toRows(searchIcons(searchIndex.value, term.value), 'results')
+
+    if (activeCategory.value) {
+      const { id, icons: list } = activeCategory.value
+      return toRows(sortIconsByLabel(list, toValue(options.sortLocale)), `category-${id}`)
+    }
+
+    const pinned = toValue(options.pinned)
+    if (pinned && pinnedIcons.value.length > 0) {
+      return [
+        { kind: 'heading', key: 'pinned-heading', label: pinned.label },
+        ...toRows(pinnedIcons.value, 'pinned'),
+        { kind: 'heading', key: 'all-heading', label: toValue(options.allIconsLabel) },
+        ...toRows(sortedIcons.value, 'all'),
+      ]
+    }
+
+    return toRows(sortedIcons.value, 'all')
+  })
+
+  /** The indexes of the rows that hold icons, in order. */
+  const iconRows = computed(() =>
+    rows.value.flatMap((row, index) => (row.kind === 'icons' ? [index] : [])),
+  )
+
+  /** The icons in the list on show; the pinned section repeats icons, so it does not count. */
+  const iconCount = computed(
+    () =>
+      rows.value.reduce((count, row) => count + (row.kind === 'icons' ? row.icons.length : 0), 0) -
+      (rows.value[0]?.kind === 'heading' ? pinnedIcons.value.length : 0),
+  )
+
+  const rowLength = (row: number | undefined) => {
+    const entry = row === undefined ? undefined : rows.value[row]
+    return entry?.kind === 'icons' ? entry.icons.length : 0
+  }
+
+  const iconAt = (position: GridPosition | null) => {
+    if (!position) return null
+    const row = rows.value[position.row]
+    return row?.kind === 'icons' ? (row.icons[position.col] ?? null) : null
+  }
+
+  /** Where the current icon first appears in the grid. */
+  const currentPosition = computed<GridPosition | null>(() => {
+    const name = model.value?.icon
+    if (!name) return null
+    for (const row of iconRows.value) {
+      const entry = rows.value[row]
+      const col = entry?.kind === 'icons' ? entry.icons.findIndex((icon) => icon.name === name) : -1
+      if (col !== -1) return { row, col }
+    }
+    return null
+  })
+
+  /** What a choice of this icon writes, and so what its cell shows: the current style, or its first. */
+  const styleOf = (icon: NexxtIconPickerIcon) =>
+    iconStyleFor(icon.styles, model.value?.style, styleOrder.value)
+
+  /** The classes of a glyph: those of its style, the one from `iconClass`, and the centring. */
+  const glyphClass = (icon: NexxtIconPickerIcon, style: string | null = styleOf(icon)) => [
+    ...(style ? (stylesById.value.get(style)?.classes ?? []) : []),
+    options.iconClass()(icon.name),
+    GLYPH_CLASSES,
+  ]
+
+  return {
+    shownCategories,
+    activeCategory,
+    catalogueEmpty,
+    currentIcon,
+    currentStyle,
+    rows,
+    iconRows,
+    iconCount,
+    currentPosition,
+    rowLength,
+    iconAt,
+    styleOf,
+    glyphClass,
+  }
+}

package/src/components/organisms/IconPicker/useIconPickerNavigation.ts

@@ -0,0 +1,206 @@
+import { computed, ref, watch, type ComputedRef, type Ref } from 'vue'
+import { useDebounceFn } from '@vueuse/core'
+import type { NexxtIconPickerIcon } from './IconPicker.vue'
+import type { GridPosition } from './useIconPickerCatalogue'
+
+const RESULTS_DELAY = 500
+
+/** What the grid part exposes: the parts of navigating that need its scroll box. */
+export interface IconPickerGridHandle {
+  /** Focus the grid itself; the highlight is its active descendant. */
+  focus: () => void
+  /** Scroll the least needed to show the row, and render the rows there at once. */
+  reveal: (row: number) => void
+  /** Whether the row is fully in view. */
+  inView: (row: number) => boolean
+  /** The rows that fit in view, less one, at least one. */
+  pageRows: () => number
+  scrollToTop: () => void
+}
+
+interface IconPickerNavigationOptions {
+  /** The indexes of the rows that hold icons, in order. */
+  iconRows: ComputedRef<number[]>
+  currentPosition: ComputedRef<GridPosition | null>
+  iconCount: ComputedRef<number>
+  catalogueEmpty: ComputedRef<boolean>
+  iconAt: (position: GridPosition | null) => NexxtIconPickerIcon | null
+  rowLength: (row: number | undefined) => number
+  /** The raw search: a letter typed in the grid is appended to it. */
+  search: Ref<string>
+  /** The trimmed search. */
+  term: ComputedRef<string>
+  category: Ref<string | null>
+  isOpen: Ref<boolean>
+  grid: () => IconPickerGridHandle | null | undefined
+  focusSearch: () => void
+  choose: (icon: NexxtIconPickerIcon) => void
+  /** The copy of the announcement. */
+  results: () => (count: number) => string
+}
+
+const isPrintable = (event: KeyboardEvent) =>
+  event.key.length === 1 && event.key !== ' ' && !event.ctrlKey && !event.metaKey && !event.altKey
+
+/**
+ * The keyboard, highlight and focus state of the picker: the highlighted cell and whether the grid
+ * has focus, the keys of the search field and the grid, the move from one to the other, and the
+ * results count for the live region. Only a choice writes the model; moving the highlight never does.
+ */
+export const useIconPickerNavigation = (options: IconPickerNavigationOptions) => {
+  const { iconRows, currentPosition, iconAt, rowLength, search, term, category, isOpen } = options
+
+  const highlight = ref<GridPosition | null>(null)
+  const gridFocused = ref(false)
+  const announcement = ref('')
+  /** Opening resets search and category; that reset is no change to announce. */
+  let skipAnnouncement = false
+
+  const highlightedIcon = computed(() => iconAt(highlight.value))
+
+  const moveTo = (row: number | undefined, col: number) => {
+    if (row === undefined || rowLength(row) === 0) return
+    highlight.value = { row, col: Math.max(0, Math.min(col, rowLength(row) - 1)) }
+    options.grid()?.reveal(row)
+  }
+
+  /**
+   * On opening: the reset (search, category) runs in between, so the highlight lands on the
+   * current icon of the full list.
+   */
+  const open = (reset: () => void) => {
+    // On the state the watcher sees: a search of only spaces is no term, and resetting it fires nothing
+    skipAnnouncement = term.value !== '' || category.value !== null
+    reset()
+    highlight.value = currentPosition.value
+    announcement.value = ''
+  }
+
+  const close = () => {
+    gridFocused.value = false
+  }
+
+  /** Into the grid from the search field: the current icon when it is in view, the first cell otherwise. */
+  const enterGrid = () => {
+    const current = currentPosition.value
+    if (current && options.grid()?.inView(current.row)) highlight.value = current
+    else moveTo(iconRows.value[0], 0)
+    options.grid()?.focus()
+  }
+
+  const onGridFocus = () => {
+    gridFocused.value = true
+    if (!highlightedIcon.value) moveTo(iconRows.value[0], 0)
+  }
+
+  const onGridBlur = () => {
+    gridFocused.value = false
+  }
+
+  const onCellHover = (position: GridPosition) => {
+    highlight.value = position
+  }
+
+  const onGridKeydown = (event: KeyboardEvent) => {
+    // A letter is a search: the field takes it, and the focus
+    if (isPrintable(event)) {
+      event.preventDefault()
+      search.value += event.key
+      options.focusSearch()
+      return
+    }
+
+    const position = highlight.value
+    const icon = iconAt(position)
+    if (!position || !icon) return
+
+    const order = iconRows.value
+    const at = order.indexOf(position.row)
+    const page = options.grid()?.pageRows() ?? 1
+    const toEdge = event.ctrlKey || event.metaKey
+    const last = order.at(-1)
+
+    switch (event.key) {
+      case 'ArrowRight':
+        if (position.col + 1 < rowLength(position.row)) moveTo(position.row, position.col + 1)
+        else moveTo(order[at + 1], 0)
+        break
+      case 'ArrowLeft':
+        if (position.col > 0) moveTo(position.row, position.col - 1)
+        else moveTo(order[at - 1], rowLength(order[at - 1]) - 1)
+        break
+      case 'ArrowDown':
+        moveTo(order[at + 1], position.col)
+        break
+      case 'ArrowUp':
+        if (at === 0) options.focusSearch()
+        else moveTo(order[at - 1], position.col)
+        break
+      case 'Home':
+        moveTo(toEdge ? order[0] : position.row, 0)
+        break
+      case 'End':
+        moveTo(toEdge ? last : position.row, rowLength(toEdge ? last : position.row) - 1)
+        break
+      case 'PageDown':
+        moveTo(order[Math.min(at + page, order.length - 1)], position.col)
+        break
+      case 'PageUp':
+        moveTo(order[Math.max(at - page, 0)], position.col)
+        break
+      case 'Enter':
+      case ' ':
+        options.choose(icon)
+        break
+      default:
+        return
+    }
+
+    event.preventDefault()
+  }
+
+  const onSearchKeydown = (event: KeyboardEvent) => {
+    if (event.key === 'ArrowDown' && iconRows.value.length > 0) {
+      event.preventDefault()
+      enterGrid()
+    } else if (event.key === 'Enter' && term.value) {
+      event.preventDefault()
+      const first = iconAt({ row: iconRows.value[0] ?? -1, col: 0 })
+      if (first) options.choose(first)
+    }
+  }
+
+  const announceResults = useDebounceFn(() => {
+    announcement.value = options.results()(options.iconCount.value)
+  }, RESULTS_DELAY)
+
+  // A new list starts at the top with nothing highlighted; back on the full list (also on opening,
+  // which resets both) the current icon is highlighted again
+  watch([term, category], () => {
+    highlight.value = !term.value && category.value === null ? currentPosition.value : null
+    options.grid()?.scrollToTop()
+    if (skipAnnouncement) skipAnnouncement = false
+    else if (isOpen.value) announceResults()
+  })
+
+  // The catalogue came in while the panel was open: highlight the current icon, as on opening
+  watch(options.catalogueEmpty, (empty) => {
+    if (!empty && isOpen.value && !term.value && category.value === null) {
+      highlight.value = currentPosition.value
+    }
+  })
+
+  return {
+    highlight,
+    highlightedIcon,
+    gridFocused,
+    announcement,
+    open,
+    close,
+    onGridFocus,
+    onGridBlur,
+    onCellHover,
+    onGridKeydown,
+    onSearchKeydown,
+  }
+}

package/src/components.json

@@ -61,6 +61,7 @@
   "NexxtDropdownButton": "components/organisms/DropdownButton/DropdownButton.vue",
   "NexxtFontPicker": "components/organisms/FontPicker/FontPicker.vue",
   "NexxtHeader": "components/organisms/Header/Header.vue",
+  "NexxtIconPicker": "components/organisms/IconPicker/IconPicker.vue",
   "NexxtModal": "components/organisms/Modal/Modal.vue",
   "NexxtPickerPanel": "components/organisms/PickerPanel/PickerPanel.vue",
   "NexxtProgressBar": "components/organisms/ProgressBar/ProgressBar.vue",

package/src/index.ts

@@ -126,6 +126,23 @@ export type {
   NexxtFontPickerMessages,
   NexxtFontPickerProps,
 } from './components/organisms/FontPicker/FontPicker.vue'
+export type {
+  NexxtIconPickerCategory,
+  NexxtIconPickerIcon,
+  NexxtIconPickerMessages,
+  NexxtIconPickerPinned,
+  NexxtIconPickerProps,
+  NexxtIconPickerStyle,
+  NexxtIconPickerValue,
+} from './components/organisms/IconPicker/IconPicker.vue'
+export {
+  iconLabelFromName,
+  iconSearchIndex,
+  iconStyleFor,
+  searchIcons,
+  sortIconsByLabel,
+} from './components/organisms/IconPicker/iconPickerHelpers'
+export type { NexxtIconPickerSearchEntry } from './components/organisms/IconPicker/iconPickerHelpers'
 export { EDITOR_PADDING_STEPS } from './components/editor/molecules/EditorPadding/EditorPadding.vue'
 export type {
   EditorPaddingMessages,
@@ -214,6 +231,7 @@ export { default as NexxtFloatingPanel } from './components/atoms/FloatingPanel/
 export { default as NexxtFontPicker } from './components/organisms/FontPicker/FontPicker.vue'
 export { default as NexxtHeader } from './components/organisms/Header/Header.vue'
 export { default as NexxtIcon } from './components/atoms/Icon/Icon.vue'
+export { default as NexxtIconPicker } from './components/organisms/IconPicker/IconPicker.vue'
 export { default as NexxtInfoBlock } from './components/molecules/InfoBlock/InfoBlock.vue'
 export { default as NexxtInputField } from './components/molecules/InputField/InputField.vue'
 export { default as NexxtInputSelect } from './components/molecules/InputSelect/InputSelect.vue'