@astronox/core 0.5.12 → 0.5.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astronox/core",
-  "version": "0.5.12",
+  "version": "0.5.13",
   "description": "Reusable Astro components, patterns, styles, and infrastructure for AstroNox sites.",
   "license": "MIT",
   "keywords": [

package/src/components/feedback/ThemeBootstrap/ThemeBootstrap.astro

@@ -20,9 +20,41 @@ const { storageKey = defaultThemeStorageKey, seasonalTheme }: Props =
     const root = document.documentElement;
     const seasonalKey = `${storageKey}:seasonal`;
     const media = window.matchMedia?.('(prefers-color-scheme: dark)');
-    const choices = seasonalTheme
-      ? ['light', 'dark', seasonalTheme.appearance]
-      : ['light', 'dark'];
+    let choices = ['light', 'dark'];
+    let activeEventId = null;
+    let boundaryTimeout;
+
+    const resolveSeason = (now) => {
+      if (!seasonalTheme) return { id: null, boundary: null };
+      const period = seasonalTheme.annualPeriod;
+      if (!period) return { id: seasonalTheme.id, boundary: null };
+
+      const spansNewYear =
+        period.start.month * 100 + period.start.day >
+        period.end.month * 100 + period.end.day;
+      const year = now.getFullYear();
+      for (const startYear of [year - 1, year, year + 1]) {
+        const start = new Date(
+          startYear,
+          period.start.month - 1,
+          period.start.day,
+        );
+        const end = new Date(
+          startYear + Number(spansNewYear),
+          period.end.month - 1,
+          period.end.day,
+        );
+        if (now < start) return { id: null, boundary: start.getTime() };
+        if (now < end) {
+          return {
+            id: `${seasonalTheme.id}-${startYear}`,
+            boundary: end.getTime(),
+          };
+        }
+      }
+      return { id: null, boundary: null };
+    };
+
     const read = (key) => {
       try {
         return window.localStorage.getItem(key);
@@ -42,11 +74,11 @@ const { storageKey = defaultThemeStorageKey, seasonalTheme }: Props =
       return value === 'light' || value === 'dark' ? value : null;
     };
     const readSeasonal = () => {
-      if (!seasonalTheme) return null;
+      if (!activeEventId) return null;
       try {
         const value = JSON.parse(read(seasonalKey) ?? 'null');
         if (
-          value?.id === seasonalTheme.id &&
+          value?.id === activeEventId &&
           (value.choice === 'seasonal' || value.choice === 'classic')
         ) {
           return value.choice;
@@ -57,44 +89,81 @@ const { storageKey = defaultThemeStorageKey, seasonalTheme }: Props =
       return null;
     };
     const saveSeasonal = (choice) => {
-      if (!seasonalTheme) return;
-      write(seasonalKey, JSON.stringify({ id: seasonalTheme.id, choice }));
+      if (!activeEventId) return;
+      write(seasonalKey, JSON.stringify({ id: activeEventId, choice }));
     };
 
     let classic = readClassic();
-    let seasonal = readSeasonal();
+    let seasonal = null;
     let current;
-    if (seasonalTheme && seasonal === null) {
-      seasonal = 'seasonal';
-      saveSeasonal(seasonal);
-    }
 
     const handleVisibility = () => {
       root.toggleAttribute('data-theme-animation-paused', document.hidden);
+      if (!document.hidden) reconcile();
     };
     const next = () => choices[(choices.indexOf(current) + 1) % choices.length];
     const resolve = () =>
-      seasonalTheme && seasonal === 'seasonal'
+      activeEventId && seasonal === 'seasonal'
         ? seasonalTheme.appearance
         : (classic ?? (media?.matches ? 'dark' : 'light'));
     const apply = () => {
       const appearance = resolve();
-      if (current === appearance) return;
+      const appearanceChanged = current !== appearance;
       const theme = appearance === 'light' ? 'light' : 'dark';
-      root.dataset.themeSwitching = 'true';
+      const decorations = activeEventId
+        ? (seasonalTheme.decorations ?? 'none')
+        : 'none';
+      if (appearanceChanged) root.dataset.themeSwitching = 'true';
       root.dataset.theme = theme;
       root.dataset.appearance = appearance;
       current = appearance;
-      root.dataset.nextTheme = next();
-      void root.offsetWidth;
-      delete root.dataset.themeSwitching;
-      document.dispatchEvent(
-        new CustomEvent('astronox:theme-change', {
-          detail: { theme, appearance },
-        }),
+      const nextTheme = next();
+      const controlsChanged =
+        root.dataset.nextTheme !== nextTheme ||
+        root.dataset.themeDecorations !== decorations;
+      root.dataset.nextTheme = nextTheme;
+      root.dataset.themeDecorations = decorations;
+      root.toggleAttribute(
+        'data-theme-animation-paused',
+        document.hidden && decorations === 'animated',
       );
+      if (appearanceChanged) {
+        void root.offsetWidth;
+        delete root.dataset.themeSwitching;
+      }
+      if (appearanceChanged || controlsChanged) {
+        document.dispatchEvent(
+          new CustomEvent('astronox:theme-change', {
+            detail: { theme, appearance },
+          }),
+        );
+      }
+    };
+    const reconcile = () => {
+      const now = new Date();
+      const season = resolveSeason(now);
+      if (activeEventId !== season.id) {
+        activeEventId = season.id;
+        seasonal = readSeasonal();
+      }
+      if (activeEventId && seasonal === null) {
+        seasonal = 'seasonal';
+        saveSeasonal(seasonal);
+      }
+      choices = activeEventId
+        ? ['light', 'dark', seasonalTheme.appearance]
+        : ['light', 'dark'];
+      clearTimeout(boundaryTimeout);
+      if (season.boundary !== null) {
+        boundaryTimeout = setTimeout(
+          reconcile,
+          Math.min(season.boundary - now.getTime(), 2_147_483_647),
+        );
+      }
+      apply();
     };
     const cycle = () => {
+      reconcile();
       const appearance = next();
       if (appearance === 'light' || appearance === 'dark') {
         classic = appearance;
@@ -106,7 +175,6 @@ const { storageKey = defaultThemeStorageKey, seasonalTheme }: Props =
       saveSeasonal(seasonal);
       apply();
     };
-    const handleSystem = () => apply();
     const handleStorage = (event) => {
       if (
         event.key !== null &&
@@ -117,31 +185,28 @@ const { storageKey = defaultThemeStorageKey, seasonalTheme }: Props =
       }
       classic = readClassic();
       seasonal = readSeasonal();
-      if (seasonalTheme && seasonal === null) {
-        seasonal = 'seasonal';
-        saveSeasonal(seasonal);
-      }
-      apply();
+      reconcile();
     };
 
     root.dataset.themeStorageKey = storageKey;
-    root.dataset.themeDecorations = seasonalTheme?.decorations ?? 'none';
     window.__astronoxTheme = {
       next,
       cycle,
       destroy: () => {
-        media?.removeEventListener('change', handleSystem);
+        clearTimeout(boundaryTimeout);
+        media?.removeEventListener('change', reconcile);
         document.removeEventListener('visibilitychange', handleVisibility);
         delete root.dataset.themeAnimationPaused;
         window.removeEventListener('storage', handleStorage);
+        window.removeEventListener('focus', reconcile);
+        window.removeEventListener('pageshow', reconcile);
       },
     };
-    media?.addEventListener('change', handleSystem);
-    if (seasonalTheme?.decorations === 'animated') {
-      document.addEventListener('visibilitychange', handleVisibility);
-      handleVisibility();
-    }
+    media?.addEventListener('change', reconcile);
+    document.addEventListener('visibilitychange', handleVisibility);
     window.addEventListener('storage', handleStorage);
-    apply();
+    window.addEventListener('focus', reconcile);
+    window.addEventListener('pageshow', reconcile);
+    reconcile();
   })();
 </script>

package/src/config/siteConfig.ts

@@ -81,6 +81,30 @@ export function defineSiteConfig<const TConfig extends SiteConfig>(
     throw new Error('A seasonal theme requires a non-empty event id.');
   }
 
+  const period = config.seasonalTheme?.annualPeriod;
+  if (period) {
+    for (const { month, day } of [period.start, period.end]) {
+      const date = new Date(Date.UTC(2001, month - 1, day));
+      if (
+        !Number.isInteger(month) ||
+        !Number.isInteger(day) ||
+        date.getUTCFullYear() !== 2001 ||
+        date.getUTCMonth() !== month - 1 ||
+        date.getUTCDate() !== day
+      ) {
+        throw new Error(
+          'Annual theme periods require month/day dates valid every year.',
+        );
+      }
+    }
+    if (
+      period.start.month === period.end.month &&
+      period.start.day === period.end.day
+    ) {
+      throw new Error('An annual theme period requires distinct boundaries.');
+    }
+  }
+
   const localeIds = new Set<string>();
   const urlCodes = new Set<string>();
 

package/src/theme/contracts.ts

@@ -7,8 +7,16 @@ export type SeasonalAppearance = 'halloween';
 
 export type ThemeAppearance = ColorTheme | SeasonalAppearance;
 
+export type AnnualThemePeriod = {
+  /** Inclusive local date, with months numbered from 1 to 12. */
+  start: { month: number; day: number };
+  /** Exclusive local date, possibly in the following year. */
+  end: { month: number; day: number };
+};
+
 export type SeasonalThemeConfig = {
   id: string;
   appearance: SeasonalAppearance;
   decorations?: 'static' | 'animated';
+  annualPeriod?: AnnualThemePeriod;
 };