@lovebowls/leagueelements/src/elements/LeagueMatchesAttention/ai_module_summary.md

League Elements package for LoveBowls

## AI Module Summary: LeagueMatchesAttention

### 1. Module Name

`LeagueMatchesAttention`

### 2. Purpose and Business Logic

The `LeagueMatchesAttention` module is a frontend custom element designed to display a filtered list of matches that require immediate user attention. This typically includes matches with overdue results, scheduling conflicts, future results entered prematurely, or matches without a scheduled date.

Its business logic is to prioritize and highlight matches needing action from the user, improving administrative efficiency and data integrity by drawing focus to potential issues or pending tasks.

### 3. Working Logic

`LeagueMatchesAttention` operates as a self-contained Custom HTML Element. Its core responsibilities involve receiving match data, filtering and sorting it based on predefined 'attention' criteria, handling pagination for the filtered list, and rendering the list for display.

-   **Data Handling:** Receives an array of match objects via the `data` attribute and a mapping of team IDs to display names via the `team-mapping` attribute. It parses this input and stores it internally (`this.matches`, `this.teamMapping`). It also observes the `is-mobile` attribute to adjust rendering if needed.
-   **Filtering and Sorting:** The `_getMatchesRequiringAttention` method filters the `this.matches` array to identify matches that meet specific criteria (e.g., past date with no result, future date with result, scheduling conflicts detected by `_getConflictingMatchKeys`, no date/result). It then sorts these attention-required matches based on a priority system (conflicts highest, then past pending, no date, future result).
-   **Pagination:** Implements basic pagination to display a subset of the filtered matches per page (`this.currentPage`, `this.itemsPerPage`, `_hasNextPage`, `setPage` methods). The rendered output (`renderAttentionMatches`) shows only the current page's items.
-   **Rendering:** The `render` method generates the HTML structure using a template (`TEMPLATE`) and styles (based on `is-mobile`). It injects the list of attention matches rendered by `renderAttentionMatches` and includes pagination controls.
-   **User Interaction:** Sets up event listeners (`setupEventListeners`) primarily to handle clicks on pagination buttons (`#attention-prev`, `#attention-next`) to change the `currentPage` and trigger a re-render. It also dispatches a `league-matches-attention-event` with `type: 'matchClick'` when a match item is clicked, including the clicked `match` object in the detail.
-   **Team Display:** Uses the provided `teamMapping` to display team names instead of just IDs in the match list (`getTeamDisplayName`).

### 4. File and Folder Structure

The module is located at `/c:/lb/dev/leagueElements/src/elements/LeagueMatchesAttention`. The primary files analyzed are:

-   `leagueElements/src/elements/LeagueMatchesAttention/LeagueMatchesAttention.js`: Contains the main class definition and logic for the custom element.
-   `leagueElements/src/elements/LeagueMatchesAttention/LeagueMatchesAttention-styles.js`: Contains the CSS styles for the component, including specific styles for match items, paging, and attention icons, importing shared styles.
-   `leagueElements/src/elements/LeagueMatchesAttention/ai_module_update.md`: Instructions for this analysis.

Relevant files imported:

-   `../shared-styles.js` (for base panel, button, list item, and mobile styles)

### 5. Database Table Structure

Based on the `match` data structure consumed by this component (which includes fields like `key`, `date`, `homeTeam` (with `_id` and `name`), `awayTeam` (with `_id` and `name`), and `result` (with `homeScore`, `awayScore`)), the backend database likely includes a table or collection for Matches with at least these fields. The presence of team `_id` and `name` in the match object suggests either embedding or a clear relationship to a Teams collection. The calculation of scheduling conflicts relies on match dates and participating teams.

*   **Note:** This is an inference based on frontend data structures. Confirmation requires analyzing backend migration files or ORM models.

### 6. Tech Stack and Library Versions

-   **Frontend:** Custom Elements API, JavaScript (ES6+), HTML, CSS.
-   **Styling:** Relies on shared CSS variables and classes imported via `../shared-styles.js` and module-specific styles.
-   **Date/Time Handling:** Uses standard JavaScript `Date` objects and `getTime()` for date comparisons (implicitly involving system time/timezone). Does not directly use `TemporalUtils` but processes date strings that might originate from a system using Temporal or similar.
-   **Component Interaction:** Designed to be a child component, receiving data via attributes and communicating user actions (match clicks) via custom events (`league-matches-attention-event`).

*   **Information Needed:** Specific versions of any major frontend frameworks (if used in the wider project) or backend technologies.

### 7. Architecture and Code Organization Style

-   **Architecture:** Frontend is built as a self-contained Web Component (`LeagueMatchesAttention`) extending `HTMLElement`. It uses Shadow DOM for encapsulation.
-   **Code Organization:** Follows a class-based structure with methods logically grouped by functionality (data loading, filtering/sorting, rendering, event handling, pagination). Styles are separated.

### 8. Module Routes

This module is a frontend custom element and does not define its own application routes. It is intended to be embedded within a larger application page or component that manages routing. The component receives the relevant attention matches data via an attribute, which would be populated by the parent application, likely after fetching data for the currently viewed league.

### 9. Controllers and their Meaning

As a frontend component, this module does not contain backend controllers. It consumes match data provided by a parent component. The data is likely fetched from a backend API via controllers responsible for retrieving league and match information, including identifying matches that meet the 'attention' criteria (though the filtering/sorting logic for display is handled client-side within this component).

User actions from this component (like clicking a match) are communicated via custom events, which a parent component would handle, potentially triggering a different UI action (e.g., opening a match edit modal) or a backend interaction.

### 10. Module Services and their Logic

Similar to controllers, this frontend module does not contain backend services. It relies on backend services consumed by the parent application to provide the raw match data. The logic for identifying which matches require attention and sorting them is primarily implemented client-side within this component (`_getMatchesRequiringAttention`). Backend services would be responsible for the source data retrieval and potentially for calculating/providing the raw match data used by this component.

### 11. Interaction with Other Modules

-   **Frontend:**
    *   Uses shared styles (`../shared-styles.js`).
    *   Communicates with its parent component/application by dispatching `league-matches-attention-event` (for `dataLoaded` and `matchClick`).
    *   It is likely embedded within components like `leagueElement` or `leagueAdminElement` to display attention matches for a specific league.
-   **Backend:**
    *   Interacts *indirectly* by receiving match data via attributes populated by the parent application, which obtains this data from backend services/controllers.