@escape-game-over/atlas 0.1.91 → 0.1.93

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@escape-game-over/atlas",
-    "version": "0.1.91",
+    "version": "0.1.93",
     "type": "module",
     "description": "Typed, data-driven machinery for static multi-locale, multi-deployment Astro sites.",
     "private": false,

package/src/astro/client.ts

@@ -9,6 +9,11 @@
  * import, so a component's contract can be imported from frontmatter too.
  */
 
+export {
+    type OpenStatus,
+    openStatus,
+    type VenueNow,
+} from "../hours.ts";
 export * from "./attribution.ts";
 export * from "./axon-event.ts";
 export * from "./background-video.ts";

package/src/hours.ts

@@ -1,3 +1,4 @@
+import type { TimeZone } from "./time-zones.ts";
 import type { Digit, NonEmpty } from "./types.ts";
 
 /**
@@ -192,6 +193,11 @@ export interface HoursFormat {
 export interface FormattedHours {
     /** `"Mon–Thu, Sun"`. */
     readonly days: string;
+    /**
+     * The same days as ids, in week order: what a page matches today against
+     * to light the row it falls in.
+     */
+    readonly weekdays: NonEmpty<Weekday>;
     /** `"14:00–23:30"`, or the word for closed. */
     readonly times: string;
 }
@@ -250,6 +256,7 @@ export function formatHours(
                     : `${dayName(first)}${between}${dayName(last)}`
             )
             .join(and),
+        weekdays: group.days,
         times:
             group.hours === "closed"
                 ? format.closed
@@ -347,3 +354,147 @@ const SCHEMA_DAY: Readonly<Record<Weekday, string>> = {
 export function schemaDays(group: HoursGroup): readonly string[] {
     return group.days.map((day) => SCHEMA_DAY[day]);
 }
+
+/**
+ * The day `offset` days from `day`: -1 is yesterday, 1 is tomorrow.
+ *
+ * The week wraps around, so the index is taken modulo 7. The `+ 7` keeps it
+ * from going negative: the day before Monday is `(0 - 1 + 7) % 7 = 6`, Sunday.
+ */
+function dayFrom(day: Weekday, offset: -1 | 1): Weekday {
+    const next = WEEK[(WEEK.indexOf(day) + offset + 7) % 7];
+    if (next === undefined) {
+        throw new Error(`No day ${offset} from ${day}.`);
+    }
+    return next;
+}
+
+/**
+ * The venue's wall clock at `now`: the day, and the time.
+ *
+ * `now` is a moment, the same everywhere; `timeZone` is the venue's, so a
+ * visitor in Athens looking at a London venue gets London's time. The
+ * visitor's own zone never enters into it.
+ *
+ * The formatter's output is read, not shown, so its locale only has to name
+ * weekdays the way `Weekday` spells them: `"en"`.
+ */
+function clockAt(
+    now: Date,
+    timeZone: TimeZone
+): { readonly day: Weekday; readonly time: string } {
+    // Ask for the weekday, hour and minute as they read in the venue's zone,
+    // as separate pieces: [{ type: "weekday", value: "Saturday" }, …].
+    // `h23` makes midnight "00", not "24" (which some locales give).
+    const parts = new Intl.DateTimeFormat("en", {
+        timeZone,
+        weekday: "long",
+        hour: "2-digit",
+        minute: "2-digit",
+        hourCycle: "h23",
+    }).formatToParts(now);
+
+    // The value of one piece, e.g. part("hour") → "00".
+    const part = (type: Intl.DateTimeFormatPartTypes): string => {
+        return parts.find((each) => each.type === type)?.value ?? "";
+    };
+
+    // "Saturday" → "saturday". Matched against `WEEK` rather than cast, so
+    // the result is a `Weekday` the compiler knows about.
+    const day = WEEK.find((each) => each === part("weekday").toLowerCase());
+    if (day === undefined) {
+        throw new Error(`No weekday in ${now.toISOString()} at ${timeZone}.`);
+    }
+
+    // "00:30": the same shape as `TimeOfDay`, so it compares against the
+    // hours directly.
+    return { day, time: `${part("hour")}:${part("minute")}` };
+}
+
+/**
+ * Where a venue stands, as a page words it: open until when, or when it
+ * opens next. Only "closed today" has no time to go with it.
+ */
+export type OpenStatus =
+    | { readonly state: "open"; readonly time: TimeOfDay }
+    | { readonly state: "opensToday"; readonly time: TimeOfDay }
+    | { readonly state: "opensTomorrow"; readonly time: TimeOfDay }
+    | { readonly state: "closedToday" };
+
+/** A day's spans; none on a day off. */
+function spansOn(hours: WeeklyHours, day: Weekday): readonly TimeRange[] {
+    const dayHours = hours[day];
+    return dayHours === "closed" ? [] : dayHours;
+}
+
+/** `14:00`–`00:45`: closes the next day. */
+function pastMidnight(range: TimeRange): boolean {
+    return range.closes < range.opens;
+}
+
+/** Today on the venue's clock, and where the venue stands. */
+export interface VenueNow {
+    /** For lighting today's row in a printed week. */
+    readonly today: Weekday;
+    readonly status: OpenStatus;
+}
+
+/**
+ * Open or shut at `now`, on the venue's clock. Computed in the browser, not
+ * at build: the answer changes by the minute.
+ *
+ * Times are compared as text, which for `"HH:MM"` is the same as comparing
+ * them as times. A span past midnight keeps Friday's opening going into
+ * Saturday's small hours: at 00:30 on Saturday, `14:00`–`00:45` on Friday is
+ * still open.
+ */
+export function openStatus(
+    hours: WeeklyHours,
+    timeZone: TimeZone,
+    now: Date
+): VenueNow {
+    const { day, time } = clockAt(now, timeZone);
+    return { today: day, status: statusAt(hours, day, time) };
+}
+
+/**
+ * The status at one wall-clock moment. Checked in this order, and the first
+ * that matches wins.
+ */
+function statusAt(hours: WeeklyHours, day: Weekday, time: string): OpenStatus {
+    // 1. Still in last night's opening: yesterday has a span past midnight
+    //    (`14:00`–`00:45`) and it is not yet 00:45.
+    const lateYesterday = spansOn(hours, dayFrom(day, -1)).find(
+        (range) => pastMidnight(range) && time < range.closes
+    );
+    if (lateYesterday !== undefined) {
+        return { state: "open", time: lateYesterday.closes };
+    }
+
+    // 2. Open now: a span of today has started and not yet closed. A span
+    //    past midnight, once started, stays open for the rest of today.
+    const today = spansOn(hours, day);
+    const current = today.find(
+        (range) =>
+            range.opens <= time && (pastMidnight(range) || time < range.closes)
+    );
+    if (current !== undefined) {
+        return { state: "open", time: current.closes };
+    }
+
+    // 3. Shut now, but a span of today has not started yet: before opening,
+    //    or between the spans of a split day.
+    const later = today.find((range) => time < range.opens);
+    if (later !== undefined) {
+        return { state: "opensToday", time: later.opens };
+    }
+
+    // 4. Done for today: when tomorrow's first span opens.
+    const [tomorrow] = spansOn(hours, dayFrom(day, 1));
+    if (tomorrow !== undefined) {
+        return { state: "opensTomorrow", time: tomorrow.opens };
+    }
+
+    // 5. Done for today, and tomorrow is a day off.
+    return { state: "closedToday" };
+}

package/src/index.ts

@@ -122,8 +122,11 @@ export {
     groupHours,
     type HoursFormat,
     type HoursGroup,
+    type OpenStatus,
+    openStatus,
     type TimeOfDay,
     type TimeRange,
+    type VenueNow,
     type Weekday,
     type WeeklyHours,
 } from "./hours.ts";
@@ -285,6 +288,7 @@ export type {
     StaticPath,
 } from "./site/index.ts";
 export type { Sitemap, SitemapConfig } from "./sitemap.ts";
+export { TIME_ZONES, type TimeZone } from "./time-zones.ts";
 export type { IsoDate, Letter, NonEmpty, StringKeys } from "./types.ts";
 export {
     absoluteUrl,

package/src/time-zones.ts

@@ -0,0 +1,481 @@
+/**
+ * Every IANA time zone a venue can be in: `"Europe/London"`, `"Asia/Dubai"`.
+ *
+ * A union rather than `string` so a typo (`"Europe/Londn"`) fails to compile
+ * instead of throwing in a visitor's browser, the one place nobody looks.
+ *
+ * Two lists merged, because neither is complete on its own. tzdata's zones
+ * (2026c) carry the current names (`Asia/Kolkata`, `Europe/Kyiv`); ICU's
+ * `Intl.supportedValuesOf("timeZone")` still answers with the old ones
+ * (`Asia/Calcutta`, `Europe/Kiev`) and has a few tzdata folds into links.
+ * Every engine accepts both spellings, so both are allowed. `Factory`, tzdata's
+ * placeholder, is left out.
+ *
+ * Regenerate when tzdata adds a zone, which happens about once a year.
+ */
+export const TIME_ZONES = [
+    "Africa/Abidjan",
+    "Africa/Accra",
+    "Africa/Addis_Ababa",
+    "Africa/Algiers",
+    "Africa/Asmera",
+    "Africa/Bamako",
+    "Africa/Bangui",
+    "Africa/Banjul",
+    "Africa/Bissau",
+    "Africa/Blantyre",
+    "Africa/Brazzaville",
+    "Africa/Bujumbura",
+    "Africa/Cairo",
+    "Africa/Casablanca",
+    "Africa/Ceuta",
+    "Africa/Conakry",
+    "Africa/Dakar",
+    "Africa/Dar_es_Salaam",
+    "Africa/Djibouti",
+    "Africa/Douala",
+    "Africa/El_Aaiun",
+    "Africa/Freetown",
+    "Africa/Gaborone",
+    "Africa/Harare",
+    "Africa/Johannesburg",
+    "Africa/Juba",
+    "Africa/Kampala",
+    "Africa/Khartoum",
+    "Africa/Kigali",
+    "Africa/Kinshasa",
+    "Africa/Lagos",
+    "Africa/Libreville",
+    "Africa/Lome",
+    "Africa/Luanda",
+    "Africa/Lubumbashi",
+    "Africa/Lusaka",
+    "Africa/Malabo",
+    "Africa/Maputo",
+    "Africa/Maseru",
+    "Africa/Mbabane",
+    "Africa/Mogadishu",
+    "Africa/Monrovia",
+    "Africa/Nairobi",
+    "Africa/Ndjamena",
+    "Africa/Niamey",
+    "Africa/Nouakchott",
+    "Africa/Ouagadougou",
+    "Africa/Porto-Novo",
+    "Africa/Sao_Tome",
+    "Africa/Tripoli",
+    "Africa/Tunis",
+    "Africa/Windhoek",
+    "America/Adak",
+    "America/Anchorage",
+    "America/Anguilla",
+    "America/Antigua",
+    "America/Araguaina",
+    "America/Argentina/Buenos_Aires",
+    "America/Argentina/Catamarca",
+    "America/Argentina/Cordoba",
+    "America/Argentina/Jujuy",
+    "America/Argentina/La_Rioja",
+    "America/Argentina/Mendoza",
+    "America/Argentina/Rio_Gallegos",
+    "America/Argentina/Salta",
+    "America/Argentina/San_Juan",
+    "America/Argentina/San_Luis",
+    "America/Argentina/Tucuman",
+    "America/Argentina/Ushuaia",
+    "America/Aruba",
+    "America/Asuncion",
+    "America/Bahia",
+    "America/Bahia_Banderas",
+    "America/Barbados",
+    "America/Belem",
+    "America/Belize",
+    "America/Blanc-Sablon",
+    "America/Boa_Vista",
+    "America/Bogota",
+    "America/Boise",
+    "America/Buenos_Aires",
+    "America/Cambridge_Bay",
+    "America/Campo_Grande",
+    "America/Cancun",
+    "America/Caracas",
+    "America/Catamarca",
+    "America/Cayenne",
+    "America/Cayman",
+    "America/Chicago",
+    "America/Chihuahua",
+    "America/Ciudad_Juarez",
+    "America/Coral_Harbour",
+    "America/Cordoba",
+    "America/Costa_Rica",
+    "America/Coyhaique",
+    "America/Creston",
+    "America/Cuiaba",
+    "America/Curacao",
+    "America/Danmarkshavn",
+    "America/Dawson",
+    "America/Dawson_Creek",
+    "America/Denver",
+    "America/Detroit",
+    "America/Dominica",
+    "America/Edmonton",
+    "America/Eirunepe",
+    "America/El_Salvador",
+    "America/Fort_Nelson",
+    "America/Fortaleza",
+    "America/Glace_Bay",
+    "America/Godthab",
+    "America/Goose_Bay",
+    "America/Grand_Turk",
+    "America/Grenada",
+    "America/Guadeloupe",
+    "America/Guatemala",
+    "America/Guayaquil",
+    "America/Guyana",
+    "America/Halifax",
+    "America/Havana",
+    "America/Hermosillo",
+    "America/Indiana/Indianapolis",
+    "America/Indiana/Knox",
+    "America/Indiana/Marengo",
+    "America/Indiana/Petersburg",
+    "America/Indiana/Tell_City",
+    "America/Indiana/Vevay",
+    "America/Indiana/Vincennes",
+    "America/Indiana/Winamac",
+    "America/Indianapolis",
+    "America/Inuvik",
+    "America/Iqaluit",
+    "America/Jamaica",
+    "America/Jujuy",
+    "America/Juneau",
+    "America/Kentucky/Louisville",
+    "America/Kentucky/Monticello",
+    "America/Kralendijk",
+    "America/La_Paz",
+    "America/Lima",
+    "America/Los_Angeles",
+    "America/Louisville",
+    "America/Lower_Princes",
+    "America/Maceio",
+    "America/Managua",
+    "America/Manaus",
+    "America/Marigot",
+    "America/Martinique",
+    "America/Matamoros",
+    "America/Mazatlan",
+    "America/Mendoza",
+    "America/Menominee",
+    "America/Merida",
+    "America/Metlakatla",
+    "America/Mexico_City",
+    "America/Miquelon",
+    "America/Moncton",
+    "America/Monterrey",
+    "America/Montevideo",
+    "America/Montserrat",
+    "America/Nassau",
+    "America/New_York",
+    "America/Nome",
+    "America/Noronha",
+    "America/North_Dakota/Beulah",
+    "America/North_Dakota/Center",
+    "America/North_Dakota/New_Salem",
+    "America/Nuuk",
+    "America/Ojinaga",
+    "America/Panama",
+    "America/Paramaribo",
+    "America/Phoenix",
+    "America/Port-au-Prince",
+    "America/Port_of_Spain",
+    "America/Porto_Velho",
+    "America/Puerto_Rico",
+    "America/Punta_Arenas",
+    "America/Rankin_Inlet",
+    "America/Recife",
+    "America/Regina",
+    "America/Resolute",
+    "America/Rio_Branco",
+    "America/Santarem",
+    "America/Santiago",
+    "America/Santo_Domingo",
+    "America/Sao_Paulo",
+    "America/Scoresbysund",
+    "America/Sitka",
+    "America/St_Barthelemy",
+    "America/St_Johns",
+    "America/St_Kitts",
+    "America/St_Lucia",
+    "America/St_Thomas",
+    "America/St_Vincent",
+    "America/Swift_Current",
+    "America/Tegucigalpa",
+    "America/Thule",
+    "America/Tijuana",
+    "America/Toronto",
+    "America/Tortola",
+    "America/Vancouver",
+    "America/Whitehorse",
+    "America/Winnipeg",
+    "America/Yakutat",
+    "Antarctica/Casey",
+    "Antarctica/Davis",
+    "Antarctica/DumontDUrville",
+    "Antarctica/Macquarie",
+    "Antarctica/Mawson",
+    "Antarctica/McMurdo",
+    "Antarctica/Palmer",
+    "Antarctica/Rothera",
+    "Antarctica/Syowa",
+    "Antarctica/Troll",
+    "Antarctica/Vostok",
+    "Arctic/Longyearbyen",
+    "Asia/Aden",
+    "Asia/Almaty",
+    "Asia/Amman",
+    "Asia/Anadyr",
+    "Asia/Aqtau",
+    "Asia/Aqtobe",
+    "Asia/Ashgabat",
+    "Asia/Atyrau",
+    "Asia/Baghdad",
+    "Asia/Bahrain",
+    "Asia/Baku",
+    "Asia/Bangkok",
+    "Asia/Barnaul",
+    "Asia/Beirut",
+    "Asia/Bishkek",
+    "Asia/Brunei",
+    "Asia/Calcutta",
+    "Asia/Chita",
+    "Asia/Colombo",
+    "Asia/Damascus",
+    "Asia/Dhaka",
+    "Asia/Dili",
+    "Asia/Dubai",
+    "Asia/Dushanbe",
+    "Asia/Famagusta",
+    "Asia/Gaza",
+    "Asia/Hebron",
+    "Asia/Ho_Chi_Minh",
+    "Asia/Hong_Kong",
+    "Asia/Hovd",
+    "Asia/Irkutsk",
+    "Asia/Jakarta",
+    "Asia/Jayapura",
+    "Asia/Jerusalem",
+    "Asia/Kabul",
+    "Asia/Kamchatka",
+    "Asia/Karachi",
+    "Asia/Kathmandu",
+    "Asia/Katmandu",
+    "Asia/Khandyga",
+    "Asia/Kolkata",
+    "Asia/Krasnoyarsk",
+    "Asia/Kuala_Lumpur",
+    "Asia/Kuching",
+    "Asia/Kuwait",
+    "Asia/Macau",
+    "Asia/Magadan",
+    "Asia/Makassar",
+    "Asia/Manila",
+    "Asia/Muscat",
+    "Asia/Nicosia",
+    "Asia/Novokuznetsk",
+    "Asia/Novosibirsk",
+    "Asia/Omsk",
+    "Asia/Oral",
+    "Asia/Phnom_Penh",
+    "Asia/Pontianak",
+    "Asia/Pyongyang",
+    "Asia/Qatar",
+    "Asia/Qostanay",
+    "Asia/Qyzylorda",
+    "Asia/Rangoon",
+    "Asia/Riyadh",
+    "Asia/Saigon",
+    "Asia/Sakhalin",
+    "Asia/Samarkand",
+    "Asia/Seoul",
+    "Asia/Shanghai",
+    "Asia/Singapore",
+    "Asia/Srednekolymsk",
+    "Asia/Taipei",
+    "Asia/Tashkent",
+    "Asia/Tbilisi",
+    "Asia/Tehran",
+    "Asia/Thimphu",
+    "Asia/Tokyo",
+    "Asia/Tomsk",
+    "Asia/Ulaanbaatar",
+    "Asia/Urumqi",
+    "Asia/Ust-Nera",
+    "Asia/Vientiane",
+    "Asia/Vladivostok",
+    "Asia/Yakutsk",
+    "Asia/Yangon",
+    "Asia/Yekaterinburg",
+    "Asia/Yerevan",
+    "Atlantic/Azores",
+    "Atlantic/Bermuda",
+    "Atlantic/Canary",
+    "Atlantic/Cape_Verde",
+    "Atlantic/Faeroe",
+    "Atlantic/Faroe",
+    "Atlantic/Madeira",
+    "Atlantic/Reykjavik",
+    "Atlantic/South_Georgia",
+    "Atlantic/St_Helena",
+    "Atlantic/Stanley",
+    "Australia/Adelaide",
+    "Australia/Brisbane",
+    "Australia/Broken_Hill",
+    "Australia/Darwin",
+    "Australia/Eucla",
+    "Australia/Hobart",
+    "Australia/Lindeman",
+    "Australia/Lord_Howe",
+    "Australia/Melbourne",
+    "Australia/Perth",
+    "Australia/Sydney",
+    "Etc/GMT",
+    "Etc/GMT+1",
+    "Etc/GMT+10",
+    "Etc/GMT+11",
+    "Etc/GMT+12",
+    "Etc/GMT+2",
+    "Etc/GMT+3",
+    "Etc/GMT+4",
+    "Etc/GMT+5",
+    "Etc/GMT+6",
+    "Etc/GMT+7",
+    "Etc/GMT+8",
+    "Etc/GMT+9",
+    "Etc/GMT-1",
+    "Etc/GMT-10",
+    "Etc/GMT-11",
+    "Etc/GMT-12",
+    "Etc/GMT-13",
+    "Etc/GMT-14",
+    "Etc/GMT-2",
+    "Etc/GMT-3",
+    "Etc/GMT-4",
+    "Etc/GMT-5",
+    "Etc/GMT-6",
+    "Etc/GMT-7",
+    "Etc/GMT-8",
+    "Etc/GMT-9",
+    "Etc/UTC",
+    "Europe/Amsterdam",
+    "Europe/Andorra",
+    "Europe/Astrakhan",
+    "Europe/Athens",
+    "Europe/Belgrade",
+    "Europe/Berlin",
+    "Europe/Bratislava",
+    "Europe/Brussels",
+    "Europe/Bucharest",
+    "Europe/Budapest",
+    "Europe/Busingen",
+    "Europe/Chisinau",
+    "Europe/Copenhagen",
+    "Europe/Dublin",
+    "Europe/Gibraltar",
+    "Europe/Guernsey",
+    "Europe/Helsinki",
+    "Europe/Isle_of_Man",
+    "Europe/Istanbul",
+    "Europe/Jersey",
+    "Europe/Kaliningrad",
+    "Europe/Kiev",
+    "Europe/Kirov",
+    "Europe/Kyiv",
+    "Europe/Lisbon",
+    "Europe/Ljubljana",
+    "Europe/London",
+    "Europe/Luxembourg",
+    "Europe/Madrid",
+    "Europe/Malta",
+    "Europe/Mariehamn",
+    "Europe/Minsk",
+    "Europe/Monaco",
+    "Europe/Moscow",
+    "Europe/Oslo",
+    "Europe/Paris",
+    "Europe/Podgorica",
+    "Europe/Prague",
+    "Europe/Riga",
+    "Europe/Rome",
+    "Europe/Samara",
+    "Europe/San_Marino",
+    "Europe/Sarajevo",
+    "Europe/Saratov",
+    "Europe/Simferopol",
+    "Europe/Skopje",
+    "Europe/Sofia",
+    "Europe/Stockholm",
+    "Europe/Tallinn",
+    "Europe/Tirane",
+    "Europe/Ulyanovsk",
+    "Europe/Vaduz",
+    "Europe/Vatican",
+    "Europe/Vienna",
+    "Europe/Vilnius",
+    "Europe/Volgograd",
+    "Europe/Warsaw",
+    "Europe/Zagreb",
+    "Europe/Zurich",
+    "Indian/Antananarivo",
+    "Indian/Chagos",
+    "Indian/Christmas",
+    "Indian/Cocos",
+    "Indian/Comoro",
+    "Indian/Kerguelen",
+    "Indian/Mahe",
+    "Indian/Maldives",
+    "Indian/Mauritius",
+    "Indian/Mayotte",
+    "Indian/Reunion",
+    "Pacific/Apia",
+    "Pacific/Auckland",
+    "Pacific/Bougainville",
+    "Pacific/Chatham",
+    "Pacific/Easter",
+    "Pacific/Efate",
+    "Pacific/Enderbury",
+    "Pacific/Fakaofo",
+    "Pacific/Fiji",
+    "Pacific/Funafuti",
+    "Pacific/Galapagos",
+    "Pacific/Gambier",
+    "Pacific/Guadalcanal",
+    "Pacific/Guam",
+    "Pacific/Honolulu",
+    "Pacific/Kanton",
+    "Pacific/Kiritimati",
+    "Pacific/Kosrae",
+    "Pacific/Kwajalein",
+    "Pacific/Majuro",
+    "Pacific/Marquesas",
+    "Pacific/Midway",
+    "Pacific/Nauru",
+    "Pacific/Niue",
+    "Pacific/Norfolk",
+    "Pacific/Noumea",
+    "Pacific/Pago_Pago",
+    "Pacific/Palau",
+    "Pacific/Pitcairn",
+    "Pacific/Ponape",
+    "Pacific/Port_Moresby",
+    "Pacific/Rarotonga",
+    "Pacific/Saipan",
+    "Pacific/Tahiti",
+    "Pacific/Tarawa",
+    "Pacific/Tongatapu",
+    "Pacific/Truk",
+    "Pacific/Wake",
+    "Pacific/Wallis",
+] as const;
+
+/** One of `TIME_ZONES`. */
+export type TimeZone = (typeof TIME_ZONES)[number];