@antelopejs/dms 0.0.1

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

@@ -0,0 +1,80 @@
+import type { ComputedRef } from "vue";
+import type {
+  ChartAnnotation,
+  ChartAutoYRange,
+  ChartCurve,
+  ChartSeries,
+  ChartType,
+  ChartXAxis,
+  ChartXAxisFormatter,
+  ComparisonStyle,
+  DonutRecord,
+} from "./types";
+
+export interface MixedSeriesDef {
+  name: string;
+  type: "line" | "area" | "column" | "rangeArea";
+  color?: string;
+}
+
+export interface ApexClickOpts {
+  dataPointIndex: number;
+  seriesIndex: number;
+}
+
+export type ApexClickHandler = (
+  event: unknown,
+  ctx: unknown,
+  opts: ApexClickOpts,
+) => void;
+
+export interface UseApexChartInput {
+  type: ChartType;
+  title?: string;
+  height?: string;
+  showGrid?: boolean;
+  showTooltip?: boolean;
+  showLegend?: boolean;
+  smooth?: boolean;
+  curve?: ChartCurve;
+  stacked?: boolean;
+  annotations?: ChartAnnotation[];
+  autoYRange?: ChartAutoYRange;
+  syncGroup?: string;
+  chartId?: string;
+  comparisonStyle?: ComparisonStyle;
+  comparisonSeriesCount?: number;
+  series: ChartSeries[];
+  donutData?: DonutRecord[];
+  colors?: string[] | string;
+  rawOptions?: Array<{ key: string; value: string }>;
+  themeRevision?: number;
+  yRange?: { min: number; max: number };
+  strokeWidth?: number;
+  fillOpacity?: number;
+  barWidth?: number;
+  columnWidth?: number;
+  roundedCorners?: boolean;
+  orientation?: "horizontal" | "vertical";
+  centralLabel?: string;
+  centralSubLabel?: string;
+  arcWidth?: number;
+  hollowSize?: string;
+  showTotal?: boolean;
+  shadeIntensity?: number;
+  distributed?: boolean;
+  seriesDefs?: MixedSeriesDef[];
+  pointSize?: number;
+  showLabels?: boolean;
+  xaxisType?: "category" | "datetime" | "numeric";
+  xAxis?: ChartXAxis;
+  xAxisFormatter?: ChartXAxisFormatter;
+  yAxisFormatter?: (value: number) => string;
+  onDataPointClick?: ApexClickHandler;
+}
+
+export interface UseApexChartOutput {
+  apexType: ComputedRef<string>;
+  options: ComputedRef<Record<string, unknown>>;
+  series: ComputedRef<unknown>;
+}

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

@@ -0,0 +1,204 @@
+import { onMounted, ref, watch, 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";
+
+export interface UseChartFetchOptions<T> {
+  fetchUrl?: string;
+  fetchUrlMethod?: string;
+  periodScope?: string;
+  realtimeTopic?: string | string[];
+  watchSource?: () => unknown;
+  staticData?: T | null | (() => T | null);
+}
+
+export interface UseChartFetchReturn<T> {
+  data: Ref<T | null>;
+  isLoading: Ref<boolean>;
+  error: Ref<unknown>;
+  refresh: () => Promise<void>;
+}
+
+const DEBOUNCE_FRAME_MS = 180;
+const DEFAULT_HTTP_METHOD = "GET";
+// Matches usePeriodScope's own grace period before it warns about a missing
+// scope: past it, a card whose scope never registered stops claiming to load.
+const PENDING_SCOPE_GRACE_MS = 250;
+
+function buildFinalUrl(
+  url: string | undefined,
+  scopeState: PeriodState | null,
+  scope: string | undefined,
+): string | undefined {
+  if (!url) return url;
+  if (!scope) return url;
+  return appendPeriodToUrl(url, scopeState);
+}
+
+interface FetchRunner {
+  hasFetchedOnce: boolean;
+  /** Inputs the last fetch was started for, to collapse duplicate triggers. */
+  lastInputs: string | null;
+  pendingTimer: ReturnType<typeof setTimeout> | null;
+  activeAbort: AbortController | null;
+}
+
+type AuthFetcher = <T>(
+  url: string,
+  opts: { method: string; signal: AbortSignal },
+) => Promise<T>;
+
+async function runFetch<T>(
+  authFetch: AuthFetcher,
+  options: UseChartFetchOptions<T>,
+  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 (!url) return;
+  if (runner.activeAbort) runner.activeAbort.abort();
+  runner.activeAbort = new AbortController();
+  isLoading.value = true;
+  error.value = null;
+  try {
+    data.value = await authFetch<T>(url, {
+      method: options.fetchUrlMethod || DEFAULT_HTTP_METHOD,
+      signal: runner.activeAbort.signal,
+    });
+  } catch (err) {
+    if ((err as { name?: string })?.name !== "AbortError") error.value = err;
+  } finally {
+    isLoading.value = false;
+  }
+}
+
+function readStaticData<T>(
+  source: UseChartFetchOptions<T>["staticData"],
+): T | null {
+  if (typeof source === "function") return (source as () => T | null)();
+  return source ?? null;
+}
+
+function subscribeRealtimeTopics(
+  topic: string | string[] | undefined,
+  onEvent: () => void,
+): void {
+  if (!topic) return;
+  const topics = Array.isArray(topic) ? topic : [topic];
+  for (const entry of topics) {
+    useRealtimeTopic(entry, (event) => {
+      if (!("type" in event)) return;
+      onEvent();
+    });
+  }
+}
+
+export function useChartFetch<T>(
+  options: UseChartFetchOptions<T>,
+): UseChartFetchReturn<T> {
+  const data = ref<T | null>(
+    readStaticData(options.staticData),
+  ) as Ref<T | null>;
+  // A card that fetches has nothing to show until its first response lands.
+  // SSR cannot help: registerPeriodScope() is a client-only no-op, so a
+  // 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 error = ref<unknown>(null);
+  const scopeState = usePeriodScope(options.periodScope);
+  const { $authFetch } = useAuthFetch();
+  const runner: FetchRunner = {
+    hasFetchedOnce: false,
+    lastInputs: null,
+    pendingTimer: null,
+    activeAbort: null,
+  };
+
+  const performFetch = () =>
+    runFetch(
+      $authFetch as AuthFetcher,
+      options,
+      scopeState.value,
+      runner,
+      data,
+      isLoading,
+      error,
+    );
+
+  const refresh = async () => {
+    if (runner.pendingTimer) clearTimeout(runner.pendingTimer);
+    await performFetch();
+  };
+
+  const currentInputs = () =>
+    `${scopeState.value?.key ?? ""}|${JSON.stringify(options.watchSource?.() ?? null)}`;
+
+  const fetchScheduledInputs = () => {
+    runner.lastInputs = currentInputs();
+    void performFetch();
+  };
+
+  // A period scope registers during the PeriodSelector's setup, which lands
+  // before or after a card's own mount depending on which chunk resolves
+  // first. Either way both the watcher and onMounted end up looking at the
+  // same freshly registered scope and each ask for a refresh; keying on the
+  // inputs the last fetch was started for collapses that into one request.
+  const scheduleRefresh = () => {
+    if (runner.pendingTimer) clearTimeout(runner.pendingTimer);
+    if (options.periodScope && !scopeState.value) return;
+    const inputs = currentInputs();
+    if (inputs === runner.lastInputs) return;
+    if (!runner.hasFetchedOnce) {
+      runner.hasFetchedOnce = true;
+      fetchScheduledInputs();
+      return;
+    }
+    runner.pendingTimer = setTimeout(fetchScheduledInputs, DEBOUNCE_FRAME_MS);
+  };
+
+  // A realtime event means the data behind unchanged inputs moved, so it has
+  // to bypass the deduplication above.
+  const refreshFromRealtime = () => {
+    runner.lastInputs = null;
+    scheduleRefresh();
+  };
+
+  const fetchOnMount = () => {
+    scheduleRefresh();
+    if (runner.hasFetchedOnce) return;
+    // The scope has not registered yet, and may never. Give it the grace
+    // period usePeriodScope itself allows before it warns, then drop the
+    // loading state so a misconfigured scope shows its empty value rather
+    // than a skeleton that never resolves.
+    setTimeout(() => {
+      if (!runner.hasFetchedOnce) isLoading.value = false;
+    }, PENDING_SCOPE_GRACE_MS);
+  };
+
+  if (options.fetchUrl) {
+    watch(
+      () => [scopeState.value?.key, options.watchSource?.()],
+      scheduleRefresh,
+    );
+    onMounted(fetchOnMount);
+    subscribeRealtimeTopics(options.realtimeTopic, refreshFromRealtime);
+  } else if (typeof options.staticData === "function") {
+    watch(
+      () => readStaticData(options.staticData),
+      (next) => {
+        data.value = next;
+      },
+    );
+  }
+
+  return { data, isLoading, error, refresh };
+}

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

@@ -0,0 +1,119 @@
+const DEFAULT_COLOR_NAME = "primary";
+const SAFE_HEX_FALLBACK = "#7c3aed";
+const MUTED_FALLBACK = "#6b7280";
+const CHART_GRID_COLOR = "rgba(148, 163, 184, 0.25)";
+const HEX_PREFIXES = ["#", "rgb", "hsl"];
+const SHADE_TOKEN =
+  /^(primary|secondary|success|info|warning|error|neutral|accent)-(50|[1-9]00|950)$/;
+const CSS_VARIABLE = /^--[\w-]+$/;
+const CSS_VARIABLE_FUNCTION = /^var\((--[\w-]+)\)$/;
+const COLOR_CHANNEL_MAX = 255;
+const DEFAULT_PALETTE = [
+  "primary",
+  "success",
+  "info",
+  "warning",
+  "error",
+  "secondary",
+];
+
+const COLOR_NAME_TO_VAR: Record<string, string> = {
+  primary: "--ui-primary",
+  secondary: "--ui-secondary",
+  success: "--ui-success",
+  info: "--ui-info",
+  warning: "--ui-warning",
+  error: "--ui-error",
+  neutral: "--ui-text-toned",
+  accent: "--ui-primary",
+};
+
+function isHexLike(value: string): boolean {
+  return HEX_PREFIXES.some((prefix) => value.startsWith(prefix));
+}
+
+const colorProbeCache = new Map<string, string>();
+
+/** Invalidate resolved colors before consumers recompute for a theme change. */
+export function clearChartColorCache(): void {
+  colorProbeCache.clear();
+}
+
+function toApexColor(color: string, fallback: string): string {
+  if (!color || color === "transparent" || color === "rgba(0, 0, 0, 0)")
+    return fallback;
+  if (color.startsWith("rgb")) return color;
+  // Computed styles preserve OKLCH in modern browsers; Apex expects sRGB.
+  const canvas = document.createElement("canvas");
+  canvas.width = canvas.height = 1;
+  const context = canvas.getContext("2d");
+  if (!context) return fallback;
+  context.fillStyle = color;
+  context.fillRect(0, 0, 1, 1);
+  const [red, green, blue, alpha] = context.getImageData(0, 0, 1, 1).data;
+  if (!alpha) return fallback;
+  return `rgba(${red}, ${green}, ${blue}, ${alpha / COLOR_CHANNEL_MAX})`;
+}
+
+function probeCssColor(varName: string, fallback: string): string {
+  if (typeof document === "undefined" || !document.body) return fallback;
+  const cacheKey = `${varName}:${fallback}`;
+  const cached = colorProbeCache.get(cacheKey);
+  if (cached) return cached;
+  const probe = document.createElement("div");
+  // Background does not inherit body text when a token is missing or invalid.
+  probe.style.backgroundColor = `var(${varName}, ${fallback})`;
+  probe.style.position = "absolute";
+  probe.style.visibility = "hidden";
+  probe.style.pointerEvents = "none";
+  document.body.appendChild(probe);
+  const computed = getComputedStyle(probe).backgroundColor.trim();
+  document.body.removeChild(probe);
+  const final = toApexColor(computed, fallback);
+  colorProbeCache.set(cacheKey, final);
+  return final;
+}
+
+function readCssVariable(name: string, fallback: string): string {
+  return probeCssColor(name, fallback);
+}
+
+function colorVariable(value: string): string | undefined {
+  if (CSS_VARIABLE.test(value)) return value;
+  const variable = CSS_VARIABLE_FUNCTION.exec(value);
+  if (variable) return variable[1];
+  const token = SHADE_TOKEN.exec(value);
+  if (!token) return COLOR_NAME_TO_VAR[value];
+  const scale = token[1] === "accent" ? "primary" : token[1];
+  return `--ui-color-${scale}-${token[2]}`;
+}
+
+/** Resolve semantic colors, shade tokens and global CSS variables for Apex. */
+export function resolveChartColor(value: string | undefined): string {
+  const colorName = value ?? DEFAULT_COLOR_NAME;
+  if (isHexLike(colorName)) return colorName;
+  const variable = colorVariable(colorName);
+  if (!variable) return colorName;
+  return readCssVariable(variable, SAFE_HEX_FALLBACK);
+}
+
+/** Resolve a supplied color list or the unchanged default semantic palette. */
+export function resolveChartColors(value: unknown): string[] {
+  if (Array.isArray(value)) {
+    return value.map((entry) => resolveChartColor(String(entry)));
+  }
+  if (typeof value === "string") return [resolveChartColor(value)];
+  return DEFAULT_PALETTE.map((name) => resolveChartColor(name));
+}
+
+export function readThemeMuted(): string {
+  return readCssVariable("--ui-text-muted", MUTED_FALLBACK);
+}
+
+export function readThemeHighlighted(): string {
+  return readCssVariable("--ui-text-highlighted", "#ffffff");
+}
+
+export function readThemeBorder(): string {
+  return CHART_GRID_COLOR;
+}

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

@@ -0,0 +1,59 @@
+import { onBeforeUnmount, onMounted, ref, type Ref } from "vue";
+import { clearChartColorCache } from "./useChartTheme";
+
+interface ColorModeLike {
+  preference?: string;
+  value?: string;
+  $subscribe?: (cb: () => void) => () => void;
+}
+
+type ColorModeFactory = () => ColorModeLike;
+
+const THEME_OBSERVED_ATTRIBUTES = ["class", "data-theme", "style"];
+
+function getColorModeFactory(): ColorModeFactory | undefined {
+  const fn = (globalThis as unknown as { useColorMode?: ColorModeFactory })
+    .useColorMode;
+  return typeof fn === "function" ? fn : undefined;
+}
+
+function trySubscribeColorMode(bump: () => void) {
+  const factory = getColorModeFactory();
+  if (!factory) return;
+  const mode = factory();
+  mode?.$subscribe?.(bump);
+}
+
+function createThemeObserver(bump: () => void): MutationObserver {
+  const observer = new MutationObserver(bump);
+  observer.observe(document.documentElement, {
+    attributes: true,
+    attributeFilter: THEME_OBSERVED_ATTRIBUTES,
+  });
+  return observer;
+}
+
+export function useThemeRevision(): Ref<number> {
+  const revision = ref(0);
+
+  if (typeof window === "undefined") return revision;
+
+  let observer: MutationObserver | null = null;
+
+  const bump = () => {
+    clearChartColorCache();
+    revision.value += 1;
+  };
+
+  onMounted(() => {
+    observer = createThemeObserver(bump);
+    trySubscribeColorMode(bump);
+  });
+
+  onBeforeUnmount(() => {
+    observer?.disconnect();
+    observer = null;
+  });
+
+  return revision;
+}

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

@@ -0,0 +1,2 @@
+export * from "./useConfirm";
+export * from "./usePresenceEditWarning";

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

@@ -0,0 +1,24 @@
+import LazyDmsConfirmModal from "../../components/confirm/ConfirmModal.vue";
+
+export interface ConfirmOptions {
+  title: string;
+  description: string;
+  confirmLabel?: string;
+  cancelLabel?: string;
+  confirmColor?: "primary" | "error" | "warning";
+}
+
+export function useConfirm() {
+  const overlay = useOverlay();
+
+  async function confirm(options: ConfirmOptions): Promise<boolean> {
+    const modal = overlay.create(LazyDmsConfirmModal, {
+      props: options,
+    });
+
+    const result = await modal.open();
+    return result === true;
+  }
+
+  return { confirm };
+}

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

@@ -0,0 +1,19 @@
+import LazyDmsPresenceEditModal from "../../components/table-view/PresenceEditModal.vue";
+import type { PresenceEditActor } from "../../components/table-view/PresenceEditModal.vue";
+
+export function usePresenceEditWarning() {
+  const overlay = useOverlay();
+
+  async function warnBeforeEdit(
+    editors: PresenceEditActor[],
+  ): Promise<boolean> {
+    const modal = overlay.create(LazyDmsPresenceEditModal, {
+      props: { editors },
+    });
+
+    const result = await modal.open();
+    return result === true;
+  }
+
+  return { warnBeforeEdit };
+}

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

@@ -0,0 +1,3 @@
+export * from "./types";
+export * from "./useDrawer";
+export * from "./useModal";

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

@@ -0,0 +1,99 @@
+import type { Component } from "vue";
+import type { ContainerInstance, ContainerOptions } from "./types";
+
+type Overlay = ReturnType<typeof useOverlay>;
+
+/**
+ * Defer `open` until any closing Reka UI menu has left the DOM.
+ *
+ * When a container is opened from a menu (e.g. the table-view row-actions
+ * dropdown's "View details"), the menu is still animating closed. Opening a
+ * drawer/modal overlay while the menu is mid-close lets the menu's teardown
+ * (focus return + dismiss events) instantly dismiss the fresh overlay — it
+ * flashes in and back out, so nothing shows. So we poll until no `[role="menu"]`
+ * remains, then leave a short beat for its focus handling to settle before
+ * opening. Paths with no open menu (row double-click, direct calls) open on the
+ * spot. Returns a canceller so a pending open can be aborted (see `close`).
+ */
+function openWhenMenusClosed(open: () => void): () => void {
+  if (
+    typeof document === "undefined" ||
+    !document.querySelector('[role="menu"]')
+  ) {
+    open();
+    return () => {};
+  }
+
+  const STEP_MS = 32;
+  const MAX_MS = 800;
+  const SETTLE_MS = 60;
+  let waited = 0;
+  let settleTimer: ReturnType<typeof setTimeout> | null = null;
+  const poll = setInterval(() => {
+    waited += STEP_MS;
+    if (document.querySelector('[role="menu"]') && waited < MAX_MS) return;
+    clearInterval(poll);
+    settleTimer = setTimeout(open, SETTLE_MS);
+  }, STEP_MS);
+
+  return () => {
+    clearInterval(poll);
+    if (settleTimer !== null) clearTimeout(settleTimer);
+  };
+}
+
+/**
+ * Shared opening logic behind {@link useDrawer} and {@link useModal}: create the
+ * themed overlay, ensure a unique `containerId` for the leave-guard system, mark
+ * the body component raw so Vue keeps it as-is, and expose the open `result`
+ * promise together with a programmatic `close`.
+ */
+export function openDynamicContainer<Result, Options extends ContainerOptions>(
+  overlay: Overlay,
+  container: Component,
+  idPrefix: string,
+  options: Options,
+): ContainerInstance<Result> {
+  const { component, headerComponent, containerId, ...rest } = options;
+  const instance = overlay.create(container, {
+    props: {
+      ...rest,
+      containerId: containerId ?? `${idPrefix}-${crypto.randomUUID()}`,
+      component: markRaw(component),
+      ...(headerComponent && { headerComponent: markRaw(headerComponent) }),
+    },
+  });
+
+  // The actual open is deferred past any closing menu; expose the eventual
+  // open() result through a stable promise and let close() abort a still-pending
+  // open (or resolve its result if it never opened).
+  let opened = false;
+  let resolveResult!: (value: Result) => void;
+  let rejectResult!: (reason?: unknown) => void;
+  const result = new Promise<Result>((resolve, reject) => {
+    resolveResult = resolve;
+    rejectResult = reject;
+  });
+  const cancelPendingOpen = openWhenMenusClosed(() => {
+    opened = true;
+    // Forward both settle paths: a render error inside the mounted component
+    // must reject `result` rather than leave it pending (and unhandled), as the
+    // original `return instance.open()` did.
+    (instance.open() as Promise<Result>).then(resolveResult, rejectResult);
+  });
+
+  return {
+    result,
+    close: (value?: Result) => {
+      if (opened) {
+        instance.close(value);
+      } else {
+        // Closed before the deferred open fired: abort the pending open and tear
+        // down the eagerly-created overlay so it isn't orphaned in the manager.
+        cancelPendingOpen();
+        instance.close(value);
+        resolveResult(value as Result);
+      }
+    },
+  };
+}

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

@@ -0,0 +1,43 @@
+import type { Component } from "vue";
+import type { ModalSize } from "../../types/modal";
+
+/**
+ * Side from which a {@link DrawerOptions} drawer slides in.
+ * Mirrors the `direction` prop of the internal DynamicDrawer container.
+ */
+export type DrawerDirection = "top" | "bottom" | "left" | "right";
+
+/**
+ * Options shared by every themed container opened through a public composable.
+ * They map one-to-one onto the props of the internal Dynamic{Drawer,Modal}
+ * containers, except `containerId` which is generated when omitted.
+ */
+export interface ContainerOptions {
+  title: string;
+  description?: string;
+  component: Component;
+  componentOptions?: Record<string, unknown>;
+  headerComponent?: Component;
+  headerComponentOptions?: Record<string, unknown>;
+  containerId?: string;
+}
+
+/** Options accepted by {@link useDrawer}'s `open`. */
+export interface DrawerOptions extends ContainerOptions {
+  direction?: DrawerDirection;
+}
+
+/** Options accepted by {@link useModal}'s `open`. */
+export interface ModalOptions extends ContainerOptions {
+  size?: ModalSize;
+}
+
+/**
+ * Handle returned when a container is opened. `result` settles with the value
+ * the body component emits on `success` (or the value passed to `close`) once
+ * the container is dismissed; `close` dismisses it programmatically.
+ */
+export interface ContainerInstance<Result = unknown> {
+  result: Promise<Result>;
+  close: (result?: Result) => void;
+}

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

@@ -0,0 +1,27 @@
+import DynamicDrawer from "../../build/components/containers/drawer/DynamicDrawer.vue";
+import { openDynamicContainer } from "./openDynamicContainer";
+import type { ContainerInstance, DrawerOptions } from "./types";
+
+const DRAWER_ID_PREFIX = "drawer";
+
+/**
+ * Public composable to open a DMS-themed drawer from any module that extends the
+ * layer. Wraps the internal DynamicDrawer container; `open` returns a handle
+ * whose `result` settles when the drawer is dismissed.
+ */
+export function useDrawer() {
+  const overlay = useOverlay();
+
+  function open<Result = unknown>(
+    options: DrawerOptions,
+  ): ContainerInstance<Result> {
+    return openDynamicContainer<Result, DrawerOptions>(
+      overlay,
+      DynamicDrawer,
+      DRAWER_ID_PREFIX,
+      options,
+    );
+  }
+
+  return { open };
+}