Add README files to all directories

generated by LLM

src/README.md

@@ -0,0 +1,36 @@
+# Source Directory (`src`)
+
+This directory contains the main source code for the Topola Viewer application. It includes the application entry point, main layout components, chart rendering logic, data source adapters, menus, side panel, translations, and utilities.
+
+## Subdirectories
+
+*   **[datasource](datasource)**: Implements data sources for loading GEDCOM files, URLs, WikiTree API data, and embedded data.
+*   **[menu](menu)**: Contains components for the top navigation bar, search bar, and various menus (upload, URL, WikiTree).
+*   **[sidepanel](sidepanel)**: Contains components for the side panel, which shows individual details and chart configuration settings.
+*   **[translations](translations)**: Contains JSON files with translations for supported languages.
+*   **[util](util)**: Contains utility functions for dates, GEDCOM data, analytics, and responsive design.
+
+## Files
+
+*   **[app.tsx](app.tsx)**: The main application component that manages state, routing, data loading orchestration, and high-level layout.
+*   **[changelog.tsx](changelog.tsx)**: Component that fetches and displays the recent changes in a modal dialog when the app is updated.
+*   **[chart.tsx](chart.tsx)**: The primary chart rendering component using D3 and the `topola` library. It handles zoom, pan, and export actions.
+*   **[donatso-chart.tsx](donatso-chart.tsx)**: An alternative chart view utilizing the `family-chart` library.
+*   **[index.tsx](index.tsx)**: The entry point of the application. It sets up polyfills, internationalization, and renders the app root.
+*   **[intro.tsx](intro.tsx)**: The landing page component shown when no data is loaded. It provides instructions, examples, and privacy information.
+
+## Assets
+
+*   **[index.css](index.css)**: Global CSS styles for the application.
+*   **[topola.jpg](topola.jpg)**: Image asset for the Topola logo.
+
+## Type Definitions
+
+*   **[family-chart.d.ts](family-chart.d.ts)**: Type definitions for the `family-chart` library.
+*   **[imports.d.ts](imports.d.ts)**: Type definitions for non-code assets (e.g., CSS imports).
+*   **[javascript-natural-sort.d.ts](javascript-natural-sort.d.ts)**: Type definitions for the `javascript-natural-sort` library.
+*   **[lunr-languages.d.ts](lunr-languages.d.ts)**: Type definitions for `lunr-languages` plugins.
+*   **[parse-gedcom.d.ts](parse-gedcom.d.ts)**: Type definitions for the `parse-gedcom` library.
+*   **[react-app-env.d.ts](react-app-env.d.ts)**: Type definitions for React application environment.
+*   **[react-linkify.d.ts](react-linkify.d.ts)**: Type definitions for the `react-linkify` library.
+*   **[vite-env.d.ts](vite-env.d.ts)**: Type definitions for Vite environment variables.

src/datasource/README.md

@@ -0,0 +1,19 @@
+# Data Sources
+
+This directory contains the implementation of various data sources supported by Topola Viewer. It handles loading genealogical data from different origins and transforming it into a unified format used by the application.
+
+## Purpose
+
+The main purpose of this directory is to abstract away the details of where the genealogical data comes from. Whether it is a file uploaded by the user, a URL pointing to a GEDCOM file, data fetched from the WikiTree API, or data received from a parent window in embedded mode, this directory provides a consistent interface ([DataSource](data_source.ts#L19)) to the rest of the application.
+
+## Files
+
+- [data_source.ts](data_source.ts): Defines the core abstractions for data sources, including the [DataSourceEnum](data_source.ts#L5) and the [DataSource](data_source.ts#L19) interface.
+- [load_data.ts](load_data.ts): Contains helper functions for loading data from files and URLs, handling zip files (GEDZIP), and implements [UploadedDataSource](load_data.ts#L155) and [GedcomUrlDataSource](load_data.ts#L195).
+- [embedded.ts](embedded.ts): Implements [EmbeddedDataSource](embedded.ts#L34) for cases where the viewer is embedded in an iframe and receives GEDCOM data via window messages.
+- [gedcom_generator.ts](gedcom_generator.ts): Used to create a GEDCOM structure from internal JSON data. This is primarily used to generate a GEDCOM representation for data sources that do not natively provide it (like WikiTree), which is needed for the details panel.
+- [wikitree.ts](wikitree.ts): Implements [WikiTreeDataSource](wikitree.ts#L62) and serves as the main entry point for loading data from WikiTree.
+- [wikitree_api.ts](wikitree_api.ts): Handles the actual communication with the WikiTree API using the `wikitree-js` library, including caching and handling private profiles.
+- [wikitree_transformer.ts](wikitree_transformer.ts): Transforms data fetched from the WikiTree API into Topola's internal data format.
+- [load_data.spec.ts](load_data.spec.ts): Unit tests for the data loading functions in `load_data.ts`.
+- `testdata/`: A directory containing test files used by the unit tests.

src/menu/README.md

@@ -0,0 +1,14 @@
+# Menu Directory
+
+This directory contains React components that make up the top navigation bar and its associated menus and dialogs in Topola Viewer. It handles loading data from various sources, searching for individuals, and changing chart views.
+
+## Files
+
+- [menu_item.tsx](menu_item.tsx): A utility component that renders as either a `Menu.Item` or a `Dropdown.Item` from `semantic-ui-react`, allowing menu items to be shared between desktop and mobile layouts.
+- [search.tsx](search.tsx): The `SearchBar` component displayed in the top bar. It handles user input and displays search results.
+- [search_index.ts](search_index.ts): Implements the search index using the `lunr` library. It creates a searchable index of individuals from the loaded genealogy data, supporting multilingual search and character normalization.
+- [top_bar.tsx](top_bar.tsx): The main component for the application's top navigation bar. It handles responsive design for small and large screens and aggregates all the menus and the search bar.
+- [upload_menu.tsx](upload_menu.tsx): The "Open file" menu item. It allows users to upload local GEDCOM files and images.
+- [url_menu.tsx](url_menu.tsx): The "Load from URL" menu item and modal dialog. It allows users to load data from a URL, using a proxy to avoid CORS issues.
+- [wikitree_menu.tsx](wikitree_menu.tsx): Menu items and modal dialogs for WikiTree integration, including loading by WikiTree ID and logging in.
+- [wikitree.png](wikitree.png): Image asset for the WikiTree logo used in the menus.

src/sidepanel/README.md

@@ -0,0 +1,18 @@
+# Side Panel Directory
+
+This directory contains components and logic for the side panel of the Topola Viewer application. The side panel is used to display detailed information about a selected individual and to configure chart settings.
+
+## Purpose
+
+The purpose of this directory is to provide a collapsible side panel that offers:
+1.  **Detailed Information**: Displays comprehensive data about a selected person, including their name, images, events, facts, notes, and sources, extracted from the loaded GEDCOM file.
+2.  **Chart Configuration**: Provides controls for users to customize the appearance of the genealogical chart (e.g., color schemes, showing/hiding IDs, and sex indicators).
+
+This directory acts as a container for these features, organizing them into specific subdirectories:
+- **[config](config/)**: Contains the UI and logic for managing chart display settings.
+- **[details](details/)**: Contains components for rendering the detailed view of an individual's data.
+- **[head](head/)**: Contains components to display metadata from the GEDCOM file header.
+
+## Files in this Directory
+
+- [side-panel.tsx](side-panel.tsx): The main React component that implements the side panel. It manages the layout, switching between expanded and collapsed states. When expanded, it displays a tabbed interface with "Info" (details) and "Settings" (configuration) panes. When collapsed in a mobile view, it shows a minimal view of the selected person's name. It also includes the button to toggle the panel's expanded state.

src/sidepanel/config/README.md

@@ -0,0 +1,20 @@
+# Chart Configuration
+
+This directory contains the logic and UI for configuring the display of the genealogical chart.
+
+## Purpose
+
+The purpose of this directory is to manage the user-configurable settings for the chart visualization. This includes:
+- **Colors**: How individuals in the chart are colored (none, by generation, or by sex).
+- **IDs**: Whether to show or hide person IDs.
+- **Sex**: Whether to show or hide indicators for sex.
+
+It provides the data structures for the configuration, default values, functions to serialize/deserialize the configuration to/from URL query parameters, and the UI component for the side panel.
+
+## Files
+
+- [config.tsx](config.tsx): The main file containing:
+  - `ChartColors`, `Ids`, and `Sex` enums defining the available options.
+  - `Config` interface defining the configuration state.
+  - `argsToConfig` and `configToArgs` functions for mapping the configuration to and from URL query arguments.
+  - `ConfigPanel` React component providing the UI controls (radio buttons) for these settings in the side panel.

src/sidepanel/details/README.md

@@ -0,0 +1,16 @@
+# Details Directory
+
+This directory contains React components for displaying detailed information about a selected individual (person) in the side panel of the Topola Viewer application. The details are extracted from a parsed GEDCOM file.
+
+## Files
+
+- [additional-files.tsx](additional-files.tsx): Displays a list of links to non-image files associated with an entry.
+- [collapsed-details.tsx](collapsed-details.tsx): Displays a minimal, vertical view of details (person's name) when the side panel is collapsed.
+- [details.tsx](details.tsx): The main component that orchestrates the display of all details for an individual, including name, images, events, facts, notes, and sources.
+- [event-extras.tsx](event-extras.tsx): Displays additional content for events (images, notes, sources, files) in a tabbed interface.
+- [events.tsx](events.tsx): Handles the logic and display for all events related to an individual, sorting them by date and grouping them by life stages.
+- [linkify-new-tab.tsx](linkify-new-tab.tsx): A helper component that wraps content and makes URLs clickable, opening them in a new tab.
+- [multiline-text.tsx](multiline-text.tsx): Helper component to display multi-line text with linkified URLs.
+- [sources.tsx](sources.tsx): Displays a list of sources cited for an entry.
+- [translated-tag.tsx](translated-tag.tsx): Component to translate GEDCOM tags into human-readable labels.
+- [wrapped-image.tsx](wrapped-image.tsx): Component to display images with loading placeholders, error fallback, and a click-to-enlarge modal.

src/sidepanel/head/README.md

@@ -0,0 +1,16 @@
+# Head Directory
+
+This directory contains components responsible for displaying information from the header of the loaded GEDCOM file in the side panel.
+
+## Files
+
+### [head.tsx](head.tsx)
+
+Defines the `SourceHead` component. This component displays metadata about the data source, extracted from the GEDCOM header (`HEAD` record). It includes information such as:
+- The software name that generated the file (`SOUR`)
+- File creation date (`DATE`)
+- Original file name (`FILE`)
+- Submitter's name and contact details (phone, email, address) (`SUBM`)
+- Copyright information (`COPR`)
+
+The component conditionally renders these details only if they are present in the data.

src/translations/README.md

@@ -0,0 +1,19 @@
+# Translations
+
+This directory contains translation files for the Topola Viewer application. These files are used to support multiple languages in the user interface.
+
+## Files
+
+Each file in this directory corresponds to a specific language and contains a JSON object with translation keys and their corresponding localized strings.
+
+*   [bg.json](bg.json): Bulgarian translations.
+*   [cs.json](cs.json): Czech translations.
+*   [de.json](de.json): German translations.
+*   [fr.json](fr.json): French translations.
+*   [it.json](it.json): Italian translations.
+*   [pl.json](pl.json): Polish translations.
+*   [ru.json](ru.json): Russian translations.
+
+## Usage
+
+These files are loaded by the internationalization (i18n) framework used in the project to display the UI in the user's preferred language. English strings are used as defaults directly in the source code. The translation json files are loaded in [../index.tsx](src/index.tsx).

src/util/README.md

@@ -0,0 +1,17 @@
+# Utilities (`src/util`)
+
+This directory contains various utility functions, hooks, and classes used across the application. These utilities handle date calculations, GEDCOM data processing, internationalization of errors, analytics, and responsive design setup.
+
+## Files
+
+- **[age_util.ts](age_util.ts)**: Utilities for calculating and formatting age based on birth and death dates. It handles exact dates, ranges, and qualifiers, and supports localization.
+- **[age_util.spec.ts](age_util.spec.ts)**: Unit tests for `age_util.ts`.
+- **[analytics.ts](analytics.ts)**: Provides the `analyticsEvent` function to send events to Google Analytics using `gtag`.
+- **[analytics_noop.ts](analytics_noop.ts)**: A no-op implementation of `analyticsEvent`, used when analytics are disabled.
+- **[date_util.ts](date_util.ts)**: Utilities for formatting and comparing dates, handling `DateOrRange` objects from the `topola` library, and supporting localization.
+- **[error.ts](error.ts)**: Defines the `TopolaError` class, extending `Error` to include an error code and arguments used for internationalized error messages.
+- **[error_i18n.ts](error_i18n.ts)**: Provides `getI18nMessage` to return translated messages for `TopolaError` instances.
+- **[gedcom_util.ts](gedcom_util.ts)**: A comprehensive utility file for handling GEDCOM data. It includes functions for parsing and converting GEDCOM files, normalizing data (sorting children and spouses), dereferencing entries, and extracting specific data like names and sources.
+- **[gedcom_util.spec.ts](gedcom_util.spec.ts)**: Unit tests for `gedcom_util.ts`.
+- **[media.ts](media.ts)**: Sets up responsive design breakpoints (small and large) using the `@artsy/fresnel` library.
+- **[previous-hook.ts](previous-hook.ts)**: A custom React hook (`usePrevious`) that returns the value of a variable from the previous render.