41 KiB
Hoover — SPA Framework
Hoover is the custom reactive SPA framework used by the Vacuum Wall web UI. It provides a lightweight VDOM rendering engine, reactive state, a hash-based router, a central model layer for data synchronization, and shared UI components. No build step is required — all code runs as ES modules served raw by nginx.
Overview
| Module | File | Purpose |
|---|---|---|
| Reactivity | reactivity.js |
Reactive Proxy state with batched render requests |
| VDOM | vdom.js |
Virtual DOM: h() factory, diffing, patching |
| Render | render.js |
Render engine: container-level diffing, component lifecycle |
| Component | component.js |
Page definitions, lifecycle hooks, state caching |
| Router | router.js |
Hash-based SPA router, Link navigation component |
| Model | model.js |
Central reactive store per subsystem, fetch, WS invalidation, loading states |
| WebSocket | websocket.js |
Auto-reconnect WS, topic routing to model refresh |
| API | api.js |
JSON fetch wrapper, toast notifications, form submissions |
| Helpers | helpers.js |
Escaping, DOM value helpers, zone parsing |
| Components | components/*.js |
Reusable UI: layout, data tables, modals, toasts |
| Barrel | index.js |
Single import point for all public APIs |
All public APIs are exported from hoover/index.js. Pages and app bootstrap import from this single entry point.
Architecture
index.html — static shell with #sidebar, #main, #modal-root
└── app.js — SPA bootstrap
├── modelRegister('firewall', { subsystem: 'firewall', fetch: ... })
├── modelRegister('dnsmasq', { subsystem: 'dnsmasq', fetch: ... })
├── modelFetch('firewall') / modelFetch('dnsmasq') / ...
├── render(sidebarEl, Sidebar) — sidebar render root
├── render(mainEl, MainContent) — main content render root
└── connect() — WebSocket lifecycle
The HTML shell (index.html) provides named DOM containers (#sidebar, #main) plus a #modal-root anchor for modals. The app.js bootstrap mounts Hoover render functions onto #sidebar and #main, creating two independent render roots. The server substitutes __WS_URL_PLACEHOLDER__ in index.html to set window.__WS_URL__ for WebSocket routing.
Each render root registers a render function via render(container, fn). When reactive state changes, all registered render functions re-execute in a single batched microtask, producing new VNodes that are diffed against the previous tree and patched into the DOM.
Data Flow
WS message → refreshByTopic(topic) → modelFetch(name) → model.data = apiFetch()
→ reactivity proxy triggers render
→ page.render(state) reads model data
The model layer is the single source of truth for subsystem data. Pages never call apiFetch for data loading — they call getModel(name) in init() to get a reactive model, then read model.data, model.loading, and model.error in render().
Mutations (ConfirmDelete, ActionButton, QuickModal, apiSubmit) refresh models by name (refresh: 'firewall'), not by calling load functions. The model layer ensures in-flight dedup, loading flag management, and WS-driven auto-refresh.
Bootstrap
The app starts from webui/static/app.js:
import { h, render, Link, hComp, ToastContainer, connect, apiFetch,
modelRegister, modelFetch, reactive } from '/static/hoover/index.js?v=8';
// 1. Register subsystem models
modelRegister('firewall', {
subsystem: 'firewall',
fetch: async () => {
const r = await apiFetch('/api/firewall/config');
if (!r.ok) throw new Error(r.error);
return r.data;
},
});
// ... more modelRegister calls ...
// 2. Initial fetch for all models
for (const name of ['status', 'firewall', 'network', 'dnsmasq', 'nginx', 'acme', 'wireguard']) {
modelFetch(name);
}
// 3. Create reactive router state
const router = {
state: reactive({ path: location.hash.slice(1) || '/dashboard' }),
component() {
const name = this.state.path.replace(/^\//, '');
const page = Pages[name] || NotFoundPage;
return hComp(page, this.state.path);
},
};
// 4. Listen for hash changes
window.addEventListener('hashchange', () => {
router.state.path = location.hash.slice(1) || '/dashboard';
});
// 5. Mount render roots
render(sidebarEl, Sidebar);
render(mainEl, MainContent);
// 6. Start WebSocket (deferred to avoid initial render conflict)
setTimeout(connect, 0);
Reactivity
reactive(obj)
Wraps a plain object in a reactive Proxy. Any property assignment that changes the value automatically schedules a batched re-render across all registered render roots.
const state = reactive({ data: null, loading: true, error: null });
// Triggers re-render
state.loading = false;
state.data = result;
Multiple property mutations in the same microtask tick produce a single render cycle. Read properties normally; only writes trigger updates.
Important: Hoover's reactivity proxy intercepts property set only. It does not track property additions/deletions, array mutations (e.g., push, splice), or nested object deep changes. Always mutate top-level properties by assignment:
// Correct — assigns a new array
state.items = [...state.items, newItem];
// Incorrect — push won't trigger re-render
state.items.push(newItem);
requestUpdate()
Manually schedule a re-render. Only one microtask is queued regardless of how many times it's called in the same tick.
Model
The model layer (model.js) is the central data synchronization mechanism. Each subsystem gets one reactive model with { data, loading, refreshing, error }. Hoover handles fetching, WS invalidation, loading states, and in-flight dedup.
modelRegister(name, definition)
Register a subsystem model at app bootstrap.
modelRegister('firewall', {
subsystem: 'firewall', // WS topic to listen for ('*' = all)
fetch: async (signal) => { // async fetch function
const r = await apiFetch('/api/firewall/config', { signal });
if (!r.ok) throw new Error(r.error);
return r.data;
},
defaultData: null, // optional, initial data value
});
// Parameterized example — tab-aware fetch:
modelRegister('logs', {
subsystem: '*',
fetch: async (signal, tab) => {
const url = LOG_TABS[tab || 'journal'];
const r = await apiFetch(url, { signal });
if (!r.ok) throw new Error(r.error);
return (r.data || '').split('\n').filter(l => l.length > 0);
},
});
| Parameter | Description |
|---|---|
name |
Model name (e.g., 'firewall', 'dnsmasq') |
definition.subsystem |
WS topic string. Use 'firewall', 'dnsmasq', etc. Use '*' to match all topics. |
definition.fetch(signal?, param?) |
Async function that fetches and returns data. Throws on error. Receives optional AbortSignal and optional parameter (e.g., tab key). |
definition.defaultData |
Optional initial data value (default: null) |
getModel(name)
Get a reactive model by name. Returns the model object with { data, loading, refresh, error } properties. Call in init() to access model state in render().
// In page init
init() {
return {
firewall: getModel('firewall'),
};
}
// In render
render(state) {
const guard = renderGuard(state.firewall, 'Zones', 'Firewall zones', state.firewall.data?.zones);
if (guard) return guard;
const zones = state.firewall.data?.zones || [];
// ...
}
modelFetch(name, signal?, param?)
Trigger a fetch for the named model. In-flight dedup ensures concurrent callers get the same promise. Updates loading/refreshing flags automatically.
// Initial load
modelFetch('firewall');
// Post-mutation refresh
const r = await apiFetch('/api/firewall/zones', { method: 'POST', body });
if (r.ok) modelFetch('firewall');
// Parameterized fetch (e.g., tab-aware logs)
modelFetch('logs', 'journal');
modelFetch('logs', 'nginx-access');
Behavior:
- If a fetch is already in progress for this model (and param), returns the existing promise (dedup).
- Sets
model.loading = trueon first fetch,model.refreshing = trueon subsequent fetches. - Clears
model.errorbefore fetch. - On success, assigns result to
model.data. - On failure, stores error in
model.error. - Flags cleared in
finallyblock. - Does not abort in-progress fetches — other consumers may still need the data.
- The
paramargument is passed tofetch(signal, param)for parameterized models. Dedup key isname: param.
refreshByTopic(topic)
Refresh all models whose subsystem topic matches. Called by websocket.js when a WS message arrives.
Model subsystem |
Topic | Match? |
|---|---|---|
'firewall' |
'firewall' |
Yes |
'firewall' |
'dnsmasq' |
No |
'*' |
'firewall' |
Yes (always matches) |
'nginx' |
'*' |
Yes (wildcard topic) |
collectLoadingModels(...models)
Combine loading/refreshing/error from multiple models for composite renderGuard calls.
// Pages that consume multiple models
render(state) {
const c = collectLoadingModels(state.nginx, state.acme);
const guard = renderGuard({ loading: c.loading, refreshing: c.refreshing, error: c.error },
'Proxy', 'Nginx reverse proxy');
if (guard) return guard;
// ...
}
Returns { loading, refreshing, error } derived from the union of all passed models.
Virtual DOM
h(tag, props, ...children)
The VNode factory. Three forms:
// Element
h('div', { class: 'card' }, h('span', null, 'Hello'))
// Text node
h('#text', 'some text')
// Component (Hoover component, not function — must use hComp or h('#comp', ...))
h('#comp', { component: MyPage, key: '/dashboard' }, [])
Children flattening: null, undefined, and false children are filtered out. String and number primitives are automatically converted to text VNodes.
HTM (Tagged HTML Templates)
Hoover ships with htm for JSX-like template syntax using tagged template literals. Import and use:
import { html, Badge, ConfirmDelete } from '/static/hoover/index.js';
// Instead of:
h('div', { class: 'card' },
h('h3', { style: 'color:red' }, 'Title'),
h('button', { 'on:click': handler }, 'Click')
)
// Write:
html`<div class="card">
<h3 style="color:red">Title</h3>
<button onClick=${handler}>Click</button>
</div>`
Event naming: Use camelCase onClick=${fn} — the adapter translates events to Hoover's on:click convention. Any attribute starting with on followed by a capital letter (e.g., onSubmit, onChange) is converted.
Component syntax: Use <${Component}> syntax for inline components:
html`<${Badge} text=${val} variant="info" />`
html`<${ConfirmDelete} url=${url} message=${msg} success="Deleted" refresh="firewall" />`
Interpolation: Values are interpolated with ${...}. Use esc() for user-controlled text:
html`<tr key=${item.id}>
<td>${esc(item.name)}</td>
<td>${item.value}</td>
</tr>`
Spread attributes: Use ...${props} to spread an object as props:
html`<${Badge} ...${badgeProps} />`
Boolean attributes: Use html<${Badge} readonly />`` for boolean attributes.
Coexistence with h(): Both h and html are exported from the barrel. Use whichever is clearer for the given context. Simple elements are often shorter with h(), while complex nested structures benefit from html.
Limitations:
- No
<Badge>...</Badge>closing syntax — must use self-closing<${Badge} ... />or full<${Badge} ... ></${Badge}>syntax - No control flow (
if/for) in templates — use JavaScript conditionals and.map()before interpolation esc()is still required for user-controlled text to prevent XSS
Props
| Prop | Behavior |
|---|---|
class |
String or object ({ active: bool } — truthy keys joined as class names) |
style |
String or object ({ color: 'red' } — applies to el.style) |
html / innerHTML |
Sets innerHTML directly |
textContent |
Sets textContent directly |
value |
On <input>, <textarea>, <select>: sets .value; otherwise sets attribute |
checked |
On <input>: sets .checked; otherwise sets attribute |
disabled |
Sets .disabled boolean property on applicable elements |
on:click, on:submit, etc. |
Event listeners (on: prefix + event name) |
key |
Used by keyed diff algorithm; not applied to DOM |
ref |
Reserved (no-op); not applied to DOM |
All other keys are set as HTML attributes. null, undefined, and false values remove the attribute.
Diffing
The diff algorithm uses index-based unkeyed diffing by default. When any VNode in a sibling set has a key prop, the keyed algorithm is used for the entire set. Keyed diff preserves DOM element order and reuses elements by key.
Use key when rendering lists that can be reordered, inserted, or removed:
items.map(item =>
h('li', { key: item.id }, esc(item.name))
)
Rendering
render(container, fn)
Mount a render function onto a DOM element. First call creates DOM from scratch; subsequent calls diff and patch in place.
function View() {
return h('div', null, 'Hello ' + state.name);
}
render(document.getElementById('root'), View);
The render function executes on every reactive update. It can return a single VNode or an array of VNodes.
Pages
definePage(def)
Define a page component with reactive state and rendering. Pages access data through models, not by fetching directly.
export default definePage({
// Return initial state — models are obtained via getModel()
init() {
return {
firewall: getModel('firewall'),
};
},
// Optional: one-time setup on mount (e.g., opening a modal dialog)
// Not used for data loading — model layer handles that
async load(state) {
// Rarely needed
},
// Called on every reactive update — return VNode(s)
render(state) {
const guard = renderGuard(state.firewall, 'Zones', 'Firewall zone management', state.firewall.data?.zones);
if (guard) return guard;
const zones = state.firewall.data?.zones?.available || [];
return [
PageHeader({ title: 'Zones' }),
zones.map(z => h('div', { class: 'card', key: z }, esc(z))),
];
},
// Optional: cleanup on unmount
onUnmount(state) {
// abort pending fetches, clear cached state
},
});
Pages get data from models reactive — they never call apiFetch in load(). The model layer fetches data, manages loading/error states, and triggers re-renders when data arrives.
Page Definition Properties
| Property | Required | Description |
|---|---|---|
init() |
Yes | Returns initial state object. Wrapped with reactive() by definePage. Call getModel(name) here to access model data. |
load(state) |
No | Optional one-time setup called on mount. Not used for data loading — use model layer instead. |
render(state) |
Yes | Returns VNode(s) for the page. Read model data from state.<model>.data. |
onUnmount(state) |
No | Called when page is unmounted. Use for custom cleanup (e.g., aborting page-local fetches). |
Page Lifecycle
- Mount:
init()creates state →load()fires if defined → component tracked by key. - Update: Reactive state change (from model data update, navigation, etc.) →
render()re-executes → VDOM diff patches DOM. - WS auto-refresh: Topic message arrives →
refreshByTopic()→modelFetch()for matching models →model.dataupdate → reactivity triggersrender(). - Unmount:
onUnmount()called if defined → component entry destroyed.
hComp(renderer, key)
Create a VNode for a page component. The key determines lifecycle boundaries — the same key reuses the existing component instance (preserving state and in-flight loads).
// Router pattern — key is the path so navigation to a different page unmounts the old one
return hComp(page, this.state.path);
Router
Custom Router Pattern (Used by Vacuum Wall)
The Vacuum Wall app uses a custom router object rather than createRouter(). Reactive path state with hashchange listener handles navigation:
const router = {
state: reactive({ path: location.hash.slice(1) || '/dashboard' }),
component() {
const name = this.state.path.replace(/^\//, '');
const page = Pages[name] || NotFoundPage;
return hComp(page, this.state.path);
},
};
window.addEventListener('hashchange', () => {
router.state.path = location.hash.slice(1) || '/dashboard';
});
createRouter(routes)
Alternative: built-in hash-based router with route map.
const router = createRouter({
'/dashboard': () => h('#comp', { component: DashboardPage, key: '/dashboard' }, []),
'/zones': () => h('#comp', { component: ZonesPage, key: '/zones' }, []),
'*': () => h('#comp', { component: NotFoundPage, key: '*' }, []),
});
Returns { state, navigate(path), component() }. The component() function returns the VNode for the current route and should be used inside a render function.
Link(props)
Client-side navigation link. Sets location.hash without full page navigation. Accepts path, class, children.
Link({ path: '/zones', class: 'active', children: ['Zones'] })
// Renders: <a href="#/zones" class="active">Zones</a>
WebSocket
connect()
Start the WebSocket connection to the daemon at ws://<host>/ws (auto-detects wss: for HTTPS). Set window.__WS_URL__ to override. Auto-reconnects with exponential backoff (max 15s).
WS Message Types
| Type | Fields | Effect |
|---|---|---|
versions |
updated: [topic, …] |
Refresh all models matching listed topics |
refresh |
topics: [topic, …] |
Same as versions |
notify |
topic |
Refresh all models matching the topic |
status |
topic |
Refresh all models matching the topic |
Model subsystem: '*' matches all topics.
WS Auto-Refresh Flow
When a WS message arrives for a topic:
refreshByTopic(topic)iterates registered models.- Matching models call
modelFetch(name). - Model fetch updates
model.data, triggering reactivity and page re-renders. - In-flight dedup prevents duplicate fetches.
Pages have no awareness of WS events. The model layer handles all WS-driven refresh.
onMessage(topics, handler)
Direct one-off subscription for code outside definePage:
const unsub = onMessage(['firewall'], (msg) => {
// handle raw message
});
// Later: unsub();
Handler receives the parsed WS message object.
API
apiFetch(url, options)
Fetch wrapper with automatic JSON handling.
const res = await apiFetch('/api/firewall/zones', { method: 'GET' });
// res: { ok: true, data: …, error: null, status: 200 }
- Automatically sets
Accept: application/json. - If
bodyis a plain object (notFormData), stringifies it and setsContent-Type: application/json. - On HTTP 401, reloads the page (session expired).
- On non-2xx, returns
{ ok: false, error: "message", status }. - On network error, returns
{ ok: false, error: "Network error", status: 0 }. - Passes
credentials: 'same-origin'by default.
toast(message, type, duration)
Show a toast notification. Auto-dismisses after duration ms (default 4000). type is one of 'info', 'success', 'error', 'warning'. Returns a toast ID.
dismissToast(id)
Dismiss a specific toast by ID.
ToastContainer()
Component that renders queued toasts. Include it in the main render root:
function MainContent() {
return [router.component(), ToastContainer()];
}
apiSubmit(config)
Build a form action for formModal. Collects body, validates, submits via apiFetch, toasts, and closes the modal on success. After success, refreshes the named model(s).
apiSubmit({
url: '/api/firewall/zones',
method: 'POST', // optional, defaults to 'POST'
body: () => ({ name: $val('zone-name') }),
validate: (b) => !b.name ? 'Name required' : null,
successMsg: 'Zone created',
refresh: 'firewall', // model name(s) to refresh after success
closeModal: () => closeModal(), // optional, called after success toast
}),
Returns an array of action descriptors matching the formModal action shape. Spread it into the actions array: ...apiSubmit({ … }).
Parameters:
| Parameter | Description |
|---|---|
url |
API URL |
method |
HTTP method (default: 'POST') |
body |
() => body function, or undefined for no body |
validate |
`(body) => string |
successMsg |
Success toast message |
refresh |
Model name (string) or array of names (string[]) to refresh via modelFetch() after success |
closeModal |
Optional function to call after success (e.g., () => closeModal()) |
submitText |
Submit button text (default: 'Submit') |
checkAbort(ac)
Deprecated. Use model layer (modelRegister / modelFetch) for data fetching with abort handling and loading state management.
Create an abort-checking function from an AbortController. Returns true if the caller should bail out early. Used between sequential fetches in multi-fetch operations.
const isAborted = checkAbort(abortCtrl);
const r = await apiFetch('/api/first', { signal });
if (isAborted()) return;
const r2 = await apiFetch('/api/second', { signal });
refactorLoad(state, dataKey, fetchFn, opts)
Deprecated. Use model layer (modelRegister / modelFetch) for data fetching with abort handling and loading state management.
Async load wrapper that encapsulates loading/refreshing flag management, abort checking, and staleness guards. Used for page-local fetches that don't go through the model layer.
import { refactorLoad } from '/static/hoover/index.js';
async function load(state, abortController, entry) {
await refactorLoad(state,
// dataKey: truthy means existing data, use refreshing vs loading
s => s.items?.length,
// fetchFn: receives (state, signal, isAborted)
// isAborted is a zero-arg function to re-check abort between sequential fetches
async (s, signal, isAborted) => {
const r = await apiFetch('/api/mydata', { signal });
if (r.ok) s.items = r.data || [];
else s.error = r.error;
},
{ entry, abortController },
);
}
Parameters:
| Parameter | Description |
|---|---|
state |
Page state object |
dataKey(state) |
Returns truthy if data already exists (sets refreshing vs loading) |
fetchFn(state, signal, isAborted) |
Page-specific async fetch logic. The third argument isAborted() is a zero-arg function to re-check abort/stale status between sequential fetches |
opts.entry |
Router entry with requestId for staleness checks |
opts.abortController |
AbortController for cancellation |
poll(opts)
Poll an API endpoint until a terminal state is reached.
import { poll } from '/static/hoover/index.js';
poll({
url: '/api/certs/issue/' + enc(requestId),
interval: 2000,
timeout: 120000,
successKey: (d) => d.status === 'completed',
onErrorKey: (d) => d.status === 'failed',
onComplete: (d) => {
toast('Certificate issued', 'success');
modelFetch('acme');
},
onError: (d) => {
toast('Issuance failed', 'error');
},
});
Parameters:
| Parameter | Description |
|---|---|
url |
Poll URL |
interval |
Poll interval in ms (default: 3000) |
timeout |
Max poll time in ms (default: 60000) |
successKey |
(data) => boolean — when true, stops polling and calls onComplete |
onErrorKey |
(data) => boolean — when true, stops polling and calls onError |
onComplete |
(data) => void, called on success |
onError |
(data) => void, called on error or timeout |
UI Components
Layout
PageHeader(props)
Page header with title, optional subtitle, and action buttons.
PageHeader({
title: 'Zones',
subtitle: 'Firewall zone management',
actions: h('button', { class: 'btn btn-primary', 'on:click': () => addZoneModal(state) }, 'Add Zone'),
})
Tabs(props)
Tab bar component. Writes to state[prop] on tab click. The caller is responsible for rendering tab body content.
Tabs({
state,
tabs: ['ranges', 'leases', 'dns'],
prop: 'activeTab', // optional, defaults to 'activeTab'
formatLabel: k => k.replace(/-/g, ' '), // optional, defaults to capitalize
onTabClick: k => { /* side effect on tab change */ }, // optional
})
Parameters:
| Parameter | Description |
|---|---|
state |
Reactive state object |
tabs |
Array of tab keys (e.g. ['ranges', 'leases']) |
prop |
State property name for active tab (default: 'activeTab') |
formatLabel(key) |
Label formatter function (default: capitalize first letter) |
onTabClick(key) |
Optional callback after state update |
SectionTitle({ title })
Section header with h3.section-title styling.
SectionTitle({ title: 'WAN / External' })
DataTableSection({ title, columns, rows, emptyText, key })
SectionTitle heading followed by a Table wrapper. Combines section heading and table into a single component.
DataTableSection({
title: 'WAN / External',
columns: ['Interface', 'IPv4', 'IPv6', 'MAC', 'Zone'],
rows: ifaceRows(wanIface),
emptyText: 'No WAN interfaces',
key: 'wan-ifaces', // optional
})
Parameters:
| Parameter | Description |
|---|---|
title |
Section heading |
columns |
Column header labels |
rows |
Body row vnodes |
emptyText |
Empty-state message |
key |
VNode key |
ActionGroup(...children)
Flex button container with 8px gap. Accepts VNode children directly.
ActionGroup(
h('button', { class: 'btn btn-primary', 'on:click': addFn }, 'Add'),
ActionButton({ url: '/api/apply', label: 'Apply', refresh: 'firewall' }),
)
renderGuard(state, title, subtitle, data)
Return early with loading/error/empty-state VNodes. Returns null when data is ready, allowing the page to render its content.
Single model:
const guard = renderGuard(state.firewall, 'Zones', 'Zone management', state.firewall.data?.zones);
if (guard) return guard;
Multiple models (use renderGuardMulti):
const guard = renderGuardMulti('Proxy', 'Nginx reverse proxy', state.nginx, state.acme);
if (guard) return guard;
renderGuardMulti internally calls collectLoadingModels then delegates to renderGuard. For fine-grained control over loading flags, collectLoadingModels is still available.
Checks state.loading, state.error, and data presence in that order. Uses state.refreshing to show "Refreshing…" instead of "Loading…".
Data Display
Badge({ text, variant })
Colored label. variant: 'info', 'success', 'warning', 'danger'.
StatusDot({ status })
Status indicator dot. status: 'success'/'up' (green), 'danger'/'down' (red), or 'pending' (yellow).
StatCard({ label, value, meta })
Dashboard stat card with label, value, and optional meta.
StatCard({ label: 'Active Zones', value: 3, meta: 'lan, wan, dmz' })
StatusText({ status })
StatusDot + human-readable label. Returns [StatusDot, ' ', label].
StatusText({ status: iface.state })
// status: 'up' → [green dot, ' ', 'Up']
// status: 'down' → [red dot, ' ', 'Down']
// status: 'pending' → [yellow dot, ' ', 'Pending']
Empty({ text })
Empty-state placeholder card.
Card({ header, children })
Card container with optional header.
ConfirmDelete(props)
Delete button with native confirm() dialog, then API DELETE call, toast, and model refresh. Shows a spinner animation during the API call, auto-disables the button, and optionally marks the parent row/card as pending-deletion until the model refresh removes it from the DOM.
ConfirmDelete({
url: '/api/firewall/zones/myzone',
message: 'Delete zone myzone?',
success: 'Zone deleted',
refresh: 'firewall',
label: 'Delete',
})
Parameters:
| Parameter | Description |
|---|---|
url |
API DELETE URL |
message |
Confirmation prompt text |
success |
Success toast message (default: 'Removed') |
refresh |
Model name (string) or array of names (string[]) to refresh via modelFetch() |
label |
Button text (default: 'Remove') |
body |
Optional JSON body to send with DELETE |
deleteKey |
Unique identifier for the item. When provided, marks the row/card as pending-deletion (opacity + red border) after API success until model refresh removes it from the DOM. Requires _deleting.has(key) class binding on the parent element. |
ActionButton(props)
Inline button that POSTs to an API endpoint, toasts on result, and optionally refreshes models. Supports toggle labels for on/off buttons. Shows a spinner animation during API calls and auto-disables the button to prevent double-submit.
ActionButton({
url: '/api/dhcp/apply',
method: 'POST', // optional, defaults to 'POST'
body: () => undefined, // optional
label: 'Apply',
successMsg: 'Applied',
errorType: 'error', // optional, defaults to 'error'
refresh: 'dnsmasq', // model name(s) to refresh
cls: 'btn btn-outline', // optional
disabled: false,
})
// Toggle variant (e.g., enable/disable masquerade):
ActionButton({
url: '/api/firewall/masquerade',
body: () => ({ zone: z.name, enable: !z.masquerade }),
labelOn: 'Disable',
labelOff: 'Enable',
condition: z.masquerade,
refresh: 'firewall',
})
Parameters:
| Parameter | Description |
|---|---|
url |
API URL |
method |
HTTP method (default: 'POST') |
body |
() => body or undefined for no body |
label |
Button text |
labelOn / labelOff |
Toggle labels when condition is true/false |
condition |
Toggle condition for labelOn/labelOff |
successMsg |
Success toast message |
errorType |
Toast type for errors (default: 'error') |
refresh |
Model name (string) or array of names (string[]) to refresh via modelFetch() after success |
cls |
Button CSS classes (default: 'btn btn-outline') |
disabled |
Disabled state |
ActionCell(props)
Standardizes "action button + ConfirmDelete" in a table cell. The delete button shows a spinner during API calls and supports pending-deletion row styling. Use for rows that need an edit action alongside a delete action.
ActionCell({
editLabel: 'Edit',
editClick: () => editDomain({ ...d, _s: state }),
removeUrl: '/api/proxy/domains/' + enc(d.domain),
removeMessage: 'Remove proxy for ' + d.domain + '?',
removeSuccess: 'Domain removed',
removeRefresh: 'proxy',
removeLabel: 'Delete',
})
Parameters:
| Parameter | Description |
|---|---|
editLabel |
First button text |
editClick |
First button click handler |
removeUrl |
API DELETE URL |
removeMessage |
Confirmation prompt text |
removeSuccess |
Success toast message |
removeRefresh |
Model name (string) or array of names (string[]) to refresh after delete |
removeLabel |
Delete button label (default: 'Remove') |
removeBody |
Optional JSON body to send with DELETE |
editCls |
Override classes for edit button (default: 'btn btn-sm btn-outline') |
deleteKey |
Unique identifier forwarded to ConfirmDelete. Enables pending-delete row styling. |
certStatusBadge(props)
Badge for certificate status based on expiry data. Evaluates certStatus, expired, and daysRemaining to determine badge text and color.
certStatusBadge({ expired: c.expired, daysRemaining: c.days_remaining })
// Returns: Badge({ text: '30d left', variant: 'warning' })
Evaluation order:
| Condition | Result |
|---|---|
certStatus === 'valid' or 'active' |
'Valid' (success) |
expired, certStatus === 'expired', or daysRemaining <= 0 |
'Expired' (danger) |
daysRemaining <= 30 |
'Xd left' (warning) |
daysRemaining (positive, > 30) |
'Xd left' (success) |
| fallback | certStatus or 'N/A' (info) |
Parameters:
| Parameter | Description |
|---|---|
daysRemaining |
Days until expiry |
expired |
Explicitly expired flag |
certStatus |
Status string (e.g. 'valid', 'active', 'expired') |
serviceStatusBadge(props)
Returns a StatusDot + Badge pair for a service state string.
serviceStatusBadge({ state: statusUp.state || 'down' })
// Returns: [StatusDot({ status: 'success' }), ' ', Badge({ text: 'up', variant: 'success' })]
Parameters:
| Parameter | Description |
|---|---|
state |
Service state (e.g. 'up', 'down') |
ServiceStatus(props)
ServiceStatusBadge + label in a single <span class="service-status"> vnode. Convenient for embedding in list items or standalone status lines.
ServiceStatus({ state: st.state || 'down' })
ServiceStatus({ state: dmsk.state || 'down', label: 'Dnsmasq' })
Parameters:
| Parameter | Description |
|---|---|
state |
Service state string (e.g. 'up', 'down') |
label |
Optional label text after the badge |
MonoText(props)
Monospace text with optional truncation. Renders as <span class="mono-text">.
MonoText({ text: p.publicKey })
MonoText({ text: p.publicKey, maxLength: 20 })
// Truncates with "..." if text exceeds maxLength
Parameters:
| Parameter | Description |
|---|---|
text |
Text to display |
maxLength |
Truncate with "..." if longer (optional) |
ZoneSelect(props)
Dropdown to select a firewall zone. Renders as <select class="form-select">.
ZoneSelect({
zones: state.zones,
value: iface.zone,
onChange: (z) => changeZone(iface.name, z, state),
})
Parameters:
| Parameter | Description |
|---|---|
zones |
Available zone names (string[]) |
value |
Currently selected zone |
onChange |
(zone) => void callback |
placeholder |
Placeholder option text (optional) |
Table({ columns, rows, emptyText, wrapCard, key })
Table wrapper with header, body, and empty-state row. rows expects pre-built <tr> VNodes.
Table({
columns: ['Name', 'Status', 'Action'],
rows: items.map(i => h('tr', null,
h('td', null, esc(i.name)),
h('td', null, StatusDot({ status: i.state })),
h('td', null, ConfirmDelete({
url: '/api/item/' + enc(i.id),
message: 'Delete ' + esc(i.name) + '?',
success: 'Item removed',
refresh: 'firewall',
})),
)),
emptyText: 'No items',
})
Modal
openModal(renderFn)
Open a modal dialog. renderFn receives the modal content element:
openModal((inner) => {
inner.innerHTML = '<h2 class="modal-title">Details</h2>…';
});
closeModal([idx])
Close a modal. Without argument, closes the topmost modal.
closeAllModals()
Close all open modals.
formModal(inner, title, fields, actions)
Render a standard modal form inside the modal content element.
Field shape:
{ label: 'Name', id: 'name', placeholder: 'Enter name' }
{ label: 'Type', id: 'type', tag: 'select', options: [['a', true], 'b', 'c'] }
{ label: 'Notes', id: 'notes', tag: 'textarea', value: '' }
tag:'input'(default),'select','textarea'- For
select:optionsis an array of strings or[value, selected]tuples valueis pre-populated value
Action shape:
{ label: 'Save', cls: 'btn-primary', action: 's', handler: () => { … } }
{ label: 'Cancel', cls: 'btn-outline', action: 'c', handler: () => closeModal() }
The action field becomes a data-action attribute used for button lookup.
QuickModal(props)
Factory that returns a function to open a modal with form fields and API submission. The returned function accepts a data argument forwarded to title, fields, submit.url, and submit.body resolvers. Use as an on:click handler.
const addZone = QuickModal({
title: 'Add Zone', // string or (data) => string
fields: (data) => [ // or static array
{ label: 'Name', id: 'name', placeholder: 'Enter name' },
],
submit: {
url: '/api/zones', // or (data) => string
method: 'POST', // optional, default 'POST'
body: (data) => ({ name: $val('name') }), // or static object
validate: (b) => !b.name ? 'Name required' : null,
successMsg: 'Zone created', // or (data) => string
},
refresh: 'firewall', // model name(s) to refresh after success
});
// Usage in render:
h('button', { 'on:click': () => addZone(state) }, 'Add Zone')
Parameters:
| Parameter | Description |
|---|---|
title |
Modal title or (data) => string |
fields |
Form field descriptors or (data) => object[] |
submit.url |
API URL or (data) => string |
submit.method |
HTTP method (default: 'POST') |
submit.body |
(data) => object, body to send (note: the function is called with the data argument from the outer call) |
submit.validate |
`(body) => string |
submit.successMsg |
Success toast message or (data) => string |
refresh |
Model name (string) or array of names (string[]) to refresh via modelFetch() after success |
handler |
Optional custom handler (data, closeModal) => void that bypasses apiSubmit |
submitLabel |
Submit button label (default: 'Submit') |
MultiSelectModal(props)
Factory that returns a function to open a multi-select modal. Use as an on:click handler in VNode props.
const editIface = MultiSelectModal({
title: 'Interfaces: ' + zoneName,
url: '/api/firewall/zones/' + enc(zoneName) + '/interfaces',
options: state.interfaces,
selected: zone.interfaces,
fieldKey: 'interfaces',
successMsg: 'Interfaces updated',
refresh: 'firewall',
});
// Usage:
h('button', { 'on:click': editIface }, 'Edit')
Parameters:
| Parameter | Description |
|---|---|
title |
Modal title |
url |
API POST URL |
options |
All selectable options (string[]) |
selected |
Currently selected values (string[]) |
fieldKey |
JSON key for the submitted field |
successMsg |
Success toast message (default: 'Updated') |
refresh |
Model name (string) or array of names (string[]) to refresh via modelFetch() after success |
Toast
ToastContainer()
Render the toast notification container. Include in the main render root. See API section above.
Helpers
| Function | Description |
|---|---|
esc(s) |
HTML-escape a string for safe text content |
att_esc(s) |
Escape for safe use in HTML attributes |
enc(s) |
URL-encode a string (encodeURIComponent) |
$val(id) |
Get value of document.getElementById(id) |
parseZones(data) |
Parse zone data from API responses into a flat string array |
downloadBlob(blob, filename) |
Trigger a browser file download from a Blob |
Versioned Imports
Static assets in app.js are imported with querystring version pins (e.g., ?v=8) to invalidate browser cache when the framework changes. Page imports also include version pins (e.g., ?v=9). The server handles caching headers; the version query string ensures browser cache invalidation.
Dev mode (VACUUM_WALL_DEV set) disables aggressive static asset caching.
Conventions
- Pages export
definePage({ … })as default. Each page inwebui/static/pages/. - Model-first data loading: Pages get data from
getModel(name)ininit(). The model layer handles fetching, loading states, error handling, and WS-driven refresh. Pages never callapiFetchinload(). - Render pattern:
renderGuardearly return → data rendering. Always return VNode array or single VNode. - Multi-model pages: Use
renderGuardMulti(title, subtitle, ...models)for combined loading/error guard.collectLoadingModelsis still exported for edge cases needing raw flags. - Mutation refresh: UI components use
refresh: 'model_name'to triggermodelFetch()after API mutations. Accepts single name or array. - Keys on list items use unique identifiers (
item.id), not array indices. - Escaping: Use
esc()for any user-controlled text rendered inh()children. Useenc()for URL segments. - Modals: Use
formModal+apiSubmitfor standard CRUD operations. UseopenModal+ custom render function for non-form content. - Log / stream data: Pages that fetch raw text or streams (e.g.,
logs.js) can use the model layer with a parameterized fetch. Register the model with afetch(signal, param)that selects the right URL based onparam, and callmodelFetch('logs', tabKey).