This package contains some Widgets to be used in the georgeous Scriptable app for iOS. It is a simple UI to show your workhours from Mite using its API.
To give the 🦄 some 🍫 this is based on Typescript, is build using esbuild and is tested (at least partially) using jest.
For now this package contains these Widgets:
- Workhours Lockscreen - Shows the workhours of the current week in a small Widget with the circle as big as possible on the Lockscreen
- Workhours Single - A single Widget to show workhours of the current week with a label on the Homescreen
- Workhours Triple - Shows three stats as medium Widget on the Homescreen, current week, last week and today
Use the correct Node version, as defined in .nvmrc. I highly recommend to use Node Version Manager (for Unix it's nvm, on Windows it's nvm-windows).
On macOS / Linux simply run nvm use in the root of this project.
Unfortunatly on Windows reading the .nvmrc is not supported, so you either have to manually type the correct Node version or use the PowerShell with something like iex "nvm use $(cat .nvmrc)".
Just run npm install in the root of this project.
To build the Widgets run npm run build in the root of this project and have a look at the dist folder.
The output then contains the Widgets as *.scriptable files, which can be simply opened and used in Scriptable. Additionally the scripts themselves are also available as *.js files.
Once installed and configured as Widget, you have to provide two essential properties, using the "Parameter" field in the Widget configuration. The configuration must be provided as valid JSON for the time being (until I come up with a better solution).
All currently available properties can be found as
WidgetParameterstype in the src/utils/auxiliary.utils.ts.
| Property | Description | Default | |
|---|---|---|---|
context |
The Mite context (or subdomain if you will) to be used | required | |
token |
The Mite API token which can be generated in your Mite account | required | |
hours |
The number of hours you work per week | optional | 40 |
collapse |
Tries to narrow down spacing and remove backgrounds to make the content appear as big as possible within the Widget. Meant to be used for Lockscreen usage | optional | false |
hideLabels |
Hides the labels below the stats (not the labels inside the cirlces) | optional | false |
So a sample configuration could look like this:
{ "context": "mycompany", "token": "somegeneratedtoken", "hours": 35, "hideLabels": true }
First of all a big shoutout to Simon Støvring for the fantastic (and free!) Scriptable App.
To gain the benefits of typed JS I needed to provide typings for the Scriptable API.
After manully declaring some of the types, I decided to generate them from this API in some way, and found out that one of the example Widgets already uses the documentation in a JSON form, which is provided seprately.
So I came up with a simple parser for the (I guess) MkDocs format, which I tracked in a separate repository. This CLI tool is run after postinstall and generates the typings in src/scriptable.d.ts, but could also be run directly with
npx mkdocs-ts https://docs.scriptable.app/scriptable.json src/scriptable.d.tsor in this package with npm run generate:types.
For convenience I derived the official colors available from the Apple UI guidelines and added them along with some utility functions to src/utils/colors.utils.ts.
So dependend of the device theme and platform, the correct color can be used with e.g. getSystemColor('red'). The available colors are typed, of cause.
A simple translation mechanism is available using a JSON translations file and some tooling in src/utils/i18n.utils.ts.
Dependend on the device language, the correct translation can be used with e.g. i18n('LABEL.TODAY'). The available translations keys are typed as well, as they're derived from the JSON.
For convenience, the Widgets are additionally packaged into *.scriptable files, which can be directly opened in Scriptable.
This is done with a custom esbuild plugin. This plugin is consumed in the esbuild.config.ts and can be configured with a scriptfile path (relative to the root of the project) and a package property which can either be a path to a JSON file, or an inline object providing the package meta data.
As this is typed, the plugin options can be found as ScriptablePluginOptions and the package meta data format as ScriptableMetadata types in tools/esbuild-plugin-scriptable.ts.
This plugin may be split out in a separate package in the future. If you're interested in this, please let me know.
See. Configuration or src/utils/auxiliary.utils.ts.
For KPIs, as the fancy project owner would call them.
As the Scriptable API exposes the posibility to paint in a draw context, one has nearly everything we need to draw stuff like in Canvas or SVG.
Have a look on the createProgressCircle function at src/views/progress-circle.view.ts to see how this is done.
© 2022 - Created at 🌙 with ❤️ and 🍺 by David Enke.