@nexxtmove/ui 2.6.0 → 2.7.0

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

@@ -0,0 +1,734 @@
+import type { Meta, StoryObj } from '@storybook/vue3-vite'
+import { expect, fn, userEvent, waitFor, within } from 'storybook/test'
+import { ref } from 'vue'
+import IconPicker, {
+  type NexxtIconPickerCategory,
+  type NexxtIconPickerIcon,
+  type NexxtIconPickerStyle,
+  type NexxtIconPickerValue,
+} from './IconPicker.vue'
+
+/**
+ * The stories draw with the Font Awesome kit Storybook loads; the component itself knows no icon
+ * set. These classes and `iconClass` are what a consumer hands in.
+ */
+const STYLES: NexxtIconPickerStyle[] = [
+  { id: 'light', label: 'Light', classes: ['fa-light'] },
+  { id: 'regular', label: 'Regular', classes: ['fa-regular'] },
+  { id: 'solid', label: 'Solid', classes: ['fa-solid'] },
+  { id: 'thin', label: 'Thin', classes: ['fa-thin'] },
+  { id: 'duotone-light', label: 'Duotone', classes: ['fa-duotone', 'fa-light'] },
+  { id: 'brands', label: 'Merk', classes: ['fa-brands'] },
+]
+
+const ALL_STYLES = ['light', 'regular', 'solid', 'thin', 'duotone-light']
+
+const iconClass = (name: string) => `fa-${name}`
+
+const icon = (name: string, label: string, terms: string[] = [], styles = ALL_STYLES) => ({
+  name,
+  label,
+  terms,
+  styles,
+})
+
+/** A slice of the kit: about fifty icons, one of them a brand. */
+const ICONS: NexxtIconPickerIcon[] = [
+  icon('house', 'House', ['home', 'building', 'residence']),
+  icon('house-chimney', 'House chimney', ['home', 'fireplace']),
+  icon('house-user', 'House user', ['home', 'resident']),
+  icon('building', 'Building', ['apartment', 'office']),
+  icon('city', 'City', ['buildings', 'town']),
+  icon('store', 'Store', ['shop', 'market']),
+  icon('warehouse', 'Warehouse', ['storage']),
+  icon('key', 'Key', ['unlock', 'password']),
+  icon('door-open', 'Door open', ['entry', 'exit']),
+  icon('bed', 'Bed', ['sleep', 'bedroom']),
+  icon('couch', 'Couch', ['sofa', 'living room']),
+  icon('bath', 'Bath', ['bathroom', 'tub']),
+  // Fewer styles: a cell shows it in the first of `styles` it has when the current one is missing
+  icon('kitchen-set', 'Kitchen set', ['cooking', 'pan'], ['solid', 'regular']),
+  icon('tree', 'Tree', ['forest', 'nature']),
+  icon('leaf', 'Leaf', ['eco', 'green']),
+  icon('sun', 'Sun', ['weather', 'bright']),
+  icon('moon', 'Moon', ['night', 'dark']),
+  icon('cloud', 'Cloud', ['weather']),
+  icon('snowflake', 'Snowflake', ['winter', 'cold']),
+  icon('star', 'Star', ['favorite', 'rating']),
+  icon('heart', 'Heart', ['love', 'like']),
+  icon('bell', 'Bell', ['notification', 'alert']),
+  icon('envelope', 'Envelope', ['email', 'mail', 'letter']),
+  icon('phone', 'Phone', ['call', 'telephone']),
+  icon('comment', 'Comment', ['chat', 'message']),
+  icon('user', 'User', ['person', 'profile']),
+  icon('users', 'Users', ['people', 'group']),
+  icon('user-tie', 'User tie', ['agent', 'business']),
+  icon('handshake', 'Handshake', ['deal', 'agreement']),
+  icon('briefcase', 'Briefcase', ['work', 'business']),
+  icon('chart-line', 'Chart line', ['graph', 'trend']),
+  icon('chart-pie', 'Chart pie', ['graph', 'share']),
+  icon('calendar', 'Calendar', ['date', 'event']),
+  icon('clock', 'Clock', ['time', 'hour']),
+  icon('camera', 'Camera', ['photo', 'picture']),
+  icon('image', 'Image', ['photo', 'picture']),
+  icon('video', 'Video', ['film', 'movie']),
+  icon('music', 'Music', ['song', 'audio']),
+  icon('map-location-dot', 'Map location dot', ['map', 'pin']),
+  icon('location-dot', 'Location dot', ['map', 'pin', 'marker']),
+  icon('car', 'Car', ['vehicle', 'drive']),
+  icon('bicycle', 'Bicycle', ['bike', 'cycle']),
+  icon('plane', 'Plane', ['airplane', 'flight', 'travel']),
+  icon('train', 'Train', ['rail', 'transit']),
+  icon('truck', 'Truck', ['delivery', 'moving']),
+  icon('magnifying-glass', 'Magnifying glass', ['search', 'find']),
+  icon('gear', 'Gear', ['settings', 'cog']),
+  icon('lock', 'Lock', ['secure', 'padlock']),
+  icon('shield', 'Shield', ['protect', 'security']),
+  icon('circle-check', 'Circle check', ['done', 'ok']),
+  icon('circle-info', 'Circle info', ['information', 'help']),
+  icon('linkedin', 'LinkedIn', ['social', 'network'], ['brands']),
+]
+
+/** A few categories. The labels sort in Dutch; the last one shows how a long label truncates. */
+const CATEGORIES: NexxtIconPickerCategory[] = [
+  {
+    id: 'buildings',
+    label: 'Gebouwen',
+    icons: ['house', 'house-chimney', 'house-user', 'building', 'city', 'store', 'warehouse'],
+  },
+  {
+    id: 'household',
+    label: 'Huishouden',
+    icons: ['key', 'door-open', 'bed', 'couch', 'bath', 'kitchen-set', 'house'],
+  },
+  { id: 'nature', label: 'Natuur', icons: ['tree', 'leaf', 'sun', 'moon', 'cloud', 'snowflake'] },
+  {
+    id: 'communication',
+    label: 'Communicatie',
+    icons: ['bell', 'envelope', 'phone', 'comment', 'users'],
+  },
+  {
+    id: 'business',
+    label: 'Zakelijk',
+    icons: ['user-tie', 'handshake', 'briefcase', 'chart-line', 'chart-pie', 'calendar'],
+  },
+  {
+    id: 'transportation',
+    label: 'Vervoer',
+    icons: ['car', 'bicycle', 'plane', 'train', 'truck'],
+  },
+  { id: 'brands', label: 'Merken', icons: ['linkedin'] },
+  // Only names the catalogue does not know: an empty category, which the rail leaves out
+  { id: 'retired', label: 'Archief', icons: ['retired-icon', 'another-retired-icon'] },
+  {
+    id: 'security',
+    label: 'Beveiliging, sloten en toegangscontrole',
+    icons: ['lock', 'key', 'shield'],
+  },
+]
+
+const PINNED = { label: 'Op deze pagina', icons: ['envelope', 'phone', 'location-dot', 'star'] }
+
+export default {
+  title: 'Components/Organisms/IconPicker',
+  component: IconPicker,
+  // Room for the panel under the trigger, also when Docs renders the story inline
+  decorators: [() => ({ template: '<div class="min-h-148 p-2"><story /></div>' })],
+  parameters: {
+    // A new component without known violations: axe gates these stories, against the project's
+    // reporting mode. The plays end with the panel open where its content needs checking.
+    a11y: { test: 'error' },
+  },
+  args: {
+    icons: ICONS,
+    categories: CATEGORIES,
+    styles: STYLES,
+    iconClass,
+    catalogueStatus: 'ready',
+    onOpen: fn(),
+    onClose: fn(),
+    onRetry: fn(),
+  },
+  argTypes: {
+    catalogueStatus: { control: 'inline-radio', options: ['loading', 'ready', 'error'] },
+    side: { control: 'inline-radio', options: ['bottom', 'left'] },
+  },
+} satisfies Meta<typeof IconPicker>
+
+type Story = StoryObj<typeof IconPicker>
+
+/** The settings panel of the editor is 312px of content. */
+const EDITOR_WIDTH = 'w-78'
+
+const renderPicker =
+  (initial: NexxtIconPickerValue | null, frame = EDITOR_WIDTH) =>
+  (args: Story['args']) => ({
+    components: { IconPicker },
+    setup() {
+      const value = ref<NexxtIconPickerValue | null>(initial)
+      return { args, value, frame }
+    },
+    template: `
+      <div class="flex flex-col gap-3">
+        <div :class="frame">
+          <IconPicker v-bind="args" v-model="value" />
+        </div>
+        <button type="button" class="self-start small-normal text-gray-900 underline">Volgende veld</button>
+        <p class="extra-small-normal text-gray-700">
+          model: <code data-testid="model">{{ value === null ? 'null' : value.icon + ' / ' + value.style }}</code>
+        </p>
+      </div>
+    `,
+  })
+
+// The panel is teleported to <body>, so it is looked up there, not in the canvas
+const page = within(document.body)
+
+const triggerOf = (canvasElement: HTMLElement) =>
+  canvasElement.querySelector<HTMLButtonElement>('button[aria-haspopup="grid"]')!
+
+const gridOf = () => page.getByRole('grid')
+
+/** The panel scales in for 200ms; layout sizes are not scaled, rects are. */
+const settled = (element: HTMLElement) =>
+  waitFor(() => expect(getComputedStyle(element.closest('.z-50 > div')!).opacity).toBe('1'))
+
+/**
+ * Opens the panel and waits for its enter transition. The field has focus while the panel still
+ * carries the transition's `opacity-0`, so a `toBeVisible` right after would fail on a slow runner.
+ */
+const openPanel = async (canvasElement: HTMLElement) => {
+  await userEvent.click(triggerOf(canvasElement))
+  const input = await page.findByRole('textbox', { name: 'Icoon zoeken' })
+  await waitFor(() => expect(input).toHaveFocus())
+  await settled(input)
+  return input
+}
+
+const activeCell = () =>
+  document.getElementById(gridOf().getAttribute('aria-activedescendant') ?? '')
+
+const closed = () => waitFor(() => expect(page.queryByRole('grid')).toBeNull())
+
+const MEASURE_CLASS = 'zz-glyph-measure'
+
+/**
+ * The box of the glyph itself, not of its `<i>`: Font Awesome draws the glyph in `::before`, which
+ * has no rect. For one measurement the pseudo-element is switched off and a span with the same
+ * character and font takes its place, laid out exactly as `::before` would be.
+ */
+const glyphBox = (glyph: HTMLElement) => {
+  if (!document.getElementById(MEASURE_CLASS)) {
+    const style = document.createElement('style')
+    style.id = MEASURE_CLASS
+    style.textContent = `.${MEASURE_CLASS}::before { content: none !important; }`
+    document.head.append(style)
+  }
+  const before = getComputedStyle(glyph, '::before')
+  const character = /^"(.*?)"/u.exec(before.content)?.[1] ?? ''
+  const span = document.createElement('span')
+  span.textContent = character
+  Object.assign(span.style, {
+    fontFamily: before.fontFamily,
+    fontWeight: before.fontWeight,
+    fontStyle: before.fontStyle,
+    fontSize: before.fontSize,
+    lineHeight: before.lineHeight,
+  })
+  glyph.classList.add(MEASURE_CLASS)
+  glyph.append(span)
+  const box = span.getBoundingClientRect()
+  span.remove()
+  glyph.classList.remove(MEASURE_CLASS)
+  return { character, box }
+}
+
+/** The glyph's centre lies within 0.5px of its frame's centre, on both axes. */
+const expectCentred = async (glyph: HTMLElement, frame: HTMLElement) => {
+  const { character, box } = glyphBox(glyph)
+  const outer = frame.getBoundingClientRect()
+  await expect(character).not.toBe('')
+  await expect(box.width).toBeGreaterThan(0)
+  await expect(
+    Math.abs(box.left + box.width / 2 - (outer.left + outer.width / 2)),
+  ).toBeLessThanOrEqual(0.5)
+  await expect(
+    Math.abs(box.top + box.height / 2 - (outer.top + outer.height / 2)),
+  ).toBeLessThanOrEqual(0.5)
+}
+
+/** Waits for the icon font, so a glyph has its real width before it is measured. */
+const iconFontReady = async () => {
+  await document.fonts.ready
+  await waitFor(() =>
+    expect(
+      [...document.fonts].some(
+        (font) => /Font Awesome/.test(font.family) && font.status === 'loaded',
+      ),
+    ).toBe(true),
+  )
+}
+
+/**
+ * The editor: no visible label, the icons already on the page pinned on top, and the panel beside
+ * the settings panel. The trigger reads "Symbool, Envelope, Light"; the current icon leads the
+ * pinned section and is the one selected cell.
+ */
+export const Editor: Story = {
+  args: { ariaLabel: 'Symbool', pinned: PINNED },
+  render: renderPicker({ icon: 'envelope', style: 'light' }),
+  play: async ({ canvasElement, args }) => {
+    const canvas = within(canvasElement)
+    const trigger = triggerOf(canvasElement)
+    await expect(trigger).toHaveAccessibleName('Symbool, Envelope, Light')
+    await expect(trigger).toHaveAttribute('aria-expanded', 'false')
+
+    const input = await openPanel(canvasElement)
+    await expect(args.onOpen).toHaveBeenCalledOnce()
+    await expect(trigger).toHaveAttribute('aria-expanded', 'true')
+
+    const grid = gridOf()
+    await settled(grid)
+    await expect(input).toHaveAttribute('aria-controls', grid.id)
+    await expect(page.getByRole('tab', { name: 'Alle iconen' })).toHaveAttribute(
+      'aria-selected',
+      'true',
+    )
+
+    // the pinned section first, the current icon leading it; one selected cell
+    const headers = page.getAllByRole('rowheader')
+    await expect(headers.map((header) => header.textContent)).toEqual([
+      'Op deze pagina',
+      'Alle iconen',
+    ])
+    const selected = grid.querySelectorAll('[aria-selected="true"]')
+    await expect(selected).toHaveLength(1)
+    await expect(selected[0]).toHaveAccessibleName('Envelope')
+    await expect(selected[0]).toHaveAccessibleDescription('Huidige keuze')
+    await expect(selected[0]!.closest('[role="row"]')).toHaveAttribute('aria-rowindex', '2')
+
+    // the panel: 576 wide (less where the viewport is narrower), the surface's shadow-sm
+    const panel = page.getByRole('group', { name: 'Symbool' })
+    const surface = panel.parentElement!
+    await expect(surface.className).toContain('shadow-sm')
+    const viewport = document.documentElement.clientWidth
+    await expect(surface.offsetWidth).toBe(Math.min(576, viewport - 16))
+    await expect(surface.offsetHeight).toBeLessThanOrEqual(520)
+
+    // the rail is 192px; six square cells share the grid's width with 12px between them
+    const rail = page.getByRole('tablist', { name: 'Categorieën' })
+    await expect(rail.offsetWidth).toBe(192)
+    const row = grid.querySelectorAll<HTMLElement>('[role="row"]:has([role="gridcell"])')[1]!
+    await expect(getComputedStyle(row).gridTemplateColumns.split(' ')).toHaveLength(6)
+    await expect(getComputedStyle(row).columnGap).toBe('12px')
+    const cells = Array.from(row.querySelectorAll<HTMLElement>('[role="gridcell"]'))
+    const content = grid.clientWidth - 16
+    const cell = (content - 5 * 12) / 6
+    for (const element of cells) {
+      await expect(Math.abs(element.offsetWidth - cell)).toBeLessThanOrEqual(1)
+      await expect(element.offsetHeight).toBe(element.offsetWidth)
+    }
+
+    // every glyph sits in the middle of its cell, whatever its width: the selected cell, a plain
+    // one, a hovered one; and in the trigger's preview box and the footer
+    await iconFontReady()
+    for (const name of ['Envelope', 'Bicycle', 'Star', 'Phone']) {
+      const target = page.getAllByRole('gridcell', { name })[0]!
+      await expectCentred(target.querySelector('i')!, target)
+    }
+    const camera = page.getByRole('gridcell', { name: 'Camera' })
+    await userEvent.hover(camera)
+    await expectCentred(camera.querySelector('i')!, camera)
+    const preview = trigger.querySelector<HTMLElement>('i')!
+    await expectCentred(preview, preview.parentElement!)
+    const footerGlyph = panel.querySelector<HTMLElement>('[aria-hidden="true"].h-11 i')!
+    await expectCentred(footerGlyph, footerGlyph)
+
+    // hover moves the highlight and the footer, never the model
+    await userEvent.hover(page.getByRole('gridcell', { name: 'Bell' }))
+    await expect(panel).toHaveTextContent('bell')
+    await expect(canvas.getByTestId('model')).toHaveTextContent('envelope / light')
+
+    // a choice writes the model, closes the panel and puts focus back on the trigger
+    await userEvent.click(page.getByRole('gridcell', { name: 'Kitchen set' }))
+    await closed()
+    await expect(trigger).toHaveFocus()
+    // Kitchen set has no light: it takes the first style it has in the order of `styles`
+    await expect(canvas.getByTestId('model')).toHaveTextContent('kitchen-set / regular')
+    await expect(trigger).toHaveAccessibleName('Symbool, Kitchen set, Regular')
+
+    // open again: the panel is left open for axe
+    await openPanel(canvasElement)
+  },
+}
+
+/** A form: visible label, placeholder, nothing chosen yet. */
+export const Form: Story = {
+  args: { label: 'Icoon voor de knop' },
+  render: renderPicker(null, 'w-96'),
+  play: async ({ canvasElement }) => {
+    const trigger = triggerOf(canvasElement)
+    await expect(trigger).toHaveAccessibleName('Icoon voor de knop Kies een icoon')
+    await openPanel(canvasElement)
+    await expect(gridOf().querySelector('[aria-selected="true"]')).toBeNull()
+  },
+}
+
+/**
+ * Search runs over the whole catalogue: name, label and the extra terms, every word has to match.
+ * An exact name ranks first, then a name or label that starts with the search, then one where a
+ * word does, then the rest; alphabetical within a rank. Searching resets the category, a category
+ * clears the search.
+ */
+export const Search: Story = {
+  args: { ariaLabel: 'Symbool' },
+  render: renderPicker({ icon: 'star', style: 'solid' }),
+  play: async ({ canvasElement }) => {
+    const input = await openPanel(canvasElement)
+    const names = () =>
+      page.getAllByRole('gridcell').map((cell) => cell.getAttribute('aria-label') ?? '')
+
+    await userEvent.click(page.getByRole('tab', { name: 'Natuur' }))
+    await expect(names()).toEqual(['Cloud', 'Leaf', 'Moon', 'Snowflake', 'Sun', 'Tree'])
+
+    // exact name, then names that start with it, then a match inside a word
+    await userEvent.type(input, 'house')
+    await expect(page.getByRole('tab', { name: 'Alle iconen' })).toHaveAttribute(
+      'aria-selected',
+      'true',
+    )
+    await expect(names()).toEqual(['House', 'House chimney', 'House user', 'Warehouse'])
+
+    // `home` is only a search term
+    await userEvent.clear(input)
+    await userEvent.type(input, 'home')
+    await expect(names()).toEqual(['House', 'House chimney', 'House user'])
+
+    await userEvent.clear(input)
+    await userEvent.type(input, 'HOUSE chim')
+    await expect(names()).toEqual(['House chimney'])
+
+    // the count is announced after 500ms
+    const live = document.querySelector('[aria-live="polite"]')!
+    await waitFor(() => expect(live).toHaveTextContent('1 icoon'))
+
+    await userEvent.click(page.getByRole('tab', { name: 'Gebouwen' }))
+    await expect(input).toHaveValue('')
+    await waitFor(() => expect(live).toHaveTextContent('7 iconen'))
+
+    // a category without any icon the catalogue knows is not in the rail
+    await expect(page.queryByRole('tab', { name: 'Archief' })).toBeNull()
+
+    // a long label truncates, with the full name as its title
+    const long = page.getByRole('tab', { name: 'Beveiliging, sloten en toegangscontrole' })
+    await expect(long).toHaveAttribute('title', 'Beveiliging, sloten en toegangscontrole')
+    const text = long.querySelector('span')!
+    await expect(getComputedStyle(text).textOverflow).toBe('ellipsis')
+  },
+}
+
+/**
+ * The keyboard: ↓ on the trigger opens with focus in the search field, ↓ goes on into the grid,
+ * arrows, Home/End, Ctrl+Home/End and PageUp/PageDown move the highlight, Enter chooses, Escape
+ * closes without a change. Tab runs search field → rail → grid → out, which closes the panel.
+ */
+export const Keyboard: Story = {
+  args: { ariaLabel: 'Symbool' },
+  render: renderPicker({ icon: 'house', style: 'light' }),
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement)
+    const trigger = triggerOf(canvasElement)
+
+    trigger.focus()
+    await userEvent.keyboard('{ArrowDown}')
+    const input = await page.findByRole('textbox', { name: 'Icoon zoeken' })
+    await waitFor(() => expect(input).toHaveFocus())
+
+    // into the grid: the current icon, in view
+    await userEvent.keyboard('{ArrowDown}')
+    const grid = gridOf()
+    await expect(grid).toHaveFocus()
+    await expect(activeCell()).toHaveAccessibleName('House')
+
+    await userEvent.keyboard('{ArrowRight}')
+    await expect(activeCell()).toHaveAccessibleName('House chimney')
+    await userEvent.keyboard('{Home}')
+    await expect(activeCell()?.getAttribute('aria-colindex')).toBe('1')
+    await userEvent.keyboard('{End}')
+    await expect(activeCell()?.getAttribute('aria-colindex')).toBe('6')
+    await userEvent.keyboard('{Control>}{End}{/Control}')
+    await expect(activeCell()).toHaveAccessibleName('Warehouse')
+    await userEvent.keyboard('{Control>}{Home}{/Control}')
+    await expect(activeCell()).toHaveAccessibleName('Bath')
+
+    // a page is the rows in view less one
+    const rowOf = () => Number(activeCell()!.closest('[role="row"]')!.getAttribute('aria-rowindex'))
+    const step = Math.max(1, Math.floor(grid.clientHeight / (activeCell()!.offsetHeight + 12)) - 1)
+    await userEvent.keyboard('{PageDown}')
+    await expect(rowOf()).toBe(1 + step)
+    await userEvent.keyboard('{PageUp}')
+    await expect(rowOf()).toBe(1)
+
+    // ↑ in the first row goes back to the field; a letter in the grid goes there too
+    await userEvent.keyboard('{ArrowUp}')
+    await expect(input).toHaveFocus()
+    await userEvent.keyboard('{ArrowDown}')
+    await userEvent.keyboard('t')
+    await expect(input).toHaveFocus()
+    await expect(input).toHaveValue('t')
+    await userEvent.clear(input)
+
+    // Enter chooses, closes and returns focus
+    await userEvent.keyboard('{ArrowDown}{ArrowRight}{Enter}')
+    await closed()
+    await expect(trigger).toHaveFocus()
+    await expect(canvas.getByTestId('model')).toHaveTextContent('house-chimney / light')
+
+    // Escape closes without a change; reopening highlights the current icon again
+    await userEvent.keyboard('{Enter}')
+    await waitFor(() => expect(page.getByRole('textbox', { name: 'Icoon zoeken' })).toHaveFocus())
+    await userEvent.click(page.getByRole('tab', { name: 'Natuur' }))
+    await userEvent.keyboard('{Escape}')
+    await closed()
+    await expect(trigger).toHaveFocus()
+    await expect(canvas.getByTestId('model')).toHaveTextContent('house-chimney / light')
+    await userEvent.keyboard('{Enter}')
+    const field = await page.findByRole('textbox', { name: 'Icoon zoeken' })
+    await waitFor(() => expect(field).toHaveFocus())
+    await expect(page.getByRole('tab', { name: 'Alle iconen' })).toHaveAttribute(
+      'aria-selected',
+      'true',
+    )
+    await userEvent.keyboard('{ArrowDown}')
+    await expect(activeCell()).toHaveAccessibleName('House chimney')
+
+    // Tab order: field → rail → grid → out, which closes
+    field.focus()
+    await userEvent.tab()
+    await expect(page.getByRole('tab', { name: 'Alle iconen' })).toHaveFocus()
+    // the rail item shows its focus ring: no `outline-style: none` left over from :focus
+    const focusedTab = page.getByRole('tab', { name: 'Alle iconen' })
+    await expect(focusedTab.matches(':focus-visible')).toBe(true)
+    await expect(getComputedStyle(focusedTab).outlineStyle).not.toBe('none')
+    await expect(getComputedStyle(focusedTab).outlineWidth).toBe('2px')
+    await userEvent.keyboard('{ArrowDown}')
+    await expect(document.activeElement).toHaveAttribute('aria-selected', 'true')
+    await userEvent.tab()
+    await expect(page.getByRole('grid')).toHaveFocus()
+    await userEvent.tab()
+    await closed()
+    await expect(canvas.getByRole('button', { name: 'Volgende veld' })).toHaveFocus()
+  },
+}
+
+/**
+ * The catalogue is on its way: skeletons in the rail and the grid, no spinner. The search field
+ * works already; a term typed now applies once the catalogue is in.
+ */
+export const Loading: Story = {
+  args: { ariaLabel: 'Symbool', icons: [], catalogueStatus: 'loading' },
+  render: renderPicker({ icon: 'house', style: 'light' }),
+  play: async ({ canvasElement }) => {
+    await openPanel(canvasElement)
+    const grid = gridOf()
+    await expect(grid).toHaveAttribute('aria-busy', 'true')
+    await expect(grid.querySelectorAll('.animate-pulse')).toHaveLength(36)
+    const rail = page.getByRole('tablist')
+    await expect(rail.querySelectorAll('.animate-pulse')).toHaveLength(8)
+    // only the skeletons stand in for the categories: none of the real ones shows yet
+    await expect(page.getAllByRole('tab').map((element) => element.textContent?.trim())).toEqual([
+      'Alle iconen',
+    ])
+    await expect(page.queryByRole('progressbar')).toBeNull()
+  },
+}
+
+/**
+ * The app's flow: the catalogue is fetched on the first open. A term typed while it loads is
+ * applied as soon as it is in.
+ */
+export const LazyCatalogue: Story = {
+  args: { ariaLabel: 'Symbool' },
+  render: (args) => ({
+    components: { IconPicker },
+    setup() {
+      const value = ref<NexxtIconPickerValue | null>({ icon: 'star', style: 'light' })
+      const status = ref<'loading' | 'ready' | 'error'>('loading')
+      const icons = ref<NexxtIconPickerIcon[]>([])
+      let fetched = false
+      const onOpen = () => {
+        args.onOpen?.()
+        if (fetched) return
+        fetched = true
+        setTimeout(() => {
+          icons.value = ICONS
+          status.value = 'ready'
+        }, 800)
+      }
+      return { args, value, status, icons, onOpen }
+    },
+    template: `
+      <div class="w-78">
+        <IconPicker v-bind="args" v-model="value" :icons="icons" :catalogue-status="status" @open="onOpen" />
+      </div>
+    `,
+  }),
+  play: async ({ canvasElement }) => {
+    const input = await openPanel(canvasElement)
+    await userEvent.type(input, 'truck')
+    await waitFor(() => expect(page.getByRole('gridcell', { name: 'Truck' })).toBeInTheDocument())
+    await expect(page.getAllByRole('gridcell')).toHaveLength(1)
+  },
+}
+
+/**
+ * NexxtButton's link variant is cornflower-blue-600 on white, 4.31:1: a known violation of the
+ * button itself, not of this picker. Kept out of the gate so the rest of the panel is checked.
+ */
+const LINK_BUTTON_EXEMPT = {
+  a11y: { test: 'error', context: { exclude: ['[data-variant="link"]'] } },
+}
+
+/**
+ * The catalogue failed: the current icon stays the one choosable cell, with a notice and
+ * "Opnieuw proberen" under the grid. The consumer fetches again on `@retry`.
+ */
+export const CatalogueError: Story = {
+  args: { ariaLabel: 'Symbool', icons: [], catalogueStatus: 'error' },
+  parameters: LINK_BUTTON_EXEMPT,
+  render: renderPicker({ icon: 'house-chimney', style: 'solid' }),
+  play: async ({ canvasElement, args }) => {
+    await openPanel(canvasElement)
+    const cells = page.getAllByRole('gridcell')
+    await expect(cells).toHaveLength(1)
+    await expect(cells[0]).toHaveAccessibleName('House chimney')
+    await expect(cells[0]).toHaveAttribute('aria-selected', 'true')
+
+    const retry = page.getByRole('button', { name: 'Opnieuw proberen' })
+    await expect(retry.closest('[role="status"]')).toHaveTextContent(
+      'De iconen konden niet worden geladen.',
+    )
+    // after the grid in the tab order
+    gridOf().focus()
+    await userEvent.tab()
+    await expect(retry).toHaveFocus()
+    await userEvent.keyboard('{Enter}')
+    await expect(args.onRetry).toHaveBeenCalledOnce()
+
+    // the current icon can still be chosen
+    gridOf().focus()
+    await userEvent.keyboard('{Enter}')
+    await closed()
+    await expect(triggerOf(canvasElement)).toHaveFocus()
+    await openPanel(canvasElement)
+  },
+}
+
+/** Nothing matches: the empty state, with a button that clears the search. No grid to control. */
+export const NoResults: Story = {
+  args: { ariaLabel: 'Symbool' },
+  parameters: LINK_BUTTON_EXEMPT,
+  render: renderPicker({ icon: 'house', style: 'light' }),
+  play: async ({ canvasElement }) => {
+    const input = await openPanel(canvasElement)
+    await userEvent.type(input, 'huis')
+    await waitFor(() => expect(page.getByText('Geen iconen gevonden')).toBeVisible())
+    await waitFor(() =>
+      expect(
+        page.getByText('Niets voor ‘huis’. Zoeken werkt alleen met Engelse woorden.'),
+      ).toBeVisible(),
+    )
+    await expect(input).not.toHaveAttribute('aria-controls')
+
+    await userEvent.click(page.getByRole('button', { name: 'Zoekopdracht wissen' }))
+    await expect(input).toHaveValue('')
+    await expect(input).toHaveFocus()
+    await userEvent.type(input, 'huis')
+  },
+}
+
+/**
+ * Next to a side panel: the panel opens to the left of the trigger, `sideOffset` away. Where the
+ * room on the left is less than the panel plus an 8px margin, it opens below, right aligned.
+ */
+export const SideLeft: Story = {
+  args: { ariaLabel: 'Symbool', side: 'left', sideOffset: 37, pinned: PINNED },
+  render: (args) => ({
+    components: { IconPicker },
+    setup() {
+      const value = ref<NexxtIconPickerValue | null>({ icon: 'star', style: 'light' })
+      return { args, value }
+    },
+    template: `
+      <div class="flex justify-end">
+        <div class="w-78 border-l border-gray-200 pl-7">
+          <IconPicker v-bind="args" v-model="value" />
+        </div>
+      </div>
+    `,
+  }),
+  play: async ({ canvasElement }) => {
+    const trigger = triggerOf(canvasElement)
+    await openPanel(canvasElement)
+    const grid = gridOf()
+    await settled(grid)
+    const surface = page.getByRole('group', { name: 'Symbool' }).parentElement!
+    const panel = surface.getBoundingClientRect()
+    const anchor = trigger.getBoundingClientRect()
+
+    if (anchor.left - 37 >= 576 + 8) {
+      await expect(Math.round(anchor.left - panel.right)).toBe(37)
+      await expect(Math.round(panel.top)).toBe(Math.round(anchor.top))
+    } else {
+      await expect(Math.round(panel.top - anchor.bottom)).toBe(8)
+    }
+  },
+}
+
+const SIZE = 4317
+
+/** The full kit is about this size: the grid renders only the rows in view, never all of them. */
+const LARGE: NexxtIconPickerIcon[] = Array.from({ length: SIZE }, (_, index) => {
+  const base = ICONS[index % (ICONS.length - 1)]!
+  return {
+    name: `${base.name}-${index}`,
+    label: `${base.label} ${String(index).padStart(4, '0')}`,
+    terms: base.terms,
+    styles: base.styles,
+  }
+})
+
+const LARGE_LABELS = LARGE.map(({ label }) => label).sort(new Intl.Collator('nl').compare)
+
+/**
+ * 4317 icons, as many as the kit. The grid is virtualised per row: whatever the scroll position,
+ * only the rows in view and three either side are in the DOM.
+ */
+export const LargeCatalogue: Story = {
+  args: {
+    ariaLabel: 'Symbool',
+    icons: LARGE,
+    categories: [],
+    iconClass: (name: string) => `fa-${name.replace(/-\d+$/, '')}`,
+  },
+  render: renderPicker({ icon: 'star-19', style: 'light' }),
+  play: async ({ canvasElement }) => {
+    await openPanel(canvasElement)
+    const grid = gridOf()
+    await expect(grid).toHaveAttribute('aria-rowcount', String(Math.ceil(SIZE / 6)))
+    await expect(grid.querySelectorAll('[role="gridcell"]').length).toBeLessThanOrEqual(150)
+
+    grid.scrollTop = grid.scrollHeight
+    grid.dispatchEvent(new Event('scroll'))
+    await waitFor(() =>
+      expect(page.queryByRole('gridcell', { name: LARGE_LABELS.at(-1) })).toBeInTheDocument(),
+    )
+    await expect(grid.querySelectorAll('[role="gridcell"]').length).toBeLessThanOrEqual(150)
+
+    // Ctrl+Home back to the first cell: the active descendant is always a rendered cell
+    grid.focus()
+    await userEvent.keyboard('{Control>}{Home}{/Control}')
+    await expect(activeCell()).not.toBeNull()
+    await expect(activeCell()).toHaveAccessibleName(LARGE_LABELS[0]!)
+  },
+}