@antelopejs/dms 0.5.6 → 0.6.1

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

@@ -0,0 +1,74 @@
+import {
+  QUICK_ACTION_ADD,
+  QUICK_ACTION_BUTTON,
+  QUICK_ACTION_BUTTON_KEY,
+  QUICK_ACTION_COMPONENT_KEY,
+  QUICK_ACTION_QUERY_KEY,
+} from "../../types/quick-actions";
+
+type QuickActionTargetHandler = (target: QuickActionTarget) => unknown;
+
+const targetHandlers: Record<
+  QuickActionTarget["type"],
+  QuickActionTargetHandler
+> = {
+  navigate: (target) => {
+    if (target.type !== "navigate") return;
+    return navigateDms({ path: target.to, query: target.query });
+  },
+  // Routed rather than broadcast: the table view reads the intent from the
+  // query on mount, so the action works from any page — a window event would
+  // have to outrace the navigation it needs.
+  openForm: (target) => {
+    if (target.type !== "openForm") return;
+    return navigateDms({
+      path: target.to,
+      query: {
+        [QUICK_ACTION_QUERY_KEY]: QUICK_ACTION_ADD,
+        [QUICK_ACTION_COMPONENT_KEY]: target.component,
+      },
+    });
+  },
+  button: (target) => {
+    if (target.type !== "button") return;
+    return navigateDms({
+      path: target.to,
+      query: {
+        [QUICK_ACTION_QUERY_KEY]: QUICK_ACTION_BUTTON,
+        [QUICK_ACTION_COMPONENT_KEY]: target.component,
+        [QUICK_ACTION_BUTTON_KEY]: target.button,
+      },
+    });
+  },
+  event: (target) => {
+    if (target.type !== "event") return;
+    if (typeof window === "undefined") return;
+    window.dispatchEvent(
+      new CustomEvent(target.name, { detail: target.payload }),
+    );
+  },
+};
+
+/**
+ * Runs the client-side behavior a quick action declares through its
+ * discriminated `target`: `navigate`, `openForm` and `button` route to the
+ * action's page, `event` dispatches a window `CustomEvent` in place for whoever
+ * listens.
+ */
+export function dispatchQuickActionTarget(target: QuickActionTarget): unknown {
+  const handler = targetHandlers[target.type];
+  return handler?.(target);
+}
+
+/**
+ * The quick action a key names among those served to the user: its
+ * `category:id`, or its bare id when no other category uses it. Undefined for
+ * one the user is not served.
+ */
+export function findServedQuickAction(
+  served: Record<string, QuickActionInfo> | undefined,
+  key: string,
+): QuickActionInfo | undefined {
+  if (!served) return undefined;
+  return served[key] ?? Object.values(served).find((entry) => entry.id === key);
+}

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

@@ -0,0 +1,7 @@
+/**
+ * The mono uppercase label of the design (.eyebrow) at its 10.5px size, for
+ * the places `DmsEyebrow` cannot go: a theme slot, a `tv()` slot, a table
+ * head. Its colour is the caller's.
+ */
+export const EYEBROW_CLASS =
+  "font-mono text-[10.5px] font-semibold tracking-[0.12em] uppercase";

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

@@ -0,0 +1,60 @@
+/** A field whose input component carries options. */
+interface FieldWithOptions {
+  component: { options?: object };
+}
+
+type Translate = (key: string) => string;
+type Options = Record<string, unknown>;
+
+// Texts of an input component's options a reader sees: its placeholder, the
+// text beside a switch, a repeater's button and headers…
+const TEXT_OPTIONS = [
+  "placeholder",
+  "label",
+  "description",
+  "addLabel",
+  "keyLabel",
+  "valueLabel",
+] as const;
+// …and those of the entries of its lists: the options of a select, the
+// columns of a repeater.
+const LIST_OPTIONS = ["items", "columns"] as const;
+const ENTRY_TEXTS = ["label", "description"] as const;
+
+const isText = (value: unknown): value is string => typeof value === "string";
+
+function translateTexts(
+  source: Options,
+  keys: readonly string[],
+  processI18n: Translate,
+): Options {
+  const translated: Options = { ...source };
+  for (const key of keys) {
+    if (isText(source[key])) translated[key] = processI18n(source[key]);
+  }
+  return translated;
+}
+
+/**
+ * A field with the texts of its input component's options translated
+ * (`$`-prefixed i18n keys): placeholder, labels, descriptions, and those of
+ * its options and columns, the way forms show them.
+ */
+export function processFieldI18n<F extends FieldWithOptions>(
+  field: F,
+  processI18n: Translate,
+): F {
+  const opts = field.component.options as Options | undefined;
+  if (!opts) return field;
+
+  const options = translateTexts(opts, TEXT_OPTIONS, processI18n);
+  for (const key of LIST_OPTIONS) {
+    const list = opts[key];
+    if (!Array.isArray(list)) continue;
+    options[key] = list.map((entry: Options) =>
+      translateTexts(entry, ENTRY_TEXTS, processI18n),
+    );
+  }
+
+  return { ...field, component: { ...field.component, options } };
+}

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

@@ -0,0 +1,46 @@
+// Popover triggers that stand in for a field (date picker, cascader) are
+// outline UButtons: this restyles them onto the v2 field look of the input
+// theme (layers/dms-layout/app/theme/form-controls.ts), so a trigger never
+// differs from the text inputs around it.
+
+/** Classes of the trigger button itself. */
+export const FIELD_TRIGGER_CLASS = [
+  "h-8 gap-2 px-2.5 text-base/5 md:text-[13px] font-normal text-highlighted",
+  "bg-(--dms-bg-field) ring-accented shadow-(--shadow-xs)",
+  "hover:bg-(--dms-bg-field) hover:ring-(--dms-field-border-hover)",
+  "active:bg-(--dms-bg-field) active:scale-100",
+  "focus-visible:outline-3 focus-visible:outline-(--dms-accent-tint-strong) focus-visible:ring-primary",
+  "disabled:bg-(--dms-bg-muted) disabled:shadow-none",
+].join(" ");
+
+/** Slot classes: 16px dimmed icons, like the input's leading/trailing icons. */
+export const FIELD_TRIGGER_UI = {
+  leadingIcon: "size-4 text-dimmed",
+  trailingIcon: "size-4 text-dimmed ms-auto",
+};
+
+/** Icon closing a field trigger, as on v2 select triggers. */
+export const FIELD_TRIGGER_ICON = "i-ph-caret-up-down";
+
+/**
+ * An invalid trigger, as UFormField marks the inputs it wraps (color "error"
+ * plus highlight): the error border, kept on hover and focus, with the error
+ * halo. Applied after FIELD_TRIGGER_CLASS, it wins the merge.
+ */
+export const FIELD_TRIGGER_INVALID_CLASS =
+  "ring-error hover:ring-error focus-visible:ring-error focus-visible:outline-(--dms-error-tint)";
+
+/**
+ * The same on a bordered surface standing in for a field (rich-text editor,
+ * colour swatch, upload tile): the error border and focus halo. A plain
+ * element merges no classes, so it takes these instead of its own border
+ * colour, focus border and outline colour, never on top of them.
+ */
+export const FIELD_SURFACE_INVALID_CLASS =
+  "border-error hover:border-error focus-within:border-error has-focus-visible:border-error outline-(--dms-error-tint)";
+
+/**
+ * A field whose control has no border of its own (a tree, an inline
+ * calendar): an error ring around it.
+ */
+export const FIELD_RING_INVALID_CLASS = "rounded-lg ring-1 ring-error";

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

@@ -0,0 +1,33 @@
+// How a link target configured on a block is followed. Block options are plain
+// strings, so the kind is read off the string itself: an in-page anchor stays a
+// bare `<a href="#…">` (an Inertia visit would reload the page to scroll), an
+// absolute URL opens in a new tab, and everything else is a DMS route.
+
+export type LinkKind = "internal" | "anchor" | "external";
+
+const EXTERNAL_LINK_PATTERN = /^(?:[a-z][a-z\d+.-]*:|\/\/)/i;
+
+/** Where `to` leads: a DMS route, an anchor on this page, or another site. */
+export function linkKind(to: string): LinkKind {
+  if (to.startsWith("#")) return "anchor";
+  return EXTERNAL_LINK_PATTERN.test(to) ? "external" : "internal";
+}
+
+/** Attributes that open an external link safely in a new tab. */
+export const EXTERNAL_LINK_ATTRIBUTES = {
+  target: "_blank",
+  rel: "noopener noreferrer",
+} as const;
+
+/**
+ * Props for a `UButton` (or `ULink`) following `to`: an external target opens
+ * in a new tab, the others navigate in place.
+ */
+export function buttonLinkProps(
+  to: string | undefined,
+): Record<string, string> {
+  if (!to) return {};
+  return linkKind(to) === "external"
+    ? { to, ...EXTERNAL_LINK_ATTRIBUTES }
+    : { to };
+}

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

@@ -0,0 +1,21 @@
+const PLACEHOLDER = /\{(\w+)\}/g;
+
+const isFillable = (value: unknown): value is string | number | boolean =>
+  typeof value === "string" ||
+  typeof value === "number" ||
+  typeof value === "boolean";
+
+/**
+ * A literal (non-`$`) text with its `{name}` placeholders filled from
+ * `params`, as a `$` key's translation receives them. A placeholder without a
+ * value stays as written, so text that merely holds braces is left alone.
+ */
+export function interpolateLiteral(
+  text: string,
+  params: Record<string, unknown>,
+): string {
+  return text.replace(PLACEHOLDER, (placeholder, name: string) => {
+    const value = Object.hasOwn(params, name) ? params[name] : undefined;
+    return isFillable(value) ? String(value) : placeholder;
+  });
+}

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

@@ -0,0 +1,13 @@
+/**
+ * A count or a code in a small mono chip (v2 `.c-count`, `.c-code`): tab and
+ * group counts, an IP, an endpoint. Its size, weight and colours are the
+ * caller's; `bg-elevated` is its resting background.
+ */
+export const MONO_CHIP_CLASS = "rounded-[4px] px-[5px] py-px font-mono";
+
+/**
+ * A small mono uppercase tag (v2 `.cs-mod`): a module's tag on its card, a
+ * notification's source. Its frame and colours are the caller's.
+ */
+export const MONO_TAG_CLASS =
+  "rounded-[4px] px-1.5 font-mono text-[9.5px] font-semibold tracking-[0.08em] uppercase";

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

@@ -0,0 +1,6 @@
+/**
+ * Icon of an entry "Preview as role" locks, wherever it is drawn (sidebar,
+ * tabs, header and quick actions). Its hatch is the `dms-hatch-locked` /
+ * `dms-hatch-partial` utility of the layout stylesheet.
+ */
+export const PREVIEW_LOCK_ICON = "i-ph-lock-simple";

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

@@ -0,0 +1,54 @@
+import type { QuickActionIntent } from "../../types/quick-actions";
+
+/** Runs a quick-action intent (open the creation form, press a button). */
+export type QuickActionTargetRunner = (intent: QuickActionIntent) => void;
+
+/** A table view mounted on the page, able to answer quick actions. */
+export interface MountedQuickActionTarget {
+  /** Path of the page that mounted it. */
+  path: string;
+  /** Its component id, which quick actions and header buttons name. */
+  componentId: string;
+  run: QuickActionTargetRunner;
+}
+
+// Browser-only: table views register once mounted, so a server render never
+// adds to this module-wide set shared by every request.
+const mountedTargets = new Set<MountedQuickActionTarget>();
+
+/**
+ * Called by a table view once mounted: something on its own page (a header
+ * button) can then press its buttons in place, rather than through the URL.
+ *
+ * @returns The callback that unregisters it, to call on unmount
+ */
+export function registerQuickActionTarget(
+  target: MountedQuickActionTarget,
+): () => void {
+  mountedTargets.add(target);
+  return () => {
+    mountedTargets.delete(target);
+  };
+}
+
+/**
+ * Runs `intent` on the table view `componentId` of the page at `path`, if it
+ * is mounted. Pressing in place opens the form or modal on the click: the
+ * URL route (`quickAction` query) is only for a table view on another page,
+ * and costs two server visits.
+ *
+ * @returns Whether a mounted table view ran it
+ */
+export function runMountedQuickAction(
+  path: string,
+  componentId: string,
+  intent: QuickActionIntent,
+): boolean {
+  for (const target of mountedTargets) {
+    if (target.path === path && target.componentId === componentId) {
+      target.run(intent);
+      return true;
+    }
+  }
+  return false;
+}

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

@@ -0,0 +1,67 @@
+import { regionalDateTimeFormat } from "#dms-core/app/utils/regional";
+
+const SECOND_MS = 1000;
+const MINUTE_MS = 60 * SECOND_MS;
+const HOUR_MS = 60 * MINUTE_MS;
+const DAY_MS = 24 * HOUR_MS;
+const WEEK_MS = 7 * DAY_MS;
+const MONTH_MS = 30 * DAY_MS;
+const YEAR_MS = 365 * DAY_MS;
+
+interface RelativeUnit {
+  unit: Intl.RelativeTimeFormatUnit;
+  ms: number;
+  /** The unit applies below this elapsed time. */
+  below: number;
+}
+
+const RELATIVE_UNITS: RelativeUnit[] = [
+  { unit: "minute", ms: MINUTE_MS, below: HOUR_MS },
+  { unit: "hour", ms: HOUR_MS, below: DAY_MS },
+  { unit: "day", ms: DAY_MS, below: WEEK_MS },
+  { unit: "week", ms: WEEK_MS, below: MONTH_MS },
+  { unit: "month", ms: MONTH_MS, below: YEAR_MS },
+  { unit: "year", ms: YEAR_MS, below: Number.POSITIVE_INFINITY },
+];
+
+function capitalize(text: string): string {
+  return text ? `${text[0]!.toLocaleUpperCase()}${text.slice(1)}` : text;
+}
+
+/**
+ * "2 hr. ago", "Yesterday", "In 5 days": the distance between `date` and
+ * `now`, in the largest unit that keeps it a whole number, past or future.
+ */
+export function formatRelativeDate(
+  date: string | number | Date,
+  locale: string,
+  now: number = Date.now(),
+): string {
+  const deltaMs = new Date(date).getTime() - now;
+  const distance = Math.abs(deltaMs);
+  const unit =
+    RELATIVE_UNITS.find((candidate) => distance < candidate.below) ??
+    RELATIVE_UNITS[RELATIVE_UNITS.length - 1]!;
+  const value = Math.round(deltaMs / unit.ms);
+  const format = new Intl.RelativeTimeFormat(locale, {
+    numeric: "auto",
+    style: "short",
+  });
+  return capitalize(format.format(value, unit.unit));
+}
+
+/** "Sep 27": day and short month. */
+export function formatDayMonth(
+  date: string | number | Date,
+  locale: string,
+): string {
+  return regionalDateTimeFormat(locale, {
+    month: "short",
+    day: "numeric",
+  }).format(new Date(date));
+}
+
+/** First word of a name, for "Sep 27 · by Camille". */
+export function firstNameOf(name: unknown): string {
+  return typeof name === "string" ? (name.trim().split(/\s+/)[0] ?? "") : "";
+}

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

@@ -0,0 +1,20 @@
+/** What decides which rows a table lists, paging and order aside. */
+export interface SelectionScope {
+  columnFilters: readonly unknown[];
+  /** Filters the user does not edit: the active tab's, the URL's. */
+  hiddenFilters: readonly unknown[];
+  globalFilter?: string;
+}
+
+/**
+ * A key that changes when the set of rows a table lists does: its filters,
+ * its search or its tab. Paging and sorting move through the same set, so
+ * they keep it.
+ */
+export function selectionScopeKey(scope: SelectionScope): string {
+  return JSON.stringify([
+    scope.columnFilters,
+    scope.hiddenFilters,
+    scope.globalFilter ?? "",
+  ]);
+}

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

@@ -0,0 +1,7 @@
+/**
+ * The accent text link of the design (v2 `.au-link`, `.c-link`) for a link
+ * the ULink theme does not draw (a `DmsLink`, a button reading as a link):
+ * accent, 550, underlined on hover. Its size is the caller's.
+ */
+export const TEXT_LINK_CLASS =
+  "text-primary font-[550] hover:underline hover:underline-offset-[3px]";

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

@@ -0,0 +1,10 @@
+/**
+ * A bordered row on a stage card (an account to switch to, a next step): a
+ * 10px-rounded hairline box holding an icon or avatar and its text. Its
+ * vertical padding is the caller's.
+ */
+export const TILE_ROW_CLASS =
+  "border-default flex items-center gap-3 rounded-[10px] border px-3";
+
+/** A tile row the user picks: the hover tint and the accent hairline. */
+export const TILE_ROW_INTERACTIVE_CLASS = `${TILE_ROW_CLASS} hover:bg-elevated transition-colors hover:border-(--dms-accent-line)`;

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

@@ -0,0 +1,74 @@
+// Semantic tones shared by the generic v2 building blocks (IconWell,
+// StatusPill, EmptyState, CheckList). Tailwind needs literal class strings,
+// so every tone maps to a static record instead of `bg-${tone}` interpolation.
+// The tints and lines come from the v2 tokens (--dms-*-tint / --dms-*-line,
+// both themes) wherever one exists.
+
+import type { Tone } from "../../types/tone";
+
+const KNOWN_TONES = new Set<string>([
+  "neutral",
+  "primary",
+  "secondary",
+  "success",
+  "warning",
+  "error",
+  "info",
+]);
+
+/** True when `tone` is one of the semantic tones (not a custom color name). */
+export function isDmsTone(tone: string): tone is Tone {
+  return KNOWN_TONES.has(tone);
+}
+
+/** v2 .icon-well: the tone tint with an inset 1px line of the same tone. */
+export const DMS_TONE_WELL: Record<Tone, string> = {
+  neutral: "bg-elevated text-muted ring-(--ui-border-accented)",
+  primary: "bg-(--dms-accent-tint) text-primary ring-(--dms-accent-line)",
+  secondary: "bg-secondary/10 text-secondary ring-secondary/35",
+  success: "bg-(--dms-success-tint) text-success ring-(--dms-success-line)",
+  warning: "bg-(--dms-warning-tint) text-warning ring-(--dms-warning-line)",
+  error: "bg-(--dms-error-tint) text-error ring-(--dms-error-line)",
+  info: "bg-(--dms-info-tint) text-info ring-(--dms-info-line)",
+};
+
+/** v2 .status: the tone text on a soft tint of it. */
+export const DMS_TONE_SOFT: Record<Tone, string> = {
+  neutral: "bg-elevated text-muted",
+  primary: "bg-(--dms-accent-tint) text-primary",
+  secondary: "bg-secondary/12 text-secondary",
+  success: "bg-success/12 text-success",
+  warning: "bg-warning/12 text-warning",
+  error: "bg-error/12 text-error",
+  info: "bg-info/12 text-info",
+};
+
+/** Tone as a text color only. */
+export const DMS_TONE_TEXT: Record<Tone, string> = {
+  neutral: "text-muted",
+  primary: "text-primary",
+  secondary: "text-secondary",
+  success: "text-success",
+  warning: "text-warning",
+  error: "text-error",
+  info: "text-info",
+};
+
+/** Tone as a hairline border (outline pills). */
+export const DMS_TONE_OUTLINE: Record<Tone, string> = {
+  neutral: "border-(--ui-border-accented)",
+  primary: "border-(--dms-accent-line)",
+  secondary: "border-secondary/35",
+  success: "border-(--dms-success-line)",
+  warning: "border-(--dms-warning-line)",
+  error: "border-(--dms-error-line)",
+  info: "border-(--dms-info-line)",
+};
+
+/**
+ * The text color of a tone given as a plain string (a backend option); empty
+ * for a value that is no tone.
+ */
+export function toneTextClass(tone: string | undefined): string {
+  return tone && isDmsTone(tone) ? DMS_TONE_TEXT[tone] : "";
+}

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;
+}