Some base documentation

Signed-off-by: guido <[email protected]>

Update api.md
Update api.md

README.md

@@ -8,12 +8,13 @@ more Post Types but also, to search for Terms belonging to one or more Taxonomie
 ## Table of Content
 
 1. Installation
-2. Api
-3. Components
-4. Hooks
-5. Logging
-6. Integration
-7. Storage
+2. Development
+3. Api
+4. Components
+5. Hooks
+6. Logging
+7. Integration
+8. Storage
 
 ## License
 

docs/api.md

@@ -0,0 +1,50 @@
+# Api
+
+The `api` define a `fetch` function which is there to hide the WordPress Fetch API. The reason behind this decision lies on the fact that we might want to add middlewares to the request in the future or introducing some global data manipulation.
+
+The package provide then the following functions to interact with the WordPress API:
+
+## `searchEntities`
+
+This function is a wrapper for the Search Endpoint of the WordPress API. It will return a `Set` of entities matching the search query.
+
+The possible query arguments are specified by the `EntitiesSearch.QueryArguments` type, an interface you can expand to add more arguments.
+
+This function is not directly consumed by the components and it is not intended to be used internally. The idea is to follow the Tell don't Ask principle and let the consumer specify how to search the Entities.
+
+Below a possible example of it's usage related to a component:
+
+```js
+// my-component.tsx
+type Search = EntitiesSearch.SearchEntitiesFunction<string, string>;
+type Props = {
+    search: Search
+}
+
+const MyComponent (props: Props) => {
+    const [entities, setEntities] = useState<Set>(new Set());
+
+    useEffect(() => {
+        props
+            .search(
+                'my search phrase',
+                'post',
+                new Set(['page']),
+                {
+                    per_page: 10,
+                    _fields: ['slug', 'title']
+                }
+            )
+            .then(setEntities);
+    }, []);
+
+    // Do something with the entities
+}
+
+// index.tsx
+import {searchEntities} from '@wp-entities-search';
+
+root.render(<MyComponent search={searchEntities} />);
+```
+
+NOTE: The function does not handle possible request exceptions.

docs/development.md

@@ -0,0 +1,53 @@
+# Development
+
+The first thing to do is to clone the repository and install the dependencies:
+
+```bash
+$ git clone [email protected]:widoz/wp-entities-search.git
+$ cd wp-entities-search
+$ composer install
+$ yarn install
+```
+
+After we have installed the dependencies we need to build the assets:
+
+```bash
+$ yarn build
+```
+
+or alternatively we can run the dev script to compile the assets with source maps:
+
+```bash
+$ yarn build:dev
+```
+
+## The Environment
+
+The project is making use of `@wordress/env` as a local environment to develop the solution.
+
+To start the environment we need to run the following command:
+
+```bash
+$ yarn wp-env start
+```
+
+This will install WordPress and will set the current project as a plugin. The package contain a E2E module used by the plugin to help with the development. The module register two blocks; one for the Custom Post Type and one for the Custom Taxonomy.
+
+The WordPress installation is provided without content. To add some we can run the following commands from the root of the project:
+
+```bash
+./scripts/create-posts.sh --num 20 --title Post --type post
+./scripts/create-posts.sh --num 20 --title Page --type page
+./scripts/create-terms.sh --num 20 --name Category --taxonomy category
+./scripts/create-terms.sh --num 20 --name Tag --taxonomy post_tag
+```
+
+## Basic Concepts
+
+The package implement a Value Object to handle immutability called `Set`. This is the main implementation used by the package to work with external data. Whenever a data is fetched from the WordPress API it will be wrapped in a `Set` object, but also all components and functions deal with this implementation. In a summary, every data entering the package will be wrapped in a `Set` object.
+
+Another commonly used data structure is the `ControlOption` which is not directly consumed but define the type of the `Set`. It should not be consumed directly but through the `Set` api.
+
+## Usage Examples
+
+As mentioned above the package have a E2E module which register two blocks to test the functionality. The first block is a Custom Post Type and the second one is a Custom Taxonomy. The two blocks are using the same component to render the results, you can get some insight about the usage from them.

docs/installation.md

@@ -0,0 +1,18 @@
+# Installation
+
+This package is available as a composer library and as a npm package.
+
+You're not forced to use both, you can use only one of them. The php implementation is using [Modularity](https://github.com/inpsyde/modularity) a modular [PSR-11](https://github.com/php-fig/container) implementation for WordPress Plugins, Themes and Libraries.
+The JavaScript implementation is composed of a set of utilities and React components to help you build your own UI.
+
+## Composer
+
+To install the package as part of the composer dependencies of your project, run the following command:
+
+```bash
+composer require widoz/wp-entities-search
+```
+
+## NPM
+
+Not Ready Yet