jsdocs & cleanup of gallery-list, utils, & types

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<string, string> })
 
+/**
+ * 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)'
         )
 </template>
-
-<style scoped lang="sass">
-
-</style>

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
 }

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<string, string>
+  /**
+   * 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
 }