Introduce Enriched Control Option

@types/index.d.ts

@@ -42,11 +42,6 @@ declare namespace EntitiesSearch {
 		queryArguments?: EntitiesSearch.QueryArguments<E>
 	) => Promise<Options<E>>;
 
-	type ControlOption<V extends any> = Readonly<{
-		value: V;
-		label: string;
-	}>;
-
 	type SingularControl<V> = {
 		[K in keyof BaseControl<V>]: K extends 'value'
 			? V
@@ -55,6 +50,20 @@ declare namespace EntitiesSearch {
 			: BaseControl<V>[K];
 	};
 
+	interface Record<T> {
+		get<F>(key: string, fallback?: F): T | F | undefined;
+		set(key: string, value: T): Record<T>;
+	}
+
+	interface ControlOption<V extends any> extends Readonly<{
+		value: V;
+		label: string;
+	}> {}
+
+	interface EnrichedControlOption<V extends any> extends ControlOption<V>, Readonly<{
+		readonly extra: Record<string, unknown>;
+	}> {}
+
 	interface BaseControl<V>
 		extends Readonly<{
 			value: Set<V>;

sources/client/src/api/search-entities.ts

@@ -13,7 +13,7 @@ import { doAction } from '@wordpress/hooks';
  */
 import { abortControllers } from '../services/abort-controllers';
 import { ContextualAbortController } from '../services/contextual-abort-controller';
-import { Set } from '../vo/set';
+import { Set } from '../models/set';
 import { fetch } from './fetch';
 
 export async function searchEntities< E >(

sources/client/src/components/composite-entities-by-kind.tsx

@@ -16,7 +16,7 @@ import { useEntitiesOptionsStorage } from '../hooks/use-entities-options-storage
 import { useSearch } from '../hooks/use-search';
 import { orderSelectedOptionsAtTheTop } from '../utils/order-selected-options-at-the-top';
 import { uniqueControlOptions } from '../utils/unique-control-options';
-import { Set } from '../vo/set';
+import { Set } from '../models/set';
 
 /**
  * A composite component that provides a way to search for entities by kind.

sources/client/src/components/plural-select-control.tsx

@@ -8,7 +8,7 @@ import React, { JSX } from 'react';
 /**
  * Internal dependencies
  */
-import { Set } from '../vo/set';
+import { Set } from '../models/set';
 import { NoOptionsMessage } from './no-options-message';
 
 export function PluralSelectControl(

sources/client/src/hooks/use-entities-options-storage.ts

@@ -14,7 +14,7 @@ import { doAction } from '@wordpress/hooks';
  */
 import { makeInitialState } from '../storage/entities/initial-state';
 import { reducer } from '../storage/entities/reducer';
-import { Set } from '../vo/set';
+import { Set } from '../models/set';
 
 type _Reducer< E, K > = Reducer<
 	EntitiesSearch.EntitiesState< E, K >,

sources/client/src/hooks/use-entity-records.ts

@@ -11,7 +11,7 @@ import { useEntityRecords as useCoreEntityRecords } from '@wordpress/core-data';
 /**
  * Internal dependencies
  */
-import { Set } from '../vo/set';
+import { Set } from '../models/set';
 
 enum ResolveStatus {
 	ERROR = 'ERROR',

sources/client/src/hooks/use-query-viewable-post-types.ts

@@ -6,7 +6,7 @@ import EntitiesSearch from '@types';
 /**
  * Internal dependencies
  */
-import { Set } from '../vo/set';
+import { Set } from '../models/set';
 import { useEntityRecords } from './use-entity-records';
 
 /**

sources/client/src/hooks/use-query-viewable-taxonomies.ts

@@ -6,7 +6,7 @@ import EntitiesSearch from '@types';
 /**
  * Internal dependencies
  */
-import { Set } from '../vo/set';
+import { Set } from '../models/set';
 import { useEntityRecords } from './use-entity-records';
 
 /**

sources/client/src/hooks/use-search.ts

@@ -13,7 +13,7 @@ import { doAction } from '@wordpress/hooks';
 /**
  * Internal dependencies
  */
-import { Set } from '../vo/set';
+import { Set } from '../models/set';
 
 type SearchPhrase = Parameters<
 	EntitiesSearch.SearchControl[ 'onChange' ]

sources/client/src/index.ts

@@ -12,10 +12,12 @@ export * from './hooks/use-entity-records';
 export * from './hooks/use-query-viewable-post-types';
 export * from './hooks/use-query-viewable-taxonomies';
 
+export * from './models/set';
+export * from './models/immutable-record';
+
 export * from './utils/convert-entities-to-control-options';
 export * from './utils/is-control-option';
-export * from './utils/order-selected-options-at-the-top';
 export * from './utils/unique-control-options';
+export * from './utils/order-selected-options-at-the-top';
 
-export * from './vo/control-option';
-export * from './vo/set';
+export * from './value-objects/control-option';

sources/client/src/models/immutable-record.ts

@@ -0,0 +1,20 @@
+/**
+ * External dependencies
+ */
+import EntitiesSearch from '@types';
+
+export class ImmutableRecord< T > implements EntitiesSearch.Record< T > {
+	readonly #map: Record< string, T > = {};
+
+	public constructor( map: Record< string, T > = {} ) {
+		this.#map = map;
+	}
+
+	public get< F >( key: string, fallback?: F ): T | F | undefined {
+		return this.#map[ key ] ?? fallback;
+	}
+
+	public set( key: string, value: T ): ImmutableRecord< T > {
+		return new ImmutableRecord( { ...this.#map, [ key ]: value } );
+	}
+}

sources/client/src/storage/entities/initial-state.ts

@@ -6,7 +6,7 @@ import EntitiesSearch from '@types';
 /**
  * Internal dependencies
  */
-import { Set } from '../../vo/set';
+import { Set } from '../../models/set';
 
 type Options< V > = EntitiesSearch.ControlOption< V >;
 

sources/client/src/storage/entities/reducer.ts

@@ -6,7 +6,7 @@ import EntitiesSearch from '@types';
 /**
  * Internal dependencies
  */
-import { Set } from '../../vo/set';
+import { Set } from '../../models/set';
 
 /**
  * @internal

sources/client/src/utils/convert-entities-to-control-options.ts

@@ -6,22 +6,30 @@ import EntitiesSearch from '@types';
 /**
  * Internal dependencies
  */
-import { ControlOption } from '../vo/control-option';
-import { Set } from '../vo/set';
+import { ControlOption } from '../value-objects/control-option';
+import { Set } from '../models/set';
 import { assert } from './assert';
+import { ImmutableRecord } from '../models/immutable-record';
 
 export function convertEntitiesToControlOptions<
 	V,
 	EntitiesFields extends { [ p: string ]: any },
 >(
 	entities: Set< EntitiesFields >,
 	labelKey: string,
-	valueKey: string
+	valueKey: string,
+	...extraKeys: Array< string >
 ): Set< EntitiesSearch.ControlOption< V > > {
 	return entities.map( ( entity ) => {
 		const label = entity[ labelKey ];
 		const value = entity[ valueKey ];
-		assert( typeof label === 'string', 'Label Key must be a string' );
-		return new ControlOption( label, value );
+		assert( typeof label === 'string', 'Label key must be a string' );
+
+		const extra = extraKeys.reduce(
+			( record, key ) => ( { ...record, [ key ]: entity[ key ] } ),
+			{}
+		);
+
+		return new ControlOption( label, value, new ImmutableRecord( extra ) );
 	} );
 }

sources/client/src/utils/order-selected-options-at-the-top.ts

@@ -6,7 +6,7 @@ import EntitiesSearch from '@types';
 /**
  * Internal dependencies
  */
-import { Set } from '../vo/set';
+import { Set } from '../models/set';
 
 export function orderSelectedOptionsAtTheTop< V >(
 	options: Set< EntitiesSearch.ControlOption< V > >,

sources/client/src/utils/unique-control-options.ts

@@ -6,7 +6,7 @@ import EntitiesSearch from '@types';
 /**
  * Internal dependencies
  */
-import { Set } from '../vo/set';
+import { Set } from '../models/set';
 
 // TODO Is this necessary due the new Set implementation?
 export function uniqueControlOptions< V >(

sources/client/src/vo/control-option.ts → sources/client/src/value-objects/control-option.ts

@@ -7,12 +7,20 @@ import EntitiesSearch from '@types';
  * Internal dependencies
  */
 import { assert } from '../utils/assert';
+import { ImmutableRecord } from '../models/immutable-record';
 
-export class ControlOption< V > implements EntitiesSearch.ControlOption< V > {
+export class ControlOption< V >
+	implements EntitiesSearch.EnrichedControlOption< V >
+{
 	public readonly label: string;
 	public readonly value: V;
+	public readonly extra: EntitiesSearch.Record< unknown >;
 
-	public constructor( label: string, value: V ) {
+	public constructor(
+		label: string,
+		value: V,
+		extra: EntitiesSearch.Record< unknown > = new ImmutableRecord()
+	) {
 		assert(
 			label !== '',
 			'ControlOption: Label must be a non empty string.'
@@ -24,5 +32,6 @@ export class ControlOption< V > implements EntitiesSearch.ControlOption< V > {
 
 		this.label = label;
 		this.value = value;
+		this.extra = extra;
 	}
 }

tests/client/integration/components/composite-entities-by-kind.test.tsx

@@ -21,7 +21,7 @@ import { CompositeEntitiesByKind } from '../../../../sources/client/src/componen
 import { PluralSelectControl } from '../../../../sources/client/src/components/plural-select-control';
 import { SearchControl } from '../../../../sources/client/src/components/search-control';
 import { SingularSelectControl } from '../../../../sources/client/src/components/singular-select-control';
-import { Set } from '../../../../sources/client/src/vo/set';
+import { Set } from '../../../../sources/client/src/models/set';
 
 jest.mock( '@wordpress/hooks', () => ( {
 	doAction: jest.fn(),
@@ -36,7 +36,11 @@ describe( 'CompositeEntitiesByKind', () => {
 
 		const rendered = render(
 			<CompositeEntitiesByKind
-				searchEntities={ () => Promise.resolve( new Set() ) }
+				searchEntities={ () =>
+					Promise.resolve(
+						new Set< EntitiesSearch.ControlOption< any > >()
+					)
+				}
 				entities={ {
 					value: new Set(),
 					onChange: () => {},
@@ -92,7 +96,9 @@ describe( 'CompositeEntitiesByKind', () => {
 					} }
 					kind={ {
 						value: new Set( [ 'post' ] ),
-						options: new Set(),
+						options: new Set<
+							EntitiesSearch.ControlOption< any >
+						>(),
 						onChange: () => {},
 					} }
 				>
@@ -335,7 +341,9 @@ describe( 'CompositeEntitiesByKind', () => {
 					} }
 					kind={ {
 						value: new Set( [ 'post' ] ),
-						options: new Set(),
+						options: new Set<
+							EntitiesSearch.ControlOption< any >
+						>(),
 						onChange: () => {},
 					} }
 				>
@@ -381,7 +389,9 @@ describe( 'CompositeEntitiesByKind', () => {
 					} }
 					kind={ {
 						value: new Set( [ 'post' ] ),
-						options: new Set(),
+						options: new Set<
+							EntitiesSearch.ControlOption< any >
+						>(),
 						onChange: () => {},
 					} }
 				>
@@ -414,7 +424,9 @@ describe( 'CompositeEntitiesByKind', () => {
 					} }
 					kind={ {
 						value: new Set( [ 'post' ] ),
-						options: new Set(),
+						options: new Set<
+							EntitiesSearch.ControlOption< any >
+						>(),
 						onChange: () => {},
 					} }
 				>
@@ -485,7 +497,11 @@ describe( 'CompositeEntitiesByKind', () => {
 
 		const rendered = render(
 			<CompositeEntitiesByKind
-				searchEntities={ () => Promise.resolve( new Set() ) }
+				searchEntities={ () =>
+					Promise.resolve(
+						new Set< EntitiesSearch.ControlOption< any > >()
+					)
+				}
 				entities={ {
 					value: new Set(),
 					onChange: () => {},

tests/client/unit/api/search-entities.test.ts

@@ -15,7 +15,7 @@ import { doAction } from '@wordpress/hooks';
  */
 import { fetch } from '../../../../sources/client/src/api/fetch';
 import { searchEntities } from '../../../../sources/client/src/api/search-entities';
-import { Set } from '../../../../sources/client/src/vo/set';
+import { Set } from '../../../../sources/client/src/models/set';
 
 jest.mock( '@wordpress/hooks', () => ( {
 	doAction: jest.fn(),

tests/client/unit/components/plural-select-control.test.tsx

@@ -15,7 +15,7 @@ import { faker } from '@faker-js/faker';
  * Internal dependencies
  */
 import { PluralSelectControl } from '../../../../sources/client/src/components/plural-select-control';
-import { Set } from '../../../../sources/client/src/vo/set';
+import { Set } from '../../../../sources/client/src/models/set';
 import { buildOptions } from '../utils';
 
 describe( 'Posts Select', () => {

tests/client/unit/components/radio-control.test.tsx

@@ -12,7 +12,7 @@ import { render, screen, fireEvent } from '@testing-library/react';
  * Internal dependencies
  */
 import { RadioControl } from '../../../../sources/client/src/components/radio-control';
-import { Set } from '../../../../sources/client/src/vo/set';
+import { Set } from '../../../../sources/client/src/models/set';
 
 describe( 'KindRadioControl', () => {
 	it( 'renders the component', () => {

tests/client/unit/components/singular-select-control.test.tsx

@@ -15,7 +15,7 @@ import { faker } from '@faker-js/faker';
  * Internal dependencies
  */
 import { SingularSelectControl } from '../../../../sources/client/src/components/singular-select-control';
-import { Set } from '../../../../sources/client/src/vo/set';
+import { Set } from '../../../../sources/client/src/models/set';
 import { buildOptions } from '../utils';
 
 describe( 'Post Types Select', () => {

tests/client/unit/components/toggle-control.test.tsx

@@ -12,7 +12,7 @@ import userEvent from '@testing-library/user-event';
  * Internal dependencies
  */
 import { ToggleControl } from '../../../../sources/client/src/components/toggle-control';
-import { Set } from '../../../../sources/client/src/vo/set';
+import { Set } from '../../../../sources/client/src/models/set';
 
 const options = new Set( [
 	{ label: 'Option 1', value: '1' },

tests/client/unit/hooks/use-entities-options-storage.test.tsx

@@ -17,7 +17,7 @@ import { doAction } from '@wordpress/hooks';
  * Internal dependencies
  */
 import { useEntitiesOptionsStorage } from '../../../../sources/client/src/hooks/use-entities-options-storage';
-import { Set } from '../../../../sources/client/src/vo/set';
+import { Set } from '../../../../sources/client/src/models/set';
 
 jest.mock( '@wordpress/hooks', () => ( {
 	doAction: jest.fn(),

tests/client/unit/hooks/use-query-viewable-post-types.test.ts

@@ -11,7 +11,7 @@ import { describe, it, jest, expect } from '@jest/globals';
  */
 import { useEntityRecords } from '../../../../sources/client/src/hooks/use-entity-records';
 import { useQueryViewablePostTypes } from '../../../../sources/client/src/hooks/use-query-viewable-post-types';
-import { Set } from '../../../../sources/client/src/vo/set';
+import { Set } from '../../../../sources/client/src/models/set';
 
 jest.mock( '@wordpress/data', () => {
 	return {

tests/client/unit/hooks/use-query-viewable-taxonomies.test.ts

@@ -11,7 +11,7 @@ import { describe, expect, it, jest } from '@jest/globals';
  */
 import { useEntityRecords } from '../../../../sources/client/src/hooks/use-entity-records';
 import { useQueryViewableTaxonomies } from '../../../../sources/client/src/hooks/use-query-viewable-taxonomies';
-import { Set } from '../../../../sources/client/src/vo/set';
+import { Set } from '../../../../sources/client/src/models/set';
 
 jest.mock( '../../../../sources/client/src/hooks/use-entity-records', () => {
 	return {