Getting started

What is this

Why the framework exists, what it is made of, and why it ships two different ways.

PathLogs UI grew out of an issue tracker: the board, the Gantt chart, the command palette and a dozen primitives were written for one specific product — and then it turned out half of them were needed in every project after it. The framework is that half, lifted out of the application and stripped of its domain.

Why

There is no shortage of component libraries, and the world does not need another button. The value here is elsewhere — in the things people rewrite in every project and trip over the same way every time:

drag-to-scroll that does not break clicks and yields to native drag&drop;
a kanban board whose optimistic state does not snap back during quick successive moves;
a dropdown menu that does not take the dialog with it when that dialog was opened from the menu itself;
user-supplied Markdown in which raw HTML and a javascript: link are impossible.

Every one of these small things cost real debugging, and next to each of them in the code sits a comment explaining what the alternative would have been.

Two ways to ship

The framework is delivered two different ways. That is not a compromise — it is a split along the grain of the code.

npm packages

Tokens, hooks, primitives

These change rarely, and you want to update them with a single command. Versioning genuinely helps here.

CLI registry

Board, Gantt, filters

Heavyweight widgets almost always need edits for a particular domain. Keeping them behind a versioning wall just forces you to tunnel through it with props.

What's inside

terminal

@toimetdev/pathlogs-tokens   CSS variables, themes, colour utilities
@toimetdev/pathlogs-hooks    drag-scroll, hotkeys, SSE, polling, theme
@toimetdev/pathlogs-core     dialogs, menus, tooltips, palette, Markdown
@toimetdev/pathlogs-ui       CLI: copies widgets into your project

The component packages carry their own CSS and do not require Tailwind. Registry widgets are the opposite — they are marked up with Tailwind, because they land in your project, where it is already configured.

Principles

A component knows nothing about your domain. What to show is decided by renderCard; what to do, by a callback. The same board serves tasks, support tickets and job candidates.
Logic is separated from markup. Everything that can be checked without a DOM lives in its own module and is covered by tests: card ordering, the critical path, Markdown parsing, the maths of momentum.
Colour is never the only carrier of meaning. A status always has text beside it; a priority has a meter, not just a hue.
Comments explain the «why». Where a decision is not obvious, the note next to it says what the alternative would have been.

Next up — installation: packages, styles and the theme script.