feat: add "relevance" to event and course search ordering options

TH-1442.

Add "relevance" as a new oredring option in events and courses search.
It is using "-rank" as sort-parameter value, which means descending
"rank", which is also the default sort-parameter in LinkedEvents, when a
full text search -parameter is used.

Rank sorting option and filter scoring system is effective only when
using `x_full_text` -parameter.

Rank should not be explicitly set, but left empty instead, when wanted
to be affective. The rank sorting needs a mandatory secondary order
field and scoring annotation to queryset, which are only activated when
`x_full_text` -parameter is used and sort-parameter is left empty.

Ref.
[LINK-2422](https://helsinkisolutionoffice.atlassian.net/browse/LINK-2422)

Author: nikomakela

apps/events-helsinki/src/domain/search/eventSearch/utils.tsx

@@ -3,7 +3,6 @@ import type {
   AppLanguage,
   Meta,
   QueryEventListArgs,
-  EVENT_SORT_OPTIONS,
   KeywordOnClickHandlerType,
   Venue,
 } from '@events-helsinki/components';
@@ -16,6 +15,7 @@ import {
   scrollToTop,
   CITY_OF_HELSINKI_LINKED_EVENTS_ORGANIZATION_ID,
   EVENT_SEARCH_FILTERS,
+  EVENT_SORT_OPTIONS,
 } from '@events-helsinki/components';
 import {
   addDays,
@@ -262,7 +262,12 @@ export const getEventSearchVariables = ({
     location: places.sort((a, b) => a.localeCompare(b)),
     pageSize,
     publisher,
-    sort: sortOrder,
+    /**
+     * As per LinkedEvents requirements (see LINK-2422; https://helsinkisolutionoffice.atlassian.net/browse/LINK-2422),
+     * relevance sorting (rank) is activated by providing an *empty string* as the sort parameter when
+     * `x_full_text` is used, not the literal '-rank' value.
+     */
+    sort: sortOrder === EVENT_SORT_OPTIONS.RANK_DESC ? '' : sortOrder,
     start,
     startsAfter,
     superEventType,

apps/hobbies-helsinki/src/domain/search/eventSearch/utils.tsx

@@ -7,13 +7,13 @@ import {
   scrollToTop,
   EVENT_SEARCH_FILTERS,
   CITY_OF_HELSINKI_LINKED_EVENTS_ORGANIZATION_ID,
+  EVENT_SORT_OPTIONS,
 } from '@events-helsinki/components';
 import type {
   AppLanguage,
   Meta,
   QueryEventListArgs,
   EventFields,
-  EVENT_SORT_OPTIONS,
   KeywordOnClickHandlerType,
   Venue,
 } from '@events-helsinki/components';
@@ -247,7 +247,12 @@ export const getEventSearchVariables = ({
     location: places.sort((a, b) => a.localeCompare(b)),
     pageSize,
     publisher,
-    sort: sortOrder,
+    /**
+     * As per LinkedEvents requirements (see LINK-2422; https://helsinkisolutionoffice.atlassian.net/browse/LINK-2422),
+     * relevance sorting (rank) is activated by providing an *empty string* as the sort parameter when
+     * `x_full_text` is used, not the literal '-rank' value.
+     */
+    sort: sortOrder === EVENT_SORT_OPTIONS.RANK_DESC ? '' : sortOrder,
     start,
     startsAfter,
     superEventType,

apps/sports-helsinki/src/domain/search/combinedSearch/adapters/EventSearchAdapter.ts

@@ -1,4 +1,7 @@
-import { CITY_OF_HELSINKI_LINKED_EVENTS_ORGANIZATION_ID } from '@events-helsinki/components';
+import {
+  CITY_OF_HELSINKI_LINKED_EVENTS_ORGANIZATION_ID,
+  EVENT_SORT_OPTIONS,
+} from '@events-helsinki/components';
 import { EventTypeId } from '@events-helsinki/components/types';
 import {
   SPORT_COURSES_KEYWORDS,
@@ -56,10 +59,11 @@ class EventSearchAdapter implements CombinedSearchAdapter<EventSearchParams> {
     this.keywordOrSet1 = SPORT_COURSES_KEYWORDS;
     this.keywordOrSet2 = this.getSportsKeywords(input);
     this.keywordOrSet3 = this.getTargetGroupKeywords(input);
-    this.sort =
-      (eventType === EventTypeId.General
-        ? input.eventOrderBy
-        : input.courseOrderBy) ?? initialEventSearchAdapterValues.sort;
+    this.sort = this.getSortingValue(
+      eventType,
+      input.eventOrderBy,
+      input.courseOrderBy
+    );
     this.publisher =
       input.organization ?? initialEventSearchAdapterValues.publisher;
     this.publisherAncestor = input.helsinkiOnly
@@ -68,6 +72,38 @@ class EventSearchAdapter implements CombinedSearchAdapter<EventSearchParams> {
     this.superEvent = this.getSuperEvent(eventType);
   }
 
+  /**
+   * Determines the correct sort parameter value for an API request.
+   *
+   * This function selects the appropriate sort order (`eventOrderBy` or `courseOrderBy`)
+   * based on the `eventType`. It also implements special handling for
+   * `EVENT_SORT_OPTIONS.RANK_DESC`.
+   *
+   * As per LinkedEvents API requirements (see LINK-2422), relevance sorting (rank)
+   * is activated by providing an *empty string* as the sort parameter when
+   * `x_full_text` is used, not the literal '-rank' value. This function
+   * performs that conversion.
+   *
+   * @param {EventTypeId} eventType The type of event, used to decide whether to use `eventOrderBy` or `courseOrderBy`.
+   * @param {EventSearchParams['sort']} [eventOrderBy] The sort value to use if `eventType` is `EventTypeId.General`.
+   * @param {EventSearchParams['sort']} [courseOrderBy] The sort value to use if `eventType` is `EventTypeId.Course`.
+   * @returns {string} The finalized sort parameter string. Returns an empty string (`''`)
+   * if the determined sort value is `EVENT_SORT_OPTIONS.RANK_DESC`,
+   * otherwise returns the selected or default sort value.
+   */
+  public getSortingValue(
+    eventType: EventTypeId,
+    eventOrderBy?: EventSearchParams['sort'],
+    courseOrderBy?: EventSearchParams['sort']
+  ): string {
+    const sortValue =
+      (eventType === EventTypeId.General ? eventOrderBy : courseOrderBy) ??
+      initialEventSearchAdapterValues.sort;
+
+    // RANK_DESC needs to be handled as an empty string.
+    return sortValue === EVENT_SORT_OPTIONS.RANK_DESC ? '' : sortValue;
+  }
+
   /**
    * If the search is for Courses,
    * the superEvent should be set to 'none' -

apps/sports-helsinki/src/domain/search/eventSearch/utils.tsx

@@ -1,6 +1,5 @@
 import type {
   AppLanguage,
-  EVENT_SORT_OPTIONS,
   EventFields,
   FilterType,
   KeywordOnClickHandlerType,
@@ -22,6 +21,7 @@ import {
   isEventFields,
   isVenue,
   scrollToTop,
+  EVENT_SORT_OPTIONS,
 } from '@events-helsinki/components';
 import {
   addDays,
@@ -244,7 +244,12 @@ export const getEventSearchVariables = ({
     pageSize,
     publisher,
     publisherAncestor: null,
-    sort: sortOrder,
+    /**
+     * As per LinkedEvents requirements (see LINK-2422; https://helsinkisolutionoffice.atlassian.net/browse/LINK-2422),
+     * relevance sorting (rank) is activated by providing an *empty string* as the sort parameter when
+     * `x_full_text` is used, not the literal '-rank' value.
+     */
+    sort: sortOrder === EVENT_SORT_OPTIONS.RANK_DESC ? '' : sortOrder,
     start,
     superEventType,
     superEvent,

packages/components/src/components/orderBySelect/EventsOrderBySelect.tsx

@@ -25,6 +25,10 @@ const EventsOrderBySelect: React.FC<{
       text: t('search:orderBy.endTime'),
       value: EVENT_SORT_OPTIONS.END_TIME,
     },
+    {
+      text: t('search:orderBy.relevance'),
+      value: EVENT_SORT_OPTIONS.RANK_DESC,
+    },
     {
       text: t('search:orderBy.lastModifiedTime'),
       value: EVENT_SORT_OPTIONS.LAST_MODIFIED_TIME_DESC,

packages/components/src/constants/event-constants.ts

@@ -27,6 +27,18 @@ export enum EVENT_SORT_OPTIONS {
   LAST_MODIFIED_TIME_DESC = '-last_modified_time',
   START_TIME = 'start_time',
   START_TIME_DESC = '-start_time',
+  /**
+   * NOTE: Rank is effective only when using `x_full_text` -parameter.
+   *
+   * NOTE: Rank should not be explicitly set, but left empty instead, when wanted.
+   * The rank sorting needs a mandatory secondary order field and scoring annotation to queryset,
+   * which are only activated when `x_full_text` -parameter is used and sort-parameter is left empty.
+   *
+   * However, in our own apps' URL we want sort-param to be set and visible, so it needs to be converted on search.
+   *
+   * Ref. [LINK-2422](https://helsinkisolutionoffice.atlassian.net/browse/LINK-2422)
+   * */
+  RANK_DESC = '-rank',
 }
 
 export const isEventSortOption = (