@antelopejs/dms 0.9.7 → 0.10.0

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

@@ -1,5 +1,5 @@
 import { readerClock } from "./periodClock";
-import type { PeriodComparison, PeriodRange } from "./types";
+import type { PeriodComparison, PeriodPreset, PeriodRange } from "./types";
 
 const NON_OVERLAP_GAP_MS = 1;
 
@@ -30,7 +30,132 @@ function isWholeDayRange(range: PeriodRange): boolean {
   );
 }
 
-function shiftPreviousPeriod(range: PeriodRange): PeriodRange {
+const MONTHS_PER_YEAR = 12;
+const MONTHS_PER_QUARTER = 3;
+
+// The calendar unit a preset counts in, in months: its previous period is
+// the previous month, quarter or year, not the same number of days before.
+const PRESET_MONTH_SPANS: Partial<Record<PeriodPreset, number>> = {
+  "this-month": 1,
+  "last-month": 1,
+  "this-quarter": MONTHS_PER_QUARTER,
+  "last-quarter": MONTHS_PER_QUARTER,
+  ytd: MONTHS_PER_YEAR,
+  "last-year": MONTHS_PER_YEAR,
+};
+
+/** What a comparison is resolved against beyond the range itself. */
+export interface ComparisonContext {
+  /** The preset the range comes from: a calendar one compares by calendar. */
+  preset?: PeriodPreset;
+  /**
+   * The instant the range was resolved at: a range running past today
+   * (`this-month` on the 18th) compares what has elapsed of it.
+   */
+  now?: Date;
+}
+
+/** `date` moved by whole months, its day kept within the month reached. */
+function shiftMonths(date: Date, months: number): Date {
+  const clock = readerClock();
+  const wall = clock.wall(date);
+  const month = wall.month + months;
+  // Day 0 of the next month is the last day of this one.
+  const lastDay = clock.wall(
+    clock.instant({ ...wall, month: month + 1, day: 0 }),
+  ).day;
+  return clock.instant({ ...wall, month, day: Math.min(wall.day, lastDay) });
+}
+
+/** Whether `date` is the midnight opening a calendar month. */
+function isMonthStart(date: Date): boolean {
+  return isLocalMidnight(date) && readerClock().wall(date).day === 1;
+}
+
+/** Months from one month start to another. */
+function monthsBetween(from: Date, to: Date): number {
+  const clock = readerClock();
+  const start = clock.wall(from);
+  const end = clock.wall(to);
+  return (end.year - start.year) * MONTHS_PER_YEAR + end.month - start.month;
+}
+
+/** The instant right after a range: the start of what follows it. */
+const afterRange = (range: PeriodRange): Date =>
+  new Date(range.to.getTime() + NON_OVERLAP_GAP_MS);
+
+/**
+ * The calendar months a range's previous period steps back by: the unit of a
+ * calendar preset, else the months of a range made of whole months (a custom
+ * September compares to August). Any other range has none.
+ */
+function calendarMonthSpan(
+  range: PeriodRange,
+  preset: PeriodPreset | undefined,
+): number | undefined {
+  if (!isMonthStart(range.from)) return undefined;
+  const presetSpan = preset ? PRESET_MONTH_SPANS[preset] : undefined;
+  if (presetSpan) return presetSpan;
+  const end = afterRange(range);
+  return isMonthStart(end) ? monthsBetween(range.from, end) : undefined;
+}
+
+/** The last millisecond of `date`'s day. */
+function endOfDay(date: Date): Date {
+  const clock = readerClock();
+  const nextDay = clock.instant({
+    ...clock.wall(date),
+    day: clock.wall(date).day + 1,
+    hours: 0,
+    minutes: 0,
+    seconds: 0,
+    milliseconds: 0,
+  });
+  return new Date(nextDay.getTime() - NON_OVERLAP_GAP_MS);
+}
+
+/**
+ * What a comparison measures of a range: all of it, or what has elapsed of
+ * it when it runs past today — the rest holds no data yet, and comparing it
+ * with a whole period reads as a fall.
+ */
+function elapsedEnd(range: PeriodRange, now: Date | undefined): Date {
+  if (!now) return range.to;
+  const today = endOfDay(now);
+  return range.to.getTime() > today.getTime() ? today : range.to;
+}
+
+/**
+ * The same span of the calendar `months` earlier: the whole month, quarter
+ * or year before when the range is complete and ends with a month, else its
+ * elapsed days (the 1st to the 18th of the month before).
+ */
+function shiftCalendarPeriod(
+  range: PeriodRange,
+  months: number,
+  end: Date,
+): PeriodRange {
+  const from = shiftMonths(range.from, -months);
+  const isComplete = end.getTime() === range.to.getTime();
+  if (isComplete && isMonthStart(afterRange(range))) {
+    // The span before ends where the range starts: August, then September.
+    return { from, to: new Date(range.from.getTime() - NON_OVERLAP_GAP_MS) };
+  }
+  return { from, to: endOfDay(shiftMonths(end, -months)) };
+}
+
+function shiftPreviousPeriod(
+  range: PeriodRange,
+  context: ComparisonContext,
+): PeriodRange {
+  const months = calendarMonthSpan(range, context.preset);
+  if (months) {
+    return shiftCalendarPeriod(range, months, elapsedEnd(range, context.now));
+  }
+  return shiftEqualLength(range);
+}
+
+function shiftEqualLength(range: PeriodRange): PeriodRange {
   // Whole-day ranges move by calendar days, so a span crossing a daylight
   // saving change still starts at midnight (a fixed-ms shift lands an hour off).
   if (isWholeDayRange(range)) {
@@ -50,7 +175,14 @@ function shiftPreviousPeriod(range: PeriodRange): PeriodRange {
   };
 }
 
-function shiftPreviousYear(range: PeriodRange): PeriodRange {
+function shiftPreviousYear(
+  range: PeriodRange,
+  context: ComparisonContext,
+): PeriodRange {
+  const end = elapsedEnd(range, context.now);
+  if (end.getTime() !== range.to.getTime()) {
+    return shiftCalendarPeriod(range, MONTHS_PER_YEAR, end);
+  }
   return {
     from: shiftCalendar(range.from, 0, -1),
     to: shiftCalendar(range.to, 0, -1),
@@ -59,7 +191,7 @@ function shiftPreviousYear(range: PeriodRange): PeriodRange {
 
 const COMPARISON_RESOLVERS: Record<
   Exclude<PeriodComparison, "none" | "custom">,
-  (range: PeriodRange) => PeriodRange
+  (range: PeriodRange, context: ComparisonContext) => PeriodRange
 > = {
   "previous-period": shiftPreviousPeriod,
   "previous-year": shiftPreviousYear,
@@ -68,18 +200,27 @@ const COMPARISON_RESOLVERS: Record<
 /**
  * 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. Ranges of
+ * `previous-period` follows the calendar for a calendar range: a month, a
+ * quarter or a year (`this-month`, `last-quarter`, `ytd`…, or a custom range
+ * of whole months) compares to the one before — September to August, Q3 to
+ * Q2. Any other range compares to the equal-length span immediately before
+ * it, offset by a single millisecond so the two never overlap; ranges of
  * whole days are measured in calendar days, so daylight saving changes don't
- * move their midnight boundaries. A range with no bounds (`all`) has nothing
- * to compare against: `null`.
+ * move their midnight boundaries.
+ *
+ * A range running past today (`this-month` on the 18th) compares what has
+ * elapsed of it — the 1st to the 18th of the month before, or of the year
+ * before with `previous-year` — not a whole period against days that hold no
+ * data yet. A range with no bounds (`all`) has nothing to compare against:
+ * `null`.
  */
 export function resolveComparisonRange(
   comparison: PeriodComparison,
   range: PeriodRange | null,
   customRange: PeriodRange | null,
+  context: ComparisonContext = {},
 ): PeriodRange | null {
   if (comparison === "none" || !range) return null;
   if (comparison === "custom") return customRange;
-  return COMPARISON_RESOLVERS[comparison](range);
+  return COMPARISON_RESOLVERS[comparison](range, context);
 }

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

@@ -25,7 +25,7 @@ import {
   resolvePresetRange,
 } from "./presetResolvers";
 import { resolveComparisonRange } from "./compareResolvers";
-import { periodRenderNow } from "./periodRenderNow";
+import { serverRenderNow } from "../../build/composables/renderNow";
 
 export interface UsePeriodOptions {
   defaultPreset?: PeriodPreset;
@@ -52,7 +52,7 @@ export interface UsePeriodReturn {
   state: ComputedRef<PeriodState>;
   /**
    * The instant `state` was resolved from: what a label relative to now
-   * reads, so it holds still with the period (see `periodRenderNow`).
+   * reads, so it holds still with the period (see `serverRenderNow`).
    */
   resolvedAt: ComputedRef<Date>;
   setPreset: (preset: PeriodPreset) => void;
@@ -150,6 +150,7 @@ function buildState(refs: PeriodRefs, now: Date): PeriodState {
     refs.comparison.value,
     range,
     refs.customCompareRange.value,
+    { preset: refs.preset.value, now },
   );
   const partial = {
     preset: refs.preset.value,
@@ -184,7 +185,7 @@ function makeSetters(refs: PeriodRefs) {
  * comparisons and custom ranges resolved into a publishable `state`.
  *
  * A server render and the browser hydrating it resolve from the same instant
- * (`periodRenderNow`), so both render the same bounds.
+ * (`serverRenderNow`), so both render the same bounds.
  *
  * Relative presets (`last-hour`, `last-24h`) re-resolve every minute, and
  * calendar presets (`today`, `last-7-days`, `this-month`...) at each local
@@ -214,7 +215,8 @@ export function usePeriod(options: UsePeriodOptions = {}): UsePeriodReturn {
   // The server render's instant, until the clock ticks or the period changes
   // once on screen: what the setup applies (the URL's period) the server
   // applied as well.
-  const renderNow = shallowRef(periodRenderNow());
+  const serverNow = serverRenderNow();
+  const renderNow = shallowRef(serverNow === null ? null : new Date(serverNow));
   if (renderNow.value) {
     onMounted(() => {
       watch(

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

@@ -88,7 +88,7 @@ function readPeriodScope(
  * first render must match the HTML. It also answers `null` for a period the
  * browser could resolve to other bounds: before the browser's cookie names
  * its time zone. A relative preset resolves from the instant the server
- * hands the browser (`periodRenderNow`), so both read the same bounds.
+ * hands the browser (`serverRenderNow`), so both read the same bounds.
  */
 export function usePeriodScope(
   id: string | undefined,
@@ -144,3 +144,29 @@ export function appendPeriodToUrl(
   const separator = url.includes("?") ? "&" : "?";
   return `${url}${separator}${params.toString()}`;
 }
+
+/**
+ * The comparison a period scope applies, `null` while no selector registers
+ * it: `none` too when the selected comparison resolves to no window (every
+ * period, `all`, has nothing to compare against), so a consumer hides its
+ * comparison exactly when the request carries no `compareFrom` /
+ * `compareTo`. A server render reads it once, as the caller sets up, like
+ * `usePeriodScopePreset`: the mode is a name, the same on both sides.
+ */
+export function usePeriodScopeComparison(
+  id: string | undefined,
+): ComputedRef<PeriodState["comparison"] | null> {
+  if (!id) return computed(() => null);
+  const registry = usePeriodScopeRegistry();
+  if (typeof window !== "undefined")
+    return computed(() => effectiveComparison(readPeriodScope(registry, id)));
+  const comparison = effectiveComparison(readPeriodScope(registry, id));
+  return computed(() => comparison);
+}
+
+function effectiveComparison(
+  state: PeriodState | null,
+): PeriodState["comparison"] | null {
+  if (!state) return null;
+  return state.compareRange ? state.comparison : "none";
+}