@antelopejs/dms 0.9.7 → 0.10.0

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 }));
+}

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

@@ -0,0 +1,308 @@
+import { nextTick } from "vue";
+import {
+  hashText,
+  type TableField,
+} from "#dms-core/app/build/composables/user/tablePreferences";
+import type { QueryParamFilters } from "../../../../composables/table-view/types/config";
+import type { TablePreferences } from "../useTablePreferences";
+import { RECORD_URL_KEY } from "./recordLink";
+import { readTableUrlKey, type TableUrlScope, writeTableUrlKey } from "./views";
+
+/**
+ * The kept fields that decide which rows a table lists: a link that names
+ * part of that state replaces all of it, not only what it names.
+ */
+const LINKED_STATE_FIELDS: ReadonlySet<TableField> = new Set<TableField>([
+  "activeView",
+  "activeTab",
+  "columnFilters",
+  "sorting",
+  "pagination",
+  "paginationScope",
+]);
+
+/**
+ * The listing choices a user makes on a link's table (a view, a tab, a
+ * filter, a sort): the first one makes the state shown their own.
+ */
+const USER_CHOICE_FIELDS: ReadonlySet<TableField> = new Set<TableField>([
+  "activeView",
+  "activeTab",
+  "columnFilters",
+  "sorting",
+]);
+
+const VIEW_URL_KEY = "view";
+const TAB_URL_KEY = "tab";
+
+/**
+ * What `query` names as the table's view: an id, `""` for no view at all
+ * (`?view=`), or `undefined` when it names none.
+ */
+const namedView = (
+  query: Record<string, unknown>,
+  urlScope: TableUrlScope,
+): string | undefined => {
+  const reading = readTableUrlKey(query, urlScope, VIEW_URL_KEY);
+  return reading.isCleared ? "" : reading.value;
+};
+
+/** What the URL a table arrives on may name, and how it was reached. */
+export interface TableLinkArrival {
+  query: Record<string, unknown>;
+  urlScope: TableUrlScope;
+  queryParamFilters: QueryParamFilters | undefined;
+  /** The page was reached through a visit, not loaded or gone back to. */
+  isVisit: boolean;
+  /** The tab kept from the last visit. */
+  rememberedTab: string;
+  /** The URL filters the kept state was chosen under (`urlFilterScope`). */
+  keptLinkScope: string | undefined;
+  /** The link the table last showed, unclaimed by the user (`linkKeyScope`). */
+  shownLink: string | undefined;
+}
+
+const namesUrlFilter = (
+  query: Record<string, unknown>,
+  queryParamFilters: QueryParamFilters | undefined,
+  isNamed: (param: string) => boolean,
+): boolean =>
+  Object.keys(queryParamFilters ?? {}).some(
+    (param) => query[param] !== undefined && isNamed(param),
+  );
+
+/**
+ * The `queryParamFilters` values `query` carries, as one key, or `undefined`
+ * when it carries none: what a kept state chosen under them is tied to.
+ */
+export function urlFilterScope(
+  query: Record<string, unknown>,
+  queryParamFilters: QueryParamFilters | undefined,
+): string | undefined {
+  const values = Object.keys(queryParamFilters ?? {})
+    .filter((param) => query[param] !== undefined)
+    .sort()
+    .map((param) => [param, query[param]]);
+  return values.length > 0 ? hashText(JSON.stringify(values)) : undefined;
+}
+
+/**
+ * What `query` names for the table (its view, tab and row, and the filters
+ * declared in `queryParamFilters`), as one key, or `undefined` when it names
+ * none of them: a URL spelling a key short or prefixed reads the same.
+ */
+export function linkKeyScope(
+  query: Record<string, unknown>,
+  urlScope: TableUrlScope,
+  queryParamFilters: QueryParamFilters | undefined,
+): string | undefined {
+  const named = [
+    [VIEW_URL_KEY, namedView(query, urlScope)],
+    ...[TAB_URL_KEY, RECORD_URL_KEY].map((key) => [
+      key,
+      readTableUrlKey(query, urlScope, key).value,
+    ]),
+  ].filter(([, value]) => value !== undefined);
+  const filters = Object.keys(queryParamFilters ?? {})
+    .filter((param) => query[param] !== undefined)
+    .sort()
+    .map((param) => [`?${param}`, query[param]]);
+  const values = [...named, ...filters];
+  return values.length > 0 ? hashText(JSON.stringify(values)) : undefined;
+}
+
+/**
+ * Whether the table was reached through a link that names what it lists: a
+ * view, a record, a filter declared in `queryParamFilters`, or a tab. Reached
+ * through a visit (a link clicked, a notification), it always is, even when
+ * what it names is what the user left. Loaded in full (a reload) or gone back
+ * to, the URL may be the one the table wrote for the user's own choices: it
+ * is a link again when it is the link the table last showed, and when it
+ * names a view or a record, or a tab or URL filters other than the kept
+ * ones. A server render cannot tell a reload from a URL typed or opened in a
+ * new browser tab, so a full load naming only the kept tab reads as one.
+ */
+export function isLinkedArrival(arrival: TableLinkArrival): boolean {
+  const { query, urlScope, queryParamFilters } = arrival;
+  const linkScope = linkKeyScope(query, urlScope, queryParamFilters);
+  if (linkScope === undefined) return false;
+  if (arrival.isVisit || linkScope === arrival.shownLink) return true;
+  const names = (key: string) => !!readTableUrlKey(query, urlScope, key).value;
+  if (namedView(query, urlScope) !== undefined || names(RECORD_URL_KEY)) {
+    return true;
+  }
+  const filterScope = urlFilterScope(query, queryParamFilters);
+  if (filterScope !== undefined && filterScope !== arrival.keptLinkScope) {
+    return true;
+  }
+  const tab = readTableUrlKey(query, urlScope, TAB_URL_KEY).value;
+  return tab !== undefined && tab !== arrival.rememberedTab;
+}
+
+/**
+ * The table's preferences as a link arrival reads them: the listing state
+ * (`LINKED_STATE_FIELDS`) reads as its defaults, so the link applies over
+ * the table's own default state rather than over the last visit's. The
+ * kept state is only replaced once the user makes the state shown their own
+ * (`linkFollowingPreferences`).
+ */
+export function linkedArrivalPreferences(
+  preferences: TablePreferences,
+): TablePreferences {
+  return {
+    ...preferences,
+    get: (field, defaultValue) =>
+      LINKED_STATE_FIELDS.has(field)
+        ? defaultValue
+        : preferences.get(field, defaultValue),
+  };
+}
+
+/** A visit to the page the table is already shown on. */
+export interface TableLinkVisit {
+  query: Record<string, unknown>;
+  /**
+   * A link pushed on the page (one clicked, a notification): it is followed
+   * even when it names what the table shows.
+   */
+  isLinkClick: boolean;
+  /** The query of the visit the table was last reached through. */
+  previousQuery: Record<string, unknown>;
+  urlScope: TableUrlScope;
+  queryParamFilters: QueryParamFilters | undefined;
+  /** The view and the tab the table shows. */
+  activeView: string | undefined;
+  activeTab: string;
+  canOpenView: (id: string) => boolean;
+  canOpenTab: (id: string) => boolean;
+}
+
+/**
+ * Whether a visit that keeps the table mounted (a link to the page already
+ * shown, back and forward) is a link to follow as an arrival would. A link
+ * clicked on the page counts whenever it names a view or a tab the table can
+ * open, or a URL filter, even what the table already shows: the state around
+ * it may hide it. Otherwise (back and forward), the view and the tab are
+ * written or kept in place, so they count when they differ from what the
+ * table shows; a URL filter when it differs from the last visit. A row named
+ * (`?record=`) is opened on the table as it stands, its page included: it is
+ * no listing link, and a link naming one counts only for a view, a tab or a
+ * URL filter that changes what the table lists. A visit repeating what the
+ * table already reads (the one that mounted it) is not a link.
+ */
+export function isLinkedVisit(visit: TableLinkVisit): boolean {
+  const { query, previousQuery, urlScope, isLinkClick } = visit;
+  const read = (from: Record<string, unknown>, key: string) =>
+    readTableUrlKey(from, urlScope, key).value;
+  // A link clicked counts even when it names what is already there, unless
+  // it opens a row: the table it is opened on stays as it stands.
+  const isRowLink = read(query, RECORD_URL_KEY) !== undefined;
+  const isNew = (value: unknown, current: unknown) =>
+    (isLinkClick && !isRowLink) || value !== current;
+  const view = namedView(query, urlScope);
+  if (view === "" && isNew(undefined, visit.activeView)) return true;
+  if (view && isNew(view, visit.activeView) && visit.canOpenView(view)) {
+    return true;
+  }
+  const tab = read(query, TAB_URL_KEY);
+  if (tab && isNew(tab, visit.activeTab) && visit.canOpenTab(tab)) return true;
+  return namesUrlFilter(query, visit.queryParamFilters, (param) =>
+    isNew(query[param], previousQuery[param]),
+  );
+}
+
+/** A kept field of the listing state, with its value shown and default. */
+export type KeptListingField = [
+  field: TableField,
+  value: unknown,
+  defaultValue: unknown,
+];
+
+/** What `linkFollowingPreferences` reads the table's link state from. */
+export interface LinkFollowingOptions {
+  /** The table arrived on a link (`isLinkedArrival`). */
+  isLinkedArrival: boolean;
+  urlScope: TableUrlScope;
+  /** The URL filters the table lists under now (`urlFilterScope`). */
+  linkScope: () => string | undefined;
+  /** What the URL shown names for the table now (`linkKeyScope`). */
+  linkKeys: () => string | undefined;
+  /** The listing state shown, as it is kept (`LINKED_STATE_FIELDS`). */
+  listingState: () => KeptListingField[];
+}
+
+/** Preferences that leave a link's listing state unkept until it is the user's. */
+export interface LinkFollowingPreferences extends TablePreferences {
+  /**
+   * Runs `change`, which opens a link on the table already shown: as on a
+   * linked arrival, the state it sets is not kept.
+   */
+  followLink: (change: () => void) => Promise<void>;
+  /** Called once the table is mounted: what changes from then is the user's. */
+  settleArrival: () => Promise<void>;
+}
+
+/**
+ * Wraps the table's preferences so the listing state a link opens (on
+ * arrival or on the table already shown) does not overwrite the kept one,
+ * which stays for the next plain visit. The table keeps its state from
+ * watchers, which run on the next flush: what the link and the arrival set
+ * is settled a tick later. The user's first choice from there (a view, a
+ * tab, a filter, a sort) makes the state shown theirs: it is kept whole,
+ * with the URL filters it was chosen under, and the view the link named
+ * leaves the URL, which then reads as a plain visit on reload. Until then,
+ * the link shown is kept too (`shownLink`), so a reload shows it again.
+ */
+export function linkFollowingPreferences(
+  preferences: TablePreferences,
+  options: LinkFollowingOptions,
+): LinkFollowingPreferences {
+  let isShowingLink = options.isLinkedArrival;
+  let isSettled = false;
+
+  const keepLinkScope = () => {
+    preferences.set("linkScope", options.linkScope(), undefined);
+    preferences.set("shownLink", undefined, undefined);
+  };
+  const keepShownLink = () =>
+    preferences.set("shownLink", options.linkKeys(), undefined);
+
+  const takeOver = () => {
+    isShowingLink = false;
+    for (const [field, value, defaultValue] of options.listingState()) {
+      preferences.set(field, value, defaultValue);
+    }
+    keepLinkScope();
+    writeTableUrlKey(options.urlScope, VIEW_URL_KEY);
+  };
+
+  return {
+    ...preferences,
+    set: (field, value, defaultValue) => {
+      if (!LINKED_STATE_FIELDS.has(field)) {
+        preferences.set(field, value, defaultValue);
+      } else if (!isShowingLink) {
+        preferences.set(field, value, defaultValue);
+        keepLinkScope();
+      } else if (isSettled && USER_CHOICE_FIELDS.has(field)) {
+        takeOver();
+      }
+    },
+    followLink: async (change) => {
+      isShowingLink = true;
+      isSettled = false;
+      try {
+        change();
+        await nextTick();
+        keepShownLink();
+      } finally {
+        isSettled = true;
+      }
+    },
+    settleArrival: async () => {
+      await nextTick();
+      if (isShowingLink) keepShownLink();
+      isSettled = true;
+    },
+  };
+}