From 69bf59902d6a1801180c50c29893dfbd46a4e486 Mon Sep 17 00:00:00 2001
From: guido <dev@guidoscialfa.com>
Date: Sun, 18 Feb 2024 20:12:48 +0100
Subject: [PATCH] Add ControlOption documentation

Explaining the Value Object and the usage of the `extra` property.
---
 README.md              |  7 ++--
 docs/control-option.md | 89 ++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 93 insertions(+), 3 deletions(-)
 create mode 100644 docs/control-option.md

diff --git a/README.md b/README.md
index 8f88829..c4bda90 100644
--- a/README.md
+++ b/README.md
@@ -11,9 +11,10 @@ more Post Types but also, to search for Terms belonging to one or more Taxonomie
 2. [Development](./docs/development.md)
 3. [Api](./docs/api.md)
 4. [Components](./docs/components.md)
-5. [Hooks](./docs/hooks.md)
-6. [Logging](./docs/logging.md)
-7. [Storage](./docs/storage.md)
+5. [Control Option](./docs/control-option.md)
+6. [Hooks](./docs/hooks.md)
+7. [Logging](./docs/logging.md)
+8. [Storage](./docs/storage.md)
 
 ## License
 
diff --git a/docs/control-option.md b/docs/control-option.md
new file mode 100644
index 0000000..f43b84c
--- /dev/null
+++ b/docs/control-option.md
@@ -0,0 +1,89 @@
+# Control Option
+
+The `ControlOption` is the core Value Object of the project. It holds the information about the entities, and it
+is carried around the business logic and the presentational layer.
+
+The Control Option mainly contain the following properties:
+
+- `label` (String): The label of the control option.
+- `value` (mixed): The value of the control option.
+
+An additional data structure is part of the `EnrichedControlOption` interface implemented by `ControlOption`. This DS is
+not consumed within any of the _Base_ or _Composite_ components of the project, it is there to permit the third parties
+to customize the UI.
+
+The `extra` property is of type `EntitiesSearch.Record`; it can hold a heterogeneous set of properties, we do not check
+against values or types, this is up to the consumer.
+
+## About the Value
+
+The `value` is a generic type to give the possibility to customize the shape of the value since we allow the consumer to
+implement they own components, and therefore we do not want to pose any restriction.
+
+Nonetheless, the possible types the `value` can assume within the project Components is `string | number`;
+see `EntitiesSearch.Value` type for more info.
+
+## How to use the Extra Property
+
+Let's say you're using the `CompositeEntitiesByKind` component, and you want to render along with the Title of the
+entity the `type` and the `excerpt`.
+
+In the example below we're using the `extra` property to carry the `type` and the `excerpt` of the entity.
+
+The `convertEntitiesToContrlOptions` will create the `ControlOption` with the `extra` property containing the post type
+and the post excerpt.
+
+```typescript
+searchEntities: async (
+	phrase,
+	postType,
+	queryArguments
+) => {
+	const postsEntities = await searchEntities(
+		'post',
+		postType,
+		phrase,
+		{...queryArguments, fields: ['title', 'id', 'type', 'excerpt']}
+	);
+
+	return convertEntitiesToControlOptions(
+		postsEntities,
+		'title',
+		'id',
+
+		// Extra properties
+		'type',
+		'excerpt'
+	);
+}
+```
+
+Then you can access the extra properties within your component since the `CompositeEntitiesByKind` will pass
+the `entities` of type `EntitiesSearch.BaseControl< E >` to the children.
+
+```typescript
+(entities: EntitiesSearch.BaseControl< E >) => {
+    return <MyComponent {...entities} />;
+}
+```
+
+And internally of your `MyComponent` you can access the `extra` property of the `ControlOption`:
+
+```typescript
+function MyComponent(entities: Options<V>): JSX.Element {
+    return (
+        <div>
+            {entities.options.map((option) => (
+                <label>
+                    <input value={option.value} />
+                    <span>{option.label}</span>
+                    <span>
+                        <span>{option.extra.get('type')}</span>
+                        <span>{option.extra.get('excerpt')}</span>
+                    </span>
+                </label>
+            ))}
+        </div>
+    );
+}
+```