@enonic/ui-utils

Everything useful without a view layer: the request transport, the i18n core, the values an XP form edits with the helpers that parse and format them, principal keys, a task followed to its end, the browser side of the admin events hub, the theme the admin applications share, and the store behind a toast stack.

Nothing here imports a component or a framework, and nothing reads state it did not create. That is the package's whole value — it can be used from a store, a worker, a test, or code that has no DOM at all, and a function's result depends on its arguments alone. Phrases come from the consumer, which fetches them from its own server and passes them in. The exceptions read the environment by nature: the theme reads its storage and the OS preference through the window it is handed, the page's by default; documentVisibility reads the document it is handed; parseRelativeTime reads the clock unless it is handed now, and dateFromTime answers a time of today; the admin events hub imports its client from the url it is given.

pnpm add @enonic/ui-utils              # the errors, the i18n core and the values, no peers
pnpm add @enonic/ui-utils neverthrow   # plus the transport, from '@enonic/ui-utils/request'

The hub client is its own entry too, @enonic/ui-utils/admin-events, with no peer: it is the one code here that loads a module from a runtime url — the client XP serves under the hub's api. So is the XP menu, @enonic/ui-utils/admin-menu: the one code here that writes to document.head, where it puts the loader XP serves as the menu-loader extension of com.enonic.xp.app.main. And so is the task polling, @enonic/ui-utils/task, for the transport's reason: it answers with its ResultAsync.

The root entry resolves nothing outside the package. The transport is its own entry, @enonic/ui-utils/request, and the only code that needs neverthrow: every request answers with its ResultAsync, so a consumer of the transport installs it and shares one copy of the class. neverthrow is therefore an optional peer.

What is here

The theme

XP's admin applications — Settings, Content Studio, the menu — are released separately and share one theme: the enonic:theme entry in localStorage, light, dark or system. These functions are that contract, so that no application spells it out by hand.

• The entry is the truth. An event is only a cue to read it again: what a listener hears is what readTheme answers, and a missing or invalid entry is system.
• Every page hears a switch. storage fires only in the other tabs, so writeTheme also dispatches THEME_CHANGE_EVENT on the window, which every bundle on the page listens to.
• Listeners hear changes. Never on subscribe, and not for a write that leaves the answer as it was; each subscribe* returns its unsubscribe, and the caller decides how long it listens.
• Blocked storage reads as system, and a write warns.

Content Studio's pre-paint script reads enonic:theme inline, before any bundle loads, and is the one copy of the key outside this package.

The notifications

createNotifications() is the store behind Host.notify, and behind an application's own toasts: what NotificationList from @enonic/ui-kit renders. It is a factory, not an instance: the application creates one, exports it from its own module, and hands it to the list and to every Host it creates for a mount — a toast an extension raises through host.notify lands in the host's stack, never in a second one. The policy it keeps:

• One just like it is not shown twice. Same tone, message and owner is the toast already up, whose dismiss comes back; its lifetime is not restarted, and the duplicate's own options — its onClose among them — are dropped, since it was never shown. Two owners saying the same thing each keep their own.
• Three on screen, the rest queued in the order raised; a promoted toast starts its full lifetime then, not when it was raised.
• A warning or an error stays thirty seconds, the rest five, unless lifetimeMs says otherwise or autoHide is off; a lifetime past what setTimeout can wait, MAX_LIFETIME_MS, is held there. pause and resume hold and continue what is left — the list calls them on hover and focus.
• owner is what dismissOwned takes down when a mount is revoked; onClose is called once when a toast leaves, whichever way, and one that throws is reported and costs no other its close.

export const notifications = createNotifications();

const dismiss = notifications.notify('success', 'Saved');
notifications.notify('info', 'Moved to /site/news', {
  actions: [{ label: '/site/news', onClick: () => select('/site/news') }],
});
notifications.notify('error', 'Live updates unavailable', { autoHide: false, owner: 'app:users' });
notifications.dismissOwned('app:users');

Part of the Enonic UI Toolkit.