docs(mobile-client): add new doc for headlines feed feature

- Introduce a new document explaining the main news feed functionality
- Cover core components, BLoCs, and key features
- Include information on infinite scrolling, pull-to-refresh, filtering, and dynamic content injection

Author: fulleni

src/content/docs/mobile-client/features/headlines-feed.mdx

@@ -0,0 +1,37 @@
+---
+title: Headlines Feed
+description: Learn how the main news feed is managed, including filtering and dynamic content.
+---
+import { Card, CardGrid } from '@astrojs/starlight/components';
+
+The Headlines Feed is the core feature of the mobile client, providing users with a scrollable list of news articles. It is a sophisticated system that supports pagination, pull-to-refresh, complex filtering, and dynamic content injection.
+
+## Core Components
+
+The feed is managed by a collection of BLoCs that handle different aspects of its functionality.
+
+-   **`HeadlinesFeedBloc`**: The central BLoC that manages the state of the main feed. It is responsible for fetching headlines from the `HeadlinesRepository`, handling pagination (`HeadlinesFeedFetchRequested`), and applying filters (`HeadlinesFeedFiltersApplied`).
+
+-   **`FeedInjectorService`**: A crucial service that dynamically injects non-headline content, such as advertisements (`Ad`) and account-related calls-to-action (`FeedAction`), into the list of headlines. It uses business logic based on the user's status and remote configuration to determine where and when to place this content.
+
+-   **Filter BLoCs**: A set of specialized BLoCs manage the state for the filter selection pages:
+    -   `TopicsFilterBloc`: Fetches and manages the list of available topics for filtering.
+    -   `SourcesFilterBloc`: Manages the complex logic for filtering by source, which also includes sub-filters for country and source type.
+    -   `CountriesFilterBloc`: Fetches and manages the list of countries for filtering.
+
+## Key Functionalities
+
+<CardGrid>
+	<Card title="Infinite Scrolling" icon="arrow-down">
+		The feed uses pagination to load headlines continuously as the user scrolls. The `_onScroll` listener in `HeadlinesFeedPage` detects when the user is near the bottom of the list and dispatches a `HeadlinesFeedFetchRequested` event to load the next page of content.
+	</Card>
+	<Card title="Pull-to-Refresh" icon="refresh">
+		Users can pull down from the top of the feed to refresh the content. This action triggers a `HeadlinesFeedRefreshRequested` event, which re-fetches the first page of headlines with the currently active filters.
+	</Card>
+	<Card title="Advanced Filtering" icon="filter">
+		Users can tap the filter icon in the AppBar to open the `HeadlinesFilterPage`. This page allows them to apply filters based on topics and sources. A unique feature is the "Apply my followed items" checkbox, which automatically creates a filter based on the user's followed topics and sources.
+	</Card>
+    <Card title="Dynamic Content" icon="add-circle">
+        The `FeedInjectorService` intelligently inserts ads and calls-to-action (e.g., "Link your account") into the feed. This logic is based on rules defined in the `RemoteConfig`, such as ad frequency per user role, ensuring a tailored experience.
+    </Card>
+</CardGrid>