morpheus

README

Morpheus

Morpheus is an open alpha web component UI kit. It provides 49 components and 5 utility components, and targets server-driven architectures.

Install

Load the base stylesheet, 1 theme stylesheet and the component bundle. jsDelivr serves every tagged release straight from this repository.

<link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/romshark/morpheus@v0.3.3/min/morpheus.css"/>
<link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/romshark/morpheus@v0.3.3/min/theme-default.css"/>
<script type="module" src="https://cdn.jsdelivr.net/gh/romshark/morpheus@v0.3.3/min/bundle.js"></script>

Pin the tag. Floating refs such as @latest resolve to the newest matching tag and pull in breaking changes. To self-host, take the same files from /min/ or from a release.

To ship only the components a page uses, build a trimmed bundle on the bundle builder page or with the morpheus command, which needs Go:

go run github.com/romshark/morpheus@v0.3.3 bundle -components select,dialog -o static/morpheus

Its morpheus.min.js and morpheus.min.css replace bundle.js and morpheus.css. It also writes theme-default.css, and -themes picks others, such as -themes default,rose. Command line describes the command.

The Go module carries the templ wrappers (neo.Select, datastar.ComboboxAsync, and one per component):

go get github.com/romshark/morpheus

See Getting started for the walkthrough.

Motivation

Morpheus targets a server-centric stack of Go, Templ, and Datastar. basecoatui covers much of this stack but has limits. Its combobox cannot be patched from the server without corrupting internal JavaScript state, a fix that has been on its roadmap for some time.

Morpheus is a proof of concept of a web component UI kit that is easy to patch from the server through what Datastar calls "fat morphs". A fat morph re-renders a single page template and sends the HTML over SSE to be morph-patched onto the existing DOM. It is designed from scratch for server-driven architectures, with other use cases in mind. Morph-based patching also exists in other ecosystems, such as:

• Alpine.js morph plugin
• HTMX Idiomorph extension
• Hotwire Turbo
• Laravel Livewire.

For the architecture and the reasoning behind these choices, see DESIGN.md.

Browser support

Morpheus targets Baseline Newly available as of August 2024. Minimum versions:

Browser	Minimum
Chrome / Edge	125
Safari	17.5
Firefox	129

There is no polyfill layer and no legacy fallback path. The kit uses the platform directly, and these features set the floor:

• @starting-style and transition-behavior: allow-discrete: enter and exit animations for surfaces that toggle display.
• :state() and CustomStateSet: a component's internal state, kept out of the light DOM so a morph cannot strip it (see Internal state).
• Popover API and <dialog>: top-layer rendering, modal lifecycle, and light dismiss.
• :has(), container queries, and round(): layout and sizing that reacts to content and to the parent box rather than the viewport.

scrollend and :host-context() degrade instead of setting the floor. scrollend falls back to a settle timer where it is missing. :host-context() (Chromium and WebKit only) carries an increased-contrast refinement that Firefox skips.

Developing

Prerequisites:

• Go (minimum version in go.mod)
• Templ
• golangci-lint
• Templier
• Node.js (for esbuild).

Commands:

• make gen: full build (install js deps, bundle JS/CSS, run templ generate, render the static site into ./dst).
• make watch: incremental rebuilds with live-reload via templier.
• make bundle-size: report raw/gzip/brotli sizes of the shippable JS + CSS.
• make clean: remove ./dst and generated bundles.

See CONTRIBUTING.md for the contribution workflow.

FAQ

See FAQ.md.

Documentation

Overview

Command morpheus builds a bundle of only the Morpheus components a page uses. It writes the files the bundle builder page at https://romshark.github.io/morpheus/bundle-builder/ builds. Run "morpheus -h" for usage.