gingko/client

Gingko Writer. Tree-based writing software, written in Elm.

Gingko Writer

Writing software to help organize and draft complex documents. Anything from novels and screenplays to legal briefs and graduate theses.

This is a ground-up rewrite of GingkoApp.com. The latest version is available online at gingkowriter.com.

The desktop version (on branch desktop), is currently well behind the web app version. It will eventually be brought up to par, but if you need it now, it's available to download on the releases page (for Linux, Windows, and Mac).

Contributions Welcome!

If you want to help translate Gingko Writer, you can join the translation project.

For code contributions, see CONTRIBUTING.md for a guide to getting started.

---

Installation & Dev Environment

1. Install Prerequisites

• Node.js
• Bun.sh
• SQlite
• CouchDB*
  • Note down your admin username and password for the next step.

I can't provide detailed instructions for installing these, because each system is different.

* this dependency will be removed once all user documents are migrated to SQLite DB.

2. Project Directories

git clone [email protected]:gingko/client.git
git clone [email protected]:gingko/server.git
mkdir data

After this you should have all three directories side-by-side: client, server, and data.

3. Client setup

cd client
bun i
cp config-example.js config.js
bun run newwatch

4. Server setup

In a new terminal, navigate to the /server directory, and do the following:

npm i
cp config-example.js config.js
sed -i 's/couchusername/your_couchdb_admin_username/' config.js
sed -i 's/couchpassword/your_couchdb_admin_password/' config.js
npm run build
npm start

Now you should be able to visit http://localhost:3000 and use your local Gingko Writer install.

client's Issues

Refactor and simplify ports to/from JS

Current setup for communicating with JS from Elm is using the poor "request/response" mental model. I've already found it to be cumbersome.

It should be replaced and refactored. Here is a talk on how to think about ports in a way that scales better:

• "The Importance of Ports" by Murphy Randle - Elm-conf (youtube, 22min)
• https://github.com/splodingsocks/a-very-im-port-ant-topic/blob/master/example/src/OutsideInfo.elm

Continue from the card most recently edited

When we open a Gingko file, the very first card at the top level gets selected, not the card we edited last.

That's annoying when we have a decent amount of cards and don't know where we left off. Or when we do remember the last card we wrote/edited, we still have to search for it in all the cards and their sublevels.

Export only a subtree, or only a given column

Current: we can only export the entire tree.

Desired: ability to choose to export the following portions of a tree:

• Currently selected card & its subtree
• A given column

Export as Text (Windows) : Entire document appears on one line

Seems to be an issue with line-endings, because the same files open correctly on Linux.

Cancelling "Open dialog" leads to Uncaught Exception

Uncaught TypeError: Cannot read property '0' of undefined
    at file:///home/adriano/code/learn/gingko/client/app/main.js:43873:43
    at CallbacksRegistry.apply (/home/adriano/code/learn/gingko/client/node_modules/electron/dist/resources/electron.asar/common/api/callbacks-registry.js:48:25)
    at EventEmitter.<anonymous> (/home/adriano/code/learn/gingko/client/node_modules/electron/dist/resources/electron.asar/renderer/api/remote.js:299:21)
    at emitThree (events.js:116:13)
    at EventEmitter.emit (events.js:197:7)

Bring up word counts on hitting `w`

It's useful to be able to see all word counts without having to switch to mouse. Pressing w should toggle the word count tray on and off.

Autosave card edits periodically

Current: we have full version history, but not within a card. HTML textarea itself takes care of undo/redo, but we don't have any autosave functionality.

Desired: edits within a card are saved, so that if there's a crash, power failure, etc, unsaved content is still recoverable.

Smallest-delta between current & desired: add oninput handler for textareas, which saves cardId, position, and content to localStorage. Use throttling if necessary to prevent slowdown.

Prevent dragging of last card

Moving the last card isn't allowed, so drag-and-drop should be prevented.

Keyboard shortcuts for moving cards: missing Alt+(HJKL) option.

Alt+arrow keys works, but for those who use hjkl to navigate the tree, we need to add the following shortcuts:

• Alt+h (move left)
• Alt+j (move down)
• Alt+k (move up)
• Alt+l (move right)

Continue with the most recent tree on start up

Currently when we close the Gingko app and then re-open it, we get the 'Untitled Tree'. It breaks productive flow to have to relocate and open the file you where working on.

Worse, Gingko starts the opening process in the documents folder, not the most recent folder in which a Gingko file was saved.

Gzip files in backwards-compatible way

Gingko's files contain a lot of repetition, and can be compressed well with gzip.

Add additional navigation keys, such as home, page up, etc.

Home: top of column
Page Up: top of current group. If there already, jump up to bottom of group above.
Page Down: bottom of current group. If there already, jump down to top of group below.
End: bottom of column

Resizing window doesn't rescroll

Current: Disorienting lack of scrolling when window is resized.
Desired: When window is resized, trigger an "Activate" on currently active card, to force rescroll.

Highlight parent card

Current: Parent card has no special formatting.

Desired: Like web version, parent card stands out somewhat from its siblings.

Search & Filtering

Work is lost when double-clicking to edit another card, while current is unsaved

Current state (user reports):

When I double-click another card in Gingko2 without saving the one I was writing in, then my edited text gets lost. I already lost a few small pieces of text this way, because I forgot to cmd-enter. Whereas in Gingkoapp the edited card gets saved when I start editing another card, even if I don't press cmd-enter.

Desired: Clicking outside current card leads to save on loss of focus.

Add ability to move cards with Drag and Drop.

Click and drag a card (or draggable portion thereof), and drop it above/below/as-child of any other.

Enable Spell-check

Menu on Mac shows "Ctrl" instead of "Cmd" for shortcuts.

Autosave entire document

Autosave entire tree periodically (to local leveldb?), for file recovery/etc.

Copy/Paste cards and subtrees

Trial Usage counter stops at "20" days

Fix db.type warning in pouchdb-replication-stream

Floods the console with warning. Fix needed here: pouchdb-community/pouchdb-replication-stream#63

Refactor `(Model, Cmd Msg) -> (Model, Cmd Msg)` chaining functions

This pattern is useful to perform multiple actions that each can have associated commands. Both cancelCard and activate are of this type:

update : Msg -> Model -> ( Model, Cmd Msg )
update msg ({objects, workingTree, status} as model) =
  case msg of
    Activate id ->
      case vs.editing of
        Just eid ->
          model ! [ sendOut ( GetText eid ) ]
            |> cancelCard
            |> activate id
--- ...

cancelCard : ( Model, Cmd Msg ) -> ( Model, Cmd Msg )
cancelCard (model, prevCmd) =
  let vs = model.viewState in
  { model
    | viewState = { vs | editing = Nothing }
  }
    ! [prevCmd]
    |> sendCollabState (CollabState model.uid (Active vs.active) "")

But this pattern has lead to multipe hard to debug silent errors if prevCmd isn't appended (thus breaking the chain)!

This should be refactored to either make "missing prevCmd" errors more obvious, or to make them impossible.

Warn if swap file exists

If a file with the same path and .swp appended exists, and it's different from the current one, then there was an error during the save process.

Need some way to find out if it's the swap file that's corrupt, the current one, both, or neither.

Switch from AppImage to Snap?

Pros for switch:

• electron-builder now defaults to Snap
• Snap has auto-updates built in

Cons:

• Dblsqd and its interface won't work with Snap
• Current users with AppImage won't receive update notifications

Text overlap rendering issue

In v2.0.1 on Debian Linux, using the word "root" in a markdown header results in the saved text appearing lower on the node, overlapping text written on the next line. I get the same result for all child nodes and at any header depth. That is, "# root", "## root" and "### root" all result in text overlap anomalies. I haven't been able to reproduce the issue with any other header text.

Formatting with selection + shortcuts

Select text and press "Ctrl+B" for bold, "Ctrl+I" for italic, etc.

Export Live Preview

It'd be helpful with more complex documents, to be able to preview the "final" exported document, including all filters and selections ("whole tree" vs "current card & children" vs "column X").

This will be especially important as more export options and formats are added.

Data from *.gko file not being read

One user reported a *.gko file that doesn't open correctly. No error messages or console logs.
Data seems intact on inspection seems corrupted on write.

Add word count feature

Words per card, per subtree, column, etc.

It would be great to count words written, not just words present, but that might be being perfectionist.

Backtick "verbatim" Markdown doesn't scroll or wrap

When using Markdown's backticks (`like this`), we expect that lines longer than the card would either:

• Wrap within the verbatim block
• Or: Present a horizontal scrollbar on the verbatim block
• Or: Present a horizontal scrollbar on the card itself.

None of these are happening.

Allow opening *.gko files by double clicking

• Use electron-builder's fileAssociations option to associate *.gko files with Gingko.
• Load given file on launch
• Decide how to handle existing windows. Open in existing window? New instance?

Implement Undo / Redo

Code syntax highlighting

elm-Markdown has support for this, it just needs to be enabled by including the script for highlight.js

Exception on startup in Windows

[Window Title]
Error

[Main Instruction]
A JavaScript error occurred in the main process

[Content]
Uncaught Exception:
Error: Command failed: 4294967295
System.AggregateException: One or more errors occurred. ---> System.NullReferenceException: Object reference not set to an instance of an object.
   at Squirrel.UpdateInfo.<>c.<Create>b__20_0(ReleaseEntry x)
   at Squirrel.EnumerableExtensions.ExtremaBy[TSource,TKey](IEnumerable`1 source, Func`2 keySelector, Func`3 compare)
   at Squirrel.EnumerableExtensions.MaxBy[TSource,TKey](IEnumerable`1 source, Func`2 keySelector, IComparer`1 comparer)
   at Squirrel.EnumerableExtensions.MaxBy[TSource,TKey](IEnumerable`1 source, Func`2 keySelector)
   at Squirrel.UpdateInfo.Create(ReleaseEntry currentVersion, IEnumerable`1 availableReleases, String packageDirectory)

Full error message:
gingko-0.8.0-startup-error.txt

Implement drag handlers, so that users can still select text in cards without triggering a drag.

Auto-update on Linux doesn't replace file correctly

After new update is installed, it's named installer-x.x.x.AppImage, instead of gingko-client-x.x.x.AppImage. It's possible this has been the case since upgrading to electron 2.0.0-beta.4

Allow user to split cards

In old web app, it's very useful to be able to use Ctrl+J, Ctrl+K, Ctrl+L to split a card (down|up|as-child). That's not currently supported in this version.

Ctrl + arrow keys during editing shouldn't trigger "new card" actions

Current: Ctrl + right, Ctrl + up, Ctrl + down are all default shortcuts for text navigation (move by word/line). But in Gingko they trigger a card insertion, even when in edit mode.

Desired: Those shortcuts should be made normal mode only.

Solution: The HandleKey actions for mod+right, mod+up and mod+down (found here), should be changed to normalMode model (insertBelow vs.active) etc.

Only typing triggers "unsaved" state. Moving, Inserting, and Deleting cards doesn't

Moving, Inserting (blank) card, and Deleting cards doesn't trigger "unsaved" state. Which means that user could accidentally lose changes if they close the file, since it won't warn that there are unsaved changes.

Receiving 'head not ok' errors

Documents are saving correctly, but the following error occurs on some change:

CustomPouchError {status: 409, name: "conflict", message: "Document update conflict", error: true, id: "heads/master"}

This needs to be corrected before implementing sync.

Restore window state to what it was when last closed

Position, size, and maximized-or-not, should all be restored when Gingko is re-opened

Export to Word (*.docx)

Add "About" modal, to show current version number

Portable version (Windows)

Add Portable version to releases, so that people can use Gingko from a USB or similar.

Check that data is written correctly before deeming the Save process complete

Perhaps by comparing a hash of the data to write, and then a hash of the readStream of written file.

Basic LaTeX support

Fullscreen & Distraction-free mode

Can be either simple (edit one card in full screen view, like in current gingkoapp.com version).

Or complex, where the entire column is editable fullscreen, perhaps with a dimmed view of the parent on the right. Pressing Enter (or any time a new paragraph is created) creates a new card. Moving through cards is as simple as moving within one text box, and we can also merge by click-deleting the dividing marker between them.

Refactor timestamp and timeJSON from Native

Elm 0.19 will disallow Native javascript code, so I'll need a different way to pass in timestamps when needed. Probably by splitting an action into Intent + port to JS + port to Elm + Perform.

A simple temporary hack might be instead to pass in the timestamp with the shortcuts that trigger actions that need it.