Sandcastle search and filtering updates

[ggetz]

Description

• Added a sandcastle.config.js file for managing gallery and search-related properties which may change more frequently than the source code, and could differ across different deployments.
• scripts/buildGallery.js now:
  • Uses options defined in sandcastle.config.js.
  • Builds gallery files, pagefind output, and list.json directly to the public folder, rather than relying on vite to copy later. This keeps source and output files separate, preventing unintentional overwrites.
  • Via scripts/createGalleryRecord.js, creates an in-memory HTML file for each gallery item that pagefind can use for indexing.
    • We adjust the default weighting schema such that tile >> description >> code in terms of search relevance using the data-pagefind-weight attribute. Hierarchical labels like "Title", "Description", and "Labels" are ignored completed.
    • data-pagefind-meta lets us grab metadata properties. data-pagefind-filter let's us grab the metadata used for filtering. Lastly, id attributes are important to assign for enabling highlighting on the front end.
• Top-level styling was added for code blocks and for highlights using the mark semantic element.
  • Highlighting styles point to the top-level css variables --highlight-color-*, including background color, border color, and text color; hover and pressed variations. Update --highlight-color-* variables in src/App.css to tweak the highlight colors.
• src/utils/loadFromUrl.js is now in it's own file—It loads per the the url param as before, but now throws errors if requested content can not be found. Errors are handled and routed to in-app console to make it obvious to the user.
• Moves gallery-related components and store the src/Gallery directory:
  • src/Gallery/GalleryItemStore.ts creates a shared context for use across gallery components.
  • src/Gallery/GalleryItemList.ts and src/Gallery/GalleryItemCard.ts manages the filtered list of gallery items, implementing the ariakit Composite* abstract components.
    • Search matches should be highlighted in titles, descriptions, and code blocks. Labels that match the current filter will be highlighted (active).
    • When there is code sample relevant to the current search term, it will also appears on the gallery card.
    • I added a "line count" display to give users a bit more context when navigating examples (akin to say video length on youtube). I'm also hoping it reminds us to write more concise examples.
    • Tweaked the styling a bit to allow for more room for descriptions as well as the complete titles. These are essential for navigating the examples, and we're starting to provide more context in descriptions.
  • src/Gallery/GalleryItemSearchInput.tsx handles the search term query input. The pagefind search is performant enough that, IMO, it does not require the debounce, so I left it out for the sake of simplicity. Let me know if there are strong opinions on this.
  • src/Gallery/GalleryItemSearchFilter.tsx handles filtering by labels with the DropdownMenu component so we can show the pagefind total results per-category.
    • Filters can also be updated by clicking the label tags themselves.
• Handle third-party type definitions in a standard and automated manner—.d.ts files moved moved to @types directory that is specified in the typescript config as a types root.

Issue number and link

N/A

Testing plan

1. Verify gallery item loading:

• Try different urls
• Click gallery examples directly
• Click the "open code" button in the top-right of cards
• Navigate back and forward in your browser history

2. Try searching for various terms:

• Ensure the "clear" button clears the search term
• Ensure you can now match titles and descriptions in addition to code

3. Use the filters:

• Make sure we default to "Showcases"
• Use the 'labels' dropdown
• Use the label tags in the gallery item cards

Author checklist

• Fix page title
• Merge sandcastle-v2
• I have performed a self-review of my code
• I have submitted a Contributor License Agreement
• I have added my name to CONTRIBUTORS.md
• I have updated CHANGES.md with a short summary of my change
• I have added or updated unit tests to ensure consistent code coverage
• I have updated the inline documentation, and included code examples where relevant

[github-actions]

Thank you for the pull request, @ggetz!

✅ We can confirm we have a CLA on file for you.

[jjspace]

Thanks @ggetz this is looking pretty good! Definitely glad search is much better with the title/description.

I didn't dig into the code yet but had a handful of small initial comments

Style nit-picks

• gallery card titles are just slightly too wide for the code button, increase padding
• the code examples use the text cursor but clicking them activates it and text is not selectable. Switch to pointer
• The gallery cards feel ever so slightly cramped. maybe increase gap between and padding on edges?
• the image borders seem a little weird in light mode. There's a light line inside the border from something? Maybe use just the border not the outline
• The padding on the 121 for showcases seems bad. I know tt's consistent with the others to be circles but maybe make it expand?. Would happen with any 3 digit number
• The left edge of the labels is not aligned vertically with the title/desc for cards
• Should gallery card labels always be at the bottom of the card? I'm back and forth on this, fine either way I think
• In light mode the badges kinda "disappear" is that what we want? In dark mode they have more contrast. Maybe this is just stratakit itself
• Toggling the theme now creates a "2 step" transition with the main background then the cards (and a few inputs). I didn't see this before, worth investigating?
• When there are no code examples the cards feel just slightly too big. Should we reduce that?
  • Height also seems slightly dictated by the thumbnail aspect ratio. This should not be the case, we should force them to be consistent and crop/stretch as needed
• There is no border on the gallery list header anymore so when scrolling there's not a good distinction between header and items.
  • The number of results also isn't sticky. I think making it sticky with the divider line might be good
  • In dark mode this doesn't matter as much since cards have a different background but in light mode they're the same color and blend together. Maybe we need a different color for the cards?

Functionality

• Seeing a bit of lagging UI when typing searches fast, maybe we do need that debounce
• When loading a gallery example the header title still shows the highlight. This seems weird?
• Is the number in the labels filter supposed to update for the current search term?
• Not totally sure the line number adds much to the gallery but happy to leave it for now and try it out!
• The active "pressing" style applies to the whole card when clicking the label badges which seems wrong
  • Hover styles too but that one's less of a concern
• There's a bit of a lag in updating the "Results" string when switching a label
  • This also seems to apply to the style for the current label? It still shows selected even after the list updates
• The gallery cards are no longer Tab-selectable which is pretty major for a11y
  • The entire gallery list is though? not sure why but it creates a focus outline under the header that looks bad
  • Figured out they do some arrow navigation but tab doesn't work. I assume this is aria-kit shenanagins but probably need to figure that out
• The thumbnail alt text is [object Object], oops!

Video of the slight 2 step lag/update when changing theme and filters:

simplescreenrecorder-2025-08-29_13.23.21.mp4