[WIP] first draft of client directory and overall coding style docs

client-dir-structure.md

@@ -0,0 +1,85 @@
+# Goals
+- readability
+- accessibility of related files
+- separation of path-associated Views from their constituent Components
+- intuitive navigation of grouped components
+
+# Guidelines
+- always use absolute imports from `./src/path/to/import`
+
+# Structure
+```sh
+src/
+  - views/
+    - ViewName.jsx
+    - ViewName/
+  - components/
+    - ViewName/
+    - UI/
+    - Utility/
+    - Static/
+  - queries/
+  - mutations/
+  - utils/
+  - assets/
+  - styles/
+  - App.jsx
+  - index.js
+
+```
+- `utils/`: shared non component utilities (formatting)
+- `styles/`: shared SCSS and config
+- `assets/`: shared static assets
+- `App.jsx`: import `views/` for Router
+- `index.js`: root export with wrappers and configuration
+
+## Queries and Mutations
+- only used in the component: write in the component file
+- shared by multiple components: write in `queries/` or `mutations/`
+  - `queryName.js` or `mutationName.js`
+- label the queries or mutations for easier debugging
+```js
+query DescriptiveLabelName($input_name: input_type) {
+  query(input: $input) {
+    return_field
+  }
+}
+
+mutation DescriptiveActionName($input_name: input_type) {
+  mutation(input: $input) {
+    return_field
+  }
+}
+```
+
+### mutations
+- when calling a mutation of data owned by and returning a Type always request back
+  - the `id` field
+  - the fields that were updated
+- this will keep the cache consistent and remove the need for callback-based updates
+
+## `views/`
+- `/ViewName.jsx`
+  - imports children and renders a path-associated view
+- `/ViewName/`
+  - `index.jsx`: same as `ViewName.jsx`
+  - include non-component support files specific to the view (custom styling, assets, animations)
+
+## `components/`
+- `ViewName/`: components only used in a single View
+- `Category/`: shared components under a common category
+  - `UI/`: base UI components (buttons, cards)
+  - `Utility/`: utility components (`<Request />`, `<Modal />`)
+  - `Static/`: static homepage components
+- `ComponentName/`: complex shared components not necessarily under a view or category (rare)
+
+### component directories
+- each directory should have a default export from `index.jsx`
+- components should contain one SCSS file per depth of directory
+
+### component definitions within the directories
+- components should mostly remain in flat `.jsx` files
+- if a component grows in complexity to require sub-components create a dir by its name to contain them
+  - follows component directory guidelines
+  - this new dir should now contain the SCSS styles for itself and sub-components
+  - **rarely extend deeper than one sub-directory component**

code-style.md

@@ -0,0 +1,78 @@
+# Chingu Coding Style
+- updated 11/4/18
+
+# Core
+- base of AirBnB coding style
+- readability and ease of writing
+- consistency across codebases and authors
+- rejecting rules that needlessly restrict coding
+
+# Basics
+- 2 spaces (not tabs)
+- semicolons to end all statements
+  - no inline statement chaining
+- maximum column length of 100 characters
+- new lines at the ends of each file
+
+# Trailing Commas
+
+# Parameter lists
+If fitting in less than 100 column length: inline
+Extending beyond 100 column length: multi-line (trailing comma)
+
+# Destructuring
+Parameter lists
+One param: destructuring ok
+Multi param: param name => destructure in first lines of function body
+Column length: break across multi line if extending beyond 100
+
+# JSDocs
+- define above all classes and functions / methods
+- first line should be `updated: MM/DD/YY`
+  - update this line whenever params or props are changed
+
+## minimum
+- @param [@prop for Components]
+  - `@param paramName {type} description of param expected values and/or usage
+  - list required params first
+  - skip a line and use `-- OPTIONAL --` as a line separator before the optional params
+- @return [not needed for Components]
+
+## optional
+- `@example` (skip line then write sample usage)
+
+## object properties
+- `@param objectName {type} description of object parameter as a whole`
+- `@param objectName.propertyName {type} description of object param property`
+
+## example
+```js
+/**
+ * updated: 10/22/18
+ * 
+ * @prop {array} questions array of Question data objects for rendering
+ * @prop {string} purpose Dynamic Form collection name (for form data persistence)
+ * @prop {array} questions array of Dynamic Question objects
+ * 
+ * -- OPTIONAL --
+ * @prop {object} initialData CAUTION: very delicate - must match expected shape EXACTLY. Provide initial form_data. 
+ * @prop {object} hiddenData values for 'hidden' input types -> { field_name: value }
+ * @prop {bool} persistence controls storing form data in LS onFormChange
+ * @prop {func} onSubmit wrapper callback for handling submit behavior
+ * @prop {func} onValidate callback for field level control of 'disabled' flag. expects boolean return
+ * @prop {func} onInputChange observation-only handler with args (field_name, value, form_data)
+ * @prop {func} customComponents custom input_type components (merged with defaults, precedence to custom components)
+ */
+```
+
+
+
+# Client PropTypes
+In class def using static propTypes
+- define expected shapes
+- use `isRequired`
+## PropType functions for expected values
+- use proptype functions for controlling expected values
+- throw useful error message
+```js
+```