@antelopejs/dms 0.5.6 → 0.6.0

package/frontend-vue/layers/dms-core/app/composables/useFormValidation.ts

@@ -0,0 +1,209 @@
+import { type Ref, watch } from "vue";
+import type { ZodErrorMap, ZodType, ZodTypeDef } from "zod";
+import { resolveApiMessage } from "./translation/useTranslation";
+import { type ValidationIssue, validationIssueMessage } from "./useFieldErrors";
+
+/**
+ * Client-side checks of the hand-built forms (auth pages, onboarding,
+ * settings panels), worded like the DMS form: an empty required control says
+ * "This field is required.", a malformed one says why, under the control.
+ */
+
+/** A required control left empty. */
+export const REQUIRED_MESSAGE = "$dms.field_errors.required";
+/** A code entry (PIN cells) filled only in part. */
+export const CODE_INCOMPLETE_MESSAGE = "$dms.field_errors.code_incomplete";
+/** A new password that misses one of the listed rules. */
+export const PASSWORD_RULES_MESSAGE = "$dms.field_errors.password_rules";
+
+type Translate = (key: string, params?: Record<string, unknown>) => string;
+
+/** A UForm validation issue, as a Standard Schema reports it. */
+interface FormIssue {
+  message: string;
+  path?: PropertyKey[];
+}
+
+type FormValidationResult<Output> =
+  | { value: Output; issues?: undefined }
+  | { issues: FormIssue[] };
+
+/** A zod schema as the Standard Schema `UForm` validates with. */
+export interface LocalizedSchema<Output> {
+  "~standard": {
+    version: 1;
+    vendor: string;
+    validate: (value: unknown) => Promise<FormValidationResult<Output>>;
+  };
+}
+
+// Markup that is content on its own, without any text around it.
+const RICH_TEXT_MEDIA = /<(img|hr|iframe|video|audio|embed|object)\b/i;
+const HTML_TAG = /<[^>]*>/g;
+const HTML_SPACE = /&nbsp;|&#160;|\u00A0/g;
+
+/** Whether a rich-text document holds nothing: no text, no media. */
+export function isRichTextBlank(html: string): boolean {
+  if (RICH_TEXT_MEDIA.test(html)) return false;
+  return html.replace(HTML_TAG, "").replace(HTML_SPACE, " ").trim() === "";
+}
+
+/**
+ * Whether a value counts as "not filled": nothing, blanks, no item, a
+ * cleared number, an empty rich-text document (`<p></p>`, with
+ * `type` `rich_text`), or an object (address, date range, image,
+ * translations) whose every part is blank. `false` and `0` are values;
+ * inside an object a flag (an image's `principal`) is not content.
+ *
+ * @param type The DMS data type id of the value, when it changes the reading
+ */
+export function isBlankValue(value: unknown, type?: string): boolean {
+  if (value === undefined || value === null) return true;
+  if (typeof value === "string") {
+    return type === "rich_text" ? isRichTextBlank(value) : value.trim() === "";
+  }
+  if (typeof value === "number") return Number.isNaN(value);
+  if (value instanceof Date) return Number.isNaN(value.getTime());
+  if (Array.isArray(value)) {
+    return value.every((item) => isBlankValue(item, type));
+  }
+  if (typeof value === "object") {
+    return Object.values(value)
+      .filter((part) => typeof part !== "boolean")
+      .every((part) => isBlankValue(part, type));
+  }
+  return false;
+}
+
+/**
+ * The message key of a zod issue the schema left unworded: "required" for a
+ * blank value (zod would say the e-mail is malformed or the text too short),
+ * else the dashboard's wording of the issue code.
+ */
+export function formIssueMessage(
+  issue: ValidationIssue,
+  data: unknown,
+): string {
+  return isBlankValue(data) ? REQUIRED_MESSAGE : validationIssueMessage(issue);
+}
+
+const issueErrorMap: ZodErrorMap = (issue, context) => ({
+  message: formIssueMessage(issue, context.data),
+});
+
+/**
+ * Wraps a zod schema for `UForm`: issues the schema does not word itself get
+ * the dashboard's messages (translated), a `$key` message is translated, and
+ * a message already in prose is kept.
+ */
+export function localizeSchema<Output, Input>(
+  schema: ZodType<Output, ZodTypeDef, Input>,
+  translate: Translate,
+): LocalizedSchema<Output> {
+  const resolve = (message: string) =>
+    message.startsWith("$") ? resolveApiMessage(translate, message) : message;
+  return {
+    "~standard": {
+      version: 1,
+      vendor: "dms",
+      validate: async (value) => {
+        const result = await schema.safeParseAsync(value, {
+          errorMap: issueErrorMap,
+        });
+        return result.success
+          ? { value: result.data }
+          : {
+              issues: result.error.issues.map(({ message, path }) => ({
+                message: resolve(message),
+                path,
+              })),
+            };
+      },
+    },
+  };
+}
+
+/** {@link localizeSchema} with the current locale. */
+export function useLocalizedSchema<Output, Input>(
+  schema: ZodType<Output, ZodTypeDef, Input>,
+): LocalizedSchema<Output> {
+  const { t } = useI18n();
+  return localizeSchema(schema, (key, params = {}) => t(key, params));
+}
+
+/**
+ * The error of a code entry on submit: required when no cell is filled,
+ * incomplete when some are missing, none once every cell holds a digit.
+ *
+ * @returns A message key, or `undefined` for a complete code
+ */
+export function codeEntryError(
+  cells: ReadonlyArray<string | number | null | undefined> | undefined,
+  length: number,
+): string | undefined {
+  const code = (cells ?? []).map((cell) => String(cell ?? "").trim()).join("");
+  if (code === "") return REQUIRED_MESSAGE;
+  return code.length < length ? CODE_INCOMPLETE_MESSAGE : undefined;
+}
+
+/** The message key of a required value left empty, else `undefined`. */
+export function requiredError(value: unknown): string | undefined {
+  return isBlankValue(value) ? REQUIRED_MESSAGE : undefined;
+}
+
+/** What `UForm` exposes that {@link useLiveFormErrors} needs. */
+export interface LiveFormHandle {
+  getErrors: (name?: string) => ReadonlyArray<unknown>;
+  validate: (options: { name: string; silent: boolean }) => Promise<unknown>;
+}
+
+/**
+ * Re-checks a field in error as soon as its value changes. `UForm` only does
+ * it once the field was left: a field flagged on submit (and focused) would
+ * keep its message while the user fixes it. A field without an error is left
+ * alone, so nothing shows while typing before the first blur or submit.
+ *
+ * @param form The page's `UForm`
+ * @param state The form state, keyed by field name
+ */
+export function useLiveFormErrors(
+  form: Ref<LiveFormHandle | null | undefined>,
+  state: object,
+): void {
+  watch(
+    () => ({ ...state }) as Record<string, unknown>,
+    (current, previous) => {
+      const handle = form.value;
+      if (!handle) return;
+      for (const name of Object.keys(current)) {
+        if (current[name] === previous[name]) continue;
+        if (handle.getErrors(name).length === 0) continue;
+        void handle.validate({ name, silent: true }).catch(() => undefined);
+      }
+    },
+  );
+}
+
+/**
+ * Focuses the first control in error, in page order, after a failed submit.
+ * `UForm` disables its fields while it validates: the focus waits a task for
+ * them to be enabled again.
+ *
+ * @param errors The errors of the form (`UForm`'s `@error` event `errors`)
+ */
+export function focusFirstFormError(
+  errors: ReadonlyArray<{ id?: string }>,
+): void {
+  if (typeof document === "undefined") return;
+  setTimeout(() => {
+    const [first] = errors
+      .map((error) => (error.id ? document.getElementById(error.id) : null))
+      .filter((element): element is HTMLElement => !!element)
+      .sort((a, b) =>
+        a.compareDocumentPosition(b) & Node.DOCUMENT_POSITION_FOLLOWING
+          ? -1
+          : 1,
+      );
+    first?.focus();
+  });
+}

package/frontend-vue/layers/dms-core/app/composables/user/useRegionalFormat.ts

@@ -0,0 +1,65 @@
+import {
+  formatDate,
+  formatDateTime,
+  formatNumber,
+  formatPercentage,
+  formatPrice,
+  formatRelativeTime,
+  formatTime,
+} from "../../utils/formatter";
+import {
+  regionalDateTimeFormat,
+  type RegionalOptionsSettings,
+} from "../../utils/regional";
+
+type DateInput = Date | string | number | undefined | null;
+
+/**
+ * The shared formatters bound to the signed-in user's language and regional
+ * preferences (Settings › Language & region): the language of the interface,
+ * their time zone, clock and date format. Each call reads the current
+ * language, so a formatter used in a `computed` follows a language switch.
+ *
+ * The plain formatters (`formatDate`, `formatNumber`…) fall back to `en-US`
+ * when no locale is passed; these never need one.
+ */
+export function useRegionalFormat() {
+  const { t, locale } = useI18n();
+
+  return {
+    /** The language the values are written in. */
+    locale,
+    /**
+     * `new Intl.DateTimeFormat` in the user's language with their
+     * preferences applied, for a format the helpers below do not cover.
+     *
+     * @param options What the screen asks for; explicit options win
+     * @param settings `keepLocalZone` for calendar days computed in the browser
+     */
+    dateTimeFormat: (
+      options: Intl.DateTimeFormatOptions,
+      settings?: RegionalOptionsSettings,
+    ) => regionalDateTimeFormat(locale.value, options, settings),
+    /** A date ("1 October 2026" by default), `null` when it is not one. */
+    formatDate: (date: unknown, options?: Intl.DateTimeFormatOptions) =>
+      formatDate(date, locale.value, options),
+    /** A time ("14:05:00" by default), `null` when it is not a date. */
+    formatTime: (date: DateInput, options?: Intl.DateTimeFormatOptions) =>
+      formatTime(date, locale.value, options),
+    /** A date and its time, `null` when it is not a date. */
+    formatDateTime: (date: DateInput, options?: Intl.DateTimeFormatOptions) =>
+      formatDateTime(date, locale.value, options),
+    /** "just now", "5 minutes ago", "yesterday at 14:05", then the date. */
+    formatRelativeTime: (date: Date | string | number) =>
+      formatRelativeTime(date, t, locale.value),
+    /** A number; a value that is not one is returned as is. */
+    formatNumber: (value: unknown, options?: Intl.NumberFormatOptions) =>
+      formatNumber(value, locale.value, options),
+    /** An amount, in euros unless `options.currency` says otherwise. */
+    formatPrice: (value: unknown, options?: Intl.NumberFormatOptions) =>
+      formatPrice(value, locale.value, options),
+    /** A ratio as a percentage (`0.25` → "25%"). */
+    formatPercentage: (value: unknown, options?: Intl.NumberFormatOptions) =>
+      formatPercentage(value, locale.value, options),
+  };
+}

package/frontend-vue/layers/dms-core/app/composables/user/useUserRegionalPreferences.ts

@@ -0,0 +1,57 @@
+import {
+  browserTimeZone,
+  localeWeekStart,
+  readRegionalPreferences,
+  type RegionalPreferenceFields,
+  type RegionalPreferences,
+  type TimeFormatPreference,
+} from "../../utils/regional";
+
+const TWELVE_HOUR_CYCLES = ["h11", "h12"];
+
+/** The clock a locale uses on its own (`h12` for en-US, `h23` for fr-FR). */
+function localeTimeFormat(locale: string): TimeFormatPreference {
+  const { hourCycle } = new Intl.DateTimeFormat(locale, {
+    hour: "numeric",
+  }).resolvedOptions();
+  return TWELVE_HOUR_CYCLES.includes(hourCycle ?? "") ? "h12" : "h23";
+}
+
+/**
+ * The signed-in user's regional preferences (Settings › Language & region),
+ * and what they resolve to once the automatic ones are filled in: the
+ * browser's time zone, the language's first day of the week and clock.
+ *
+ * The shared formatters (`formatDate`, `formatDateTime`, the table date
+ * types, relative dates…) already apply them; this is for a screen that needs
+ * the values themselves, such as a calendar's `weekStartsOn`.
+ */
+export function useUserRegionalPreferences() {
+  const { user } = useUserSession<RegionalPreferenceFields>();
+  const { locale } = useI18n();
+
+  const preferences = computed<RegionalPreferences>(() =>
+    readRegionalPreferences(user.value),
+  );
+  const detectedTimeZone = browserTimeZone();
+  const timeZone = computed(
+    () => preferences.value.timeZone ?? detectedTimeZone,
+  );
+  const weekStartsOn = computed(
+    () => preferences.value.weekStart ?? localeWeekStart(locale.value),
+  );
+  const timeFormat = computed(
+    () => preferences.value.timeFormat ?? localeTimeFormat(locale.value),
+  );
+
+  return {
+    /** What the user chose; an unset field is automatic. */
+    preferences,
+    /** The zone the browser runs in, suggested while the zone is automatic. */
+    detectedTimeZone,
+    timeZone,
+    /** 0 Sunday … 6 Saturday, as calendars take it. */
+    weekStartsOn,
+    timeFormat,
+  };
+}

package/frontend-vue/layers/dms-core/app/types/confirm-dialog.ts

@@ -0,0 +1,68 @@
+/** One dependent a confirmed action affects, listed in its dialog. */
+export interface ConfirmDialogImpact {
+  icon: string;
+  /** `$`-prefixed: an i18n key, receiving the dialog's params. */
+  label: string;
+  count?: number | string;
+}
+
+/** A field the user fills in before confirming (a serialized form field). */
+export interface ConfirmDialogField {
+  id: string;
+  label?: string;
+  description?: string;
+  /** Id of the field's data type. */
+  type: string;
+  /** Input component drawing the field. */
+  component: ComponentInfo;
+  required?: boolean;
+  disabled?: boolean;
+  defaultValue?: unknown;
+}
+
+/** Colors of a confirmation dialog's confirm button and header well. */
+export type ConfirmDialogColor =
+  | "primary"
+  | "secondary"
+  | "success"
+  | "error"
+  | "warning"
+  | "info"
+  | "neutral";
+
+/**
+ * The dialog an action asks in before it runs (backend `ConfirmDialog`),
+ * the same for every action. Texts are i18n keys (with `$`) or literals,
+ * interpolated with `params` and, on a row action, the row's fields.
+ */
+export interface ConfirmDialog {
+  title: string;
+  description?: string;
+  params?: Record<string, unknown>;
+  icon?: string;
+  color?: ConfirmDialogColor;
+  confirmLabel?: string;
+  cancelLabel?: string;
+  impact?: ConfirmDialogImpact[];
+  /** The action cannot run: the dialog only explains why. */
+  blocked?: boolean;
+  /** Text the user must type to confirm. */
+  confirmText?: string;
+  /** Fields whose values are sent with the action's request. */
+  fields?: ConfirmDialogField[];
+  /** A component drawn in the dialog's body. */
+  component?: ComponentInfo;
+}
+
+/** A confirmation the server words: a URL answering a {@link ConfirmDialog}. */
+export interface ConfirmDialogFrom {
+  from: string;
+}
+
+/** The confirmation of an action (backend `confirm`). */
+export type ActionConfirm = ConfirmDialog | ConfirmDialogFrom;
+
+/** Whether a confirmation is worded by the server. */
+export const isConfirmFrom = (
+  confirm: ActionConfirm,
+): confirm is ConfirmDialogFrom => "from" in confirm;

package/frontend-vue/layers/dms-core/app/types/menu.ts

@@ -27,6 +27,18 @@ export interface DmsMenuItem extends NavigationMenuItem {
   fullId?: string;
   variant?: MenuItemVariant;
   status?: MenuItemStatus;
+  /**
+   * Set by "Preview as role" only, on an entry the previewed role could not
+   * open: the menu draws it hatched and locked. Never set outside a preview.
+   */
+  previewLocked?: boolean;
+  /**
+   * Set by "Preview as role" only: `hidden` on an entry the previewed role
+   * could not open (red hatch and lock), `partial` on one it opens without
+   * some of its blocks, actions or entries (orange hatch and lock). Never set
+   * outside a preview.
+   */
+  previewState?: "hidden" | "partial";
 }
 
 /** The route a menu is highlighted against. */

package/frontend-vue/layers/dms-core/app/types/row-action.ts

@@ -1,4 +1,5 @@
 import type { AnyFieldRule, FieldRule } from "./row-action-operators";
+import type { ActionConfirm } from "./confirm-dialog";
 
 export type FieldEqualsRule<
   T extends Record<string, unknown> = Record<string, unknown>,
@@ -48,4 +49,17 @@ export interface RowActionConfig<
   isEnabled?: boolean;
   isVisible?: boolean;
   rule?: RowActionRule<T>;
+  /** Label in place of the built-in one (`$`: i18n key). */
+  label?: string;
+  /** Icon in place of the built-in one. */
+  icon?: string;
+  /** Asked before the action runs: a fixed dialog, or `{ from }`. */
+  confirm?: ActionConfirm;
+  /**
+   * Delete, archive, restore: toast once the action succeeded, receiving
+   * `{ count }` (`$`: i18n key).
+   */
+  successMessage?: string;
+  /** Add: drawn in the page header instead of the toolbar. */
+  placement?: "toolbar" | "header";
 }

package/frontend-vue/layers/dms-core/app/utils/formatter.ts

@@ -1,3 +1,8 @@
+import {
+  currentRegionalPreferences,
+  regionalDateTimeFormat,
+  regionalDayNumber,
+} from "./regional";
 import { isNumber } from "./type-check";
 
 const DEFAULT_LOCALE = "en-US";
@@ -32,39 +37,39 @@ type RelativeTimeRule = {
   ) => string;
 };
 
-function isSameDay(date1: Date, date2: Date): boolean {
-  return (
-    date1.getFullYear() === date2.getFullYear() &&
-    date1.getMonth() === date2.getMonth() &&
-    date1.getDate() === date2.getDate()
-  );
+/** Whether `date` fell yesterday, in the user's time zone. */
+function isYesterday(date: Date): boolean {
+  return regionalDayNumber(date) === regionalDayNumber(new Date()) - 1;
 }
 
 function formatTimeHHMM(date: Date, locale: string): string {
-  return new Intl.DateTimeFormat(locale, {
+  return regionalDateTimeFormat(locale, {
     hour: "2-digit",
     minute: "2-digit",
   }).format(date);
 }
 
 function formatShortDate(date: Date, locale: string): string {
-  return new Intl.DateTimeFormat(locale, {
+  return regionalDateTimeFormat(locale, {
     day: "2-digit",
     month: "2-digit",
     year: "2-digit",
   }).format(date);
 }
 
-function formatTimeCompact(date: Date): string {
-  const hours = date.getHours();
-  const minutes = date.getMinutes().toString().padStart(2, "0");
-  return `${hours}h${minutes}`;
-}
-
-function getYesterday(): Date {
-  const yesterday = new Date();
-  yesterday.setDate(yesterday.getDate() - 1);
-  return yesterday;
+/** "14h05" on a 24-hour clock; the locale's own time on a 12-hour one. */
+function formatTimeCompact(date: Date, locale: string): string {
+  if (currentRegionalPreferences().timeFormat === "h12") {
+    return formatTimeHHMM(date, locale);
+  }
+  const parts = regionalDateTimeFormat(locale, {
+    hour: "numeric",
+    minute: "2-digit",
+    hourCycle: "h23",
+  }).formatToParts(date);
+  const read = (type: Intl.DateTimeFormatPartTypes) =>
+    parts.find((part) => part.type === type)?.value ?? "";
+  return `${Number(read("hour"))}h${read("minute")}`;
 }
 
 const RELATIVE_TIME_RULES: RelativeTimeRule[] = [
@@ -85,7 +90,7 @@ const RELATIVE_TIME_RULES: RelativeTimeRule[] = [
       t("common.time.hours_ago", { count: Math.floor(diffMs / TIME_UNITS.h) }),
   },
   {
-    condition: (_, targetDate) => isSameDay(targetDate, getYesterday()),
+    condition: (_, targetDate) => isYesterday(targetDate),
     format: (t, _, targetDate, locale) =>
       t("common.time.yesterday_at", {
         time: formatTimeHHMM(targetDate, locale),
@@ -110,7 +115,7 @@ export function formatRelativeTime(
   }
 
   return t("common.time.on_date", {
-    date: `${formatShortDate(targetDate, locale)} ${formatTimeCompact(targetDate)}`,
+    date: `${formatShortDate(targetDate, locale)} ${formatTimeCompact(targetDate, locale)}`,
   });
 }
 
@@ -149,7 +154,7 @@ export function formatDate(
       return null;
     }
 
-    return new Intl.DateTimeFormat(locale, formatOptions).format(validDate);
+    return regionalDateTimeFormat(locale, formatOptions).format(validDate);
   } catch {
     return null;
   }
@@ -215,40 +220,58 @@ export function formatPercentage(
   });
 }
 
-export function parseTimeSpan(value: string | number): number {
-  if (isNumber(value)) return Number(value);
-  const normalizedValue = value.trim();
-  if (!normalizedValue) return 0;
-
-  const UNIT_MAP: Record<string, keyof typeof TIME_UNITS> = {
-    y: "y",
-    M: "M",
-    mo: "M",
-    w: "w",
-    d: "d",
-    h: "h",
-    m: "m",
-    s: "s",
-    ms: "ms",
-  };
-
-  let totalMs = 0;
-  const regex = /(\d+(?:\.\d+)?)(ms|mo|[Mmwydhs])/g;
-
-  let match;
-  while ((match = regex.exec(normalizedValue)) !== null) {
-    const rawValue = match[1];
-    const unit = match[2];
-    if (!rawValue || !unit) continue;
-
-    const canonicalUnit = UNIT_MAP[unit];
-    if (!canonicalUnit || !(canonicalUnit in TIME_UNITS)) continue;
-
-    const numValue = Number.parseFloat(rawValue);
-    totalMs += numValue * TIME_UNITS[canonicalUnit as keyof typeof TIME_UNITS];
+const TIME_SPAN_UNITS: Record<string, keyof typeof TIME_UNITS> = {
+  y: "y",
+  M: "M",
+  mo: "M",
+  w: "w",
+  d: "d",
+  h: "h",
+  m: "m",
+  s: "s",
+  ms: "ms",
+};
+
+// `01:30`, `26:00:30`: hours, then minutes and seconds under 60.
+const CLOCK_SPAN = /^(\d+):([0-5]\d)(?::([0-5]\d))?$/;
+// `1h30m`, `1h 30m`, `1h:30m` (what `formatTimeSpan` writes), `1.5h`.
+const UNIT_SPAN = /^(?:\d+(?:\.\d+)?(?:ms|mo|[Mmwydhs])[\s:]*)+$/;
+const UNIT_SPAN_PART = /(\d+(?:\.\d+)?)(ms|mo|[Mmwydhs])/g;
+
+function readClockSpan(text: string): number | undefined {
+  const match = CLOCK_SPAN.exec(text);
+  if (!match) return undefined;
+  const [, hours, minutes, seconds] = match;
+  return (
+    Number(hours) * TIME_UNITS.h +
+    Number(minutes) * TIME_UNITS.m +
+    Number(seconds ?? 0) * TIME_UNITS.s
+  );
+}
+
+function readUnitSpan(text: string): number | undefined {
+  if (!UNIT_SPAN.test(text)) return undefined;
+  let total = 0;
+  for (const [, amount, unit] of text.matchAll(UNIT_SPAN_PART)) {
+    total += Number.parseFloat(amount!) * TIME_UNITS[TIME_SPAN_UNITS[unit!]!];
   }
+  return total;
+}
+
+/**
+ * A duration typed in, in milliseconds: a clock duration (`01:30`,
+ * `26:00:30`) or units (`1h30m`, `1h 30m`, `1.5h`), or `undefined` for a
+ * text that is neither.
+ */
+export function readTimeSpan(value: string): number | undefined {
+  const text = value.trim();
+  if (!text) return undefined;
+  return readClockSpan(text) ?? readUnitSpan(text);
+}
 
-  return totalMs;
+export function parseTimeSpan(value: string | number): number {
+  if (isNumber(value)) return Number(value);
+  return readTimeSpan(value) ?? 0;
 }
 
 const DEFAULT_SEPARATOR = ":";