@antelopejs/dms 0.0.1

package/frontend-vue/layers/dms-core/app/composables/leave-guard/useLeaveGuard.ts

@@ -0,0 +1,105 @@
+import type {
+  LeaveGuardCallback,
+  LeaveGuardEntry,
+  LeaveGuardRegistry,
+  UseLeaveGuardReturn,
+} from "./types";
+
+const GUARD_ID_PREFIX = "guard";
+
+const registry = shallowRef<LeaveGuardRegistry>(new Map());
+
+function generateGuardId(): string {
+  return `${GUARD_ID_PREFIX}-${Date.now()}-${Math.random().toString(36).slice(2, 9)}`;
+}
+
+async function runGuardsSequentially(
+  guards: LeaveGuardEntry[],
+): Promise<boolean> {
+  for (const guard of guards) {
+    try {
+      const result = await guard.callback();
+      if (result === false) {
+        return false;
+      }
+    } catch {
+      return false;
+    }
+  }
+  return true;
+}
+
+function isClientSide(): boolean {
+  return !import.meta.env.SSR;
+}
+
+function updateRegistry(
+  mutate: (map: Map<string, LeaveGuardEntry[]>) => void,
+): void {
+  const newMap = new Map(registry.value);
+  mutate(newMap);
+  registry.value = newMap;
+}
+
+export const useLeaveGuard = (): UseLeaveGuardReturn => {
+  function addGuard(
+    containerId: string,
+    callback: LeaveGuardCallback,
+  ): () => void {
+    if (!isClientSide()) {
+      return () => {};
+    }
+
+    const guardId = generateGuardId();
+    const entry: LeaveGuardEntry = { id: guardId, callback };
+
+    updateRegistry((map) => {
+      const existingGuards = map.get(containerId) || [];
+      map.set(containerId, [...existingGuards, entry]);
+    });
+
+    return () => removeGuard(containerId, guardId);
+  }
+
+  function removeGuard(containerId: string, guardId: string): void {
+    if (!isClientSide()) return;
+
+    const guards = registry.value.get(containerId);
+    if (!guards) return;
+
+    const filtered = guards.filter((g) => g.id !== guardId);
+
+    updateRegistry((map) => {
+      if (filtered.length === 0) {
+        map.delete(containerId);
+      } else {
+        map.set(containerId, filtered);
+      }
+    });
+  }
+
+  async function executeGuards(containerId: string): Promise<boolean> {
+    if (!isClientSide()) return true;
+
+    const guards = registry.value.get(containerId);
+    if (!guards || guards.length === 0) {
+      return true;
+    }
+    return runGuardsSequentially(guards);
+  }
+
+  function clearGuards(containerId: string): void {
+    if (!isClientSide()) return;
+
+    updateRegistry((map) => {
+      map.delete(containerId);
+    });
+  }
+
+  return {
+    addGuard,
+    removeGuard,
+    executeGuards,
+    clearGuards,
+  };
+};

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

@@ -0,0 +1,44 @@
+import type { PeriodComparison, PeriodRange } from "./types";
+
+const NON_OVERLAP_GAP_MS = 1;
+
+function shiftPreviousPeriod(range: PeriodRange): PeriodRange {
+  const duration = range.to.getTime() - range.from.getTime();
+  const shiftMs = duration + NON_OVERLAP_GAP_MS;
+  return {
+    from: new Date(range.from.getTime() - shiftMs),
+    to: new Date(range.to.getTime() - shiftMs),
+  };
+}
+
+function shiftPreviousYear(range: PeriodRange): PeriodRange {
+  const previousFrom = new Date(range.from);
+  previousFrom.setFullYear(previousFrom.getFullYear() - 1);
+  const previousTo = new Date(range.to);
+  previousTo.setFullYear(previousTo.getFullYear() - 1);
+  return { from: previousFrom, to: previousTo };
+}
+
+const COMPARISON_RESOLVERS: Record<
+  Exclude<PeriodComparison, "none" | "custom">,
+  (range: PeriodRange) => PeriodRange
+> = {
+  "previous-period": shiftPreviousPeriod,
+  "previous-year": shiftPreviousYear,
+};
+
+/**
+ * Resolves the range a period is compared against.
+ *
+ * `previous-period` returns the equal-length span immediately before the
+ * range, offset by a single millisecond so the two never overlap.
+ */
+export function resolveComparisonRange(
+  comparison: PeriodComparison,
+  range: PeriodRange,
+  customRange: PeriodRange | null,
+): PeriodRange | null {
+  if (comparison === "none") return null;
+  if (comparison === "custom") return customRange;
+  return COMPARISON_RESOLVERS[comparison](range);
+}

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

@@ -0,0 +1,142 @@
+import {
+  END_OF_DAY_HOURS,
+  END_OF_DAY_MINUTES,
+  END_OF_DAY_MS,
+  END_OF_DAY_SECONDS,
+  MS_PER_DAY,
+  MS_PER_HOUR,
+  type PeriodPreset,
+  type PeriodRange,
+} from "./types";
+
+function startOfDay(date: Date): Date {
+  const next = new Date(date);
+  next.setHours(0, 0, 0, 0);
+  return next;
+}
+
+function endOfDay(date: Date): Date {
+  const next = new Date(date);
+  next.setHours(
+    END_OF_DAY_HOURS,
+    END_OF_DAY_MINUTES,
+    END_OF_DAY_SECONDS,
+    END_OF_DAY_MS,
+  );
+  return next;
+}
+
+function addDays(date: Date, amount: number): Date {
+  return new Date(date.getTime() + amount * MS_PER_DAY);
+}
+
+function addHours(date: Date, amount: number): Date {
+  return new Date(date.getTime() + amount * MS_PER_HOUR);
+}
+
+function startOfMonth(date: Date, monthOffset = 0): Date {
+  return new Date(date.getFullYear(), date.getMonth() + monthOffset, 1);
+}
+
+function endOfMonth(date: Date, monthOffset = 0): Date {
+  const next = new Date(
+    date.getFullYear(),
+    date.getMonth() + monthOffset + 1,
+    0,
+  );
+  return endOfDay(next);
+}
+
+function startOfQuarter(date: Date, quarterOffset = 0): Date {
+  const quarter = Math.floor(date.getMonth() / 3) + quarterOffset;
+  return new Date(date.getFullYear(), quarter * 3, 1);
+}
+
+function endOfQuarter(date: Date, quarterOffset = 0): Date {
+  const quarter = Math.floor(date.getMonth() / 3) + quarterOffset;
+  return endOfDay(new Date(date.getFullYear(), quarter * 3 + 3, 0));
+}
+
+function startOfYear(date: Date, yearOffset = 0): Date {
+  return new Date(date.getFullYear() + yearOffset, 0, 1);
+}
+
+function endOfYear(date: Date, yearOffset = 0): Date {
+  return endOfDay(new Date(date.getFullYear() + yearOffset, 11, 31));
+}
+
+const PRESET_RANGE_RESOLVERS: Record<
+  Exclude<PeriodPreset, "custom">,
+  (now: Date) => PeriodRange
+> = {
+  "last-hour": (now) => ({ from: addHours(now, -1), to: now }),
+  "last-24h": (now) => ({ from: addDays(now, -1), to: now }),
+  today: (now) => ({ from: startOfDay(now), to: endOfDay(now) }),
+  yesterday: (now) => {
+    const yesterday = addDays(now, -1);
+    return { from: startOfDay(yesterday), to: endOfDay(yesterday) };
+  },
+  "last-7-days": (now) => ({
+    from: startOfDay(addDays(now, -6)),
+    to: endOfDay(now),
+  }),
+  "last-30-days": (now) => ({
+    from: startOfDay(addDays(now, -29)),
+    to: endOfDay(now),
+  }),
+  "last-90-days": (now) => ({
+    from: startOfDay(addDays(now, -89)),
+    to: endOfDay(now),
+  }),
+  "this-month": (now) => ({
+    from: startOfMonth(now),
+    to: endOfMonth(now),
+  }),
+  "last-month": (now) => ({
+    from: startOfMonth(now, -1),
+    to: endOfMonth(now, -1),
+  }),
+  "this-quarter": (now) => ({
+    from: startOfQuarter(now),
+    to: endOfQuarter(now),
+  }),
+  "last-quarter": (now) => ({
+    from: startOfQuarter(now, -1),
+    to: endOfQuarter(now, -1),
+  }),
+  ytd: (now) => ({
+    from: startOfYear(now),
+    to: endOfDay(now),
+  }),
+  "last-year": (now) => ({
+    from: startOfYear(now, -1),
+    to: endOfYear(now, -1),
+  }),
+};
+
+const RELATIVE_PRESETS = new Set<PeriodPreset>(["last-hour", "last-24h"]);
+
+/**
+ * Relative presets resolve against the instant they are read: a live
+ * dashboard must re-resolve them as time passes, where calendar presets
+ * stay valid until the preset itself changes.
+ */
+export function isRelativePreset(preset: PeriodPreset): boolean {
+  return RELATIVE_PRESETS.has(preset);
+}
+
+/**
+ * Resolves a preset into a concrete range.
+ *
+ * Calendar presets snap to day boundaries (start-of-day to end-of-day), while
+ * the relative ones (`last-hour`, `last-24h`) keep instant bounds so an ops
+ * dashboard can read sub-day granularity.
+ */
+export function resolvePresetRange(
+  preset: PeriodPreset,
+  now: Date,
+  fallbackRange: PeriodRange,
+): PeriodRange {
+  if (preset === "custom") return fallbackRange;
+  return PRESET_RANGE_RESOLVERS[preset](now);
+}

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

@@ -0,0 +1,59 @@
+export type PeriodPreset =
+  | "last-hour"
+  | "last-24h"
+  | "today"
+  | "yesterday"
+  | "last-7-days"
+  | "last-30-days"
+  | "last-90-days"
+  | "this-month"
+  | "last-month"
+  | "this-quarter"
+  | "last-quarter"
+  | "ytd"
+  | "last-year"
+  | "custom";
+
+export type PeriodComparison =
+  | "none"
+  | "previous-period"
+  | "previous-year"
+  | "custom";
+
+export interface PeriodRange {
+  from: Date;
+  to: Date;
+}
+
+export interface PeriodState {
+  preset: PeriodPreset;
+  comparison: PeriodComparison;
+  range: PeriodRange;
+  compareRange: PeriodRange | null;
+  key: string;
+}
+
+export const MS_PER_HOUR = 3600000;
+export const MS_PER_DAY = 86400000;
+
+export const END_OF_DAY_HOURS = 23;
+export const END_OF_DAY_MINUTES = 59;
+export const END_OF_DAY_SECONDS = 59;
+export const END_OF_DAY_MS = 999;
+
+export const DEFAULT_PRESETS: PeriodPreset[] = [
+  "this-month",
+  "last-month",
+  "this-quarter",
+  "last-quarter",
+  "ytd",
+  "last-year",
+  "last-7-days",
+  "last-30-days",
+];
+
+export const DEFAULT_COMPARISONS: PeriodComparison[] = [
+  "none",
+  "previous-period",
+  "previous-year",
+];

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

@@ -0,0 +1,173 @@
+import {
+  computed,
+  getCurrentScope,
+  onScopeDispose,
+  ref,
+  watch,
+  type ComputedRef,
+  type Ref,
+} from "vue";
+import {
+  DEFAULT_COMPARISONS,
+  DEFAULT_PRESETS,
+  MS_PER_DAY,
+  type PeriodComparison,
+  type PeriodPreset,
+  type PeriodRange,
+  type PeriodState,
+} from "./types";
+import { isRelativePreset, resolvePresetRange } from "./presetResolvers";
+import { resolveComparisonRange } from "./compareResolvers";
+
+export interface UsePeriodOptions {
+  defaultPreset?: PeriodPreset;
+  defaultComparison?: PeriodComparison;
+  presets?: PeriodPreset[];
+  comparisons?: PeriodComparison[];
+}
+
+export interface UsePeriodReturn {
+  preset: Ref<PeriodPreset>;
+  comparison: Ref<PeriodComparison>;
+  customRange: Ref<PeriodRange | null>;
+  customCompareRange: Ref<PeriodRange | null>;
+  presets: ComputedRef<PeriodPreset[]>;
+  comparisons: ComputedRef<PeriodComparison[]>;
+  state: ComputedRef<PeriodState>;
+  setPreset: (preset: PeriodPreset) => void;
+  setComparison: (comparison: PeriodComparison) => void;
+  setCustomRange: (range: PeriodRange | null) => void;
+  setCustomCompareRange: (range: PeriodRange | null) => void;
+}
+
+const FALLBACK_RANGE_DAYS = 30;
+const FALLBACK_RANGE_MS = FALLBACK_RANGE_DAYS * MS_PER_DAY;
+const DEFAULT_PRESET: PeriodPreset = "this-month";
+const DEFAULT_COMPARISON: PeriodComparison = "none";
+const RELATIVE_REFRESH_INTERVAL_MS = 60000;
+
+function useRelativePresetClock(preset: Ref<PeriodPreset>): Ref<number> {
+  const tick = ref(0);
+  if (typeof window === "undefined") return tick;
+  let timer: ReturnType<typeof setInterval> | null = null;
+  const stop = () => {
+    if (timer !== null) clearInterval(timer);
+    timer = null;
+  };
+  watch(
+    () => isRelativePreset(preset.value),
+    (isRelative) => {
+      stop();
+      if (!isRelative) return;
+      timer = setInterval(() => {
+        tick.value += 1;
+      }, RELATIVE_REFRESH_INTERVAL_MS);
+    },
+    { immediate: true },
+  );
+  if (getCurrentScope()) onScopeDispose(stop);
+  return tick;
+}
+
+function defaultFallbackRange(now: Date): PeriodRange {
+  return {
+    from: new Date(now.getTime() - FALLBACK_RANGE_MS),
+    to: now,
+  };
+}
+
+function buildKey(state: Omit<PeriodState, "key">): string {
+  return [
+    state.preset,
+    state.comparison,
+    state.range.from.toISOString(),
+    state.range.to.toISOString(),
+    state.compareRange ? state.compareRange.from.toISOString() : "-",
+    state.compareRange ? state.compareRange.to.toISOString() : "-",
+  ].join("|");
+}
+
+interface PeriodRefs {
+  preset: Ref<PeriodPreset>;
+  comparison: Ref<PeriodComparison>;
+  customRange: Ref<PeriodRange | null>;
+  customCompareRange: Ref<PeriodRange | null>;
+}
+
+function buildState(refs: PeriodRefs): PeriodState {
+  const now = new Date();
+  const fallback = refs.customRange.value ?? defaultFallbackRange(now);
+  const range = resolvePresetRange(refs.preset.value, now, fallback);
+  const compareRange = resolveComparisonRange(
+    refs.comparison.value,
+    range,
+    refs.customCompareRange.value,
+  );
+  const partial = {
+    preset: refs.preset.value,
+    comparison: refs.comparison.value,
+    range,
+    compareRange,
+  };
+  return { ...partial, key: buildKey(partial) };
+}
+
+function makeSetters(refs: PeriodRefs) {
+  return {
+    setPreset: (next: PeriodPreset) => {
+      refs.preset.value = next;
+    },
+    setComparison: (next: PeriodComparison) => {
+      refs.comparison.value = next;
+    },
+    setCustomRange: (range: PeriodRange | null) => {
+      refs.customRange.value = range;
+      if (range) refs.preset.value = "custom";
+    },
+    setCustomCompareRange: (range: PeriodRange | null) => {
+      refs.customCompareRange.value = range;
+      if (range) refs.comparison.value = "custom";
+    },
+  };
+}
+
+/**
+ * Reactive period state machine behind `PeriodSelector` — presets,
+ * comparisons and custom ranges resolved into a publishable `state`.
+ *
+ * Call it inside a component `setup` or an `effectScope`: the interval that
+ * keeps relative presets (`last-hour`, `last-24h`) sliding is disposed with
+ * that scope, and leaks if none exists. Under `KeepAlive`, a deactivated
+ * component keeps its scope, so a relative preset keeps ticking (one
+ * re-resolution per minute) until unmount.
+ */
+export function usePeriod(options: UsePeriodOptions = {}): UsePeriodReturn {
+  const refs: PeriodRefs = {
+    preset: ref<PeriodPreset>(options.defaultPreset ?? DEFAULT_PRESET),
+    comparison: ref<PeriodComparison>(
+      options.defaultComparison ?? DEFAULT_COMPARISON,
+    ),
+    customRange: ref<PeriodRange | null>(null),
+    customCompareRange: ref<PeriodRange | null>(null),
+  };
+  const presets = computed<PeriodPreset[]>(
+    () => options.presets ?? DEFAULT_PRESETS,
+  );
+  const comparisons = computed<PeriodComparison[]>(
+    () => options.comparisons ?? DEFAULT_COMPARISONS,
+  );
+  const relativeClock = useRelativePresetClock(refs.preset);
+  const state = computed<PeriodState>(() => {
+    void relativeClock.value;
+    return buildState(refs);
+  });
+  const setters = makeSetters(refs);
+
+  return {
+    ...refs,
+    presets,
+    comparisons,
+    state,
+    ...setters,
+  };
+}

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

@@ -0,0 +1,86 @@
+import { computed, ref, type ComputedRef } from "vue";
+import type { PeriodState } from "./types";
+
+interface PeriodScopeRegistration {
+  state: ComputedRef<PeriodState>;
+  refCount: number;
+}
+
+const periodScopeRegistry = new Map<string, PeriodScopeRegistration>();
+const registryVersion = ref(0);
+
+function bumpRegistry(): void {
+  registryVersion.value += 1;
+}
+
+const noopUnregister = (): void => undefined;
+
+export function registerPeriodScope(
+  id: string,
+  state: ComputedRef<PeriodState>,
+): () => void {
+  if (typeof window === "undefined") return noopUnregister;
+  const existing = periodScopeRegistry.get(id);
+  if (existing) {
+    existing.state = state;
+    existing.refCount += 1;
+  } else {
+    periodScopeRegistry.set(id, { state, refCount: 1 });
+  }
+  bumpRegistry();
+  return () => {
+    const entry = periodScopeRegistry.get(id);
+    if (!entry) return;
+    entry.refCount -= 1;
+    if (entry.refCount <= 0) periodScopeRegistry.delete(id);
+    bumpRegistry();
+  };
+}
+
+const warnedMissingScopes = new Set<string>();
+const MISSING_SCOPE_WARN_DELAY_MS = 250;
+
+function deferMissingScopeWarn(id: string): void {
+  if (warnedMissingScopes.has(id)) return;
+  warnedMissingScopes.add(id);
+  if (typeof window === "undefined") return;
+  setTimeout(() => {
+    if (periodScopeRegistry.has(id)) return;
+    console.warn(
+      `[dms] periodScope "${id}" is not registered. The consumer will run without period filtering. Add a PeriodSelector with id="${id}" to bind it.`,
+    );
+  }, MISSING_SCOPE_WARN_DELAY_MS);
+}
+
+export function usePeriodScope(
+  id: string | undefined,
+): ComputedRef<PeriodState | null> {
+  return computed(() => {
+    if (!id) return null;
+    void registryVersion.value;
+    const entry = periodScopeRegistry.get(id);
+    if (!entry) {
+      deferMissingScopeWarn(id);
+      return null;
+    }
+    return entry.state.value;
+  });
+}
+
+export function appendPeriodToUrl(
+  url: string | undefined,
+  state: PeriodState | null,
+): string | undefined {
+  if (!url || !state) return url;
+  const params = new URLSearchParams();
+  params.set("from", state.range.from.toISOString());
+  params.set("to", state.range.to.toISOString());
+  if (state.compareRange) {
+    params.set("compareFrom", state.compareRange.from.toISOString());
+    params.set("compareTo", state.compareRange.to.toISOString());
+  }
+  params.set("preset", state.preset);
+  params.set("comparison", state.comparison);
+  const separator = url.includes("?") ? "&" : "?";
+  return `${url}${separator}${params.toString()}`;
+}

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

@@ -0,0 +1,46 @@
+import {
+  useUserRealtime,
+  type RealtimeTopicHandler,
+  type UserRealtimeApi,
+} from "./useUserRealtime";
+
+const PAGE_REALTIME_KEY = "dms.realtime.page";
+
+export interface PageRealtimeApi {
+  subscribe(topic: string, handler: RealtimeTopicHandler): () => void;
+  sessionId: Ref<string | undefined>;
+  pageId: Ref<string | undefined>;
+}
+
+export function usePageRealtime(
+  pageId: MaybeRefOrGetter<string>,
+): PageRealtimeApi {
+  const user: UserRealtimeApi = useUserRealtime();
+  const resolvedPageId = computed(() => toValue(pageId) || undefined);
+  let lastSet: string | undefined;
+
+  watch(
+    resolvedPageId,
+    (next) => {
+      lastSet = next;
+      void user.setPage(next ?? null);
+    },
+    { immediate: true },
+  );
+
+  onScopeDispose(() => {
+    if (user.pageId.value === lastSet) {
+      void user.setPage(null);
+    }
+  });
+
+  return {
+    subscribe: user.subscribe,
+    sessionId: user.sessionId,
+    pageId: resolvedPageId,
+  };
+}
+
+export function providePageRealtime(api: PageRealtimeApi): void {
+  provide(PAGE_REALTIME_KEY, api);
+}

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

@@ -0,0 +1,25 @@
+import { useUserRealtime, type RealtimeTopicHandler } from "./useUserRealtime";
+
+export function useRealtimeTopic(
+  topic: MaybeRefOrGetter<string | undefined>,
+  handler: RealtimeTopicHandler,
+): void {
+  const api = useUserRealtime();
+
+  let unsubscribe: (() => void) | undefined;
+
+  watch(
+    () => toValue(topic),
+    (next) => {
+      unsubscribe?.();
+      unsubscribe = undefined;
+      if (!next) return;
+      unsubscribe = api.subscribe(next, handler);
+    },
+    { immediate: true },
+  );
+
+  onScopeDispose(() => {
+    unsubscribe?.();
+  });
+}