From ea4c1f518c3bed9765b54d13ad0d891e147d9725 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Dafydd=20Ll=C5=B7r=20Pearson?= <DafyddLlyr@gmail.com>
Date: Wed, 27 Nov 2024 20:51:47 +0000
Subject: [PATCH 1/3] docs: How to add fields to search

---
 doc/how-to/how-to-add-fields-to-search.md | 88 +++++++++++++++++++++++
 1 file changed, 88 insertions(+)
 create mode 100644 doc/how-to/how-to-add-fields-to-search.md

diff --git a/doc/how-to/how-to-add-fields-to-search.md b/doc/how-to/how-to-add-fields-to-search.md
new file mode 100644
index 0000000000..1e7fbe580c
--- /dev/null
+++ b/doc/how-to/how-to-add-fields-to-search.md
@@ -0,0 +1,88 @@
+# How to add fields to the Editor search index
+
+## Overview
+
+This guide outlines the process of adding new searchable fields to the PlanX Editors' frontend search functionality, which uses Fuse.js for indexing and searching. This is a required step with adding a new component to PlanX, or adding new fields to an existing component.
+
+## Background
+
+- Search is currently implemented in the frontend using Fuse.js
+- Only certain fields are searchable:
+  - Text fields (simple text)
+  - Rich text fields (HTML)
+  - Data values (e.g. `data.fn`)
+
+## Process
+
+### 1. Update facets configuration
+
+Location: `src/pages/FlowEditor/components/Sidebar/Search/facets.ts`
+
+#### Guidelines:
+- Use key paths to the new fields (e.g. `data.myNewField`)
+- Wrap rich text fields with `richTextField()` helper - this strips HTML tags
+- Add data fields to `DATA_FACETS`
+- Add text fields to `ALL_FACETS`
+- Avoid adding duplicate values already held in `ALL_FACETS` (e.g., `data.title`, `data.description`)
+
+#### Example:
+
+```ts
+// facets.ts
+
+const myNewComponent: SearchFacets = [
+  richTextField("data.myRichTextField"),
+  "data.myPlainTextField"
+];
+
+export const ALL_FACETS: SearchFacets = [
+  ...otherComponents,
+  ...myNewComponent,
+  ...DATA_FACETS,
+];
+```
+
+### 2. Assign display values
+
+Location: `src/pages/FlowEditor/components/Sidebar/Search/SearchResultCard/getDisplayDetailsForResult.tsx`
+
+#### Add key formatters:
+
+```ts
+// getDisplayDetailsForResult.tsx
+
+const keyFormatters: KeyMap = {
+  ...existingFormatters,
+  "data.myNewField": {
+    getDisplayKey: () => "My New Field",
+  },
+};
+```
+
+### 3. Update tests
+
+Locations: 
+- `src/pages/FlowEditor/components/Sidebar/Search/SearchResultCard/allFacets.test.ts`
+- `src/pages/FlowEditor/components/Sidebar/Search/SearchResultCard/dataFacets.test.ts`
+
+#### Test steps:
+1. Add new component to `mockFlow`
+2. Create mock search result 
+   - Example: `mockMyComponentResult: SearchResult<IndexedNode>`
+
+### Debugging tip
+
+A search result can be easily logged to the console from `SearchResultCard`. Simply search for one of your new fields, and click on the card.
+
+```ts
+// SearchResultCard/index.tsx
+
+const handleClick = () => {
+  const url = getURLForNode(result.item.id);
+  // Temporarily disable navigation
+  // navigate(url);
+  
+  // Log the full search result to console
+  console.log({ result });
+};
+```
\ No newline at end of file

From 9c474a8664ee9355f8e086e34537d269b453a215 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Dafydd=20Ll=C5=B7r=20Pearson?= <DafyddLlyr@gmail.com>
Date: Wed, 27 Nov 2024 20:53:52 +0000
Subject: [PATCH 2/3] doc: Update adding a component guide

---
 editor.planx.uk/docs/adding-a-new-component.md | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/editor.planx.uk/docs/adding-a-new-component.md b/editor.planx.uk/docs/adding-a-new-component.md
index d04fa57a10..121a03930c 100644
--- a/editor.planx.uk/docs/adding-a-new-component.md
+++ b/editor.planx.uk/docs/adding-a-new-component.md
@@ -122,6 +122,10 @@ import SetValue from "@planx/components/SetValue/Editor";
 set: SetValueComponent,
 ```
 
+6. Add text fields to search index
+
+Please see detailed guide here - https://github.com/theopensystemslab/planx-new/blob/main/doc/how-to/how-to-add-fields-to-search.md
+
 ## Preview environment & integrations
 
 1. `src/pages/Preview/Node.tsx`

From 5d6f113cb0e62824b9eee1aa023d1b65cfd5e380 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Dafydd=20Ll=C5=B7r=20Pearson?= <DafyddLlyr@gmail.com>
Date: Wed, 27 Nov 2024 20:54:47 +0000
Subject: [PATCH 3/3] doc: Add link to Feedback PR

---
 doc/how-to/how-to-add-fields-to-search.md | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/doc/how-to/how-to-add-fields-to-search.md b/doc/how-to/how-to-add-fields-to-search.md
index 1e7fbe580c..fb6c12062f 100644
--- a/doc/how-to/how-to-add-fields-to-search.md
+++ b/doc/how-to/how-to-add-fields-to-search.md
@@ -85,4 +85,6 @@ const handleClick = () => {
   // Log the full search result to console
   console.log({ result });
 };
-```
\ No newline at end of file
+```
+
+For reference, [please see this PR](https://github.com/theopensystemslab/planx-new/pull/4015) which added the text fields for the `Feedback` component to the search index.
\ No newline at end of file