@antelopejs/dms 0.7.8 → 0.7.10

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

@@ -0,0 +1,149 @@
+import { getCurrentInstance, onMounted, type Ref } from "vue";
+import {
+  type CompactTableEntry,
+  decodeServerField,
+  encodeServerField,
+  isDefaultValue,
+  isServerTableField,
+  type LocalTableField,
+  readLocalTableEntry,
+  SERVER_TABLE_FIELDS,
+  type ServerTableField,
+  type TableField,
+  TABLES_PREFERENCE_KEY,
+  tablePreferenceId,
+  writeLocalTableEntry,
+} from "#dms-core/app/build/composables/user/tablePreferences";
+
+/**
+ * The preferences of one table view. A field the server render needs
+ * (`ServerTableField`) is read in setup from the cookie, on the server too; a
+ * field only the browser draws (`LocalTableField`) reads as its default in
+ * setup, on both sides, and is restored from `localStorage` once mounted.
+ */
+export interface TablePreferences {
+  /** A server field's stored value, else `defaultValue`; a local field's default. */
+  get: <T>(field: TableField, defaultValue: T) => T;
+  /** Stores `value`, or forgets the field when `value` is its default. */
+  set: <T>(field: TableField, value: T, defaultValue: T) => void;
+  /**
+   * Sets `state` to the local field's stored value once the table is
+   * mounted, unless `isValid` refuses it: the server and the hydrating
+   * client render the default, so no mismatch.
+   */
+  restore: <T>(
+    field: LocalTableField,
+    state: Ref<T>,
+    isValid?: (value: T) => boolean,
+  ) => void;
+}
+
+interface PendingRestore {
+  field: LocalTableField;
+  apply: (value: unknown) => void;
+}
+
+/** The table's entry in the cookie: `tables.<id>`, its server fields. */
+function useServerTableEntry(id: string) {
+  const { getPreference, setPreference, removePreference } = usePreferences();
+  const path = `${TABLES_PREFERENCE_KEY}.${id}`;
+
+  const entry = (): CompactTableEntry | undefined =>
+    getPreference<CompactTableEntry | undefined>(path, undefined);
+  const tables = () =>
+    getPreference<Record<string, unknown>>(TABLES_PREFERENCE_KEY, {});
+
+  // The last entry takes the collection with it: no empty branch left over.
+  const forget = () => {
+    const isLastEntry = Object.keys(tables()).every((key) => key === id);
+    removePreference(isLastEntry ? TABLES_PREFERENCE_KEY : path);
+  };
+
+  const set = (
+    field: ServerTableField,
+    value: unknown,
+    defaultValue: unknown,
+  ) => {
+    const { key } = SERVER_TABLE_FIELDS[field];
+    const next = { ...entry() };
+    const encoded = encodeServerField(field, value, defaultValue);
+    if (JSON.stringify(next[key]) === JSON.stringify(encoded)) return;
+    if (encoded === undefined) Reflect.deleteProperty(next, key);
+    else next[key] = encoded;
+    if (Object.keys(next).length === 0) forget();
+    else setPreference(path, next);
+  };
+
+  // The table used last is evicted last: opening it counts as a write.
+  const markUsed = () => {
+    const current = entry();
+    if (current && Object.keys(tables()).at(-1) !== id) {
+      setPreference(path, current);
+    }
+  };
+
+  return { entry, set, markUsed };
+}
+
+const setLocalField = (
+  id: string,
+  field: LocalTableField,
+  value: unknown,
+  defaultValue: unknown,
+) => {
+  const entry = readLocalTableEntry(id);
+  if (isDefaultValue(value, defaultValue)) {
+    Reflect.deleteProperty(entry, field);
+  } else {
+    entry[field] = JSON.parse(JSON.stringify(value));
+  }
+  writeLocalTableEntry(id, entry);
+};
+
+const restoreLocalFields = (id: string, pending: PendingRestore[]) => {
+  const stored = readLocalTableEntry(id);
+  pending
+    .filter(({ field }) => stored[field] !== undefined)
+    .forEach(({ field, apply }) => apply(stored[field]));
+};
+
+/**
+ * The preferences of the table view `componentId` on page `pageId`, under a
+ * short hash of both: the cookie entry `tables.<id>`, and the
+ * `localStorage` key `dms-table-preferences:v1:<id>`.
+ */
+export function useTablePreferences(
+  componentId: string | undefined,
+  pageId: string | undefined,
+): TablePreferences {
+  const id = tablePreferenceId(componentId ?? "", pageId ?? "");
+  const server = useServerTableEntry(id);
+  const pending: PendingRestore[] = [];
+
+  if (getCurrentInstance()) {
+    onMounted(() => {
+      restoreLocalFields(id, pending);
+      server.markUsed();
+    });
+  }
+
+  return {
+    get: (field, defaultValue) =>
+      isServerTableField(field)
+        ? decodeServerField(field, server.entry(), defaultValue)
+        : defaultValue,
+    set: (field, value, defaultValue) =>
+      isServerTableField(field)
+        ? server.set(field, value, defaultValue)
+        : setLocalField(id, field, value, defaultValue),
+    restore: (field, state, isValid) => {
+      pending.push({
+        field,
+        apply: (value) => {
+          const restored = value as typeof state.value;
+          if (!isValid || isValid(restored)) state.value = restored;
+        },
+      });
+    },
+  };
+}

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

@@ -9,6 +9,8 @@ import {
   type ReplaceUrlVariablesContext,
   resolveUrlVariables,
 } from "../../utils/urlVariables";
+import type { RowActionRule } from "#dms-core/app/types/row-action";
+import { pinRows } from "./utils/pinnedRows";
 import {
   appendPeriodToUrl,
   usePeriodScope,
@@ -34,6 +36,11 @@ export interface TableRowsOptions {
    * read again on every request.
    */
   route?: () => ReplaceUrlVariablesContext;
+  /**
+   * The rows listed first whatever the sort (backend `pinnedRows`), read on
+   * every request: `undefined` while the display pins nothing.
+   */
+  pinnedRows?: () => RowActionRule | undefined;
 }
 
 const FILTER_PREFIX = "filter_";
@@ -94,13 +101,15 @@ const compareValues = (a: unknown, b: unknown): number => {
 /**
  * The rows the browser narrows, sorts and pages itself, for what the source
  * route left to it: a search over the listed columns' text, the sort on one
- * column, the page.
+ * column, the page. The pinned rows lead before the page is cut, so they
+ * open the first one.
  */
 export function processSourceRows<T extends Record<string, unknown>>(
   rows: T[],
   query: Query,
   capabilities: SourceCapabilities,
   columns: TableViewColumn[],
+  pinnedRows?: RowActionRule,
 ): TableViewListResponse<T> {
   let processed = rows;
   const search = typeof query.search === "string" ? query.search.trim() : "";
@@ -120,6 +129,7 @@ export function processSourceRows<T extends Record<string, unknown>>(
       (a, b) => direction * compareValues(get(a, sortKey), get(b, sortKey)),
     );
   }
+  processed = pinRows(processed, pinnedRows);
   const offset = Number(query.offset) || 0;
   const limit = Number(query.limit) || processed.length;
   return {
@@ -151,7 +161,8 @@ function emptySourcePage<T>(query: Query): TableViewListResponse<T> {
  * source's `periodScope` adds the period of its selector to the URL, like a
  * chart's; until that selector registers, nothing is requested and the list
  * answers `null`, which the table draws as its skeleton. `sourceUrl` is the
- * URL requested, for the caller to list again when it changes.
+ * URL requested, for the caller to list again when it changes. The rows
+ * `pinnedRows` accepts lead each list answered.
  */
 export function useTableRows<T extends Record<string, unknown>>(
   options: TableRowsOptions,
@@ -189,13 +200,26 @@ export function useTableRows<T extends Record<string, unknown>>(
         limit: Number(query.limit) || 0,
       };
     }
-    return processSourceRows(response.results, query, capabilities, columns);
+    return processSourceRows(
+      response.results,
+      query,
+      capabilities,
+      columns,
+      options.pinnedRows?.(),
+    );
   };
 
-  const list = (query: Query): Promise<TableViewListResponse<T> | null> =>
-    source
-      ? listFromSource(source, query)
-      : api<TableViewListResponse<T>>(`${location}/list`, { query });
+  const withPinnedRows = (
+    page: TableViewListResponse<T> | null,
+  ): TableViewListResponse<T> | null =>
+    page && { ...page, results: pinRows(page.results, options.pinnedRows?.()) };
+
+  const list = async (query: Query): Promise<TableViewListResponse<T> | null> =>
+    withPinnedRows(
+      source
+        ? await listFromSource(source, query)
+        : await api<TableViewListResponse<T>>(`${location}/list`, { query }),
+    );
 
   // A source answers its totals one list at a time.
   const countBatch = async (
@@ -242,5 +266,12 @@ export function useTableRows<T extends Record<string, unknown>>(
       ? getSourceRow(source, id)
       : api<T>(`${location}/get`, { query: { id } });
 
-  return { isSource: !!source, sourceUrl, list, countBatch, getRow };
+  return {
+    isSource: !!source,
+    sourceUrl,
+    isPeriodPending,
+    list,
+    countBatch,
+    getRow,
+  };
 }

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

@@ -122,6 +122,7 @@ export const useTableViewConfig = <T extends Data>(
     caption: processI18n(config.caption ?? ""),
     maxHeight: config.maxHeight,
     rowIdKey: config.rowIdKey,
+    labelKey: config.labelKey,
     rowActions: config.rowActions,
     rowClick: config.rowClick,
     customNavItems: config.customNavItems,

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

@@ -801,17 +801,21 @@ export const useTableRowActions = <T extends Data>(
     await proceed();
   };
 
-  const { handleCustomButton, handleCustomRowAction, handleBulkCustomAction } =
-    useActionTargets({
-      api: config.api,
-      pageId: config.pageId,
-      componentId: config.componentId,
-      refreshCallback: config.refreshCallback,
-      handleApiError,
-      rowNavigation: config.rowNavigation,
-      recordScope: config.recordScope,
-      rowIdKey: config.rowIdKey,
-    });
+  const {
+    handleCustomButton,
+    handleCustomRowAction,
+    handleBulkCustomAction,
+    handleMissingRow,
+  } = useActionTargets({
+    api: config.api,
+    pageId: config.pageId,
+    componentId: config.componentId,
+    refreshCallback: config.refreshCallback,
+    handleApiError,
+    rowNavigation: config.rowNavigation,
+    recordScope: config.recordScope,
+    rowIdKey: config.rowIdKey,
+  });
 
   return {
     createFormContainer,
@@ -826,6 +830,7 @@ export const useTableRowActions = <T extends Data>(
     handleCustomButton,
     handleCustomRowAction,
     handleBulkCustomAction,
+    handleMissingRow,
     handleApiError,
     runConfirmedBuiltIn,
   };

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

@@ -23,6 +23,7 @@ import {
   type UserTableView,
   viewSnapshot,
 } from "./utils/views";
+import type { TablePreferences } from "./useTablePreferences";
 
 /** The table's state a view reads and sets. */
 export interface TableViewsState {
@@ -40,8 +41,8 @@ export interface TableViewsOptions {
   views: TableViewViewsConfig | undefined;
   defaults: TableStateDefaults;
   state: TableViewsState;
-  /** Preference key of the table, for one of its settings. */
-  preferenceKey: (suffix: string) => string;
+  /** The table's preferences (`useTablePreferences`). */
+  preferences: TablePreferences;
   urlScope: TableUrlScope;
 }
 
@@ -52,8 +53,6 @@ export interface ResolvedTableView extends TableViewViewConfig {
 }
 
 export const VIEW_URL_KEY = "view";
-const ACTIVE_VIEW_PREFERENCE = "activeView";
-const USER_VIEWS_PREFERENCE = "userViews";
 const NO_VIEW = "";
 const VIEW_NAME_FIELD = "label";
 
@@ -64,8 +63,7 @@ const VIEW_NAME_FIELD = "label";
  * 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 { views, defaults, state, preferences, urlScope } = options;
   const { user } = useUserSession();
   const { t } = useI18n();
   const { processI18n } = useTranslation();
@@ -74,9 +72,9 @@ export function useTableViews(options: TableViewsOptions) {
   const route = useDmsRoute();
 
   const userId = computed(() => user.value?._id as string | undefined);
-  const storedUserViews = ref<UserTableView[]>(
-    getPreference<UserTableView[]>(preferenceKey(USER_VIEWS_PREFERENCE), []),
-  );
+  // Kept in the browser: none on the server, restored once mounted.
+  const storedUserViews = ref<UserTableView[]>([]);
+  preferences.restore("userViews", storedUserViews, Array.isArray);
   const ownUserViews = computed(() =>
     views?.userViews && userId.value
       ? storedUserViews.value.filter((view) => view.ownerId === userId.value)
@@ -132,25 +130,50 @@ export function useTableViews(options: TableViewsOptions) {
 
   // 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).
+  // 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.
   const urlView = readTableUrlKey(route.query, urlScope, VIEW_URL_KEY);
-  const persistedViewId = getPreference<string | undefined>(
-    preferenceKey(ACTIVE_VIEW_PREFERENCE),
+  const persistedViewId = preferences.get<string | undefined>(
+    "activeView",
     undefined,
   );
   let isUrlViewUnavailable = false;
+  let isUrlViewPending = false;
+  let isOpenedOnArrival = false;
   if (urlView.value && findView(urlView.value)) {
     openView(urlView.value);
+    isOpenedOnArrival = true;
   } else if (urlView.value) {
-    isUrlViewUnavailable = true;
-    openView(views?.defaultView);
+    isUrlViewPending = true;
   } else if (persistedViewId === undefined) {
     if (views?.defaultView) openView(views.defaultView);
+    isOpenedOnArrival = !!views?.defaultView;
   } else {
     activeViewId.value = findView(persistedViewId)?.id;
   }
 
+  // The browser-only state (order, density) is restored over the view opened
+  // in setup: the view's own wins, as it did when everything was read there.
+  const reapplyBrowserState = () => {
+    const snapshot = viewSnapshot(activeView.value, defaults);
+    state.columnOrder.value = snapshot.order;
+    state.density.value = snapshot.density;
+  };
+
+  const arriveOnceMounted = () => {
+    if (isUrlViewPending) {
+      isUrlViewUnavailable = !findView(urlView.value);
+      openView(isUrlViewUnavailable ? views?.defaultView : urlView.value);
+    } else if (isOpenedOnArrival) {
+      reapplyBrowserState();
+    } else if (persistedViewId && !activeViewId.value) {
+      activeViewId.value = findView(persistedViewId)?.id;
+    }
+  };
+
   onMounted(() => {
+    arriveOnceMounted();
     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}=".`,
@@ -166,7 +189,7 @@ export function useTableViews(options: TableViewsOptions) {
   });
 
   watch(activeViewId, (id) => {
-    setPreference(preferenceKey(ACTIVE_VIEW_PREFERENCE), id ?? NO_VIEW);
+    preferences.set<string | undefined>("activeView", id ?? NO_VIEW, undefined);
   });
 
   const isModified = computed(() => {
@@ -181,7 +204,7 @@ export function useTableViews(options: TableViewsOptions) {
 
   const writeUserViews = (next: UserTableView[]) => {
     storedUserViews.value = next;
-    setPreference(preferenceKey(USER_VIEWS_PREFERENCE), next);
+    preferences.set("userViews", next, []);
   };
 
   /** Back to the open view's own state. */

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

@@ -0,0 +1,29 @@
+import type { RowActionRule } from "#dms-core/app/types/row-action";
+import { evaluateRowActionRule } from "#dms-core/app/utils/row-action-rule-evaluator";
+
+interface PartitionedRows<T> {
+  pinned: T[];
+  rest: T[];
+}
+
+/**
+ * The rows a table view's `pinnedRows` accepts first, then the others, each
+ * in the order they came in: the sort keeps ordering both, it no longer
+ * decides which rows lead.
+ */
+export function pinRows<T extends Record<string, unknown>>(
+  rows: T[],
+  pinnedRows: RowActionRule | undefined,
+): T[] {
+  if (!pinnedRows) return rows;
+  const { pinned, rest } = rows.reduce<PartitionedRows<T>>(
+    (parts, row) => {
+      (evaluateRowActionRule(pinnedRows, row) ? parts.pinned : parts.rest).push(
+        row,
+      );
+      return parts;
+    },
+    { pinned: [], rest: [] },
+  );
+  return pinned.length === 0 ? rows : [...pinned, ...rest];
+}

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

@@ -1,5 +1,6 @@
 import type { CustomRowAction } from "../../../../types/row-action";
 import { readTableUrlKey, type TableUrlScope } from "./views";
+import { readFetchNotFound } from "../../../utils/fetchNotFound";
 
 /** Query key of the row a `deepLink` action has open. */
 export const RECORD_URL_KEY = "record";
@@ -76,16 +77,28 @@ export interface DeepLinkedRowSource<T> {
   getRow: (id: string) => Promise<T | undefined>;
 }
 
+/** What a deep link found: its row, or a route answering it is gone. */
+export interface DeepLinkedRow<T> {
+  row?: T;
+  /** The route answered 404: the row the link names no longer exists. */
+  isMissing: boolean;
+}
+
 /**
  * The row a deep link names: the listed one, else the one read by id — a row
- * beyond the first page. A row the route cannot answer (gone, a 404) opens
- * nothing.
+ * beyond the first page. A route answering 404 marks it missing; any other
+ * failure (a refusal, the network) or no route at all finds nothing.
  */
 export async function resolveDeepLinkedRow<T>(
   id: string,
   source: DeepLinkedRowSource<T>,
-): Promise<T | undefined> {
+): Promise<DeepLinkedRow<T>> {
   const listed = source.listed?.find((row) => source.idOf(row) === id);
-  if (listed) return listed;
-  return source.getRow(id).catch(() => undefined);
+  if (listed) return { row: listed, isMissing: false };
+  try {
+    const row = await source.getRow(id);
+    return { row: row ?? undefined, isMissing: false };
+  } catch (error: unknown) {
+    return { isMissing: readFetchNotFound(error) !== null };
+  }
 }

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

@@ -54,6 +54,23 @@ export const sanitizeSorting = (
   return [{ id: first.id, desc: first.desc === true }];
 };
 
+/**
+ * The sort the list route can serve ({@link sanitizeSorting}), or the
+ * default sort when that leaves none: a sort the user cleared, or one naming
+ * a column gone, goes back to the table's default rather than to the
+ * database's natural order — and is remembered so.
+ */
+export const sortingOrDefault = (
+  sorting: SortingState | null | undefined,
+  sortable: ReadonlySet<string>,
+  defaultSorting: SortingState,
+): SortingState => {
+  const sanitized = sanitizeSorting(sorting, sortable);
+  return sanitized.length > 0
+    ? sanitized
+    : sanitizeSorting(defaultSorting, sortable);
+};
+
 /** Whether two sorting states request the same order. */
 export const isSameSorting = (a: SortingState, b: SortingState): boolean =>
   a.length === b.length &&

package/frontend-vue/layers/dms-ui/app/build/utils/fetchNotFound.ts

@@ -0,0 +1,79 @@
+import { HTTP_NOT_FOUND } from "../../../../dms-core/app/utils/http-status";
+import type { I18nTranslate } from "#dms-core/app/composables/translation/useTranslation";
+import type { BlockAction } from "../components/blocks/BlockActions.vue";
+import { userFacingText } from "../composables/confirm/actionError";
+import type { Tone } from "../../types/tone";
+
+/** Translation key of the not-found title, shared by blocks and guards. */
+export const NOT_FOUND_TITLE_KEY = "dms.blocks.not_found";
+/** Translation key of the not-found hint, when the 404 says nothing usable. */
+export const NOT_FOUND_HINT_KEY = "dms.blocks.not_found_hint";
+
+/** What the body of a 404 may lay over a not-found state. */
+export interface NotFoundEmptyState {
+  title?: string;
+  description?: string;
+  icon?: string;
+  tone?: Tone;
+  actions?: BlockAction[];
+}
+
+/**
+ * What a data source answering 404 says about it, read from the error body:
+ * `{ message?, emptyState? }`, both optional.
+ */
+export interface FetchNotFound {
+  /** The body's `message`: an i18n key or a sentence for the user. */
+  message?: string;
+  /** Laid over the not-found state drawn (title, icon, actions…). */
+  emptyState?: NotFoundEmptyState;
+}
+
+interface FetchFailure {
+  statusCode?: number;
+  status?: number;
+  response?: { status?: number; _data?: unknown };
+  data?: unknown;
+}
+
+const isObject = (value: unknown): value is Record<string, unknown> =>
+  typeof value === "object" && value !== null;
+
+const statusOf = (error: FetchFailure): number | undefined =>
+  error.statusCode ?? error.status ?? error.response?.status;
+
+/**
+ * The not-found answer a failed request carries, or `null` when it failed any
+ * other way (network, refusal, crash): a 404 is the server's final word that
+ * what is read does not exist, not a load error to retry.
+ */
+export function readFetchNotFound(error: unknown): FetchNotFound | null {
+  if (!isObject(error)) return null;
+  const failure = error as FetchFailure;
+  if (statusOf(failure) !== HTTP_NOT_FOUND) return null;
+  const data = failure.data ?? failure.response?._data;
+  const body = isObject(data) ? data : {};
+  return {
+    message: typeof body.message === "string" ? body.message : undefined,
+    emptyState: isObject(body.emptyState)
+      ? (body.emptyState as NotFoundEmptyState)
+      : undefined,
+  };
+}
+
+/**
+ * The default texts of a not-found state, before the 404's `emptyState` is
+ * laid over them: a translated "Not found", and the body's `message` when it
+ * is user-facing, else a translated hint. A block and a `Guard` draw the same.
+ */
+export function notFoundTexts(
+  notFound: FetchNotFound | null | undefined,
+  translate: I18nTranslate,
+): { title: string; description: string } {
+  return {
+    title: translate(NOT_FOUND_TITLE_KEY, {}),
+    description:
+      userFacingText(notFound?.message, translate) ??
+      translate(NOT_FOUND_HINT_KEY, {}),
+  };
+}

package/frontend-vue/layers/dms-ui/app/build/utils/urlVariables.ts

@@ -3,7 +3,8 @@
 // a specific occurrence, `{{params.id:1}}` being the id of the page carrying the
 // table view (see extractRouteParams).
 const PARAM_TOKEN = /\{\{params\.(\w+(?::\d+)?)\}\}/g;
-const QUERY_TOKEN = /\{\{query\.(\w+)\}\}/g;
+// A query key may carry dots and dashes: a period selector writes `<id>.period`.
+const QUERY_TOKEN = /\{\{query\.([\w.-]+)\}\}/g;
 const RESPONSE_TOKEN = /\{\{response\.(\w+)\}\}/g;
 const TOKEN_OPENING = "{{";
 
@@ -118,3 +119,47 @@ export function resolveTextVariables(
   const resolved = fillRouteTokens(text, context, TEXT_ENCODING);
   return hasUrlVariables(resolved) ? undefined : resolved;
 }
+
+// A route token left without a value: `{{params.id}}`, `{{query.workspace}}`.
+const UNRESOLVED_ROUTE_TOKEN = /\{\{(?:params|query)\.\w+(?::\d+)?\}\}/g;
+const UNRESOLVED_ROUTE_VALUE = /^\{\{(?:params|query)\.\w+(?::\d+)?\}\}$/;
+const QUERY_SEPARATOR = "?";
+const FRAGMENT_SEPARATOR = "#";
+const PAIR_SEPARATOR = "&";
+const VALUE_SEPARATOR = "=";
+
+/** The query of a URL without the pairs whose whole value is a token left empty. */
+function dropUnresolvedPairs(search: string): string {
+  return search
+    .split(PAIR_SEPARATOR)
+    .filter((pair) => {
+      const value = pair.slice(pair.indexOf(VALUE_SEPARATOR) + 1);
+      return (
+        !pair.includes(VALUE_SEPARATOR) || !UNRESOLVED_ROUTE_VALUE.test(value)
+      );
+    })
+    .join(PAIR_SEPARATOR);
+}
+
+/**
+ * A link's URL with the `{{params.X}}` / `{{query.X}}` tokens of the page it
+ * sits on filled, for a button that always leads somewhere: a query pair
+ * whose value is a token the page has no value for is left out
+ * (`?workspace={{query.workspace}}` on a page without `?workspace=` leads to
+ * the target's default), any other such token is left empty.
+ */
+export function resolveLinkVariables(
+  url: string,
+  context: ReplaceUrlVariablesContext,
+): string {
+  const filled = replaceUrlVariables(url, context);
+  if (!hasUrlVariables(filled)) return filled;
+  const [beforeFragment = "", ...fragment] = filled.split(FRAGMENT_SEPARATOR);
+  const [path = "", ...search] = beforeFragment.split(QUERY_SEPARATOR);
+  const query = dropUnresolvedPairs(search.join(QUERY_SEPARATOR));
+  const rebuilt = [
+    query ? `${path}${QUERY_SEPARATOR}${query}` : path,
+    ...fragment,
+  ].join(FRAGMENT_SEPARATOR);
+  return rebuilt.replace(UNRESOLVED_ROUTE_TOKEN, "");
+}