Examples search: maintainer’s guide

Architecture overview

The control flow is as follows:

1. Page Load
2. Fetch Collections
3. Filter & Validate Data
4. Build Fuse.js Index
5. Render Filters
6. Apply URL State
7. Listen for Events

Key files

Data flow

1. All collections are fetched from https://public.flourish.studio/visualisation/{id}/visualisation-object.json
2. Cards filtered: only Include === "y" are kept
3. Industry/Purpose values validated against VALID_* allowlists (invalid values silently stripped)
4. Featured === "y" prepends “Featured” to Industry field
5. Sorted by Priority first, then stable pseudo-random order

Configuration points

All configuration is at the top of examples.js:

Important behaviours

• Featured is auto-unchecked when user types a search query
• Featured and Purpose are mutually exclusive - selecting one unchecks the other
• Radio buttons toggle - clicking same one twice unchecks it
• URL uses replaceState - no browser history entries for searches
• Card thumbnails are lazy loaded - card images and gif’s are lazy loaded with an extensive margin

Potential pitfalls

1. Missing Include: "y" - Card silently excluded
2. Misspelled Industry/Purpose - Value silently stripped (but you can check console for warnings)
3. Missing Link field - Preview/Make own buttons won’t work
4. Same card in multiple collections - Shows as duplicates (no deduplication)
5. Modal has no timeout - If iframe fails to load, stays invisible
6. No pagination - Rendering 1000+ results could slow UI

Debug mode

Add ?debug to URL to see:

• Data load counts
• Filter options extracted
• Fuse.js search scores and matched fields
• Lazy image loading

Common tasks

Add new collection

Add ID to COLLECTION_IDS array in examples.js

Add new filter

1. Add field to VISIBLE_FILTER_FIELDS
2. Create corresponding VALID_* array for validation

Adjust search fuzziness

Change FUSE_OPTIONS.threshold (lower = stricter, 0 = exact match, 1 = match anything)

Fuse search explained

Fuse.js scores each potential match between 0.0 (perfect) and 1.0 (complete mismatch). Any result scoring above threshold is excluded.

Score formula

score = (errors / pattern.length) * fieldNorm

• errors — character mismatches (typos) between query and candidate
• pattern.length — length of the search term
• fieldNorm — a multiplier derived from the total length of the field being searched

Without the flags below, two additional factors affect the score: the position of the match inside the field, and the ratio of the query length to the field length. Both are undesirable for our use case, so we disable them.

Our configuration and why

Multi-word queries

Fuse.js treats queries as a single character sequence, not as separate words. "area chart" matches the literal string "area chart" but "chart area" does not match "Area chart" — order matters. Searching for "area chart" also won’t match a field containing only "Area".

Comma-separated field values

With ignoreLocation: true, commas are just characters. A field like "Area, Bump" will match searches for "area" and "bump" equally well.

Troubleshoot missing example

Check:

• Include field is set to “y”
• Industry/Purpose values match VALID_* arrays exactly
• Link field exists with format visualisation/ID or story/ID