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

League Elements package for LoveBowls

## AI Module Summary: leagueMatch

### 1. Module Name

`leagueMatch`

### 2. Purpose and Business Logic

The primary purpose of the `leagueMatch` module is to provide a modal dialog interface for creating and updating match entries. It allows users to select home and away teams, set the match date, and optionally enter the match scores if the match has been played.

It solves the business problem of providing a dedicated, user-friendly form for managing individual match details within the league management system.

### 3. Working Logic

`leagueMatch` is implemented as a Custom HTML Element (`<league-match>`). Its core logic involves displaying a modal form, populating it with data, capturing user input, validating that input, and signaling save or cancel actions to a parent component via custom events.

-   **Data Handling:** The modal receives match data (`this.match`), a list of available teams (`this.teams`), its open state (`this.open`), device type (`this.isMobile`), and operation mode (`this.mode`) via properties and observed attributes. It parses and uses this data to populate the form fields. It collects user input from the form.
-   **Rendering:** The `render` method generates the modal's HTML structure, including form fields for teams, date, scores, and action buttons (OK/Cancel). It dynamically populates team dropdowns based on the `this.teams` data and pre-fills fields if the `this.match` property is set (in 'edit' mode).
-   **User Interaction:** It handles user interactions within the modal, such as selecting teams, entering date and scores, checking the 'Is Played' checkbox, and clicking the OK or Cancel buttons. It also includes logic for focus trapping within the modal when open.
-   **Validation:** The `_onOk` method performs basic validation on the form inputs (e.g., ensuring teams are selected, teams are different, date is entered, scores are numbers if played) and displays error messages using `showError` if validation fails.
-   **Event Dispatch:** Upon successful validation of the form data when the OK button is clicked, it dispatches a `match-save` custom event containing the collected match data (`match` object) in the event detail. The Cancel button dispatches a `match-cancel` event. These events signal to the parent component that an action has been taken and pass the relevant data.
-   **Modal State:** The element manages its visibility based on the `open` attribute/property. It also adjusts its appearance based on the `is-mobile` attribute.

### 4. File and Folder Structure

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

-   `leagueElements/src/elements/leagueMatch/leagueMatch.js`: Contains the main class definition and logic for the custom element.
-   `leagueElements/src/elements/leagueMatch/leagueMatch-styles.js`: Contains the CSS styles for the modal and its form elements, importing shared styles.
-   `leagueElements/src/elements/leagueMatch/ai_module_update.md`: Instructions for this analysis.

### 5. Database Table Structure

Based on the data handled by this modal (the `match` object structure passed via the `match-save` event), the backend database likely has a structure to store match information. This would include fields for:

-   A unique identifier (e.g., `key` or `_id`).
-   The match `date`.
-   References to the `homeTeam` and `awayTeam`, likely via their unique identifiers (`_id`), and possibly storing their names for convenience.
-   An optional `result` object, containing `homeScore` and `awayScore` (or similar fields).
-   Potentially other metadata not visible in this modal (e.g., league ID).)

*   **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:** Utilizes shared CSS variables and classes imported into `leagueMatch-styles.js` from `../shared-styles.js`.
-   **Component Interaction:** Designed to be used as a child component, receiving data via attributes/properties and communicating actions via custom events (`match-save`, `match-cancel`).

*   **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 (`LeagueMatch`) extending `HTMLElement`, designed specifically as a modal dialog. It uses Shadow DOM for encapsulation.
-   **Code Organization:** Follows a class-based structure with methods for handling attribute/property changes, rendering, user input handling, validation, and event dispatching. Styles are separated into a dedicated file and leverage shared modal and form styles.

### 8. Module Routes

This module is a frontend custom element and does not define its own application routes. As a modal, it is typically displayed and managed by a parent component or a routing mechanism in the main application when a user action (like clicking 'Add Match' or 'Edit Match') triggers its visibility.

### 9. Controllers and their Meaning

As a frontend modal component, this module does not contain backend controllers. It provides the UI for capturing match data. The data collected by this modal is intended to be sent to the backend via API calls initiated by a parent component that listens for the `match-save` event. Backend controllers would be responsible for receiving this data, validating it server-side, and persisting it to the database.

### 10. Module Services and their Logic

Similar to controllers, this frontend module does not contain backend services. It provides the data payload (the match object) via the `match-save` event. Backend services would be consumed by the parent application to handle the business logic associated with creating or updating a match, including data validation, database interaction, and potentially recalculating league standings after a result is entered.

### 11. Interaction with Other Modules

-   **Frontend:**
    *   Relies on shared styles (`../shared-styles.js`) for its appearance and layout as a modal and form.
    *   Communicates with its parent component/application by dispatching `match-save` and `match-cancel` custom events.
    *   It is likely used by components like `leagueAdminElement` (for adding/editing matches in administration) and potentially `leagueElement` (for entering results via the table or match lists).
-   **Backend:**
    *   Interacts *indirectly* with backend services and controllers by providing data via the `match-save` event, which a parent component uses to trigger backend API calls for data persistence.
    *   Receives initial match data (in edit mode) and the list of teams from a parent component, which obtains this data from the backend.