Add README files to all directories

generated by LLM

.github/workflows/README.md

@@ -0,0 +1,11 @@
+# GitHub Workflows
+
+This directory contains GitHub Actions workflow files that automate various tasks for the project, such as continuous integration (CI), security analysis, and deployment.
+
+## Files
+
+- [codeql-analysis.yml](file:///home/pwiech/personal/github/topola-viewer/.github/workflows/codeql-analysis.yml): Performs CodeQL security analysis on the codebase to identify potential vulnerabilities.
+- [deploy-everywhere.yml](file:///home/pwiech/personal/github/topola-viewer/.github/workflows/deploy-everywhere.yml): A manually triggered workflow that initiates deployment to both GitHub Pages and WikiTree Apps by calling their respective workflow files.
+- [deploy-gh-pages.yml](file:///home/pwiech/personal/github/topola-viewer/.github/workflows/deploy-gh-pages.yml): Handles the deployment of the application to GitHub Pages.
+- [deploy-wikitree-apps.yml](file:///home/pwiech/personal/github/topola-viewer/.github/workflows/deploy-wikitree-apps.yml): Manages the deployment of the application to WikiTree Apps using SFTP.
+- [node.js.yml](file:///home/pwiech/personal/github/topola-viewer/.github/workflows/node.js.yml): The main Continuous Integration (CI) workflow. It installs dependencies, checks formatting, lints, builds, and runs tests across multiple Node.js versions.

PROJECT_STRUCTURE.md

@@ -0,0 +1,52 @@
+# Project Structure
+
+This directory is the root directory of the **Topola Genealogy Viewer** project. It serves as the central hub containing project configuration, build setup, dependency management, and the main entry points for development, testing, and deployment. The actual application source code, assets, and tests are organized into subdirectories.
+
+## Purpose of this Directory
+
+The root directory orchestrates the project. It contains configuration files for various tools (Vite, ESLint, Jest, Cypress, TypeScript), metadata about dependencies (`package.json`), and scripts for common tasks. It glues together the source code in `src`, the static assets in `public`, and the tests in `cypress`.
+
+## Files in this Directory (Categorized by Role)
+
+Here is an enumeration of the files in this directory, categorized by their role in the project:
+
+### Application Entry Point
+*   **[index.html](index.html)**: The main HTML entry point for the application.
+
+### Build & Environment
+*   **[.env](.env)**: Contains environment variables for the project.
+*   **[vite.config.mts](vite.config.mts)**: Configuration file for the Vite build tool.
+
+### Dependencies & Scripts
+*   **[package.json](package.json)**: Defines the project's dependencies, scripts, version, and other metadata.
+*   **[package-lock.json](package-lock.json)**: Automatically generated file that describes the exact dependency tree that was generated by npm.
+*   **[deploy-wikitree.sh](deploy-wikitree.sh)**: A shell script used to deploy the application files to WikiTree servers using `lftp`.
+
+### Tool Configuration
+*   **[.eslintrc.js](.eslintrc.js)**: Configuration file for ESLint, used for identifying and reporting on patterns in JavaScript/TypeScript code.
+*   **[.gitignore](.gitignore)**: Specifies files and directories that should be ignored by Git.
+*   **[prettier.config.mjs](prettier.config.mjs)**: Configuration for Prettier code formatter.
+*   **[tsconfig.json](tsconfig.json)**: Configuration file for the TypeScript compiler.
+
+### Testing
+*   **[cypress.config.ts](cypress.config.ts)**: Configuration file for Cypress end-to-end testing framework.
+*   **[jest.config.ts](jest.config.ts)**: Configuration file for the Jest testing framework used for unit tests.
+
+### Documentation & Assets
+*   **[README.md](README.md)**: The main project documentation, covering features, examples, and usage instructions.
+*   **[CHANGELOG.md](CHANGELOG.md)**: Records a log of notable changes made to the project over time.
+*   **[LICENSE](LICENSE)**: The license file for the project (Apache License 2.0).
+*   **[screenshot.png](screenshot.png)**: An image showing a screenshot of the application, used in the README.md.
+
+## Subdirectories Overview
+
+Based on the documentation in the subdirectories, here is a high-level overview of the project's structure:
+
+*   **[src](src)**: The core of the application.
+    *   **[datasource](src/datasource)**: Handles loading and transforming genealogical data from various sources (files, URLs, WikiTree).
+    *   **[menu](src/menu)**: Contains navigation and menu components.
+    *   **[sidepanel](src/sidepanel)**: Implements the side panel for details and configuration.
+    *   **[translations](src/translations)**: Holds localization JSON files.
+    *   **[util](src/util)**: Common utilities for dates, analytics, and data processing.
+*   **[public](public)**: Contains static assets (like the favicon) served directly at the root path.
+*   **[cypress](cypress)**: Contains end-to-end tests in the `e2e` folder.

cypress/e2e/README.md

@@ -0,0 +1,17 @@
+# Cypress E2E Tests
+
+This directory contains End-to-End (E2E) tests for the Topola Viewer application, using the Cypress testing framework. The purpose of these tests is to verify the application's behavior from a user's perspective by simulating interactions in a real browser environment.
+
+## Test Files
+
+- [chart_view.cy.js](file:///home/pwiech/personal/github/topola-viewer/cypress/e2e/chart_view.cy.js)
+  Tests the core functionality of the chart view. It verifies that data can be loaded from a remote URL, that the chart can be interacted with (e.g., expanding nodes to show more people), and that the side panel displays correct information.
+
+- [embedded.cy.js](file:///home/pwiech/personal/github/topola-viewer/cypress/e2e/embedded.cy.js)
+  Tests the application in embedded mode. It verifies that Topola can be successfully loaded and run within an iframe, which is how it might be used when embedded in other websites.
+
+- [intro.cy.js](file:///home/pwiech/personal/github/topola-viewer/cypress/e2e/intro.cy.js)
+  Tests the application's landing page (intro page). It ensures that the introductory text is visible and that the main menu actions (like opening a file or loading from a URL) are present.
+
+- [search.cy.js](file:///home/pwiech/personal/github/topola-viewer/cypress/e2e/search.cy.js)
+  Tests the search functionality within the application. It verifies that users can search for individuals and that selecting a result correctly highlights or displays that person in the view.

public/README.md

@@ -0,0 +1,7 @@
+# Public Directory
+
+This directory contains static assets that are served directly by the web server. In this project, files in the `public` directory are served at the root path.
+
+## Files
+
+- [favicon.png](favicon.png): The icon displayed in the browser tab.

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.