@antelopejs/dms 0.9.8 → 0.11.0

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

@@ -54,6 +54,12 @@ export interface ResolvedTableView extends TableViewViewConfig {
 
 export const VIEW_URL_KEY = "view";
 const NO_VIEW = "";
+
+/**
+ * The open view as the preferences keep it: no view open is kept too, so the
+ * next visit does not fall back to the default view.
+ */
+export const keptViewId = (id: string | undefined): string => id ?? NO_VIEW;
 const VIEW_NAME_FIELD = "label";
 
 /**
@@ -128,11 +134,58 @@ export function useTableViews(options: TableViewsOptions) {
     applySnapshot(viewSnapshot(view, defaults));
   };
 
+  /**
+   * Opens a view, or, for the one already open, closes it: back to the
+   * table's own default state without a view.
+   */
+  const selectView = (id: string) =>
+    openView(id === activeViewId.value ? undefined : id);
+
+  /**
+   * Back on the view kept from the last visit. The table's state is kept
+   * apart and restored as it was left, modified or not, but the search is
+   * not kept: the view's own comes back with it.
+   */
+  const restoreKeptView = (id: string) => {
+    const view = findView(id);
+    activeViewId.value = view?.id;
+    if (view) state.globalFilter.value = view.search || undefined;
+  };
+
+  /**
+   * Opens a link followed on the table already shown as a linked arrival
+   * reads it: the view it names, else the default view, else the table's
+   * default listing state under the reader's own presentation.
+   */
+  const openLinkedView = (query: Record<string, unknown>) => {
+    const named = readTableUrlKey(query, urlScope, VIEW_URL_KEY);
+    const view = named.isCleared
+      ? undefined
+      : (findView(named.value) ?? findView(views?.defaultView));
+    if (view) return openView(view.id);
+    openDefaultListing();
+  };
+
+  /**
+   * No view open, the table's default listing state (filters, search, sort)
+   * under the reader's own presentation: what a link to no view opens.
+   */
+  const openDefaultListing = () => {
+    const snapshot = viewSnapshot(undefined, defaults);
+    activeViewId.value = undefined;
+    state.columnFilters.value = snapshot.filters.map((filter) => ({
+      ...filter,
+    }));
+    state.globalFilter.value = undefined;
+    state.sorting.value = snapshot.sorting;
+    state.pagination.value = { ...state.pagination.value, pageIndex: 0 };
+  };
+
   // Read once, on arrival: a view named by the URL wins over the state kept
   // from the last visit; a view the caller may not open falls back to the
   // default one, with a word (on the client, once mounted). The user's views
   // are kept in the browser, so a view that is not the module's is resolved
-  // once mounted.
+  // once mounted. An empty one (`?view=`) names no view.
   const urlView = readTableUrlKey(route.query, urlScope, VIEW_URL_KEY);
   const persistedViewId = preferences.get<string | undefined>(
     "activeView",
@@ -141,7 +194,9 @@ export function useTableViews(options: TableViewsOptions) {
   let isUrlViewUnavailable = false;
   let isUrlViewPending = false;
   let isOpenedOnArrival = false;
-  if (urlView.value && findView(urlView.value)) {
+  if (urlView.isCleared) {
+    openDefaultListing();
+  } else if (urlView.value && findView(urlView.value)) {
     openView(urlView.value);
     isOpenedOnArrival = true;
   } else if (urlView.value) {
@@ -150,7 +205,7 @@ export function useTableViews(options: TableViewsOptions) {
     if (views?.defaultView) openView(views.defaultView);
     isOpenedOnArrival = !!views?.defaultView;
   } else {
-    activeViewId.value = findView(persistedViewId)?.id;
+    restoreKeptView(persistedViewId);
   }
 
   // The browser-only state (order, density) is restored over the view opened
@@ -168,7 +223,7 @@ export function useTableViews(options: TableViewsOptions) {
     } else if (isOpenedOnArrival) {
       reapplyBrowserState();
     } else if (persistedViewId && !activeViewId.value) {
-      activeViewId.value = findView(persistedViewId)?.id;
+      restoreKeptView(persistedViewId);
     }
   };
 
@@ -189,7 +244,11 @@ export function useTableViews(options: TableViewsOptions) {
   });
 
   watch(activeViewId, (id) => {
-    preferences.set<string | undefined>("activeView", id ?? NO_VIEW, undefined);
+    preferences.set<string | undefined>(
+      "activeView",
+      keptViewId(id),
+      undefined,
+    );
   });
 
   const isModified = computed(() => {
@@ -265,11 +324,26 @@ export function useTableViews(options: TableViewsOptions) {
     activeViewId.value = view.id;
   };
 
-  /** Deletes one of the user's views; the table keeps its state. */
-  const deleteView = (id: string) => {
-    if (!findView(id)?.isUserView) return;
-    writeUserViews(storedUserViews.value.filter((view) => view.id !== id));
-    if (activeViewId.value === id) activeViewId.value = undefined;
+  /**
+   * Deletes one of the user's views, once confirmed. Deleting the open one
+   * goes back to the table's own default state: what it set (its search
+   * above all) would otherwise stay applied with no view to show it.
+   */
+  const deleteView = async (id: string) => {
+    const view = findView(id);
+    if (!view?.isUserView) return;
+    const isConfirmed = await confirm({
+      title: t("dms.table.views.delete_title"),
+      description: t("dms.table.views.delete_description", {
+        view: view.label,
+      }),
+      icon: "i-ph-trash",
+      color: "error",
+      confirmLabel: t("dms.table.views.delete"),
+    });
+    if (!isConfirmed) return;
+    writeUserViews(storedUserViews.value.filter((stored) => stored.id !== id));
+    if (activeViewId.value === id) openView(undefined);
   };
 
   return {
@@ -279,6 +353,8 @@ export function useTableViews(options: TableViewsOptions) {
     isModified,
     canSaveViews: !!views?.userViews,
     openView,
+    selectView,
+    openLinkedView,
     resetView,
     saveView,
     saveAsNewView,

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

@@ -90,10 +90,20 @@ export interface BulkActionOutcome {
 
 // The count each bulk route answers with: delete sends the number of deleted
 // rows (or `{ deleted }` when a row rule filtered out every id), archive and
-// restore send `{ archivedCount }` / `{ restoredCount }`.
-const COUNT_KEYS = ["deleted", "archivedCount", "restoredCount"] as const;
+// restore send `{ archivedCount }` / `{ restoredCount }`, and a custom bulk
+// route `{ count }`.
+const COUNT_KEYS = [
+  "count",
+  "deleted",
+  "archivedCount",
+  "restoredCount",
+] as const;
 
-const readCount = (response: unknown): number | undefined => {
+/**
+ * The number of rows a bulk route says it changed: a bare number or one of
+ * its count keys, `undefined` when it does not say.
+ */
+export const readBulkCount = (response: unknown): number | undefined => {
   if (typeof response === "number") return response;
   if (!response || typeof response !== "object") return undefined;
   for (const key of COUNT_KEYS) {
@@ -112,7 +122,7 @@ export function bulkActionOutcome(
   response: unknown,
   requested: number,
 ): BulkActionOutcome {
-  const count = readCount(response);
+  const count = readBulkCount(response);
   const processed =
     count === undefined ? requested : Math.min(Math.max(count, 0), requested);
   return { processed, skipped: requested - processed };

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

@@ -1,3 +1,4 @@
+import type { CSSProperties } from "vue";
 import { get } from "@nuxt/ui/runtime/utils/index.js";
 import type {
   TableViewCardProps,
@@ -68,8 +69,132 @@ export function cardFieldColumns(
   ]);
   return columns
     .filter(
-      (column) =>
-        column.listable !== false && !skipped.has(column.accessorKey),
+      (column) => column.listable !== false && !skipped.has(column.accessorKey),
     )
     .slice(0, FALLBACK_CARD_FIELD_COUNT);
 }
+
+/** The id of the data type drawing a name with its avatar and subtitle. */
+const IDENTITY_DISPLAY_TYPE = "identity";
+
+/** The database id: a technical key, never worth a line on a card. */
+const DATABASE_ID_KEY = "_id";
+
+/**
+ * What a built-in card reads off its row besides its title: the subtitle and
+ * the avatar the title column's `identity` display declares, so a card shows
+ * the row as its grid cell does.
+ */
+export interface CardIdentity {
+  /** Row field drawn under the title. */
+  subtitleField?: string;
+  /** Row field holding the avatar: an image value or a URL. */
+  avatarField?: string;
+  /** File storage the avatar is read from. */
+  storage?: string;
+}
+
+const optionString = (
+  options: Record<string, unknown> | undefined,
+  key: string,
+): string | undefined =>
+  typeof options?.[key] === "string" ? options[key] : undefined;
+
+/** The identity the title column (`labelKey`) declares, if it is one. */
+export function cardIdentity(
+  columns: TableViewColumn[],
+  labelKey: string | undefined,
+): CardIdentity {
+  if (!labelKey) return {};
+  const display = columns.find(
+    (column) => column.accessorKey === labelKey,
+  )?.display;
+  if (display?.type !== IDENTITY_DISPLAY_TYPE) return {};
+  return {
+    subtitleField: optionString(display.options, "subtitleField"),
+    avatarField: optionString(display.options, "avatarField"),
+    storage: optionString(display.options, "storage"),
+  };
+}
+
+const hasValue = (value: unknown): boolean =>
+  value !== undefined && value !== null && value !== "";
+
+/**
+ * The line a card draws under its title, as the row holds it: the identity's
+ * subtitle, else the row's id when the table names it with a key of its own
+ * (`rowIdKey: "code"`) and the title is not it already. The database `_id`
+ * is never shown: a UUID or `proj-074` tells the reader nothing.
+ */
+export function cardSubtitle<T>(
+  item: T,
+  identity: CardIdentity,
+  shown: CardShownKeys,
+): unknown {
+  const row = item as Record<string, unknown>;
+  if (identity.subtitleField) {
+    const subtitle: unknown = get(row, identity.subtitleField);
+    if (hasValue(subtitle)) return subtitle;
+  }
+  if (shown.rowIdKey === DATABASE_ID_KEY) return undefined;
+  if (!shown.labelKey || !hasValue(get(row, shown.labelKey))) return undefined;
+  const id = cardRowId(item, shown.rowIdKey);
+  return id || undefined;
+}
+
+/** The avatar a card draws in place of the title's initials, if any. */
+export function cardAvatar<T>(
+  item: T,
+  identity: CardIdentity,
+): { key: string } | string | undefined {
+  if (!identity.avatarField) return undefined;
+  const avatar: unknown = get(
+    item as Record<string, unknown>,
+    identity.avatarField,
+  );
+  if (typeof avatar === "string") return avatar || undefined;
+  if (avatar && typeof avatar === "object" && "key" in avatar) {
+    const { key } = avatar as { key: unknown };
+    return typeof key === "string" && key ? { key } : undefined;
+  }
+  return undefined;
+}
+
+/** The narrowest a card of the `cards` display gets (backend `card.minWidth`). */
+export const DEFAULT_CARD_MIN_WIDTH = "230px";
+
+// The grid's gap and side padding, as `CARD_GRID_CLASS` sets them: the width
+// cap below adds them to the cards' own.
+const CARD_GRID_GAP = "0.75rem";
+const CARD_GRID_PADDING = "36px";
+
+// How much wider than `card.minWidth` a card may stretch when the row has room
+// for more cards than the list holds. A full row hardly reaches it: n cards
+// fit, but not n + 1, so each one stays under twice the minimum, give or take
+// a gap.
+const CARD_MAX_WIDTH_FACTOR = 2;
+
+/**
+ * The cards grid: auto-fit tracks of at least `--dms-card-min-width` (the
+ * whole row on a narrower screen), so a short list's empty tracks collapse
+ * and its cards stretch across the row instead of leaving a hole at its end.
+ */
+export const CARD_GRID_CLASS =
+  "grid grid-cols-[repeat(auto-fit,minmax(min(var(--dms-card-min-width),100%),1fr))] gap-3 px-[18px] pt-4 pb-[18px]";
+
+/**
+ * The style of a cards grid holding `count` cards of at least `minWidth` (a
+ * CSS length): the width its tracks start from, and a cap keeping one or two
+ * cards from stretching across a whole wide screen.
+ */
+export function cardGridStyle(
+  minWidth: string | undefined,
+  count: number,
+): CSSProperties {
+  const width = minWidth || DEFAULT_CARD_MIN_WIDTH;
+  const cards = Math.max(1, count);
+  return {
+    "--dms-card-min-width": width,
+    maxWidth: `calc(${cards} * ${CARD_MAX_WIDTH_FACTOR} * ${width} + ${cards - 1} * ${CARD_GRID_GAP} + ${CARD_GRID_PADDING})`,
+  };
+}

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

@@ -0,0 +1,13 @@
+/** The text of a cell value, as the browser searches and sorts it. */
+export const textOf = (value: unknown): string =>
+  value === null || value === undefined
+    ? ""
+    : typeof value === "object"
+      ? JSON.stringify(value)
+      : String(value);
+
+/** Orders two cell values the browser sorts: numbers by value, else as text. */
+export const compareValues = (a: unknown, b: unknown): number => {
+  if (typeof a === "number" && typeof b === "number") return a - b;
+  return textOf(a).localeCompare(textOf(b), undefined, { numeric: true });
+};

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

@@ -49,3 +49,31 @@ export function keepListedRows(
     Object.entries(expanded).filter(([id]) => listed.has(id)),
   );
 }
+
+/** A table's open rows, and the listed set (its query) they belong to. */
+export interface ExpandedRowsState {
+  expanded: ExpandedRowMap;
+  listedKey?: string;
+}
+
+/**
+ * The open rows once the listed rows change: a newly listed set (another
+ * `listedKey`: page, filter, search, sort, tab, archive view) opens with
+ * `defaultExpanded`; a refresh of the same set keeps what the user opened,
+ * minus rows no longer listed. Rows that have not arrived yet (`undefined`,
+ * the list still loading, as on a first load) list no set: the default waits
+ * for them instead of being spent on an empty table.
+ */
+export function expandedRowsOnListing(
+  state: ExpandedRowsState,
+  rowIds: string[] | undefined,
+  listedKey: string,
+  mode?: ExpandedDefault,
+  single?: boolean,
+): ExpandedRowsState {
+  if (!rowIds) return state;
+  if (listedKey === state.listedKey) {
+    return { listedKey, expanded: keepListedRows(state.expanded, rowIds) };
+  }
+  return { listedKey, expanded: defaultExpandedRows(rowIds, mode, single) };
+}

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

@@ -1,4 +1,5 @@
-import type { SortingState } from "@tanstack/vue-table";
+import { get } from "@nuxt/ui/runtime/utils/index.js";
+import type { ColumnSort, SortingState } from "@tanstack/vue-table";
 import {
   regionalDateTimeFormat,
   regionalDayKey,
@@ -13,6 +14,7 @@ import type {
   TableViewGroupedConfig,
 } from "../../../../composables/table-view/types";
 import type { TableFilter } from "../../../components/table/Table.vue";
+import { compareValues } from "./compareValues";
 import { sortValueKind } from "./sortableColumns";
 
 /** Key of the group of rows without a value. */
@@ -146,6 +148,91 @@ export function groupedSorting(
   return [{ id: groupByField, desc: own ? !!own.desc : by !== "value" }];
 }
 
+/**
+ * The sort a group's rows follow on the grouped display. The list route sorts
+ * on one field, the grouped column, so the sort picked on another column —
+ * by the user or a view, or the hand order of a `reorder` table — orders each
+ * group's rows in the browser instead, over the page listed.
+ */
+export function withinGroupSort(
+  picked: SortingState,
+  grouped: TableViewGroupedConfig,
+): ColumnSort | undefined {
+  return picked.find((entry) => entry.id !== grouped.groupByField);
+}
+
+/** What decides the order a table view lists its rows in. */
+export interface TableSortingInput {
+  /** The order field of a hand-ordered table (`reorder`). */
+  reorderField?: string;
+  /** The grouped options, while the grouped display shows. */
+  grouped?: TableViewGroupedConfig;
+  /** The display shown offers the sort picker. */
+  canSort: boolean;
+  /** The sort the user picked or a view opened with. */
+  sorting: SortingState;
+  /** The table's default sort. */
+  defaultSorting: SortingState;
+}
+
+/**
+ * The order the rows are wanted in: the hand order of a `reorder` table,
+ * else the picked sort. The grouped display hides the sort picker but keeps
+ * the sort a view opened it with: it orders the rows of each group.
+ */
+export function pickedTableSorting(input: TableSortingInput): SortingState {
+  if (input.reorderField) return [{ id: input.reorderField, desc: false }];
+  return input.canSort || input.grouped ? input.sorting : input.defaultSorting;
+}
+
+/**
+ * The sort the list route is asked for (the route sorts on one field): on the
+ * grouped display, the grouped column, so that a group's rows follow each
+ * other — the picked order then sorts each group, see
+ * {@link orderGroupedRows}; else the picked order.
+ */
+export function listTableSorting(input: TableSortingInput): SortingState {
+  const picked = pickedTableSorting(input);
+  if (input.grouped) return groupedSorting(picked, input.grouped);
+  return picked;
+}
+
+/**
+ * The rows of a page listed on the grouped column, each group's rows in the
+ * order `picked` gives them (see {@link withinGroupSort}). The groups keep
+ * the order the list gave them; rows the sort cannot tell apart keep theirs.
+ */
+export function orderGroupedRows<T>(
+  rows: T[],
+  grouped: TableViewGroupedConfig,
+  picked: SortingState,
+  locale: string,
+): T[] {
+  const sort = withinGroupSort(picked, grouped);
+  if (!sort) return rows;
+  const by = grouped.by ?? "value";
+  const groupOf = new Map<string, number>();
+  const entries = rows.map((row, index) => {
+    const key = rowGroupKey(
+      get(row as Record<string, unknown>, grouped.groupByField),
+      by,
+      locale,
+    );
+    if (!groupOf.has(key)) groupOf.set(key, groupOf.size);
+    return { row, index, group: groupOf.get(key)! };
+  });
+  const direction = sort.desc ? -1 : 1;
+  const valueOf = (row: T) => get(row as Record<string, unknown>, sort.id);
+  return entries
+    .sort(
+      (a, b) =>
+        a.group - b.group ||
+        direction * compareValues(valueOf(a.row), valueOf(b.row)) ||
+        a.index - b.index,
+    )
+    .map((entry) => entry.row);
+}
+
 /** How a date column picked in the options menu is cut, unless configured. */
 const DEFAULT_DATE_GROUP_BY: TableViewGroupBy = "day";
 
@@ -178,3 +265,29 @@ export function groupedOptionsFor(
     grouped.by && grouped.by !== "value" ? grouped.by : DEFAULT_DATE_GROUP_BY;
   return { ...grouped, groupByField: field, by };
 }
+
+/** The rows of one group, under its key. */
+export interface RowGroup<T> {
+  key: string;
+  rows: T[];
+}
+
+/**
+ * The rows filed under their group, each group once, in the order its first
+ * row comes. The list is sorted on the grouped column, but rows listed in
+ * another order — the previous sort, still shown while the grouped one loads
+ * — must not open a group twice: two headers under one key.
+ */
+export function groupRows<T>(
+  rows: readonly T[],
+  keyOf: (row: T) => string,
+): RowGroup<T>[] {
+  const groups = new Map<string, T[]>();
+  for (const row of rows) {
+    const key = keyOf(row);
+    const group = groups.get(key);
+    if (group) group.push(row);
+    else groups.set(key, [row]);
+  }
+  return [...groups].map(([key, grouped]) => ({ key, rows: grouped }));
+}