DataVis NITRO

A React + Tailwind + @mieweb/ui UI built on top of the DataVis ACE data acquisition and computation engine.

Live Demo · Storybook · Rewrite Plan

DataVis is a set of tools for exploring, manipulating, and visualizing data. It features, among other things:

• Extensible data acquisition methods; it has builtin support for HTTP (XML, JSON, CSV), local CSV, in-page HTML table & JS value.
• Intelligent automatic handling of numerous data types such as dates, currency, and embedded JSON. User-added type handling is available.
• Efficient and extensive type-associated filtering, grouping, pivotting, and aggregation operations.
• Flexible user interfaces for exploring and understanding data, including tables and graphs. This project is one such interface.

graph LR
    subgraph ACE["DataVis ACE (from wcdatavis project)"]
        Source
        View
        Aggregates
        Types
        Prefs
    end

    subgraph Adapter["Adapter Layer"]
        EventBridge["EventBridge"]
        Hooks["useSource · useView · usePrefs"]
        TypeAdapter["Type formatting"]
    end

    subgraph ReactUI["React UI"]
        DataGrid["DataGrid"]
        Filters["FilterBar"]
        Controls["ControlPanel"]
        Tables["Table Renderers"]
        Dialogs["Dialogs"]
    end

    ACE --> Adapter --> ReactUI

    classDef core fill:#e8f5e9,stroke:#2e7d32
    classDef adapter fill:#fff3e0,stroke:#e65100
    classDef ui fill:#e3f2fd,stroke:#1565c0
    class Source,View,Aggregates,Types,Prefs core
    class EventBridge,Hooks,TypeAdapter adapter
    class DataGrid,Filters,Controls,Tables,Dialogs ui

Tech Stack

| Layer | Technology | |-------|-----------| | Framework | React 19 | | UI Components | @mieweb/ui (^0.2.2) | | Styling | Tailwind CSS 4 (@tailwindcss/vite) | | Build | Vite 6 (library mode, ES module output) | | Language | TypeScript 5.8 (strict) | | Drag & Drop | @dnd-kit/core + @dnd-kit/sortable | | Linting | ESLint 10 + typescript-eslint + jsx-a11y | | Storybook | Storybook 8.6 (React + Vite) | | i18n | TSV-based, 10 locales |

Quick Start

# Install dependencies
npm install

# Start dev server (http://localhost:5173)
npm run dev

# Start Storybook (http://localhost:6006)
npm run storybook

# Build library
npm run build

NPM Scripts

| Script | Description | |--------|-------------| | dev | Start Vite dev server | | build | Build library (ES module output to dist/) | | preview | Preview production build locally | | storybook | Start Storybook on port 6006 | | build-storybook | Build static Storybook site | | lint | Run ESLint + i18n key check | | lint:eslint | Run ESLint on src/ | | lint:i18n | Verify all t()/trans() keys exist in en-US.tsv | | lint:i18n:update | Auto-append missing i18n keys to TSV |

Project Structure

src/
├── index.ts              # Library entry point (exports adapters + components)
├── main.tsx              # Demo app (3-tab example with mock data)
├── adapters/             # Bridges wcdatavis core → React
│   ├── event-bridge.ts   # mixinEventHandling → React hooks
│   ├── use-data.ts       # useSource(), useView() hooks
│   ├── use-prefs.ts      # usePrefs() hook for perspectives
│   ├── type-adapter.ts   # Cell formatting + comparison
│   ├── group-adapter.ts  # Group function registry bridge
│   └── colconfig-adapter.ts  # Column config format bridge
├── components/
│   ├── DataGrid.tsx      # Top-level grid component
│   ├── TitleBar.tsx      # Header with title + action buttons
│   ├── GridToolbar.tsx   # Mode-aware composite toolbar
│   ├── DetailSlider.tsx  # Row detail slide-in panel
│   ├── OperationsPalette.tsx  # Row-level action buttons
│   ├── LoadingOverlay.tsx     # Spinner overlay
│   ├── LanguageSelector.tsx   # Locale picker (10 locales)
│   ├── controls/         # Group / Pivot / Aggregate control panel
│   ├── dialogs/          # Modal dialogs (6 total)
│   ├── filters/          # Per-column filter widgets
│   ├── table/            # Table renderers (plain, grouped, pivot)
│   └── toolbars/         # Plain, Group, Pivot, Prefs toolbars
├── demo/                 # Demo data + filter engine
├── i18n/                 # TransContext, useTranslation(), locale TSVs
└── scripts/              # i18n lint checker

Components

Core

| Component | Description | |-----------|-------------| | DataGrid | Top-level component composing title bar, toolbar, control panel, filter bar, table, and dialogs | | TitleBar | Grid header with title, row count badge, and action buttons (debug, export, refresh, controls toggle) | | GridToolbar | Shows the right toolbar based on data mode — plain, grouped, or pivot | | GlobalSearchControl | Plain-mode visual search across visible columns with highlighting and an accessible result count | | DetailSlider | Slide-in panel from the right edge for row detail content | | OperationsPalette | Inline toolbar of icon buttons for row-level operations | | LoadingOverlay | Block-UI overlay with @mieweb/ui Spinner | | LanguageSelector | Locale picker supporting 10 languages |

Controls

| Component | Description | |-----------|-------------| | ControlPanel | Four-section panel: Filter, Group, Pivot, Aggregate. Uses @dnd-kit for drag-and-drop field reordering | | ControlSection | Single section with dropdown to add fields and a sortable field list | | AggregateSection | Aggregate function selector with multi-field argument support | | FieldPill | Draggable field chip with optional group-function button |

Filters

| Component | Description | |-----------|-------------| | FilterBar | Composite filter bar — one filter widget per visible column | | StringFilter | Text/dropdown filter with contains, equals, in, blank operators | | NumberFilter | Numeric filter with comparison operators | | DateFilter | Date filter with on/before/after/between/every/current/last operators | | BooleanFilter | Checkbox filter for boolean columns | | FilterContext | React context for dynamic filter management (add/remove from column headers) |

Plain-Mode Global Search

The plain grid toolbar includes a debounced global search that visually narrows the rows already returned by ACE. It searches formatted display text across visible columns before NITRO's row display limit, so matches beyond the first rendered batch are included. Existing per-column ACE filters run first, and global search narrows their result without changing the ACE filter specification or rerunning grouping, pivoting, aggregation, sorting, or data acquisition.

The feature is intentionally visual-only and plain-mode-only. It is hidden and cleared in grouped or pivoted output, and it does not change ACE counts, aggregates, CSV exports, clipboard exports, preferences, or other consumers of the underlying view. Custom cell renderers can provide exact searchable display text through TableColumn.getSearchText.

Table Renderers

| Component | Description | |-----------|-------------| | TableRenderer | Selects sub-renderer based on data mode (plain / group-detail / group-summary / pivot) | | PlainTable | Flat table with column resize, reorder, sticky headers, context menu, sort, keyboard nav, row selection, zebra striping | | GroupDetailTable | Grouped view with collapsible headers, per-group aggregates, two-row sub-column headers | | GroupSummaryTable | One-row-per-group summary with aggregate values | | PivotTable | Pivot matrix of row-values × column-values with aggregate cells | | HeaderContextMenu | Right-click context menu for column headers |

Dialogs

| Component | Description | |-----------|-------------| | ColumnConfigDialog | Column order, visibility, display names, per-column flags with drag-and-drop reordering | | TemplateEditorDialog | Edit Handlebars/Squirrelly templates for plain, grouped, and pivot modes | | DebugDialog | Live debug info in 4 tabs (Source, View, Grid, Prefs) with collapsible JSON sections | | GridTableOptionsDialog | Cell display-format template customization | | GroupFunctionDialog | Group function selector with categorized buttons | | PerspectiveManagerDialog | Perspective CRUD — JSON inspector, create/rename/delete |

Toolbars

| Component | Description | |-----------|-------------| | PlainToolbar | Auto show-more, show all, columns, templates, row mode, auto resize | | GroupToolbar | Group mode toggle, total row, expand all, pin groups | | PivotToolbar | Show totals, pin groups, hide zero values, templates | | PrefsToolbar | Perspective reset, back/forward, perspective dropdown, save/rename/delete |

Adapter Layer

The adapter layer bridges the legacy wcdatavis data-processing objects into React without modifying the original code.

| Module | Purpose | |--------|---------| | EventBridge | Converts mixinEventHandling pub/sub (.on/.off/.fire) to React hooks: useDataVisEvent(), useDataVisEvents() | | useSource() | Wraps Source construction and data fetching with reactive state | | useView() | Wraps ComputedView lifecycle — sorting, filtering, grouping, pivoting, aggregation | | usePrefs() | Wraps Prefs for perspective management (reset, history, CRUD) | | formatCellValue() | Bridges types.js formatters to React-safe output | | compareValues() | Type-aware comparison for client-side sorting | | adaptGroupFunctionRegistry() | Converts legacy group function registry to React GroupFunction[] | | ordMapToColumnConfigs() | Converts OrdMap<FieldColConfig> to React ColumnConfig[] |

Adapter Rules

1. No jQuery in new UI code — all DOM is React-owned
2. Event bridge — legacy event system maps to React callbacks and hooks
3. Data hooks — useSource() and useView() expose reactive state
4. Type formatting — reuses types.js formatters, converting HTML output to React elements where needed
5. i18n — reuses trans() directly via TransContext

Internationalization (i18n)

Translations are stored as tab-separated key/value pairs in TSV files. The English source of truth is src/i18n/en-US.tsv.

Supported locales: en-US, es-MX, fr-FR, id-ID, nl-NL, pt-BR, ru-RU, th-TH, vi-VN, zh-Hans-CN

Components use the useTranslation() hook which provides a t(key, ...args) function. The default returns '' for unknown keys so the t(KEY) || 'Fallback' pattern works throughout.

# Check all i18n keys are defined
npm run lint:i18n

# Auto-append missing keys with fallback text
npm run lint:i18n:update

The i18n lint script (scripts/check-i18n-keys.mjs) uses the TypeScript compiler API to walk src/ and extract all t()/trans() calls, then compares against keys defined in the TSV.

Aggregation Functions

The grid supports 8 aggregate functions that compute per-group values in grouped table mode:

| Function | Label | Description | |----------|-------|-------------| | sum | Sum | Numeric sum | | avg | Average | Arithmetic mean | | count | Count | Row count (no field required) | | counta | Count Values | Count of non-null/non-empty values | | countu | Count Unique | Count of distinct non-null/non-empty values | | min | Min | Minimum value | | max | Max | Maximum value | | list | Unique Values | Comma-separated unique non-empty values |

Aggregate values appear in group header rows, aligned under matching column headers with a two-row sub-column layout (e.g., Salary → SUM | AVG).

Demo App

The demo (src/main.tsx) provides three tabbed example grids with mock data:

| Tab | Rows | Columns | Description | |-----|------|---------|-------------| | Simple | 8 | 8 | Employee directory | | Wide (50 columns) | 20 | 50 | Contact + appointment + location data | | Large (5K rows) | 5,000 | 33 | Financial ledger + inventory |

Start the demo with npm run dev and open http://localhost:5173.

Storybook

Interactive component catalog with stories for all major components:

| Story | Components | |-------|-----------| | DataGrid | Full grid with mock data | | ControlPanel | Group/Pivot/Aggregate controls | | DetailSlider | Row detail slide-in panel | | Dialogs | All 6 dialog components | | FilterBar | Filter widgets for all column types | | TableRenderer | Plain, grouped, and pivot table modes |

Start Storybook with npm run storybook and open http://localhost:6006.

Rewrite Status

The rewrite follows a phased approach documented in v0-rewrite-plan.md.

| Phase | Description | Status | |-------|-------------|--------| | 0 | Scaffold & adapter layer | ✅ Complete | | 1 | Grid shell (DataGrid, Toolbar, Slider, LoadingOverlay) | ✅ Complete | | 2 | Filters & Control Panel | ✅ Complete | | 3 | Dialog components (6 dialogs) | ✅ Complete | | 4 | Table renderer (plain, grouped, pivot) | ✅ Complete | | 5 | Graph shell (Chart.js wrapper) | Planned | | 6 | Polish & integration | In progress |

Additional features landed post-Phase 4: sorting end-to-end, client-side filtering, i18n lint guard, accessibility audit (ARIA labels, keyboard nav, focus management), group-by with aggregates.

License

MIT — Copyright (c) 2025 Medical Informatics Engineering, Inc.