pt/dataflow
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
transformed-refactor
dataflow/PERSPECTIVE.md
Paul Trowbridge 442c38d3c4 Add PERSPECTIVE.md documenting the @perspective-dev version pairing 
Records why the 4.5.1 viewer/client + 4.4.1 d3fc pairing is deliberate,
not a skew to "fix": the /inline and /themes entrypoints exist only in
4.5.x, while viewer-d3fc caps at 4.4.1, so this is the only combination
that keeps both inline WASM bundling and the d3fc charts. Verified by
build failure when pinning all four to 4.4.1. Points to the canonical
guide in pf_app for shared rationale.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-06-15 23:53:31 -04:00

2.6 KiB
Raw Permalink Blame History

Perspective — dataflow specifics

Shared rationale lives in the canonical guide: /home/pt/pf_app/PERSPECTIVE.md (loading, version policy, Arrow constraints, deploy pattern, upgrade smoke test). This file records only what's specific to dataflow.

Distribution: these are the @perspective-dev/* packages (repo github.com/perspective-dev/perspective), not FINOS @finos/perspective. Same engine, separate npm scope and release schedule — don't mix the two.

Current state

  • Loader: npm /inline (ui/src/pages/Pivot.jsx) — bundled WASM, offline-capable. ✅ This is the target loader; pf_app should adopt it.
  • Data: JSON rows via api.getViewData(source, 100000, 0), capped at 100k. ✅ Correct for dataflow's read-only, click-to-inspect model. No need to move to Arrow unless view sizes grow well past 100k.
  • Deploy: deploy.sh + dataflow.service (systemd) + nginx. ✅ Reference pattern for the org; pf_app should copy it.
  • Charts: viewer-d3fc is imported, so the chart plugins are available in the UI. Default plugin config is datagrid-only ({ edit_mode: 'SELECT_REGION' }).
  • Layout safety: cleanLayout() filters saved configs against valid columns before restore — the reference implementation; keep it.

The version pair is correct — do NOT "fix" it to 4.4.1

ui/package.json pins viewer/client/datagrid at ^4.5.1 and viewer-d3fc at ^4.4.1. This looks like a skew but is deliberate and necessary — it's the only combination that keeps both of dataflow's hard requirements:

  • Inline WASM bundling. Pivot.jsx imports @perspective-dev/client/inline, @perspective-dev/viewer/inline, and @perspective-dev/viewer/themes. Those export paths exist only in 4.5.x — they are absent from 4.4.1's exports map.
  • d3fc chart plugins. viewer-d3fc is published only up to 4.4.1.

Verified the hard way: pinning all four to 4.4.1 and rebuilding fails with "./inline" is not exported … from @perspective-dev/client. So the 4.5.1/4.4.1 pair stays. Don't touch it.

What to actually do:

  • Keep the versions as-is; commit package-lock.json so the resolved set can't drift on npm install. (Optionally tighten the carets to exact 4.5.1/4.4.1 to make that explicit.)
  • Treat any Perspective bump as gated by the canonical smoke test (§7): a d3fc chart renders, dark/light re-themes, and save→reload→drop-column layout restore.
  • Revisit only when viewer-d3fc ships a 4.5.x — then a fully-coherent inline-capable 4.5.x suite becomes possible and the pair can collapse to one version.