DevactionUI

The component library of DevAction: Phoenix function components, LiveView hooks and a token stylesheet. It depends on Phoenix and LiveView only, so every DevAction project (and any other) takes the same pieces.

Repository layout

devaction_ui/        the package: lib/ (components), assets/js (hooks), assets/css (tokens), test/
devaction_ui/site/   the documentation site: a Phoenix app that depends on the package by path

The package is what goes to Hex and into every project; it needs Phoenix and LiveView only. The site is a consumer of the package like any other, with its own mix.exs, release and Dockerfile, so it deploys on its own and nothing of it ships with the package.

Running the documentation

cd site
mix setup
mix phx.server    # http://localhost:4100

mix setup fetches the deps, installs the npm packages the editor hook needs, and builds the CSS and JS. Every component has a page with live examples (each with its source), and the API tables are read off the modules themselves, so they cannot drift from the code. ⌘K searches; the sun/moon button flips the theme.

Deploying the documentation

The Dockerfile at the root builds an Alpine release of the site (the context is the whole repo, because the site depends on the package by path):

docker build -t devaction-ui-site .
docker run -p 4000:4000 -e SECRET_KEY_BASE=$(mix phx.gen.secret) -e PHX_HOST=ui.example.com devaction-ui-site

PORT, PHX_HOST and SECRET_KEY_BASE are the only variables; /up answers 200 for the proxy's health check.

Templates

Whole screens built only from the library live under site/lib/devaction_ui_site/screens/<group>_<slug>.html.heex and are listed in site/lib/devaction_ui_site/templates.ex. Each is a page of its own at /screens/<group>/<slug>; the documentation embeds it scaled down, next to its source (/templates/<group>). Every example and every screen runs in a LiveView of its own, so what you type or click in one never reaches another.

Tests

mix test && mix js.test            # the package
cd site && mix test                # the site

Using it in a project

{:devaction_ui, github: "devaction-labs/devaction_ui"}

1. CSS: @import "../../deps/devaction_ui/assets/css/devaction_ui.css"; in the app's Tailwind entry. The stylesheet itself tells Tailwind to read the components and the hooks (some classes live in the JS), so there is no @source to add.
2. JS: import {hooks as devactionUI} from "../../deps/devaction_ui/assets/js/devaction_ui" and merge into the LiveSocket hooks.
3. Fonts: Geist and Geist Mono are named in the tokens; the host app serves them.

The rules that keep it extractable

• It knows nothing about any app. No app module, no Gettext backend: text comes in as attributes and slots. test/devaction_ui/no_hand_made_ui_test.exs fails if a file here reaches out.
• 100% independent: no Fluxon, no daisyUI, no Heroicons. Everything here is Phoenix.Component plus Tailwind. Icons come in as slots; the documentation site fills them with Hugeicons.
• Classes live in the components, not in a stylesheet. A component carries its Tailwind utilities in its template; @apply in @layer components is allowed for the classes the canvas names. The only CSS the library needs is the tokens (:root variables and @theme) and the shimmer, aura-spin, aura-glow and toast-out keyframes, in assets/css/app.css today. A host app makes Tailwind read the components with @source "../../deps/devaction_ui/lib".
• Tokens, never a hex in a template. bg-card, text-muted, border-tag-risk-line. The tokens flip with the theme through light-dark(), so a component never has a dark: variant of its own. The theme is data-theme="dark" or the .dark class on <html>.
• Color is never alone. A tag has text, a callout has a title or an icon, a progress bar has a label.
• Motion respects prefers-reduced-motion.
• Text in a pre is an attribute, not a slot. A slot carries the template's line breaks and indentation into the code. code_block takes code.

What is here

Where an app also has its own alert, badge, button or pagination, call these qualified (<DevactionUI.Alert.alert>) instead of importing them, so the two never collide.

The documentation site shows all of them in every variant; flip the theme there to check the dark side.

Adding a component

1. Put it in lib/devaction_ui/, with attrs and slots documented, a @moduledoc that says what it means and when to use it, and a test in test/devaction_ui/.
2. Show it in the site: list the module in a category of site/lib/devaction_ui_site/catalog.ex (it gets its page, its title and its summary from the module itself) and add its sections as site/lib/devaction_ui_site/examples/<slug>_<nn>.html.heex, each starting with <%!-- title: Title | text: One line --%>.
3. Replace any copy of it in a screen. A screen that needs a variant adds it here; it does not write its own.

Hooks

The hooks are plain ES modules in assets/js/devaction_ui/ (one file per component, index.js exports them as DevactionUI.Tabs and so on); no component carries a <script>. A host app merges them in its app.js: hooks: {...devactionUI}. The logic that needs no DOM sits in its own module with a test beside it (mix js.test). Their DOM is changed by the hook, so the server must not undo it: tabs and accordion tell LiveView to ignore the attributes the hook owns (JS.ignore_attributes), the pillbox and the combobox use phx-update="ignore", the table puts the ticks back after a redraw (beforeUpdate/updated) and the board gives the focus back to the moved card. To check the keys and the focus by hand, open the documentation site.

Time zones and languages

The library never reads the clock or a locale. The date picker takes today (an ISO date the caller computed in the workspace's time zone) and a locale for the month and weekday names (browser Intl); every text, from a shortcut to "Collapse", is given by the caller. The date picker and the pillbox are phx-update="ignore": to reset them from the server, give them a new id.