@antelopejs/dms 0.5.6 → 0.6.0

package/frontend-vue/layers/dms-ui/app/build/composables/table-view/utils/formTexts.ts

@@ -0,0 +1,127 @@
+/** The forms a table view opens: add (`new`), edit and details (`view`). */
+export type TableViewFormKind = "new" | "edit" | "view";
+
+/** Heading texts of one form (a backend `formContainer.pages` entry). */
+export interface TableViewFormText {
+  displayName?: string;
+  description?: string;
+}
+
+/** The backend `formContainer.pages`: the texts of each form. */
+export interface TableViewFormPages {
+  new?: TableViewFormText;
+  edit?: TableViewFormText;
+  details?: TableViewFormText;
+}
+
+/** The `formContainer.pages` key of each form kind. */
+const FORM_PAGE_KEYS: Record<TableViewFormKind, keyof TableViewFormPages> = {
+  new: "new",
+  edit: "edit",
+  view: "details",
+};
+
+/** Separates the form title from the label of the row it is about. */
+export const RECORD_LABEL_SEPARATOR = " · ";
+
+interface FallbackKeys {
+  title: string;
+  description: string;
+  /** The description naming the table's caption (`{caption}`). */
+  captionDescription: string;
+}
+
+const FALLBACK_KEYS: Record<TableViewFormKind, FallbackKeys> = {
+  new: {
+    title: "dms.table.new_item",
+    description: "dms.table.new_item_description",
+    captionDescription: "dms.table.new_item_in",
+  },
+  edit: {
+    title: "dms.table.edit_item",
+    description: "dms.table.edit_item_description",
+    captionDescription: "dms.table.edit_item_in",
+  },
+  view: {
+    title: "dms.table.view_item",
+    description: "dms.table.view_item_description",
+    captionDescription: "dms.table.view_item_in",
+  },
+};
+
+export interface FormContainerTextSource {
+  kind: TableViewFormKind;
+  /** The table view's `formContainer.pages`. */
+  pages?: TableViewFormPages;
+  /** The table's caption, `$`-prefixed when an i18n key. */
+  caption?: string;
+  /** The row's label (its `labelKey` value), for the edit and details forms. */
+  recordLabel?: unknown;
+  /** The reader's locale, to read a localized label in. */
+  locale?: string;
+}
+
+export interface FormContainerTexts {
+  title: string;
+  description: string;
+}
+
+/**
+ * Title and description of the drawer or modal a table view opens a form in:
+ * the table's `formContainer.pages` entry, else "New entry" / "Edit entry" /
+ * "Entry details" with a description naming the caption. The row's label
+ * follows the title ("Edit task · Write the docs").
+ */
+export function resolveFormContainerTexts(
+  source: FormContainerTextSource,
+  resolve: (text: string) => string,
+  t: (key: string, params?: Record<string, unknown>) => string,
+): FormContainerTexts {
+  const keys = FALLBACK_KEYS[source.kind];
+  const texts = source.pages?.[FORM_PAGE_KEYS[source.kind]];
+  const caption = source.caption ? resolve(source.caption) : "";
+
+  const title = texts?.displayName ? resolve(texts.displayName) : t(keys.title);
+  const label = formatRecordLabel(source.recordLabel, source.locale);
+  let description: string;
+  if (texts?.description) {
+    description = resolve(texts.description);
+  } else if (caption) {
+    description = t(keys.captionDescription, { caption });
+  } else {
+    description = t(keys.description);
+  }
+
+  return {
+    title: label ? `${title}${RECORD_LABEL_SEPARATOR}${label}` : title,
+    description,
+  };
+}
+
+/**
+ * A row label worth showing: a non-empty string or number. A localized value
+ * (`{ en: "Task 1", fr: "Tâche 1" }`, as a form loads it) gives its text in
+ * `locale`, its language, or else its first text.
+ */
+export function formatRecordLabel(
+  value: unknown,
+  locale?: string,
+): string | undefined {
+  if (typeof value === "number") return String(value);
+  if (typeof value === "string") return value.trim() || undefined;
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return undefined;
+  }
+  const texts = value as Record<string, unknown>;
+  const candidates = [
+    locale ? texts[locale] : undefined,
+    locale ? texts[locale.split("-")[0]!] : undefined,
+    ...Object.values(texts),
+  ];
+  for (const candidate of candidates) {
+    if (typeof candidate !== "string") continue;
+    const label = candidate.trim();
+    if (label) return label;
+  }
+  return undefined;
+}

package/frontend-vue/layers/dms-ui/app/build/composables/table-view/utils/groupedRows.ts

@@ -0,0 +1,180 @@
+import type { SortingState } from "@tanstack/vue-table";
+import {
+  regionalDateTimeFormat,
+  regionalDayKey,
+  regionalDayNumber,
+  regionalWeekStart,
+} from "#dms-core/app/utils/regional";
+import { nameCalendarDay } from "../../../components/activity-feed/activityFeedDays";
+import { isEligibleKanbanColumn } from "../../../../composables/table-view/kanban";
+import type {
+  TableViewColumn,
+  TableViewGroupBy,
+  TableViewGroupedConfig,
+} from "../../../../composables/table-view/types";
+import type { TableFilter } from "../../../components/table/Table.vue";
+import { sortValueKind } from "./sortableColumns";
+
+/** Key of the group of rows without a value. */
+export const NO_GROUP_KEY = "";
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+const DAYS_PER_WEEK = 7;
+// 1970-01-01, day 0, was a Thursday.
+const EPOCH_WEEKDAY = 4;
+const DAY_KEY_LENGTH = 10;
+
+const toDate = (value: unknown): Date | undefined => {
+  if (value === null || value === undefined || value === "") return undefined;
+  const date = new Date(value as string | number | Date);
+  return Number.isNaN(date.getTime()) ? undefined : date;
+};
+
+const dayKeyOfNumber = (dayNumber: number): string =>
+  new Date(dayNumber * DAY_MS).toISOString().slice(0, DAY_KEY_LENGTH);
+
+/** The first day of the week `dayNumber` falls in, as a day number. */
+function weekStartDay(dayNumber: number, weekStart: number): number {
+  const weekday = (dayNumber + EPOCH_WEEKDAY) % DAYS_PER_WEEK;
+  return dayNumber - ((weekday - weekStart + DAYS_PER_WEEK) % DAYS_PER_WEEK);
+}
+
+function valueKey(value: unknown): string {
+  if (value === null || value === undefined) return NO_GROUP_KEY;
+  if (Array.isArray(value)) return value.map(valueKey).join(",");
+  if (typeof value === "object") {
+    const id = (value as Record<string, unknown>)._id;
+    return id === undefined ? JSON.stringify(value) : String(id);
+  }
+  return String(value);
+}
+
+type GroupKeyReader = (value: unknown, locale: string) => string;
+
+const GROUP_KEY_READERS: Record<TableViewGroupBy, GroupKeyReader> = {
+  value: (value) => valueKey(value),
+  day: (value) => {
+    const date = toDate(value);
+    return date ? regionalDayKey(date) : NO_GROUP_KEY;
+  },
+  week: (value, locale) => {
+    const date = toDate(value);
+    if (!date) return NO_GROUP_KEY;
+    const start = weekStartDay(
+      regionalDayNumber(date),
+      regionalWeekStart(locale),
+    );
+    return dayKeyOfNumber(start);
+  },
+};
+
+/**
+ * The group a row's value files it under: the value itself (a relation by
+ * its id), or the calendar day or week (`YYYY-MM-DD` of its first day) a date
+ * falls on in the reader's time zone.
+ */
+export function rowGroupKey(
+  value: unknown,
+  by: TableViewGroupBy,
+  locale: string,
+): string {
+  return GROUP_KEY_READERS[by](value, locale);
+}
+
+/** Texts a date group heading reads. */
+export interface DateGroupLabels {
+  today: string;
+  yesterday: string;
+  /** "Week of {date}". */
+  weekOf: (date: string) => string;
+}
+
+const keyDate = (key: string): Date => new Date(`${key}T12:00:00Z`);
+
+/** Heading of a day or week group: "Today · Sep 29", "Week of Sep 22". */
+export function dateGroupLabel(
+  key: string,
+  by: Exclude<TableViewGroupBy, "value">,
+  locale: string,
+  labels: DateGroupLabels,
+  now: Date = new Date(),
+): string {
+  const date = keyDate(key);
+  if (by === "week") {
+    return labels.weekOf(
+      regionalDateTimeFormat(locale, { month: "short", day: "numeric" }).format(
+        date,
+      ),
+    );
+  }
+  const day = nameCalendarDay(date, now, locale, labels);
+  return day.date ? `${day.name} · ${day.date}` : (day.name ?? key);
+}
+
+/**
+ * The filter that lists a group's rows, for its count: the value itself, or
+ * the group's days. Days are compared on calendar dates, as the date filter
+ * does.
+ */
+export function groupFilter(
+  accessorKey: string,
+  key: string,
+  by: TableViewGroupBy,
+): TableFilter | undefined {
+  if (key === NO_GROUP_KEY) return undefined;
+  if (by === "value") return { accessorKey, mode: "is", value: key };
+  const firstDay = Date.parse(`${key}T00:00:00Z`) / DAY_MS;
+  const lastDay = by === "week" ? firstDay + DAYS_PER_WEEK - 1 : firstDay;
+  return {
+    accessorKey,
+    mode: "is_between",
+    value: `${key},${dayKeyOfNumber(lastDay)}`,
+  };
+}
+
+/**
+ * The sort the grouped display lists by, so a group's rows follow each other:
+ * on its column, in the direction the user picked on it, else the newest
+ * dates or the first values first.
+ */
+export function groupedSorting(
+  sorting: SortingState,
+  grouped: TableViewGroupedConfig,
+): SortingState {
+  const { groupByField, by = "value" } = grouped;
+  const own = sorting.find((entry) => entry.id === groupByField);
+  return [{ id: groupByField, desc: own ? !!own.desc : by !== "value" }];
+}
+
+/** How a date column picked in the options menu is cut, unless configured. */
+const DEFAULT_DATE_GROUP_BY: TableViewGroupBy = "day";
+
+const isDateColumn = (column: TableViewColumn): boolean =>
+  sortValueKind(column.type.id) === "date";
+
+/**
+ * A column the user may group the rows by from the options menu: one holding
+ * a few known values, as a kanban board's columns do, or a date.
+ */
+export const isGroupableColumn = (column: TableViewColumn): boolean =>
+  isEligibleKanbanColumn(column) || isDateColumn(column);
+
+/**
+ * The grouped options once the user picked `field`: the configured ones on
+ * the configured column; on another date, the configured day or week cut
+ * (by day when the configured column groups by value); else by value.
+ */
+export function groupedOptionsFor(
+  grouped: TableViewGroupedConfig,
+  field: string,
+  columns: TableViewColumn[],
+): TableViewGroupedConfig {
+  if (field === grouped.groupByField) return grouped;
+  const column = columns.find((candidate) => candidate.accessorKey === field);
+  if (!column || !isDateColumn(column)) {
+    return { ...grouped, groupByField: field, by: "value" };
+  }
+  const by =
+    grouped.by && grouped.by !== "value" ? grouped.by : DEFAULT_DATE_GROUP_BY;
+  return { ...grouped, groupByField: field, by };
+}

package/frontend-vue/layers/dms-ui/app/build/composables/table-view/utils/quickFilters.ts

@@ -0,0 +1,178 @@
+import type { TableViewColumn } from "../../../../composables/table-view/types/column";
+import type { TableViewQuickFilterMode } from "../../../../composables/table-view/types/config";
+import type { TableFilter } from "../../../components/table/Table.vue";
+
+/** A value a quick filter offers. */
+export interface QuickFilterItem {
+  label: string;
+  value: string;
+}
+
+/** A quick filter ready for the toolbar. */
+export interface ResolvedQuickFilter {
+  field: string;
+  label: string;
+  icon: string;
+  allLabel: string;
+  mode: TableViewQuickFilterMode;
+  items: QuickFilterItem[];
+  /** Its values are still loading: the button holds its place, disabled. */
+  pending?: boolean;
+}
+
+/** Where a relation quick filter reads its values from. */
+export interface QuickFilterRelationSource {
+  url: string;
+  labelKey: string;
+  valueKey: string;
+}
+
+interface ColumnInputOptions {
+  items?: Array<{ value: unknown; label: string }>;
+  multiple?: boolean;
+  searchUrl?: string;
+  keyMapping?: { label?: string; value?: string };
+}
+
+const DEFAULT_LABEL_KEY = "name";
+const DEFAULT_VALUE_KEY = "_id";
+const ARRAY_MODE: TableViewQuickFilterMode = "array_contains_string";
+const SCALAR_MODE: TableViewQuickFilterMode = "is";
+
+const inputOptions = (column: TableViewColumn | undefined) =>
+  (column?.type?.inputComponent?.options ?? {}) as ColumnInputOptions;
+
+/**
+ * The compare mode a quick filter applies: the declared one, else "contains"
+ * for a multiple select or relation (the row holds a list) and equality
+ * otherwise.
+ */
+export function quickFilterMode(
+  column: TableViewColumn | undefined,
+  declared?: TableViewQuickFilterMode,
+): TableViewQuickFilterMode {
+  if (declared) return declared;
+  return inputOptions(column).multiple ? ARRAY_MODE : SCALAR_MODE;
+}
+
+/**
+ * The values a select or boolean column offers, known from its declaration;
+ * `undefined` for a column whose values must be fetched (a relation).
+ */
+export function staticQuickFilterItems(
+  column: TableViewColumn | undefined,
+  translate: (key: string) => string,
+): QuickFilterItem[] | undefined {
+  if (!column) return [];
+  const typeId = column.type?.id;
+  if (typeId === "boolean" || typeId === "status") {
+    return [
+      { value: "true", label: translate("$dms.table.filter.boolean.checked") },
+      {
+        value: "false",
+        label: translate("$dms.table.filter.boolean.unchecked"),
+      },
+    ];
+  }
+  const items = inputOptions(column).items;
+  if (items) {
+    return items.map((item) => ({
+      value: String(item.value),
+      label: translate(item.label),
+    }));
+  }
+  return relationQuickFilterSource(column) ? undefined : [];
+}
+
+/** The `select` endpoint a relation column picks its rows from. */
+export function relationQuickFilterSource(
+  column: TableViewColumn | undefined,
+): QuickFilterRelationSource | undefined {
+  const options = inputOptions(column);
+  if (!options.searchUrl) return undefined;
+  return {
+    url: options.searchUrl,
+    labelKey: options.keyMapping?.label ?? DEFAULT_LABEL_KEY,
+    valueKey: options.keyMapping?.value ?? DEFAULT_VALUE_KEY,
+  };
+}
+
+/** Rows of a relation's `select` endpoint as quick filter values. */
+export function relationQuickFilterItems(
+  rows: Array<Record<string, unknown>>,
+  source: QuickFilterRelationSource,
+): QuickFilterItem[] {
+  return rows.flatMap((row) => {
+    const value = row[source.valueKey];
+    if (value === undefined || value === null) return [];
+    return [
+      {
+        value: String(value),
+        label: String(row[source.labelKey] ?? value),
+      },
+    ];
+  });
+}
+
+/** The column filter a quick filter reads and writes. */
+const isQuickFilterOf =
+  (quickFilter: Pick<ResolvedQuickFilter, "field" | "mode">) =>
+  (filter: TableFilter): boolean =>
+    filter.accessorKey === quickFilter.field && filter.mode === quickFilter.mode;
+
+/**
+ * The value a quick filter shows as picked: the one its column's filter holds
+ * in the table's filter state, whichever control set it.
+ */
+export function quickFilterValue(
+  filters: TableFilter[],
+  quickFilter: Pick<ResolvedQuickFilter, "field" | "mode">,
+): string | undefined {
+  const value = filters.find(isQuickFilterOf(quickFilter))?.value;
+  return value === undefined || value === null || value === ""
+    ? undefined
+    : String(value);
+}
+
+/**
+ * The table's filters once a quick filter picked `value`, `undefined` for its
+ * "All" entry. It writes the column's own filter — the one the filters row
+ * shows, the preferences keep and "Reset filters" clears: a default filter on
+ * the column takes the value, any other filter on it gives way.
+ */
+export function applyQuickFilter(
+  filters: TableFilter[],
+  quickFilter: Pick<ResolvedQuickFilter, "field" | "mode">,
+  value: string | undefined,
+): TableFilter[] {
+  const { field, mode } = quickFilter;
+  const pinned = filters.find(
+    (filter) => filter.accessorKey === field && filter.pinned,
+  );
+  if (pinned) {
+    return filters.map((filter) =>
+      filter === pinned ? { ...filter, mode, value } : filter,
+    );
+  }
+  const others = filters.filter((filter) => filter.accessorKey !== field);
+  return value === undefined
+    ? others
+    : [...others, { accessorKey: field, mode, value, pinned: false }];
+}
+
+/**
+ * The text of a quick filter's button: its label while nothing is picked,
+ * else the picked value's label — preceded by the filter's own label
+ * ("Role: Admin") when the table has no filters row to show the chip in.
+ */
+export function quickFilterButtonLabel(
+  quickFilter: ResolvedQuickFilter,
+  filters: TableFilter[],
+  hasFiltersRow: boolean,
+): string {
+  const value = quickFilterValue(filters, quickFilter);
+  if (value === undefined) return quickFilter.label;
+  const picked =
+    quickFilter.items.find((item) => item.value === value)?.label ?? value;
+  return hasFiltersRow ? picked : `${quickFilter.label}: ${picked}`;
+}

package/frontend-vue/layers/dms-ui/app/build/composables/table-view/utils/recordLink.ts

@@ -0,0 +1,32 @@
+import { readTableUrlKey, type TableUrlScope } from "./views";
+
+/** Query key of the row a `deepLink` action has open. */
+export const RECORD_URL_KEY = "record";
+
+/** The key this table writes the open row under: short on a sole table. */
+export function recordUrlKey(scope: TableUrlScope): string {
+  return scope.isSoleTableView || !scope.tableId
+    ? RECORD_URL_KEY
+    : `${scope.tableId}.${RECORD_URL_KEY}`;
+}
+
+/** The row the URL names for this table, if any. */
+export function readRecordId(
+  query: Record<string, unknown>,
+  scope: TableUrlScope,
+): string | undefined {
+  return readTableUrlKey(query, scope, RECORD_URL_KEY).value;
+}
+
+/**
+ * Writes (or, without an id, removes) the open row in the browser's URL in
+ * place: no visit, no history entry, the link and a reload open it again.
+ */
+export function writeRecordId(scope: TableUrlScope, id?: string): void {
+  if (typeof window === "undefined") return;
+  const url = new URL(window.location.href);
+  const key = recordUrlKey(scope);
+  if (id) url.searchParams.set(key, id);
+  else url.searchParams.delete(key);
+  window.history.replaceState(window.history.state, "", url);
+}

package/frontend-vue/layers/dms-ui/app/build/composables/table-view/utils/reorder.ts

@@ -0,0 +1,68 @@
+import { get } from "@nuxt/ui/runtime/utils/index.js";
+
+/** A row's new position value, saved by a partial edit. */
+export interface ReorderEdit {
+  id: string;
+  value: number;
+}
+
+const POSITION_STEP = 1;
+
+/** The rows with the one at `from` moved to `to`. */
+export function moveRow<T>(rows: readonly T[], from: number, to: number): T[] {
+  const next = [...rows];
+  const [moved] = next.splice(from, 1);
+  if (moved !== undefined) next.splice(to, 0, moved);
+  return next;
+}
+
+const positionOf = (row: unknown, field: string): number | undefined => {
+  const value = Number(get(row as Record<string, unknown>, field));
+  return Number.isFinite(value) ? value : undefined;
+};
+
+/**
+ * The position the moved row takes between its new neighbours, when they
+ * leave room for one: halfway between them, or a step beyond the only one.
+ */
+function slotBetween(
+  previous: number | undefined,
+  next: number | undefined,
+): number | undefined {
+  if (previous !== undefined && next !== undefined) {
+    return previous < next ? (previous + next) / 2 : undefined;
+  }
+  if (previous !== undefined) return previous + POSITION_STEP;
+  if (next !== undefined) return next - POSITION_STEP;
+  return undefined;
+}
+
+/**
+ * The edits a move saves: the moved row alone when its neighbours leave
+ * room for it, else the page renumbered from its lowest position — and only
+ * the rows whose position changed.
+ */
+export function reorderEdits(
+  rows: readonly unknown[],
+  movedIndex: number,
+  field: string,
+  rowIdKey: string,
+): ReorderEdit[] {
+  const idOf = (row: unknown) =>
+    String(get(row as Record<string, unknown>, rowIdKey));
+  const slot = slotBetween(
+    positionOf(rows[movedIndex - 1], field),
+    positionOf(rows[movedIndex + 1], field),
+  );
+  if (slot !== undefined) {
+    return [{ id: idOf(rows[movedIndex]), value: slot }];
+  }
+  const positions = rows
+    .map((row) => positionOf(row, field))
+    .filter((value): value is number => value !== undefined);
+  const base = positions.length > 0 ? Math.min(...positions) : 0;
+  return rows.flatMap((row, index) => {
+    const value = base + index * POSITION_STEP;
+    return positionOf(row, field) === value ? [] : [{ id: idOf(row), value }];
+  });
+}