From ef873dcda2704011f99730103973b0902297eb3e Mon Sep 17 00:00:00 2001 From: Philipp Stracker Date: Mon, 18 Nov 2024 18:51:11 +0100 Subject: [PATCH] =?UTF-8?q?=F0=9F=92=A1=20Document=20all=20Redux=20store?= =?UTF-8?q?=20files?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../resources/js/data/onboarding/action-types.js | 9 +++++++++ .../resources/js/data/onboarding/actions.js | 10 ++++++++++ .../resources/js/data/onboarding/controls.js | 9 +++++++++ .../resources/js/data/onboarding/hooks.js | 10 ++++++++++ .../resources/js/data/onboarding/reducer.js | 11 +++++++++++ .../resources/js/data/onboarding/resolvers.js | 10 ++++++++++ .../resources/js/data/onboarding/selectors.js | 10 ++++++++++ 7 files changed, 69 insertions(+) diff --git a/modules/ppcp-settings/resources/js/data/onboarding/action-types.js b/modules/ppcp-settings/resources/js/data/onboarding/action-types.js index f4834bbf5..7a38dbb1b 100644 --- a/modules/ppcp-settings/resources/js/data/onboarding/action-types.js +++ b/modules/ppcp-settings/resources/js/data/onboarding/action-types.js @@ -1,3 +1,12 @@ +/** + * Action Types: Define unique identifiers for actions across all store modules. + * + * Keys are module-internal and can have any value. + * Values must be unique across all store modules to avoid collisions. + * + * @file + */ + export default { // Transient data. SET_TRANSIENT: 'ONBOARDING:SET_TRANSIENT', diff --git a/modules/ppcp-settings/resources/js/data/onboarding/actions.js b/modules/ppcp-settings/resources/js/data/onboarding/actions.js index 22c9571e1..ac194252d 100644 --- a/modules/ppcp-settings/resources/js/data/onboarding/actions.js +++ b/modules/ppcp-settings/resources/js/data/onboarding/actions.js @@ -1,3 +1,13 @@ +/** + * Action Creators: Define functions to create action objects. + * + * These functions update state or trigger side effects (e.g., async operations). + * Exported functions must have unique names across all store modules. + * Actions are categorized as Transient, Persistent, or Side effect. + * + * @file + */ + import ACTION_TYPES from './action-types'; /** diff --git a/modules/ppcp-settings/resources/js/data/onboarding/controls.js b/modules/ppcp-settings/resources/js/data/onboarding/controls.js index abe9f73f9..729df17c6 100644 --- a/modules/ppcp-settings/resources/js/data/onboarding/controls.js +++ b/modules/ppcp-settings/resources/js/data/onboarding/controls.js @@ -1,3 +1,12 @@ +/** + * Controls: Implement side effects, typically asynchronous operations. + * + * Controls use ACTION_TYPES keys as identifiers to ensure uniqueness. + * They are triggered by corresponding actions and handle external interactions. + * + * @file + */ + import { select } from '@wordpress/data'; import { apiFetch } from '@wordpress/api-fetch'; diff --git a/modules/ppcp-settings/resources/js/data/onboarding/hooks.js b/modules/ppcp-settings/resources/js/data/onboarding/hooks.js index d74fa2010..9e5f1d179 100644 --- a/modules/ppcp-settings/resources/js/data/onboarding/hooks.js +++ b/modules/ppcp-settings/resources/js/data/onboarding/hooks.js @@ -1,3 +1,13 @@ +/** + * Hooks: Provide the main API for components to interact with the store. + * + * These encapsulate store interactions, offering a consistent interface. + * Hooks simplify data access and manipulation for components. + * Exported hooks must have unique names across all store modules. + * + * @file + */ + import { useSelect, useDispatch } from '@wordpress/data'; import { PRODUCT_TYPES, STORE_NAME } from '../constants'; diff --git a/modules/ppcp-settings/resources/js/data/onboarding/reducer.js b/modules/ppcp-settings/resources/js/data/onboarding/reducer.js index a037928f3..41a57c578 100644 --- a/modules/ppcp-settings/resources/js/data/onboarding/reducer.js +++ b/modules/ppcp-settings/resources/js/data/onboarding/reducer.js @@ -1,3 +1,14 @@ +/** + * Reducer: Defines store structure and state updates for this module. + * + * Manages both transient (temporary) and persistent (saved) state. + * Each module uses isolated memory objects to prevent conflicts. + * The initial state must define all properties, as dynamic additions are not supported. + * Reducers are separated per module to avoid conflicts in state management. + * + * @file + */ + import { createReducer, createSetters } from '../utils'; import ACTION_TYPES from './action-types'; diff --git a/modules/ppcp-settings/resources/js/data/onboarding/resolvers.js b/modules/ppcp-settings/resources/js/data/onboarding/resolvers.js index 7009ecff4..7d79e35e6 100644 --- a/modules/ppcp-settings/resources/js/data/onboarding/resolvers.js +++ b/modules/ppcp-settings/resources/js/data/onboarding/resolvers.js @@ -1,3 +1,13 @@ +/** + * Resolvers: Handle asynchronous data fetching for the store. + * + * These functions update store state with data from external sources. + * Each resolver corresponds to a specific selector but must have a unique name. + * Resolvers are called automatically when selectors request unavailable data. + * + * @file + */ + import { dispatch } from '@wordpress/data'; import { __ } from '@wordpress/i18n'; import { apiFetch } from '@wordpress/data-controls'; diff --git a/modules/ppcp-settings/resources/js/data/onboarding/selectors.js b/modules/ppcp-settings/resources/js/data/onboarding/selectors.js index a2a16af13..89c62a360 100644 --- a/modules/ppcp-settings/resources/js/data/onboarding/selectors.js +++ b/modules/ppcp-settings/resources/js/data/onboarding/selectors.js @@ -1,3 +1,13 @@ +/** + * Selectors: Extract specific pieces of state from the store. + * + * These functions provide a consistent interface for accessing store data. + * They allow components to retrieve data without knowing the store structure. + * Exported functions must have unique names across all store modules. + * + * @file + */ + import { STORE_KEY } from './constants'; const EMPTY_OBJ = Object.freeze( {} );