4th March 2025

An Idea in Motion

I am making steady progress with Orsn v2.

Non-Technical

With v2 I have redesigned, to varying degrees, the paradigm, the interface and the database structure.

Now we have a simplified paradigm of Cards and Pages. Pages take over from Contexts in v1. They're extensions (plugins) and can provide custom visualisations and interactions. As part of the v2 rewrite, there will be fewer of these at first, with more attention paid to proper execution – v1 was more of a proof of concept. I will also provide templates for those who want to create their own.

A Project has three modes: Edit, Design and Publish. Edit is for creating content. Design is for arranging Pages, and Publish is for the presentation of the selected Pages. For the moment I am focusing solely on Edit mode.

Edit mode: a simple prototype page, with temporary content and design, showing sidebar and tabbed contents

The interface is already cleaner. In edit mode there is now only one main sidebar, instead of two. It has tabs at the top and accordion-type sections at the bottom. (Cards will have their own foldable annotation and revisions sidebars, on the opposite side of the interface, as will Pages...) Not unlike what you would see in VS Code or a similar IDE app. As before, the sidebar position is switchable in settings. This time, though, I have added some basic functionality which was missing in v1, e.g. dragging of sidebars and accordion sections to resize them.

Cards now have Blocks, that is separate sections for different types of Markdown content. This is still in development, but it will bring Orsn up to speed with what other Markdown editors offer. The types of Block supported will be text blocks, code blocks with highlighting, tables with some useful editing options, and LaTeX. (There are some interesting graphing options in Markdown these days but that is not a priority for now. That kind of thing can perhaps be better done in a Page extension.) I think this kind of Block concept should be familiar to anyone who has used Jupyter Notebooks or similar tools.

There is the option to have multiple Stacks now, in a tabbed interface. Before, there was just one Stack. A Stack is a collection of Cards. A bit like a folder, functionally, but it avoids the use of a hierarchical structure in the Cards themselves. Once you have added Cards to a Stack, you can collectively add them to a Page, if you want. You can create 'Live Stacks', e.g. a Stack based on a tag, which shows every Card with that tag. Or a Stack based on a search term. Etc. (Like 'smart folders' in some OSs.) At least you will be able to. For the moment, I am pouring the foundations, not laying the bricks.

A priority on the roadmap is to make it possible to assign properties to Cards. In this way, a Card in a Project will be able to have certain custom fields. As an example, you might have a Project for storing book references, in which each book's Card has ISBN and author properties. Those properties will then be accessible for visualisations or interactions in Pages, if the Card is added to a Page.

I won't say too much more about the database design, as it is ambitious in the features it might support in the future, but my priorities for now are more modest.

Technical

My starting point for updating the software was to migrate everything to Vue3 and rewrite the codebase to use Typescript. That phase is complete apart from a very few utility files which are still in javascript for the moment.
I resisted Typescript to a degree in the past, in part because I like code to be readable and self-explanatory wherever possible. I also want it to look nice! Perhaps not surprising for someone who spends a lot of time building interfaces? Typescript decorates javascript to such a great extent that if you are at all unfamiliar with it, code clarity is much reduced. Also, there are certain procedural aspects about it which I found confusing. Where to put the type declarations? What's the difference between .ts and .d.ts files?

On the other hand... for an application of any complexity, type safety is such a boon. It forces you to think clearly and helps enforce consistency. It makes structural decisions in the code explicit. That is all-important. I don't want to say how often I have found inconsistencies in v1 of Orsn, inconsistencies which Typescript has forced me to confront and fix. Also, once you have a certain level of familiarity with Typescript, the code is still very readable. And for other confusions, such as where to declare types, there is always the option of reading the documentation or looking at other people's code.

So overall I am delighted with Typescript, and I can't see myself going back. It has definitely helped make clearer what is happening under the hood in all the different parts of the new Orsn.

The move to Vue3 is what made it possible to use more Typescript than in v1. I have seen that other javascript frameworks are trending (Svelte?) but I haven't looked into them. Vue seems to be going strong and I really enjoy its usability and the sensible structural guidelines it sets out. I used React in a former job and its language was stated very much in terms of the requirements of the framework and its logic. Vue's language is stated more in terms of the requirements of the app designer. That may make it slightly more high level in some respects, but not significantly. You still have to understand lifecycle events, data binding, all the core stuff that makes it useful.

As part of the move to Vue3 I also upgraded the application's store system from Vuex to Pinia. They are similar to use in a lot of ways, but the move to Pinia has allowed me to remove a lot of code, as data updates are now executed straight away in 'actions' instead of in separate 'mutations'. That is easier to read and make sense of, and more economical to write. Pinia also supports Typescript directly.

The Road Ahead

The path onwards is pretty clear, and I am confident about the technical side of achieving the goals. The big problem is having the time to get there. That's the battle, and of course that is the difference between an imagined app and a 'real' one. It's not properly real until you make it.

It's interesting trying to balance the small details against the bigger picture. You can spend your morning making a sidebar resizable, but then you have to switch perspectives and consider the overall design and purpose.

It would definitely be useful to hear from others with different perspectives. I don't want to spend a long time going down the wrong paths. Find me on the fediverse @Lemmy@post.lurk.org, or send an email to: info [at] orsn.io