163 lines
8.4 KiB
Markdown
163 lines
8.4 KiB
Markdown
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.
|