From c36f16562d13610b720f058389f2ca7b247726ca Mon Sep 17 00:00:00 2001
From: Leni Kadali <52788034+lenikadali@users.noreply.github.com>
Date: Tue, 26 Nov 2024 23:44:01 +0300
Subject: [PATCH] docs: Add component guidelines for PlaceCal (#2648)

---
 app/components/guidelines.md | 48 ++++++++++++++++++++++++++++++++++++
 1 file changed, 48 insertions(+)
 create mode 100644 app/components/guidelines.md

diff --git a/app/components/guidelines.md b/app/components/guidelines.md
new file mode 100644
index 000000000..6c3b26771
--- /dev/null
+++ b/app/components/guidelines.md
@@ -0,0 +1,48 @@
+# Component Guidelines
+
+## About
+
+This serves as the reference documentation for components in PlaceCal (how to generate them etc).
+
+In case you find something unclear, inaccurate or out of date, please feel to create a new issue describing what needs doing :smile:
+
+## Technical Details
+
+PlaceCal currently uses [ViewComponent](https://viewcomponent.org/) for all new components. Previously the gem [`mountain_view`](https://github.com/devnacho/mountain_view) was used but has since been deprecated and is in the process of being removed (see [this issue](https://github.com/geeksforsocialchange/PlaceCal/issues/2270))
+
+### Creating a new component
+
+[Follow the instructions](https://viewcomponent.org/guide/generators.html) over on the ViewComponents' documentation to generate a new component.
+
+### Folder structure
+
+For simple components, the component and its template should appear in `app/components/` as shown below:
+
+```
+components
+├── address_component.rb            # Component definition
+└── address_component.html.erb      # HTML template
+```
+
+For more complex components, they should have their own folder. Using the above as an example, the folder structure would look like so:
+
+```
+components
+├── address_component.rb            # Component definition
+└── address_component
+    ├── address_component.html.erb  # HTML template
+    ├── address_component.js        # Optional: Stimulus controller
+    └── address_component.scss      # Optional: Component-namespaced scss
+```
+
+### Linting
+
+Components follow the same conventions as regular Ruby on Rails code. RuboCop gets run as part of our [pre-commit](https://github.com/geeksforsocialchange/PlaceCal/blob/main/package.json#L33-L36) hooks so any violations found will automatically be fixed. Whatever can't be fixed, you'll have to fix yourself :grinning:
+
+### Testing
+
+When testing components, please make sure that you write unit tests that only exercise the component's rendering logic. This means that no usage of VCR or an overly elaborate test data setup within the component test.
+
+### Il8n
+
+Localization is handled by the files in the `config/locales` directory.