watterblock =========== This project is a web based notepad specialized for keeping score in the game of watten. It is not an online version of the game, and it has no social features. It is only intended to replace a piece of paper. Principles ---------- This is a hobby project, and I don't want to spend a lot of time maintaining it. Therefore, the following principles will guide its development. 1. **No feature creep:** For the time beeing, this project will not grow beyond being a simple score keeping tool. Logical expansions, like synching a session between users / devices, will not be implemented, because they would be too complicated for the time I intend to spend on maintenance. 2. **Simple and stable dependencies:** I have learned in past projects that fast moving environments, like many modern JS frameworks, are very tedious to keep up with. Therefore all libraries must be stable and consistent. Also, I don't want to spend much time wrangling npm. Therefore all dependencies must be vendorable as a couple of files. 3. **Browser based development:** I don't want to spend a lot of time on build tools, transpilers, and similar things. All code has to be able to run in the browser in the form it is written. All dev tools (like the testing framework) have to be able to run in the browser. 4. **Targetting Baseline:** The limited time for maintenance means I won't be able to do testing for all browser/version/os tripples. Instead, I'll target "baseline widely available" and rely on it's correctness for portability. I'll also use features that are "baseline newly available", but only with feature checking, which I'll only do for them. 5. **Extensive tests:** I don't want to spend a lot of time on bug hunting, therefore everything that can be tested automatically should be. 6. **Good documentation:** I'll most certainly forget how some things work at some point. Thus it is paramount to keep a good documentation, so I won't have to read through everything again. ### Trade-offs The principles above provide structure and certain advantages to the project. However, they also have a cost. While I have deemed it to be worthwhile in this case, I consider it important to at least document the disadvantages. 1. No access to a lot of JavaScripts modern ecosystem. 2. No access to compile time features such as actual typechecking. 3. More network load that strictly necessary. 4. Less performance than what would be possible. ### Violations In some cases I have deemed it acceptable to deviate from the above principles. These are the following: 1. The `jsconfig.json` file is a build tool configuration file. It shouldn't be needed, as the project doesn't use any build tools. However, it allows the LSP to be more usefull, thus justifying its existence. 2. Nested CSS. It is so much more managable than repeating the same selectors over and over. Keep in mind that the principles are to make the maintenence of this side project viable for me in the long term. In ~4 months from this writing (2026-03-04) they become baseline widely available and I would want to rewrite all the styles then. I deem this to be a worthwhile trade-off. 3. The `:has()` CSS pseudo-class. While it's not as useful, it becomes baseline widely available at the same time as nested CSS. Might as well use it then, as a non-supporting browser can't be used either way. Structure --------- 1. `index.html` is the main HTML file bootstraping everything. 2. `index.js` is the JS file bootstraping the actual behaviour. 3. `style.css` is the CSS file bootstraping the actual styles. It also contains the colors and some helper classes. 4. `models/` contains the "business logic", i.e. classes representing the current state and its behaviour at runtime. 5. `data/` contains components to store that state in persistent storage for later access. 6. `ui/` contains the user interface. The `.js` files contain mithril components, the `.css` files their styles. 7. `service-worker.js` is a ServiceWorker-Script, allowing for offline usage. 8. `manifest.json` makes it possible to install the notepad as an app. 9. `test.html` loads and runs the unit tests from the various `*.test.js` files across the project. Those files are co-located with the stuff they contain tests for, to make them easier to manage. 10. `vendored/` contains copies of external dependencies, for direct use. Dependencies ------------ ### QUnit **QUnit** is a JS unit testing framework. It was chosen because it is easy to use and can be run in the browser. It consists of `vendored/qunit-2.25.0.js` and `vendored/qunit-2.25.0.css`. This is it's license: Copyright OpenJS Foundation and other contributors, https://openjsf.org/ Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. ### Mithril **Mithril** is a JS single page framework. It was chosen because it is rather simple, easy to understand, and developed with the expectation of being used like this, not needing a build tool. It consists of `vendored/mithril-2.3.8.js`. This is it's license: The MIT License (MIT) Copyright (c) 2017 Leo Horie Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. ### normalize.css **normalize.css** makes styles more consistent across browser, thus simplifying custom styling. It consists of `vendored/normalize-8.0.1.css`. This is it's license: # The MIT License (MIT) Copyright © Nicolas Gallagher and Jonathan Neal Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.