vue-data-view-plus

Vue 3 components to present the same dataset in multiple ways—table, card grid, line chart, and bar chart—using one column definition (ColumnsDef) as the single source of truth for labels, types, formatting, and chart eligibility.

Install

npm install vue-data-view-plus

Peer dependencies

Install these in your app (versions should satisfy the ranges in this package’s peerDependencies):

• vue
• chart.js
• vue-chartjs
• chartjs-adapter-date-fns (used by the line chart for the time axis)
• date-fns (required by chartjs-adapter-date-fns)

Styles

Import the bundled CSS once (e.g. in main.ts or your app shell):

import "vue-data-view-plus/style.css";

If your bundler struggles with the export subpath, use:

import "vue-data-view-plus/dist/style.css";

The stylesheet maps design tokens to CSS variables (--vdv-*, with fallbacks to common --color-* / --space-* names). Override those variables in your app to theme tables and charts.

Core idea

1. items: an array of row objects (TItem extends ColumnObject).
2. columns: a typed array describing every visible column (including a special "actions" column if you need row buttons).
3. Derived behavior: sorting, pagination, cell text, chart axes, and aggregates all read from that same columns metadata plus items—you do not configure charts with a second, parallel schema unless you opt in (e.g. filterDefs for bar-chart categories).

Business logic

This section describes how the library decides what to render and how, not just API names.

Column model

• Each column has a key matching a property on the row (unless you use getValue or the special actions key).
• type drives:
  • Default formatting when no custom formatter is set (tableFormatters).
  • Sort behavior (numbers, dates, currencies, text).
  • Chart eligibility (see below).
• Column header text (table, cards, chart axis pickers) uses resolveColumnDisplayLabel:
  • If labelKey is set, translate(labelKey) is used with the optional translate prop (i18n lookup).
  • Otherwise label is shown as-is (use for literals or already translated text, e.g. Hebrew resolved in the parent).
• actions columns render TableAction buttons; optional icon is resolved via iconResolver (e.g. map a string name to a Vue component).

label vs labelKey

| Field | Behavior | | ----- | -------- | | label | Display string when labelKey is absent. Not passed through translate. | | labelKey | Optional. When set (non-empty), the visible title is translate(labelKey). |

You can export resolveColumnDisplayLabel from the package if you need the same rule outside components.

Table & cards (DataTable, DataColumnar)

1. Sorting

   • Clicking a sortable column header toggles asc/desc on that column key.
   • Sort uses getValue when present, otherwise row[key].
   • Comparison is type-aware (number / currency / date / text).

2. Pagination

   • Operates on the sorted list.
   • Page size changes emit update:pageSize; the parent owns the effective page size if you store it.
   • When disabled or page size is zero, all sorted rows are shown.

3. Cells

   • Optional named slots per column key override rendering for that column.
   • Otherwise TableCell formats from type, format, or formatter.
   • wrapper (text | button | chip | link) chooses the host element; link uses linkComponent (e.g. RouterLink) or a plain <a> with href(row).

4. Footer totals

   • If any column defines total, a footer row runs those functions on the full sorted dataset (not only the current page).

Cards repeat the same row/column semantics in a denser layout; actions appear in a footer strip per card.

DataView (unified toggle)

• Renders table | cards | chart | barChart based on view (v-model via update:view).
• Line chart and bar chart navigation buttons appear only when the respective mode is supported (see helpers below).
• If the requested view becomes invalid (e.g. columns change and charts are no longer possible), the view falls back to table and update:view may emit table to keep parent state consistent.

Line chart (DataChart)

Eligibility (“business rule”): at least one column with type === "date" and one with type === "number" or "currency" (see chartSupported / dataChartSupport).

Behavior:

1. X axis uses a chosen date column; Y uses a numeric/currency column.
2. Raw points are (time, value) pairs; invalid dates or numbers are skipped.
3. Group by (granularity none / day / week / month / year) buckets points in local calendar time (same philosophy as Chart.js time scale defaults). Inside each bucket, Y values are combined with aggregateY—default sumAggregate—so overlapping rows in the same bucket add up (typical for amounts over time).
4. Tooltip titles use formatChartBucketLabel so labels match the granularity.

Peers must include chartjs-adapter-date-fns because the adapter is imported by the component (time scale).

Bar chart (DataBarChart)

Eligibility: at least one categorical X source:

1. type === "boolean" columns, or
2. DataViewSelectFilterDef entries passed in filterDefs (type: "select"), paired by key—optionally joined to a real column via the same key (if the row only holds an id, getValue / dot-path lookups can still resolve a value).

Ordering of X descriptors: boolean columns first, then select-backed keys; duplicate keys dedupe (boolean wins if both exist—unlikely).

Y axis:

• sum / mean need a numeric/currency column.
• count counts rows per category and does not require a numeric column.

Buckets: values are aggregated per category label. Booleans map to yes / no / empty** via **translate**. Select categories use **options()** on the **DataViewSelectFilterDef` for display labels where possible.

See aggregateBarChart, getBarChartXDescriptors, barChartSupported.

Internationalization (translate)

• Components accept optional translate: (key: string) => string (e.g. vue-i18n t).
• Built-in UI strings (toolbar, pagination, yes/no, chart chrome, …) go through the same helper that applies default English when translate is missing, or when a key is unknown.
• Column headers do not call translate(label) anymore. Use label for final text, or set labelKey to pass only that string through translate.

Icons (iconResolver)

• TableAction.icon may be a Vue component or an opaque string (your app maps strings to icons if you supply iconResolver).

Integration props (summary)

| Prop | Role | |------|------| | translate | Localize all built-in keys (table, loading, chart strings, pagination, …). | | iconResolver | Resolve actions[k].icon when icons are strings. | | linkComponent | e.g. RouterLink; default link behavior otherwise. | | filterDefs | Bar chart category sources from select filter definitions (DataViewFilterDef[]). |

Quick usage

<script setup lang="ts">
import { DataView, type ColumnsDef } from "vue-data-view-plus";

interface Row extends Record<string, unknown> {
  id: number;
  name: string;
  amount: number;
  createdAt: string;
}

const items: Row[] = [
  /* ... */
];

const columns = [
  { key: "name", label: "Name", type: "text" },
  { key: "amount", label: "Amount", type: "currency" },
  {
    key: "createdAt",
    label: "Created",
    type: "date",
    format: "datetime",
  },
] as const satisfies ColumnsDef<Row>;
</script>

<template>
  <DataView
    :items="items"
    :columns="columns"
    :translate="(k) => k"
    :show-view-toggle="true"
  />
</template>

Pass translate from vue-i18n, iconResolver, and link-component in real apps.

Exported utilities

Use these when you want the same rules outside the UI (e.g. feature flags or server docs):

| Export | Purpose | |--------|---------| | chartSupported, getDateColumnKeys, getNumericColumnKeys | Line-chart column detection. | | barChartSupported, getBarChartXDescriptors | Bar-chart category detection (+ filterDefs). | | aggregateBarChart | Same aggregation as DataBarChart. | | aggregateTimeSeriesPoints, formatChartBucketLabel, sumAggregate, … | Line-chart bucketing. | | formatCell, getCellValue, getRowId | Table/card formatting and identity. | | resolveColumnDisplayLabel, ColumnLikeForLabel | Same label / labelKey title rules as the UI. | | useTableSort, useTablePagination | Headless sort/pagination. |

Build from source

In this repo’s package folder:

npm run build
npm test

prepublishOnly runs npm run build before npm publish.

License

Set the SPDX identifier in this package’s package.json license field when you publish (for example "MIT").