@antelopejs/dms 0.5.5 → 0.6.0

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

@@ -0,0 +1,266 @@
+import type {
+  PaginationState,
+  SortingState,
+  VisibilityState,
+} from "@tanstack/vue-table";
+import type { Ref } from "vue";
+import type {
+  TableViewViewConfig,
+  TableViewViewsConfig,
+} from "../../../composables/table-view/types";
+import type {
+  TableDensity,
+  TableFilter,
+} from "../../components/table/Table.vue";
+import {
+  isSameTableState,
+  newUserViewId,
+  readTableUrlKey,
+  snapshotViewState,
+  type TableStateDefaults,
+  type TableStateSnapshot,
+  type TableUrlScope,
+  type UserTableView,
+  viewSnapshot,
+} from "./utils/views";
+
+/** The table's state a view reads and sets. */
+export interface TableViewsState {
+  columnFilters: Ref<TableFilter[]>;
+  globalFilter: Ref<string | undefined>;
+  sorting: Ref<SortingState>;
+  columnVisibility: Ref<VisibilityState>;
+  columnOrder: Ref<string[]>;
+  display: Ref<string>;
+  density: Ref<TableDensity>;
+  pagination: Ref<PaginationState>;
+}
+
+export interface TableViewsOptions {
+  views: TableViewViewsConfig | undefined;
+  defaults: TableStateDefaults;
+  state: TableViewsState;
+  /** Preference key of the table, for one of its settings. */
+  preferenceKey: (suffix: string) => string;
+  urlScope: TableUrlScope;
+}
+
+/** A view as the table lists it. */
+export interface ResolvedTableView extends TableViewViewConfig {
+  /** Saved by the user, who may update or delete it. */
+  isUserView: boolean;
+}
+
+export const VIEW_URL_KEY = "view";
+const ACTIVE_VIEW_PREFERENCE = "activeView";
+const USER_VIEWS_PREFERENCE = "userViews";
+const NO_VIEW = "";
+const VIEW_NAME_FIELD = "label";
+
+/**
+ * The views of a table view: the module's and the user's own, the one open,
+ * whether the table moved away from it, and the ways back (Reset) or forward
+ * (Save, Save as new view). Opening a view always applies its whole state:
+ * a change made to a view is not kept when another is opened.
+ */
+export function useTableViews(options: TableViewsOptions) {
+  const { views, defaults, state, preferenceKey, urlScope } = options;
+  const { getPreference, setPreference } = usePreferences();
+  const { user } = useUserSession();
+  const { t } = useI18n();
+  const { processI18n } = useTranslation();
+  const toast = useToast();
+  const { confirm } = useConfirm();
+  const route = useDmsRoute();
+
+  const userId = computed(() => user.value?._id as string | undefined);
+  const storedUserViews = ref<UserTableView[]>(
+    getPreference<UserTableView[]>(preferenceKey(USER_VIEWS_PREFERENCE), []),
+  );
+  const ownUserViews = computed(() =>
+    views?.userViews && userId.value
+      ? storedUserViews.value.filter((view) => view.ownerId === userId.value)
+      : [],
+  );
+
+  const items = computed<ResolvedTableView[]>(() => [
+    ...(views?.items ?? []).map((view) => ({
+      ...view,
+      label: processI18n(view.label),
+      isUserView: false,
+    })),
+    ...ownUserViews.value.map(({ ownerId: _ownerId, ...view }) => ({
+      ...view,
+      isUserView: true,
+    })),
+  ]);
+  const findView = (id: string | undefined) =>
+    id ? items.value.find((view) => view.id === id) : undefined;
+
+  const currentSnapshot = (): TableStateSnapshot => ({
+    filters: state.columnFilters.value,
+    search: state.globalFilter.value ?? "",
+    sorting: state.sorting.value,
+    visibility: state.columnVisibility.value,
+    order: state.columnOrder.value,
+    display: state.display.value,
+    density: state.density.value,
+  });
+
+  const applySnapshot = (snapshot: TableStateSnapshot) => {
+    state.columnFilters.value = snapshot.filters.map((filter) => ({
+      ...filter,
+    }));
+    state.globalFilter.value = snapshot.search || undefined;
+    state.sorting.value = snapshot.sorting;
+    state.columnVisibility.value = snapshot.visibility;
+    state.columnOrder.value = snapshot.order;
+    state.display.value = snapshot.display;
+    state.density.value = snapshot.density;
+    state.pagination.value = { ...state.pagination.value, pageIndex: 0 };
+  };
+
+  const activeViewId = ref<string | undefined>();
+  const activeView = computed(() => findView(activeViewId.value));
+
+  /** Opens a view, or the table's own default state without one. */
+  const openView = (id: string | undefined) => {
+    const view = findView(id);
+    activeViewId.value = view?.id;
+    applySnapshot(viewSnapshot(view, defaults));
+  };
+
+  // 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).
+  const urlView = readTableUrlKey(route.query, urlScope, VIEW_URL_KEY);
+  const persistedViewId = getPreference<string | undefined>(
+    preferenceKey(ACTIVE_VIEW_PREFERENCE),
+    undefined,
+  );
+  let isUrlViewUnavailable = false;
+  if (urlView.value && findView(urlView.value)) {
+    openView(urlView.value);
+  } else if (urlView.value) {
+    isUrlViewUnavailable = true;
+    openView(views?.defaultView);
+  } else if (persistedViewId === undefined) {
+    if (views?.defaultView) openView(views.defaultView);
+  } else {
+    activeViewId.value = findView(persistedViewId)?.id;
+  }
+
+  onMounted(() => {
+    if (urlView.ignoredShortKey && import.meta.env.DEV) {
+      console.warn(
+        `[DMS] "?${VIEW_URL_KEY}=" is ignored on a page with several table views: name the table, "?${urlScope.tableId}.${VIEW_URL_KEY}=".`,
+      );
+    }
+    if (!isUrlViewUnavailable) return;
+    toast.add({
+      title: t("dms.table.views.unavailable_title"),
+      description: t("dms.table.views.unavailable_description"),
+      color: Color.warning,
+      icon: "i-ph-eye-slash",
+    });
+  });
+
+  watch(activeViewId, (id) => {
+    setPreference(preferenceKey(ACTIVE_VIEW_PREFERENCE), id ?? NO_VIEW);
+  });
+
+  const isModified = computed(() => {
+    const view = activeView.value;
+    if (!view) return false;
+    return !isSameTableState(
+      currentSnapshot(),
+      viewSnapshot(view, defaults),
+      defaults.columnOrder,
+    );
+  });
+
+  const writeUserViews = (next: UserTableView[]) => {
+    storedUserViews.value = next;
+    setPreference(preferenceKey(USER_VIEWS_PREFERENCE), next);
+  };
+
+  /** Back to the open view's own state. */
+  const resetView = () => openView(activeViewId.value);
+
+  /** Keeps the current state in the open view, one of the user's own. */
+  const saveView = () => {
+    const view = activeView.value;
+    if (!view?.isUserView) return;
+    const state = snapshotViewState(currentSnapshot());
+    writeUserViews(
+      storedUserViews.value.map((stored) =>
+        stored.id === view.id ? { ...stored, ...state } : stored,
+      ),
+    );
+  };
+
+  const askViewName = async (): Promise<string | undefined> => {
+    let name: string | undefined;
+    const isConfirmed = await confirm({
+      title: t("dms.table.views.save_as_title"),
+      description: t("dms.table.views.save_as_description"),
+      icon: "i-ph-bookmark-simple",
+      color: "primary",
+      confirmLabel: t("dms.table.views.save_as_confirm"),
+      fields: [
+        {
+          id: VIEW_NAME_FIELD,
+          label: t("dms.table.views.name_label"),
+          type: "string",
+          required: true,
+          component: {
+            componentName: "dms-input-text",
+            options: { placeholder: t("dms.table.views.name_placeholder") },
+          },
+        },
+      ],
+      onConfirm: async (values) => {
+        name = String(values[VIEW_NAME_FIELD] ?? "").trim() || undefined;
+      },
+    });
+    return isConfirmed ? name : undefined;
+  };
+
+  /** Saves the current state as a new view of the user's, then opens it. */
+  const saveAsNewView = async () => {
+    const owner = userId.value;
+    if (!views?.userViews || !owner) return;
+    const label = await askViewName();
+    if (!label) return;
+    const view: UserTableView = {
+      id: newUserViewId(),
+      label,
+      ownerId: owner,
+      ...snapshotViewState(currentSnapshot()),
+    };
+    writeUserViews([...storedUserViews.value, view]);
+    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;
+  };
+
+  return {
+    items,
+    activeViewId,
+    activeView,
+    isModified,
+    canSaveViews: !!views?.userViews,
+    openView,
+    resetView,
+    saveView,
+    saveAsNewView,
+    deleteView,
+  };
+}
+
+export type TableViewsApi = ReturnType<typeof useTableViews>;

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

@@ -0,0 +1,152 @@
+import type {
+  ConfirmColor,
+  ConfirmNotice,
+} from "../../../../composables/confirm/types";
+
+/** A table's row selection, by row id (TanStack `RowSelectionState`). */
+export type RowSelectionMap = Record<string, boolean>;
+
+/** The ids of the selected rows, every page included. */
+export function selectedRowIds(selection: RowSelectionMap): string[] {
+  return Object.keys(selection).filter((id) => selection[id]);
+}
+
+/**
+ * The query of a bulk request: the ids go as one repeated key
+ * (`?ids=a&ids=b`), which the data routes read in full.
+ */
+export function bulkActionQuery(
+  queryKey: string,
+  ids: string[],
+): Record<string, string | string[]> {
+  return { [queryKey]: [...ids] };
+}
+
+/** The bulk actions that ask before running. */
+export type ConfirmedBulkAction = "delete" | "deletePermanently" | "archive";
+
+/**
+ * Tone of each confirmation: archiving can be undone (warning), deleting
+ * cannot (error), from the archive or from the list alike.
+ */
+export const BULK_CONFIRM_TONES: Record<ConfirmedBulkAction, ConfirmColor> = {
+  delete: "error",
+  deletePermanently: "error",
+  archive: "warning",
+};
+
+const BULK_CONFIRM_ICONS: Record<ConfirmedBulkAction, string> = {
+  delete: "i-ph-trash",
+  deletePermanently: "i-ph-trash",
+  archive: "i-ph-archive",
+};
+
+const BULK_CONFIRM_KEYS: Record<ConfirmedBulkAction, string> = {
+  delete: "delete",
+  deletePermanently: "delete_permanently",
+  archive: "archive",
+};
+
+/** vue-i18n's `t(key, named, plural)`. */
+export type PluralTranslate = (
+  key: string,
+  named: Record<string, unknown>,
+  plural: number,
+) => string;
+
+/** What the confirmation of a bulk action says, and in which tone. */
+export interface BulkActionConfirm {
+  title: string;
+  description: string;
+  confirmLabel: string;
+  color: ConfirmColor;
+  icon: string;
+}
+
+/**
+ * The confirmation of `action` over `count` rows: its texts name how many rows
+ * it reaches, in the singular or the plural.
+ */
+export function bulkActionConfirm(
+  action: ConfirmedBulkAction,
+  count: number,
+  t: PluralTranslate,
+): BulkActionConfirm {
+  const prefix = `dms.table.${BULK_CONFIRM_KEYS[action]}_confirm`;
+  return {
+    title: t(`${prefix}_title`, { count }, count),
+    description: t(`${prefix}_description`, { count }, count),
+    confirmLabel: t(`${prefix}_button`, { count }, count),
+    color: BULK_CONFIRM_TONES[action],
+    icon: BULK_CONFIRM_ICONS[action],
+  };
+}
+
+/** What a bulk request reached: the rows it changed and the ones it left. */
+export interface BulkActionOutcome {
+  processed: number;
+  skipped: number;
+}
+
+// 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;
+
+const readCount = (response: unknown): number | undefined => {
+  if (typeof response === "number") return response;
+  if (!response || typeof response !== "object") return undefined;
+  for (const key of COUNT_KEYS) {
+    const value = (response as Record<string, unknown>)[key];
+    if (typeof value === "number") return value;
+  }
+  return undefined;
+};
+
+/**
+ * How many of the requested rows a bulk route changed. Rows a row rule
+ * rejects (or that no longer exist) are left out by the server: they are the
+ * skipped ones. A response without a count is taken as a full success.
+ */
+export function bulkActionOutcome(
+  response: unknown,
+  requested: number,
+): BulkActionOutcome {
+  const count = readCount(response);
+  const processed =
+    count === undefined ? requested : Math.min(Math.max(count, 0), requested);
+  return { processed, skipped: requested - processed };
+}
+
+/** The bulk routes whose outcome counts the rows they reached. */
+export type BulkActionKind = "delete" | "archive" | "restore";
+
+/**
+ * What a bulk action says when rows were left out (a row rule refused them,
+ * or they were already gone): how many of the selection, and why. Undefined
+ * when every row went through. The server gives no reason per row, so the
+ * reason is the one rows are skipped for.
+ */
+export function bulkActionShortfall(
+  action: BulkActionKind,
+  outcome: BulkActionOutcome,
+  t: PluralTranslate,
+): ConfirmNotice | undefined {
+  const { processed, skipped } = outcome;
+  if (skipped === 0) return undefined;
+  return {
+    title:
+      processed === 0
+        ? t(`dms.table.bulk_refused.${action}`, { count: skipped }, skipped)
+        : t(
+            `dms.table.bulk_partial.${action}`,
+            { failed: skipped, total: processed + skipped },
+            skipped,
+          ),
+    description: t(
+      "dms.table.bulk_refused_reason",
+      { count: skipped },
+      skipped,
+    ),
+  };
+}

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

@@ -0,0 +1,75 @@
+import { get } from "@nuxt/ui/runtime/utils/index.js";
+import type {
+  TableViewCardProps,
+  TableViewDisplayContext,
+} from "../../../../composables/table-view/types/display";
+import type { TableViewColumn } from "../../../../composables/table-view/types/column";
+
+// The columns a card shows when its table declares no `card.fields`.
+const FALLBACK_CARD_FIELD_COUNT = 4;
+
+/** What a card shows already, so its fields leave it out. */
+export interface CardShownKeys {
+  /** The card's title. */
+  labelKey?: string;
+  rowIdKey: string;
+  /** Shown another way: the column a kanban card sits in. */
+  others?: string[];
+}
+
+/** The id of a row, read with the table's `rowIdKey`. */
+export function cardRowId<T>(item: T, rowIdKey: string): string {
+  return String(get(item as Record<string, unknown>, rowIdKey) ?? "");
+}
+
+/**
+ * The props a custom card receives for `item`, the same whichever display
+ * draws it.
+ */
+export function buildCardProps<T>(
+  item: T,
+  context: Pick<
+    TableViewDisplayContext<T>,
+    "columns" | "labelKey" | "rowIdKey" | "actions" | "selection"
+  >,
+): TableViewCardProps<T> {
+  const rowId = cardRowId(item, context.rowIdKey);
+  return {
+    row: item,
+    rowId,
+    columns: context.columns,
+    labelKey: context.labelKey,
+    actions: context.actions,
+    selected: context.selection.isSelected(rowId),
+    select: (value?: boolean) => context.selection.toggle(rowId, value),
+    open: () => context.actions.open(item),
+  };
+}
+
+/**
+ * The columns a card shows below its title, on the cards grid and the kanban
+ * board alike: the declared `card.fields`, else the first listable columns
+ * besides what the card shows already.
+ */
+export function cardFieldColumns(
+  columns: TableViewColumn[],
+  declared: string[] | undefined,
+  shown: CardShownKeys,
+): TableViewColumn[] {
+  if (declared) {
+    return declared
+      .map((key) => columns.find((column) => column.accessorKey === key))
+      .filter((column): column is TableViewColumn => !!column);
+  }
+  const skipped = new Set([
+    shown.labelKey,
+    shown.rowIdKey,
+    ...(shown.others ?? []),
+  ]);
+  return columns
+    .filter(
+      (column) =>
+        column.listable !== false && !skipped.has(column.accessorKey),
+    )
+    .slice(0, FALLBACK_CARD_FIELD_COUNT);
+}

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

@@ -0,0 +1,70 @@
+import type { TableViewLayout } from "../../../../composables/table-view/types/config";
+
+/** Every chrome control of a table view, resolved. */
+export interface ResolvedTableChrome {
+  caption: boolean;
+  /** `toggle`: a button opening a field; `field`: always open; `none`. */
+  search: "toggle" | "field" | "none";
+  filters: boolean;
+  sorting: boolean;
+  refresh: boolean;
+  menu: boolean;
+  columnMenus: boolean;
+  pageSize: boolean;
+}
+
+/** What a table has to offer, which decides the controls worth drawing. */
+export interface TableChromeContext {
+  /** The table names itself (`caption`). */
+  hasCaption: boolean;
+  /** The controller declares `@Searchable` fields. */
+  isSearchable: boolean;
+  /** A column is `filterable`. */
+  isFilterable: boolean;
+}
+
+const LAYOUT_CHROME: Record<TableViewLayout, ResolvedTableChrome> = {
+  full: {
+    caption: true,
+    search: "toggle",
+    filters: true,
+    sorting: true,
+    refresh: true,
+    menu: true,
+    columnMenus: true,
+    pageSize: true,
+  },
+  // The list of a settings page: tabs, an open search field, quick filters,
+  // sortable headers, the row menu and a short footer.
+  compact: {
+    caption: false,
+    search: "field",
+    filters: false,
+    sorting: false,
+    refresh: false,
+    menu: false,
+    columnMenus: false,
+    pageSize: false,
+  },
+};
+
+/** The full chrome: what a standalone table draws when nothing is configured. */
+export const FULL_TABLE_CHROME: ResolvedTableChrome = LAYOUT_CHROME.full;
+
+/**
+ * The controls a table draws: those of its `layout`, less the ones it has
+ * nothing to offer through (no caption to show, no field to search in, no
+ * column to filter on).
+ */
+export function resolveTableChrome(
+  layout: TableViewLayout | undefined,
+  context: TableChromeContext,
+): ResolvedTableChrome {
+  const base = LAYOUT_CHROME[layout ?? "full"] ?? FULL_TABLE_CHROME;
+  return {
+    ...base,
+    caption: base.caption && context.hasCaption,
+    search: context.isSearchable ? base.search : "none",
+    filters: base.filters && context.isFilterable,
+  };
+}

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

@@ -0,0 +1,24 @@
+import type {
+  TableViewDisplayContext,
+  TableViewExpandedRowProps,
+} from "../../../../composables/table-view/types/display";
+import { cardRowId } from "./card";
+
+/** The props a custom detail band receives for `item`. */
+export function buildExpandedRowProps<T>(
+  item: T,
+  context: Pick<
+    TableViewDisplayContext<T>,
+    "columns" | "labelKey" | "rowIdKey" | "actions" | "refresh"
+  >,
+): TableViewExpandedRowProps<T> {
+  return {
+    row: item,
+    rowId: cardRowId(item, context.rowIdKey),
+    columns: context.columns,
+    labelKey: context.labelKey,
+    actions: context.actions,
+    open: () => context.actions.open(item),
+    refresh: context.refresh,
+  };
+}

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

@@ -0,0 +1,51 @@
+/** Open rows of an expandable table, by row id. */
+export type ExpandedRowMap = Record<string, boolean>;
+
+/** Which rows open on arrival (backend `expandable.defaultExpanded`). */
+export type ExpandedDefault = "none" | "first" | "all";
+
+/**
+ * The rows a freshly listed set opens with: none, the first one, or all of
+ * them (only the first in single mode).
+ */
+export function defaultExpandedRows(
+  rowIds: string[],
+  mode: ExpandedDefault = "none",
+  single = false,
+): ExpandedRowMap {
+  if (mode === "none" || rowIds.length === 0) return {};
+  if (mode === "first" || single) return { [rowIds[0]!]: true };
+  return Object.fromEntries(rowIds.map((id) => [id, true]));
+}
+
+/**
+ * The open rows after a toggle. TanStack hands either a map or `true` ("all
+ * rows"); `true` becomes an explicit map of the listed rows. Single mode keeps
+ * only the row opened last.
+ */
+export function nextExpandedRows(
+  previous: ExpandedRowMap,
+  next: ExpandedRowMap | true,
+  rowIds: string[],
+  single = false,
+): ExpandedRowMap {
+  const nextMap: ExpandedRowMap =
+    next === true
+      ? Object.fromEntries(rowIds.map((id) => [id, true]))
+      : Object.fromEntries(Object.entries(next).filter(([, open]) => open));
+  if (!single) return nextMap;
+  const opened = Object.keys(nextMap).filter((id) => !previous[id]);
+  const kept = opened.at(-1) ?? Object.keys(nextMap).at(-1);
+  return kept ? { [kept]: true } : {};
+}
+
+/** Open rows still listed after a refresh of the same set. */
+export function keepListedRows(
+  expanded: ExpandedRowMap,
+  rowIds: string[],
+): ExpandedRowMap {
+  const listed = new Set(rowIds);
+  return Object.fromEntries(
+    Object.entries(expanded).filter(([id]) => listed.has(id)),
+  );
+}