@antelopejs/dms 0.7.10 → 0.7.12

package/frontend-vue/layers/dms-ui/app/components/blocks/LiveToggleBlock.vue

@@ -5,11 +5,11 @@ import { usePageLive } from "../../composables/live/usePageLive";
 import { formatElapsed } from "../../build/composables/live/formatElapsed";
 import { useLiveToggleShortcut } from "../../build/composables/live/useLiveToggleShortcut";
 import { HIDDEN_TAB_NOTE } from "../../build/composables/live/pageLiveController";
+import type { ConfirmTranslate } from "../../build/composables/confirm/confirmDialogTexts";
 import {
-  resolveConfirmText,
-  type ConfirmTranslate,
-} from "../../build/composables/confirm/confirmDialogTexts";
-import type { PageLiveNote, PageLiveNoteTone } from "../../types/live";
+  missedRowsText,
+  showLiveNote,
+} from "../../build/composables/live/liveNotes";
 import type { DefaultComponentProps } from "../../../../dms-core/app/types/component";
 
 interface LiveToggleBlockProps extends DefaultComponentProps {
@@ -40,11 +40,6 @@ const ALIGN_CLASSES: Record<
   center: "justify-center",
   right: "justify-end",
 };
-const TONE_CLASSES: Record<PageLiveNoteTone, string> = {
-  neutral: "",
-  warning: "text-warning",
-  error: "text-error",
-};
 const PILL_BUTTON_CLASS =
   "focus-visible:outline-primary flex items-center gap-1.5 rounded-[5px] px-2 py-1 text-[12px] font-medium transition-colors focus-visible:outline-2";
 const PILL_IDLE_CLASS = "text-muted hover:text-default hover:bg-elevated";
@@ -90,15 +85,10 @@ const updatedLabel = computed(() => {
     : updated;
 });
 
-const noteText = (note: PageLiveNote) =>
-  resolveConfirmText(note.text, note.params ?? {}, translate);
-
 const missedText = computed(() => {
   const count = live.missedCount.value;
   if (count === 0) return "";
-  return props.missedLabel
-    ? resolveConfirmText(props.missedLabel, { count }, translate)
-    : t("dms.live.new_rows", { count }, count);
+  return missedRowsText(count, props.missedLabel, translate);
 });
 
 // "Paused · typing in the Tester · 40 new requests", the detail apart: it
@@ -107,7 +97,7 @@ const pausedText = computed(() => {
   const reason = live.pauseReason.value;
   return [
     t("dms.live.paused"),
-    reason ? noteText(reason) : "",
+    reason ? showLiveNote(reason, translate).text : "",
     missedText.value,
   ]
     .filter((part) => part !== "")
@@ -117,10 +107,7 @@ const pausedText = computed(() => {
 const detail = computed(() => {
   const note = live.missedDetail.value;
   if (!note || live.missedCount.value === 0) return null;
-  return {
-    text: noteText(note),
-    toneClass: TONE_CLASSES[note.tone ?? "neutral"],
-  };
+  return showLiveNote(note, translate);
 });
 
 // A hidden tab resumes by itself when it shows again: no button for it.

package/frontend-vue/layers/dms-ui/app/components/chart/Chart.vue

@@ -21,6 +21,7 @@ import type {
   ChartAnnotation,
   ChartAutoYRange,
   ChartCurve,
+  ChartLegendPosition,
   ChartResponse,
   ChartSeries,
   ChartType,
@@ -48,6 +49,7 @@ interface Props extends DefaultComponentProps {
   showGrid?: boolean;
   showTooltip?: boolean;
   showLegend?: boolean;
+  legendPosition?: ChartLegendPosition;
   smooth?: boolean;
   curve?: ChartCurve;
   stacked?: boolean;
@@ -238,6 +240,7 @@ const apex = useApexChart(() => ({
   showGrid: props.showGrid,
   showTooltip: props.showTooltip,
   showLegend: effectiveShowLegend.value,
+  legendPosition: props.legendPosition,
   smooth: props.smooth,
   curve: props.curve,
   stacked: props.stacked,

package/frontend-vue/layers/dms-ui/app/components/chart/ChartCard.vue

@@ -34,6 +34,8 @@ interface Props extends DefaultComponentProps {
   valuePrecision?: ValuePrecision;
   showDelta?: boolean;
   showLegend?: boolean;
+  /** The wrapped chart draws its own legend, naming each series. */
+  showSeriesLegend?: boolean;
   primaryLabel?: string;
   comparisonLabel?: string;
 }
@@ -53,6 +55,7 @@ const DEFAULT_COMPARISON_LABEL_KEY = "dms.chart.legend_comparison";
 const props = withDefaults(defineProps<Props>(), {
   showDelta: true,
   showLegend: true,
+  showSeriesLegend: false,
   valueFormat: "compact",
   currencyCode: "EUR",
 });
@@ -126,7 +129,7 @@ const nestedContext = reactive<NestedChartContext>({
   cardSeries: [],
   cardComparisonSeries: [],
   isLoading: false,
-  hideLegend: true,
+  hideLegend: !props.showSeriesLegend,
   valueFormat: props.valueFormat,
   currencyCode: props.currencyCode,
   valuePrecision: props.valuePrecision,
@@ -138,6 +141,7 @@ watchEffect(() => {
   nestedContext.cardSeries = cardSeries.value;
   nestedContext.cardComparisonSeries = cardComparisonSeries.value;
   nestedContext.isLoading = isLoading.value;
+  nestedContext.hideLegend = !props.showSeriesLegend;
   nestedContext.valueFormat = props.valueFormat;
   nestedContext.currencyCode = props.currencyCode;
   nestedContext.valuePrecision = props.valuePrecision;

package/frontend-vue/layers/dms-ui/app/components/code-snippet/CodeSnippet.vue

@@ -10,7 +10,17 @@ import type { CodeToken, highlightCode } from "../../build/utils/codeHighlight";
 
 // Read-only code in the editor's look: a head with the title, the language
 // and a copy button, then the code highlighted by the editor's languages.
-// Until the highlighter loads (and on the server) the code shows as is.
+// Without a title or a language there is no head: the copy button floats in
+// the code's corner. Until the highlighter loads (and on the server) the
+// code shows as is.
+
+/**
+ * How long lines break: `false` scrolls them sideways, `true` wraps them
+ * between words, `"anywhere"` also breaks a word too long for the line (a
+ * URL, a token, a minified payload).
+ */
+type CodeSnippetWrap = boolean | "anywhere";
+
 interface CodeSnippetProps {
   /** The code, verbatim. */
   code: string;
@@ -25,8 +35,13 @@ interface CodeSnippetProps {
   title?: string;
   /** Lines shown before the code scrolls; all of them when unset. */
   maxLines?: number;
+  /**
+   * A CSS height the code scrolls past (`"20rem"`), when `maxLines` is not
+   * set: for a payload whose lines differ in length once wrapped.
+   */
+  maxHeight?: string;
   /** Wraps long lines instead of scrolling sideways. */
-  wrap?: boolean;
+  wrap?: CodeSnippetWrap;
 }
 
 const props = withDefaults(defineProps<CodeSnippetProps>(), {
@@ -34,6 +49,7 @@ const props = withDefaults(defineProps<CodeSnippetProps>(), {
   copy: true,
   title: undefined,
   maxLines: undefined,
+  maxHeight: undefined,
   wrap: false,
 });
 
@@ -41,24 +57,39 @@ const LINE_HEIGHT_PX = 19;
 // The code's top and bottom padding (`py-2`), around its lines.
 const CODE_PADDING_PX = 16;
 
+const WRAP_CLASSES: Record<"false" | "true" | "anywhere", string> = {
+  false: "whitespace-pre",
+  true: "break-words whitespace-pre-wrap",
+  anywhere: "whitespace-pre-wrap [overflow-wrap:anywhere]",
+};
+
 const highlight = shallowRef<typeof highlightCode | null>(null);
 
 const language = computed(() => resolveCodeLanguage(props.language));
+// A language given, even `text`, is named in a head; without a title either,
+// a head would only hold the copy button.
+const isHeadless = computed(() => !props.title && props.language === undefined);
 const hasHead = computed(
-  () => !!props.title || props.copy || language.value !== PLAIN_CODE_LANGUAGE,
+  () =>
+    !isHeadless.value &&
+    (!!props.title || props.copy || language.value !== PLAIN_CODE_LANGUAGE),
+);
+const hasFloatingCopy = computed(() => isHeadless.value && props.copy);
+const wrapClass = computed(
+  () => WRAP_CLASSES[String(props.wrap) as keyof typeof WRAP_CLASSES],
 );
 const tokens = computed<CodeToken[]>(() =>
   highlight.value
     ? highlight.value(props.code, language.value)
     : [{ text: props.code }],
 );
-const sizeStyle = computed(() =>
-  props.maxLines
-    ? {
-        maxHeight: `${props.maxLines * LINE_HEIGHT_PX + CODE_PADDING_PX}px`,
-      }
-    : undefined,
-);
+const sizeStyle = computed(() => {
+  if (props.maxLines)
+    return {
+      maxHeight: `${props.maxLines * LINE_HEIGHT_PX + CODE_PADDING_PX}px`,
+    };
+  return props.maxHeight ? { maxHeight: props.maxHeight } : undefined;
+});
 
 onMounted(async () => {
   const module = await import("../../build/utils/codeHighlight");
@@ -68,7 +99,7 @@ onMounted(async () => {
 
 <template>
   <div
-    class="border-default min-w-0 overflow-hidden rounded-[10px] border bg-(--ui-bg)"
+    class="border-default relative min-w-0 overflow-hidden rounded-[10px] border bg-(--ui-bg)"
   >
     <div
       v-if="hasHead"
@@ -85,10 +116,17 @@ onMounted(async () => {
       </span>
       <DmsCopyButton v-if="props.copy" :value="props.code" />
     </div>
+    <!-- Kept clear of the code: the code's end padding leaves it room. -->
+    <DmsCopyButton
+      v-if="hasFloatingCopy"
+      :value="props.code"
+      class="absolute end-1 top-1"
+      data-floating-copy
+    />
     <!-- Focusable: a keyboard scrolls the code when it overflows. -->
     <pre
-      class="text-highlighted m-0 overflow-auto px-3.5 py-2 font-mono text-[12.5px] leading-[19px]"
-      :class="props.wrap ? 'break-words whitespace-pre-wrap' : 'whitespace-pre'"
+      class="text-highlighted m-0 overflow-auto py-2 ps-3.5 font-mono text-[12.5px] leading-[19px]"
+      :class="[wrapClass, hasFloatingCopy ? 'pe-10' : 'pe-3.5']"
       :style="sizeStyle"
       :data-language="language"
       tabindex="0"

package/frontend-vue/layers/dms-ui/app/components/form/Form.vue

@@ -17,6 +17,10 @@ import {
   type FormValidator,
 } from "../../composables/form/types/validation";
 import { FORM_FIELD_LOADING_KEY } from "../../composables/form/types/field-loading";
+import {
+  FORM_HANDLE_KEY,
+  linkedFieldId,
+} from "../../build/composables/form/enclosingForm";
 import { FORM_CONTENT_LANGUAGE_KEY } from "../../composables/form/types/content-language";
 import { DMS_SECTION_SURFACE_KEY } from "../../build/components/section/context";
 import DmsSaveBar from "../save-bar/SaveBar.vue";
@@ -30,7 +34,7 @@ import { DMS_CONTAINER_KEY } from "../../build/composables/containers/context";
 import { useFormDirty } from "../../composables/unsaved-changes/useFormDirty";
 import { useUnsavedChanges } from "../../composables/unsaved-changes/useUnsavedChanges";
 import { formSaveMode } from "../../build/composables/form/formFooter";
-import { usePageRecordLabel } from "#dms-core/app/build/composables/page/usePageRecordLabel";
+import { usePageRecordLabel } from "#dms-core/app/composables/page/usePageRecordLabel";
 import { formatRecordLabel } from "../../build/composables/table-view/utils/formTexts";
 import {
   FORM_ENTRY_CONTEXT_KEY,
@@ -168,6 +172,13 @@ async function focusField(name: string | undefined): Promise<void> {
   row?.scrollIntoView({ block: "center" });
 }
 
+/** Brings a field into view and focuses it: a link's anchor, a field's request. */
+async function revealField(fieldId: string): Promise<void> {
+  await formSettled();
+  fieldRow(fieldId)?.scrollIntoView({ block: "center" });
+  await focusField(fieldId);
+}
+
 /**
  * A refused submit: its field errors go under the fields, the first focused.
  *
@@ -516,6 +527,13 @@ function onSubmit(event: Parameters<typeof handleSubmit>[0]) {
 }
 
 provide(FORM_VALIDATOR_KEY, registerValidator);
+provide(FORM_HANDLE_KEY, {
+  submit: async () => {
+    await form.value?.submit();
+  },
+  registerValidator,
+  revealField,
+});
 provide(FORM_FIELD_LOADING_KEY, setFieldLoading);
 provide(FORM_CONTENT_LANGUAGE_KEY, "*");
 
@@ -580,6 +598,25 @@ if (props.labelKey && !inFormContainer) {
   });
 }
 
+// A page opened on a field's anchor (`#retentionDays`, the id of its
+// control) brings it into view and focuses it once drawn: a link followed
+// inside the app gets no jump from the browser, and the fields of a record
+// exist only once it loaded. A form in a drawer or a modal follows none: the
+// anchor is the page's.
+if (!inFormContainer && !container) {
+  const followFieldAnchor = () => {
+    const fieldId = linkedFieldId(window.location.hash, allFieldIds.value);
+    if (fieldId) void revealField(fieldId);
+  };
+  onMounted(() => {
+    followFieldAnchor();
+    window.addEventListener("hashchange", followFieldAnchor);
+  });
+  onBeforeUnmount(() =>
+    window.removeEventListener("hashchange", followFieldAnchor),
+  );
+}
+
 const isHorizontal = props.fieldsOrientation !== "vertical";
 const surface: FormSurface = inFormContainer
   ? "container"

package/frontend-vue/layers/dms-ui/app/components/form/components/InputNumber.vue

@@ -4,9 +4,14 @@ import type {
   InputNumberEmits,
   InputNumberSlots,
 } from "@nuxt/ui/components/InputNumber.vue";
-import { computed } from "vue";
+import { computed, nextTick } from "vue";
 import { useForwardPropsEmits } from "reka-ui";
 import { useControlError } from "../../../build/composables/form/useControlError";
+import {
+  numberAdjustment,
+  parseTypedNumber,
+} from "../../../build/utils/numberAdjustment";
+import type { InputNumberAdjustment } from "../../../types/input-number";
 
 defineOptions({ inheritAttrs: false });
 
@@ -15,16 +20,27 @@ interface InputNumberFieldProps extends InputNumberProps {
   suffix?: string;
 }
 
+interface InputNumberAdjustEmits {
+  /**
+   * The field kept another value than the one typed, on leaving it or on
+   * Enter: clamped to `min` / `max`, or put on its `step`.
+   */
+  adjust: [adjustment: InputNumberAdjustment];
+}
+
+type InputNumberFieldEmits = InputNumberEmits & InputNumberAdjustEmits;
+
 const props = defineProps<InputNumberFieldProps>();
-const emits = defineEmits<InputNumberEmits>();
+const emits = defineEmits<InputNumberFieldEmits>();
 defineSlots<InputNumberSlots>();
 
 const forwarded = useForwardPropsEmits(props, emits);
 const inputProps = computed(() => {
-  const { suffix: _suffix, ...rest } = forwarded.value;
+  const { suffix: _suffix, onAdjust: _onAdjust, ...rest } = forwarded.value;
   return rest;
 });
 const { processI18n } = useTranslation();
+const { locale } = useI18n();
 
 // v2 number fields keep the value left-aligned with a compact caret stepper.
 const DEFAULT_ORIENTATION = "vertical";
@@ -41,6 +57,41 @@ function onIncomingText(event: InputEvent): void {
   const refusesNegative = props.min !== undefined && props.min >= 0;
   report(refusesNegative && text.includes("-") ? BELOW_MIN : undefined);
 }
+
+// What was typed since the field last settled, and the value it settled on.
+let typedText: string | null = null;
+let settledValue: number | null | undefined;
+
+function onTyped(event: Event): void {
+  typedText = (event.target as HTMLInputElement).value;
+  settledValue = undefined;
+}
+
+function onSettledValue(value: number | null | undefined): void {
+  settledValue = value;
+}
+
+// The number field keeps its own copy of the text typed, which it does not
+// always redraw when it settles on the value it already held (1020 typed
+// over 1,000): its `change` handler copies the kept value's text back.
+function redraw(input: HTMLInputElement): void {
+  input.dispatchEvent(new Event("change"));
+}
+
+/** Once the field applied the typed text: on leaving it, or on Enter. */
+async function settle(event: Event): Promise<void> {
+  if (typedText === null) return;
+  const text = typedText;
+  typedText = null;
+  const input = event.target as HTMLInputElement;
+  await nextTick();
+  const typed = parseTypedNumber(text, props.locale ?? locale.value);
+  const kept = settledValue === undefined ? props.modelValue : settledValue;
+  const adjustment = numberAdjustment(typed, kept, props);
+  if (!adjustment) return;
+  emits("adjust", adjustment);
+  redraw(input);
+}
 </script>
 
 <template>
@@ -49,9 +100,13 @@ function onIncomingText(event: InputEvent): void {
   <div
     :class="props.suffix ? 'flex items-center gap-2' : 'contents'"
     @beforeinput.capture="onIncomingText"
+    @input="onTyped"
+    @keydown.enter="settle"
   >
     <UInputNumber
       v-bind="{ ...inputProps, ...$attrs }"
+      @blur="settle"
+      @update:model-value="onSettledValue"
       :class="props.suffix && 'min-w-0 flex-1'"
       :orientation="props.orientation ?? DEFAULT_ORIENTATION"
       :increment="{ color: 'neutral' }"

package/frontend-vue/layers/dms-ui/app/components/guard/Guard.vue

@@ -13,7 +13,8 @@ import { notFoundTexts } from "../../build/utils/fetchNotFound";
 // `Guard` block (interface-dms `base/guard`): renders its children unchanged
 // unless a route says there is nothing for them, then one EmptyState (the
 // `fallback`, with the answer's `emptyState` laid over it) in their place.
-// `display: contents`, so the children lay out as if the guard were not there.
+// Several children stack with the room the page leaves between its blocks,
+// as in a tab: the page spaces the guard, not what it holds.
 interface GuardProps extends DefaultComponentProps {
   fetchUrl?: string;
   fetchUrlMethod?: string;
@@ -67,7 +68,7 @@ const fallback = computed<GuardFallback | null>(() => {
 </script>
 
 <template>
-  <div class="contents" data-dms-guard>
+  <div class="space-y-6" data-dms-guard>
     <DmsEmptyStateBlock v-if="fallback" v-bind="fallback" />
     <slot v-else />
   </div>

package/frontend-vue/layers/dms-ui/app/components/tab/Tab.vue

@@ -3,8 +3,11 @@ import type { TabProps } from "../../composables/tab/types";
 import { type TabBadges, TabVariant } from "../../composables/tab/types/props";
 import { useChartFetch } from "../../composables/chart/useChartFetch";
 import { confirmLeave } from "../../build/composables/unsaved-changes/registry";
+import { useComposedText } from "../../../../dms-core/app/composables/translation/useComposedText";
+import type { BadgeProps } from "@nuxt/ui";
 
 const { processI18n } = useTranslation();
+const { processText } = useComposedText();
 
 const props = withDefaults(defineProps<TabProps>(), {
   // A tab set with nothing in it yet is a legitimate state — a page being
@@ -45,9 +48,24 @@ const countFormat = computed(() => new Intl.NumberFormat(locale.value));
 const COUNT_BADGE_CLASS =
   "rounded-[4px] bg-elevated px-[5px] py-px font-mono text-[10.5px] font-semibold tabular-nums text-dimmed ring-0 in-data-[state=active]:bg-primary/10 in-data-[state=active]:text-primary";
 
+type TabBadge = TabProps["items"][number]["badge"];
+
+// A badge written as text is a BlockText: a `$` key or a ComposedText is
+// written in the reader's language, a number as it is.
+function writtenBadge(
+  badge: TabBadge,
+): string | number | BadgeProps | undefined {
+  if (badge === undefined || typeof badge === "number") return badge;
+  if (typeof badge === "string" || "key" in badge) return processText(badge);
+  const { label } = badge;
+  return typeof label === "string"
+    ? { ...badge, label: processText(label) }
+    : badge;
+}
+
 function badgeOf(item: TabProps["items"][number]) {
   const fetched = fetchedBadges.value?.[item.slot];
-  if (fetched === undefined) return item.badge;
+  if (fetched === undefined) return writtenBadge(item.badge);
   return typeof fetched === "number"
     ? countFormat.value.format(fetched)
     : fetched;

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

@@ -827,6 +827,8 @@ const liveHold = useTableLiveHold({
   gate: () => liveGate,
   signals: {
     isRowOpen: () => openRowId.value !== undefined,
+    isSearching: () => !!effectiveGlobalFilter.value,
+    isSorted: () => !isSameSorting(effectiveSorting.value, defaultSortState),
     tableElement: () => tableRoot.value?.$el ?? null,
   },
 });
@@ -2102,9 +2104,15 @@ onMounted(() => {
     @duplicate="handleRowDuplicate"
     @edit="handleRowEdit"
   >
-    <template v-if="liveHold.newCount.value > 0" #notice>
+    <template
+      v-if="liveHold.newCount.value > 0 || liveHold.reason.value"
+      #notice
+    >
       <LiveHoldBanner
         :count="liveHold.newCount.value"
+        :reason="liveHold.reason.value"
+        :missed-label="liveHold.missedLabel"
+        :detail="liveHold.missedDetail.value"
         @show="liveHold.showNew"
       />
     </template>

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

@@ -64,6 +64,9 @@ export interface ChartSeries {
 
 export type ChartCurve = "smooth" | "straight" | "stepline";
 
+/** Mirror of `ChartLegendPosition`: where a chart draws its legend. */
+export type ChartLegendPosition = "top" | "bottom";
+
 /** Opt-in expansion of native Y bounds to include annotation lines and bands. */
 export interface ChartAutoYRange {
   /** Outward fraction of each bound's magnitude (or 1 at zero). Defaults to 0.08. */

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

@@ -3,6 +3,7 @@ import type {
   ChartAnnotation,
   ChartAutoYRange,
   ChartCurve,
+  ChartLegendPosition,
   ChartSeries,
   ChartType,
   ChartXAxis,
@@ -35,6 +36,7 @@ export interface UseApexChartInput {
   showGrid?: boolean;
   showTooltip?: boolean;
   showLegend?: boolean;
+  legendPosition?: ChartLegendPosition;
   smooth?: boolean;
   curve?: ChartCurve;
   stacked?: boolean;

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

@@ -1,7 +1,17 @@
 import type { InjectionKey } from "vue";
 
+/**
+ * A check a `Form` runs before each submit: `false` stops the submit before
+ * anything is sent. See `useEnclosingForm().addValidator`.
+ */
 export type FormValidator = () => boolean;
+
+/** Adds a {@link FormValidator} to a `Form`; returns its removal. */
 export type RegisterValidator = (validator: FormValidator) => () => void;
 
+/**
+ * What a `Form` provides to register a validator. Kept for the fields that
+ * inject it; a module's field calls `useEnclosingForm().addValidator`.
+ */
 export const FORM_VALIDATOR_KEY: InjectionKey<RegisterValidator> =
   Symbol("form-validator");

package/frontend-vue/layers/dms-ui/app/composables/form/useEnclosingForm.ts

@@ -0,0 +1,61 @@
+import { getCurrentScope, inject, onScopeDispose } from "vue";
+import { FORM_HANDLE_KEY } from "../../build/composables/form/enclosingForm";
+import type { FormValidator } from "./types/validation";
+
+/** The DMS `Form` a custom field is drawn in (see {@link useEnclosingForm}). */
+export interface EnclosingForm {
+  /**
+   * Submits the form as its save button does: the form validates its fields,
+   * runs the validators, then sends what changed. Resolves once the submit
+   * was handled; a refused one shows its errors as usual.
+   */
+  submit: () => Promise<void>;
+  /**
+   * Runs `validator` before each submit: answering `false` stops it, before
+   * anything is sent (and before the other validators). Removed when the
+   * calling component goes, or by calling the returned function.
+   */
+  addValidator: (validator: FormValidator) => () => void;
+  /**
+   * Brings a field of the form into view, by its id, and focuses its control:
+   * its first focusable part when the control is a group.
+   */
+  focusField: (fieldId: string) => Promise<void>;
+}
+
+/**
+ * The DMS `Form` the calling component is drawn in: what a custom field (an
+ * `inputComponent` of the module's own) needs of it without reading the DOM.
+ * `null` outside a `Form`.
+ *
+ * ```ts
+ * const form = useEnclosingForm();
+ * const { confirm } = useConfirm();
+ * // Ask before a save that deletes data; submit again once confirmed.
+ * form?.addValidator(() => {
+ *   if (!isLowered.value || isConfirmed) return true;
+ *   void confirm({ title: "Delete older logs?" }).then((accepted) => {
+ *     isConfirmed = accepted;
+ *     if (accepted) void form.submit();
+ *   });
+ *   return false;
+ * });
+ * ```
+ *
+ * A page opened on the anchor of a field (`/settings#retentionDays`, the
+ * field's id) scrolls to it and focuses it once the form is drawn, without
+ * any of this: `focusField` is for a link or a button inside the page.
+ */
+export function useEnclosingForm(): EnclosingForm | null {
+  const handle = inject(FORM_HANDLE_KEY, null);
+  if (!handle) return null;
+  return {
+    submit: handle.submit,
+    addValidator: (validator) => {
+      const remove = handle.registerValidator(validator);
+      if (getCurrentScope()) onScopeDispose(remove);
+      return remove;
+    },
+    focusField: handle.revealField,
+  };
+}

package/frontend-vue/layers/dms-ui/app/composables/global/searchShortcuts.ts

@@ -0,0 +1,24 @@
+/**
+ * Focuses a page's own search (⌘ / on macOS, Ctrl / elsewhere), so it never
+ * competes with "/" for the navigation search. `meta` is read as Ctrl off
+ * macOS by `defineShortcuts`. The shifted variant is the same physical keys
+ * on layouts where "/" needs Shift (AZERTY: Shift + :), which
+ * `defineShortcuts` would otherwise reject as an extra modifier.
+ */
+export const PAGE_SEARCH_SHORTCUTS = ["meta_/", "meta_shift_/"] as const;
+
+/**
+ * `defineShortcuts` map focusing a page's own search on ⌘ / or Ctrl /: the
+ * keys a custom page binds its search to, "/" being the navigation
+ * search's.
+ *
+ * @example
+ * ```ts
+ * defineShortcuts(buildPageSearchShortcuts(() => input.value?.focus()));
+ * ```
+ */
+export function buildPageSearchShortcuts(
+  focus: () => void,
+): Record<string, () => void> {
+  return Object.fromEntries(PAGE_SEARCH_SHORTCUTS.map((key) => [key, focus]));
+}

package/frontend-vue/layers/dms-ui/app/composables/live/usePageLive.ts

@@ -75,8 +75,9 @@ export interface PageLiveState {
  * const { isPaused, missedCount, resume, hold, release } = usePageLive();
  * ```
  *
- * A component that refetches on its own realtime topic need not use it:
- * built-in blocks with a `realtimeTopic` already follow the state.
+ * A component that refetches on its own realtime topic need not read it:
+ * `usePageLiveRefresh` gates its refresh as the built-in blocks with a
+ * `realtimeTopic` are.
  */
 export function usePageLive(): PageLiveState {
   const isPaused = computed(() => currentPageLive()?.isPaused.value ?? false);