@dashadmin/dash-reports 1.3.72 → 1.3.74-srcfree.1

package/src/adapters/mui/chartTheme.ts

@@ -1,84 +0,0 @@
-import type { Theme } from '@mui/material';
-
-/**
- * Chart chrome, taken from the app's MUI theme.
- *
- * Grid and axis lines are deliberately recessive — a chart's ink belongs to its
- * data, and heavy or dashed rules read as content. Text uses the theme's own
- * ink tokens, never a series colour: a coloured mark beside a label carries the
- * identity, so colouring the text as well adds nothing and costs contrast.
- */
-export interface ChartChrome {
-  dark: boolean;
-  grid: string;
-  axisText: string;
-  tooltipBg: string;
-  tooltipText: string;
-  surface: string;
-}
-
-export function chartChrome(theme: Theme): ChartChrome {
-  const dark = theme.palette.mode === 'dark';
-
-  return {
-    dark,
-    // ~8% ink: present enough to read a value against, quiet enough to ignore.
-    grid: dark ? 'rgba(255,255,255,0.08)' : 'rgba(0,0,0,0.08)',
-    axisText: theme.palette.text.secondary,
-    tooltipBg: dark ? 'rgba(32,32,30,0.96)' : 'rgba(255,255,255,0.96)',
-    tooltipText: theme.palette.text.primary,
-    surface: theme.palette.background.paper,
-  };
-}
-
-/** Shared scale/plugin options so every widget reads the same. */
-export function baseChartOptions(chrome: ChartChrome, showLegend: boolean) {
-  return {
-    responsive: true,
-    maintainAspectRatio: false,
-    interaction: {
-      // Whole-bucket hover: the hit target is the column, not the mark, so a
-      // thin bar or a small point does not demand pixel-accurate aim.
-      mode: 'index' as const,
-      intersect: false,
-    },
-    plugins: {
-      legend: {
-        display: showLegend,
-        position: 'bottom' as const,
-        labels: {
-          color: chrome.axisText,
-          usePointStyle: true,
-          pointStyle: 'circle' as const,
-          boxWidth: 8,
-          boxHeight: 8,
-          padding: 16,
-        },
-      },
-      tooltip: {
-        backgroundColor: chrome.tooltipBg,
-        titleColor: chrome.tooltipText,
-        bodyColor: chrome.tooltipText,
-        borderColor: chrome.grid,
-        borderWidth: 1,
-        padding: 10,
-        cornerRadius: 6,
-        displayColors: true,
-        usePointStyle: true,
-      },
-    },
-    scales: {
-      x: {
-        grid: { display: false },
-        border: { color: chrome.grid },
-        ticks: { color: chrome.axisText, maxRotation: 0, autoSkipPadding: 12 },
-      },
-      y: {
-        beginAtZero: true,
-        grid: { color: chrome.grid },
-        border: { display: false },
-        ticks: { color: chrome.axisText, precision: 0 as unknown as number },
-      },
-    },
-  };
-}

package/src/adapters/mui/index.ts

@@ -1,29 +0,0 @@
-import { registerVisualization } from '../../core/visualizationRegistry';
-import { BarWidget } from './BarWidget';
-import { LineWidget } from './LineWidget';
-import { DoughnutWidget } from './DoughnutWidget';
-import { PieWidget } from './PieWidget';
-import { KpiWidget } from './KpiWidget';
-import { FunnelWidget } from './FunnelWidget';
-import { SeriesTableWidget } from './TableWidget';
-
-/**
- * Register the MUI/Chart.js renderers.
- *
- * Importing this module is what wires the adapter up; `core/` never imports a
- * chart library, so a different adapter can register its own set against the
- * same registry without this one being loaded.
- */
-registerVisualization('Bar', BarWidget);
-registerVisualization('Line', LineWidget);
-registerVisualization('Doughnut', DoughnutWidget);
-registerVisualization('Pie', PieWidget);
-registerVisualization('Kpi', KpiWidget);
-registerVisualization('Funnel', FunnelWidget);
-registerVisualization('Table', SeriesTableWidget);
-
-export { BarWidget, LineWidget, DoughnutWidget, PieWidget, KpiWidget, FunnelWidget, SeriesTableWidget };
-export { DetailTable } from './TableWidget';
-export { PreviewWidget } from './PreviewWidget';
-export * from './palette';
-export { chartChrome, baseChartOptions } from './chartTheme';

package/src/adapters/mui/palette.ts

@@ -1,85 +0,0 @@
-import type { ReportSpec } from '../../core/types';
-
-/**
- * The categorical series palette.
- *
- * Eight hues, in a fixed order, validated for colour-vision deficiency against
- * both surfaces (worst adjacent CVD ΔE 9.1 light / 8.4 dark on the OKLab×100
- * scale; worst adjacent normal-vision ΔE 19.6 / 19.3). The dark column is the
- * same eight hues re-stepped for a dark surface — not an automatic flip of the
- * light values, which would drop several below the 3:1 contrast floor.
- *
- * Three light-mode hues (aqua, yellow, magenta) sit under 3:1 against the light
- * surface. That is permitted only with "relief": a legend is always rendered
- * for two or more series and every report also offers a Table visualisation,
- * so no value is reachable by colour alone.
- */
-export const SERIES_LIGHT = [
-  '#2a78d6', // blue
-  '#eb6834', // orange
-  '#1baf7a', // aqua
-  '#eda100', // yellow
-  '#e87ba4', // magenta
-  '#008300', // green
-  '#4a3aa7', // violet
-  '#e34948', // red
-] as const;
-
-export const SERIES_DARK = [
-  '#3987e5',
-  '#d95926',
-  '#199e70',
-  '#c98500',
-  '#d55181',
-  '#008300',
-  '#9085e9',
-  '#e66767',
-] as const;
-
-/** Anything past the eighth slot folds into this rather than inventing a hue. */
-export const OTHER_LIGHT = '#8a8a80';
-export const OTHER_DARK = '#6f6f66';
-
-export const MAX_SERIES = SERIES_LIGHT.length;
-
-export function seriesPalette(dark: boolean): readonly string[] {
-  return dark ? SERIES_DARK : SERIES_LIGHT;
-}
-
-/**
- * A stable slot for every series key.
- *
- * Keyed on the ENTITY, never on its position in the current result. Assigning
- * by index would repaint every surviving series the moment a filter removed one
- * above it — the reader sees "delivered" change from aqua to orange and reads it
- * as a different thing. The spec's declared dimension values give a fixed order
- * that survives filtering; metric order does the same when there is no pivot.
- * Keys the spec does not declare (a free-form pivot like product name) fall back
- * to first-seen order, which is at least stable within one result.
- */
-export function buildSlotMap(spec: ReportSpec | null, pivotKey: string | undefined, seriesKeys: string[]): Map<string, number> {
-  const ordered: string[] = [];
-
-  const pivotDimension = pivotKey ? spec?.dimensions?.find((d) => d.key === pivotKey) : undefined;
-
-  if (pivotDimension?.values?.length) {
-    pivotDimension.values.forEach((v) => ordered.push(String(v.value)));
-  } else if (!pivotKey && spec?.metrics?.length) {
-    spec.metrics.forEach((m) => ordered.push(m.key));
-  }
-
-  seriesKeys.forEach((k) => {
-    if (!ordered.includes(k)) ordered.push(k);
-  });
-
-  const map = new Map<string, number>();
-  ordered.forEach((key, index) => map.set(key, index));
-
-  return map;
-}
-
-export function colorForSlot(slot: number, dark: boolean): string {
-  if (slot >= MAX_SERIES) return dark ? OTHER_DARK : OTHER_LIGHT;
-
-  return seriesPalette(dark)[slot];
-}

package/src/adapters/mui/useChartData.ts

@@ -1,62 +0,0 @@
-import { useMemo } from 'react';
-import { useTheme } from '@mui/material';
-import { formatBucket, formatBucketLong } from '../../core/formatBucket';
-import { buildSlotMap, colorForSlot, MAX_SERIES } from './palette';
-import { chartChrome } from './chartTheme';
-import { label as renderLabel } from '../../core/label';
-import type { VisualizationProps } from '../../core/visualizationRegistry';
-
-/**
- * Everything the cartesian widgets share: stable colours, folded overflow,
- * formatted labels and the resolved chrome.
- *
- * Series past the eighth are folded into a single "Other" series rather than
- * given a generated hue — nine-plus categorical colours stop being
- * distinguishable, and a reader cannot hold that many identities at once. The
- * fold is additive, so the total still reconciles with the table.
- */
-export function useChartData({ result, spec, translate }: VisualizationProps) {
-  const theme = useTheme();
-
-  return useMemo(() => {
-    const chrome = chartChrome(theme);
-    const pivotKey = result.meta?.pivot ?? undefined;
-
-    const slots = buildSlotMap(spec, pivotKey ?? undefined, result.series.map((s) => s.key));
-
-    const kept = result.series.filter((s) => (slots.get(s.key) ?? 0) < MAX_SERIES);
-    const overflow = result.series.filter((s) => (slots.get(s.key) ?? 0) >= MAX_SERIES);
-
-    const datasets = kept.map((series) => ({
-      key: series.key,
-      label: renderLabel(translate, series.label, series.labelText),
-      data: series.data,
-      color: colorForSlot(slots.get(series.key) ?? 0, chrome.dark),
-    }));
-
-    if (overflow.length > 0) {
-      // Sum the tail position-wise so the folded series is still a real total.
-      const summed = result.buckets.map((_, index) =>
-        overflow.reduce<number | null>((acc, series) => {
-          const value = series.data[index];
-          if (value === null || value === undefined) return acc;
-          return (acc ?? 0) + value;
-        }, null),
-      );
-
-      datasets.push({
-        key: '__other__',
-        label: translate('dash_reports.other', { _: 'Other', count: overflow.length }),
-        data: summed,
-        color: colorForSlot(MAX_SERIES, chrome.dark),
-      });
-    }
-
-    const labels = result.buckets.map((b) => formatBucket(b, result.granularity, translate));
-    const longLabels = result.buckets.map((b) => formatBucketLong(b, result.granularity, translate));
-
-    return { chrome, datasets, labels, longLabels, foldedCount: overflow.length };
-  }, [result, spec, translate, theme]);
-}
-
-export default useChartData;

package/src/core/formatBucket.ts

@@ -1,73 +0,0 @@
-import type { Granularity, TranslateFn } from './types';
-
-/**
- * Turn a bucket key into an axis label.
- *
- * Series grains arrive as 'YYYY-MM-DD HH:mm:ss' in the REPORTING timezone —
- * already local, already truncated. They are formatted by string slicing rather
- * than by `new Date(...)`, deliberately: parsing them into a Date would apply
- * the browser's timezone to a value the server already converted, shifting
- * every label by the offset between the viewer and the venue. A restaurant in
- * Santiago read from a laptop in Madrid must still show Santiago's days.
- */
-export function formatBucket(
-  bucket: string | number,
-  granularity: Granularity,
-  translate: TranslateFn,
-): string {
-  // A total has exactly one bucket covering the whole window, so it has no
-  // meaningful axis label — the surrounding card already states the period.
-  if (granularity === 'total') {
-    return translate('dash_reports.granularity.total', { _: 'Total' });
-  }
-
-  if (granularity === 'hourOfDay') {
-    return `${String(bucket).padStart(2, '0')}:00`;
-  }
-
-  if (granularity === 'dayOfWeek') {
-    // ISO day: 1 = Monday .. 7 = Sunday.
-    const key = ['monday', 'tuesday', 'wednesday', 'thursday', 'friday', 'saturday', 'sunday'][Number(bucket) - 1];
-    return translate(`dash_reports.weekdays.${key}`, { _: key ?? String(bucket) });
-  }
-
-  const raw = String(bucket);
-  const date = raw.slice(0, 10);          // YYYY-MM-DD
-  const [year, month, day] = date.split('-');
-
-  switch (granularity) {
-    case 'yearly':
-      return year;
-    case 'monthly':
-      return `${month}/${year}`;
-    case 'weekly':
-      return `${day}/${month}`;
-    case 'daily':
-    default:
-      return `${day}/${month}`;
-  }
-}
-
-/** A longer form for tooltips, where there is room to disambiguate. */
-export function formatBucketLong(
-  bucket: string | number,
-  granularity: Granularity,
-  translate: TranslateFn,
-): string {
-  if (granularity === 'total' || granularity === 'hourOfDay' || granularity === 'dayOfWeek') {
-    return formatBucket(bucket, granularity, translate);
-  }
-
-  const raw = String(bucket);
-  const [year, month, day] = raw.slice(0, 10).split('-');
-
-  if (granularity === 'yearly') return year;
-  if (granularity === 'monthly') return `${month}/${year}`;
-  if (granularity === 'weekly') {
-    return translate('dash_reports.week_of', { _: `Week of ${day}/${month}/${year}`, date: `${day}/${month}/${year}` });
-  }
-
-  return `${day}/${month}/${year}`;
-}
-
-export default formatBucket;

package/src/core/label.ts

@@ -1,28 +0,0 @@
-import type { TranslateFn } from './types';
-
-/**
- * Render a backend label.
- *
- * The API sends a translation KEY plus the text the backend resolved for it.
- * This prefers the app's own translation of the key and falls back to the
- * backend's text — polyglot's `_` option does exactly that, returning the
- * default whenever the key is missing.
- *
- * Why both: sending only the key means every app must redeclare every report's
- * vocabulary, and a newly registered report renders as `reports.x.title` until
- * someone ships a frontend change. Sending only text would take the override
- * away and make responses locale-bound. This way a new report is readable with
- * no frontend change, and an app that wants different wording still wins by
- * defining the key.
- */
-export function label(
-  translate: TranslateFn,
-  key: string | undefined,
-  text?: string,
-): string {
-  if (!key) return text ?? '';
-
-  return translate(key, { _: text ?? key });
-}
-
-export default label;

package/src/core/queryParams.ts

@@ -1,27 +0,0 @@
-import type { ReportFilterState } from './types';
-
-/**
- * Flatten filter state into the query the backend expects.
- *
- * Dimension selections are sent under their own key (`?status[]=CREATED`),
- * which is what ReportQuery::resolveFilters reads. Empty selections are
- * omitted entirely rather than sent as an empty array — an empty `whereIn`
- * matches nothing, so sending one would turn "no filter" into "no rows".
- */
-export function toQueryParams(filters: ReportFilterState): Record<string, unknown> {
-  const params: Record<string, unknown> = {
-    start: filters.start,
-    end: filters.end,
-    granularity: filters.granularity,
-  };
-
-  if (filters.pivot) params.pivot = filters.pivot;
-
-  Object.entries(filters.dimensions ?? {}).forEach(([key, values]) => {
-    if (Array.isArray(values) && values.length > 0) params[key] = values;
-  });
-
-  return params;
-}
-
-export default toQueryParams;

package/src/core/types.ts

@@ -1,157 +0,0 @@
-/**
- * The wire contract with app/ReportCore.
- *
- * A ReportSpec is the single description the backend serves for a report, and
- * everything this package renders — filters, chart shells, export controls —
- * is derived from it. Nothing here is KitchnTabs-specific: a domain adds a
- * report by registering a definition server-side, and this package renders it
- * without a frontend change.
- *
- * Deliberately NOT called a "manifest": `ResourceManifest` already means a lazy
- * resource-module map in dash-app-common and dash-admin, and reusing the word
- * for a second, unrelated concept would be a genuine ambiguity in a codebase
- * that already has both.
- *
- * Every `label` is a translation KEY, never display text. The previous
- * generation of this feature returned Spanish strings from PHP, which is what
- * made it unusable for a second domain.
- */
-
-export type Granularity =
-  /** One bucket for the whole window — a period total, not a timeline. */
-  | 'total'
-  | 'daily'
-  | 'weekly'
-  | 'monthly'
-  | 'yearly'
-  | 'hourOfDay'
-  | 'dayOfWeek';
-
-export type VisualizationType =
-  | 'Bar'
-  | 'Line'
-  | 'Pie'
-  | 'Doughnut'
-  | 'Kpi'
-  | 'Funnel'
-  | 'Table';
-
-export interface DimensionValue {
-  value: string | number | boolean;
-  /** Translation key. */
-  label: string;
-  /** Backend-resolved text, used when the app has no translation for `label`. */
-  labelText?: string;
-  icon?: string;
-}
-
-export interface ReportDimension {
-  key: string;
-  label: string;
-  labelText?: string;
-  type: 'column' | 'jsonpath' | 'relation';
-  multiple?: boolean;
-  source?: string;
-  visibleTo?: string[];
-  values?: DimensionValue[];
-}
-
-export interface ReportMetric {
-  key: string;
-  label: string;
-  labelText?: string;
-  kind: 'count' | 'countNotNull' | 'countDistinct' | 'sum' | 'avg' | 'min' | 'max';
-  /** Render as money/decimal rather than an integer. */
-  decimal: boolean;
-  /** 'minutes' for a duration metric; the UI appends the unit. */
-  unit?: string | null;
-}
-
-export interface ReportVisualization {
-  type: VisualizationType;
-  options?: Record<string, unknown>;
-}
-
-export interface ReportSpec {
-  key: string;
-  title: string;
-  titleText?: string;
-  granularities: Granularity[];
-  defaultGranularity: Granularity;
-  timezone: string;
-  dimensions: ReportDimension[];
-  metrics: ReportMetric[];
-  visualizations: ReportVisualization[];
-  /** How this report is best read; the tab that opens first. */
-  defaultVisualization: VisualizationType;
-  previewGranularity: Granularity;
-  filters: Record<string, { type: string }>;
-  exporters: string[];
-  defaultRangeDays: number;
-}
-
-export interface ReportSeries {
-  key: string;
-  /** Translation key (or literal text for a value like a tenant name). */
-  label: string;
-  /** Backend-resolved text; used when the app has no translation for `label`. */
-  labelText?: string;
-  metric: string;
-  /** Exactly one point per bucket; null means "no data", 0 means "none". */
-  data: Array<number | null>;
-}
-
-export interface ReportResult {
-  key: string;
-  granularity: Granularity;
-  timezone: string;
-  /** Timestamps for series grains, small ints for cyclic ones. */
-  buckets: Array<string | number>;
-  series: ReportSeries[];
-  totals: Record<string, number | null>;
-  meta?: {
-    start?: string;
-    end?: string;
-    pivot?: string | null;
-    scopedTenantIds?: string[] | null;
-  };
-}
-
-export interface ReportTablePage {
-  data: Array<Record<string, unknown>>;
-  total: number;
-  page: number;
-  perPage: number;
-  lastPage: number;
-}
-
-export interface ReportListEntry {
-  key: string;
-  title: string;
-  titleText?: string;
-  metrics?: ReportMetric[];
-  visualizations: ReportVisualization[];
-  /** How this report is best read — drives the list preview and the first tab. */
-  defaultVisualization: VisualizationType;
-  /** Coarser grain for the preview: a card is too small for a daily series. */
-  previewGranularity: Granularity;
-  defaultRangeDays: number;
-}
-
-/** The user-driven part of a report request. */
-export interface ReportFilterState {
-  start: string;
-  end: string;
-  granularity: Granularity;
-  pivot?: string;
-  /** Dimension key -> selected values. */
-  dimensions: Record<string, Array<string | number | boolean>>;
-}
-
-/**
- * Injected rather than imported from react-admin, so this package stays usable
- * in a public/light app that has no react-admin i18n provider at all. The `_`
- * option is polyglot's default-value convention, so a missing key renders
- * sensible text instead of the raw key.
- */
-export type TranslateFn = (key: string, options?: Record<string, unknown>) => string;