@antelopejs/dms 0.12.1 → 0.13.0

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

@@ -1,4 +1,10 @@
-import { computed, getCurrentInstance, onMounted, type Ref } from "vue";
+import {
+  computed,
+  getCurrentInstance,
+  onMounted,
+  shallowRef,
+  type Ref,
+} from "vue";
 
 /** How keyboard hints are printed: macOS/iOS symbols, or PC key names. */
 export type KeyboardPlatform = "mac" | "other";
@@ -10,6 +16,12 @@ export type KeyboardPlatform = "mac" | "other";
  */
 export const KEYBOARD_PLATFORM_COOKIE = "dms-keyboard-platform";
 const KEYBOARD_PLATFORM_COOKIE_MAX_AGE = 60 * 60 * 24 * 365;
+/**
+ * The platform the server rendered the page's hints with, handed to the
+ * browser with the page: the cookie may change before every hint has
+ * hydrated.
+ */
+const RENDERED_KEYBOARD_PLATFORM_STATE = "dms-keyboard-platform-rendered";
 /** What the server renders before the browser has said otherwise. */
 export const DEFAULT_KEYBOARD_PLATFORM: KeyboardPlatform = "other";
 
@@ -91,12 +103,17 @@ function normalizePlatform(value: KeyboardPlatform): KeyboardPlatform {
 }
 
 /**
- * The keyboard platform every hint renders with, shared by all callers. The
- * server and the hydrating browser both start from the cookie, so their HTML
- * matches; once mounted, the browser detects its platform and, if the cookie
- * was wrong or missing, corrects it, which re-renders the hints in place and
- * lets the next server render get them right. Only labels follow it: the key
- * bindings themselves stay with `defineShortcuts`.
+ * The keyboard platform every hint renders with, shared by all callers.
+ *
+ * The server renders the cookie's platform and hands it to the browser with
+ * the page. A component the browser creates while it hydrates that page
+ * (`isDmsHydrating()`) renders it too, until its own `onMounted`: the first
+ * hint to mount corrects the cookie, and a hint hydrating after it (an async
+ * component) must still draw what the server drew. Once mounted, the browser
+ * detects its platform and, if the cookie was wrong or missing, corrects it,
+ * which re-renders the hints in place and lets the next server render get
+ * them right. Only labels follow it: the key bindings themselves stay with
+ * `defineShortcuts`.
  */
 export function useKeyboardPlatform() {
   const stored: Ref<KeyboardPlatform> = useDmsCookie<KeyboardPlatform>(
@@ -106,13 +123,23 @@ export function useKeyboardPlatform() {
       maxAge: KEYBOARD_PLATFORM_COOKIE_MAX_AGE,
     },
   );
-  if (getCurrentInstance()) {
+  const rendered = useDmsState<KeyboardPlatform>(
+    RENDERED_KEYBOARD_PLATFORM_STATE,
+    () => normalizePlatform(stored.value),
+    { transfer: true },
+  );
+  const inComponent = getCurrentInstance() !== null;
+  const hydrating = shallowRef(inComponent && isDmsHydrating());
+  if (inComponent) {
     onMounted(() => {
+      hydrating.value = false;
       const detected = detectKeyboardPlatform(window.navigator);
       if (stored.value !== detected) stored.value = detected;
     });
   }
-  const platform = computed(() => normalizePlatform(stored.value));
+  const platform = computed(() =>
+    normalizePlatform(hydrating.value ? rendered.value : stored.value),
+  );
   return {
     platform,
     isMac: computed(() => platform.value === "mac"),

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

@@ -94,7 +94,7 @@ function createExportToasts(
 ) {
   const toast = useToast();
   const { t } = useI18n();
-  const { processApiMessage } = useTranslation();
+  const { presentError } = useApiErrorPresenter();
   const { $authFetch } = useAuthFetch();
 
   function resolveLabels(
@@ -152,14 +152,13 @@ function createExportToasts(
 
   function buildRetryActions(
     opts: RunExportJobOptions,
-    labels: UseExportJobLabels,
     getCurrentToastId: () => string | number,
-  ): { label: string; onClick: () => void }[] | undefined {
+  ): ApiErrorAction[] | undefined {
     if (opts.retryable === false) return undefined;
     return [
       {
-        label: labels.retry,
-        onClick: () => {
+        labelKey: opts.labels?.retry ?? "dms.table.export.retry",
+        onSelect: () => {
           toast.remove(getCurrentToastId());
           void runJob(opts);
         },
@@ -170,39 +169,13 @@ function createExportToasts(
   function showFailure(
     toastId: string | number,
     opts: RunExportJobOptions,
-    labels: UseExportJobLabels,
-    error?: string,
-  ): string | number {
-    let newId: string | number = toastId;
-    newId = replaceProgressToast(toastId, {
-      color: Color.error,
-      icon: "i-ph-warning",
-      title: labels.errorTitle,
-      description: error ? processApiMessage(error) : labels.fallbackErrorTitle,
-      duration: EXPORT_TOAST_DURATION,
-      progress: true,
-      actions: buildRetryActions(opts, labels, () => newId),
+    error: unknown,
+  ): void {
+    presentError(error, {
+      fallbackKey: opts.labels?.errorTitle ?? "dms.table.export.error_title",
+      replaceToastId: toastId,
+      actions: buildRetryActions(opts, () => toastId),
     });
-    return newId;
-  }
-
-  function showError(
-    toastId: string | number,
-    opts: RunExportJobOptions,
-    labels: UseExportJobLabels,
-    error: Error,
-  ): string | number {
-    let newId: string | number = toastId;
-    newId = replaceProgressToast(toastId, {
-      color: Color.error,
-      icon: "i-ph-warning",
-      title: labels.fallbackErrorTitle,
-      description: processApiMessage(error.message),
-      duration: EXPORT_TOAST_DURATION,
-      progress: true,
-      actions: buildRetryActions(opts, labels, () => newId),
-    });
-    return newId;
   }
 
   return {
@@ -212,7 +185,6 @@ function createExportToasts(
     updateProgressToast,
     showSuccess,
     showFailure,
-    showError,
   };
 }
 
@@ -352,25 +324,10 @@ async function readExportStream(
   return new Blob(chunks as BlobPart[]);
 }
 
-function getErrorMessage(
-  error: Parameters<typeof apiErrorText>[0],
-): string | undefined {
-  // oxlint-disable-next-line anti-slop/require-safety-comment-for-type-assertion -- These fields are not validated as strings; preserve optional property access, getter order, and truthy non-string forwarding for malformed errors.
-  const err = error as { data?: string; message?: string };
-  const data = err?.data;
-  const message = err?.message;
-  return data || message;
-}
-
 export const useExportJob = () => {
   const context = createExportToasts((opts) => runJob(opts));
-  const {
-    resolveLabels,
-    createExportToast,
-    showSuccess,
-    showFailure,
-    showError,
-  } = context;
+  const { resolveLabels, createExportToast, showSuccess, showFailure } =
+    context;
   const {
     startJob,
     resolveStatusUrl,
@@ -404,10 +361,7 @@ export const useExportJob = () => {
       );
       showSuccess(exportToast.id, labels);
     } catch (error) {
-      const message = getErrorMessage(error);
-      if (message) showFailure(exportToast.id, opts, labels, message);
-      // oxlint-disable-next-line anti-slop/require-safety-comment-for-type-assertion -- Rejections are not checked as Error; retain showError's existing message access and failure behavior for malformed values.
-      else showError(exportToast.id, opts, labels, error as Error);
+      showFailure(exportToast.id, opts, error);
     }
   }
 

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

@@ -0,0 +1,13 @@
+import { useKeyboardPlatform } from "../composables/global/keyboardPlatform";
+
+/**
+ * Nuxt UI's key hints (`<UKbd value="meta">`, the `kbds` of its menus, the
+ * dashboard search button) print `meta`, `ctrl` and `alt` for the keyboard
+ * platform the dashboard's own hints use: the cookie's, read in each hint's
+ * setup, so a hint hydrating the server's page keeps the platform the server
+ * printed until it is mounted (`useKeyboardPlatform`). Without it they print
+ * a blank on the server and fill it in once mounted.
+ */
+export default defineDmsPlugin(({ vueApp }) => {
+  provideDmsKbdPlatform(vueApp, () => useKeyboardPlatform().platform);
+});

package/frontend-vue/layers/dms-ui/i18n/locales/ui-en-GB.json

@@ -748,6 +748,7 @@
       "not_found_hint": "What this shows doesn’t exist, or no longer does."
     },
     "action_error": {
+      "fields": "{summary}",
       "forbidden": "You don’t have permission to do this.",
       "generic": "Something went wrong and the action couldn’t be completed. Try again."
     },

package/frontend-vue/layers/dms-ui/i18n/locales/ui-fr-FR.json

@@ -748,6 +748,7 @@
       "not_found_hint": "Ce qui est affiché ici n’existe pas, ou plus."
     },
     "action_error": {
+      "fields": "{summary}",
       "forbidden": "Vous n’avez pas l’autorisation d’effectuer cette action.",
       "generic": "Une erreur est survenue et l’action n’a pas pu aboutir. Réessayez."
     },

package/frontend-vue/package.json

@@ -18,9 +18,7 @@
     "test": "vitest run",
     "format": "prettier --write .",
     "lint": "node scripts/check-invariants.mjs && node scripts/check-disable-blocks.mjs && eslint .",
-    "lint:fix": "eslint . --fix",
-    "frontend:build": "ajs dms build -b http://127.0.0.1:5010",
-    "frontend:start": "ajs dms start -p 3001"
+    "lint:fix": "eslint . --fix"
   },
   "dependencies": {
     "@codemirror/autocomplete": "^6.18.6",

package/frontend-vue/scripts/check-api-error-presentation.mjs

@@ -0,0 +1,242 @@
+import { readdirSync, readFileSync, existsSync, statSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const PRESENTER = fileURLToPath(
+  new URL(
+    "../layers/dms-core/app/composables/useApiErrorPresenter.ts",
+    import.meta.url,
+  ),
+);
+const SKIP = new Set(["node_modules", "dist", "tests", "test", "fixtures"]);
+
+function dependencies(root) {
+  let directory = resolve(root);
+  if (!statSync(directory).isDirectory()) directory = dirname(directory);
+  while (!existsSync(join(directory, "package.json"))) {
+    const parent = dirname(directory);
+    if (parent === directory) throw new Error(`No package.json above ${root}`);
+    directory = parent;
+  }
+  try {
+    const require = createRequire(join(directory, "package.json"));
+    return {
+      ts: require("typescript"),
+      parse: require("vue/compiler-sfc").parse,
+    };
+  } catch (error) {
+    throw new Error(
+      `Install typescript and vue in ${directory} to check API error presentation`,
+      { cause: error },
+    );
+  }
+}
+
+/** Runtime sources only. Test fixtures and generated directories are excluded. */
+export function apiErrorSources(root) {
+  if (!statSync(root).isDirectory()) return [resolve(root)];
+  return readdirSync(root, { withFileTypes: true }).flatMap((entry) => {
+    if (entry.name.startsWith(".") || SKIP.has(entry.name)) return [];
+    const path = join(root, entry.name);
+    if (entry.isDirectory()) return apiErrorSources(path);
+    return /\.(?:vue|[cm]?tsx?)$/.test(entry.name) &&
+      !/\.(?:test|spec|d)\.ts$/.test(entry.name)
+      ? [resolve(path)]
+      : [];
+  });
+}
+
+/** Parses both Vue script blocks without treating template text as JavaScript. */
+export function apiErrorScripts(file, source, tools) {
+  if (!file.endsWith(".vue")) return [{ source, offset: 0 }];
+  const { descriptor, errors } = tools.parse(source, { filename: file });
+  if (errors.length)
+    throw new Error(`Cannot parse ${file}: ${errors.join(", ")}`);
+  return [descriptor.script, descriptor.scriptSetup]
+    .filter(Boolean)
+    .map((block) => ({
+      source: block.content,
+      offset: block.loc.start.offset,
+      isSetup: block === descriptor.scriptSetup,
+    }));
+}
+
+function bindingsOf(tree, ts) {
+  const bindings = new Map();
+  const visit = (node) => {
+    if (ts.isVariableDeclaration(node) && node.initializer) {
+      if (ts.isIdentifier(node.name))
+        bindings.set(node.name.text, node.initializer);
+      if (ts.isObjectBindingPattern(node.name)) {
+        for (const item of node.name.elements) {
+          if (ts.isIdentifier(item.name))
+            bindings.set(item.name.text, {
+              binding: item.propertyName?.getText(tree) ?? item.name.text,
+              owner: node.initializer,
+            });
+        }
+      }
+    }
+    ts.forEachChild(node, visit);
+  };
+  visit(tree);
+  return bindings;
+}
+
+/** Analyzes local toast bindings and failure regions. Cross-file effects are not inferred. */
+export function analyzeApiErrorScript(source, file, ts) {
+  const tree = ts.createSourceFile(
+    file,
+    source,
+    ts.ScriptTarget.Latest,
+    true,
+    ts.ScriptKind.TS,
+  );
+  const bindings = bindingsOf(tree, ts);
+  const unwrap = (node) => {
+    while (
+      node &&
+      (ts.isParenthesizedExpression(node) ||
+        ts.isAsExpression(node) ||
+        ts.isSatisfiesExpression(node) ||
+        ts.isNonNullExpression(node))
+    )
+      node = node.expression;
+    return node;
+  };
+  const resolveBinding = (node, seen = new Set()) => {
+    node = unwrap(node);
+    if (
+      node &&
+      ts.isIdentifier(node) &&
+      bindings.has(node.text) &&
+      !seen.has(node.text)
+    ) {
+      seen.add(node.text);
+      const next = bindings.get(node.text);
+      if (!next.binding) return resolveBinding(next, seen);
+    }
+    return node;
+  };
+  const isToast = (node) => {
+    node = resolveBinding(node);
+    return (
+      node &&
+      ((ts.isIdentifier(node) && node.text === "toast") ||
+        (ts.isCallExpression(node) &&
+          node.expression.getText(tree) === "useToast"))
+    );
+  };
+  const methodOf = (call) => {
+    const expression = unwrap(call.expression);
+    if (
+      ts.isPropertyAccessExpression(expression) &&
+      isToast(expression.expression) &&
+      ["add", "update"].includes(expression.name.text)
+    )
+      return expression.name.text;
+    if (ts.isIdentifier(expression)) {
+      const binding = bindings.get(expression.text);
+      if (
+        binding?.binding &&
+        isToast(binding.owner) &&
+        ["add", "update"].includes(binding.binding)
+      )
+        return binding.binding;
+    }
+    return null;
+  };
+  const colorOf = (payload) => {
+    payload = resolveBinding(payload);
+    if (!payload || !ts.isObjectLiteralExpression(payload)) return "dynamic";
+    if (payload.properties.some(ts.isSpreadAssignment)) return "dynamic";
+    const color = payload.properties.find(
+      (property) =>
+        property.name?.getText(tree).replace(/["']/g, "") === "color",
+    );
+    if (!color) return "neutral";
+    const value = resolveBinding(color.initializer);
+    if (!value) return "dynamic";
+    if (ts.isStringLiteral(value)) return value.text;
+    if (
+      ts.isPropertyAccessExpression(value) &&
+      value.expression.getText(tree) === "Color"
+    )
+      return value.name.text;
+    return "dynamic";
+  };
+  const calls = [];
+  const visit = (node, failure = null) => {
+    if (ts.isCatchClause(node)) {
+      visit(node.block, node.variableDeclaration?.name.getText(tree) ?? "");
+      return;
+    }
+    if (ts.isCallExpression(node)) {
+      const method = methodOf(node);
+      if (method) {
+        const payload = node.arguments[method === "update" ? 1 : 0];
+        const color = colorOf(payload);
+        if (color === "error" || (failure !== null && color !== "success"))
+          calls.push({ node, payload, method, failure, color, tree });
+      }
+      const expression = unwrap(node.expression);
+      if (
+        ts.isPropertyAccessExpression(expression) &&
+        ["catch", "then"].includes(expression.name.text)
+      ) {
+        const rejectionIndex = expression.name.text === "catch" ? 0 : 1;
+        visit(expression, failure);
+        node.arguments.forEach((argument, index) => {
+          const rejected =
+            index === rejectionIndex &&
+            (ts.isArrowFunction(argument) || ts.isFunctionExpression(argument));
+          visit(
+            argument,
+            rejected
+              ? (argument.parameters[0]?.name.getText(tree) ?? "")
+              : failure,
+          );
+        });
+        return;
+      }
+    }
+    ts.forEachChild(node, (child) => visit(child, failure));
+  };
+  visit(tree);
+  return calls;
+}
+
+/** Returns diagnostics for local failure toasts outside the canonical presenter. */
+export function checkApiErrorPresentation(roots) {
+  return roots.flatMap((root) => {
+    const tools = dependencies(root);
+    return apiErrorSources(resolve(root)).flatMap((file) => {
+      if (file === PRESENTER) return [];
+      const source = readFileSync(file, "utf8");
+      return apiErrorScripts(file, source, tools).flatMap((script) =>
+        analyzeApiErrorScript(script.source, file, tools.ts).map(({ node }) => {
+          const offset = script.offset + node.getStart();
+          const line = source.slice(0, offset).split("\n").length;
+          return `${file}:${line}: Use useApiErrorPresenter().presentError(error, { fallbackKey })`;
+        }),
+      );
+    });
+  });
+}
+
+/** Runs the checker with development dependencies resolved from each frontend root. */
+export function assertApiErrorPresentation(roots) {
+  const diagnostics = checkApiErrorPresentation(roots);
+  if (diagnostics.length) throw new Error(diagnostics.join("\n"));
+}
+
+if (
+  process.argv[1] &&
+  resolve(process.argv[1]) === fileURLToPath(import.meta.url)
+) {
+  const roots = process.argv.slice(2);
+  if (!roots.length)
+    throw new Error("Pass frontend app or layers directories to check");
+  assertApiErrorPresentation(roots);
+}

package/frontend-vue/scripts/check-invariants.mjs

@@ -4,6 +4,8 @@ import { dirname, join, relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { brotliDecompressSync } from "node:zlib";
 import { z } from "zod";
+import { assertApiErrorPresentation } from "./check-api-error-presentation.mjs";
+import "./test-api-error-presentation.mjs";
 import "./check-autoimport-boundaries.mjs";
 import "./test-autoimport-boundaries.mjs";
 import "./check-page-invariants.mjs";
@@ -12,6 +14,25 @@ import "../../../../checks/notification-tone-contract.mjs";
 const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 const LAYERS_DIR = join(ROOT, "layers");
 
+function checkCoreErrorFallback() {
+  for (const locale of ["en-GB", "fr-FR"]) {
+    const messages = JSON.parse(
+      readFileSync(
+        join(LAYERS_DIR, `dms-core/i18n/locales/core-${locale}.json`),
+        "utf8",
+      ),
+    );
+    assert.ok(
+      messages.error["500"].description.trim(),
+      `${locale}: always load error.500.description`,
+    );
+    assert.ok(
+      messages.error.read_only_demo.trim(),
+      `${locale}: translate error.read_only_demo`,
+    );
+  }
+}
+
 function collectSources(dir) {
   return readdirSync(dir, { withFileTypes: true }).flatMap((entry) => {
     const file = join(dir, entry.name);
@@ -334,6 +355,8 @@ function checkGeistNarrowSpace() {
 }
 
 for (const [name, check] of [
+  ["API error presentation", () => assertApiErrorPresentation([LAYERS_DIR])],
+  ["core error fallback", checkCoreErrorFallback],
   ["translated accessible names", checkAccessibleNames],
   ["layer plugin registration", checkPluginRegistration],
   ["compare mode labels", checkCompareModeLabels],