From e0f01f8f3b4b9707ceccce9ae1c95b2171a5dfd9 Mon Sep 17 00:00:00 2001
From: Mikkel Jakobsen <jakobsen.mikkel@gmail.com>
Date: Tue, 14 Jan 2025 20:27:42 +0100
Subject: [PATCH] Add ADR for Xstate

---
 docs/README.md                      |  9 +++---
 docs/architecture/adr-002-xstate.md | 46 +++++++++++++++++++++++++++++
 2 files changed, 51 insertions(+), 4 deletions(-)
 create mode 100644 docs/architecture/adr-002-xstate.md

diff --git a/docs/README.md b/docs/README.md
index 8aeed73..62073c4 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -1,4 +1,5 @@
 ![GO logo](../public/icons/logo-white-readme.svg)
+
 <p>
   <br/>
   Website for the public library that uses <a href="https://nextjs.org" target="_blank">Next.js</a> with the <a href="https://nextjs.org/docs/app" target="_blank">App Router</a> for the frontend and <a href="https://www.drupal.org/" target="_blank">Drupal</a> for content management.
@@ -10,8 +11,8 @@
 
 ## URLs
 
-| Description                                             | URL                                                      |
-| ------------------------------------------------------- | -------------------------------------------------------- |
+| Description                                             | URL                                                        |
+| ------------------------------------------------------- | ---------------------------------------------------------- |
 | Demo site (may change)                                  | <https://node.pr-1707.dpl-cms.dplplat01.dpl.reload.dk/>    |
 | Demo site Drupal CMS (may change, login through lagoon) | <https://varnish.pr-1707.dpl-cms.dplplat01.dpl.reload.dk/> |
 
@@ -220,11 +221,11 @@ To add a custom type, create a new file in the `lib/types` directory and define
 
 ### xState
 
-TODO: write something if relevant
+Read about xState [here](architecture/adr-002-xstate.md).
 
 ### Config handling
 
-Read about configuration[here](architecture/adr-001-configuration.md).
+Read about configuration [here](architecture/adr-001-configuration.md).
 
 ### Storybook
 
diff --git a/docs/architecture/adr-002-xstate.md b/docs/architecture/adr-002-xstate.md
new file mode 100644
index 0000000..1ebb18a
--- /dev/null
+++ b/docs/architecture/adr-002-xstate.md
@@ -0,0 +1,46 @@
+# Xstate
+
+## Context
+
+We wanted a methodology of handling state when we have a feature set with a
+growing number of different states, transitions and context.
+
+Also we wanted to get acquainted with Xstate both because of its principle of
+using a state tree and because of it's possibility of visualizing the various
+scenarios/flows a user could go through.
+
+## Decision
+
+The search page was growing into being a problematic scenario as described above
+with multiple elements and connected states to be managed:
+
+- Searching
+- Loading more results
+- Filtering and loading possible filters
+- Linking to a search/filtering
+
+So we decided to implement the current early version of the search in Xstate in
+order to get a transparent state tree controlling the different states and
+transition to other states.
+
+## Alternatives considered
+
+Other state handlers where considered:
+
+- Zustand
+- Redux
+
+## Consequences
+
+Common to the alternatives considered is the fact that they do have the concept
+of a state tree controlling which transitions are available at the various levels.
+
+By having all the states and possible transitions between them in a Xstate machine
+we have a predictable way of treating the various cases/flows a user can go through.
+
+Also Xstate has powerful tools in order to handle side effects of the machine/actor.
+One example is the [event handlers](https://stately.ai/docs/event-emitter#event-handlers) which we use for listening if a filter was toggled. When a filter is toggled
+we can either set or remove a query parameter accordingly.
+
+Even machine/actors can interact with each other, but let's see if we will ever
+need that complexity.