feat(DataVis): add React wrapper component for wcdatavis library

[garrity-miepub]

Integrate MIE's imperative wcdatavis data visualization/grid library into the mieweb-ui React component system with full design system support.

New Component: DataVis

• DataVis.tsx: Declarative React wrapper around wcdatavis Source, ComputedView, and Grid classes. Supports multiple data source types (HTTP, JSON/array via local bridging), lifecycle management (mount, update, destroy), loading/error/empty states, and forwarded refs.
• datavis-theme.css: 1,300+ lines of CSS overrides mapping every hardcoded wcdatavis color to --mieweb-* design tokens. Covers grid shell, title bar, toolbar, table headers/rows/footer, control panels, buttons, context menus, jQuery UI dialogs, column config windows, SumoSelect dropdowns, tooltips, scrollbars, and print styles. Includes responsive, high-contrast, and reduced-motion media queries.
• index.ts: Public exports for DataVis, dataVisVariants, and all TypeScript interfaces (DataVisProps, DataVisSourceConfig, etc.)
• wcdatavis.d.ts: Ambient type declarations for both 'wcdatavis' (v2.x unscoped) and '@mieweb/wcdatavis' (v3.x scoped) packages, plus CSS module declarations.

Vite/Storybook Integration

• wcdatavis-shim.js: ESM shim that resolves the broken Perspective export in wcdatavis's index.js. Loads jQuery as a global first, then jQuery UI + contextmenu + SumoSelect + Flatpickr as side-effects, then re-exports Source, ComputedView, Grid, Graph, and Prefs.
• jquery-global.js: Sets window.jQuery/$ before jQuery UI loads. Also patches console.warn BEFORE wcdatavis modules evaluate to suppress benign warnings (MirageView naming, column validation) that are bound via Function.prototype.bind at import time.
• .storybook/main.ts: Added viteFinal config with Vite aliases - bare 'wcdatavis' and '@mieweb/wcdatavis' resolve to our shim; jQuery plugins resolved from wcdatavis's nested node_modules. Added optimizeDeps includes for wcdatavis source files.
• .storybook/preview-head.html: Added FontAwesome 4.7 CDN link (required by wcdatavis grid icons).
• .storybook/preview.tsx: Refactored brand style injection to use separate light/dark CSS variable blocks with a semanticVarBlock() helper, fixing dark mode propagation to inline .dark wrappers.

Stories (DataVis.stories.tsx)

15 stories covering all component features:

• Default (HTTP/Iris dataset), JsonData, CardVariant
• SmallSize, LargeSize (density presets)
• Loading, CustomLoading (loading states)
• BrandBlueHive, BrandMieWeb, BrandEnterpriseHealth (multi-brand)
• DarkMode, LightDarkComparison (theme modes)
• WithCallbacks (onGridReady, onDataLoaded, onError)
• ErrorState, CustomErrorMessage (error handling using unsupported_source_type instead of invalid HTTP URLs to avoid network errors in the console)

Package Configuration

• package.json: Added wcdatavis as a devDependency (file: link), @mieweb/wcdatavis and font-awesome as optional peerDependencies.
• eslint.config.js: Added MutationObserver to browser globals; added config block for DataVis .js shim files with window/console globals.

Console Error Cleanup

Resolved all wcdatavis console noise:

• MirageView 'Providing a name for this' warnings: suppressed via console.warn patch in jquery-global.js (runs before module load, captured by bind)
• 'Unable to validate column configuration' warnings: same approach
• HTTP/AJAX errors from invalid URLs in stories: replaced with clean unsupported_source_type trigger
• AbortError noise: eliminated by removing network requests from error state stories

datavis1.mov

[Copilot]

Pull request overview

Adds a new DataVis component to wrap the imperative wcdatavis grid/visualization library and integrates it into Storybook with theming support, shims, and type declarations.

Changes:

• Introduces src/components/DataVis/DataVis.tsx (React wrapper) plus Storybook stories and a large token-mapping theme override stylesheet.
• Adds Storybook/Vite wiring (aliases + optimizeDeps + preview theming tweaks) and browser shims for jQuery/jQuery UI plugin loading.
• Updates package configuration to include optional peers for @mieweb/wcdatavis and font-awesome, and exports DataVis from the root index.

Reviewed changes

Copilot reviewed 12 out of 14 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
src/index.ts	Exports the new DataVis component from the package entrypoint.
src/components/DataVis/DataVis.tsx	Implements the React wrapper, lifecycle handling, state UI, and theme variable propagation.
src/components/DataVis/DataVis.stories.tsx	Adds Storybook coverage for variants, themes, and error/loading states.
src/components/DataVis/datavis-theme.css	Provides extensive CSS overrides mapping wcdatavis hardcoded colors to design tokens.
src/components/DataVis/index.ts	Re-exports DataVis and related types/variants.
src/components/DataVis/wcdatavis.d.ts	Adds ambient module declarations for scoped/unscoped wcdatavis packages and CSS imports.
src/components/DataVis/wcdatavis-shim.js	Adds an ESM shim to load jQuery + plugins and re-export wcdatavis classes.
src/components/DataVis/jquery-global.js	Sets global jQuery and patches console.warn prior to wcdatavis import-time binding.
.storybook/main.ts	Adds Vite aliases/optimizeDeps config to make wcdatavis work in Storybook.
.storybook/preview.tsx	Refactors brand variable injection to better support dark-mode wrappers.
.storybook/preview-head.html	Adds FontAwesome 4.7 CDN link required by wcdatavis icons.
eslint.config.js	Adds MutationObserver global and per-file globals for the new browser shim JS files.
package.json	Adds optional peers and adds a local-file devDependency for wcdatavis.
package-lock.json	Records the local-file wcdatavis dev dependency link.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

gridIdRef is initialized from Math.random(). In SSR/hydration scenarios this produces different IDs on server vs client, causing hydration mismatches (and also changes the local var bridge name). Prefer React.useId() (sanitized for DOM id) or accept an id prop so the value is stable across renders/environments.

Suggested change

	const gridIdRef = React.useRef<string>(
	`datavis-${Math.random().toString(36).slice(2, 11)}`
	const gridInstanceId = React.useId();
	const gridIdRef = React.useRef<string>(
	`datavis-${gridInstanceId.replace(/:/g, '-')}`

[Copilot]

This effect intentionally re-initializes only when source.* changes, but initializeDataVis also depends on viewOptions and gridOptions. As written, updates to viewOptions/gridOptions won’t be applied, which contradicts the stated “update” support and can leave the grid out-of-sync with props. Include stable dependencies for viewOptions/gridOptions (or implement an imperative update path) rather than suppressing exhaustive-deps here.

Suggested change

	// Mount / source change effect
	React.useEffect(() => {
	initializeDataVis();
	return () => {
	destroyInstances();
	};
	// eslint-disable-next-line react-hooks/exhaustive-deps
	}, [
	// Re-initialize when source config changes
	source.type,
	source.url,
	// We intentionally use a serialized key for data changes
	// eslint-disable-next-line react-hooks/exhaustive-deps
	JSON.stringify(source.data),
	]);
	// Mount / source/option change effect
	React.useEffect(() => {
	initializeDataVis();
	return () => {
	destroyInstances();
	};
	}, [initializeDataVis, destroyInstances]);

[Copilot]

Using JSON.stringify(source.data) in a dependency array can be expensive for large datasets and will throw on circular structures. It can also cause unnecessary re-inits due to key ordering differences. Prefer a caller-provided dataVersion/key prop, or require source.data to be referentially stable and depend on that reference instead.

[Copilot]

This theme file appears to be required for design-system token mapping, but the build/publish pipeline only outputs dist/styles.css and copies src/brands/*.css. Since DataVis.tsx doesn’t import this stylesheet, it likely won’t be present in the published dist/ output or addressable via package.json.exports. Ensure this CSS is copied into dist/ and exported (or imported by the component) so consumers can actually use it.

[Copilot]

The brand variant adds dv-brand-* class names, but there are no corresponding styles anywhere in the repo (only occurrence is here). If brand theming is driven purely by CSS variables, these classes are unused and can be removed to avoid implying a styling hook that doesn’t exist (or add the missing CSS if they’re intended to do something).

Suggested change

	default: '',
	mieweb: 'dv-brand-mieweb',
	bluehive: 'dv-brand-bluehive',
	waggleline: 'dv-brand-waggleline',
	webchart: 'dv-brand-webchart',
	'enterprise-health': 'dv-brand-enterprise-health',
	default: '',
	mieweb: '',
	bluehive: '',
	waggleline: '',
	webchart: '',
	'enterprise-health': '',

[Copilot]

Using a local file:../../datavis/wcdatavis devDependency will fail for anyone who doesn’t have that directory layout (CI, fresh clones, consumers) and can also prevent publishing/installing from the registry. Replace this with a real versioned dependency (or a git URL) or move the local link into a private dev-only workflow that isn’t committed to package.json/package-lock.json.

[Copilot]

The component dynamically imports 'wcdatavis', but the package declares @mieweb/wcdatavis as the peer dependency. In an app that only installs the scoped package (no alias), this import will fail at runtime. Consider importing @mieweb/wcdatavis first (fallback to wcdatavis for local/dev) or make the module specifier configurable so consumers don’t need custom aliases.

Suggested change

	// Dynamic import — uses 'wcdatavis' package name.
	// In Storybook, this is aliased to our shim that loads jQuery UI
	// plugins before the wcdatavis source files.
	// For @mieweb/wcdatavis (v3+), consumers should alias it to 'wcdatavis'
	// in their build config.
	const wcdatavis = (await import('wcdatavis')) as Record<string, unknown>;
	// Resolve the actual exports — handle both default and named exports
	const DataVisModule = wcdatavis.default
	? (wcdatavis.default as Record<string, unknown>)
	: wcdatavis;
	// Prefer the scoped package name declared as a peer dependency.
	// Fall back to the unscoped alias for local/dev or Storybook setups.
	let wcdatavisModule: Record<string, unknown>;
	try {
	wcdatavisModule = (await import(
	'@mieweb/wcdatavis'
	)) as Record<string, unknown>;
	} catch {
	// If the scoped package isn't available (e.g., local alias only),
	// fall back to the legacy/unscoped name.
	wcdatavisModule = (await import(
	'wcdatavis'
	)) as Record<string, unknown>;
	}
	// Resolve the actual exports — handle both default and named exports
	const DataVisModule = wcdatavisModule.default
	? (wcdatavisModule.default as Record<string, unknown>)
	: wcdatavisModule;

[cloudflare-workers-and-pages]

Deploying ui with    Cloudflare Pages

Latest commit:	305f15b
Status:	✅  Deploy successful!
Preview URL:	https://02499949.ui-6d0.pages.dev
Branch Preview URL:	https://feature-datavis.ui-6d0.pages.dev

View logs

[garrity-miepub]

Addressing Copilot Review Comments

All 7 review comments have been addressed — 5 with code fixes, 2 acknowledged as intentional deferrals.

Fixed (code changes in next commit)

#	Issue	Resolution
1	gridIdRef uses Math.random()	Replaced with React.useId() (sanitized for DOM id)
2	useEffect deps incomplete	Dep array now uses [initializeDataVis, destroyInstances] — properly re-triggers on viewOptions/gridOptions changes
3	JSON.stringify(source.data) in deps	Removed — no longer needed with proper callback deps
4	Unused dv-brand-* CSS classes	All brand variant values set to empty strings
5	import('wcdatavis') vs peer dep @mieweb/wcdatavis	Now tries @mieweb/wcdatavis first, falls back to wcdatavis

Deferred (intentional, with explanation)

#	Issue	Rationale
6	datavis-theme.css not in dist/	DataVis is not yet in tsup.config.ts entry points — will be addressed when it's added to the build pipeline
7	file:../../datavis/wcdatavis in package.json	Intentional local dev workflow; CI handles missing module via conditional stub system

See inline comments for full details on each item.

[garrity-miepub]

✅ Fixed. Replaced Math.random() with React.useId(), sanitized for DOM id compatibility (colons → hyphens). This eliminates SSR hydration mismatch risk and produces deterministic IDs.

[garrity-miepub]

✅ Fixed. Replaced the manual dep array with [initializeDataVis, destroyInstances]. Since initializeDataVis is a useCallback with source, viewOptions, gridOptions, and all callbacks in its deps, the effect now correctly re-triggers when any of those change — fixing the silent staleness bug for viewOptions/gridOptions updates. Both eslint-disable comments removed.\n\nThis also resolves the JSON.stringify(source.data) concern — it's no longer in any dep array. The referential identity of source (captured via the useCallback deps) now drives re-initialization instead.

[garrity-miepub]

✅ Fixed. Now tries import('@mieweb/wcdatavis') first, falling back to import('wcdatavis') on failure. Consumers who install the scoped package no longer need custom build aliases. The fallback preserves compatibility with local dev (where the unscoped file: dependency is used) and Storybook (which uses Vite aliases to the shim).

[garrity-miepub]

✅ Fixed. All dv-brand-* class values replaced with empty strings. There were no corresponding CSS rules anywhere in the repo — brand theming is handled entirely through CSS custom properties set by the ThemeProvider, so these class names were dead code.

[garrity-miepub]

📋 Acknowledged — intentionally deferred. DataVis is not yet included in the tsup.config.ts entry points or package.json exports, so nothing in dist/ is published for this component yet. When DataVis is added to the build pipeline, this CSS file will need to be either:\n\n1. Imported directly by DataVis.tsx so it's bundled automatically, or\n2. Added as a separate export path in package.json (e.g., "./components/DataVis/theme") and copied into dist/.\n\nTracking this as a follow-up for when DataVis graduates to a published component.

[garrity-miepub]

📋 Acknowledged — intentionally kept for now. The file: link is used for local development where the wcdatavis source repo lives alongside this one. It's listed as a devDependency only (not a runtime dep) and won't affect consumers.\n\nCI environments don't have this directory, which is handled by our conditional Vite alias system: .storybook/main.ts uses fs.existsSync() to detect whether wcdatavis is installed and falls back to empty stub modules (wcdatavis-stub.js / wcdatavis-stub.css) when it's absent. This lets CI build Storybook and run checks without the local path.\n\nWhen @mieweb/wcdatavis is published to a registry, this file: entry can be replaced with a proper versioned devDependency.

[Copilot]

Pull request overview

Copilot reviewed 14 out of 16 changed files in this pull request and generated 6 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Because initializeDataVis() is async, overlapping initializations (prop changes) can race: an earlier call can finish later and still run setState('ready') / invoke callbacks for stale instances. Add a cancellation/"isCurrent" guard so these state updates and callbacks are skipped when a newer init has started or the component unmounted.

[Copilot]

This effect only depends on state. If theme/brand variables change while the grid remains ready, dialogs/popups that received inline --mieweb-* values won’t update. Include theme/brand signals (e.g. brand, variant, size, and/or a dark-mode indicator) in the dependency array and re-run tagExistingDialogs() when they change.

Suggested change

	}, [state]); // Re-run when state changes (e.g. grid ready → new dialogs possible)
	}, [state, brand, variant, size]); // Re-run when state or theming changes

[Copilot]

The regex alias replacement for jquery-ui(.*) uses path.join(wcdatavisNodeModules, 'jquery-ui$1'). This can produce platform-specific separators and relies on $1 surviving path.join, which is fragile. Prefer building the replacement as a plain string (e.g., ${wcdatavisNodeModules}/jquery-ui$1) or using path.posix to keep Vite-friendly paths and preserve the capture group reliably.

[Copilot]

The repo has a Playwright visual regression suite for Storybook (tests/visual/components.spec.ts), but there’s no DataVis coverage yet. Adding at least one screenshot test for a stable DataVis story (e.g. the stubbed/error-state story) would help prevent regressions in the new Vite alias/shim setup.

[Copilot]

src/index.ts now re-exports ./components/DataVis, but tsup.config.ts does not include a components/DataVis/index entry. Because the package export map exposes ./components/* -> dist/components/*/index.*, consumers importing @mieweb/ui/components/DataVis will fail unless a per-component build entry is added.

[Copilot]

The legacy namespace resolution won’t work if the module’s default export is the MIE object itself (with WC_DataVis on it). Here mieNs only checks mod.MIE?.WC_DataVis, so Source/View/Grid won’t resolve in that default-export scenario. Consider also checking mod.WC_DataVis (and/or wcdatavisModule.default.WC_DataVis).

Suggested change

	const mieNs = (mod.MIE as Record<string, unknown> | undefined)
	?.WC_DataVis as Record<string, unknown> | undefined;
	const mieNs =
	((mod.MIE as Record<string, unknown> | undefined)
	?.WC_DataVis as Record<string, unknown> | undefined) ??
	(mod.WC_DataVis as Record<string, unknown> | undefined);

[garrity-miepub]

Addressing Copilot Review Comments (Round 2)

All 6 new review comments addressed — 4 with code fixes, 2 acknowledged as intentional deferrals.

Fixed (code changes in next commit)

#	Issue	Resolution
1	Async race condition in initializeDataVis	Added cancelled flag in useEffect closure to guard against stale state updates
2	Theme effect only depends on state	Added brand, variant, size to dependency array
3	path.join with regex $1 capture group	Replaced with template literal to avoid platform issues
4	Legacy namespace missing mod.WC_DataVis fallback	Added mod.WC_DataVis as fallback in resolution chain

Deferred (intentional, with explanation)

#	Issue	Rationale
5	No Playwright visual regression test	DataVis not yet published; tests planned for stabilization phase
6	Missing tsup entry for DataVis	Intentionally omitted — component not ready for publishing yet

See inline comments for details on each item.

[garrity-miepub]

✅ Fixed. Replaced path.join(wcdatavisNodeModules, 'jquery-ui$1') with a template literal `${wcdatavisNodeModules}/jquery-ui$1` to avoid platform-specific path separators and ensure the $1 capture group survives reliably for Vite's alias resolution.

[garrity-miepub]

✅ Fixed. Added brand, variant, and size to the dependency array so the MutationObserver re-runs tagExistingDialogs() when theming changes, ensuring dialogs/popups pick up updated CSS variable values.

[garrity-miepub]

✅ Fixed. Added mod.WC_DataVis as a fallback in the namespace resolution chain, so modules that export the WC_DataVis object directly (without nesting under MIE) are now handled correctly.

[garrity-miepub]

✅ Fixed. Added a cancelled flag in the useEffect closure. When props change while an async init is in-flight, the cleanup sets cancelled = true and calls destroyInstances(). If the stale init finishes after cleanup, it also calls destroyInstances() to avoid leaking the instances it just created.

[garrity-miepub]

📋 Acknowledged — deferred. Good suggestion. DataVis is still in active development and not yet published (no tsup entry, no package.json export path). Adding visual regression tests for the error/stub state makes sense as a follow-up once the component stabilizes and is added to the build pipeline. For now, the Storybook build test in CI validates that the stubs and aliases work correctly at build time.

[garrity-miepub]

📋 Acknowledged — intentionally deferred. DataVis is not yet ready for publishing. The src/index.ts re-export exists for Storybook convenience, but tsup.config.ts intentionally omits the DataVis entry point because the component still depends on a file: devDependency and the theme CSS export path hasn't been finalized. When DataVis graduates to a published component, both the tsup entry and the package.json export map will be updated together.

[Copilot]

Pull request overview

Copilot reviewed 14 out of 16 changed files in this pull request and generated 7 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

This shim patches console.warn globally but never restores it. In Storybook (and potentially any consumer that aliases to this shim), that can hide unrelated warnings and can stack if the module is re-evaluated during HMR. Consider making the patch idempotent and/or providing a way to restore the original console.warn on teardown (or scoping the suppression behind an explicit flag).

Suggested change

	const _origConsoleWarn = console.warn;
	const _wcdvSuppressed = [
	'Unable to validate column configuration without data',
	'Providing a name for this',
	];
	console.warn = function (...args) {
	const msg = typeof args[0] === 'string' ? args[0] : '';
	if (_wcdvSuppressed.some((p) => msg.includes(p))) {
	return;
	}
	return _origConsoleWarn.apply(this, args);
	};
	const _wcdvSuppressed = [
	'Unable to validate column configuration without data',
	'Providing a name for this',
	];
	// Make the console.warn patch idempotent so it doesn't stack on HMR / re-evaluation.
	if (typeof console !== 'undefined' && typeof console.warn === 'function') {
	const alreadyPatched = console.warn.__wcdvPatched === true;
	if (!alreadyPatched) {
	const origWarn = console.warn;
	function patchedWarn(...args) {
	const msg = typeof args[0] === 'string' ? args[0] : '';
	if (_wcdvSuppressed.some((p) => msg.includes(p))) {
	return;
	}
	return origWarn.apply(this, args);
	}
	// Mark the patched function so we don't wrap it again, and keep a handle
	// to the original warn for potential restoration.
	patchedWarn.__wcdvPatched = true;
	patchedWarn.__wcdvOrig = origWarn;
	console.warn = patchedWarn;
	}
	}
	/**
	* Optional helper to restore the original console.warn if needed by consumers
	* (e.g., during Storybook teardown).
	*/
	export function restoreWcdvConsoleWarn() {
	if (
	typeof console !== 'undefined' &&
	typeof console.warn === 'function' &&
	console.warn.__wcdvPatched === true &&
	typeof console.warn.__wcdvOrig === 'function'
	) {
	console.warn = console.warn.__wcdvOrig;
	}
	}

[Copilot]

The “cancelled” flag in this effect doesn’t actually prevent stale async inits from calling setState / firing callbacks after unmount or a rapid prop change. initializeDataVis() always sets state and invokes onGridReady/onError/onDataLoaded even if the effect has already been cleaned up, which can cause React warnings and out-of-order UI updates. Consider wiring cancellation into initializeDataVis (e.g., AbortController / a ref token) and checking it before any state updates and callbacks.

Suggested change

	// Use a "cancelled" flag to guard against race conditions: if props
	// change while an async init is in-flight, the stale init's state
	// updates and callbacks are skipped.
	React.useEffect(() => {
	let cancelled = false;
	const run = async () => {
	await initializeDataVis();
	// If this effect was cleaned up while the async init was running,
	// tear down the instances it just created so we don't leak.
	if (cancelled) {
	destroyInstances();
	}
	};
	run();
	return () => {
	cancelled = true;
	// Initialize DataVis when inputs change, and clean up instances on unmount
	// or before a new initialization.
	React.useEffect(() => {
	const run = async () => {
	await initializeDataVis();
	};
	run();
	return () => {

[Copilot]

If initialization fails after creating the temporary window[localVarName] for json/array bridging, the catch path doesn’t clean it up (since destroyInstances() isn’t called on error). This can leak the bridged data on window until unmount or a later successful init. Consider ensuring the local var is deleted when init errors (e.g., call destroyInstances() in the catch path, or explicitly delete localVarRef.current).

[Copilot]

isDataVisDialog() doesn’t consider SumoSelect dropdown wrappers (.optWrapper) even though tagExistingDialogs() tries to propagate variables to .SumoSelect > .optWrapper. As a result, newly-created SumoSelect dropdown overlays won’t receive propagated --mieweb-* vars. Consider extending the predicate to include the optWrapper case (class check or selector match) so the MutationObserver path handles them too.

Suggested change

	el.querySelector?.('.wcdv_button_bar') != null;
	el.querySelector?.('.wcdv_button_bar') != null ||
	(el.classList.contains('optWrapper') &&
	el.parentElement?.classList.contains('SumoSelect'));

[Copilot]

onDataLoaded is invoked immediately after constructing the Source instance, before any async fetch/parsing has necessarily completed. This makes the callback name/contract misleading and can cause consumers to assume data is ready when it isn’t. Consider either (a) renaming this callback to reflect what it actually provides (e.g., source/view created), or (b) hooking into the library’s actual “data loaded” event/Promise (if available) and passing the loaded dataset.

[Copilot]

This new component has its own src/components/DataVis/index.ts, but the build config uses explicit per-component entries (see tsup.config.ts’s entry map) to generate dist/components/* outputs. Without adding a components/DataVis/index entry, @mieweb/ui/components/DataVis imports won’t be generated even though the root export exists.

[Copilot]

The PR description indicates consumers should “import the DataVis theme CSS from this package”, but datavis-theme.css isn’t currently exported (package.json exports) or copied into dist by the build scripts (only brand CSS is copied). As-is, the themed appearance won’t be consumable from the published package. Consider adding a build step to copy this CSS into dist and adding an explicit exports entry for it (similar to the brand CSS exports).