From cc5b5bbe74657afd4f6d04da818edccdab113fee Mon Sep 17 00:00:00 2001 From: Lightling Date: Thu, 21 Mar 2024 21:34:10 -0400 Subject: [PATCH] jsdocs & cleanup of gallery-list, utils, & types --- src/views/gallery/gallery-list.vue | 46 +++++++++--- src/views/gallery/gallery-utilities.ts | 3 + src/views/gallery/gallery.d.ts | 96 +++++++++++++++++++++++++- 3 files changed, 134 insertions(+), 11 deletions(-) diff --git a/src/views/gallery/gallery-list.vue b/src/views/gallery/gallery-list.vue index 3ad0a04..e5e654b 100644 --- a/src/views/gallery/gallery-list.vue +++ b/src/views/gallery/gallery-list.vue @@ -15,7 +15,11 @@ const props = defineProps<{ variants: string[] }>() -const validateVariants = (variants?: string[]) => { +/** + * Wraps around the path of variant ids to ensure there are not any issues + * @param variants the array of variant ids + */ +const validateVariantPath = (variants?: string[]) => { return !!variants && variants[0] !== '' ? variants : null } @@ -31,11 +35,14 @@ const tagsToggled: string[] = [] const ready = ref(false) const galleryReady = ref(false) const entries = ref({} as GalleryDisplayedEntries) -const variants = ref(validateVariants(props.variants)) +const variants = ref(validateVariantPath(props.variants)) const hasWarnings = ref(false) const hideWarnings = defineModel('showWarnings', { type: Boolean }) const tagsByCategory = ref({} as { [category: string]: Record }) +/** + * Handles updating the displayed tags in the list + */ const onLoadTags = () => { tagsByCategory.value = { 'NoCategory': {}} Object.keys(config.tags).forEach(id => { @@ -51,6 +58,9 @@ const onLoadTags = () => { }) } +/** + * Handles updating the displayed entries in the list + */ const onDisplayEntries = () => { galleryReady.value = false let currentEntries = config.entries @@ -64,6 +74,12 @@ const onDisplayEntries = () => { setTimeout(() => galleryReady.value = true) } +/** + * Handler for the tile clicked event; + * handles navigating to the gallery-view route to display the entry selected + * @param clickEvent.event the event context which invoked this handler + * @param clickEvent.id the id of the tile that was clicked + */ const onTileClicked = (clickEvent: { event: Event, id: string }) => { const { event, id } = clickEvent const entry = entries.value[id] @@ -83,23 +99,39 @@ const onTileClicked = (clickEvent: { event: Event, id: string }) => { } } -const onNavigateBack = (e: Event) => { - e.preventDefault() +/** + * Handler for the back button which appears when navigated into entry variants; + * navigates upward one level from the currently displayed variants + */ +const onNavigateBack = (event: Event) => { + event.preventDefault() let newPath: string | null = variants.value!.slice(0, variants.value!.length - 1).join(';') if (newPath === '') { router.push({ name: routeConfig.name}) variants.value = null } else { router.push({ name: routeConfig.name, query: { v: newPath }}) - variants.value = validateVariants(newPath?.split(';')) + variants.value = validateVariantPath(newPath?.split(';')) } onDisplayEntries() } +/** + * Handler for the toggle for hiding/showing warnings; + * updates localstorage with the state of the checkbox + * so that it is saved between page loads + * @param event the event context which invoked this handler + */ const onHideWarningsToggled = (event: Event) => { storage.write(`${storageId}::hideWarnings`, (event.target as HTMLInputElement).checked) } +/** + * Handler for a tag being selected; + * updates the visibility state of the current entries + * @param event the event context which invoked this handler + * @param tagId: the id of the tag + */ const onToggleTag = (event: Event, tagId: string) => { if ((event.target as HTMLInputElement).checked) { tagsToggled.push(tagId) @@ -194,7 +226,3 @@ onMounted(async () => { @click='onTileClicked($event)' ) - - diff --git a/src/views/gallery/gallery-utilities.ts b/src/views/gallery/gallery-utilities.ts index 10323cf..f546ac0 100644 --- a/src/views/gallery/gallery-utilities.ts +++ b/src/views/gallery/gallery-utilities.ts @@ -32,6 +32,9 @@ export const _amendVariantWithDefaults = (parent: GalleryEntryInheritedPropertie if (!variant.fields && !!parent.fields) { variant.fields = parent.fields } + if (!variant.tags && !!parent.tags) { + variant.tags = parent.tags + } return variant } diff --git a/src/views/gallery/gallery.d.ts b/src/views/gallery/gallery.d.ts index 9e0d7ce..9b84516 100644 --- a/src/views/gallery/gallery.d.ts +++ b/src/views/gallery/gallery.d.ts @@ -1,32 +1,124 @@ +/** + * A partial definition of a {@link GalleryEntry} + * which defines the properties of an entry + * that can be passed down from a top-level entry down to its variants + */ export type GalleryEntryInheritedProperties = { + /** + * [SUPPORTS MARKDOWN] a place for the siteowner to describe the entry + */ description?: string + /** + * a key-value pair set of general-purpose fields to additionally describe the entry + * @example entry.fields = { + * 'date': '1960/01/01', + * 'rating': 'general', + * } + */ fields?: Record + /** + * array of tag-ids that apply to the art; + * this is used to allow a visitor to filter out entries of a specific tag + * @see {@link GalleryList.tags} + */ tags: string[] + /** + * the title of the entry + */ title: string | null | undefined + /** + * any content warnings that apply to the entry, + * which will be used to apply the `.warning` classname + * to the DOM of a gallery tile + * and will be displayed with the tile + */ warning?: string } +/** + * Defines an entry in a gallery that can be displayed in a tiled manner + * and can be clicked by a visitor to display its variants or the entry itself if there are none + */ export type GalleryEntry = GalleryEntryInheritedProperties & { - id: string - thumbnailUrl: string + /** + * the url to the thumbnail to show for the entry in the gallery tile + */ + thumbnailUrl?: string + /** + * the url to the entry itself + */ url?: string + /** + * optional variants for the entry; + * this is a recursive definition of {@link GalleryEntry entries} + * which can be navigated deeper into in a gallery + * in a manner like a folder in a file-based operating system + */ variants?: GalleryEntries } +/** + * Defines the list of entries in a gallery, + * a key-value object where the value is the entry, + * and the key represents the id of a piece; + * it is important for this to be uniquely defined at minimum within + * the scope of the entry in relation to surrounding variants + * in order for the app to properly navigate through variants + * and ultimately the view page displaying the entry + */ export type GalleryEntries = { [idOrTitle: string]: GalleryEntry } +/** + * A wrapper around {@link GalleryEntries} for the app's use only which adds additional fields + * in order for the app to effectively display the entries. + */ export type GalleryDisplayedEntries = { [idOrTitle: string]: GalleryEntry & { + /** + * specifies whether the entry is hidden by the tags selected by a visitor + */ hidden?: boolean }} +/** + * Defines a tag used by entries in a gallery + * used for filtering entries from view + */ export type GalleryTag = { + /** + * specifies a category that the tag belongs to + * in order to optionally organize them in the view; + * if category is not specified, tags will be assigned + * "NoCategory" and organized into a section without a heading + * placed before any other sections formed by categories (if any) + */ category?: string + /** + * specifies the name that the tag will appear as in the DOM; + * if not specified, the id of the tag will be used in its place + */ displayName?: string } +/** + * Defines the list of tags in a gallery, + * a key-value object where the value is the entry, + * and the key represents the id of a tag; + * the id of a tag must be unique, + * and the ids specified in a gallery entry must match + * the ids specified in `GalleryTags` in order for them to work effectively + */ export type GalleryTags = { [id: string]: GalleryTag } +/** + * Defines the model of the `GalleryList` template + */ export type GalleryList = { + /** + * the entries to display in a gallery-list template + */ entries: GalleryEntries + /** + * the tags to use for filtering entries + */ tags: GalleryTags }