You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Treehouse is a frontend written in TypeScript made to be rendered in a browser or webview for building note-taking and information management tools. It is a "thick" frontend in that it holds most application state in-memory and executes user triggered commands to mutate that state. Persistence of that state, and a few other features, are expected to be provided by a "backend", which the frontend code interacts with via a backend adapter.
8
+
Even without a backend adapter, the Treehouse frontend is still a fully functional application packaged as a JavaScript library that can be loaded onto any HTML page.
9
+
10
+
### Architecture
11
+
12
+
The library exposes a `setup()` function that:
13
+
14
+
1. Takes a DOM document and backend adapter object
15
+
1. Sets up a central controller for the UI called Workbench
16
+
1. Loads a Workspace using the backend adapter
17
+
1. Registers built-in commands and keybindings
18
+
1. Uses [Mithril.js](https://mithril.js.org/) to mount a top level Mithril component to the document
19
+
20
+
The UI is represented by a class called Workbench. This class orchestrates and provides most of the API for the rest of the system. The UI is broken down into Mithril components that implement the views for each part of the UI, pulling state from Workbench and connecting interactions to registered commands that represent all user actions. The Workbench and commands manipulate a Workspace, which represents the main data model for the system.
21
+
22
+
### Stack
23
+
24
+
To avoid the complexity and dependency hell, Treehouse avoids most common JavaScript tooling such as Node.js and NPM. Instead, Treehouse uses [Deno](https://deno.land/) as a toolchain and otherwise avoids dependencies as much as possible. The other main dependency we have is [Mithril.js](https://mithril.js.org/), which was chosen for its simplicity and lack of further dependencies.
25
+
26
+
That said, there are other dependencies beyond this core stack which are chosen very deliberately. Out of the box search indexing depends on [MiniSearch](https://lucaong.github.io/minisearch/), and our most complex (but unavoidable) dependency is [CodeMirror](https://codemirror.net/). We're very conscious of project dependencies, including development and toolchain dependencies.
The "document" for Treehouse is the Workspace, which is mostly a container for nodes. These nodes are based on a versatile and extensible API and data model called Manifold. In short, nodes:
8
+
9
+
* have a unique ID
10
+
* have a text name
11
+
* can be children to other nodes
12
+
* can have key-value attributes
13
+
* can have components
14
+
15
+
Most importantly, nodes build a tree-like structure where each node can be extended with components. Components extend the state and functionality of a node. For example, a checkbox component can be added to a node. This gives it a state (checked or not) and allows the UI to render it differently (add a checkbox).
All user performable actions are modeled as commands and registered with a command system. Commands are functions with some extra metadata, like a user displayable name and system identifier. They can be called throughout the system by their system identifier, such as when a user clicks a something.
8
+
9
+
Menus are often defined upfront, usually by commands. Commands can have keybindings registered for them for keyboard shortcuts. These systems work together. For example, a menu item for a command will show the keybinding for it.
10
+
11
+
Commands can take arguments and usually take at least a single argument called a context. This is a way to represent state of the user’s current context, such as the currently selected node.
12
+
13
+
In addition to menus, keyboard shortcuts, and UI event handlers, there is a command palette the user can trigger to show all commands that can be run in the current context.
The workbench UI is made up of Mithril components, which are similar to React components. They take parameters, can have state, and specify a view using JSX. Instead of many atomic components like buttons and labels, Treehouse focuses on larger functional components that map to areas of the UI. Reusable visual elements are represented by CSS classes. Only if a reusable atomic visual element becomes so re-used and is too complex to re-implement is it made into a Mithril component.
10
+
11
+
All the Mithril components can be found under `lib/ui`. We use Typescript to make sure their parameters are typed so they're picked up by API documentation; no need for custom documentation for view components. Mithril components are just plain old JavaScript objects with a `view` method.
12
+
13
+
### User Context
14
+
15
+
Most components are explicitly passed a reference to the Workbench, which they can use to execute commands or pull data in the current Workspace or Context. The Workbench provides a top level context that has the current selected node or nodes, the current panel, etc. However, when passing a Context around it can be given overrides. For example, you may be currently editing a particular node, but you use the mouse to perform a command on another node. The menu ensures the command will receive a Context with that node being acted on.
16
+
17
+
### Design System
18
+
19
+
Our design system is inspired by projects like [Pollen](https://www.pollen.style/), where instead of generating CSS classes from JavaScript like Tailwind (which requires a compile step and Node.js based tooling), we simply use and override CSS custom properties. This means they can be used in inline styles as well. We also have a subset of common Tailwind utility classes defined, though using the custom properties.
Backend adapters are classes that implement the backend API for a given backend. If you wanted to make your own custom backend, you would implement your own backend adapter
8
+
implementing the APIs you wish to hook into and pass that into the `setup` function when initializing Treehouse. We also have a handful of built-in adapters for public or
9
+
well-known backend interfaces:
10
+
11
+
### lib/backend/browser.ts
12
+
13
+
This backend implements the FileStorage API using localStorage. This means data will be stored in the browser for a particular device. It also implements search indexing
14
+
using MiniSearch. It does not implement the Authenticator API.
15
+
16
+
### lib/backend/github.ts
17
+
18
+
This backend implements the FileStorage API using the GitHub API to store data in a GitHub hosted Git repository. It also implements the Authenticator API against a
19
+
script that can be hosted on CloudFlare Workers that implements an OAuth client for the GitHub API. This backend adapter does not implement a search index, it simply
20
+
uses the browser implementation (MiniSearch).
21
+
22
+
### lib/backend/filesystem.ts (coming soon)
23
+
24
+
This backend implements the FileStorage API using a local filesystem. Since there isn't a good standard filesystem API in browsers, this implementation operates against
25
+
a simple REST API that can be implemented by a backend host process, such as Electron, Apptron, or something custom.
26
+
27
+
### Writing an Adapter
28
+
29
+
An adapter is just an object that implements this API:
30
+
31
+
```js
32
+
interface Backend {
33
+
auth: Authenticator|null;
34
+
index: SearchIndex;
35
+
files: FileStore;
36
+
}
37
+
38
+
interface Authenticator {
39
+
login();
40
+
logout();
41
+
currentUser(): User|null;
42
+
}
43
+
44
+
interface User {
45
+
userID(): string;
46
+
displayName(): string;
47
+
avatarURL(): string;
48
+
}
49
+
50
+
interface SearchIndex {
51
+
index(node: RawNode);
52
+
remove(id: string);
53
+
search(query: string): string[];
54
+
}
55
+
56
+
interface FileStore {
57
+
asyncreadFile(path: string): string|null;
58
+
asyncwriteFile(path: string, contents: string);
59
+
}
60
+
```
61
+
62
+
The Authenticator API is optional (and soon so might the SearchIndex API, always defaulting to MiniSearch). Typically a backend adapter will
63
+
set `auth`, `index`, and `files` to `this` and implement each of those interfaces on that same object.
0 commit comments