feat: implement comprehensive logistics and seafarer analytics reporting modules with dashboard visualizations and CSV export functionality.

libs/ui/src/index.ts

@@ -31,6 +31,7 @@ export * from "./lib/input/phone";
 export * from "./lib/data/AdvancedTable";
 export * from "./lib/data/WaitingFor";
 export * from "./lib/data/StatTile";
+export * from "./lib/data/report-format";
 export * from "./lib/feedback/use-error-handler";
 export * from "./lib/data/useServerTable";
 export * from "./lib/landing/LandingPage";

libs/ui/src/lib/data/AdvancedTable.tsx

@@ -53,6 +53,16 @@ interface AdvancedTableProps<T> {
   onRowClick?: (row: T) => void;
   /** Card title, top-left. Defaults to `tableName`, which every caller already passes. */
   title?: ReactNode;
+  /**
+   * Width below which the grid scrolls horizontally instead of compressing.
+   *
+   * The 480 default suits the three- and four-column grids most screens show.
+   * A wider table needs a wider floor: squeezed past it, Mantine ellipsises
+   * badge content, so a status column collapses to "SU…" — unreadable, and
+   * unlike a scrollbar it gives no hint that anything was hidden. Pass the
+   * table's real minimum when it carries more than about five columns.
+   */
+  minWidth?: number;
   /** Search box, filters, export — rendered top-right before Refresh/View. */
   toolbar?: ReactNode;
 }
@@ -88,6 +98,7 @@ export function AdvancedTable<T extends { id?: string | number }>({
   onRowClick,
   title,
   toolbar,
+  minWidth = 480,
 }: AdvancedTableProps<T>) {
   const { t } = useTranslation();
   const [visible, setVisible] = useState<boolean[]>(
@@ -176,7 +187,7 @@ export function AdvancedTable<T extends { id?: string | number }>({
         </Group>
       </Group>
 
-      <Table.ScrollContainer minWidth={480}>
+      <Table.ScrollContainer minWidth={minWidth}>
         <Table verticalSpacing={verticalSpacing}>
           <Table.Thead>
             <Table.Tr>

libs/ui/src/lib/data/report-format.ts

@@ -0,0 +1,285 @@
+/**
+ * Presentation rules shared by the authority's dashboards (the vessel
+ * register report and the seafarer services report).
+ *
+ * Kept here rather than in either feature folder because the two screens are
+ * meant to read as one product: the same em dash for "no answer", the same
+ * palette assigned in the same order, the same muted treatment for the
+ * bookkeeping slices. Two copies would drift the first time one of them gained
+ * a colour.
+ *
+ * Nothing in this file knows what a vessel or a seafarer is — the
+ * domain-specific labels stay in each feature's own `report-format.ts`, which
+ * re-exports this module so a component has one import.
+ */
+
+import { ethMonthName, toEthDateTime } from '@ema-platform/shared';
+
+/** One slice of a breakdown chart, as every report's API returns it. */
+export interface ReportBreakdownItem {
+  key: string;
+  label: string;
+  count: number;
+  percentage: number;
+}
+
+/** Nothing measurable is not zero — an em dash says so without lying. */
+export const DASH = '—';
+
+/**
+ * A figure the API may legitimately have no answer for.
+ *
+ * An average is null on an empty register and a rate is null until something
+ * has been decided; rendering either as 0 would report a fleet that weighs
+ * nothing and a service that approves nobody.
+ */
+export function formatNumber(
+  value: number | null | undefined,
+  options: { decimals?: number; suffix?: string } = {},
+): string {
+  if (value === null || value === undefined || Number.isNaN(value)) return DASH;
+  const text = value.toLocaleString(undefined, {
+    minimumFractionDigits: options.decimals ?? 0,
+    maximumFractionDigits: options.decimals ?? 0,
+  });
+  return options.suffix ? `${text}${options.suffix}` : text;
+}
+
+export function formatPercent(value: number | null | undefined): string {
+  return value === null || value === undefined
+    ? DASH
+    : `${formatNumber(value, { decimals: 1 })}%`;
+}
+
+export function formatMoney(value: number, currency: string): string {
+  return `${formatNumber(value, { decimals: 2 })} ${currency}`;
+}
+
+/** A signed delta for the change-vs-previous chip. */
+export function formatDelta(value: number | null): string {
+  if (value === null) return DASH;
+  const sign = value > 0 ? '+' : '';
+  return `${sign}${formatNumber(value, { decimals: 1 })}%`;
+}
+
+export function deltaColor(value: number | null): string {
+  if (value === null || value === 0) return 'gray';
+  return value > 0 ? 'teal' : 'red';
+}
+
+/**
+ * Days as a readable duration.
+ *
+ * Sea time and processing times are both days on the wire, but "487 d" is not
+ * a figure anyone reads as "a year and four months", which is the unit
+ * certificate eligibility is argued in.
+ */
+export function formatDays(value: number | null | undefined): string {
+  if (value === null || value === undefined || Number.isNaN(value)) return DASH;
+  if (value < 31) return `${formatNumber(value)} d`;
+  if (value < 365) return `${formatNumber(value / 30.44, { decimals: 1 })} mo`;
+  return `${formatNumber(value / 365.25, { decimals: 1 })} yr`;
+}
+
+/** Cumulative expiry counts, as the disjoint bands a chart can stack. */
+export interface CumulativeExpiry {
+  expiringIn30: number;
+  expiringIn60: number;
+  expiringIn90: number;
+}
+
+/**
+ * An API's expiry counts are cumulative — a certificate due in eleven days is
+ * inside the 30-, 60- and 90-day figures, which is how a renewals desk reads
+ * them. Stacked side by side in a chart that reads as three separate groups,
+ * so they are differenced into disjoint bands first.
+ */
+export function expiryBands(
+  counts: CumulativeExpiry,
+): Array<{ label: string; count: number }> {
+  const { expiringIn30, expiringIn60, expiringIn90 } = counts;
+  return [
+    { label: 'Within 30 days', count: expiringIn30 },
+    // Math.max guards against a server that ever answers non-monotonically —
+    // a negative bar is worse than a zero one.
+    { label: '31–60 days', count: Math.max(0, expiringIn60 - expiringIn30) },
+    { label: '61–90 days', count: Math.max(0, expiringIn90 - expiringIn60) },
+  ];
+}
+
+/** Red inside a week, orange inside a month, otherwise unremarkable. */
+export function expiryUrgency(daysToExpiry: number): string {
+  if (daysToExpiry <= 7) return 'red';
+  if (daysToExpiry <= 30) return 'orange';
+  return 'gray';
+}
+
+/**
+ * Officer ids are IAM uuids, which make useless axis labels. Until the
+ * dashboards have a name lookup, shorten them and keep "UNASSIGNED" readable.
+ */
+export function officerLabel(key: string): string {
+  if (key === 'UNASSIGNED') return 'Unassigned';
+  return key.length > 8 ? `${key.slice(0, 8)}…` : key;
+}
+
+/**
+ * Chart colours, assigned by position so a slice keeps its colour between
+ * renders. Mantine's palette rather than invented hex codes, so the charts
+ * follow the theme the rest of the app is built on.
+ */
+const PALETTE = [
+  'var(--mantine-color-blue-6)',
+  'var(--mantine-color-teal-6)',
+  'var(--mantine-color-orange-6)',
+  'var(--mantine-color-grape-6)',
+  'var(--mantine-color-cyan-6)',
+  'var(--mantine-color-lime-7)',
+  'var(--mantine-color-pink-6)',
+  'var(--mantine-color-indigo-6)',
+];
+
+const MUTED = 'var(--mantine-color-gray-5)';
+
+/**
+ * "Unknown" and "Other" are bookkeeping slices rather than findings, so they
+ * always take the muted colour instead of competing with the real categories
+ * for one of the bright ones.
+ */
+export function sliceColor(item: ReportBreakdownItem, index: number): string {
+  if (item.key === 'OTHER' || item.key === 'Unknown') return MUTED;
+  return PALETTE[index % PALETTE.length];
+}
+
+/**
+ * Bucket keys are ISO dates; the axis wants something a human reads.
+ *
+ * Under Amharic the tick is the Ethiopian month (and day), the way every other
+ * date in the app already renders through `dateDisplayer` — a chart whose axis
+ * says "Sep 2026" beside a table that says "መስከረም 2019" is two calendars on one
+ * screen. Bucket keys are UTC midnights, so the day is embedded at UTC noon
+ * first: `toEthDateTime` reads local Y/M/D, and in a positive-offset timezone
+ * a UTC midnight is still the previous local day.
+ */
+export function formatBucket(
+  bucket: string,
+  granularity: 'DAY' | 'WEEK' | 'MONTH',
+  language = 'en',
+): string {
+  const date = new Date(bucket);
+  if (Number.isNaN(date.getTime())) return bucket;
+  if (language.startsWith('am')) {
+    const local = new Date(
+      date.getUTCFullYear(),
+      date.getUTCMonth(),
+      date.getUTCDate(),
+      12,
+    );
+    const eth = toEthDateTime(local);
+    const month = ethMonthName(local);
+    return granularity === 'MONTH'
+      ? `${month} ${eth.year}`
+      : `${month} ${eth.date}`;
+  }
+  if (granularity === 'MONTH') {
+    return date.toLocaleDateString(undefined, {
+      month: 'short',
+      year: 'numeric',
+      timeZone: 'UTC',
+    });
+  }
+  return date.toLocaleDateString(undefined, {
+    day: 'numeric',
+    month: 'short',
+    timeZone: 'UTC',
+  });
+}
+
+/** The default window the APIs apply when none is given: the last 12 months. */
+export function defaultRange(now: Date): [Date, Date] {
+  const from = new Date(
+    Date.UTC(now.getUTCFullYear() - 1, now.getUTCMonth(), now.getUTCDate()),
+  );
+  return [from, now];
+}
+
+export const ISO_DAY_LENGTH = 10;
+
+export const toIsoDay = (date: Date): string =>
+  date.toISOString().slice(0, ISO_DAY_LENGTH);
+
+/**
+ * The filter state as URL search params, so a filtered dashboard is a
+ * shareable link rather than something the next person has to rebuild.
+ *
+ * Empty arrays and blank strings are dropped rather than serialised, which
+ * keeps an untouched dashboard's URL clean and lets the API apply its own
+ * defaults instead of being handed an empty filter to honour.
+ */
+export function queryToSearchParams(query: object): URLSearchParams {
+  const params = new URLSearchParams();
+  for (const [key, value] of Object.entries(query)) {
+    if (value === undefined || value === null || value === '') continue;
+    if (Array.isArray(value)) {
+      if (value.length === 0) continue;
+      params.set(key, value.join(','));
+    } else {
+      params.set(key, String(value));
+    }
+  }
+  return params;
+}
+
+/**
+ * The inverse, for restoring state from a shared link.
+ *
+ * The key lists are the caller's, because they are the report's filter
+ * contract: a key this report does not understand is dropped rather than
+ * forwarded to fail the API's validation pipe.
+ */
+export function searchParamsToQuery<T>(
+  params: URLSearchParams,
+  keys: {
+    arrays: readonly string[];
+    numbers: readonly string[];
+    strings: readonly string[];
+  },
+): T {
+  const query: Record<string, unknown> = {};
+  for (const key of keys.arrays) {
+    const raw = params.get(key);
+    if (raw) query[key] = raw.split(',').filter(Boolean);
+  }
+  for (const key of keys.numbers) {
+    const raw = params.get(key);
+    // An unparseable number in a hand-edited URL is ignored rather than sent
+    // on to fail the API's validation pipe.
+    if (raw !== null && raw !== '' && Number.isFinite(Number(raw))) {
+      query[key] = Number(raw);
+    }
+  }
+  for (const key of keys.strings) {
+    const raw = params.get(key);
+    if (raw) query[key] = raw;
+  }
+  const granularity = params.get('granularity');
+  if (granularity === 'DAY' || granularity === 'WEEK' || granularity === 'MONTH') {
+    query.granularity = granularity;
+  }
+  return query as T;
+}
+
+/**
+ * The multi-select options a filter offers, taken from the breakdown the last
+ * response carried — there is no lookup endpoint for flag states, ports or
+ * nationalities, and the register is the only place that knows which ones are
+ * in use.
+ *
+ * "Unknown" is dropped: it stands for a missing value, and there is nothing to
+ * filter the register down to.
+ */
+export function optionsFrom(items: ReportBreakdownItem[] | undefined): string[] {
+  return (items ?? [])
+    .filter((item) => item.key !== 'Unknown' && item.key !== 'OTHER')
+    .map((item) => item.key);
+}