Skip to content

cards: standardize the intropage asset layout (js/ + css/) for the shared card interface - #473

Merged
TheWitness merged 15 commits into
developfrom
feature/standard-cards-bundle
Nov 11, 2026
Merged

TheWitness merged 15 commits into
developfrom
feature/standard-cards-bundle

Conversation

@TheWitness

@TheWitness TheWitness commented Nov 9, 2026 •

Copy link
Copy Markdown
Member

Summary

First step of the cross-plugin dashboarding card interface standardization: give intropage the standard Cacti plugin asset layout so the shared card chrome (CactiCards) can later be promoted to core unchanged, and every plugin that adopts it uses an identical file layout.

What changed

  • Relocate the shared card chrome from includes/cards/ to the standard asset paths:
    • includes/cards/cards.css -> css/cards.css
    • includes/cards/cards.js -> js/cards.js
  • Move the plugin's main script includes/intropage.js -> js/intropage.js, so all JavaScript lives under js/ (only PHP libraries remain in includes/).
  • Add the standard js/index.php directory-index redirect stub.
  • Repoint the asset includes in display.php / setup.php, the unctions.php and unit-test comments, and the e2e specs (cacti-theme, chart-resize) that reference the files.
  • manifest.json: add js/ to expected, and record the vacated includes/cards/ and includes/intropage.js under ombstones so an upgrade prunes the stale copies a previous version left behind.
  • patch-coverage gate: allowlist the new js/index.php redirect stub (an entry-point stub not reachable from the isolated unit process, like the existing stubs).

No behaviour change - this is a pure relocation. cards.js/cards.css are git-tracked renames with zero content diff, and js/intropage.js is an unchanged rename.

Validation

All CI green: PHP 8.2-8.6 integration tests, Cacti theme-browser regressions, CodeQL, SonarCloud. Rebased on current develop.

Context

intropage is the reference implementation (window.CactiCards + adapter, .cc* markup). Follow-up PRs converge mactrack (Cacti/plugin_mactrack#412), hmib, apcupsd, syslog, alarmmanager, monitor and topx on this byte-identical bundle, then Phase 2 lands it (plus PHP helpers) in core 1.2.x and develop.

Co-authored-by: Copilot 223556219+Copilot@users.noreply.github.com

TheWitness and others added 3 commits November 9, 2026 11:09
Move the self-contained dashboard card chrome from includes/cards/ to the
standard Cacti plugin asset layout (js/cards.js + css/cards.css, with a js/
index.php redirect stub) so every plugin that adopts the card interface uses
an identical file layout and the bundle can be promoted to Cacti core
unchanged. Update the display.php/setup.php asset includes, the intropage.js
comment, the e2e theme spec path and the CHANGELOG. No behaviour change.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Relocate includes/intropage.js to js/intropage.js so all of the plugin's
JavaScript lives under js/ (alongside the relocated js/cards.js), matching the
standard Cacti plugin asset layout. Update the display.php include, the
functions.php and unit-test comments, and the chart-resize e2e spec that reads
the file. No behaviour change.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
The relocation added a top-level js/ directory and moved files out of
includes/, which tripped the expected-file-drift manifest validator. Add js/
to manifest.json 'expected', and record the vacated includes/cards/ directory
and includes/intropage.js under 'tombstones' so an upgrade prunes the stale
copies a previous version left behind.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@TheWitness
TheWitness force-pushed the feature/standard-cards-bundle branch from 0b12ef3 to 39410b8 Compare November 9, 2026 16:09
The new js/ asset directory ships the standard directory-index redirect stub
(js/index.php). Like the other entry-point stubs it is not reachable from the
isolated unit process, so the changed-line coverage gate cannot measure it;
add it to the unmeasured allowlist with a justification.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@TheWitness TheWitness changed the title cards: relocate shared card chrome to standard js/ and css/ paths cards: standardize the intropage asset layout (js/ + css/) for the shared card interface Nov 9, 2026
Clean up the shared card controller so it passes SonarCloud's Clean-as-You-Code
gate when a plugin first adds it as new code:

- use Number.parseInt instead of the global parseInt (javascript:S7773)
- give the fire-and-forget fetch/resize/add promise chains a .catch so an
  adapter rejection can't become an unhandled rejection (javascript:S9383)

No behaviour change; js/cards.js stays byte-identical across the plugins that
bundle it.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@TheWitness
TheWitness marked this pull request as ready for review November 9, 2026 16:29
Copilot AI balanced review requested due to automatic review settings November 9, 2026 16:29

Copilot AI 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.

🔵 Needs a closer look

The new empty rejection handlers silently swallow errors, including exceptions from controller callbacks, introducing an unvalidated behavior change beyond the stated content-neutral relocation.

No open issues 🎉

What changed in this PR

Standardizes intropage’s asset layout as groundwork for sharing the dashboard card interface across Cacti plugins and eventually moving it into core.

Changes:

  • Relocates card assets and the main plugin script into css/ and js/, updating loaders and test references.
  • Adds the JavaScript directory redirect stub, coverage exemption, and upgrade-pruning manifest entries.
  • Also changes promise rejection handling in the shared card controller.
File Description
tests/​Unit/​IntropagePanelReloadButtonTest.php Updates the script path in a comment.
tests/​e2e/​chart-resize.spec.cjs Loads resize helpers from the new script location.
tests/​e2e/​cacti-theme.spec.cjs Loads the relocated card stylesheet.
tests/​bin/​patch-coverage.php Exempts the new redirect stub from coverage.
setup.php Updates the card stylesheet include.
manifest.json Registers js/ and marks old asset paths for pruning.
js/​intropage.js Relocates the main script and updates a comment.
js/​index.php Adds the directory-index redirect.
js/​cards.js Relocates the controller and modifies parsing and rejection handling.
includes/​functions.php Updates the script path in PHPDoc.
display.php Updates JavaScript includes.
css/​cards.css Relocates the shared card styles.
CHANGELOG.md Documents the asset layout changes.

Review effort: Balanced

TheWitness and others added 5 commits November 9, 2026 11:41
Cacti 1.2.32 ships the shared card chrome in core (include/js/cards.js +
include/css/cards.css), loaded by the common page header. Guard the plugin's
bundled copies behind a version check so they are only enqueued on older cores;
on 1.2.32+ the core copy is used. The bundled files remain for backward
compatibility until the supported floor rises past 1.2.32.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
…quire the core file)

Only skip the bundled card chrome when Cacti is fully bootstrapped, is 1.2.32+,
AND actually ships include/*/cards.* (the version is bumped before the core
Card API lands, and isolated unit tests do not define CACTI_VERSION). This
avoids an undefined-constant fatal in the page-head unit test and keeps the
bundled copy loaded until a core that provides it is installed.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Switch the conditional to file_exists(include/*/cards.*) instead of a
CACTI_VERSION check. It is more robust: the version is bumped to 1.2.32 before
the core Card API lands, isolated unit tests do not define CACTI_VERSION, and
file presence directly answers whether core actually ships the chrome. The
bundled copy is loaded only when core does not provide it.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Adopt the hardened CactiCards controller from the core Card API review
(dragReference pointer-row resolution + findCard re-resolution of detached
references), keeping js/cards.js byte-identical with Cacti core and the other
plugin bundles.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
xmacan
xmacan previously approved these changes Nov 9, 2026
Selecting the same "Add" option twice while the first request is still
pending could append two cards with the same id, because the option stays
selectable until the debounced catalogue sync runs. The server deduplicates
saved ids, so the displayed layout then diverged from the restored one.

Guard the append in the shared controller with the existing findCard() lookup
so a card id already present is never appended a second time.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
TheWitness pushed a commit to Cacti/plugin_mactrack that referenced this pull request Nov 9, 2026
Re-syncs js/cards.js byte-identical with the intropage canonical bundle,
picking up the guard that skips an "Add" whose card id is already on the
grid. This closes the duplicate-card window where selecting the same option
twice while the first request was pending appended two cards with the same
id (which the server then deduplicated, diverging the displayed layout from
the restored one).

cards.js stays md5-identical to Cacti/plugin_intropage#473.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
TheWitness added a commit to Cacti/plugin_mactrack that referenced this pull request Nov 9, 2026
* cards: adopt the shared byte-identical card chrome

Converge the MacTrack dashboard on the shared dashboarding card interface so
the chrome can be promoted to Cacti core unchanged:

- js/cards.js is now the byte-identical shared CactiCards controller (was an
  inlined MacTrack-only copy); MacTrack-specific wiring moves to a thin
  js/mactrack_dashboard.js adapter (fetch/add/layout/maximize endpoints).
- css/cards.css is the byte-identical shared chrome; the card markup and CSS
  now use the shared .cc* contract. MacTrack's --cc-* theme bindings and
  card-body widgets (tables, key/value lists, bars) live in
  css/mactrack-dashboard.css.
- mactrack_view_dashboard.php renders .ccCard/.ccW*/.ccTool markup with the
  data-expandable/data-expanded attributes the shared chrome expects.

No functional change to the dashboard behaviour.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* cards: satisfy SonarCloud reliability rules in the shared controller

Re-sync the byte-identical shared card controller with the intropage canonical
copy, which now passes SonarCloud's Clean-as-You-Code gate:

- use Number.parseInt instead of the global parseInt (javascript:S7773)
- give the fire-and-forget fetch/resize/add promise chains a .catch so an
  adapter rejection can't become an unhandled rejection (javascript:S9383)

No behaviour change; js/cards.js remains byte-identical with plugin_intropage.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* cards: load the shared card chrome from core on Cacti 1.2.32+

Cacti 1.2.32 ships the shared card chrome in core (include/js/cards.js +
include/css/cards.css), loaded by the common page header. Guard the plugin's
bundled copies behind a version check so they are only enqueued on older cores;
on 1.2.32+ the core copy is used. The MacTrack-specific adapter and dashboard
CSS still load on every version. The bundled files remain for backward
compatibility until the supported floor rises past 1.2.32.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* cards: make the core-chrome detection robust (guard CACTI_VERSION, require the core file)

Only skip the bundled card chrome when Cacti is fully bootstrapped, is 1.2.32+,
AND actually ships include/js/cards.js (the version is bumped before the core
Card API lands). This keeps the bundled copy loaded - and its include lines
covered - until a core that provides the API is installed.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* cards: detect the core chrome by file presence, not Cacti version

Switch the conditional to file_exists(include/js/cards.js) instead of a
CACTI_VERSION check. It is more robust: the version is bumped to 1.2.32 before
the core Card API lands, and file presence directly answers whether core
actually ships the chrome. The bundled copy is loaded only when core does not
provide it.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* cards: sync the shared controller with the hardened canonical copy

Adopt the hardened CactiCards controller from the core Card API review
(dragReference pointer-row resolution + findCard re-resolution of detached
references) and the header-comment typo fix, keeping js/cards.js byte-identical
with Cacti core and the other plugin bundles.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* cards: sync the shared controller (skip duplicate concurrent adds)

Re-syncs js/cards.js byte-identical with the intropage canonical bundle,
picking up the guard that skips an "Add" whose card id is already on the
grid. This closes the duplicate-card window where selecting the same option
twice while the first request was pending appended two cards with the same
id (which the server then deduplicated, diverging the displayed layout from
the restored one).

cards.js stays md5-identical to Cacti/plugin_intropage#473.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* cards: serialize dashboard layout saves and theme the toolbar and dialog

Two MacTrack-specific fixes for the shared card dashboard:

- Serialize layout saves in the adapter. dash_layout replaces the entire
  saved layout, and the shared controller only debounces bursts within
  250 ms, so two reorders more than 250 ms apart could race and let an older
  request complete last, overwriting the user's final order/expanded state.
  Chain each POST after the previous one settles to preserve write order.

- Bind the --cc-* palette to the dashboard panel and the maximize dialog,
  not just the grid. The Add toolbar is a sibling of the grid and the dialog
  is moved under <body> by jQuery UI, so both previously fell back to the
  shared chrome's light-theme defaults (dark text, white select) on dark
  themes. Binding the panel and dialog lets all shared chrome follow the
  active theme.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

---------

Co-authored-by: TheWitness <copilot@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
intropage_page_head() now only prints the plugin's own css/cards.css when
core does not ship include/css/cards.css. The failing-job Cacti checkouts
ship that file, so the bundling branch (setup.php:496) never executed and the
changed-line coverage gate dropped to 50%. Add deterministic unit tests that
drive intropage_page_head() with base_path pointed at a temporary root both
without and with a core cards.css, exercising both sides of the guard.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@TheWitness
TheWitness marked this pull request as draft November 9, 2026 22:05
Update js/cards.js to the converged baseline (md5 84876af1) shared by Cacti
core (#8684 for 1.2.x, #8683 for develop) and every Card API plugin: the
refresh/resize supersede guard, async remove-commit, the duplicate-add guard
and expand/collapse keyboard focus. Byte-identical to core.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@TheWitness
TheWitness marked this pull request as ready for review November 11, 2026 00:24
bmfmancini
bmfmancini previously approved these changes Nov 11, 2026
Carry the shared Card API controller fix so a card refresh that lands while the
user expanded/collapsed it no longer reverts that toggle (replaceCard preserves
the live data-expanded at swap time). Byte-identical with core and the other
plugins.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Corrected shared controller (review on core #8700): replaceCard() carries the
live expand/collapse state onto refreshed markup only when the user toggled
during the request and the fresh card is still expandable; host markup stays
authoritative otherwise. Byte-identical with core and the other plugins.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@sonarqubecloud

Copy link
Copy Markdown

@TheWitness
TheWitness merged commit 9c3adbc into develop Nov 11, 2026
4 of 10 checks passed
@TheWitness
TheWitness deleted the feature/standard-cards-bundle branch November 11, 2026 16:54
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.

4 participants