@antelopejs/dms 0.9.8 → 0.11.0

package/frontend-vue/layers/dms-ui/app/build/composables/data-types/metricCells.ts

@@ -1,8 +1,12 @@
+import {
+  formatDuration,
+  readableNumberFormat,
+} from "#dms-core/app/utils/formatter";
 import { defineAsyncComponent, h } from "vue";
 import type { DataType } from "#dms-core/app/composables/data-types/useDataType";
 import StatusPill from "../../../components/status-pill/StatusPill.vue";
 import MonoCell from "../../components/table/MonoCell.vue";
-import { useComposedText } from "../../../../../dms-core/app/composables/translation/useComposedText";
+import { getAppComposedText } from "../../../../../dms-core/app/composables/translation/useComposedText";
 import {
   readRowField,
   readRowTone,
@@ -11,6 +15,7 @@ import {
   toneClass,
   type Row,
 } from "./cellHelpers";
+import { getAppTranslation } from "../../../../../dms-core/app/composables/translation/useTranslation";
 
 const Sparkline = defineAsyncComponent(
   () => import("../../../components/chart/internal/Sparkline.vue"),
@@ -50,8 +55,8 @@ function statusPillTone(opts: StatusPillOptions, key: string, row: Row) {
  * `subTone`, else the pill's.
  */
 function renderStatusPill(value: unknown, options: unknown, row: Row) {
-  const { processI18n } = useTranslation();
-  const { processText } = useComposedText();
+  const { processI18n } = getAppTranslation();
+  const { processText } = getAppComposedText();
   const opts = (options ?? {}) as StatusPillOptions;
   const key = String(value);
   const item = opts.typeOptions?.items?.find(
@@ -175,10 +180,6 @@ function renderSparkline(options: unknown, row: Row) {
 }
 
 const MS_PER_SECOND = 1000;
-const SECONDS_PER_MINUTE = 60;
-const MINUTES_PER_HOUR = 60;
-const MS_PER_MINUTE = MS_PER_SECOND * SECONDS_PER_MINUTE;
-const MS_PER_HOUR = MS_PER_MINUTE * MINUTES_PER_HOUR;
 const DURATION_UNIT_MS: Record<string, number> = { ms: 1, s: MS_PER_SECOND };
 
 // SI symbols read the same in every language; the figure follows the locale.
@@ -188,39 +189,16 @@ const withSymbol = (
   symbol: string,
   maximumFractionDigits = 0,
 ): string =>
-  `${new Intl.NumberFormat(locale, { maximumFractionDigits }).format(value)} ${symbol}`;
+  `${readableNumberFormat(locale, { maximumFractionDigits }).format(value)} ${symbol}`;
 
 /** A duration always in milliseconds, its digits grouped: "2,149 ms". */
 export function formatMilliseconds(ms: number, locale: string): string {
-  const figure = new Intl.NumberFormat(locale, {
+  const figure = readableNumberFormat(locale, {
     maximumFractionDigits: 0,
-    // `true` groups a four-digit figure too, where a locale's default (es,
-    // pl) would leave "2149" against "12.149" further down the column.
-    useGrouping: true,
   }).format(ms);
   return `${figure} ms`;
 }
 
-/**
- * A duration in its most readable unit: "910 ms", "1.8 s", "4 min 12 s",
- * "2 h 5 min".
- */
-export function formatDuration(ms: number, locale: string): string {
-  const absolute = Math.abs(ms);
-  if (absolute < MS_PER_SECOND) return withSymbol(locale, Math.round(ms), "ms");
-  if (absolute < MS_PER_MINUTE) {
-    return withSymbol(locale, ms / MS_PER_SECOND, "s", 1);
-  }
-  const [major, majorSymbol, minor, minorSymbol] =
-    absolute < MS_PER_HOUR
-      ? ([MS_PER_MINUTE, "min", MS_PER_SECOND, "s"] as const)
-      : ([MS_PER_HOUR, "h", MS_PER_MINUTE, "min"] as const);
-  const whole = Math.trunc(ms / major);
-  const rest = Math.round((ms - whole * major) / minor);
-  const head = withSymbol(locale, whole, majorSymbol);
-  return rest === 0 ? head : `${head} ${withSymbol(locale, rest, minorSymbol)}`;
-}
-
 const BYTE_SYMBOLS = ["B", "kB", "MB", "GB", "TB"];
 const BYTE_STEP = 1000;
 
@@ -253,8 +231,12 @@ interface DurationOptions {
   toneField?: string;
 }
 
-const DURATION_FORMATS: Record<string, typeof formatDuration> = {
-  readable: formatDuration,
+type DurationWriter = (ms: number, locale: string) => string;
+
+// A cell is read at a glance: the readable duration is rounded there.
+const DURATION_FORMATS: Record<string, DurationWriter> = {
+  readable: (ms, locale) =>
+    formatDuration(ms, locale, { precision: "rounded" }),
   ms: formatMilliseconds,
 };
 
@@ -270,7 +252,8 @@ function renderDuration(
 ) {
   const opts = (options ?? {}) as DurationOptions;
   const ms = numberOf(value) * (DURATION_UNIT_MS[opts.unit ?? "ms"] ?? 1);
-  const format = DURATION_FORMATS[opts.format ?? "readable"] ?? formatDuration;
+  const format =
+    DURATION_FORMATS[opts.format ?? "readable"] ?? DURATION_FORMATS.readable!;
   return figure(
     format(ms, locale),
     rowToneTextClass(row, opts.toneField, FIGURE_TONE_CLASS),

package/frontend-vue/layers/dms-ui/app/build/composables/data-types/numberSuffix.ts

@@ -0,0 +1,44 @@
+import type { DataTypeFormatter } from "#dms-core/app/composables/data-types/useDataType";
+import { getAppTranslation } from "../../../../../dms-core/app/composables/translation/useTranslation";
+
+/** A formatter writing a number for a locale, with Intl's options. */
+type NumberFormatter = (
+  value: unknown,
+  locale: string,
+  options?: Intl.NumberFormatOptions,
+) => unknown;
+
+/** The options of a numeric field a cell reads besides Intl's. */
+interface NumberSuffixOptions {
+  /** Unit after the value ("days"): an i18n key with `$`, or a literal. */
+  suffix?: string;
+}
+
+// Keeps the unit on the line of its number when a cell wraps.
+const UNIT_SEPARATOR = " ";
+
+/**
+ * A numeric data type's formatter writing the field's unit after the value,
+ * as its form input does ("12.5 kWp"), wherever the type is drawn: table
+ * cells, expanded rows, cards, read-only fields. A value that is not a
+ * number is left as the formatter returns it.
+ *
+ * A formatter also runs where no component setup is active (a footer sum, a
+ * group header, an export), so the unit is translated through the
+ * application's composer, never through a composable.
+ */
+export function withNumberSuffix(format: NumberFormatter): DataTypeFormatter {
+  return (value, locale, options) => {
+    const formatted = format(
+      value,
+      locale,
+      options as Intl.NumberFormatOptions | undefined,
+    );
+    const suffix = (options as NumberSuffixOptions | undefined)?.suffix;
+    if (!suffix || typeof value !== "number" || typeof formatted !== "string") {
+      return formatted;
+    }
+    const unit = getAppTranslation().processI18n(suffix);
+    return `${formatted}${UNIT_SEPARATOR}${unit}`;
+  };
+}

package/frontend-vue/layers/dms-ui/app/build/composables/data-types/registerDefaults.ts

@@ -7,6 +7,7 @@ import UIcon from "@nuxt/ui/runtime/vue/components/Icon.vue";
 import ULink from "@nuxt/ui/components/Link.vue";
 import { buildRelationBadges } from "./relationBadges";
 import { mapRelationBeforeState, sameRelationValue } from "./relationValue";
+import { NotFoundRelation, relationSelectSource } from "./relationRows";
 import {
   isSet,
   readRowField,
@@ -17,8 +18,15 @@ import {
   toneClass,
 } from "./cellHelpers";
 import { registerMetricCellTypes } from "./metricCells";
+import {
+  dateFilterEditorValue,
+  numberFilterEditorValue,
+} from "../table/utils/filterEditorValue";
+import { formatDuration } from "#dms-core/app/utils/formatter";
+import { withNumberSuffix } from "./numberSuffix";
 import { registerTwoLineCellType } from "./twoLineCell";
-import { useComposedText } from "../../../../../dms-core/app/composables/translation/useComposedText";
+import { formatRecordLabel } from "../table-view/utils/formTexts";
+import { getAppComposedText } from "../../../../../dms-core/app/composables/translation/useComposedText";
 import StatusPill, {
   type StatusPillVariant,
 } from "../../../components/status-pill/StatusPill.vue";
@@ -29,6 +37,8 @@ import {
   formatDayMonth,
   formatRelativeDate,
 } from "../../utils/relativeDate";
+import { serverRenderNow } from "#dms-core/app/build/composables/renderNow";
+import { getAppTranslation } from "../../../../../dms-core/app/composables/translation/useTranslation";
 
 const FilePreview = defineAsyncComponent(
   () => import("../../../components/table-view/FilePreview.vue"),
@@ -141,11 +151,57 @@ function createLinkRenderer(options: LinkRendererOptions) {
   };
 }
 
+/** A `UrlType`'s options its read-only value reads. */
+interface UrlOptions {
+  preview?: "avatar" | "image";
+  /**
+   * The label of the field shown, handed by the form's read-only display:
+   * the image's name when its row has none.
+   */
+  fieldLabel?: string;
+}
+
+const URL_IMAGE_CLASS =
+  "border-default h-16 w-auto max-w-full rounded-md border object-cover";
+
+// The fields that name a row, read in order for its image's text.
+const ROW_NAME_FIELDS = ["name", "label", "title"];
+
+/**
+ * What an image stands for to a reader who cannot see it: the name of the
+ * row it belongs to (a team member's photo is that member), or else the
+ * field's label.
+ */
+function imageAlt(row: Row, locale: string, options: UrlOptions): string {
+  for (const field of ROW_NAME_FIELDS) {
+    const name = formatRecordLabel(row?.[field], locale);
+    if (name) return name;
+  }
+  return options.fieldLabel ?? "";
+}
+
+/**
+ * A URL drawn as the image it points to, when its type asks for it
+ * (`preview`): a remote photo reads as a picture, not as its address.
+ */
+function renderUrl(value: unknown, locale: string, options: unknown, row: Row) {
+  const opts = (options ?? {}) as UrlOptions;
+  if (!opts.preview || !isString(value) || !value) return undefined;
+  const alt = imageAlt(row, locale, opts);
+  if (opts.preview === "avatar") return h(UAvatar, { src: value, alt });
+  return h("img", {
+    src: value,
+    alt,
+    loading: "lazy",
+    class: URL_IMAGE_CLASS,
+  });
+}
+
 const convertToBoolean = (value: unknown): boolean =>
   parse(String(value)) === true;
 
 const getBooleanLabel = (value: unknown): string => {
-  const { processI18n } = useTranslation();
+  const { processI18n } = getAppTranslation();
   return convertToBoolean(value)
     ? processI18n("$dms.table.filter.boolean.checked")
     : processI18n("$dms.table.filter.boolean.unchecked");
@@ -160,7 +216,7 @@ function renderBoolean(value: unknown) {
 }
 
 function formatDateBetween(value: unknown, locale: string): string {
-  const { t } = useI18n();
+  const { t } = getAppTranslation();
   const [rawStart, rawEnd] = Array.isArray(value)
     ? value
     : [
@@ -174,7 +230,7 @@ function formatDateBetween(value: unknown, locale: string): string {
 
 // v2 .status pill, tinted with the configured online/offline color.
 function renderStatus(value: unknown, options: unknown) {
-  const { processI18n } = useTranslation();
+  const { processI18n } = getAppTranslation();
   const opts = options as StatusOptions | undefined;
   const isOnline = Boolean(value);
   const onlineLabel = opts?.onlineLabel || "$common.status.online";
@@ -194,7 +250,7 @@ function renderStatusPill(label: string, color: string) {
 }
 
 function renderSelectItem(item: SelectItem) {
-  const { processI18n } = useTranslation();
+  const { processI18n } = getAppTranslation();
   const label = processI18n(item.label);
   if (!item.icon && !item.iconColor && !item.textColor) return label;
 
@@ -253,7 +309,7 @@ function renderSelect(value: unknown, options?: unknown) {
 function formatAddress(value: unknown): string {
   if (!value || typeof value !== "object") return " ";
 
-  const { processI18n } = useTranslation();
+  const { processI18n } = getAppTranslation();
   const addr = value as Record<string, string>;
   const countryName = addr.countryCode
     ? processI18n(`$country.${addr.countryCode}`)
@@ -282,12 +338,31 @@ function renderRelationBadge(label: string, title?: string) {
   });
 }
 
+// An id its `select` route did not answer: "Not found", the id on hover.
+function renderNotFoundRelation(relation: NotFoundRelation) {
+  const { t } = getAppTranslation();
+  return h(
+    "span",
+    { class: "text-muted", title: relation.id },
+    t("dms.form.relation.not_found"),
+  );
+}
+
 function renderRelationBadges(values: unknown[], labelKey: string) {
-  const { processI18n } = useTranslation();
-  const { visible, hidden } = buildRelationBadges(values, labelKey);
-  const badges = visible.map((label) =>
-    renderRelationBadge(processI18n(label)),
+  const { processI18n, t } = getAppTranslation();
+  const notFound = values.filter(
+    (item): item is NotFoundRelation => item instanceof NotFoundRelation,
   );
+  const { visible, hidden } = buildRelationBadges(
+    values.filter((item) => !(item instanceof NotFoundRelation)),
+    labelKey,
+  );
+  const badges = [
+    ...visible.map((label) => renderRelationBadge(processI18n(label))),
+    ...notFound.map((relation) =>
+      renderRelationBadge(t("dms.form.relation.not_found"), relation.id),
+    ),
+  ];
   if (hidden.length > 0) {
     const hiddenLabels = hidden.map((label) => processI18n(label)).join(", ");
     badges.push(renderRelationBadge(`+${hidden.length}`, hiddenLabels));
@@ -303,6 +378,7 @@ function renderRelation(value: unknown, options: unknown) {
     return renderRelationBadges(value, labelKey);
   }
 
+  if (value instanceof NotFoundRelation) return renderNotFoundRelation(value);
   if (!value || !isObject(value)) return value;
 
   const valueObject = value as Record<string, string>;
@@ -354,7 +430,7 @@ function renderImage(value: unknown, options: unknown) {
 }
 
 function renderFile(value: unknown, options: unknown) {
-  const { t } = useI18n();
+  const { t } = getAppTranslation();
   const opts = options as FileOptions | undefined;
 
   if (opts?.multiple && Array.isArray(value)) {
@@ -408,8 +484,8 @@ const matchesBadge = (badge: IdentityBadgeOption, value: unknown): boolean =>
  * `emptyIcon` stand for a row without a value.
  */
 function renderIdentity(value: unknown, options: unknown, row: Row) {
-  const { processI18n } = useTranslation();
-  const { processText } = useComposedText();
+  const { processI18n } = getAppTranslation();
+  const { processText } = getAppComposedText();
   const opts = (options ?? {}) as IdentityOptions;
   const badges = (opts.badges ?? [])
     .filter((badge) => matchesBadge(badge, readRowField(row, badge.field)))
@@ -526,7 +602,7 @@ function renderPill(pill: PillItem) {
  * a relation could not resolve (a deleted row) is skipped.
  */
 function renderPills(value: unknown, options: unknown, row: Row) {
-  const { processI18n } = useTranslation();
+  const { processI18n } = getAppTranslation();
   const opts = (options ?? {}) as PillsOptions;
   if (opts.exclusive && isSet(readRowField(row, opts.exclusive.field))) {
     return h("span", { class: [PILL_CLASS, PILL_FILLED_CLASS] }, [
@@ -605,11 +681,14 @@ function renderRelativeDate(
   options: unknown,
   row: Row,
 ) {
-  const { processI18n } = useTranslation();
+  const { processI18n } = getAppTranslation();
   const opts = (options ?? {}) as RelativeDateOptions;
   const date = new Date(value as string);
   if (Number.isNaN(date.getTime())) return String(value);
-  const deltaMs = date.getTime() - Date.now();
+  // Measured from the server render's instant while hydrating it: "3 min ago"
+  // written at 12:00:59 stays so in a browser hydrating at 12:01:01.
+  const now = serverRenderNow() ?? Date.now();
+  const deltaMs = date.getTime() - now;
   const isPast = deltaMs < 0;
   const title = formatDate(date, locale, RELATIVE_TITLE_FORMAT) ?? undefined;
 
@@ -624,8 +703,8 @@ function renderRelativeDate(
   const style = (isPast ? opts.pastStyle : undefined) ?? opts.style;
   let text =
     style === "day"
-      ? formatDayMonth(date, locale)
-      : formatRelativeDate(date, locale);
+      ? formatDayMonth(date, locale, now)
+      : formatRelativeDate(date, locale, now);
   const isSoon = !isPast && !!opts.soonWithinMs && deltaMs < opts.soonWithinMs;
   const tone = isPast
     ? (opts.pastTone ?? opts.tone)
@@ -644,7 +723,7 @@ function renderRelativeDate(
 }
 
 function renderMissingDate(options: unknown) {
-  const { processI18n } = useTranslation();
+  const { processI18n } = getAppTranslation();
   const opts = (options ?? {}) as RelativeDateOptions;
   if (!opts.emptyLabel) return "-";
   return h(
@@ -670,7 +749,7 @@ interface IndicatorOptions {
  * on for a set flag or a non-empty list.
  */
 function renderIndicator(value: unknown, options: unknown) {
-  const { processI18n } = useTranslation();
+  const { processI18n } = getAppTranslation();
   const opts = (options ?? {}) as IndicatorOptions;
   const isOn = isSet(value);
   const icon = isOn ? opts.onIcon : opts.offIcon;
@@ -768,7 +847,8 @@ const registerPrimitiveTypes = (
 ) => {
   registerDataType({
     id: "number",
-    formatter: { default: formatNumber as DataTypeFormatter },
+    formatter: { default: withNumberSuffix(formatNumber) },
+    filterEditorValue: numberFilterEditorValue,
   });
   registerDataType({
     id: "string",
@@ -776,15 +856,24 @@ const registerPrimitiveTypes = (
   });
   registerDataType({
     id: "price",
-    formatter: { default: formatPrice as DataTypeFormatter },
+    formatter: { default: withNumberSuffix(formatPrice) },
+    filterEditorValue: numberFilterEditorValue,
   });
   registerDataType({
     id: "percentage",
-    formatter: { default: formatPercentage as DataTypeFormatter },
+    formatter: { default: withNumberSuffix(formatPercentage) },
+    filterEditorValue: numberFilterEditorValue,
   });
   registerDataType({
     id: "string_time",
-    formatter: { default: formatTimeSpan },
+    // Written as the field writes it ("7 h 30 min"), in the reader's locale,
+    // rounded as every duration cell is: the field keeps the exact value.
+    formatter: {
+      default: (value: unknown, locale: string) =>
+        isNumber(value)
+          ? formatDuration(Number(value), locale, { precision: "rounded" })
+          : value,
+    },
   });
 };
 
@@ -801,17 +890,18 @@ const registerDateType = (registerDataType: (dataType: DataType) => void) => {
     id: "date",
     formatter: {
       default: (value: unknown, locale: string) => {
-        const { t } = useI18n();
+        const { t } = getAppTranslation();
         return formatDate(value, locale) ?? t("dms.date.undefined");
       },
       cell: (value: unknown, locale: string) => {
-        const { t } = useI18n();
+        const { t } = getAppTranslation();
         return (
           formatDate(value, locale, CELL_DATE_FORMAT) ?? t("dms.date.undefined")
         );
       },
       is_between: formatDateBetween,
     },
+    filterEditorValue: dateFilterEditorValue,
   });
 };
 
@@ -875,9 +965,13 @@ const registerLinkTypes = (registerDataType: (dataType: DataType) => void) => {
     id: "email",
     formatter: { default: createLinkRenderer({ hrefPrefix: "mailto:" }) },
   });
+  const renderLink = createLinkRenderer({ target: "_blank" });
   registerDataType({
     id: "url",
-    formatter: { default: createLinkRenderer({ target: "_blank" }) },
+    formatter: {
+      default: (value: unknown, locale: string, options: unknown, row?: Row) =>
+        renderUrl(value, locale, options, row) ?? renderLink(value, locale),
+    },
   });
 };
 
@@ -892,6 +986,7 @@ const registerRelationType = (
     },
     beforeStateMapper: mapRelationBeforeState,
     isSameValue: sameRelationValue,
+    selectSource: relationSelectSource,
   });
 };
 
@@ -906,6 +1001,7 @@ const registerCascaderRelationType = (
     },
     beforeStateMapper: mapRelationBeforeState,
     isSameValue: sameRelationValue,
+    selectSource: relationSelectSource,
   });
 };
 

package/frontend-vue/layers/dms-ui/app/build/composables/data-types/registerFieldTypes.ts

@@ -1,5 +1,6 @@
 import { h } from "vue";
 import type { DataType } from "#dms-core/app/composables/data-types/useDataType";
+import { getAppTranslation } from "../../../../../dms-core/app/composables/translation/useTranslation";
 
 // How the field types made of several values read in a table cell or a
 // read-only form: a count, a masked secret, the first line of the code,
@@ -19,7 +20,7 @@ const countOf = (value: unknown): number => {
 
 function renderCount(key: string) {
   return (value: unknown) => {
-    const { t } = useI18n();
+    const { t } = getAppTranslation();
     const count = countOf(value);
     return t(key, { count }, count);
   };

package/frontend-vue/layers/dms-ui/app/build/composables/data-types/relationFilter.ts

@@ -0,0 +1,75 @@
+import { isEmptyFormValue, sameFormValue } from "../unsaved-changes/formValue";
+
+/**
+ * A relation picker narrowed by another field of its form: the related
+ * table's `field` must equal the form's value of `from`.
+ */
+export interface RelationFilterBy {
+  field: string;
+  from: string;
+}
+
+/** The compare mode the search route matches the related `field` with. */
+const FILTER_MODE = "is";
+
+type FilterValue = string | number | boolean;
+
+function isFilterValue(value: unknown): value is FilterValue {
+  if (typeof value === "string") return value !== "";
+  return typeof value === "number" || typeof value === "boolean";
+}
+
+/**
+ * The query narrowing the picker's search: the related table's filter
+ * syntax (`filter_<field>=is:<value>`), the one its funnel sends. Nothing
+ * while the source field holds no single value: every row is offered.
+ */
+export function relationFilterParams(
+  filterBy: RelationFilterBy | undefined,
+  sourceValue: unknown,
+): Record<string, string> {
+  if (!filterBy || !isFilterValue(sourceValue)) return {};
+  return { [`filter_${filterBy.field}`]: `${FILTER_MODE}:${sourceValue}` };
+}
+
+/** The source field and the pick, before and after a change of either. */
+export interface RelationPickChange {
+  source: unknown;
+  pick: unknown;
+  previousSource: unknown;
+  previousPick: unknown;
+  /** The source value the current pick was made (or loaded) with. */
+  pickSource: unknown;
+}
+
+/** Whether to clear the pick, and the source value the pick now goes with. */
+export interface RelationPickOutcome {
+  shouldClear: boolean;
+  pickSource: unknown;
+}
+
+/** Whether a picker holds a value. */
+function hasRelationPick(value: unknown): boolean {
+  return !isEmptyFormValue(value);
+}
+
+/**
+ * Whether a change of the source field voids the pick: made for another of
+ * its values. A pick changing at the same time (a record loading both
+ * values) or after goes with the current source; going back to the value the
+ * pick was made with keeps it.
+ */
+export function resolveRelationPick(
+  change: RelationPickChange,
+): RelationPickOutcome {
+  const isPickChange = !sameFormValue(change.pick, change.previousPick);
+  if (isPickChange || !hasRelationPick(change.pick)) {
+    return { shouldClear: false, pickSource: change.source };
+  }
+  const isSourceChange = !sameFormValue(change.source, change.previousSource);
+  const isPickSource = sameFormValue(change.source, change.pickSource);
+  return {
+    shouldClear: isSourceChange && !isPickSource,
+    pickSource: change.pickSource,
+  };
+}

package/frontend-vue/layers/dms-ui/app/build/composables/data-types/relationRows.ts

@@ -0,0 +1,92 @@
+import type { DataTypeSelectSource } from "#dms-core/app/composables/data-types/useDataType";
+import { pageRequestUrl } from "../page/pageUrlValues";
+import { relationIdsQuery } from "./relationValue";
+
+/** The keys a `select` route's row carries its label and value under by default. */
+export const RELATION_LABEL_KEY = "label";
+export const RELATION_VALUE_KEY = "value";
+
+type RelationRow = Record<string, unknown>;
+
+interface RelationSelectResponse {
+  results?: RelationRow[];
+}
+
+interface RelationSourceOptions {
+  searchUrl?: unknown;
+  keyMapping?: DataTypeSelectSource["keyMapping"];
+}
+
+/**
+ * The `select` route a relation's control reads its rows from, and their key
+ * mapping: the relation data type's {@link DataTypeSelectSource}.
+ */
+export function relationSelectSource(
+  options: unknown,
+): DataTypeSelectSource | undefined {
+  const opts = options as RelationSourceOptions | undefined;
+  if (typeof opts?.searchUrl !== "string") return undefined;
+  return { searchUrl: opts.searchUrl, keyMapping: opts.keyMapping };
+}
+
+/** The value a row of the source is picked by. */
+export function relationRowValue(
+  source: DataTypeSelectSource,
+  row: RelationRow,
+): unknown {
+  return row[source.keyMapping?.value || RELATION_VALUE_KEY];
+}
+
+/** The label a row of the source is named by. */
+export function relationRowLabel(
+  source: DataTypeSelectSource,
+  row: RelationRow,
+): unknown {
+  return row[source.keyMapping?.label || RELATION_LABEL_KEY];
+}
+
+/**
+ * An id a relation's `select` route did not answer: a deleted row, or one out
+ * of the reader's reach — it cannot tell which, so it is shown as "Not
+ * found", never as "Deleted", with the id itself in its tooltip.
+ */
+export class NotFoundRelation {
+  constructor(readonly id: string) {}
+}
+
+/** The ids of a read that its rows do not answer. */
+export function notFoundRelationIds(
+  source: DataTypeSelectSource,
+  ids: string[],
+  rows: RelationRow[],
+): string[] {
+  const answered = new Set(
+    rows.map((row) => String(relationRowValue(source, row))),
+  );
+  return ids.filter((id) => !answered.has(id));
+}
+
+/**
+ * Reads the rows of a relation's ids from its `select` route, narrowed with
+ * `?ids=` to those rows alone (matched on the mapped value key), whatever the
+ * route's page size. The one way the picker, the filter chips and the
+ * read-only lists name the ids they hold. A failed read answers no rows: the
+ * ids then show as not found, as a row out of the reader's reach does.
+ */
+export function useRelationRows() {
+  const { $authFetch } = useAuthFetch();
+
+  async function readRelationRows(
+    source: DataTypeSelectSource,
+    ids: string[],
+  ): Promise<RelationRow[]> {
+    const url = pageRequestUrl(source.searchUrl);
+    if (!url || ids.length === 0) return [];
+    const response = await $authFetch<RelationSelectResponse>(url, {
+      params: relationIdsQuery(ids, source.keyMapping),
+    }).catch(() => undefined);
+    return response?.results ?? [];
+  }
+
+  return { readRelationRows };
+}