FRS-2 React Components (#2)

* Basic React Hook Form implementation. * Basic board component with hardcoded board signature * Created constant and utils file * Setup hardcoded server action. * Removed unused global css * Updated README.md * EOL
stuart-bradley · Feb 13, 2024 · 1504d9e · 1504d9e
1 parent 3077f14
commit 1504d9e
Show file tree

Hide file tree

Showing 18 changed files with 2,726 additions and 289 deletions.
diff --git a/.gitignore b/.gitignore
@@ -34,3 +34,6 @@ yarn-error.log*
 # typescript
 *.tsbuildinfo
 next-env.d.ts
+
+# Webstorm
+.idea
diff --git a/README.md b/README.md
@@ -10,12 +10,15 @@ Full documentation can be found in the [documentation](documentation) folder.
 
 ## Dependencies
 
-- Next.js `14.1.0`
-- React `18.*`
+- [Next.js](https://nextjs.org/) `14.1.0`
+- [React](https://react.dev/) `18.*`
+- [react-hexgrid](https://github.com/Hellenic/react-hexgrid) `2.0.0@beta`
+  - [emotion](https://emotion.sh/docs/introduction) `11.11.3` (dependency not imported by react-hexgrid)
 
 ### Dev Dependencies
 
-- Typescript `v5.*`
-- Tailwind CSS `v3.3.*`
-- ESLint `8.56.0`
-- Prettier `3.2.5`
+- [Typescript](https://www.typescriptlang.org/) `v5.*`
+- [Tailwind CSS](https://tailwindcss.com/) `v3.3.*`
+- [ESLint](https://eslint.org/) `8.56.0`
+- [Prettier](https://prettier.io/) `3.2.5`
+- [pre-commit](https://pre-commit.com/) `3.5.0`
diff --git a/documentation/decision_logs/decision_log_form_library.md b/documentation/decision_logs/decision_log_form_library.md
@@ -1,7 +1,37 @@
 # Decision Log - Form Library
 
-This document outlines the decision process for determining which Form library to use for the project.
+This document outlines the decision process for determining which form library to use for the project. The following
+projects are under consideration:
+
+- [Generic HTML](https://react.dev/reference/react-dom/components/form)
+- [React Hook Form (RHF)](https://react-hook-form.com/)
+- [Shadcn](https://ui.shadcn.com/)
 
 ## Comparison
 
+| Generic HTML                                                          | React Hook Form                                                                 | Shadcn                                             |
+| --------------------------------------------------------------------- | ------------------------------------------------------------------------------- | -------------------------------------------------- |
+| [ + ] Doesn't require additional libraries                            | [ + ] Widely used by the community                                              | [ + ] Built ontop of React Hook Form               |
+| [ - ] Doesn't include functionality such as input dependency natively | [ + ] Additional functionality such as schema validation and input dependencies | [ + ] Includes Component library                   |
+|                                                                       | [ + ] Uses standard HTML tags                                                   | [ + ] Integrated with Tailwind CSS                 |
+|                                                                       |                                                                                 | [ - ] Component complexity hides RHF functionality |
+
+While the Form component is relatively simple, and does not require validation, the types of algorithms possible is
+dependent on the selected expansions. Therefore, some form of input management is required. RNF provides this via
+`watch`.
+
+In terms of layout and styling, having a Tailwind CSS compatible set of Components is likely to speed up development.
+RHF integrates well with a number of component libraries, but Shadcn requires no additional work. However, Shadcn
+Components are overly verbose and complex and hide some of the RHF functionality in a way that decreases development
+speed even when custom component creation time is taken into consideration.
+
 ## Outcome
+
+**React Hook Form** has been chosen as the form library.
+
+### Additional Suggested Functionality
+
+Two systems may help speed up the development of custom components and should be explored:
+
+- [@tailwindcss/forms](https://github.com/tailwindlabs/tailwindcss-forms): Basic styles for form components.
+- [Flowbite](https://flowbite.com/): Open source component library for Tailwind that provides styling examples.
diff --git a/documentation/decision_logs/decision_log_hexagon_grid_library.md b/documentation/decision_logs/decision_log_hexagon_grid_library.md
@@ -0,0 +1,34 @@
+# Decision Log - Hexagon Grid Library
+
+This document outlines the decision process for determining which hexagon grid library to use for the project. The following
+projects are under consideration:
+
+- [HTML5 Canvas](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/canvas)
+- [Konvas JS](https://konvajs.org/)
+- [Honeycomb](https://abbekeultjes.nl/honeycomb/)
+- [react-honeycomb](https://github.com/taraspolovyi/react-honeycomb)
+- [react-hexgrid](https://github.com/Hellenic/react-hexgrid)
+
+## Comparison
+
+| HTML5 Canvas                                      | Konvas JS                                                                                             | Honeycomb                                                                                 | react-honeycomb                                            | react-hexgrid                                                                  |
+| ------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------ |
+| [ + ] No additional library required              | [ + ] Declarative React Canvas                                                                        | [ + ] Grid can be defined instead of individual hexagons                                  | [ + ] Grid can be defined instead of individual hexagons   | [ + ] Grid can be defined instead of individual hexagons                       |
+| [ - ] Requires specific math drawing calculations | [ + ] Includes a huge range of additional functionality (events, animations, data serialisation, etc) | [ + ] Includes `json` serialisation                                                       | [ - ] Does not allow for Catan shaped grids                | [ + ] Uses SVG to create auto scaling grids                                    |
+|                                                   | [ - ] Requires specific math drawing calculations                                                     | [ - ] Does not include native image output (includes examples with third-party libraries) | [ - ] Single contributor, does not appear to be maintained | [ + ] Includes examples for Catan style grids                                  |
+|                                                   |                                                                                                       |                                                                                           |                                                            | [ ~ ] Last release in 2022, but it has 300 stars and multiple contributors     |
+|                                                   |                                                                                                       |                                                                                           |                                                            | [ - ] Only uses cubic coordinates (which were not used in the original project |
+
+In the original project, the grid math was a significant time sink, and a large proportion of the overall code.
+Interestingly, it appears that a number of projects have sprung up since then to try and handle this specific use-case,
+often referencing the [same document](https://www.redblobgames.com/grids/hexagons/) that was used in the original project.
+
+Therefore, it is probably prudent to ignore the general canvas solutions and pick a library that handles the coordinate
+geometry behind the scenes.
+
+With that in mind, `react-hexgrid` looks the most promising. However, it should be noted that the cubic coordinate
+system will require additional translation of the original algorithms.
+
+## Outcome
+
+**react-hexgrid** has been chosen as the hexagon grid library.
diff --git a/documentation/decision_logs/decision_log_js_framework.md b/documentation/decision_logs/decision_log_js_framework.md
@@ -3,8 +3,8 @@
 This document outlines the decision process for determining which JS library to use for the project.
 The following projects are under consideration:
 
-- React
-- React + Next.js
+- [React](https://react.dev/)
+- [React + Next.js](https://nextjs.org/)
 
 ## Comparison
 

diff --git a/documentation/functional_requirements_specification.md b/documentation/functional_requirements_specification.md
@@ -46,8 +46,45 @@ application.
 
 #### 2.2 Form
 
+The Form Component consists of the following fields:
+
+- An expansions group checkbox (or multi-select).
+- An algorithm selector.
+  - This will have dynamic options based on the expansions selected.
+- A number of players radio group.
+
+Due to the requirement for dynamic select, `React Hook Form` (see [Decision Log](decision_logs/decision_log_form_library.md))
+should be used to create the form.
+
+The form should submit a `json` payload to the API endpoint defined in 4.
+
 #### 2.3 Canvas
 
+The Canvas Component should accept a serialised board identifier (see 4.2) and generate a Settlers of Catan board from
+this input.
+
+There are a number of options for drawing in HTML elements, the most promising of which is `react-hexgrid`
+(see [Decision Log](decision_logs/decision_log_hexagon_grid_library.md)).
+
+##### Board Styling
+
+To keep things simple initially, individual hexes can be coloured based on their corresponding tiles
+(colours were defined in the [original project](https://github.com/stuart-bradley/Catan-Randomiser/blob/master/CatanBackend.py)):
+
+- Wheat: ![#ccb804](https://placehold.co/15x15/ccb804/ccb804.png) `#ccb804`
+- Sheep: ![#a5c13f](https://placehold.co/15x15/a5c13f/a5c13f.png) `#a5c13f`
+- Rock: ![#7f7f7f](https://placehold.co/15x15/7f7f7f/7f7f7f.png) `#7f7f7f`
+- Tree: ![#3a7044](https://placehold.co/15x15/3a7044/3a7044.png) `#3a7044`
+- Brick: ![#c7490a](https://placehold.co/15x15/c7490a/c7490a.png) `#c7490a`
+- Desert: ![#fceac4](https://placehold.co/15x15/fceac4/fceac4.png) `#fceac4`
+- Gold: ![#ffcf00](https://placehold.co/15x15/ffcf00/ffcf00.png) `#ffcf00`
+- Ocean: ![#3daace](https://placehold.co/15x15/3daace/3daace.png) `#3daace`
+
+Some of the colours have been modified to increase differentiation. It may be advisable to move to `svg` icons;
+no full free set appears to exist, so this may require creation for the project.
+
+Tiles have also been named so that each tile can have a unique first letter identifier.
+
 ### 3 Board Generation Algorithms
 
 ### 4 API
@@ -63,3 +100,14 @@ application.
 #### 6.1 Docker
 
 #### 6.2 Kubernetes
+
+## Appendix
+
+### A: Conversion of RBG Coordinates to Hexcodes
+
+```python3
+# Wheat, Sheep, Ore, Wood, Brick, Desert, Gold, Ocean
+rgb_list = [[0.92,0.72,0.26], [0.65,0.76,0.25], [0.5,0.5,0.5], [0.23,0.44,0.27], [0.9,0.61,0.32], [0.99,0.92,0.77], [0.95,0.95,0], [0.24,0.67,0.81]]
+for (r,g,b) in rgb_list:
+    print('%02x%02x%02x' % (int(r*255), int(g*255), int(b*255)))
+```