@antelopejs/dms 0.7.9 → 0.7.11

package/frontend-vue/layers/dms-ui/app/components/table-view/TableView.vue

@@ -70,6 +70,7 @@ import {
   defaultSortingState,
   resolveDefaultSortConfig,
   sanitizeSorting,
+  sortingOrDefault,
   sortableColumnIds,
   sortValueKind,
 } from "../../build/composables/table-view/utils/sortableColumns";
@@ -100,6 +101,7 @@ import {
   rowCustomActions,
 } from "../../utils/rowClickAction";
 import { usePermissionPreview } from "#dms-core/app/build/composables/auth/usePermissionPreview";
+import type { RowActionRule } from "#dms-core/app/types/row-action";
 
 import UTable from "../../build/components/table/Table.vue";
 import ExpandedRowDetail from "../../build/components/table-view/ExpandedRowDetail.vue";
@@ -114,7 +116,9 @@ import type {
 } from "../../build/components/table/Table.vue";
 import {
   defineAsyncComponent,
+  useTemplateRef,
   type Component,
+  type ComponentPublicInstance,
   type WatchOptions,
   type WatchSource,
 } from "vue";
@@ -124,9 +128,13 @@ import { useGroupedRows } from "../../build/composables/table-view/useGroupedRow
 import { useTableFooter } from "../../build/composables/table-view/useTableFooter";
 import { useAccumulatedPages } from "../../build/composables/table-view/useAccumulatedPages";
 import { usePersistedPagination } from "../../build/composables/table-view/usePersistedPagination";
+import { useTablePreferences } from "../../build/composables/table-view/useTablePreferences";
+import type { Ref } from "vue";
+import type { TableField } from "#dms-core/app/build/composables/user/tablePreferences";
 import { useTableRows } from "../../build/composables/table-view/useTableRows";
 import { useRefreshTriggers } from "../../build/composables/blocks/useRefreshTriggers";
 import { useTableLiveHold } from "../../build/composables/table-view/useTableLiveHold";
+import type { TableViewLiveHoldOptions } from "../../types/live";
 import { usePageLive } from "../../composables/live/usePageLive";
 import LiveHoldBanner from "../../build/components/table-view/LiveHoldBanner.vue";
 import { useTableReorder } from "../../build/composables/table-view/useTableReorder";
@@ -169,6 +177,9 @@ interface RealtimePresenceActor {
 
 type RealtimePresenceMap = Record<string, RealtimePresenceActor[]>;
 
+/** A kept field of the table, its state, and its default. */
+type TableStatePreference = [TableField, Ref<unknown>, unknown];
+
 // The backend options of a table view, declared here as well so the
 // component's runtime props never depend on resolving the imported config.
 interface TableViewProps<T extends Data> extends TableViewConfig<T> {
@@ -176,6 +187,8 @@ interface TableViewProps<T extends Data> extends TableViewConfig<T> {
   expandable?: TableViewExpandableConfig;
   /** Placeholder of the search field. */
   searchPlaceholder?: string;
+  /** Key opening the search (`defineShortcuts` notation); `shift_f` else. */
+  searchShortcut?: string;
   /** One-click dropdown filters of the toolbar. */
   quickFilters?: TableViewQuickFilter[];
   /** Rows per page while the user picked none. */
@@ -186,6 +199,8 @@ interface TableViewProps<T extends Data> extends TableViewConfig<T> {
   source?: TableViewSourceConfig;
   /** Rows ordered by hand on a number column (backend `reorder`). */
   reorder?: TableViewReorderConfig;
+  /** Rows listed first whatever the sort (backend `pinnedRows`). */
+  pinnedRows?: RowActionRule;
   /** Footer texts and figures: row count, hint, summaries and legend. */
   footer?: TableViewFooter;
   /** What the empty body says, per reason it is empty. */
@@ -199,7 +214,7 @@ interface TableViewProps<T extends Data> extends TableViewConfig<T> {
   /** Topics whose events make the table read its rows again. */
   realtimeTopic?: string | string[];
   /** Keeps the rows while the live page is paused (backend `liveHold`). */
-  liveHold?: boolean;
+  liveHold?: boolean | TableViewLiveHoldOptions;
 }
 
 const props = defineProps<TableViewProps<T>>();
@@ -230,14 +245,10 @@ const {
   defaultDisplay,
 } = useTableViewConfig<T>(props);
 
-const { getPreference, setPreference } = usePreferences();
+const tablePreferences = useTablePreferences(componentId, pageId);
 const { sendComponentEvent } = useComponentEvent(componentId);
 const { processI18n } = useTranslation();
 
-const getTablePreferenceKey = (suffix: string) => {
-  return `tables.${componentId}.${pageId}.${suffix}`;
-};
-
 const kanbanEligibleColumns = allColumns.filter(isEligibleKanbanColumn);
 const kanbanGroupByOptions = kanbanEligibleColumns.map((column) => ({
   label: processI18n(column.header),
@@ -260,8 +271,8 @@ const groupedOptions = optionsForDisplay(GROUPED_DISPLAY_ID) as
 
 // Stored under the legacy "viewMode" key (free migration of "table"/"kanban");
 // clamped to the offered set so a stale/removed id never renders an un-offered display.
-const persistedDisplay = getPreference<string>(
-  getTablePreferenceKey("viewMode"),
+const persistedDisplay = tablePreferences.get<string>(
+  "viewMode",
   defaultDisplay,
 );
 // A default display that draws its whole interface (no table chrome, hence no
@@ -338,30 +349,24 @@ const activeDisplayComponent = computed<Component | string | undefined>(() => {
   return STATIC_DISPLAY_COMPONENTS[id];
 });
 
-const kanbanGroupBy = ref<string>(
-  getPreference<string>(
-    getTablePreferenceKey("kanbanGroupBy"),
-    kanbanOptions?.groupByField ?? "",
-  ),
-);
+const defaultKanbanGroupBy = kanbanOptions?.groupByField ?? "";
+const kanbanGroupBy = ref<string>(defaultKanbanGroupBy);
 // A saved preference may point to a column that no longer exists or is no
 // longer eligible after a backend config change.
-if (
-  kanbanOptions &&
-  !kanbanEligibleColumns.some((c) => c.accessorKey === kanbanGroupBy.value)
-) {
-  kanbanGroupBy.value = kanbanOptions.groupByField;
-}
+tablePreferences.restore(
+  "kanbanGroupBy",
+  kanbanGroupBy,
+  (field) =>
+    !kanbanOptions ||
+    kanbanEligibleColumns.some((c) => c.accessorKey === field),
+);
 
 const DEFAULT_DENSITY = "default";
 // The module's density is the default; the user's pick in the ⋯ menu is kept
 // with the rest of the table's state.
-const density = ref<"default" | "compact">(
-  getPreference(
-    getTablePreferenceKey("density"),
-    props.density ?? DEFAULT_DENSITY,
-  ),
-);
+const defaultDensity = props.density ?? DEFAULT_DENSITY;
+const density = ref<"default" | "compact">(defaultDensity);
+tablePreferences.restore("density", density);
 
 const DEFAULT_PAGE_SIZE = 10;
 const DEFAULT_PAGINATION: PaginationState = {
@@ -406,8 +411,7 @@ const routeParamHiddenFilters = computed<TableFilter[]>(() => {
 // A hidden filter's value changed with the URL, in place or through a
 // remount: the page reached among the previous rows lists from page 1.
 const paginationState = usePersistedPagination({
-  preferences: { getPreference, setPreference },
-  preferenceKey: getTablePreferenceKey,
+  preferences: tablePreferences,
   defaults: DEFAULT_PAGINATION,
   scope: () => [queryParamHiddenFilters.value, routeParamHiddenFilters.value],
 });
@@ -449,18 +453,14 @@ const groupedGroupByOptions = groupedOptions
         value: column.accessorKey,
       }))
   : [];
-const groupedGroupBy = ref<string>(
-  getPreference<string>(
-    getTablePreferenceKey("groupedGroupBy"),
-    groupedOptions?.groupByField ?? "",
-  ),
+const defaultGroupedGroupBy = groupedOptions?.groupByField ?? "";
+const groupedGroupBy = ref<string>(defaultGroupedGroupBy);
+tablePreferences.restore(
+  "groupedGroupBy",
+  groupedGroupBy,
+  (field) =>
+    !groupedOptions || groupedGroupByOptions.some((o) => o.value === field),
 );
-if (
-  groupedOptions &&
-  !groupedGroupByOptions.some((o) => o.value === groupedGroupBy.value)
-) {
-  groupedGroupBy.value = groupedOptions.groupByField;
-}
 const activeGroupedOptions = computed<TableViewGroupedConfig | undefined>(
   () =>
     groupedOptions &&
@@ -487,19 +487,14 @@ const defaultSortKind = tableDefaultSort
     )
   : undefined;
 const sorting = ref<SortingState>(
-  sanitizeSorting(
-    getPreference<SortingState>(
-      getTablePreferenceKey("sorting"),
-      defaultSortState,
-    ),
+  sortingOrDefault(
+    tablePreferences.get<SortingState>("sorting", defaultSortState),
     declaredSortableIds,
+    defaultSortState,
   ),
 );
 
-const savedFilters = getPreference<TableFilter[]>(
-  getTablePreferenceKey("columnFilters"),
-  [],
-);
+const savedFilters = tablePreferences.get<TableFilter[]>("columnFilters", []);
 
 const buildPinnedFilters = (): TableFilter[] =>
   (defaultFilters || []).map((def) => {
@@ -521,26 +516,17 @@ const initialFilters = [...buildPinnedFilters(), ...manualFilters];
 
 const columnFilters = ref<TableFilter[]>(initialFilters);
 const columnVisibility = ref<VisibilityState>(
-  getPreference<VisibilityState>(
-    getTablePreferenceKey("columnVisibility"),
-    initialVisibility,
-  ),
-);
-const columnSizing = ref<ColumnSizingState>(
-  getPreference<ColumnSizingState>(getTablePreferenceKey("columnSizing"), {}),
-);
-const columnOrder = ref<string[]>(
-  getPreference<string[]>(getTablePreferenceKey("columnOrder"), []),
+  tablePreferences.get<VisibilityState>("columnVisibility", initialVisibility),
 );
+const columnSizing = ref<ColumnSizingState>({});
+tablePreferences.restore("columnSizing", columnSizing);
+const columnOrder = ref<string[]>([]);
+tablePreferences.restore("columnOrder", columnOrder, Array.isArray);
 const hasEmptyDefaultFilter = (defaultFilters || []).some(
   (f) => f.value === undefined || f.value === null || f.value === "",
 );
-const filtersRowOpen = ref<boolean>(
-  getPreference<boolean>(
-    getTablePreferenceKey("filtersOpen"),
-    hasEmptyDefaultFilter,
-  ),
-);
+const filtersRowOpen = ref<boolean>(hasEmptyDefaultFilter);
+tablePreferences.restore("filtersOpen", filtersRowOpen);
 const globalFilter = shallowRef<string>();
 const globalFilterDebounced = refDebounced(
   globalFilter,
@@ -595,7 +581,7 @@ const {
     density,
     pagination: paginationState,
   },
-  preferenceKey: getTablePreferenceKey,
+  preferences: tablePreferences,
   urlScope,
 });
 
@@ -607,8 +593,7 @@ const TAB_URL_KEY = "tab";
 const urlTab = readTableUrlKey(useDmsRoute().query, urlScope, TAB_URL_KEY);
 // A tab named by the URL wins over the one kept from the last visit.
 const activeTabId = ref<string>(
-  urlTab.value ??
-    getPreference<string>(getTablePreferenceKey("activeTab"), ALL_TAB_ID),
+  urlTab.value ?? tablePreferences.get<string>("activeTab", ALL_TAB_ID),
 );
 
 interface ResolvedTab {
@@ -677,6 +662,8 @@ const tableRows = useTableRows<T>({
     routeParams: props.routeParams,
     routeQuery: route.query as Record<string, unknown>,
   }),
+  // Groups keep their rows together: the grouped display pins nothing.
+  pinnedRows: () => (isGroupedDisplay.value ? undefined : props.pinnedRows),
 });
 // Quick filters: dropdowns of the toolbar over a column's values (a select's
 // items, a boolean, the rows a relation points to), writing that column's
@@ -822,12 +809,26 @@ const archiveQuery = computed(() =>
   archiveMode ? { showArchived: showArchived.value } : {},
 );
 
+// The row a side panel has open, which the grid highlights.
+const rowSidePanel = useRowSidePanelContent();
+const rowSidePanelOwner = rowSidePanelOwnerKey(pageId!, componentId!);
+const openRowId = computed(() =>
+  rowSidePanel.value?.ownerKey === rowSidePanelOwner
+    ? rowSidePanel.value.rowKey
+    : undefined,
+);
+
 // The gate is set up with the other refresh triggers below; the hold only
 // reads it once the table is on screen.
+const tableRoot = useTemplateRef<ComponentPublicInstance>("tableRoot");
 const liveHold = useTableLiveHold({
-  isEnabled: !!props.liveHold,
+  liveHold: props.liveHold,
   isSource: tableRows.isSource,
   gate: () => liveGate,
+  signals: {
+    isRowOpen: () => openRowId.value !== undefined,
+    tableElement: () => tableRoot.value?.$el ?? null,
+  },
 });
 
 const { data, status, error, refresh } = await useTableListData<T>({
@@ -881,18 +882,27 @@ watch(listLoadError, (message) => {
 });
 
 // Whatever sets the sort (a header, the sort menu, a pasted table config), the
-// route only ever receives a sort it accepts. A new order lists from page 1:
+// route only ever receives a sort it accepts, and a cleared sort goes back to
+// the default one rather than being remembered empty. A new order lists from page 1:
 // the page reached in the previous order shows unrelated rows in the new one.
 // Synchronous, so the list is queried once, with both changes.
 watch(
   sorting,
   (next, previous) => {
-    const sanitized = sanitizeSorting(next, sortableIds.value);
+    const sanitized = sortingOrDefault(
+      next,
+      sortableIds.value,
+      defaultSortState,
+    );
     if (!isSameSorting(sanitized, next)) {
       sorting.value = sanitized;
       return;
     }
-    const before = sanitizeSorting(previous, sortableIds.value);
+    const before = sortingOrDefault(
+      previous,
+      sortableIds.value,
+      defaultSortState,
+    );
     if (
       !isSameSorting(sanitized, before) &&
       paginationState.value.pageIndex !== 0
@@ -1238,6 +1248,7 @@ const {
   handleCustomButton,
   handleCustomRowAction,
   handleBulkCustomAction,
+  handleMissingRow,
   runConfirmedBuiltIn,
 } = useTableRowActions<T>({
   api: $authFetch,
@@ -1668,25 +1679,17 @@ const openRecordFromUrl = async () => {
   const id = deepLinkAction ? readRecordId(route.query, urlScope) : undefined;
   if (!deepLinkAction || !id) return;
   await until(isListLoading).toBe(false);
-  const row = await resolveDeepLinkedRow(id, {
+  const { row, isMissing } = await resolveDeepLinkedRow(id, {
     listed: shownResults.value ?? undefined,
     idOf: getRowId,
     getRow: tableRows.getRow,
   });
   if (row) handleCustomRowAction(deepLinkAction, row as Data);
+  else if (isMissing) handleMissingRow(deepLinkAction, id);
 };
 
 const selectedIds = computed(() => selectedRowIds(rowSelect.value));
 
-// The row a side panel has open, which the grid highlights.
-const rowSidePanel = useRowSidePanelContent();
-const rowSidePanelOwner = rowSidePanelOwnerKey(pageId!, componentId!);
-const openRowId = computed(() =>
-  rowSidePanel.value?.ownerKey === rowSidePanelOwner
-    ? rowSidePanel.value.rowKey
-    : undefined,
-);
-
 const isRowActionEnabled = (
   config: boolean | RowActionConfig | undefined,
   item: T,
@@ -1922,24 +1925,25 @@ defineShortcuts(
   }),
 );
 
-const tableStatePreferences = {
-  sorting,
-  columnFilters: columnFilters,
-  columnVisibility,
-  filtersOpen: filtersRowOpen,
-  activeTab: activeTabId,
-  viewMode: activeDisplayId,
-  columnOrder,
-  kanbanGroupBy,
-  groupedGroupBy,
-  density,
-} as const;
-
-Object.entries(tableStatePreferences).forEach(([key, ref]) => {
+// Each kept field with its default: a value back to it is forgotten.
+const tableStatePreferences: TableStatePreference[] = [
+  ["sorting", sorting, defaultSortState],
+  ["columnFilters", columnFilters, []],
+  ["columnVisibility", columnVisibility, initialVisibility],
+  ["filtersOpen", filtersRowOpen, hasEmptyDefaultFilter],
+  ["activeTab", activeTabId, ALL_TAB_ID],
+  ["viewMode", activeDisplayId, defaultDisplay],
+  ["columnOrder", columnOrder, []],
+  ["kanbanGroupBy", kanbanGroupBy, defaultKanbanGroupBy],
+  ["groupedGroupBy", groupedGroupBy, defaultGroupedGroupBy],
+  ["density", density, defaultDensity],
+];
+
+tableStatePreferences.forEach(([field, state, defaultValue]) => {
   watch(
-    ref,
+    state,
     (newValue) => {
-      setPreference(getTablePreferenceKey(key), newValue);
+      tablePreferences.set(field, newValue, defaultValue);
     },
     { deep: true },
   );
@@ -1951,7 +1955,7 @@ const COLUMN_SIZING_PERSIST_DEBOUNCE_MS = 500;
 let pendingColumnSizingWrite = false;
 
 const persistColumnSizing = () => {
-  setPreference(getTablePreferenceKey("columnSizing"), columnSizing.value);
+  tablePreferences.set("columnSizing", columnSizing.value, {});
   pendingColumnSizingWrite = false;
 };
 
@@ -2030,6 +2034,7 @@ onMounted(() => {
 
 <template>
   <UTable
+    ref="tableRoot"
     v-bind="tableProps"
     v-model:pagination="paginationState"
     v-model:global-filter="globalFilter"
@@ -2053,6 +2058,7 @@ onMounted(() => {
     :reorder="reorderState"
     :views-placement="viewsLayout === 'menu' ? 'header' : 'band'"
     :search-placeholder="props.searchPlaceholder"
+    :search-shortcut="props.searchShortcut"
     :quick-filters="resolvedQuickFilters"
     :footer="resolvedFooter"
     :empty-states="props.emptyStates"

package/frontend-vue/layers/dms-ui/app/components/top-list/TopListCard.vue

@@ -22,6 +22,7 @@ import type {
   ValuePrecision,
 } from "../../composables/chart/types";
 import type { DefaultComponentProps } from "../../../../dms-core/app/types/component";
+import { useComposedText } from "../../../../dms-core/app/composables/translation/useComposedText";
 
 interface Props extends DefaultComponentProps {
   title: string;
@@ -32,6 +33,8 @@ interface Props extends DefaultComponentProps {
   valueFormat?: ValueFormat;
   currencyCode?: string;
   valuePrecision?: ValuePrecision;
+  /** Unit after each formatted value, space included (" ms"); `$` key or literal. */
+  valueSuffix?: string;
   showRank?: boolean;
   highlightTopN?: number;
   rankColor?: UiColor;
@@ -100,6 +103,7 @@ const props = withDefaults(defineProps<Props>(), {
 
 const { locale, t } = useI18n();
 const { processI18n } = useTranslation();
+const { processText } = useComposedText();
 useComponentEvent(props.componentId);
 const { state: watchState } = useWatch(
   props.watchActions || [],
@@ -167,14 +171,20 @@ function barClass(index: number): string {
   return `${rankFillClass.value} ${QUIET_BAR_OPACITY_CLASS}`;
 }
 
+const valueSuffixText = computed(() =>
+  props.valueSuffix ? processI18n(props.valueSuffix) : "",
+);
+
 function formattedValue(item: TopListItem): string {
-  return formatValue(
+  if (item.valueLabel) return processText(item.valueLabel);
+  const formatted = formatValue(
     item.value,
     props.valueFormat,
     locale.value,
     props.currencyCode,
     props.valuePrecision,
   );
+  return `${formatted}${valueSuffixText.value}`;
 }
 
 function sparklineAccentFor(item: TopListItem): string {

package/frontend-vue/layers/dms-ui/app/composables/chart/types.ts

@@ -106,6 +106,8 @@ export interface TopListItem {
   title: BlockText;
   description?: BlockText;
   value: number;
+  /** The value as written, in place of the formatted one. */
+  valueLabel?: BlockText;
   delta?: number | null;
   sparkline?: number[];
   icon?: string;

package/frontend-vue/layers/dms-ui/app/composables/chart/useChartFetch.ts

@@ -16,6 +16,7 @@ import {
   resolveUrlVariables,
 } from "../../build/utils/urlVariables";
 import { useRefreshTriggers } from "../../build/composables/blocks/useRefreshTriggers";
+import { readFetchNotFound } from "../../build/utils/fetchNotFound";
 
 export interface UseChartFetchOptions<T> {
   /**
@@ -41,6 +42,10 @@ export interface UseChartFetchReturn<T> {
    * (period, watched state, realtime event) until the new answer lands.
    */
   isLoading: Ref<boolean>;
+  /**
+   * Why the last request failed. A 404 also clears `data`: read it with
+   * `readFetchNotFound` to draw a not-found state rather than a load error.
+   */
   error: Ref<unknown>;
   refresh: () => Promise<void>;
 }
@@ -111,7 +116,12 @@ async function runFetch<T>(
     data.value = response;
   } catch (err) {
     if (runner.activeAbort !== controller) return;
-    if ((err as { name?: string })?.name !== "AbortError") error.value = err;
+    if ((err as { name?: string })?.name === "AbortError") return;
+    error.value = err;
+    // A 404 says what the block showed is gone (another tab deleted it, the
+    // URL now names another record): its last values must not stay on screen
+    // as if they still belonged to it. Any other failure keeps them.
+    if (readFetchNotFound(err)) data.value = null;
   } finally {
     // A request a newer one superseded leaves the loading flag to that one:
     // clearing it here would show the empty state while the newer answer is

package/frontend-vue/layers/dms-ui/app/composables/confirm/types.ts

@@ -24,7 +24,14 @@ export type ConfirmValues = Record<string, unknown>;
  * whose texts are already resolved, plus what only a caller in the browser
  * can give (render functions, handlers).
  */
-export interface ConfirmOptions extends Omit<ConfirmDialog, "params" | "icon"> {
+export interface ConfirmOptions
+  extends Omit<ConfirmDialog, "params" | "icon" | "secondaryAction"> {
+  /**
+   * A button next to cancel and confirm that leaves the dialog open (a
+   * download before removing): its `run` is awaited, the button loading,
+   * and a rejection is shown in the dialog's alert.
+   */
+  secondaryAction?: ConfirmSecondaryAction;
   /**
    * The button focused on open (`"cancel"` for a dialog whose safe answer
    * is to stay); left out, the dialog's first focusable element.
@@ -63,6 +70,13 @@ export interface ConfirmOptions extends Omit<ConfirmDialog, "params" | "icon"> {
   ) => Promise<void | boolean | ConfirmPartialOutcome>;
 }
 
+/** A secondary button of the confirm modal: its text resolved, its handler. */
+export interface ConfirmSecondaryAction {
+  label: string;
+  icon?: string;
+  run: () => Promise<void> | void;
+}
+
 /** A summary shown in the confirm modal's alert: a title and its detail. */
 export interface ConfirmNotice {
   title: string;