Merge pull request #132 from aiven/add-coral-readme

Add coral readme

coral/README.md

@@ -0,0 +1,88 @@
+# 🪸 Klaw's new frontend app
+
+- Please be aware of our [Code of Conduct](../CODE_OF_CONDUCT.md) ❤️
+
+## About
+
+`/coral` contains a React app. It's the rewrite of the existing Klaw frontend. 
+
+## Installation and usage 
+
+ℹ️ Coral uses `pnpm run` as a package manager. Read in their official documentation [how to install](https://pnpm.io/installation) it. 
+
+- navigate to this directory
+- run `pnpm install`
+- run `pnpm dev` to start the frontend app in development mode
+
+### Usage: How to run the app
+
+ℹ️ You can see all our scripts in the [`package.json`](package.json).
+You can also run `pnpm` in your console to get a list of all available scripts.
+
+#### Scripts used and what they execute
+- `build`: builds the frontend app for production
+- `dev`: starts the frontend app for development
+- `lint`: runs a code format check and if no error is found, lints the code. 
+  - the linting script does not mutate your code. See [Linting and code formatting](#linting-and-code-formatting) for more info.
+- `preview`: builds a preview production build _locally_
+- `reformat`: runs the code formatter (prettier) and reformat all code
+- `test-dev`: runs all test tests related to changed files in a watch mode
+- `test`: runs all tests one time
+- `tsc`: runs the TypeScript compiler
+
+## Tech stack
+
+### App development
+- TypeScript - 📃 [documentation](https://www.typescriptlang.org/) | 🐙 [repository](https://github.com/microsoft/TypeScript)
+- React - 📃 [documentation](https://reactjs.org/docs/getting-started.html) | 🐙 [repository](https://github.com/facebook/react/)
+- Vite - 📃 [documentation](https://vitejs.dev/guide/) | 🐙 [repository](https://github.com/vitejs/vite)
+
+### Testing
+- Jest - 📃 [documentation](https://jestjs.io/docs/getting-started) | 🐙 [repository](https://github.com/facebook/jest)
+- React Testing Library - 📃 [documentation](https://testing-library.com/docs/react-testing-library/intro/) | 🐙 [repository](https://github.com/testing-library/react-testing-library)
+
+📃 You can find more detailed information about testing in our docs for [Frontend Testing](docs/frontend-testing.md).
+
+### Linting and code formatting
+How we keep our app's codebase looking consistent and nice 💅🏼
+
+- [Prettier](https://prettier.io/) for code formatting
+- [ESlint](https://eslint.org/) and various plugins for linting
+
+The script `lint` runs a prettier check and eslint after. It does not mutate your code in any way. If you want to format your code or let eslint fix it for you, you can run:
+
+1. First: `pnpm reformat` (prettier formatting)
+2. After that: `pnpm eslint --fix` (eslint in fix mode)
+
+ℹ️ It's convenient to let prettier and eslint auto-format your code "on save" by your IDE or editor.
+
+## Styling 
+
+We use the component library of Aiven's design system:
+  - 📃 [documentation](https://aiven-ds.netlify.app/)
+  - the repository is open source, but `private` at the moment
+
+As a rule, please don't use css classes from the design system. All styles should be created by using the existing components and their properties. 
+
+__🔄 Work in progress related to styles__
+- We plan adding css variables based on the design system's tokens.
+- We plan having a custom theme for Klaw. This will be used instead of the Aiven theme.
+
+## Documentation
+
+We've a more detailed document about our thinking about [Docmentation](docs/documentation.md). 
+
+### Tip
+You can use `alex` ( 📃 [documentation]( https://alexjs.com/) | 🐙 [repository](https://github.com/get-alex/alex)) as an **optional** linting tool. It checks text documents and highlights language that potentially could be insensitive or inconsiderate. 
+
+- run it with `pnpm --silent dlx alex` to lint text files.  
+
+
+## More detailed documentation
+
+We provide more documentation on:
+
+- Our commitment to [Accessibility](docs/accessibility.md)
+- Detailed overview of the [Directory Structure](docs/directory-structure.md)
+- Our thinking about [Docmentation](docs/documentation.md)
+- More information about [Frontend Testing](docs/frontend-testing.md)

coral/docs/directory-structure.md

@@ -113,7 +113,7 @@ Contains assets like scss and images.
 
 #### `components`
 
-Contains all UI elements in form of React components that we use in different places of the app. The components should be simple and easy to reuse. They have to be agnostic from any business logic.
+Contains all UI elements in form of React components that we use in different places of the app. The components should be clean, and uncomplicated to reuse. They have to be agnostic from any business logic.
 
 - top level `index.ts` file to export components and act as an public API.
 

coral/docs/documentation.md

@@ -17,7 +17,7 @@ First things first - what kind of work would this add for us:
 That's it for now! We can iterate over that in the process and see where we want to make tweaks.
 
 
-## Users and use cases for documenation
+## Users and use cases for documentation
 
 - external companies and developer
     - they use klaw as a product
@@ -66,7 +66,7 @@ That's it for now! We can iterate over that in the process and see where we want
 
 ### Manual checks
 - write-good linter
-- AlexJS linter
+- ✅ AlexJS linter optional
 - Hemingway Editor
 
 ### Useful links for later

coral/docs/frontend-testing.md

@@ -24,7 +24,7 @@ We use [Jest](hhttps://jestjs.io/docs/) as test runner in Frontend in general an
 
 **⚠️ We use and need this library only for testing React components.**
 
-`Dom testing library` is an opinionated library, which makes it easy to follow a specific way to write test. It’s best used with jest-dom and the custom [jest-dom matchers](https://github.com/testing-library/jest-dom#readme). The combination of both leads to nice readable tests!
+`Dom testing library` is an opinionated library, which supports a specific way of writing test. It is well documented and supports us in having a consistent code base. It’s best used with jest-dom and the custom [jest-dom matchers](https://github.com/testing-library/jest-dom#readme). The combination of both leads to nice readable tests!
 
 [react-testing-library](https://testing-library.com/docs/react-testing-library/intro) is a react-adapter for the [DOM testing-library](https://testing-library.com/docs/). 
 

coral/package.json

@@ -13,12 +13,12 @@
     "build": "tsc && vite build",
     "dev": "vite",
     "lint": "prettier --check src && eslint .",
+    "lint-staged": "lint-staged",
     "prepare": "cd .. && husky install coral/.husky",
     "preview": "vite preview",
     "reformat": "prettier --write src",
     "test": "jest",
     "test-dev": "jest --watch",
-    "lint-staged": "lint-staged",
     "tsc": "tsc"
   },
   "lint-staged": {
@@ -46,8 +46,8 @@
     "eslint": "^8.25.0",
     "eslint-config-prettier": "^8.5.0",
     "eslint-plugin-react": "^7.31.10",
-    "identity-obj-proxy": "^3.0.0",
     "husky": "^8.0.1",
+    "identity-obj-proxy": "^3.0.0",
     "jest": "^29.2.1",
     "jest-environment-jsdom": "^29.2.1",
     "lint-staged": "^13.0.3",
@@ -57,5 +57,9 @@
     "ts-node": "^10.9.1",
     "typescript": "^4.6.4",
     "vite": "^3.1.0"
+  },
+  "alex": {
+    "noBinary": true,
+    "profanitySureness": 1
   }
 }