@settleup/visualizations-react

Headless React hooks and types for building data visualizations — datagrids, charts, and metrics. This package provides the state management and data-fetching layer; pair it with @settleup/visualizations-shadcn (or your own UI components) for rendering.

Installation

npm install @settleup/visualizations-react

Peer Dependencies

• react ^19.0.0
• react-dom ^19.0.0

Overview

This package exports three categories of building blocks:

1. Hooks — Manage data fetching, filtering, sorting, and pagination
2. Types — TypeScript interfaces for schemas, controllers, filters, sorts, and more
3. Utilities — Helpers for formatting and filter construction

Hooks

useDataGrid

Manages the full lifecycle of a datagrid: schema fetching, data loading, filtering, sorting, pagination, column visibility, row selection, and inline/bulk actions.

Controllers should be Wayfinder-generated controllers, not hand-built URL strings. Wayfinder generates typed controller objects from your Laravel routes that provide .url() methods.

import { useDataGrid } from '@settleup/visualizations-react';
import UserDataGrid from '@/actions/App/DataGrids/UserDataGrid';

const grid = useDataGrid({
    controller: UserDataGrid,
});

// grid.schema       — column definitions, actions, floating filters
// grid.rows         — current page of data
// grid.loading      — whether data is being fetched
// grid.filterSets      — active filter sets
// grid.filterSetCount  — number of active filter sets
// grid.filterCount     — total number of active filters
// grid.sorts           — active sorts
// grid.pagination   — { current_page, last_page, total, per_page }
// grid.toggleColumnSort(column)
// grid.resetFilterSets(filterSets)
// grid.setPage(page)
// grid.selectRow(key, selected)
// grid.executeInlineAction(name, key)
// grid.executeBulkAction(name)

useDataGridViews

Manages saved views (named configurations of filters, sorts, and column visibility) for a datagrid.

import { useDataGridViews } from '@settleup/visualizations-react';
import UserDataGrid from '@/actions/App/DataGrids/UserDataGrid';

const views = useDataGridViews({
    controller: UserDataGrid,
});

// views.views       — array of saved DataGridView objects
// views.saveView({ name, filterSets, sorts, columns })
// views.deleteView(viewId)
// views.applyView(view, gridHandlers)
// views.resetView(schema, gridHandlers)

useChartData

Fetches chart schema and data with support for filtering and sorting.

import { useChartData } from '@settleup/visualizations-react';
import RevenueChart from '@/actions/App/Charts/RevenueChart';

const chart = useChartData({
    controller: RevenueChart,
});

// chart.schema              — label, datasets, chart type
// chart.data                — array of data points
// chart.loading             — whether data is being fetched
// chart.filterSets          — active filter sets
// chart.filterSetCount      — number of active filter sets
// chart.filterCount         — total number of active filters
// chart.addFilterSet()
// chart.removeFilterSet(index)
// chart.updateFilterSetOperator(index, operator)
// chart.addFilter(setIndex)
// chart.removeFilter(setIndex, filterIndex)
// chart.updateFilter(setIndex, filterIndex, changes)
// chart.resetFilterSets(filterSets)
// chart.clearFilterSets()
// chart.activeFilterCount   — number of active filters
// chart.sorts               — active sorts
// chart.setSorts(sorts)
// chart.hasFloatingFilters  — whether schema defines floating filters
// chart.showFloatingFilters / chart.setShowFloatingFilters(show)
// chart.refresh()           — re-fetch data

useMetric

Fetches a single scalar aggregate value with support for filtering.

import { useMetric } from '@settleup/visualizations-react';
import RevenueMetric from '@/actions/App/Metrics/RevenueMetric';

const metric = useMetric({
    controller: RevenueMetric,
});

// metric.schema             — value definition (field, header)
// metric.value              — the scalar aggregate value, or null
// metric.loading            — whether data is being fetched
// metric.filterSets         — active filter sets
// metric.filterSetCount     — number of active filter sets
// metric.filterCount        — total number of active filters
// metric.addFilterSet()
// metric.removeFilterSet(index)
// metric.updateFilterSetOperator(index, operator)
// metric.addFilter(setIndex)
// metric.removeFilter(setIndex, filterIndex)
// metric.updateFilter(setIndex, filterIndex, changes)
// metric.resetFilterSets(filterSets)
// metric.clearFilterSets()
// metric.activeFilterCount  — number of active filters
// metric.hasFloatingFilters — whether schema defines floating filters
// metric.showFloatingFilters / metric.setShowFloatingFilters(show)
// metric.refresh()          — re-fetch data

useFilterBuilder

Low-level hook for managing filter set state — adding/removing filters and filter sets, updating operators and values.

import { useFilterBuilder } from '@settleup/visualizations-react';

const builder = useFilterBuilder({
    schema,
    initialFilterSets: [],
});

// builder.filterSets
// builder.filterSetCount  — number of filter sets
// builder.filterCount     — total number of filters across all filter sets
// builder.addFilterSet()
// builder.removeFilterSet(index)
// builder.addFilter(setIndex)
// builder.updateFilter(setIndex, filterIndex, changes)
// builder.removeFilter(setIndex, filterIndex)

useVisualizationData

Base hook used internally by useDataGrid, useChartData, and useMetric. Handles schema fetching, data fetching with filter/sort params, and error state. You can use this directly for custom visualization types.

import { useVisualizationData } from '@settleup/visualizations-react';
import CustomVisualization from '@/actions/App/Visualizations/CustomVisualization';

const viz = useVisualizationData({
    controller: CustomVisualization,
    initialFilterSets: [],
    initialSorts: [],
});

Types

All types are exported from the package root:

Shared

• FilterSet, Filter, FilterSetOperator, FilterOperator — filter definitions and enums
• Sort, SortOperator — sort definitions and enum
• FloatingFilter — quick-access filter definitions
• VisualizationController — base controller shape, satisfied by Wayfinder-generated controllers (handleSchema.url(), handleData.url())
• VisualizationState — base state shape returned by hooks

DataGrids

• DataGridSchema — full schema including columns, actions, floating filters
• DataGridColumn — column definition (field, header, type, sortable, filterable, etc.)
• DataGridAction — inline or bulk action definition
• DataGridFloatingFilter — floating filter definition
• DataGridController — Wayfinder controller shape for datagrids
• DataGridView, DataGridViewColumn — saved view definitions
• PaginationState — { page, lastPage, total }

Charts

• ChartSchema — chart schema (label, datasets, floating filters)
• ChartLabel — label field definition
• ChartDataset — dataset definition (field, header, type: bar/line/area/pie/donut)
• ChartType — enum of chart types (Bar, Line, Area, Pie, Donut)
• ChartController — Wayfinder controller shape for charts

Metrics

• MetricSchema — metric schema (value definition, floating filters)
• MetricValue — value field definition (field, header)
• MetricController — Wayfinder controller shape for metrics

Utilities

• formatCellValue(value, type) — formats a cell value based on column type
• OPERATORS_BY_TYPE / getOperators(type) — available filter operators per column type
• defaultFilter(columns) / defaultFilterSet(columns) — create empty filter/filter set
• extractFloatingValues(filterSets, floatingFilters) / applyFloatingValues(...) — convert between floating filter values and filter sets

Usage with UI Components

This package is designed to be paired with a UI layer. The @settleup/visualizations-shadcn package provides shadcn/ui components that consume these hooks:

npx shadcn add ./packages/visualizations-shadcn/public/r/datagrid.json

Or build your own components using the hooks directly — they're completely headless.

Development

npm test          # run tests
npm run test:watch  # run tests in watch mode