@antelopejs/dms 0.6.0 → 0.6.1

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## v0.6.1
+
+[compare changes](https://github.com/AntelopeJS/dms/compare/v0.6.0...v0.6.1)
+
+### 🚀 Enhancements
+
+- **dms:** Resolve route tokens in block data URLs and refresh page blocks after an action ([#170](https://github.com/AntelopeJS/dms/pull/170))
+
+### 🏡 Chore
+
+- **release:** @antelopejs/interface-dms v0.4.1 ([224d341](https://github.com/AntelopeJS/dms/commit/224d341))
+
+### ❤️ Contributors
+
+- Antony Rizzitelli <rizzitelli.antony@pm.me>
+
 ## v0.6.0
 
 [compare changes](https://github.com/AntelopeJS/dms/compare/v0.5.6...v0.6.0)

package/frontend-vue/layers/dms-layout/app/build/components/layout/PageHeaderActionBar.vue

@@ -14,6 +14,7 @@ import { usePermissionPreview } from "#dms-core/app/build/composables/auth/usePe
 import { PREVIEW_LOCK_ICON } from "#dms-ui/app/build/utils/permissionPreview";
 import { runMountedQuickAction } from "#dms-ui/app/build/utils/quickActionTargets";
 import { useActionTargets } from "#dms-ui/app/build/composables/actions/useActionTargets";
+import { refreshPageBlocks } from "#dms-ui/app/utils/blockRefresh";
 import {
   dispatchQuickActionTarget,
   findServedQuickAction,
@@ -60,11 +61,14 @@ const router = useDmsRouter();
 const { $authFetch } = useAuthFetch();
 
 // The page header runs a declared button's target as a table runs its
-// toolbar buttons: confirmation, drawer, modal, API call, export, link.
+// toolbar buttons: confirmation, drawer, modal, API call, export, link. A
+// button that changed something (an API call, a form it opened) changes the
+// record the page shows: its blocks read their data again.
 const { handleCustomButton } = useActionTargets({
   api: $authFetch,
   componentId: "page-header",
   pageId: siteLayout.findMatchingRoute(route.path)?.metadata?.fullId ?? "page",
+  refreshCallback: refreshPageBlocks,
   handleApiError: (error, title) => useApiError(error, { title }),
 });
 

package/frontend-vue/layers/dms-ui/app/build/composables/blocks/registerBlockFunctions.ts

@@ -0,0 +1,7 @@
+import { BlockFunctions, refreshPageBlocks } from "../../../utils/blockRefresh";
+
+export function registerBlockFunctions() {
+  const { registerFunction } = useDefinedFunctions();
+
+  registerFunction(BlockFunctions.REFRESH_PAGE, () => refreshPageBlocks());
+}

package/frontend-vue/layers/dms-ui/app/build/composables/blocks/useBlockItems.ts

@@ -12,9 +12,15 @@ export interface BlockItemsResponse<T> {
 export interface UseBlockItemsOptions<T> {
   /** The items written in the block's options (read reactively). */
   items: () => T[] | undefined;
-  /** Route answering `{ items }`; when set it replaces the static items. */
+  /**
+   * Route answering `{ items }`; when set it replaces the static items. Its
+   * `{{params.X}}` and `{{query.X}}` tokens are filled from the page URL, and
+   * nothing is requested while one has no value (see useChartFetch).
+   */
   fetchUrl?: string;
   fetchUrlMethod?: string;
+  /** The parameters of the page route (the block's `routeParams` prop). */
+  routeParams?: () => Record<string, string> | undefined;
   watchActions?: WatchAction[];
   componentId?: string;
 }
@@ -31,8 +37,9 @@ export interface UseBlockItemsReturn<T> {
 /**
  * The items a list block (StatGroup, KeyValueList, NavCardGrid) renders:
  * either the static ones of its options, or the `items` its `fetchUrl`
- * answers with — refetched when a watched event changes the block's state,
- * like the KPI and top-list cards.
+ * answers with — refetched when a watched event changes the block's state or
+ * the page asks its blocks to refresh (refreshPageBlocks), like the KPI and
+ * top-list cards.
  */
 export function useBlockItems<T>(
   options: UseBlockItemsOptions<T>,
@@ -49,6 +56,7 @@ export function useBlockItems<T>(
   >({
     fetchUrl: options.fetchUrl,
     fetchUrlMethod: options.fetchUrlMethod,
+    routeParams: options.routeParams,
     watchSource: () => watchKey.value,
   });
 

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

@@ -1,5 +1,5 @@
 import type { LocationQueryValue } from "#dms/frontend-module";
-import { replaceUrlVariables } from "../../../composables/form/useForm";
+import { replaceUrlVariables } from "../../utils/urlVariables";
 
 type RouteQuery = Record<string, LocationQueryValue | LocationQueryValue[]>;
 

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

@@ -0,0 +1,63 @@
+// `{{params.id}}` takes the bare name, which on a route repeating a placeholder
+// is its last occurrence — the row id of a form page. The `:<n>` suffix reaches
+// 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;
+const RESPONSE_TOKEN = /\{\{response\.(\w+)\}\}/g;
+const TOKEN_OPENING = "{{";
+
+export interface ReplaceUrlVariablesContext {
+  routeParams?: Record<string, string>;
+  routeQuery: Record<string, unknown>;
+  response?: Record<string, unknown>;
+}
+
+/**
+ * Fills the `{{params.X}}`, `{{query.X}}` and (with a response)
+ * `{{response.X}}` tokens of a URL. A token with no value is left as written.
+ */
+export function replaceUrlVariables(
+  url: string,
+  context: ReplaceUrlVariablesContext,
+): string {
+  let processedUrl = url.replace(
+    PARAM_TOKEN,
+    (match, key) => context.routeParams?.[key] || match,
+  );
+
+  processedUrl = processedUrl.replace(QUERY_TOKEN, (match, key) => {
+    const value = context.routeQuery[key];
+    return typeof value === "string" ? value : match;
+  });
+
+  if (context.response) {
+    processedUrl = processedUrl.replace(RESPONSE_TOKEN, (match, key) => {
+      const value = context.response?.[key];
+      return typeof value === "string" || typeof value === "number"
+        ? String(value)
+        : match;
+    });
+  }
+
+  return processedUrl;
+}
+
+/** Whether a URL still names a token: written so, or left unresolved. */
+export function hasUrlVariables(url: string): boolean {
+  return url.includes(TOKEN_OPENING);
+}
+
+/**
+ * The URL with its tokens filled, or `undefined` while one is left: a URL
+ * naming a value the page does not carry is not a route, and must not be
+ * requested as one.
+ */
+export function resolveUrlVariables(
+  url: string | undefined,
+  context: ReplaceUrlVariablesContext,
+): string | undefined {
+  if (!url) return undefined;
+  const resolved = replaceUrlVariables(url, context);
+  return hasUrlVariables(resolved) ? undefined : resolved;
+}

package/frontend-vue/layers/dms-ui/app/components/activity-feed/ActivityFeed.vue

@@ -83,6 +83,7 @@ const {
   items: () => props.items,
   fetchUrl: props.fetchUrl,
   fetchUrlMethod: props.fetchUrlMethod,
+  routeParams: () => props.routeParams,
   watchActions: props.watchActions,
   componentId: props.componentId,
 });

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

@@ -56,6 +56,7 @@ const { items, isPending, hasError, refresh } = useBlockItems<KeyValueItem>({
   items: () => props.items,
   fetchUrl: props.fetchUrl,
   fetchUrlMethod: props.fetchUrlMethod,
+  routeParams: () => props.routeParams,
   watchActions: props.watchActions,
   componentId: props.componentId,
 });

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

@@ -87,6 +87,7 @@ const {
   items: () => props.items,
   fetchUrl: props.fetchUrl,
   fetchUrlMethod: props.fetchUrlMethod,
+  routeParams: () => props.routeParams,
   watchActions: props.watchActions,
   componentId: props.componentId,
 });

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

@@ -50,6 +50,7 @@ const { items, isPending, hasError, refresh } = useBlockItems<StatGroupItem>({
   items: () => props.items,
   fetchUrl: props.fetchUrl,
   fetchUrlMethod: props.fetchUrlMethod,
+  routeParams: () => props.routeParams,
   watchActions: props.watchActions,
   componentId: props.componentId,
 });

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

@@ -132,6 +132,7 @@ const isNested = computed(() => !!nestedContext);
 const { data, isLoading } = useChartFetch<ChartResponse>({
   fetchUrl: isNested.value ? undefined : props.fetchUrl,
   fetchUrlMethod: props.fetchUrlMethod,
+  routeParams: () => props.routeParams,
   periodScope: props.periodScope,
   realtimeTopic: props.realtimeTopic,
   staticData: null,

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

@@ -69,6 +69,7 @@ const watchKey = computed(() => JSON.stringify(watchState.value));
 const { data, isLoading } = useChartFetch<ChartCardResponse>({
   fetchUrl: props.fetchUrl,
   fetchUrlMethod: props.fetchUrlMethod,
+  routeParams: () => props.routeParams,
   periodScope: props.periodScope,
   watchSource: () => watchKey.value,
 });

package/frontend-vue/layers/dms-ui/app/components/kpi/KpiCard.vue

@@ -79,6 +79,7 @@ const staticData = computed<KpiCardResponse | null>(() => {
 const { data, isLoading, error, refresh } = useChartFetch<KpiCardResponse>({
   fetchUrl: props.fetchUrl,
   fetchUrlMethod: props.fetchUrlMethod,
+  routeParams: () => props.routeParams,
   periodScope: props.periodScope,
   staticData: () => staticData.value,
   watchSource: () => watchKey.value,

package/frontend-vue/layers/dms-ui/app/components/meter/MeterBlock.vue

@@ -76,6 +76,7 @@ const { state: watchState } = useWatch(
 const { data, isLoading, error, refresh } = useChartFetch<MeterResponse>({
   fetchUrl: props.fetchUrl,
   fetchUrlMethod: props.fetchUrlMethod,
+  routeParams: () => props.routeParams,
   watchSource: () => JSON.stringify(watchState.value),
 });
 

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

@@ -30,6 +30,7 @@ const { state: watchState } = useWatch(
 );
 const { data: fetchedBadges } = useChartFetch<TabBadges>({
   fetchUrl: props.badgesUrl,
+  routeParams: () => props.routeParams,
   watchSource: () => JSON.stringify(watchState.value),
 });
 const { locale } = useI18n();

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

@@ -108,6 +108,7 @@ const staticData = computed<TopListCardResponse | null>(() =>
 const { data, isLoading } = useChartFetch<TopListCardResponse>({
   fetchUrl: props.fetchUrl,
   fetchUrlMethod: props.fetchUrlMethod,
+  routeParams: () => props.routeParams,
   periodScope: props.periodScope,
   staticData: () => staticData.value,
   watchSource: () => watchKey.value,

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

@@ -1,13 +1,33 @@
-import { onMounted, ref, watch, type Ref } from "vue";
+import {
+  computed,
+  onBeforeUnmount,
+  onMounted,
+  ref,
+  watch,
+  type ComputedRef,
+  type Ref,
+} from "vue";
 import {
   appendPeriodToUrl,
   usePeriodScope,
 } from "../../../../dms-core/app/composables/period/usePeriodScope";
 import type { PeriodState } from "../../../../dms-core/app/composables/period/types";
 import { useRealtimeTopic } from "../../../../dms-core/app/composables/realtime/useRealtimeTopic";
+import {
+  hasUrlVariables,
+  resolveUrlVariables,
+} from "../../build/utils/urlVariables";
+import { onPageBlocksRefresh } from "../../utils/blockRefresh";
 
 export interface UseChartFetchOptions<T> {
+  /**
+   * Where the data is read from. `{{params.X}}` is filled from `routeParams`
+   * and `{{query.X}}` from the page URL's query, again when they change;
+   * nothing is requested while a token is left without a value.
+   */
   fetchUrl?: string;
+  /** The parameters of the page route (a block's `routeParams` prop). */
+  routeParams?: () => Record<string, string> | undefined;
   fetchUrlMethod?: string;
   periodScope?: string;
   realtimeTopic?: string | string[];
@@ -46,6 +66,13 @@ function buildFinalUrl(
   return appendPeriodToUrl(url, scopeState);
 }
 
+/** What one fetch requests. */
+interface FetchRequest {
+  url: string | undefined;
+  method: string | undefined;
+  periodScope: string | undefined;
+}
+
 interface FetchRunner {
   hasFetchedOnce: boolean;
   /** Inputs the last fetch was started for, to collapse duplicate triggers. */
@@ -61,16 +88,16 @@ type AuthFetcher = <T>(
 
 async function runFetch<T>(
   authFetch: AuthFetcher,
-  options: UseChartFetchOptions<T>,
+  request: FetchRequest,
   scopeState: PeriodState | null,
   runner: FetchRunner,
   data: Ref<T | null>,
   isLoading: Ref<boolean>,
   error: Ref<unknown>,
 ): Promise<void> {
-  if (!options.fetchUrl) return;
-  if (options.periodScope && !scopeState) return;
-  const url = buildFinalUrl(options.fetchUrl, scopeState, options.periodScope);
+  if (!request.url) return;
+  if (request.periodScope && !scopeState) return;
+  const url = buildFinalUrl(request.url, scopeState, request.periodScope);
   if (!url) return;
   if (runner.activeAbort) runner.activeAbort.abort();
   const controller = new AbortController();
@@ -79,7 +106,7 @@ async function runFetch<T>(
   error.value = null;
   try {
     const response = await authFetch<T>(url, {
-      method: options.fetchUrlMethod || DEFAULT_HTTP_METHOD,
+      method: request.method || DEFAULT_HTTP_METHOD,
       signal: controller.signal,
     });
     if (runner.activeAbort !== controller) return;
@@ -119,6 +146,34 @@ function subscribeRealtimeTopics(
   }
 }
 
+/**
+ * The URL to request: `fetchUrl` with its tokens filled, or `undefined` while
+ * one has no value. Only a URL naming a token reads the route.
+ */
+function useResolvedFetchUrl<T>(
+  options: UseChartFetchOptions<T>,
+): ComputedRef<string | undefined> {
+  const { fetchUrl } = options;
+  if (!fetchUrl || !hasUrlVariables(fetchUrl)) return computed(() => fetchUrl);
+  const route = useDmsRoute();
+  return computed(() =>
+    resolveUrlVariables(fetchUrl, {
+      routeParams: options.routeParams?.(),
+      routeQuery: route.query as Record<string, unknown>,
+    }),
+  );
+}
+
+// Mounted only: the page refresh is a browser event, and a block the server
+// renders has nothing to refetch.
+function subscribePageRefresh(onRefresh: () => void): void {
+  let unsubscribe: (() => void) | undefined;
+  onMounted(() => {
+    unsubscribe = onPageBlocksRefresh(onRefresh);
+  });
+  onBeforeUnmount(() => unsubscribe?.());
+}
+
 export function useChartFetch<T>(
   options: UseChartFetchOptions<T>,
 ): UseChartFetchReturn<T> {
@@ -130,7 +185,8 @@ export function useChartFetch<T>(
   // period-scoped card renders server-side with no scope and no data. Start
   // in the loading state so consumers show a skeleton instead of a hard zero
   // for the whole hydrate-then-fetch window.
-  const isLoading = ref(Boolean(options.fetchUrl));
+  const resolvedUrl = useResolvedFetchUrl(options);
+  const isLoading = ref(Boolean(resolvedUrl.value));
   const error = ref<unknown>(null);
   const scopeState = usePeriodScope(options.periodScope);
   const { $authFetch } = useAuthFetch();
@@ -144,7 +200,11 @@ export function useChartFetch<T>(
   const performFetch = () =>
     runFetch(
       $authFetch as AuthFetcher,
-      options,
+      {
+        url: resolvedUrl.value,
+        method: options.fetchUrlMethod,
+        periodScope: options.periodScope,
+      },
       scopeState.value,
       runner,
       data,
@@ -159,7 +219,7 @@ export function useChartFetch<T>(
   };
 
   const currentInputs = () =>
-    `${scopeState.value?.key ?? ""}|${JSON.stringify(options.watchSource?.() ?? null)}`;
+    `${resolvedUrl.value}|${scopeState.value?.key ?? ""}|${JSON.stringify(options.watchSource?.() ?? null)}`;
 
   const fetchScheduledInputs = () => {
     runner.pendingTimer = null;
@@ -182,7 +242,7 @@ export function useChartFetch<T>(
     const hadPending = runner.pendingTimer !== null;
     if (runner.pendingTimer) clearTimeout(runner.pendingTimer);
     runner.pendingTimer = null;
-    if (options.periodScope && !scopeState.value) {
+    if (!resolvedUrl.value || (options.periodScope && !scopeState.value)) {
       settleCancelledRefresh(hadPending);
       return;
     }
@@ -203,10 +263,11 @@ export function useChartFetch<T>(
   };
   const scheduleRefresh = () => scheduleRefreshWith(true);
 
-  // A realtime event means the data behind unchanged inputs moved, so it has
-  // to bypass the deduplication above. The inputs did not change, so the
-  // values on screen stay current until the new answer replaces them.
-  const refreshFromRealtime = () => {
+  // A realtime event or a page refresh (refreshPageBlocks) means the data
+  // behind unchanged inputs moved, so it has to bypass the deduplication
+  // above. The inputs did not change, so the values on screen stay current
+  // until the new answer replaces them.
+  const refreshSameInputs = () => {
     runner.lastInputs = null;
     scheduleRefreshWith(false);
   };
@@ -225,11 +286,12 @@ export function useChartFetch<T>(
 
   if (options.fetchUrl) {
     watch(
-      () => [scopeState.value?.key, options.watchSource?.()],
+      () => [resolvedUrl.value, scopeState.value?.key, options.watchSource?.()],
       scheduleRefresh,
     );
     onMounted(fetchOnMount);
-    subscribeRealtimeTopics(options.realtimeTopic, refreshFromRealtime);
+    subscribeRealtimeTopics(options.realtimeTopic, refreshSameInputs);
+    subscribePageRefresh(refreshSameInputs);
   } else if (typeof options.staticData === "function") {
     watch(
       () => readStaticData(options.staticData),

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

@@ -9,6 +9,17 @@ import type { FormField, FormFieldOrGroup } from "./types/field";
 import { isFieldGroup } from "./types/field";
 import { resolveResponseToast } from "../../build/utils/responseWarning";
 import { processFieldI18n } from "../../build/utils/fieldOptionsI18n";
+import {
+  type ReplaceUrlVariablesContext,
+  hasUrlVariables,
+  replaceUrlVariables,
+  resolveUrlVariables,
+} from "../../build/utils/urlVariables";
+
+export {
+  type ReplaceUrlVariablesContext,
+  replaceUrlVariables,
+} from "../../build/utils/urlVariables";
 
 /** A toast a submit response asks for, on top of the success one. */
 interface FormSubmitNotice {
@@ -135,47 +146,6 @@ function createBaseValidationSchema(
   }
 }
 
-// `{{params.id}}` takes the bare name, which on a route repeating a placeholder
-// is its last occurrence — the row id of a form page. The `:<n>` suffix reaches
-// 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;
-
-export interface ReplaceUrlVariablesContext {
-  routeParams?: Record<string, string>;
-  routeQuery: Record<string, unknown>;
-  response?: Record<string, unknown>;
-}
-
-export function replaceUrlVariables(
-  url: string,
-  context: ReplaceUrlVariablesContext,
-): string {
-  let processedUrl = url.replace(
-    PARAM_TOKEN,
-    (match, key) => context.routeParams?.[key] || match,
-  );
-
-  processedUrl = processedUrl.replace(/\{\{query\.(\w+)\}\}/g, (match, key) => {
-    const value = context.routeQuery[key];
-    return typeof value === "string" ? value : match;
-  });
-
-  if (context.response) {
-    processedUrl = processedUrl.replace(
-      /\{\{response\.(\w+)\}\}/g,
-      (match, key) => {
-        const value = context.response?.[key];
-        return typeof value === "string" || typeof value === "number"
-          ? String(value)
-          : match;
-      },
-    );
-  }
-
-  return processedUrl;
-}
-
 /** Where a submit goes, or what it lacks to go anywhere. */
 export type SubmitTarget = { url: string } | { missing: "url" | "token" };
 
@@ -191,8 +161,8 @@ export function resolveSubmitTarget(
   context: ReplaceUrlVariablesContext,
 ): SubmitTarget {
   if (!submitUrl) return { missing: "url" };
-  const url = replaceUrlVariables(submitUrl, context);
-  return url.includes("{{") ? { missing: "token" } : { url };
+  const url = resolveUrlVariables(submitUrl, context);
+  return url === undefined ? { missing: "token" } : { url };
 }
 
 function processBeforeStateMappers(
@@ -376,9 +346,9 @@ export function resolveSubmitDefaults(
 
   const resolved: Record<string, unknown> = {};
   for (const [key, value] of Object.entries(submitDefaults)) {
-    if (typeof value === "string" && value.includes("{{")) {
-      const replaced = replaceUrlVariables(value, context);
-      if (replaced.includes("{{")) continue;
+    if (typeof value === "string" && hasUrlVariables(value)) {
+      const replaced = resolveUrlVariables(value, context);
+      if (replaced === undefined) continue;
       resolved[key] = replaced;
     } else {
       resolved[key] = value;
@@ -622,11 +592,9 @@ export const useForm = (props: FormProps, options: UseFormOptions = {}) => {
     resolveSubmitDefaults(props.submitDefaults, buildUrlContext()),
   );
 
-  const resolvedFetchUrl = computed(() => {
-    if (!props.fetchUrl) return undefined;
-    const url = replaceUrlVariables(props.fetchUrl, buildUrlContext());
-    return url.includes("{{") ? undefined : url;
-  });
+  const resolvedFetchUrl = computed(() =>
+    resolveUrlVariables(props.fetchUrl, buildUrlContext()),
+  );
 
   // A form that loaded a record and does not create one (a duplicate posts
   // the loaded values as a new row) updates it: only its changes are sent.
@@ -638,11 +606,11 @@ export const useForm = (props: FormProps, options: UseFormOptions = {}) => {
     if (!props.fetchUrl) return undefined;
 
     try {
-      const processedUrl = replaceUrlVariables(
+      const processedUrl = resolveUrlVariables(
         props.fetchUrl,
         buildUrlContext(),
       );
-      if (processedUrl.includes("{{")) return undefined;
+      if (processedUrl === undefined) return undefined;
 
       const fetchedData = await $authFetch<FormFetchResponse>(processedUrl, {
         method: props.fetchUrlMethod || "GET",

package/frontend-vue/layers/dms-ui/app/plugins/register.ts

@@ -1,9 +1,11 @@
 import { registerDefaultDataTypes } from "../build/composables/data-types/registerDefaults";
 import { registerDefaultFunctions } from "../build/composables/table-view/registerDefaultFunctions";
 import { registerFormFunctions } from "../build/composables/form/registerFormFunctions";
+import { registerBlockFunctions } from "../build/composables/blocks/registerBlockFunctions";
 
 export default defineDmsPlugin(() => {
   registerDefaultDataTypes();
   registerDefaultFunctions();
   registerFormFunctions();
+  registerBlockFunctions();
 });

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

@@ -0,0 +1,28 @@
+/**
+ * The window event a data block (StatGroup, KeyValueList, NavCardGrid,
+ * ActivityFeed, KPI, top list, meter, chart, a tab set's badges) re-fetches
+ * on, keeping its values on screen until the new answer lands.
+ */
+export const BLOCK_REFRESH_EVENT = "DmsComponent.Block.Refresh";
+
+/** The watch functions every block can name (see interface-dms). */
+export const BlockFunctions = {
+  REFRESH_PAGE: "DmsComponent.Block.RefreshPage",
+} as const;
+
+/**
+ * Asks every data block mounted on the page to read its data again: what a
+ * component calls once an action of its own changed the record the page
+ * shows. The page header calls it after a button changed something.
+ */
+export function refreshPageBlocks(): void {
+  if (typeof window === "undefined") return;
+  window.dispatchEvent(new CustomEvent(BLOCK_REFRESH_EVENT));
+}
+
+/** Calls `handler` on each `refreshPageBlocks()`; returns the unsubscribe. */
+export function onPageBlocksRefresh(handler: () => void): () => void {
+  if (typeof window === "undefined") return () => {};
+  window.addEventListener(BLOCK_REFRESH_EVENT, handler);
+  return () => window.removeEventListener(BLOCK_REFRESH_EVENT, handler);
+}

package/frontend-vue/tests/block-page-refresh.test.ts

@@ -0,0 +1,128 @@
+// @vitest-environment jsdom
+/**
+ * Once an action changes the record a page shows, its data blocks read their
+ * data again in place: `refreshPageBlocks()` (or the `REFRESH_PAGE` watch
+ * function a form names) re-fetches every mounted block, keeps what it shows
+ * until the answer lands, and leaves an unmounted block alone.
+ */
+import { createApp, defineComponent, h, ref } from "vue";
+import { afterEach, beforeEach, expect, it, vi } from "vitest";
+import {
+  BlockFunctions,
+  refreshPageBlocks,
+} from "../layers/dms-ui/app/utils/blockRefresh";
+
+const requests: string[] = [];
+let answer = 1;
+
+vi.stubGlobal("useAuthFetch", () => ({
+  $authFetch: async (url: string) => {
+    requests.push(url);
+    return { value: answer };
+  },
+}));
+vi.stubGlobal("useDmsRoute", () => ({ query: {} }));
+vi.stubGlobal("ref", ref);
+
+const { useChartFetch } = await import(
+  "../layers/dms-ui/app/composables/chart/useChartFetch"
+);
+const { useDefinedFunctions } = await import(
+  "../layers/dms-core/app/composables/functions/useDefinedFunction"
+);
+vi.stubGlobal("useDefinedFunctions", useDefinedFunctions);
+const { registerBlockFunctions } = await import(
+  "../layers/dms-ui/app/build/composables/blocks/registerBlockFunctions"
+);
+
+// useChartFetch debounces every refresh past the first by 180ms.
+const SETTLE_MS = 250;
+const settle = () => new Promise((resolve) => setTimeout(resolve, SETTLE_MS));
+
+interface Probe {
+  data?: { value: { value: number } | null };
+  isLoading?: { value: boolean };
+}
+
+function mountBlock(fetchUrl: string) {
+  const probe: Probe = {};
+  const Block = defineComponent({
+    setup() {
+      const { data, isLoading } = useChartFetch<{ value: number }>({
+        fetchUrl,
+        routeParams: () => ({ id: "ws-1" }),
+      });
+      probe.data = data;
+      probe.isLoading = isLoading;
+      return () => h("div");
+    },
+  });
+  const app = createApp(Block);
+  app.mount(document.createElement("div"));
+  return { probe, unmount: () => app.unmount() };
+}
+
+const apps: Array<() => void> = [];
+
+beforeEach(() => {
+  requests.length = 0;
+  answer = 1;
+});
+
+afterEach(() => {
+  apps.splice(0).forEach((unmount) => unmount());
+});
+
+it("re-fetches every mounted block, keeping its values until the answer", async () => {
+  const facts = mountBlock("/api/ws/{{params.id}}/facts");
+  const counts = mountBlock("/api/ws/{{params.id}}/tab-counts");
+  apps.push(facts.unmount, counts.unmount);
+  await settle();
+  expect(requests).toEqual(["/api/ws/ws-1/facts", "/api/ws/ws-1/tab-counts"]);
+
+  answer = 2;
+  refreshPageBlocks();
+  expect(facts.probe.isLoading?.value).toBe(false);
+  expect(facts.probe.data?.value).toEqual({ value: 1 });
+  await settle();
+
+  expect(requests).toEqual([
+    "/api/ws/ws-1/facts",
+    "/api/ws/ws-1/tab-counts",
+    "/api/ws/ws-1/facts",
+    "/api/ws/ws-1/tab-counts",
+  ]);
+  expect(facts.probe.data?.value).toEqual({ value: 2 });
+});
+
+it("leaves an unmounted block alone", async () => {
+  const block = mountBlock("/api/ws/{{params.id}}/facts");
+  await settle();
+  block.unmount();
+  refreshPageBlocks();
+  await settle();
+  expect(requests).toEqual(["/api/ws/ws-1/facts"]);
+});
+
+it("does not request a URL whose token is unresolved", async () => {
+  const block = mountBlock("/api/ws/{{params.workspace}}/facts");
+  apps.push(block.unmount);
+  refreshPageBlocks();
+  await settle();
+  expect(requests).toEqual([]);
+});
+
+it("runs from the REFRESH_PAGE watch function", async () => {
+  registerBlockFunctions();
+  const block = mountBlock("/api/ws/{{params.id}}/facts");
+  apps.push(block.unmount);
+  await settle();
+
+  const refresh = useDefinedFunctions().getFunction(
+    BlockFunctions.REFRESH_PAGE,
+  );
+  expect(refresh).toBeTypeOf("function");
+  refresh?.();
+  await settle();
+  expect(requests).toEqual(["/api/ws/ws-1/facts", "/api/ws/ws-1/facts"]);
+});

package/frontend-vue/tests/block-route-params.test.ts

@@ -0,0 +1,190 @@
+// @vitest-environment jsdom
+/**
+ * A data block on a detail page reads the record of that page: the
+ * `{{params.X}}` / `{{query.X}}` tokens of its `fetchUrl` are filled from the
+ * page URL, again when it changes, and a URL with a token left unresolved is
+ * never requested.
+ */
+import {
+  type Component,
+  createApp,
+  defineComponent,
+  h,
+  nextTick,
+  reactive,
+  ref,
+} from "vue";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import {
+  replaceUrlVariables,
+  resolveUrlVariables,
+} from "../layers/dms-ui/app/build/utils/urlVariables";
+
+const requests: string[] = [];
+const route = reactive<{ query: Record<string, unknown> }>({ query: {} });
+
+vi.stubGlobal("useAuthFetch", () => ({
+  $authFetch: async (url: string) => {
+    requests.push(url);
+    return { items: [{ label: url }] };
+  },
+}));
+vi.stubGlobal("useDmsRoute", () => route);
+
+vi.mock("../layers/dms-core/app/composables/watch/useWatch", () => ({
+  useWatch: () => ({ state: ref({}) }),
+}));
+vi.mock(
+  "../layers/dms-core/app/composables/components/useComponentEvent",
+  () => ({ useComponentEvent: () => ({}) }),
+);
+
+const { useChartFetch } = await import(
+  "../layers/dms-ui/app/composables/chart/useChartFetch"
+);
+const { useBlockItems } = await import(
+  "../layers/dms-ui/app/build/composables/blocks/useBlockItems"
+);
+
+// useChartFetch debounces every refresh past the first by 180ms.
+const SETTLE_MS = 250;
+const settle = () => new Promise((resolve) => setTimeout(resolve, SETTLE_MS));
+
+const mounted: Array<{ unmount: () => void }> = [];
+
+function mount(component: Component) {
+  const app = createApp(component);
+  app.mount(document.createElement("div"));
+  mounted.push(app);
+}
+
+beforeEach(() => {
+  requests.length = 0;
+  route.query = {};
+});
+
+afterEach(() => {
+  mounted.splice(0).forEach((app) => app.unmount());
+});
+
+describe("resolveUrlVariables", () => {
+  it("fills route parameters and query values", () => {
+    expect(
+      resolveUrlVariables("/api/ws/{{params.id}}/facts?tab={{query.tab}}", {
+        routeParams: { id: "ws-1" },
+        routeQuery: { tab: "billing" },
+      }),
+    ).toBe("/api/ws/ws-1/facts?tab=billing");
+  });
+
+  it("reaches one occurrence of a repeated parameter", () => {
+    expect(
+      resolveUrlVariables("/api/ws/{{params.id:1}}/rows/{{params.id}}", {
+        routeParams: { id: "row-7", "id:1": "ws-1", "id:2": "row-7" },
+        routeQuery: {},
+      }),
+    ).toBe("/api/ws/ws-1/rows/row-7");
+  });
+
+  it("gives nothing while a token has no value", () => {
+    const context = { routeParams: {}, routeQuery: {} };
+    expect(resolveUrlVariables("/api/ws/{{params.id}}", context)).toBe(
+      undefined,
+    );
+    expect(replaceUrlVariables("/api/ws/{{params.id}}", context)).toBe(
+      "/api/ws/{{params.id}}",
+    );
+  });
+
+  it("leaves a URL without tokens as it is", () => {
+    expect(resolveUrlVariables("/api/plain", { routeQuery: {} })).toBe(
+      "/api/plain",
+    );
+  });
+});
+
+describe("useChartFetch with a templated fetchUrl", () => {
+  function mountFetch(
+    fetchUrl: string,
+    routeParams: () => Record<string, string> | undefined,
+  ) {
+    const state: { isLoading?: { value: boolean } } = {};
+    const Probe = defineComponent({
+      setup() {
+        const { isLoading } = useChartFetch<unknown>({ fetchUrl, routeParams });
+        state.isLoading = isLoading;
+        return () => h("div");
+      },
+    });
+    mount(Probe);
+    return state;
+  }
+
+  it("requests the URL of the page's record", async () => {
+    mountFetch("/api/ws/{{params.id}}/facts", () => ({ id: "ws-1" }));
+    await settle();
+    expect(requests).toEqual(["/api/ws/ws-1/facts"]);
+  });
+
+  it("requests nothing, and shows no skeleton, while a token is unresolved", async () => {
+    const state = mountFetch("/api/ws/{{params.id}}/facts", () => ({}));
+    await settle();
+    expect(requests).toEqual([]);
+    expect(state.isLoading?.value).toBe(false);
+  });
+
+  it("follows the route to another record", async () => {
+    const params = ref<Record<string, string>>({ id: "ws-1" });
+    mountFetch("/api/ws/{{params.id}}/facts", () => params.value);
+    await settle();
+    params.value = { id: "ws-2" };
+    await nextTick();
+    await settle();
+    expect(requests).toEqual(["/api/ws/ws-1/facts", "/api/ws/ws-2/facts"]);
+  });
+
+  it("fetches once a query value it waited for appears", async () => {
+    mountFetch("/api/activity?actor={{query.actor}}", () => ({}));
+    await settle();
+    expect(requests).toEqual([]);
+    route.query = { actor: "u-1" };
+    await nextTick();
+    await settle();
+    expect(requests).toEqual(["/api/activity?actor=u-1"]);
+  });
+});
+
+describe("useBlockItems with a templated fetchUrl", () => {
+  function mountItems(routeParams: Record<string, string>) {
+    const state: { items?: { value: unknown[] } } = {};
+    const Probe = defineComponent({
+      setup() {
+        const { items } = useBlockItems<{ label: string }>({
+          items: () => [{ label: "static" }],
+          fetchUrl: "/api/ws/{{params.id}}/billing-info",
+          routeParams: () => routeParams,
+        });
+        state.items = items;
+        return () => h("div");
+      },
+    });
+    mount(Probe);
+    return state;
+  }
+
+  it("lists the items of the page's record", async () => {
+    const state = mountItems({ id: "ws-1" });
+    await settle();
+    expect(requests).toEqual(["/api/ws/ws-1/billing-info"]);
+    expect(state.items?.value).toEqual([
+      { label: "/api/ws/ws-1/billing-info" },
+    ]);
+  });
+
+  it("shows its empty state, not the static items, without the record", async () => {
+    const state = mountItems({});
+    await settle();
+    expect(requests).toEqual([]);
+    expect(state.items?.value).toEqual([]);
+  });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@antelopejs/dms",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/AntelopeJS/dms.git"
@@ -37,7 +37,7 @@
     "@antelopejs/interface-data-api": ">=0.2.0 <1.0.0",
     "@antelopejs/interface-database": ">=0.1.8 <1.0.0",
     "@antelopejs/interface-database-decorators": ">=0.1.7 <1.0.0",
-    "@antelopejs/interface-dms": ">=0.4.0 <0.5.0",
+    "@antelopejs/interface-dms": ">=0.4.1 <0.5.0",
     "@antelopejs/interface-email": ">=0.0.5 <1.0.0",
     "@antelopejs/interface-file-storage": ">=0.1.3 <1.0.0",
     "archiver": "^7.0.1",

package/skills/dms/SKILL.md

@@ -32,6 +32,9 @@ For the framework underneath (the core, `ajs` CLI, interfaces as versioned contr
   `Grid`, `KpiCard`, … — fluent builders producing a **serializable description**, not live UI: the
   frontend renders it. **Components fetch their own data** via URLs (`fetchUrl`, `submitUrl`, …) —
   routes often declared `@Get`/`@Post` on the same page class; the backend stays the source of truth.
+  A URL names the record of its page with `{{params.id}}` / `{{query.X}}` (filled from the page URL;
+  nothing is fetched while one is unresolved), and `.watch(FormEvents.SUBMIT_SUCCESS,
+  BlockFunctions.REFRESH_PAGE)` makes the page's data blocks re-fetch after a form saves.
 - **It's interfaces all the way down.** Everything you consume from the DMS is an AntelopeJS
   interface imported as an `@antelopejs/interface-dms/...` subpath (see the imports below);
   a distributable module exposes its own from a companion `@antelopejs/interface-<name>` package listed in `antelopeJs.implements`.