feat(site): Preselect external libraries via ?library= URL param (#5180)

* feat(site): Preselect external libraries via `?library=` URL param

Opening /icons/?library=lab now enables the Lab library on load, and
toggling the checkbox keeps the address bar in sync, so the current
selection can be shared as a link.

- Repeated params (?library=a&library=b) and comma lists are accepted;
  unknown values and duplicates are dropped.
- The param is applied in onMounted rather than during setup, so the
  fetch watchers already exist and hydration doesn't mismatch on the
  checkbox.
- The URL is updated with replaceState, preserving history.state and
  other params such as ?search=.

* fix(site): Keep `?library=` across navigation and the icon drawer

The library param was only read on the first mount and was dropped by
the icon drawer, so it stopped matching the selection:

- /icons/?library=lab -> Categories -> uncheck Lab -> Back restored
  ?library=lab in the URL but left nothing selected.
- Opening and closing an icon drawer on desktop kept Lab selected but
  removed ?library= from the URL, so sharing or refreshing lost it.

Now the selection is reconciled with the URL on every mount and on
popstate: a valid ?library= wins, and when the URL has none but a
library is selected, the param is written back with replaceState.
The drawer's pushState calls in IconItem.vue and IconsOverview.vue
keep the param via a new setLibraryParams helper.

* Add localstorage

* Refactor code

---------

Co-authored-by: Eric Fennis <eric.fennis@gmail.com>
This commit is contained in:
Nanashi 2026-11-19 07:47:14 -06:00 committed by GitHub
parent fd124908bd
commit 390e824cfe
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
3 changed files with 106 additions and 34 deletions

View file

@ -8,6 +8,7 @@ import getSVGIcon from '../../utils/getSVGIcon';
import useConfetti from '../../composables/useConfetti';
import Tooltip from '../base/Tooltip.vue';
import { diamond } from '../../../data/iconNodes';
import { setLibraryParams } from '../../composables/useExternalLibs';
const downloadText = 'Download!';
const copiedText = 'Copied!';
@ -76,13 +77,17 @@ async function navigateToIcon(event) {
if (props.overlayMode && showOverlay.value) {
event.preventDefault();
window.history.pushState(
{},
'',
props.externalLibrary
? `/icons/${props.externalLibrary}/${props.name}`
: `/icons/${props.name}`,
// Keep ?library= so the selection survives opening and closing the drawer.
const url = setLibraryParams(
new URL(
props.externalLibrary
? `/icons/${props.externalLibrary}/${props.name}`
: `/icons/${props.name}`,
window.location.origin,
),
);
window.history.pushState({}, '', url);
emit(
'setActiveIcon',
props.externalLibrary ? `${props.externalLibrary}:${props.name}` : props.name,

View file

@ -18,6 +18,7 @@ import useSearchPlaceholder from '../../utils/useSearchPlaceholder.ts';
import Icon from '@lucide/vue/src/Icon';
import { listSortDescending } from '~/.vitepress/data/iconNodes';
import { track, trackDebounced } from '../../utils/openpanel';
import { setLibraryParams } from '../../composables/useExternalLibs';
const ICON_SIZE = 56;
const ICON_GRID_GAP = 8;
@ -206,6 +207,8 @@ function handleCloseDrawer() {
url.searchParams.set('search', searchQueryDebounced.value);
}
setLibraryParams(url);
window.history.pushState({}, '', url);
}

View file

@ -1,4 +1,5 @@
import { ref, inject, Ref, watch } from 'vue';
import { ref, inject, Ref, watch, onMounted } from 'vue';
import { useLocalStorage } from '@vueuse/core';
import { ExternalLibs, IconEntity } from '../types';
export const EXTERNAL_LIBS_CONTEXT = Symbol('externalLibs');
@ -6,11 +7,11 @@ export const EXTERNAL_LIBS_CONTEXT = Symbol('externalLibs');
type ExternalIconNodes = Partial<Record<ExternalLibs, IconEntity[]>>;
interface ExternalLibContext {
selectedLibs: Ref<[ExternalLibs]>;
selectedLibs: Ref<ExternalLibs[]>;
externalIconNodes: Ref<ExternalIconNodes>;
}
export const externalLibContext = {
export const externalLibContext: ExternalLibContext = {
selectedLibs: ref([]),
externalIconNodes: ref({}),
};
@ -19,41 +20,104 @@ const externalLibIconNodesAPI = {
lab: `${import.meta.env.DEV ? 'http://localhost:3000' : ''}/api/lab/icon-details`,
};
export function useExternalLibs(): ExternalLibContext {
const context = inject<ExternalLibContext>(EXTERNAL_LIBS_CONTEXT);
// URL query parameter for preselecting external libraries, e.g. /icons/?library=lab
// Repeat it for several libraries: ?library=lab&library=other
const URL_PARAM = 'library';
watch(context?.selectedLibs, async (selectedLibs) => {
const savedIconNodes = { ...context?.externalIconNodes.value };
const newExternalIconNodes: ExternalIconNodes = {};
const storedLibs = useLocalStorage<ExternalLibs[]>('external-libs', [], { initOnMounted: false });
try {
for (const lib of selectedLibs) {
if (savedIconNodes[lib]) {
newExternalIconNodes[lib] = savedIconNodes[lib];
} else {
const response = await fetch(externalLibIconNodesAPI[lib]);
const iconDetails = await response.json();
const isExternalLib = (value: string): value is ExternalLibs =>
Object.keys(externalLibIconNodesAPI).includes(value);
if (iconDetails) {
newExternalIconNodes[lib] = Object.values(iconDetails).map((iconEntity: IconEntity) => {
return {
...iconEntity,
externalLibrary: lib,
};
});
}
/**
* Writes the current library selection into `url` as `?library=` params, replacing any
* existing ones. Use it when building URLs for history.pushState so the param survives.
*/
export const setLibraryParams = (url: URL, libs = externalLibContext.selectedLibs.value) => {
url.searchParams.delete(URL_PARAM);
for (const lib of libs) {
url.searchParams.append(URL_PARAM, lib);
}
return url;
};
// Keep the URL shareable and remember the selection for the next visit.
const persistSelection = (libs: ExternalLibs[]) => {
storedLibs.value = libs;
const url = setLibraryParams(new URL(window.location.href), libs);
window.history.replaceState(window.history.state, '', url);
};
// `?library=` wins (shared links, Back/Forward); otherwise use the last selection.
const syncSelection = () => {
const { selectedLibs } = externalLibContext;
const libsFromUrl = new URLSearchParams(window.location.search)
.getAll(URL_PARAM)
.filter(isExternalLib);
const libs = libsFromUrl.length
? [...new Set(libsFromUrl)]
: storedLibs.value.filter(isExternalLib);
if (String(libs) !== String(selectedLibs.value)) {
selectedLibs.value = libs;
}
// Also when nothing changed, to restore the param on URLs that dropped it.
persistSelection(libs);
};
const fetchExternalIconNodes = async (selectedLibs: ExternalLibs[]) => {
const { externalIconNodes } = externalLibContext;
const savedIconNodes = { ...externalIconNodes.value };
const newExternalIconNodes: ExternalIconNodes = {};
try {
for (const lib of selectedLibs) {
if (savedIconNodes[lib]) {
newExternalIconNodes[lib] = savedIconNodes[lib];
} else {
const response = await fetch(externalLibIconNodesAPI[lib]);
const iconDetails = await response.json();
if (iconDetails) {
newExternalIconNodes[lib] = Object.values(iconDetails).map((iconEntity: IconEntity) => {
return {
...iconEntity,
externalLibrary: lib,
};
});
}
}
context.externalIconNodes.value = newExternalIconNodes;
} catch (error) {
console.error(error);
}
});
externalIconNodes.value = newExternalIconNodes;
} catch (error) {
console.error(error);
}
};
// Registered once at module level so they outlive any single component. The selection only
// changes in the browser, so the watchers never run during SSR.
watch(externalLibContext.selectedLibs, persistSelection);
watch(externalLibContext.selectedLibs, fetchExternalIconNodes);
if (typeof window !== 'undefined') {
window.addEventListener('popstate', syncSelection);
}
export function useExternalLibs(): ExternalLibContext {
const context = inject<ExternalLibContext>(EXTERNAL_LIBS_CONTEXT);
if (!context) {
throw new Error('useExternalLibs must be used with externalLibs context');
}
// Apply the URL/stored selection after hydration to avoid an SSR mismatch on the checkbox.
// Runs on every mount so client-side navigation to a URL carrying the param reapplies it.
onMounted(syncSelection);
return context;
}