Skip to content

ALEC-307: Migrate the ALEC UI to Onms Vue components - #175

Open
joseanesONMS wants to merge 3 commits into
release-3.xfrom
ja/alec-307-onms-vue-ui
Open

joseanesONMS wants to merge 3 commits into
release-3.xfrom
ja/alec-307-onms-vue-ui

Conversation

@joseanesONMS

Copy link
Copy Markdown
Contributor

Jira: https://opennms.atlassian.net/browse/ALEC-307

Rewrites the ALEC plugin UI from FeatherDS to the OpenNMS Onms-* component stack so it renders natively on the OpenNMS 37 Vue UI and stays self-contained on Feather-based hosts (Meridian, OpenNMS ≤36).

  • @opennms/onms-ui is private/workspace-only today, so the 35 wrappers are vendored (pinned to opennms develop 5ebe7e2c828) behind an @opennms/onms-ui alias the published package can later replace as a drop-in.
  • ui/src/theme/primevue-host.ts bridges bundled PrimeVue to whichever host mounts the plugin: on a PrimeVue host the live host config drives theme and dark mode; on a Feather host the vendored OpenNMS preset self-installs (the host app renders ALEC's root, so app.use() is never available to a plugin).
  • All 30 screens/components are migrated — FormField-wrapped fields, Info-icon help affordances, useOnmsToast, and the shared severity classes — and FeatherDS is fully removed (28 packages, the ALEC-306 CSS stopgap, variables.scss).
  • ESLint now errors on primevue/* and @featherds/* imports outside the seam, mirroring the host rule; the UI toolchain is aligned with the host (TS 5.5, vue-tsc 3.3, Vue 3.5 types — runtime still resolves to the host globals).
  • Verified on a live OpenNMS 37 in light and dark mode; 86/86 unit tests and 0 lint errors.

…e bootstrap

The OpenNMS 37 UI standardized on @opennms/onms-ui (Onms-* wrappers around
PrimeVue, NMS-20029). The package is private/workspace-only, so ALEC vendors
it (pinned to opennms develop @ 5ebe7e2c828) behind an '@opennms/onms-ui'
alias that makes the published package a drop-in swap later. Also vendored:
the OpenNMS PrimeVue preset, the --onms-* token theme, severity classes,
25 host icons, FormField and HelpBadge.

theme/primevue-host.ts makes bundled PrimeVue work without app.use() (the
host app renders ALEC's root, so we never own the app): on a PrimeVue host
it bridges the host's live config to our bundled injection Symbols so theme
and dark mode stay host-managed; on a Feather host it installs our own
config with the vendored preset into the host app's globalProperties.

Toolchain aligned with the host for the modern SFC syntax the vendored
components use: TS 5.5, vue-tsc 3.3, Vue 3.5 / vue-router 4.6 types
(runtime still resolves to the host's globals). npm's package-lock.json
replaces the stale yarn.lock. ESLint now errors on primevue/* and
@featherds/* imports outside the seam, mirroring the host rule.

https://opennms.atlassian.net/browse/ALEC-307
All 30 Feather-using components/containers now use the vendored Onms-*
wrappers: buttons/icon-buttons, chips, radios, checkboxes, selects, inputs,
textareas, tabs, drawers, spinners, toasts (useOnmsToast via the single
OnmsToastHost in MainContainer), FormField-wrapped labelled fields, and the
shared severity classes for every severity affordance. FeatherDS is fully
removed: the 28 @featherds packages, the ALEC-306 feather-styles bootstrap
and vendored feather themes, theme-dev.ts, and variables.scss are gone;
styling rides on --onms-* tokens (which resolve through PrimeVue --p-*
tokens supplied by the bundled preset on any host).

vue-tsc, eslint (0 errors), and all 86 unit tests pass; regenerated bundles
included.

https://opennms.atlassian.net/browse/ALEC-307
White-on-green failed contrast in dark mode; both Add Alarms buttons now
render as standard filled primary OnmsButtons like every other action.

https://opennms.atlassian.net/browse/ALEC-307
@joseanesONMS
joseanesONMS requested a review from synqotik August 12, 2026 18:25

@synqotik synqotik left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Most of these files (e.g. anything in ui/components or onms-ui) should not have been added.

The Feather components should be rewritten using the onms-ui package, however the actual onms-ui code and implementation should not be in this codebase. After compilation, when you actually run it against an OpenNMS instance, the code will wire up at runtime.

If this doesn't make sense, or isn't working, let me know, I'm happy to take a look myself.

@joseanesONMS

Copy link
Copy Markdown
Contributor Author

We will create a branch for an alec 4.0 that will be compatible with Meridian 26+. This ticket will go into that branch.

Current claude findings in response to current concerns:
What the host actually provides

I checked the opennms checkout to confirm the reviewer's premise, and it holds.

  • The host main bundle assigns the whole onms-ui barrel to window.OnmsUI before mounting, alongside window.Vue, Pinia, and VueRouter. It shipped in NMS-20054 and is in every build from 36.0.3 onward and in release-36.x. It is not in foundation-2025.
  • The documented plugin contract lives in ui/packages/onms-ui-example-plugin/. It externalizes @opennms/onms-ui to window.OnmsUI with rollup-plugin-external-globals, producing an ES module exactly like ALEC's build target.
  • Every name ALEC imports from the barrel exists in the host barrel today, including the toast composable. The screen migration itself does not need to change.

What has to come out of the branch

  • The 35 vendored seam components, the composable, the directive, and the alias in three vite configs plus tsconfig. Roughly 3,100 vendored lines.
  • The PrimeVue host bridge, the vendored OpenNMS theme preset, and the copied --onms-* token stylesheets. The host already provides theme, dark mode, and those tokens globally. The primevue and @primevue/themes dependencies go with them.
  • The Feather-host fallback path. That is a deliberate loss: the PR description promises Meridian and OpenNMS 36 or older, and Meridian 2025 has no window.OnmsUI. The minimum host becomes 36.0.3. That is your call, but it is where the reviewer's direction leads.

Three gaps the reviewer's message does not cover

  • Icons. The host README states subpath icon imports are not on window.OnmsUI and need the package resolvable at build time, which a private package is not. It explicitly names vendoring as the current answer for external plugins. ALEC uses 25 icons. FormField and HelpBadge are core-app files, not in the barrel at all. Those copies may need to stay, and that is worth raising on the PR.
  • Types. With the package unpublished, vue-tsc has nothing to check against. The options are a checked-in declarations file generated from the opennms package, or an ambient declare module shim that loses type safety. I would recommend the generated declarations.
  • Unit tests. The situation and configuration tests mount real components, and vitest currently resolves the alias to the vendored copy. Without it, tests need either a stub module for @opennms/onms-ui or a dev-time path to an opennms checkout, which does not work in CI.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants