docs: enhance component documentation with usage and reference tracking

- Add comprehensive JSDoc comments to HomeView and InfiniteScroll components - Document method visibility (@public/@internal) and usage contexts - Add clear references to where methods are called from (template, components, lifecycle) - Include file-level documentation with component descriptions - Document component dependencies and template usage - Add parameter and return type documentation - Clarify method call chains and dependencies - Document event emissions and component interactions This commit improves code maintainability by making method usage and component relationships more explicit in the documentation.
7 months ago · fa20360d87
4 changed files with 317 additions and 13 deletions
--- a/src/components/InfiniteScroll.vue
+++ b/src/components/InfiniteScroll.vue
@ -1,3 +1,13 @@
+/**
+ * @file InfiniteScroll.vue
+ * @description A Vue component that implements infinite scrolling functionality using the Intersection Observer API.
+ * This component emits a 'reached-bottom' event when the user scrolls near the bottom of the content.
+ * It includes debouncing to prevent multiple rapid triggers and loading state management.
+ * 
+ * @author Matthew Raymer
+ * @version 1.0.0
+ */
+
 <template>
  <div ref="scrollContainer">
    <slot />
@ -8,15 +18,51 @@
 <script lang="ts">
 import { Component, Emit, Prop, Vue } from "vue-facing-decorator";

+/**
+ * InfiniteScroll Component
+ * 
+ * This component implements infinite scrolling functionality by observing when a user
+ * scrolls near the bottom of the content. It uses the Intersection Observer API for
+ * efficient scroll detection and includes debouncing to prevent multiple rapid triggers.
+ * 
+ * Usage in template:
+ * ```vue
+ * <InfiniteScroll @reached-bottom="loadMore">
+ *   <div>Content goes here</div>
+ * </InfiniteScroll>
+ * ```
+ * 
+ * Props:
+ * - distance: number (default: 200) - Distance in pixels from the bottom at which to trigger the event
+ * 
+ * Events:
+ * - reached-bottom: Emitted when the user scrolls near the bottom of the content
+ */
@Component
 export default class InfiniteScroll extends Vue {
+  /** Distance in pixels from the bottom at which to trigger the reached-bottom event */
  @Prop({ default: 200 })
  readonly distance!: number;
+
+  /** Intersection Observer instance for detecting scroll position */
  private observer!: IntersectionObserver;
+
+  /** Flag to track initial render state */
  private isInitialRender = true;
+
+  /** Flag to prevent multiple simultaneous loading states */
  private isLoading = false;
+
+  /** Timeout ID for debouncing scroll events */
  private debounceTimeout: number | null = null;

+  /**
+   * Vue lifecycle hook that runs after component updates.
+   * Initializes the Intersection Observer if not already set up.
+   * 
+   * @internal
+   * Used internally by Vue's lifecycle system
+   */
  updated() {
    if (!this.observer) {
      const options = {
@ -32,7 +78,13 @@ export default class InfiniteScroll extends Vue {
    }
  }

-  // 'beforeUnmount' hook runs before unmounting the component
+  /**
+   * Vue lifecycle hook that runs before component unmounting.
+   * Cleans up the Intersection Observer and any pending timeouts.
+   * 
+   * @internal
+   * Used internally by Vue's lifecycle system
+   */
  beforeUnmount() {
    if (this.observer) {
      this.observer.disconnect();
@ -42,6 +94,17 @@ export default class InfiniteScroll extends Vue {
    }
  }

+  /**
+   * Handles intersection observer callbacks when the sentinel element becomes visible.
+   * Implements debouncing to prevent multiple rapid triggers and manages loading state.
+   * 
+   * @param entries - Array of IntersectionObserverEntry objects
+   * @returns false (required by @Emit decorator)
+   * 
+   * @internal
+   * Used internally by the Intersection Observer
+   * @emits reached-bottom - Emitted when the user scrolls near the bottom
+   */
  @Emit("reached-bottom")
  handleIntersection(entries: IntersectionObserverEntry[]) {
    const entry = entries[0];
--- a/src/views/HomeView.vue
+++ b/src/views/HomeView.vue
@ -1,3 +1,13 @@
+/**
+ * @file HomeView.vue
+ * @description Main view component for the application's home page. Handles user identity, feed management,
+ * and interaction with various dialogs and components. Implements infinite scrolling for activity feed
+ * and manages user registration status.
+ * 
+ * @author Matthew Raymer
+ * @version 1.0.0
+ */
+
 <template>
  <QuickNav selected="Home" />
  <TopMessage />
@ -345,13 +355,30 @@ import { logger } from "../utils/logger";
 import { GiveRecordWithContactInfo } from "types";

 /**
- * HomeView - Main view component for the application's home page
+ * HomeView Component
+ * 
+ * Main view component that handles:
+ * 1. User identity and registration management
+ * 2. Activity feed with infinite scrolling
+ * 3. Contact management and display
+ * 4. Gift/claim creation and viewing
+ * 5. Feed filtering and settings
 * 
- * Workflow:
- * 1. On mount, initializes user identity, settings, and data
- * 2. Handles user registration status
- * 3. Manages feed of activities and offers
- * 4. Provides interface for creating and viewing claims
+ * Template Usage:
+ * ```vue
+ * <HomeView>
+ *   <!-- Content is managed internally -->
+ * </HomeView>
+ * ```
+ * 
+ * Component Dependencies:
+ * - QuickNav: Navigation component
+ * - TopMessage: Message display component
+ * - OnboardingDialog: User onboarding flow
+ * - GiftedDialog: Gift creation interface
+ * - FeedFilters: Feed filtering options
+ * - InfiniteScroll: Infinite scrolling functionality
+ * - ActivityListItem: Individual activity display
 */
@Component({
  components: {
@ -417,6 +444,9 @@ export default class HomeView extends Vue {
   * 5. Load feed data
   * 6. Load new offers
   * 7. Check onboarding status
+   * 
+   * @internal
+   * Called automatically by Vue lifecycle system
   */
  async mounted() {
    try {
@ -436,6 +466,11 @@ export default class HomeView extends Vue {
   * Initializes user identity
   * - Retrieves existing DIDs
   * - Creates new DID if none exists
+   * - Loads user settings and contacts
+   * - Checks registration status
+   * 
+   * @internal
+   * Called by mounted()
   * @throws Logs error if DID retrieval fails
   */
  private async initializeIdentity() {
@ -541,6 +576,9 @@ export default class HomeView extends Vue {
   * - Feed filters and view settings
   * - Registration status
   * - Notification acknowledgments
+   * 
+   * @internal
+   * Called by mounted() and reloadFeedOnChange()
   */
  private async loadSettings() {
    const settings = await retrieveSettingsForActiveAccount();
@ -562,6 +600,9 @@ export default class HomeView extends Vue {
  /**
   * Loads user contacts from database
   * Used for displaying contact info in feed and actions
+   * 
+   * @internal
+   * Called by mounted() and initializeIdentity()
   */
  private async loadContacts() {
    this.allContacts = await db.contacts.toArray();
@ -572,6 +613,9 @@ export default class HomeView extends Vue {
   * - Checks if unregistered user can access API
   * - Updates registration status if successful
   * - Preserves unregistered state on failure
+   * 
+   * @internal
+   * Called by mounted() and initializeIdentity()
   */
  private async checkRegistrationStatus() {
    if (!this.isRegistered && this.activeDid) {
@ -598,6 +642,9 @@ export default class HomeView extends Vue {
  /**
   * Initializes feed data
   * Triggers updateAllFeed() to populate activity feed
+   * 
+   * @internal
+   * Called by mounted()
   */
  private async loadFeedData() {
    await this.updateAllFeed();
@ -609,6 +656,9 @@ export default class HomeView extends Vue {
   * - Number of new direct offers
   * - Number of new project offers
   * - Rate limit status for both
+   * 
+   * @internal
+   * Called by mounted() and initializeIdentity()
   * @requires Active DID
   */
  private async loadNewOffers() {
@ -636,6 +686,9 @@ export default class HomeView extends Vue {
  /**
   * Checks if user needs onboarding
   * Opens onboarding dialog if not completed
+   * 
+   * @internal
+   * Called by mounted()
   */
  private async checkOnboarding() {
    const settings = await retrieveSettingsForActiveAccount();
@ -648,6 +701,9 @@ export default class HomeView extends Vue {
   * Handles errors during initialization
   * - Logs error to console and database
   * - Displays user notification
+   * 
+   * @internal
+   * Called by mounted() and handleFeedError()
   * @param err Error object with optional userMessage
   */
  private handleError(err: unknown) {
@ -667,6 +723,9 @@ export default class HomeView extends Vue {

  /**
   * Checks if feed results are being filtered
+   * 
+   * @public
+   * Used in template for filter button display
   * @returns true if visible or nearby filters are active
   */
  resultsAreFiltered() {
@ -675,6 +734,9 @@ export default class HomeView extends Vue {

  /**
   * Checks if browser notifications are supported
+   * 
+   * @public
+   * Used in template for notification feature detection
   * @returns true if Notification API is available
   */
  notificationsSupported() {
@ -686,6 +748,9 @@ export default class HomeView extends Vue {
   * - Updates filter states
   * - Clears existing feed data
   * - Triggers new feed load
+   * 
+   * @public
+   * Called by FeedFilters component when filters change
   */
  async reloadFeedOnChange() {
    const settings = await retrieveSettingsForActiveAccount();
@ -700,6 +765,9 @@ export default class HomeView extends Vue {

  /**
   * Loads more feed items for infinite scroll
+   * 
+   * @public
+   * Called by InfiniteScroll component when bottom is reached
   * @param payload Boolean indicating if more items should be loaded
   */
  async loadMoreGives(payload: boolean) {
@ -711,6 +779,15 @@ export default class HomeView extends Vue {
    }
  }

+  /**
+   * Checks if coordinates fall within any search box
+   * 
+   * @internal
+   * Called by shouldIncludeRecord() for location-based filtering
+   * @param lat Latitude to check
+   * @param long Longitude to check
+   * @returns true if coordinates are within any search box
+   */
  latLongInAnySearchBox(lat: number, long: number) {
    for (const boxInfo of this.searchBoxes) {
      if (
@ -729,6 +806,9 @@ export default class HomeView extends Vue {
   * - Handles filtering of results
   * - Updates last viewed claim ID
   * - Manages loading state
+   * 
+   * @public
+   * Called by loadMoreGives() and initializeIdentity()
   */
  async updateAllFeed() {
    this.isFeedLoading = true;
@ -754,6 +834,9 @@ export default class HomeView extends Vue {

  /**
   * Processes feed results and adds them to feedData
+   * 
+   * @internal
+   * Called by updateAllFeed()
   */
  private async processFeedResults(records: GiveSummaryRecord[]) {
    for (const record of records) {
@ -767,6 +850,9 @@ export default class HomeView extends Vue {

  /**
   * Processes a single record and returns it if it passes filters
+   * 
+   * @internal
+   * Called by processFeedResults()
   */
  private async processRecord(record: GiveSummaryRecord): Promise<GiveRecordWithContactInfo | null> {
    const claim = this.extractClaim(record);
@ -786,6 +872,9 @@ export default class HomeView extends Vue {

  /**
   * Extracts claim from record, handling both direct and wrapped claims
+   * 
+   * @internal
+   * Called by processRecord()
   */
  private extractClaim(record: GiveSummaryRecord) {
    // eslint-disable-next-line @typescript-eslint/no-explicit-any
@ -794,6 +883,9 @@ export default class HomeView extends Vue {

  /**
   * Extracts giver DID from claim
+   * 
+   * @internal
+   * Called by processRecord()
   */
  private extractGiverDid(claim: any) {
    // eslint-disable-next-line @typescript-eslint/no-explicit-any
@ -802,6 +894,9 @@ export default class HomeView extends Vue {

  /**
   * Extracts recipient DID from claim
+   * 
+   * @internal
+   * Called by processRecord()
   */
  private extractRecipientDid(claim: any) {
    // eslint-disable-next-line @typescript-eslint/no-explicit-any
@ -810,6 +905,9 @@ export default class HomeView extends Vue {

  /**
   * Gets fulfills plan from cache
+   * 
+   * @internal
+   * Called by processRecord()
   */
  private async getFulfillsPlan(record: GiveSummaryRecord) {
    return await getPlanFromCache(
@ -822,6 +920,9 @@ export default class HomeView extends Vue {

  /**
   * Checks if record should be included based on filters
+   * 
+   * @internal
+   * Called by processRecord()
   */
  private shouldIncludeRecord(record: GiveSummaryRecord, fulfillsPlan: any): boolean {
    if (!this.isAnyFeedFilterOn) {
@ -844,6 +945,9 @@ export default class HomeView extends Vue {

  /**
   * Extracts provider from claim
+   * 
+   * @internal
+   * Called by processRecord()
   */
  private extractProvider(claim: any) {
    return Array.isArray(claim.provider) ? claim.provider[0] : claim.provider;
@ -851,6 +955,9 @@ export default class HomeView extends Vue {

  /**
   * Gets provided by plan from cache
+   * 
+   * @internal
+   * Called by processRecord()
   */
  private async getProvidedByPlan(provider: any) {
    return await getPlanFromCache(
@ -863,6 +970,9 @@ export default class HomeView extends Vue {

  /**
   * Creates a feed record with contact info
+   * 
+   * @internal
+   * Called by processRecord()
   */
  private createFeedRecord(
    record: GiveSummaryRecord,
@ -908,6 +1018,9 @@ export default class HomeView extends Vue {

  /**
   * Updates the last viewed claim ID in settings
+   * 
+   * @internal
+   * Called by updateAllFeed()
   */
  private async updateFeedLastViewedId(records: GiveSummaryRecord[]) {
    if (
@ -923,6 +1036,9 @@ export default class HomeView extends Vue {

  /**
   * Handles feed error and shows notification
+   * 
+   * @internal
+   * Called by updateAllFeed()
   */
  private handleFeedError(e: any) {
    logger.error("Error with feed load:", e);
@ -940,8 +1056,11 @@ export default class HomeView extends Vue {
  /**
   * Retrieve claims in reverse chronological order
   * 
-   * @param beforeId the earliest ID (of previous searches) to search earlier
-   * @return claims in reverse chronological order
+   * @internal
+   * Called by updateAllFeed()
+   * @param endorserApiServer API server URL
+   * @param beforeId OptioCalled by updateAllFeed()nal ID to fetch earlier results
+   * @returns claims in reverse chronological order
   */
  async retrieveGives(endorserApiServer: string, beforeId?: string) {
    const beforeQuery = beforeId == null ? "" : "&beforeId=" + beforeId;
@ -974,6 +1093,14 @@ export default class HomeView extends Vue {
    }
  }

+  /**
+   * Formats gift description with giver and recipient info
+   * 
+   * @public
+   * Used in template for displaying gift descriptions
+   * @param giveRecord Record containing gift information
+   * @returns formatted description string
+   */
  giveDescription(giveRecord: GiveRecordWithContactInfo) {
    // similar code is in endorser-mobile utility.ts
    // claim.claim happen for some claims wrapped in a Verifiable Credential
@ -1054,10 +1181,23 @@ export default class HomeView extends Vue {
    }
  }

+  /**
+   * Navigates to activity page
+   * 
+   * @public
+   * Called by template click handler
+   */
  goToActivityToUserPage() {
    this.$router.push({ name: "new-activity" });
  }

+  /**
+   * Navigates to claim details page
+   * 
+   * @public
+   * Called by ActivityListItem component
+   * @param jwtId ID of the claim to view
+   */
  onClickLoadClaim(jwtId: string) {
    const route = {
      path: "/claim/" + encodeURIComponent(jwtId),
@ -1065,16 +1205,31 @@ export default class HomeView extends Vue {
    this.$router.push(route);
  }

+  /**
+   * Formats amount with currency code
+   * 
+   * @internal
+   * Called by giveDescription()
+   */
  displayAmount(code: string, amt: number) {
    return "" + amt + " " + this.currencyShortWordForCode(code, amt === 1);
  }

+  /**
+   * Gets currency word based on code and plurality
+   * 
+   * @internal
+   * Called by displayAmount()
+   */
  currencyShortWordForCode(unitCode: string, single: boolean) {
    return unitCode === "HUR" ? (single ? "hour" : "hours") : unitCode;
  }

  /**
   * Opens dialog for creating new gift/claim
+   * 
+   * @public
+   * Called by template and openGiftedPrompts()
   * @param giver Optional contact info for giver
   * @param description Optional gift description
   */
@ -1093,7 +1248,9 @@ export default class HomeView extends Vue {

  /**
   * Opens prompts for gift ideas
-   * Links to openDialog for selected prompt
+   * 
+   * @public
+   * Called by template click handler
   */
  openGiftedPrompts() {
    (this.$refs.giftedPrompts as GiftedPrompts).open((giver, description) =>
@ -1103,12 +1260,21 @@ export default class HomeView extends Vue {

  /**
   * Opens feed filter configuration
-   * @param reloadFeedOnChange Callback for when filters are updated
+   * 
+   * @public
+   * Called by template click handler
   */
  openFeedFilters() {
    (this.$refs.feedFilters as FeedFilters).open(this.reloadFeedOnChange);
  }

+  /**
+   * Shows toast notification to user
+   * 
+   * @internal
+   * Used for various user notifications
+   * @param message Message to display
+   */
  toastUser(message: string) {
    this.$notify(
      {
@ -1121,10 +1287,24 @@ export default class HomeView extends Vue {
    );
  }

+  /**
+   * Computes CSS classes for known person icons
+   * 
+   * @public
+   * Used in template for icon styling
+   * @param known Whether the person is known
+   * @returns CSS class string
+   */
  computeKnownPersonIconStyleClassNames(known: boolean) {
    return known ? "text-slate-500" : "text-slate-100";
  }

+  /**
+   * Shows name input dialog if needed
+   * 
+   * @public
+   * Called by template click handler
+   */
  showNameThenIdDialog() {
    if (!this.givenName) {
      (this.$refs.userNameDialog as UserNameDialog).open(() => {
@ -1135,6 +1315,12 @@ export default class HomeView extends Vue {
    }
  }

+  /**
+   * Shows dialog for sharing method selection
+   * 
+   * @internal
+   * Called by showNameThenIdDialog()
+   */
  promptForShareMethod() {
    (this.$refs.choiceButtonDialog as ChoiceButtonDialog).open({
      title: "How can you share your info?",
@ -1154,6 +1340,14 @@ export default class HomeView extends Vue {
    });
  }

+  /**
+   * Caches image data for sharing
+   * 
+   * @public
+   * Called by ActivityListItem component
+   * @param event Event object
+   * @param imageUrl URL of image to cache
+   */
  async cacheImageData(event: Event, imageUrl: string) {
    try {
      // For images that might fail CORS, just store the URL
@ -1164,12 +1358,26 @@ export default class HomeView extends Vue {
    }
  }

+  /**
+   * Opens image viewer dialog
+   * 
+   * @public
+   * Called by ActivityListItem component
+   * @param imageUrl URL of image to display
+   */
  async openImageViewer(imageUrl: string) {
    this.selectedImageData = this.imageCache.get(imageUrl) ?? null;
    this.selectedImage = imageUrl;
    this.isImageViewerOpen = true;
  }

+  /**
+   * Handles claim confirmation
+   * 
+   * @public
+   * Called by ActivityListItem component
+   * @param record Record to confirm
+   */
  async confirmClaim(record: GiveRecordWithContactInfo) {
    this.$notify(
      {
--- a/test-playwright/test-playwright/test-results/.last-run.json
+++ b/test-playwright/test-playwright/test-results/.last-run.json
@ -0,0 +1,4 @@
+{
+  "status": "failed",
+  "failedTests": []
+}
--- a/test-playwright/test-results/.last-run.json
+++ b/test-playwright/test-results/.last-run.json
@ -0,0 +1,29 @@
+{
+  "status": "failed",
+  "failedTests": [
+    "a29eb57667e0fb28c7e9-7a80e551e7f16a766d0d",
+    "a29eb57667e0fb28c7e9-1a8c76601bb6ea4f735c",
+    "a29eb57667e0fb28c7e9-0a3670fa77fcd5ac9827",
+    "a29eb57667e0fb28c7e9-90c8866cf70c7f96647d",
+    "a29eb57667e0fb28c7e9-4abc584edcf7a6a12389",
+    "a29eb57667e0fb28c7e9-3b443656a23fd8e7eb76",
+    "a29eb57667e0fb28c7e9-1f63cf7a41b756ffe01f",
+    "a29eb57667e0fb28c7e9-4eb03633761e58eac0a4",
+    "db48a48c514e3e2940e5-cef25040a0b285eed2ba",
+    "1c818805c9b0ac973736-726f18ba6163d57238c8",
+    "c52ae54d86eda05904f3-adf7525a07e75f4e3cc2",
+    "2fac21b9c9c3eb062631-9d2d2e9a199603c11b9b",
+    "64242279fe0133650483-20fbacc4e45c5561df6c",
+    "a7ff64a290be94f9d82c-e26ceb13031dafad1133",
+    "868977083268005e6ec0-c27d226d34e20ba4863d",
+    "5e149db5da4a5e319bcc-3298c84d0ebfff5e6d7c",
+    "5e149db5da4a5e319bcc-1981ba81641b6000f80b",
+    "2b5f6d3352de2040032d-bf5ed3a9483d90c396dd",
+    "2b5f6d3352de2040032d-6f52c3699c55c19ccad8",
+    "2b5f6d3352de2040032d-0f478a3208f64651daa1",
+    "2b5f6d3352de2040032d-a05f542cad739ee3b5b9",
+    "955bdfdfe05b442c0f5d-a9ec2b8bc7bd90ea0439",
+    "955bdfdfe05b442c0f5d-2c38171f673436923a8b",
+    "1a1fd29d3f0573e705e6-a3a6805908fe9a29ab11"
+  ]
+}