@antelopejs/dms 0.9.8 → 0.10.0

package/frontend-vue/layers/dms-ui/app/build/composables/actions/rowComponentOptions.ts

@@ -0,0 +1,76 @@
+import {
+  interpolateRowText,
+  interpolateUrl,
+  namesRowField,
+} from "#dms-core/app/utils/url-interpolation";
+
+type Options = Record<string, unknown>;
+
+// An option holding a URL is named so (`fetchUrl`, `submitUrl`, `searchUrl`,
+// `to`): it is filled encoded, as an action's URL is. Any other text
+// (`rowId`, a title) takes the row's values as they are.
+const URL_OPTION = /(?:url|^to|^href)$/i;
+
+// Options naming rows of their own — a nested table's row actions, a source
+// table's `fetchRowUrl` — keep their `{{row.X}}` for those rows.
+const OWN_ROW_OPTIONS: ReadonlySet<string> = new Set([
+  "rowActions",
+  "fetchRowUrl",
+]);
+
+const isPlainObject = (value: unknown): value is Options =>
+  Object.prototype.toString.call(value) === "[object Object]";
+
+function fillValue(value: unknown, key: string, row: Options): unknown {
+  if (OWN_ROW_OPTIONS.has(key)) return value;
+  if (typeof value === "string") {
+    if (!namesRowField(value)) return value;
+    return URL_OPTION.test(key)
+      ? interpolateUrl(value, row)
+      : interpolateRowText(value, row);
+  }
+  if (Array.isArray(value))
+    return value.map((item) => fillValue(item, key, row));
+  if (isPlainObject(value)) return fillRowOptions(value, row);
+  return value;
+}
+
+/**
+ * The options a row's drawer, modal or side panel hands its component, with
+ * the row's `{{row.X}}` tokens filled, nested options included: a block
+ * declared on the backend (a `ResourceForm` reading `rowId: "{{row._id}}"`)
+ * then reads the row the container shows. `row` carries `id`, the row's id
+ * read through the table's `rowIdKey`. Filled anew for each row shown; a
+ * nested table's row actions keep theirs for their own rows.
+ */
+export function fillRowOptions(options: Options, row: Options): Options {
+  return Object.fromEntries(
+    Object.entries(options).map(([key, value]) => [
+      key,
+      fillValue(value, key, row),
+    ]),
+  );
+}
+
+/**
+ * The children of a container block (a Card, a VStack, a Tab) a row's
+ * drawer, modal or side panel shows, each child's options filled with the
+ * row as {@link fillRowOptions} fills the container's own, down the tree.
+ */
+export function fillRowChildren(
+  children: ComponentChild[],
+  row: Options,
+): ComponentChild[] {
+  return children.map((child) => ({
+    ...child,
+    component: {
+      ...child.component,
+      options: child.component.options
+        ? fillRowOptions(child.component.options as Options, row)
+        : child.component.options,
+      children: child.component.children
+        ? fillRowChildren(child.component.children, row)
+        : child.component.children,
+    },
+  }));
+}

package/frontend-vue/layers/dms-ui/app/build/composables/actions/rowNavigation.ts

@@ -1,17 +1,17 @@
 import { get } from "@nuxt/ui/runtime/utils/index.js";
+import { effectScope, shallowRef, watch } from "vue";
+import type { RowNavigation } from "../../../types/row-navigation";
 
 /**
- * What a drawer or modal opened on a row receives to step through the rows
- * the table shows (`navigation` prop): J and K do the same.
+ * Where a row stands among all the rows the table lists, under its current
+ * query, and the rows on each side of it.
  */
-export interface RowNavigation {
-  /** Position of the row among the rows shown, from 0. */
+export interface RowLocation {
+  /** From 0. */
   index: number;
   total: number;
-  hasPrev: boolean;
-  hasNext: boolean;
-  prev: () => void;
-  next: () => void;
+  prev?: Data;
+  next?: Data;
 }
 
 /** The rows a container steps through, in the order the table shows them. */
@@ -23,8 +23,29 @@ export interface RowNavigationSource {
    * container's `showRow` falls back to for a row the table does not list.
    */
   getRow?: (id: string) => Promise<Data | undefined>;
+  /** The table's count of rows, past the ones loaded; `rows` without it. */
+  total?: () => number | undefined;
+  /** Position of the first row loaded among all the rows (a page's start). */
+  offset?: () => number;
+  /**
+   * Moves the table to its next (`1`) or previous (`-1`) page, or grows a
+   * feed by one, and resolves once the rows are loaded; `false` when there is
+   * no such page or it could not be read. A step past the rows loaded turns
+   * it, so the table shows the row the container lands on.
+   */
+  loadAdjacent?: (step: RowStep) => Promise<boolean>;
+  /**
+   * Finds a row among all the rows the table lists, under its current query
+   * (a deep link to a row past the page loaded, a row live updates pushed
+   * out of it); `hint` is where it last stood. Undefined when it is not
+   * listed, or too far to look for.
+   */
+  locate?: (id: string, hint?: number) => Promise<RowLocation | undefined>;
 }
 
+/** A step through the rows: `1` to the next, `-1` to the previous. */
+export type RowStep = 1 | -1;
+
 /**
  * What a drawer, modal or side panel opened on a row receives to show
  * another row of the same table in its place (`showRow` prop): the row
@@ -37,32 +58,156 @@ export type ShowRow = (row: Data | string) => Promise<void>;
 const rowIdOf = (row: Data, rowIdKey: string): string =>
   String(get(row, rowIdKey));
 
+const loadedIndexOf = (source: RowNavigationSource, id: string): number =>
+  source
+    .rows()
+    .findIndex((candidate) => rowIdOf(candidate, source.rowIdKey) === id);
+
+/** Where the row stands, read from the rows loaded. */
+function loadedLocation(
+  source: RowNavigationSource,
+  id: string,
+): RowLocation | undefined {
+  const rows = source.rows();
+  const local = loadedIndexOf(source, id);
+  if (local < 0) return undefined;
+  const index = (source.offset?.() ?? 0) + local;
+  // The count can lag behind the rows (a row created since): never less.
+  const total = Math.max(source.total?.() ?? rows.length, index + 1);
+  return { index, total, prev: rows[local - 1], next: rows[local + 1] };
+}
+
+/** The navigation of a row at `location`. */
+function navigationAt(
+  source: RowNavigationSource,
+  location: RowLocation,
+  isLoaded: boolean,
+  step: (direction: RowStep) => () => void,
+): RowNavigation {
+  // A loaded row's neighbour past the rows loaded is reached by turning the
+  // page or locating the row; without either, the rows loaded are as far as
+  // the steps go. A located row has its neighbours with it.
+  const reachesPast = isLoaded && !!(source.loadAdjacent || source.locate);
+  const { index, total } = location;
+  return {
+    index,
+    total,
+    hasPrev: !!location.prev || (reachesPast && index > 0),
+    hasNext: !!location.next || (reachesPast && index < total - 1),
+    prev: step(-1),
+    next: step(1),
+  };
+}
+
 /**
- * The navigation of `row` among the rows shown; `go` opens another row in
- * its place. Undefined when the row is not among them (opened from a link).
+ * Follows the navigation of `row` among the rows of the table, calling
+ * `onChange` with it now and whenever it moves: the rows reloaded, live
+ * updates, the row found past the rows loaded (`locate`). Undefined while
+ * its position is unknown. A step goes to the open row's neighbour in the
+ * table's current order (`go`), found by the open row's id, never by a
+ * position the rows may have shifted from: past the rows loaded, it turns
+ * the table's page when it can, and asks `locate`. Returns the tracking's
+ * stop.
  */
-export function rowNavigation(
+export function trackRowNavigation(
   source: RowNavigationSource,
   row: Data,
   go: (row: Data) => void,
-): RowNavigation | undefined {
-  const rows = source.rows();
+  onChange: (navigation: RowNavigation | undefined) => void,
+): () => void {
   const id = rowIdOf(row, source.rowIdKey);
-  const index = rows.findIndex(
-    (candidate) => rowIdOf(candidate, source.rowIdKey) === id,
-  );
-  if (index < 0) return undefined;
-  const at = (position: number) => () => {
-    const target = rows[position];
-    if (target) go(target);
+  const located = shallowRef<RowLocation>();
+  let lastIndex: number | undefined;
+  let isStopped = false;
+  // Not found in the table's result (filtered out, too far): the rows moving
+  // do not read it again, a step still does.
+  let isUnlisted = false;
+  let locating: Promise<RowLocation | undefined> | undefined;
+
+  const locate = (): Promise<RowLocation | undefined> => {
+    if (!source.locate) return Promise.resolve(undefined);
+    // One read at a time: a second J, or a reload, waits for it.
+    locating ??= source
+      .locate(id, lastIndex)
+      .catch(() => undefined)
+      .then((found) => {
+        if (isStopped) return found;
+        located.value = found;
+        isUnlisted = !found;
+        return found;
+      })
+      .finally(() => {
+        locating = undefined;
+      });
+    return locating;
   };
-  return {
-    index,
-    total: rows.length,
-    hasPrev: index > 0,
-    hasNext: index < rows.length - 1,
-    prev: at(index - 1),
-    next: at(index + 1),
+
+  // The table's own copy of the row once it lists it.
+  const landOn = (target: Data) => {
+    if (isStopped) return;
+    const local = loadedIndexOf(source, rowIdOf(target, source.rowIdKey));
+    go(local < 0 ? target : source.rows()[local]!);
+  };
+
+  const neighbourOf = (direction: RowStep, location?: RowLocation) =>
+    direction > 0 ? location?.next : location?.prev;
+
+  const stepPast = async (direction: RowStep, loaded?: RowLocation) => {
+    const isTurned =
+      !!loaded &&
+      !!source.loadAdjacent &&
+      (await source.loadAdjacent(direction));
+    const target =
+      neighbourOf(direction, loadedLocation(source, id)) ??
+      neighbourOf(direction, await locate());
+    if (target) return landOn(target);
+    // Without a locator: the row at the next position among all, wherever
+    // the page turn put it.
+    if (!isTurned || !loaded) return;
+    const offset = source.offset?.() ?? 0;
+    const landed = source.rows()[loaded.index + direction - offset];
+    if (landed) landOn(landed);
+  };
+
+  const step = (direction: RowStep) => () => {
+    const loaded = loadedLocation(source, id);
+    const neighbour = neighbourOf(direction, loaded);
+    // Among the rows loaded: at once.
+    if (neighbour) return go(neighbour);
+    void stepPast(direction, loaded);
+  };
+
+  const scope = effectScope(true);
+  scope.run(() => {
+    watch(
+      () => {
+        const loaded = loadedLocation(source, id);
+        const location = loaded ?? located.value;
+        return location && navigationAt(source, location, !!loaded, step);
+      },
+      (navigation) => {
+        if (navigation) lastIndex = navigation.index;
+        onChange(navigation);
+      },
+      { immediate: true, flush: "sync" },
+    );
+    // Off the rows loaded (opened from a link, pushed out by live rows): its
+    // position comes from the table's whole result, read again as it moves.
+    watch(
+      () => [source.rows(), source.total?.()],
+      () => {
+        if (loadedIndexOf(source, id) >= 0) {
+          isUnlisted = false;
+          return;
+        }
+        if (!isUnlisted) void locate();
+      },
+      { immediate: true },
+    );
+  });
+  return () => {
+    isStopped = true;
+    scope.stop();
   };
 }