@nexxtmove/ui 1.40.0 → 1.41.0

package/src/components/organisms/FontPicker/FontPicker.vue

@@ -0,0 +1,576 @@
+<script lang="ts">
+import type { NexxtPickerItemData } from '../../molecules/PickerList/PickerList.vue'
+
+/** One family in the catalogue the consumer hands in. */
+export interface NexxtFontPickerFont {
+  /** The family name: shown, searched, stored on the model and used as `font-family`. */
+  family: string
+  /**
+   * Decides the group and with it the order: `web-safe` is "Standaard", listed first, `google` is
+   * "Google Fonts" after it; within a group `fonts` keeps its own order. Deliberately this narrow:
+   * this is a font picker, not a generic picker with free-form groups.
+   */
+  source: 'web-safe' | 'google'
+}
+
+/** The "Huisstijl" option at the top of the list. */
+export interface NexxtFontPickerInherit {
+  /** Text of the option, e.g. `'Huisstijl'`. */
+  label: string
+  /**
+   * The family the option points at, shown behind the label in that font. Empty: the option
+   * renders in `font-sans` and shows no family name.
+   */
+  family?: string
+}
+
+/** Overridable copy. Every key is optional and merged per key with the Dutch defaults. */
+export interface NexxtFontPickerMessages {
+  /** Placeholder of the search field. Defaults to `'Lettertype zoeken'`. */
+  searchPlaceholder?: string
+  /** Accessible name of the search field. Defaults to `'Lettertype zoeken'`. */
+  searchLabel?: string
+  /** Accessible name of the listbox. Defaults to `'Lettertypes'`. */
+  listLabel?: string
+  /** Heading of the web-safe group. Defaults to `'Standaard'`. */
+  groupWebSafe?: string
+  /** Heading of the Google group. Defaults to `'Google Fonts'`. */
+  groupGoogle?: string
+  /** Description read out on the current choice. Defaults to `'Huidige keuze'`. */
+  current?: string
+  /** Description read out on the inherit option. Defaults to `'Volgt de huisstijl, ook als die later verandert'`. */
+  inheritDescription?: string
+  /** Heading of the empty search state. Defaults to `'Geen lettertypes 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 list when the catalogue could not be loaded. */
+  catalogueError?: string
+  /** Button in that notice. Defaults to `'Opnieuw proberen'`. */
+  retry?: string
+  /** Announced 500ms after the search changes; receives the number of results. */
+  results?: (count: number) => string
+}
+
+export interface NexxtFontPickerProps {
+  /**
+   * The catalogue: web-safe and Google families together, in display order (web-safe in their
+   * own order, Google by popularity). The component fetches nothing itself.
+   */
+  fonts: NexxtFontPickerFont[]
+  /**
+   * State of fetching the Google catalogue. It only adds to the list: `loading` marks the listbox
+   * busy and, while `fonts` holds no Google family yet, shows skeleton rows under "Google Fonts";
+   * `error` shows a notice with a retry button. Whatever is in `fonts` is listed in every state,
+   * so a refresh or a failed retry never takes a catalogue away that is already there.
+   */
+  catalogueStatus?: 'loading' | 'ready' | 'error'
+  /**
+   * Loads the face for the preview. Called for rows that come within 150px of view (debounced
+   * 100ms after scrolling) and for the current value on mount. A family that loaded is never
+   * asked for again. After a failure (a rejection or a throw) the component asks again once the
+   * row has been out of view and comes back, or when the panel opens again; typing a search or a
+   * new loader function does not, so a loader that keeps failing is not called per keystroke.
+   * The loader needs no cache or retry of its own; meanwhile the row keeps its fallback font and
+   * stays choosable.
+   */
+  loadFont?: (family: string) => Promise<void> | void
+  /** Show the inherit option at the top of the list; `null` on the model is then that option. */
+  inherit?: NexxtFontPickerInherit
+  /**
+   * 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, where the settings block
+   * around the picker is the label. The trigger reads it followed by its value. Give this or
+   * `label`: without either a development build warns in the console.
+   */
+  ariaLabel?: string
+  /** Text in the trigger while nothing is chosen. Defaults to `'Kies een lettertype'`. */
+  placeholder?: string
+  /** The trigger is dimmed and does not open. */
+  disabled?: boolean
+  /**
+   * Copy of the panel. One object on purpose, following the editor components
+   * (`NexxtEditorLineHeight` and the like) rather than the separate copy props of
+   * `NexxtPickerPanel`. Merged per key with the Dutch defaults, so overriding one key keeps the
+   * others. Copy is never translated inside the component.
+   */
+  messages?: NexxtFontPickerMessages
+}
+
+const DEFAULT_MESSAGES = {
+  searchPlaceholder: 'Lettertype zoeken',
+  searchLabel: 'Lettertype zoeken',
+  listLabel: 'Lettertypes',
+  groupWebSafe: 'Standaard',
+  groupGoogle: 'Google Fonts',
+  current: 'Huidige keuze',
+  inheritDescription: 'Volgt de huisstijl, ook als die later verandert',
+  emptyTitle: 'Geen lettertypes gevonden',
+  emptyDescription: (search: string) => `Niets gevonden voor ‘${search}’.`,
+  clearSearch: 'Zoekopdracht wissen',
+  catalogueError:
+    'Google Fonts konden niet worden geladen. Je kunt kiezen uit de standaardlettertypes.',
+  retry: 'Opnieuw proberen',
+  results: (count: number) => `${count} lettertypes`,
+} satisfies Required<NexxtFontPickerMessages>
+
+/** A list row with what the template needs beyond the picker item itself. */
+interface FontRow {
+  item: NexxtPickerItemData
+  /** Family the row renders in; none renders in `font-sans`. */
+  family?: string
+  /** Family named behind the label, for the inherit option. */
+  detail?: string
+  /** What choosing the row writes to the model. */
+  value: string | null
+}
+
+// Fonts are prefixed so no family name can ever collide with the inherit option's id
+const INHERIT_ID = 'inherit'
+const fontId = (family: string) => `font:${family}`
+
+const GROUP_WEB_SAFE = 'web-safe'
+const GROUP_GOOGLE = 'google'
+
+const PANEL_MIN_WIDTH = 320
+const PANEL_HEIGHT = 360
+
+const SKELETON_ROWS = [60, 45, 70, 50, 65, 40].map((width) => ({ width: `${width}%` }))
+
+/** Between "Huisstijl" and its family, in the trigger's accessible name. */
+const SEPARATOR = ' · '
+/**
+ * The same separator on screen. No-break spaces: the label and the family are separate flex
+ * items, and a plain space at the start of the second one would collapse away.
+ */
+const DETAIL_PREFIX = '\u00a0·\u00a0'
+
+/** `font-family` for a preview: the family first, `font-sans` while it loads or if it never does. */
+const fontStyle = (family?: string) =>
+  family ? { fontFamily: `'${family.replace(/['\\]/g, '')}', var(--font-sans)` } : undefined
+</script>
+
+<script lang="ts" setup>
+import { computed, ref, useId, useTemplateRef, watchEffect } from 'vue'
+import { useElementSize } 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 NexxtSkeleton from '../../atoms/Skeleton/Skeleton.vue'
+import NexxtPickerGroup from '../../molecules/PickerGroup/PickerGroup.vue'
+import NexxtPickerPanel from '../PickerPanel/PickerPanel.vue'
+import { useFontPreviewLoader } from './useFontPreviewLoader'
+
+defineOptions({ name: 'NexxtFontPicker' })
+
+const {
+  fonts,
+  catalogueStatus = 'ready',
+  loadFont,
+  inherit,
+  label,
+  ariaLabel,
+  placeholder = 'Kies een lettertype',
+  disabled = false,
+  messages,
+} = defineProps<NexxtFontPickerProps>()
+
+/**
+ * The chosen family. `null` is the inherit option when `inherit` is given, and "nothing chosen"
+ * otherwise. `''` means the same, and is accepted only for existing stored values; the component
+ * itself always writes `null`. Only a choice writes the model; moving the highlight never does.
+ */
+const model = defineModel<string | 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 root = useTemplateRef<HTMLElement>('root')
+const trigger = useTemplateRef<HTMLButtonElement>('trigger')
+const floating = useTemplateRef<InstanceType<typeof NexxtFloatingPanel>>('floating')
+const panelRoot = useTemplateRef<HTMLElement>('panelRoot')
+
+const highlighted = ref<string | null>(null)
+const search = ref('')
+
+// ─── Value ────────────────────────────────────────────────────────────────────
+
+const chosenFamily = computed(() => model.value || null)
+
+const currentId = computed(() => {
+  if (chosenFamily.value) return fontId(chosenFamily.value)
+  return inherit ? INHERIT_ID : null
+})
+
+/** What the trigger shows: the primary text, an optional family behind it, and its font. */
+const display = computed(() => {
+  if (chosenFamily.value) {
+    return { primary: chosenFamily.value, family: chosenFamily.value, placeholder: false }
+  }
+  if (inherit) {
+    const family = inherit.family || undefined
+    return { primary: inherit.label, detail: family, family, placeholder: false }
+  }
+  return { primary: placeholder, placeholder: true }
+})
+
+const displayText = computed(() =>
+  [display.value.primary, display.value.detail].filter(Boolean).join(SEPARATOR),
+)
+
+// Label and value together, so the visible text is part of the name (WCAG 2.5.3). A visible
+// label wins over `ariaLabel`, so the name matches what a sighted user reads.
+const triggerLabelledby = computed(() => (label ? `${labelId} ${valueId}` : undefined))
+const triggerAriaLabel = computed(() =>
+  !label && ariaLabel ? `${ariaLabel}, ${displayText.value}` : undefined,
+)
+
+// ─── Rows ─────────────────────────────────────────────────────────────────────
+
+/** The catalogue as shown: everything in `fonts`, whatever the status, every family once. */
+const shownFonts = computed(() => {
+  const seen = new Set<string>()
+  return fonts.filter(({ family }) => {
+    if (seen.has(family)) return false
+    seen.add(family)
+    return true
+  })
+})
+
+const descriptionFor = (id: string, extra?: string) =>
+  [id === currentId.value ? copy.value.current : undefined, extra].filter(Boolean).join('. ') ||
+  undefined
+
+const rows = computed<FontRow[]>(() => {
+  const result: FontRow[] = []
+
+  if (inherit) {
+    const family = inherit.family || undefined
+    result.push({
+      item: {
+        id: INHERIT_ID,
+        label: inherit.label,
+        keywords: family ? [family] : undefined,
+        description: descriptionFor(INHERIT_ID, copy.value.inheritDescription),
+      },
+      family,
+      detail: family,
+      value: null,
+    })
+  }
+
+  // A family Google dropped, or a Google family while the catalogue is not in: the current
+  // choice is always in the list
+  const chosen = chosenFamily.value
+  if (chosen && !shownFonts.value.some(({ family }) => family === chosen)) {
+    const id = fontId(chosen)
+    result.push({
+      item: { id, label: chosen, description: descriptionFor(id) },
+      family: chosen,
+      value: chosen,
+    })
+  }
+
+  for (const { family, source } of shownFonts.value) {
+    const id = fontId(family)
+    result.push({
+      item: {
+        id,
+        label: family,
+        group: source === 'google' ? GROUP_GOOGLE : GROUP_WEB_SAFE,
+        description: descriptionFor(id),
+      },
+      family,
+      value: family,
+    })
+  }
+
+  return result
+})
+
+const rowById = computed(() => new Map(rows.value.map((row) => [row.item.id, row])))
+const items = computed(() => rows.value.map(({ item }) => item))
+const rowOf = (id: string) => rowById.value.get(id)
+
+const groups = computed(() => [
+  { id: GROUP_WEB_SAFE, label: copy.value.groupWebSafe },
+  { id: GROUP_GOOGLE, label: copy.value.groupGoogle },
+])
+
+const loading = computed(() => catalogueStatus === 'loading')
+const failed = computed(() => catalogueStatus === 'error')
+// The skeletons stand in for a Google group that is not there yet; next to a real one they would
+// repeat its heading
+const showSkeletons = computed(
+  () => loading.value && !shownFonts.value.some(({ source }) => source === 'google'),
+)
+
+// A trigger without either has no name for the field, and a union type to require one would
+// collapse the props to `Record<string, any>` in the emitted d.ts. `process.env.NODE_ENV` stays
+// in the library build, so the consumer's bundler decides whether this runs; `import.meta.env.DEV`
+// would be fixed to `false` when the library is built.
+if (process.env.NODE_ENV !== 'production') {
+  watchEffect(() => {
+    if (!label && !ariaLabel) {
+      console.warn('[NexxtFontPicker] Pass `label` or `ariaLabel`: the trigger has no name.')
+    }
+  })
+}
+
+// ─── Panel ────────────────────────────────────────────────────────────────────
+
+const { width: observedWidth } = useElementSize(trigger, undefined, { box: 'border-box' })
+// Also read on open: a ResizeObserver reports a frame after mount, and a panel opened before that
+// would come out at its minimum width
+const openedWidth = ref(0)
+const triggerWidth = computed(() => observedWidth.value || openedWidth.value)
+
+/** The trigger's width with a 320px minimum, within the viewport; 360px high where it fits. */
+const panelStyle = (availableHeight: number | null) => ({
+  width: `min(max(${PANEL_MIN_WIDTH}px, ${Math.round(triggerWidth.value)}px), calc(100vw - 16px))`,
+  height: `min(${PANEL_HEIGHT}px, ${availableHeight ?? PANEL_HEIGHT}px, calc(100dvh - 5rem))`,
+})
+
+const panelLabel = computed(() => label ?? ariaLabel ?? copy.value.listLabel)
+
+const onOpen = () => {
+  openedWidth.value = trigger.value?.offsetWidth ?? 0
+  search.value = ''
+  highlighted.value = currentId.value
+  emit('open')
+}
+
+const onTriggerKeydown = (event: KeyboardEvent) => {
+  if (event.key !== 'ArrowDown' || floating.value?.isOpen) return
+  event.preventDefault()
+  floating.value?.open()
+}
+
+// Focus goes back first: the panel is not teleported, so FloatingPanel does not hand it back
+// itself, and the field that has it is about to leave the DOM
+const closeToTrigger = () => {
+  trigger.value?.focus()
+  floating.value?.close()
+}
+
+const onSelect = (item: NexxtPickerItemData) => {
+  const row = rowOf(item.id)
+  // Against the raw model, so choosing the inherit option on a stored `''` writes `null`
+  if (row && row.value !== model.value) model.value = row.value
+  closeToTrigger()
+}
+
+// Tab out of the panel and the trigger closes the panel, without moving focus. No focus trap.
+// A `null` target (a click on the panel's own background) is left to FloatingPanel's outside click.
+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()
+}
+
+// ─── Loading faces ────────────────────────────────────────────────────────────
+
+useFontPreviewLoader({
+  loadFont: () => loadFont,
+  container: () => panelRoot.value,
+  rows: [search, items],
+  current: () => display.value.family,
+})
+
+// ─── Classes ──────────────────────────────────────────────────────────────────
+
+const TRIGGER_CLASSES = {
+  base: 'group flex h-10 w-full min-w-0 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',
+  enabled: 'cursor-pointer',
+  disabled: 'cursor-not-allowed opacity-50',
+}
+
+const CHEVRON_CLASSES = {
+  base: 'shrink-0 text-gray-700 transition-transform duration-200 motion-reduce:transition-none',
+  open: 'rotate-180',
+}
+
+// One text style everywhere; only "Huisstijl" keeps its width when a family follows it
+const PRIMARY_CLASSES = {
+  alone: 'min-w-0 truncate',
+  withDetail: 'shrink-0',
+}
+
+const triggerClass = computed(() => [
+  TRIGGER_CLASSES.base,
+  disabled ? TRIGGER_CLASSES.disabled : TRIGGER_CLASSES.enabled,
+])
+
+const valueClass = computed(() => [
+  'flex min-w-0 flex-1 items-center small-normal',
+  display.value.placeholder ? 'text-gray-700' : 'text-gray-900',
+])
+
+/**
+ * Grouped rows sit 12px further in than their group heading, the same step as the grouped options
+ * of NexxtComboboxPanel (heading `px-6`, option `pl-9`). The option keeps PickerItem's `px-2`, so
+ * the step goes on the row content; ungrouped rows (inherit, a value outside the catalogue) stay
+ * level with the headings.
+ */
+const ROW_CLASSES = {
+  base: 'flex min-w-0 flex-1 items-center body-normal leading-6 text-gray-900',
+  grouped: 'pl-3',
+}
+
+const rowClass = (item: NexxtPickerItemData) => [
+  ROW_CLASSES.base,
+  item.group && ROW_CLASSES.grouped,
+]
+
+const primaryClass = (detail?: string) =>
+  detail ? PRIMARY_CLASSES.withDetail : PRIMARY_CLASSES.alone
+
+const chevronClass = (isOpen: boolean) => [CHEVRON_CLASSES.base, isOpen && CHEVRON_CLASSES.open]
+</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>
+
+    <NexxtFloatingPanel
+      ref="floating"
+      class="w-full"
+      placement="bottom-start"
+      surface
+      fit-height
+      @open="onOpen"
+      @close="emit('close')"
+    >
+      <template #trigger="{ isOpen, toggle }">
+        <!--
+          `aria-haspopup="listbox"`, as NexxtSelect: what the user picks from is the listbox, and
+          that is what a screen reader should promise. `dialog` would claim a `role="dialog"`,
+          which the panel is not (it is a non-modal `role="group"` around a search field and the
+          listbox), and ARIA has no `group` value to match it exactly.
+        -->
+        <button
+          :id="triggerId"
+          ref="trigger"
+          type="button"
+          aria-haspopup="listbox"
+          :aria-expanded="isOpen"
+          :aria-label="triggerAriaLabel"
+          :aria-labelledby="triggerLabelledby"
+          :disabled="disabled"
+          :class="triggerClass"
+          @click="toggle"
+          @keydown="onTriggerKeydown"
+        >
+          <span :id="valueId" :class="valueClass" :style="fontStyle(display.family)">
+            <span :class="primaryClass(display.detail)">{{ display.primary }}</span>
+            <span v-if="display.detail" class="min-w-0 truncate text-gray-700">
+              {{ DETAIL_PREFIX }}{{ display.detail }}
+            </span>
+          </span>
+          <NexxtIcon name="chevron-down" aria-hidden="true" :class="chevronClass(isOpen)" />
+        </button>
+      </template>
+
+      <template #content="{ availableHeight }">
+        <div ref="panelRoot" class="flex flex-col" :style="panelStyle(availableHeight)">
+          <NexxtPickerPanel
+            v-model:highlighted="highlighted"
+            v-model:search="search"
+            class="min-h-0 flex-1"
+            width="100%"
+            height="100%"
+            :preview="false"
+            :collapsible="false"
+            :items="items"
+            :groups="groups"
+            :busy="loading"
+            :aria-label="panelLabel"
+            :list-label="copy.listLabel"
+            :search-label="copy.searchLabel"
+            :search-placeholder="copy.searchPlaceholder"
+            :empty-title="copy.emptyTitle"
+            :empty-description="copy.emptyDescription"
+            :clear-label="copy.clearSearch"
+            :results-announcement="copy.results"
+            @select="onSelect"
+            @close="closeToTrigger"
+          >
+            <template #item="{ item }">
+              <span
+                :class="rowClass(item)"
+                :style="fontStyle(rowOf(item.id)?.family)"
+                :data-font-family="rowOf(item.id)?.family"
+              >
+                <span :class="primaryClass(rowOf(item.id)?.detail)">{{ item.label }}</span>
+                <span v-if="rowOf(item.id)?.detail" class="min-w-0 truncate text-gray-700">
+                  {{ DETAIL_PREFIX }}{{ rowOf(item.id)?.detail }}
+                </span>
+              </span>
+              <NexxtIcon
+                v-if="item.id === currentId"
+                name="check"
+                aria-hidden="true"
+                class="shrink-0 text-xs text-cornflower-blue-600"
+              />
+            </template>
+
+            <!-- The heading and rows stand in for the Google group while it loads. They are no
+                 options, so they stay out of the accessibility tree; `aria-busy` says the rest. -->
+            <template v-if="showSkeletons" #append>
+              <NexxtPickerGroup :label="copy.groupGoogle" :collapsible="false" aria-hidden="true">
+                <div
+                  v-for="(style, index) in SKELETON_ROWS"
+                  :key="index"
+                  class="flex h-9 shrink-0 items-center pr-2 pl-5"
+                >
+                  <!-- `pl-5`: PickerItem's 8px plus the 12px step of a grouped row -->
+                  <NexxtSkeleton class="h-3" :style="style" />
+                </div>
+              </NexxtPickerGroup>
+            </template>
+          </NexxtPickerPanel>
+
+          <!-- Outside the listbox, so it is no option; 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>
+      </template>
+    </NexxtFloatingPanel>
+  </div>
+</template>

package/src/components/organisms/FontPicker/useFontPreviewLoader.ts

@@ -0,0 +1,118 @@
+import { onBeforeUnmount, watch, type WatchSource } from 'vue'
+import { useMounted } from '@vueuse/core'
+
+/** Rows within this distance of the visible part of the list count as in view. */
+const LOAD_MARGIN_PX = 150
+/** Scrolling has to rest this long before the rows in view are requested. */
+const LOAD_DEBOUNCE_MS = 100
+
+export interface FontPreviewLoaderOptions {
+  /** The consumer's loader; nothing is requested without one. */
+  loadFont: () => ((family: string) => Promise<void> | void) | undefined
+  /** Element holding the listbox; `null` while the panel is closed. */
+  container: () => HTMLElement | null
+  /** Anything whose change re-renders the rows, so they are observed afresh. */
+  rows: WatchSource[]
+  /** Family requested as soon as the component is mounted: the one the trigger shows. */
+  current: () => string | undefined
+}
+
+/**
+ * Requests the face of every family that comes into view in the listbox. Rows mark their family
+ * with `data-font-family`. A request that succeeded (or is still on its way) is never repeated.
+ * One that failed is held back until its row has really been out of view, or until the panel
+ * opens again; re-observing the rows (a search, new items, a new loader) does not count, so a
+ * loader that keeps failing is not called on every keystroke. Meanwhile the row keeps its
+ * fallback font and stays choosable, so there is nothing to report.
+ */
+export const useFontPreviewLoader = ({
+  loadFont,
+  container,
+  rows,
+  current,
+}: FontPreviewLoaderOptions) => {
+  /** Loaded, or on its way. */
+  const requested = new Set<string>()
+  /** Failed, and not yet out of view since: not asked for again until then. */
+  const failed = new Set<string>()
+
+  const request = (family: string) => {
+    const load = loadFont()
+    if (!load || requested.has(family) || failed.has(family)) return
+    requested.add(family)
+    // async, so a loader that throws synchronously is caught the same way as a rejection. No
+    // retry loop and no timer: the family waits for its row to leave the view and come back
+    void (async () => load(family))().catch(() => {
+      requested.delete(family)
+      failed.add(family)
+    })
+  }
+
+  // Not during SSR: the face is loaded in the browser that shows it
+  const isMounted = useMounted()
+
+  // The loader is a source too: one that arrives after mount still gets the current family. Any
+  // later loader inherits `requested` and `failed`, so a new identity asks for nothing again
+  watch(
+    [isMounted, current, loadFont],
+    ([mounted, family]) => {
+      if (mounted && family) request(family)
+    },
+    { immediate: true },
+  )
+
+  /** Families of the rows within reach of the view right now. */
+  const inView = new Set<string>()
+  let observer: IntersectionObserver | undefined
+  let flushTimer: ReturnType<typeof setTimeout> | undefined
+
+  // Debounced, so scrolling fast past a few hundred rows requests only where it comes to rest
+  const onIntersect = (entries: IntersectionObserverEntry[]) => {
+    for (const entry of entries) {
+      const family = (entry.target as HTMLElement).dataset.fontFamily
+      if (!family) continue
+      if (entry.isIntersecting) inView.add(family)
+      else {
+        inView.delete(family)
+        // really out of view: a failed family may be tried again when it comes back
+        failed.delete(family)
+      }
+    }
+    clearTimeout(flushTimer)
+    flushTimer = setTimeout(() => inView.forEach(request), LOAD_DEBOUNCE_MS)
+  }
+
+  const stop = () => {
+    clearTimeout(flushTimer)
+    observer?.disconnect()
+    observer = undefined
+    inView.clear()
+  }
+
+  const observe = () => {
+    stop()
+    const listbox = container()?.querySelector<HTMLElement>('[role="listbox"]')
+    if (!listbox || !loadFont() || typeof IntersectionObserver === 'undefined') return
+
+    observer = new IntersectionObserver(onIntersect, {
+      root: listbox,
+      rootMargin: `${LOAD_MARGIN_PX}px 0px`,
+    })
+    listbox.querySelectorAll<HTMLElement>('[data-font-family]').forEach((row) => {
+      observer?.observe(row)
+    })
+  }
+
+  // Every change of the rendered rows, or of the loader, re-observes them; the panel closing
+  // disconnects. Opening the panel again gives failed families a new chance
+  watch(
+    [container, loadFont, ...rows],
+    ([element], [previous]) => {
+      if (element && !previous) failed.clear()
+      observe()
+    },
+    { flush: 'post' },
+  )
+
+  onBeforeUnmount(stop)
+}