more information about DESIGN desicions

1 files changed, 68 insertions, 6 deletions

diff --git a/DESIGN.md b/DESIGN.md
index accf7ee..100ccf0 100644
--- a/DESIGN.md
+++ b/DESIGN.md
@@ -10,7 +10,8 @@
 
 * The user must provide BACKEND_URL or BACKOFFICE_URL will use as default
 
-* Token for querying the backend will be saved in localStorage under backend-token-${name}
+* Token for querying the backend will be saved in localStorage under
+  backend-token-${name}
 
 # HTTP queries to the backend
 
@@ -38,23 +39,84 @@ There are categories of queries:
 
 In this scenario, a failed request will make the app flow to break.
 
-When receiving an notfound error a generic not found page will be shown. If the BACKEND_URL points to a default instance it should send the user to create the instance.
+When receiving an not found error a generic not found page will be shown. If the
+BACKEND_URL points to a default instance it should send the user to create the
+instance.
 
 When receiving an unauthorized error, the user should be prompted with a login form.
 
-When receiving an another error (400 < http status < 600), the login form should be shown with an error message using the hint from the backend.
+When receiving an another error (400 < http status < 600), the login form should
+be shown with an error message using the hint from the backend.
 
-On other unexpected error (like network error), the login form should be shown with and error message.
+On other unexpected error (like network error), the login form should be shown
+with and error message.
 
 ## CRUD operation (async)
 
-In this scenario, a failed request does not break the flow but a message will be prompted.
+In this scenario, a failed request does not break the flow but a message will be
+prompted.
 
 # Forms
 
-For every form [FormProvider](./DESIGN.md) should be use
+All the input components should be placed in the folder `src/components/from`.
+
+The core concepts are:
+
+ * <FormProvider<T> /> places instead of <form /> it should be mapped to an
+   object of type T
+
+ * <Input /> an others: defines UI, create <input /> DOM controls and access the
+   form with useField()
+
 
 # Custom Hooks
 
+All the general purpose hooks should be placed in folder `src/hooks` and tests
+under `tests/hooks`. Starts with the `use` word.
+
 # Contexts
 
+All the contexts should be places in the folder `src/context` as a function.
+Should expose provider as a component `<XxxContextProvider />` and consumer as a
+hook function `useXxxContext()` (where XXX is the name)
+
+# Components
+
+Type of components:
+
+ * main entry point: src/index.tsx, mostly initialization
+
+ * routing: in the `src` folder, deciding who is going to take the work. Thats
+   when the page is loading but also create navigation handlers
+
+ * pages: in the `paths` folder, setup page information (like querying the
+   backend for the list of things), handlers for CRUD events, delegated routing
+   to parent and UI to children.
+
+Some others guidelines:
+
+ * Hooks over classes is preferred
+
+ * Components that are ready to be reuse on any place should be in
+   `src/components` folder
+
+ * Since one of the build target is a single bundle with all the pages, we are
+   avoiding route based code splitting
+   https://github.com/preactjs/preact-cli#route-based-code-splitting
+
+
+# Testing
+
+Every components should have examples using storybook (xxx.stories.tsx). There
+is an automated test that check that every example can be rendered so we make
+sure that we not add a regression.
+
+Every hook should have examples under `tests/hooks` with common usage trying to
+follow this structure:
+
+ * (Given) set some context of the initial condition
+
+ * (When) some action to be tested. May be the initialization of a hook or an
+   action associated with it
+
+ * (Then) a particular set of observable consequences should be expected